ウェブ検索

web_search は設定済みのプロバイダーでウェブを検索し、 正規化された結果を返します。結果はクエリごとに 15 分間キャッシュされます（設定可能）。OpenClaw には、X（旧 Twitter）の投稿向けの x_search と、 軽量な URL 取得向けの web_fetch も同梱されています。web_fetch は常にローカルで実行され、Grok がプロバイダーの場合、web_search は xAI Responses 経由で処理されます。また、x_search は常に xAI Responses を使用します。

クイックスタート

openclaw configure --section web

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

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

プロバイダーの選択

プロバイダーの比較

結果の形式

web_search は、コアツールの境界ですべての同梱および外部 Plugin プロバイダーを 正規化します。呼び出し元は、次の閉じた形式のいずれか 1 つだけを受け取ります。

type WebSearchOutput =  | {      kind: "error";      provider: string;      error: "provider_error";      message: string;      docs?: string;    }  | {      kind: "results";      provider: string;      query: string;      count: number;      tookMs?: number;      results: Array<{        title: string;        url: string;        snippet?: string;        published?: string;        siteName?: string;      }>;      externalContent: {        untrusted: true;        source: "web_search";        wrapped: true;        provider: string;      };      cached?: true;    }  | {      kind: "answer";      provider: string;      query: string;      tookMs?: number;      content: string;      citations?: Array<{ url: string; title?: string }>;      externalContent: {        untrusted: true;        source: "web_search";        wrapped: true;        provider: string;      };      cached?: true;    }  | {      kind: "raw";      provider: string;      data: unknown;    };

構造化プロバイダーは kind: "results" を使用し、合成プロバイダーは kind: "answer" を使用します。ペイロードがどちらの形式にも一致しない外部 Plugin プロバイダーは、 互換性のため kind: "raw" としてそのまま渡されます。生のスコア、抜粋、関連検索、インライン引用の オフセット、モデル ID、セッションメタデータなど、プロバイダー固有の フィールドは、正規化された分岐では渡されません。より豊富な応答が ワークフローの一部である場合は、プロバイダー専用のツールを使用してください。

externalContent.wrapped: true は、境界自体が真であることを保証する信頼マーカーです。 プロバイダーの文章（title、snippet、siteName、content、引用の タイトル、エラーの message）から既存のエンベロープ行をすべて除去し、 コア境界で正確に 1 回だけ再ラップするため、プロバイダーのメタデータが このマーカーを偽装することはできません。query は常にリクエストされたクエリであり、引用および結果の URL は http(s) として解析可能でなければなりません。published は ISO 日付形式でなければならず、URL は正規化して出力されます。また、 error キーを含むペイロードは常に kind: "error" として報告され、 生のプロバイダーコードはラップされたメッセージ内に保持されます。生のパススルー ペイロードでは、プロバイダーが設定したマーカーがそのまま保持されます。

自動検出

ドキュメントおよびセットアップフロー内のプロバイダー一覧はアルファベット順です。自動検出では、 それとは別の固定された優先順位を使用し、認証情報（requiresCredential !== false）が必要なプロバイダーは、 その認証情報が設定済みの場合にのみ選択します。 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（または別のプロバイダー）に設定します。

OpenAI ネイティブ Web 検索

OpenClaw の Web 検索が有効で、管理対象プロバイダーが固定されていない場合、直接接続の OpenAI Responses モデル （api: "openai-responses"、プロバイダー openai、 ベース URL なし、または公式 OpenAI API ベース URL）は、OpenAI がホストする web_search ツールを自動的に使用します。これはバンドルされた OpenAI Plugin によるプロバイダー所有の動作であり、OpenAI 互換プロキシのベース URL や Azure 経路には適用されません。OpenAI モデルで管理対象の web_search ツールを 引き続き使用するには、tools.web.search.provider を brave などの別のプロバイダーに設定します。 管理対象検索と OpenAI ネイティブ検索の両方を無効にするには、 tools.web.search.enabled: false を設定します。

Codex ネイティブ Web 検索

Web 検索が有効で、管理対象プロバイダーが選択されていない場合、Codex app-server ランタイムは、 Codex がホストする web_search ツールを自動的に使用します。ネイティブのホスト型検索と OpenClaw の管理対象 web_search 動的ツールは相互排他的であるため、 管理対象検索でネイティブのドメイン制限を回避することはできません。ホスト型検索が利用できない場合、 明示的に無効化されている場合、または選択した管理対象プロバイダーに置き換えられている場合、 OpenClaw は管理対象ツールを使用します。OpenClaw は Codex のスタンドアロン web.run 拡張機能を無効（features.standalone_web_search: false）のままにします。 これは、本番環境の 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,        // オプション: Codex 以外の親モデルからも Codex Hosted Search を使用します。        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 の保護付きフェッチ経路が使用されます。 そのホスト名に限り、OpenClaw は 198.18.0.0/15 と fc00::/7 に含まれる Surge、Clash、sing-box の fake-IP DNS 応答を許可します。それ以外のプライベート、ループバック、 リンクローカル、メタデータの宛先は引き続きブロックされます。Codex Hosted Search は例外です。 その制限付きワーカーは、ネットワークアクセスを Codex app-server がホストする web_search ツールに委任します。

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

設定

{  tools: {    web: {      search: {        enabled: true, // デフォルト: true        provider: "brave", // または自動検出する場合は省略        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" のような 入力ミスは、自動検出へ暗黙的にフォールバックするのではなく、設定検証で失敗します。 設定されたプロバイダーに、サードパーティー Plugin のアンインストール後に残った plugins.entries.<plugin> ブロックなど、古い Plugin の情報しかない場合、 OpenClaw は起動時の堅牢性を維持しながら警告を報告します。その場合は Plugin を再インストールするか、 openclaw doctor --fix を実行して古い設定をクリーンアップできます。

web_fetch のフォールバックプロバイダー選択は別個に行われます。

• tools.web.fetch.provider で選択します
• または、そのフィールドを省略すると、OpenClaw が設定済みの認証情報から 最初に利用可能な Web フェッチプロバイダーを自動検出します
• サンドボックス化されていない web_fetch では、 contracts.webFetchProviders を宣言するインストール済み Plugin プロバイダーを使用できます。 サンドボックス化されたフェッチでは、バンドル済みプロバイダーと検証済みの公式 Plugin インストールが許可されますが、 サードパーティーの外部 Plugin は除外されます
• 現在、公式 Firecrawl Plugin は、バンドルされた webFetchProviders の 唯一のコントリビューターであり、 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 は Grok のセットアップ完了直後に、同じ認証情報を使用するオプションの 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 の設定

enabled を省略した場合、x_search はアクティブなモデルの プロバイダーが xai であり、xAI の認証情報を解決できる場合にのみ公開されます。 既知の非 xAI プロバイダーを使用するアクティブなモデルでプロバイダーをまたいで使用するには、 plugins.entries.xai.config.xSearch.enabled を true に設定してオプトインします。 アクティブなモデルのプロバイダーが指定されていないか解決できない場合、ツールは非表示のままです。 すべてのプロバイダーで無効にするには、enabled を false に設定します。 xAI の認証情報は常に必要です。

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // 既知の非 xAI モデルプロバイダーでは必須            model: "grok-4.3",            baseUrl: "https://api.x.ai/v1", // オプション。webSearch.baseUrl を上書き            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // xAI 認証プロファイルまたは XAI_API_KEY が設定されている場合は省略可能            baseUrl: "https://api.x.ai/v1", // オプションの共有 xAI Responses ベース URL          },        },      },    },  },}

plugins.entries.xai.config.xSearch.baseUrl が設定されている場合、x_search は <baseUrl>/responses に POST します。このフィールドを省略すると、 plugins.entries.xai.config.webSearch.baseUrl、続いて公開 xAI エンドポイント （https://api.x.ai/v1）へフォールバックします。

x_search のパラメーター

allowed_x_handles と excluded_x_handles は同時に指定できません。

x_search の例

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

// 投稿ごとの統計: 可能な場合は正確なステータス URL またはステータス ID を使用await x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

例

// 基本検索await web_search({ query: "OpenClaw plugin SDK" }); // ドイツ向け検索await web_search({ query: "TV online schauen", country: "DE", language: "de" }); // 最近の結果（過去 1 週間）await web_search({ query: "AI developments", freshness: "week" }); // 日付範囲await web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // ドメインフィルタリング（Perplexity のみ）await web_search({  query: "product reviews",  domain_filter: ["-reddit.com", "-pinterest.com"],});

ツールプロファイル

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

{  tools: {    allow: ["web_search", "x_search"],    // または: allow: ["group:web"]  （web_search、x_search、web_fetch を含む）  },}

関連項目

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