網路搜尋

web_search 工具會使用你設定的提供者搜尋網頁並傳回結果。結果會依查詢快取 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 網頁搜尋

啟用 OpenClaw 網頁搜尋且未指定受管理的提供者時，直接 OpenAI Responses 模型會自動使用 OpenAI 託管的 web_search 工具。這是 bundled OpenAI Plugin 中由提供者擁有的行為，且只適用於原生 OpenAI API 流量，不適用於 OpenAI 相容的代理 base 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 的受保護 fetch 路徑。對於 受信任的提供者 API 主機，OpenClaw 只會針對該提供者主機名稱，允許 Surge、Clash 和 sing-box 假 IP DNS 回答中的 198.18.0.0/15 和 fc00::/7。 其他私有、loopback、link-local 和 metadata 目的地仍會被封鎖。

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

# 設定網頁搜尋

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

如果未設定 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_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. DuckDuckGo -- 不需要帳號或 API 金鑰的免金鑰 HTML 備援（順序 100）
11. Ollama Web Search -- 當你設定的本機 Ollama 主機可連線且已透過 ollama signin 登入時，透過它提供免金鑰備援；當主機需要時可重用 Ollama 提供者 bearer auth，且在以 OLLAMA_API_KEY 設定時可直接呼叫 https://ollama.com 搜尋（順序 110）
12. 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 也可以重用 models.providers.google.apiKey 和 models.providers.google.baseUrl，作為其專用網頁搜尋設定和 GEMINI_API_KEY 之後較低優先順序的 備援。範例請參閱供應商頁面。

tools.web.search.provider 會依據隨附和已安裝 Plugin manifest 宣告的網頁搜尋供應商 ID 進行驗證。像 "brvae" 這樣的錯字會導致設定驗證失敗，而不是靜默退回自動偵測。如果 設定的供應商只有過期的 Plugin 證據，例如解除安裝第三方 Plugin 後殘留的 plugins.entries.<plugin> 區塊， OpenClaw 會保持啟動具備韌性並回報警告，讓你可以重新安裝該 Plugin，或執行 openclaw doctor --fix 來清理過期設定。

web_fetch 備援供應商選擇是分開的：

• 使用 tools.web.fetch.provider 選擇它
• 或省略該欄位，讓 OpenClaw 從可用憑證中自動偵測第一個就緒的 web-fetch 供應商
• 非沙箱化的 web_fetch 可以使用宣告 contracts.webFetchProviders 的已安裝 Plugin 供應商；沙箱化 fetch 會維持只使用隨附項目
• 目前隨附的 web-fetch 供應商是 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.*。它使用與 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 金鑰

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

# 相關

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