ウェブ検索

web_search ツールは、設定済みのプロバイダーを使って Web を検索し、 結果を返します。結果はクエリごとに 15 分間キャッシュされます（設定可能）。

OpenClaw には、X（旧 Twitter）の投稿向けの x_search と、 軽量な URL 取得向けの web_fetch も含まれます。この段階では、web_fetch は ローカルのままですが、web_search と x_search は内部で xAI Responses を使用できます。

クイックスタート

openclaw configure --section web

await web_search({ query: "OpenClaw plugin SDK" });

await x_search({ query: "dinner recipes" });

プロバイダーの選択

プロバイダー比較

自動検出

ネイティブ OpenAI web search

直接の OpenAI Responses モデルは、OpenClaw web search が有効で、管理対象プロバイダーが固定されていない場合、OpenAI のホスト型 web_search ツールを自動的に使用します。これはバンドルされた OpenAI Plugin 内のプロバイダー所有の挙動であり、ネイティブ OpenAI API トラフィックにのみ適用され、OpenAI 互換プロキシのベース URL や Azure ルートには適用されません。OpenAI モデルに管理対象の web_search ツールを維持するには、tools.web.search.provider を brave など別のプロバイダーに設定します。または、管理対象検索とネイティブ OpenAI 検索の両方を無効にするには、tools.web.search.enabled: false を設定します。

ネイティブ Codex web search

Codex app-server ランタイムは、web search が有効で管理対象プロバイダーが選択されていない場合、Codex のホスト型 web_search ツールを自動的に使用します。ネイティブのホスト型検索と OpenClaw の管理対象 web_search 動的ツールは相互排他的であるため、管理対象検索がネイティブのドメイン制限を迂回することはできません。OpenClaw は、ホスト型検索が利用できない、明示的に無効化されている、または選択された管理対象プロバイダーに置き換えられている場合に、管理対象ツールを使用します。OpenClaw は Codex のスタンドアロン web.run 拡張を無効のままにします。本番 app-server トラフィックがユーザー定義の web 名前空間を拒否するためです。

• ネイティブ検索は tools.web.search.openaiCodex で設定します
• tools.web.search.provider: "codex" を設定すると、任意の親モデル向けの管理対象 web_search プロバイダーとして Codex Hosted Search をプロビジョニングします。各呼び出しは、境界付きの一時的な Codex app-server ターンを実行し、Codex がホスト型 webSearch 項目を出力しない場合は失敗します。
• mode: "cached" がデフォルトの優先設定ですが、Codex は制限のない app-server ターンではこれをライブ外部アクセスに解決します。ライブアクセスを明示的に要求するには "live" を設定します
• OpenClaw の管理対象 web_search を代わりに使用するには、tools.web.search.provider を brave などの管理対象プロバイダーに設定します
• Codex ホスト型検索をオプトアウトするには、tools.web.search.openaiCodex.enabled: false を設定します。他の管理対象プロバイダーは引き続き利用できます
• Codex ネイティブツールサーフェスを制限しても、管理対象 web_search は利用可能なままです
• allowedDomains が設定されている場合、ホスト型検索が利用できないと自動管理対象フォールバックはフェイルクローズするため、ネイティブの許可リストを迂回できません
• ツール無効の LLM のみの実行では、ネイティブ検索と管理対象検索の両方が無効になります
• tools.web.search.enabled: false は、管理対象検索とネイティブ検索の両方を無効にします

永続的に有効な Codex 検索ポリシーの変更では、新しいバインド済みスレッドを開始するため、すでに読み込まれた app-server スレッドが古いホスト型検索アクセスを保持することはできません。一時的なターン単位の制限では、一時的な制限付きスレッドを使用し、後で再開するために既存のバインディングを保持します。

直接の OpenAI ChatGPT Responses トラフィックでも、OpenAI のホスト型 web_search ツールを使用できます。この別経路は tools.web.search.openaiCodex.enabled: true によるオプトインのままであり、 api: "openai-chatgpt-responses" を使用する対象の openai/* モデルにのみ適用されます。

{  tools: {    web: {      search: {        enabled: true,        // Optional: use Codex Hosted Search from non-Codex parent models too.        provider: "codex",        openaiCodex: {          enabled: true,          mode: "cached",          allowedDomains: ["example.com"],          contextSize: "high",          userLocation: {            country: "US",            city: "New York",            timezone: "America/New_York",          },        },      },    },  },}

ネイティブ Codex 検索をサポートしないランタイムやプロバイダーでは、Codex は OpenClaw の動的ツール名前空間を通じて、管理対象 web_search フォールバックを使用できます。Codex ホスト型検索ではなく、OpenClaw のプロバイダー固有のネットワーク制御が必要な場合は、明示的な管理対象プロバイダーを使用してください。

provider: "codex" を選択すると、バンドルされた codex Plugin が有効になり、上記と同じ tools.web.search.openaiCodex 制限が使用されます。先に openclaw models auth login --provider openai で Codex app-server を認証してください。親エージェントは任意のモデルまたはランタイムを使用できます。Codex 経由で実行されるのは、範囲が限定された検索ワーカーだけです。

ネットワーク安全性

管理対象 HTTP web_search プロバイダー呼び出しは、OpenClaw の保護された fetch パスを使用します。信頼済みプロバイダー API ホストについては、OpenClaw は Surge、Clash、sing-box の fake-IP DNS 応答を、そのプロバイダーのホスト名に対してのみ 198.18.0.0/15 と fc00::/7 で許可します。それ以外のプライベート、ループバック、リンクローカル、メタデータ宛先は引き続きブロックされます。Codex Hosted Search は例外です。その範囲限定ワーカーは、ネットワークアクセスを Codex app-server のホスト型 web_search ツールに委譲します。

この自動許可は、任意の web_fetch URL には適用されません。web_fetch では、信頼済みプロキシがそれらの合成範囲を所有している場合にのみ、tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange と tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange を明示的に有効にしてください。

Web 検索の設定

ドキュメントとセットアップフロー内のプロバイダー一覧はアルファベット順です。自動検出では別の優先順位が保持されます。

provider が設定されていない場合、OpenClaw は次の順序でプロバイダーを確認し、最初に準備できているものを使用します。

まず API ベースのプロバイダー:

1. Brave -- BRAVE_API_KEY または plugins.entries.brave.config.webSearch.apiKey (順序 10)
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY または plugins.entries.minimax.config.webSearch.apiKey (順序 15)
3. Gemini -- plugins.entries.google.config.webSearch.apiKey、GEMINI_API_KEY、または models.providers.google.apiKey (順序 20)
4. Grok -- xAI OAuth、XAI_API_KEY、または plugins.entries.xai.config.webSearch.apiKey (順序 30)
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY または plugins.entries.moonshot.config.webSearch.apiKey (順序 40)
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY または plugins.entries.perplexity.config.webSearch.apiKey (順序 50)
7. Firecrawl -- FIRECRAWL_API_KEY または plugins.entries.firecrawl.config.webSearch.apiKey (順序 60)
8. Exa -- EXA_API_KEY または plugins.entries.exa.config.webSearch.apiKey; 任意の plugins.entries.exa.config.webSearch.baseUrl は Exa エンドポイントを上書きします (順序 65)
9. Tavily -- TAVILY_API_KEY または plugins.entries.tavily.config.webSearch.apiKey (順序 70)
10. Parallel -- PARALLEL_API_KEY または plugins.entries.parallel.config.webSearch.apiKey 経由の有料 Parallel Search API; 任意の plugins.entries.parallel.config.webSearch.baseUrl はエンドポイントを上書きします (順序 75)

その後に構成済みエンドポイントプロバイダー:

11. SearXNG -- SEARXNG_BASE_URL または plugins.entries.searxng.config.webSearch.baseUrl (順序 200)

Parallel Search (Free)、DuckDuckGo、Ollama Web Search、Codex Hosted Search などのキー不要プロバイダーは、tools.web.search.provider または openclaw configure --section web で明示的に選択した場合にのみ利用できます。API ベースのプロバイダーが構成されていないという理由だけで、OpenClaw が管理対象の web_search クエリをキー不要プロバイダーへ送ることはありません。

OpenAI Responses モデルは例外です。tools.web.search.provider が未設定の場合、上記の管理対象プロバイダーではなく OpenAI のネイティブ Web 検索を使用します。管理対象パス経由でルーティングするには、tools.web.search.provider を parallel-free (または別のプロバイダー) に設定してください。

構成

{  tools: {    web: {      search: {        enabled: true, // default: true        provider: "brave", // or omit for auto-detection        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

プロバイダー固有の構成 (API キー、ベース URL、モード) は plugins.entries.<plugin>.config.webSearch.* 配下にあります。Gemini は、専用の Web 検索構成と GEMINI_API_KEY の後の低優先度フォールバックとして、models.providers.google.apiKey と models.providers.google.baseUrl も再利用できます。例についてはプロバイダーページを参照してください。 Grok は、openclaw models auth login --provider xai --method oauth の xAI OAuth 認証プロファイルも再利用できます。API キー構成は引き続きフォールバックです。

tools.web.search.provider は、バンドル済みおよびインストール済み Plugin マニフェストで宣言された Web 検索プロバイダー ID に対して検証されます。"brvae" のような typo は、自動検出へ黙ってフォールバックするのではなく、構成検証で失敗します。サードパーティ Plugin をアンインストールした後に残った plugins.entries.<plugin> ブロックなど、構成済みプロバイダーに古い Plugin の証跡しかない場合、OpenClaw は起動の堅牢性を維持し、Plugin を再インストールするか openclaw doctor --fix を実行して古い構成をクリーンアップできるよう警告を報告します。

web_fetch フォールバックプロバイダーの選択は別です。

• tools.web.fetch.provider で選択します
• またはその項目を省略し、OpenClaw に構成済み認証情報から最初に準備できている web-fetch プロバイダーを自動検出させます
• 非サンドボックスの web_fetch は、contracts.webFetchProviders を宣言するインストール済み Plugin プロバイダーを使用できます。サンドボックス化された fetch はバンドル済みプロバイダーと検証済み公式 Plugin インストールを許可しますが、サードパーティ外部 Plugin は除外します
• 公式 Firecrawl Plugin は web-fetch フォールバックを提供し、plugins.entries.firecrawl.config.webFetch.* 配下で構成されます

openclaw onboard または openclaw configure --section web で Kimi を選択すると、OpenClaw は次の内容も尋ねることができます。

• Moonshot API リージョン (https://api.moonshot.ai/v1 または https://api.moonshot.cn/v1)
• 既定の Kimi Web 検索モデル (既定は kimi-k2.6)

x_search では、plugins.entries.xai.config.xSearch.* を構成してください。これはチャットと同じ xAI 認証プロファイル、または Grok Web 検索で使用される XAI_API_KEY / Plugin Web 検索認証情報を使用します。 従来の tools.web.x_search.* 構成は、openclaw doctor --fix によって自動移行されます。 openclaw onboard または openclaw configure --section web で Grok を選択すると、OpenClaw は同じ認証情報で任意の x_search セットアップも提示できます。 これは Grok パス内の別個の後続ステップであり、トップレベルの Web 検索プロバイダー選択ではありません。別のプロバイダーを選択した場合、OpenClaw は x_search プロンプトを表示しません。

API キーの保存

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "YOUR_KEY", // pragma: allowlist secret          },        },      },    },  },}

export BRAVE_API_KEY="YOUR_KEY"

ツールパラメーター

x_search

x_search は xAI を使用して X (旧 Twitter) の投稿をクエリし、引用付きの AI 合成回答を返します。自然言語クエリと任意の構造化フィルターを受け付けます。OpenClaw は、このツール呼び出しを処理するリクエストでのみ、組み込み xAI x_search ツールを有効にします。

x_search 構成

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true,            model: "grok-4-1-fast-non-reasoning",            baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // optional if an xAI auth profile or XAI_API_KEY is set            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL          },        },      },    },  },}

plugins.entries.xai.config.xSearch.baseUrl が設定されている場合、x_search は <baseUrl>/responses に投稿します。その項目が省略されている場合、plugins.entries.xai.config.webSearch.baseUrl、次に従来の tools.web.search.grok.baseUrl、最後に公開 xAI エンドポイントへフォールバックします。

x_search パラメーター

x_search の例

await x_search({  query: "dinner recipes",  allowed_x_handles: ["nytfood"],  from_date: "2026-03-01",});

// Per-post stats: use the exact status URL or status ID when possibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

例

// Basic searchawait web_search({ query: "OpenClaw plugin SDK" }); // German-specific searchawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Recent results (past week)await web_search({ query: "AI developments", freshness: "week" }); // Date rangeawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Domain filtering (Perplexity only)await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

ツールプロファイル

ツールプロファイルまたは許可リストを使用する場合は、web_search、x_search、または group:web を追加します。

{  tools: {    allow: ["web_search", "x_search"],    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)  },}

関連情報

• Web Fetch -- URL を取得し、読みやすいコンテンツを抽出する
• Web Browser -- JS の多いサイト向けの完全なブラウザー自動化
• Grok Search -- web_search プロバイダーとしての Grok
• Ollama Web Search -- Ollama ホスト経由のキー不要のウェブ検索