網頁搜尋

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" });

選擇供應商

供應商比較

自動偵測

文件與設定流程中的供應商清單依字母順序排列。自動偵測使用 另一套固定的優先順序，而且只有在找到已設定的供應商時，才會選擇需要 憑證（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（免費）、DuckDuckGo、 Ollama Web Search 和 Codex Hosted Search 等無須金鑰的供應商， 即使具有內部順序值，也絕不會在自動偵測中勝出。 只有當你透過 tools.web.search.provider 明確選取它們，或使用 openclaw configure --section web 選取時，才會使用這些供應商。OpenClaw 不會因為 未設定以 API 為基礎的供應商，就將受管理的 web_search 查詢傳送至無須金鑰的供應商。

OpenAI Responses 模型是例外：當 tools.web.search.provider 未設定時，它們會使用 OpenAI 的原生網路搜尋，而非上述受管理的 供應商（請見下文）。將 tools.web.search.provider 設為 parallel-free（或其他供應商），即可改為透過受管理的路徑 路由。

OpenAI 原生網路搜尋

直接使用 OpenAI Responses 模型（api: "openai-responses"、供應商為 openai，且未設定基礎 URL 或使用官方 OpenAI API 基礎 URL）時，若已啟用 OpenClaw 網頁搜尋且未固定任何託管供應商，會自動使用 OpenAI 託管的 web_search 工具。這是內建 OpenAI 外掛中由供應商負責的行為，不適用於 OpenAI 相容代理伺服器的基礎 URL 或 Azure 路由。將 tools.web.search.provider 設為其他供應商（例如 brave），即可讓 OpenAI 模型繼續使用託管的 web_search 工具；或將 tools.web.search.enabled: false 設為停用，以同時停用託管搜尋與 OpenAI 原生搜尋。

原生 Codex 網頁搜尋

當已啟用網頁搜尋且未選取託管供應商時，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" 設為把 Codex Hosted Search 佈建成任意父模型的託管 web_search 供應商。每次呼叫都會執行一次有界限的暫時性 Codex app-server 回合；若 Codex 未產生託管的 webSearch 項目，呼叫便會失敗。
• mode: "cached" 是預設偏好，但對不受限制的 app-server 回合，Codex 會將其解析為即時外部存取；設為 "live" 可明確要求即時存取
• 將 tools.web.search.provider 設為 brave 等託管供應商，即可改用 OpenClaw 的託管 web_search
• 將 tools.web.search.openaiCodex.enabled: false 設為不使用 Codex 託管搜尋；其他託管供應商仍可使用
• 限制 Codex 原生工具介面時，也會讓託管 web_search 保持可用
• 設定 allowedDomains 時，若託管搜尋無法使用，自動託管後援會採取失敗關閉，以免繞過原生允許清單
• 停用工具、僅執行大型語言模型的作業會同時停用原生搜尋與託管搜尋
• 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 後援。若需要使用 OpenClaw 特定於供應商的網路控制，而非 Codex 託管搜尋，請明確指定託管供應商。

選取 provider: "codex" 會啟用內建的 codex 外掛，並使用上方所示的相同 tools.web.search.openaiCodex 限制。請先使用 openclaw models auth login --provider openai 驗證 Codex app-server。父代理程式可使用任何模型或執行階段；只有有界限的搜尋工作程式會透過 Codex 執行。

網路安全性

託管 HTTP web_search 供應商呼叫會使用 OpenClaw 受防護的擷取路徑，範圍僅限目前供應商自己的主機名稱。僅對該主機名稱，OpenClaw 允許 Surge、Clash 和 sing-box 在 198.18.0.0/15 與 fc00::/7 中的假 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 也可在其專用網頁搜尋設定和 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 會依內建及已安裝外掛資訊清單中宣告的網頁搜尋供應商 ID 進行驗證。像 "brvae" 這樣的拼字錯誤會使設定驗證失敗，而不會無聲地退回自動偵測。若已設定的供應商只有過時的外掛證據，例如解除安裝第三方外掛後遺留的 plugins.entries.<plugin> 區塊，OpenClaw 會維持啟動韌性並回報警告，讓你可以重新安裝該外掛，或執行 openclaw doctor --fix 清理過時設定。

web_fetch 後援供應商的選取方式互相獨立：

• 使用 tools.web.fetch.provider 選取
• 或省略該欄位，讓 OpenClaw 從已設定的憑證中自動偵測第一個就緒的網頁擷取供應商
• 非沙箱化的 web_fetch 可以使用宣告 contracts.webFetchProviders 的已安裝外掛供應商；沙箱化擷取允許內建供應商及經驗證的官方外掛安裝，但排除第三方外部外掛
• 官方 Firecrawl 外掛是目前唯一內建的 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 網頁搜尋模型（預設為 kimi-k2.6）

若要使用 x_search，請設定 plugins.entries.xai.config.xSearch.*。它使用與聊天相同的 xAI 驗證設定檔，或使用 Grok 網頁搜尋所用的 XAI_API_KEY／外掛網頁搜尋憑證。 舊版 tools.web.x_search.* 設定會由 openclaw doctor --fix 自動遷移。 當你在 openclaw onboard 或 openclaw configure --section web 期間選取 Grok 時，Grok 設定完成後，OpenClaw 也會立即提供使用相同憑證的選用 x_search 設定。這是 Grok 路徑內的獨立後續步驟，而非獨立的頂層網頁搜尋供應商選項。若選取其他供應商，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 時，只有在作用中模型的供應商為 xai，且能解析到 xAI 憑證時，才會公開 x_search。若作用中模型使用已知的非 xAI 供應商，請將 plugins.entries.xai.config.xSearch.enabled 設為 true，以選擇啟用跨供應商使用。若作用中模型的供應商缺失或無法解析，此工具會維持隱藏。將 enabled 設為 false，即可對所有供應商停用此工具。使用此工具一律需要 xAI 憑證。

{  plugins: {    entries: {      xai: {        config: {          xSearch: {            enabled: true, // required for a known non-xAI model provider            model: "grok-4.3",            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 發出 POST 請求。若省略該欄位，則會依序回退至 plugins.entries.xai.config.webSearch.baseUrl、舊版 tools.web.search.grok.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",});

// 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)  },}

相關內容

• 網頁擷取 -- 擷取 URL 並提取可讀內容
• 網頁瀏覽器 -- 為大量使用 JS 的網站提供完整瀏覽器自動化
• Grok 搜尋 -- 使用 Grok 作為 web_search 供應商
• Ollama 網頁搜尋 -- 透過 Ollama 主機進行免金鑰的網頁搜尋