網路搜尋

web_search 工具會使用您設定的提供者搜尋網路並傳回結果。結果會依查詢快取 15 分鐘（可設定）。

OpenClaw 也包含用於 X（前 Twitter）貼文的 x_search，以及用於輕量級 URL 擷取的 web_fetch。在此階段，web_fetch 保持在本機，而 web_search 和 x_search 則可在底層使用 xAI Responses。

快速開始

選擇提供者
選擇一個提供者並完成任何必要的設定。某些提供者不需要金鑰，而其他的則使用 API 金鑰。請參閱下方的提供者頁面以瞭解詳細資訊。
設定
Terminal window
```
openclaw configure --section web
```
這會儲存提供者和任何所需的認證資訊。您也可以設定環境變數（例如 BRAVE_API_KEY）並針對使用 API 的提供者跳過此步驟。

使用

Agent 現在可以呼叫 web_search：

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

若要搜尋 X 貼文，請使用：

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

選擇提供者

Brave Search

附有摘要的結構化結果。支援 llm-context 模式、國家/語言篩選。提供免費層級。

DuckDuckGo

無需金鑰的備選方案。不需要 API 金鑰。非官方的 HTML 整合方式。

Exa

神經網路 + 關鍵字搜尋，具備內容提取功能（亮點、文字、摘要）。

Firecrawl

結構化結果。最適合與 firecrawl_search 和 firecrawl_scrape 搭配使用以進行深度提取。

Gemini

透過 Google Search 搜尋 grounding 提供引用文獻的 AI 綜合回答。

Grok

透過 xAI web grounding 提供引用文獻的 AI 綜合回答。

Kimi

透過 Moonshot 網頁搜尋提供附引用來源的 AI 綜合回答；未落地的聊天備援會明確失敗。

MiniMax Search

透過 MiniMax Token Plan 搜尋 API 提供結構化結果。

Ollama Web Search

透過已登入的本機 Ollama 主機或託管的 Ollama API 進行搜尋。

Perplexity

具有內容提取控制和網域過濾功能的結構化結果。

SearXNG

自託管的元搜尋。不需要 API 金鑰。聚合 Google、Bing、DuckDuckGo 等。

Tavily

具有搜尋深度、主題過濾和用於 URL 提取的 tavily_extract 的結構化結果。

供應商比較

供應商	結果樣式	過濾器	API 金鑰
Brave	結構化摘要	國家、語言、時間、`llm-context` 模式	`BRAVE_API_KEY`
DuckDuckGo	結構化摘要	—	無（免金鑰）
Exa	結構化 + 已提取	神經/關鍵字模式、日期、內容提取	`EXA_API_KEY`
Firecrawl	結構化摘要	透過 `firecrawl_search` 工具	`FIRECRAWL_API_KEY`
Gemini	AI 合成 + 引文	—	`GEMINI_API_KEY`
Grok	AI 合成 + 引文	—	`XAI_API_KEY`
Kimi	AI 綜合回答 + 引用來源；未落地的聊天備援會失敗	—	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
MiniMax Search	結構化摘要	區域 (`global` / `cn`)	`MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN`
Ollama Web Search	結構化摘要	—	已登入的本機主機無需額外設定；直接 `https://ollama.com` 搜尋則需 `OLLAMA_API_KEY`
Perplexity	結構化摘要	國家、語言、時間、網域、內容限制	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`
SearXNG	結構化摘要	分類、語言	無（自託管）
Tavily	結構化摘要	透過 `tavily_search` 工具	`TAVILY_API_KEY`

自動偵測

原生 OpenAI 網路搜尋

當啟用 OpenClaw 網路搜尋且未釘選受管理提供者時，直接的 OpenAI Responses 模型會自動使用 OpenAI 託管的 web_search 工具。這是內建的 OpenAI 外掛中的提供者擁有行為，僅適用於原生的 OpenAI API 流量，不適用於 OpenAI 相容的代理基礎 URL 或 Azure 路由。將 tools.web.search.provider 設定為其他提供者（例如 brave）以為 OpenAI 模型保留受管理的 web_search 工具，或者將 tools.web.search.enabled: false 設定為停用以停用受管理搜尋和原生 OpenAI 搜尋。

原生 Codex 網路搜尋

支援 Codex 的模型可以選擇性地使用提供者原生的 Responses web_search 工具，而不是 OpenClaw 受管理的 web_search 函式。

在 tools.web.search.openaiCodex 下進行設定
它僅針對支援 Codex 的模型（openai-codex/* 或使用 api: "openai-codex-responses" 的提供者）啟用
受管理的 web_search 仍適用於非 Codex 模型
mode: "cached" 是預設且建議的設定
tools.web.search.enabled: false 會停用受管理搜尋和原生搜尋

{
  tools: {
    web: {
      search: {
        enabled: true,
        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 行為。

網路安全

受管理的 web_search 提供者呼叫使用 OpenClaw 的防護擷取路徑。對於受信任的提供者 API 主機，OpenClaw 僅針對該提供者主機名稱在 198.18.0.0/15 和 fc00::/7 中允許 Surge、Clash 和 sing-box 的假 IP DNS 回應。其他私人、環回、連結本地和元資料目的地仍會被阻擋。

此自動許可不適用於任意的 web_fetch URL。對於 web_fetch，僅在您受信任的代理擁有這些合成範圍時，才明確啟用 tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange 和 tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange。

設定網路搜尋

文件和設定流程中的提供者清單按字母順序排列。自動偵測則維持單獨的優先順序。

如果未設定 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_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)

之後是不需要金鑰的後備選項：

DuckDuckGo — 不需要金鑰的 HTML 後備選項，無需帳戶或 API 金鑰 (順序 100)
Ollama Web Search — 當設定的本地 Ollama 主機可達並使用 ollama signin 登入時，透過該主機進行免金鑰的後備搜尋；如果主機需要，可以重複使用 Ollama 提供者的 bearer auth，並且當使用 OLLAMA_API_KEY 設定時，可以呼叫直接的 https://ollama.com 搜尋 (順序 110)
SearXNG — SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl (順序 200)

如果未偵測到任何提供者，它會後備至 Brave (您將會收到缺少金鑰的錯誤，提示您進行設定)。

設定

{
  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 也可以在其專用網路搜尋設定和 GEMINI_API_KEY 之後，重複使用 models.providers.google.apiKey 和 models.providers.google.baseUrl 作為較低優先順序的後援。請參閱提供者頁面以取得範例。

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，設定位於 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 也可以提供使用相同金鑰的選用 x_search 設定。這是 Grok 路徑內的一個獨立後續步驟，而非獨立的頂層網路搜尋提供者選擇。如果您選擇其他提供者，OpenClaw 將不會顯示 x_search 提示。

儲存 API 金鑰

執行 openclaw configure --section web 或直接設定金鑰：

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

在 Gateway 程序環境中設定提供者環境變數：

export BRAVE_API_KEY="YOUR_KEY"

若為 gateway 安裝，請將其放入 ~/.openclaw/.env。參閱環境變數。

工具參數

參數	描述
`query`	搜尋查詢（必填）
`count`	要傳回的結果數量（1-10，預設值：5）
`country`	兩個字母的 ISO 國家/地區代碼（例如 “US”、“DE”）
`language`	ISO 639-1 語言代碼（例如 “en”、“de”）
`search_lang`	搜尋語言代碼（僅限 Brave）
`freshness`	時間篩選：`day`、`week`、`month` 或 `year`
`date_after`	此日期之後的結果 (YYYY-MM-DD)
`date_before`	此日期之前的結果 (YYYY-MM-DD)
`ui_lang`	UI 語言代碼（僅限 Brave）
`domain_filter`	網域允許列表/封鎖列表陣列（僅限 Perplexity）
`max_tokens`	總內容預算，預設為 25000（僅限 Perplexity）
`max_tokens_per_page`	每頁 token 限制，預設為 2048（僅限 Perplexity）

Warning

並非所有參數都適用於所有供應商。Brave 的 llm-context 模式會拒絕 ui_lang；date_before 也需要 date_after，因為 Brave 自訂新鮮度範圍需要開始和結束日期。 Gemini、Grok 和 Kimi 會傳回一個附帶引用的綜合答案。它們接受 count 以相容共用工具，但這不會改變事實依據的答案形狀。Gemini 支援 freshness、date_after 和 date_before，方法是將其轉換為 Google 搜尋事實依據的時間範圍。當您使用 Sonar/OpenRouter 相容路徑 (plugins.entries.perplexity.config.webSearch.baseUrl / model 或 OPENROUTER_API_KEY) 時，Perplexity 的行為也相同。 SearXNG 僅對受信任的私人網路或 loopback 主機接受 http://；公共 SearXNG 端點必須使用 https://。 Firecrawl 和 Tavily 僅透過 web_search 支援 query 和 count — 若要使用進階選項，請使用其專屬工具。

x_search

x_search 使用 xAI 查詢 X（前身為 Twitter）貼文並傳回附帶引用的 AI 綜合答案。它接受自然語言查詢和可選的結構化篩選器。OpenClaw 僅在服務此工具呼叫的請求上啟用內建的 xAI x_search 工具。

x_search config

{
  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 參數

參數	說明
`query`	搜尋查詢（必填）
`allowed_x_handles`	將結果限制為特定的 X 帳號
`excluded_x_handles`	排除特定的 X 帳號
`from_date`	僅包含此日期或之後的貼文 (YYYY-MM-DD)
`to_date`	僅包含此日期或之前的貼文 (YYYY-MM-DD)
`enable_image_understanding`	讓 xAI 檢查符合貼文中附加的圖片
`enable_video_understanding`	讓 xAI 檢查符合貼文中附加的影片

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 possible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

範例

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

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

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