web_search 會使用你設定的供應商搜尋網路,並傳回
正規化的結果;結果會依查詢快取 15 分鐘(可設定)。OpenClaw
也隨附用於搜尋 X(前身為 Twitter)貼文的 x_search,以及用於
輕量擷取 URL 的 web_fetch。web_fetch 一律在本機執行;當 Grok 為供應商時,web_search 會透過
xAI Responses 路由,而 x_search 一律使用
xAI Responses。
web_search 是輕量型 HTTP 工具,而非瀏覽器自動化工具。若網站
大量使用 JS 或需要登入,請使用 Web Browser。若要
擷取特定 URL,請使用 Web Fetch。快速開始
1
選擇供應商
選擇供應商並完成所有必要設定。部分供應商
無須金鑰,其他供應商則需要 API 金鑰。詳情請參閱下方的
供應商頁面。
2
設定
BRAVE_API_KEY),並略過此步驟。3
使用
選擇供應商
Brave Search
提供含摘要片段的結構化結果。支援
llm-context 模式及國家/語言篩選條件。提供免費方案。Codex 託管搜尋
透過你的 Codex app-server 帳號提供有依據的 AI 綜合回答。
DuckDuckGo
無須金鑰的供應商。不需要 API 金鑰。採用非官方、以 HTML 為基礎的整合。
Exa
結合神經網路與關鍵字搜尋,並支援內容擷取(重點、文字、摘要)。
Firecrawl
提供結構化結果。最適合搭配
firecrawl_search 和 firecrawl_scrape 進行深度擷取。Gemini
透過 Google 搜尋依據提供含引用來源的 AI 綜合回答。
Grok
透過 xAI 網路依據提供含引用來源的 AI 綜合回答。
Kimi
透過 Moonshot 網路搜尋提供含引用來源的 AI 綜合回答;缺乏依據的聊天備援會明確失敗。
MiniMax 搜尋
透過 MiniMax Token Plan 搜尋 API 提供結構化結果。
Ollama 網路搜尋
透過已登入的本機 Ollama 主機或託管的 Ollama API 進行搜尋。
Parallel
付費的 Parallel Search API(
PARALLEL_API_KEY);提供更高的速率限制與目標調校。Parallel 搜尋(免費)
可選用且無須金鑰。Parallel 的免費 Search MCP,提供針對 LLM 最佳化的密集摘錄,且不需要 API 金鑰。
Perplexity
提供結構化結果,並支援內容擷取控制與網域篩選。
SearXNG
自行託管的中繼搜尋。不需要 API 金鑰。彙整 Google、Bing、DuckDuckGo 等搜尋引擎。
Tavily
提供結構化結果,支援搜尋深度、主題篩選,以及使用
tavily_extract 擷取 URL。供應商比較
結果格式
web_search 會在核心工具邊界正規化每個隨附及外部外掛供應商。
呼叫端只會收到以下任一種封閉格式:
kind: "results";綜合回答供應商使用
kind: "answer"。若外部外掛供應商的承載資料不符合任一格式,
為了相容性,會以 kind: "raw" 原封不動地傳遞。供應商特有的
欄位,例如原始分數、摘錄、相關搜尋、行內引用
位移、模型 ID 或工作階段中繼資料,都不會在正規化
分支中傳遞。當供應商較豐富的回應是你工作流程的一部分時,
請使用該供應商的專用工具。
externalContent.wrapped: true 是邊界本身確保為
真的信任標記:供應商文字(title、snippet、siteName、content、引用
標題、錯誤 message)會移除所有既有的封裝行,並在核心邊界
恰好重新封裝一次,因此供應商中繼資料無法偽造
此標記。query 一律是要求的查詢,引用及結果 URL
必須可解析為 http(s),published 必須符合 ISO 日期格式,URL 會以正規化形式輸出,而
含有 error 鍵的承載資料一律會回報為 kind: "error",並在
封裝訊息中保留原始供應商代碼。原始直接傳遞的
承載資料會保留供應商設定的所有標記。
自動偵測
文件和設定流程中的供應商清單會按字母排序。自動偵測使用 另一套固定的優先順序,而且只有在找到已設定的供應商時,才會選擇需要 認證資訊(requiresCredential !== false)的供應商。如果
未設定 provider,OpenClaw 會依照以下順序檢查供應商,並使用
第一個已就緒的供應商:
優先檢查由 API 支援的供應商:
- Brave —
BRAVE_API_KEY或plugins.entries.brave.config.webSearch.apiKey(順序 10) - MiniMax Search —
MINIMAX_CODE_PLAN_KEY/MINIMAX_CODING_API_KEY/MINIMAX_OAUTH_TOKEN/MINIMAX_API_KEY或plugins.entries.minimax.config.webSearch.apiKey(順序 15) - Gemini —
plugins.entries.google.config.webSearch.apiKey、GEMINI_API_KEY或models.providers.google.apiKey(順序 20) - Grok — xAI OAuth、
XAI_API_KEY或plugins.entries.xai.config.webSearch.apiKey(順序 30) - Kimi —
KIMI_API_KEY/MOONSHOT_API_KEY或plugins.entries.moonshot.config.webSearch.apiKey(順序 40) - Perplexity —
PERPLEXITY_API_KEY/OPENROUTER_API_KEY或plugins.entries.perplexity.config.webSearch.apiKey(順序 50) - Firecrawl —
FIRECRAWL_API_KEY或plugins.entries.firecrawl.config.webSearch.apiKey(順序 60) - Exa —
EXA_API_KEY或plugins.entries.exa.config.webSearch.apiKey;選用的plugins.entries.exa.config.webSearch.baseUrl會覆寫 Exa 端點(順序 65) - Tavily —
TAVILY_API_KEY或plugins.entries.tavily.config.webSearch.apiKey(順序 70) - Parallel — 透過
PARALLEL_API_KEY或plugins.entries.parallel.config.webSearch.apiKey使用付費的 Parallel Search API;選用的plugins.entries.parallel.config.webSearch.baseUrl會覆寫端點(順序 75)
- SearXNG —
SEARXNG_BASE_URL或plugins.entries.searxng.config.webSearch.baseUrl(順序 200)
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(或其他提供者),
即可改為透過受管理的路徑路由這些模型。
所有提供者金鑰欄位都支援 SecretRef 物件。對於已安裝且由 API 支援的網頁搜尋提供者,
系統會解析
plugins.entries.<plugin>.config.webSearch.apiKey 下外掛範圍的 SecretRef,
包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Parallel、Perplexity 和 Tavily;
無論是透過 tools.web.search.provider 明確選取提供者,還是透過自動偵測選取皆適用。
在自動偵測模式下,OpenClaw 僅解析所選提供者的金鑰——未選取的 SecretRef 會維持停用,
因此你可以設定多個提供者,而不必為未使用的提供者付出解析成本。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"是預設偏好設定,但 Codex 會針對不受限制的 app-server 回合,將其解析為即時外部存取;設定"live"可明確要求即時存取- 將
tools.web.search.provider設為brave等受管理提供者, 即可改用 OpenClaw 受管理的web_search - 設定
tools.web.search.openaiCodex.enabled: false可選擇停用 Codex 託管搜尋; 其他受管理提供者仍可使用 - 限制 Codex 原生工具介面時,也會讓受管理的
web_search保持可用 - 設定
allowedDomains時,若託管搜尋無法使用,自動受管理備援會採取 封閉式失敗,確保無法規避原生允許清單 - 停用工具的純 LLM 執行會同時停用原生與受管理搜尋
tools.web.search.enabled: false會同時停用受管理與原生搜尋
web_search 工具。這條獨立路徑仍須透過 tools.web.search.openaiCodex.enabled: true 選擇啟用,
且僅適用於使用 api: "openai-chatgpt-responses" 的合格 openai/* 模型。
web_search 備援。若你需要 OpenClaw 針對提供者的
網路控制,而非 Codex 託管搜尋,請使用明確的受管理提供者。
選取 provider: "codex" 會啟用隨附的 codex 外掛,並使用上述相同的
tools.web.search.openaiCodex 限制。請先使用 openclaw models auth login --provider openai 驗證 Codex app-server。
父代理程式可以使用任何模型或執行階段;只有有界限的搜尋工作程式會透過 Codex 執行。
網路安全
受管理的 HTTPweb_search 提供者呼叫會使用 OpenClaw 的受保護擷取路徑,
其範圍限制於目前提供者本身的主機名稱。OpenClaw 僅針對該主機名稱允許
198.18.0.0/15 和 fc00::/7 中來自 Surge、Clash 與 sing-box 的
假 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。
設定
plugins.entries.<plugin>.config.webSearch.* 下。
在專用網頁搜尋設定和 GEMINI_API_KEY 之後,Gemini 也可以較低優先順序的備援方式,
重複使用 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 時,
OpenClaw 也會在 Grok 設定完成後,立即提供使用相同認證資訊的選用
x_search 設定。這是 Grok 路徑內獨立的後續步驟,
不是另一個頂層網頁搜尋提供者選項。如果你選擇其他提供者,
OpenClaw 不會顯示 x_search 提示。
儲存 API 金鑰
- 設定檔
- 環境變數
執行
openclaw configure --section web 或直接設定金鑰:工具參數
x_search
x_search 使用 xAI 查詢 X(前身為 Twitter)貼文,並傳回
附有引用的 AI 綜合答案。它接受自然語言查詢和
選用的結構化篩選器。OpenClaw 會針對每個要求建構內建的 xAI x_search
工具,而非永久註冊,因此它只會在實際呼叫它的該回合中
啟用。
xAI 文件指出
x_search 支援關鍵字搜尋、語意搜尋、使用者
搜尋和討論串擷取。若要取得每篇貼文的互動統計資料,例如轉發、
回覆、書籤或瀏覽次數,建議針對確切的貼文 URL
或狀態 ID 進行精準查詢。廣泛的關鍵字搜尋可能找到正確的貼文,但傳回的
每篇貼文中繼資料可能較不完整。建議模式為:先找出貼文,然後
執行第二次 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.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 範例
範例
工具設定檔
如果使用工具設定檔或允許清單,請加入web_search、x_search 或 group:web:
相關內容
- 網頁擷取 —— 擷取 URL 並提取可讀內容
- 網頁瀏覽器 —— 針對大量使用 JS 的網站提供完整瀏覽器自動化
- Grok 搜尋 —— 使用 Grok 作為
web_search提供者 - Ollama 網頁搜尋 —— 透過你的 Ollama 主機進行免金鑰網頁搜尋