跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

web_search 工具會使用你設定的供應商搜尋網路，並傳回結果。結果會依查詢快取 15 分鐘（可設定）。 OpenClaw 也包含用於 X（前稱 Twitter）貼文的 x_search，以及用於輕量 URL 擷取的 web_fetch。在此階段，web_fetch 會保持本機執行，而 web_search 和 x_search 可在底層使用 xAI Responses。
web_search 是輕量 HTTP 工具，不是瀏覽器自動化。對於 大量使用 JS 的網站或登入，請使用 Web Browser。若要 擷取特定 URL，請使用 Web Fetch。

​
快速開始

1

Choose a provider

選擇供應商並完成任何必要設定。有些供應商 無需金鑰，而其他供應商使用 API 金鑰。詳情請參閱 下方的供應商頁面。
2

Configure

openclaw configure --section web
這會儲存供應商和任何必要的憑證。你也可以設定 env var（例如 BRAVE_API_KEY），並略過 API 支援 供應商的此步驟。
3

Use it

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 web search 產生附引用來源的 AI 合成答案；未 grounding 的聊天備援會明確失敗。

MiniMax Search

透過 MiniMax Token Plan 搜尋 API 取得結構化結果。

Ollama Web Search

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

Perplexity

結構化結果，具備內容擷取控制與網域篩選。

SearXNG

自行託管的 meta-search。不需要 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
GeminiAI 合成 + 引用來源—GEMINI_API_KEY
GrokAI 合成 + 引用來源—XAI_API_KEY
KimiAI 合成 + 引用來源；未 grounding 的聊天備援會失敗—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

​
自動偵測

當 OpenClaw web search 已啟用且未固定 managed provider 時，直接使用 OpenAI Responses 模型會自動使用 OpenAI 代管的 web_search 工具。這是 bundled OpenAI plugin 中由供應商擁有的行為，且只適用於原生 OpenAI API 流量，不適用於 OpenAI 相容代理 base URL 或 Azure 路由。將 tools.web.search.provider 設為其他供應商（例如 brave），可讓 OpenAI 模型繼續使用 managed web_search 工具；或設定 tools.web.search.enabled: false 以停用 managed search 與原生 OpenAI search。 支援 Codex 的模型可以選擇使用供應商原生 Responses web_search 工具，而不是 OpenClaw 的 managed web_search 函式。
  • 在 tools.web.search.openaiCodex 下設定
  • 只會對支援 Codex 的模型啟用（openai-codex/* 或使用 api: "openai-codex-responses" 的供應商）
  • Managed web_search 仍適用於非 Codex 模型
  • mode: "cached" 是預設且建議的設定
  • tools.web.search.enabled: false 會同時停用 managed 與原生搜尋
{
  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 會維持一般 managed web_search 行為。

​
網路安全

Managed web_search 供應商呼叫會使用 OpenClaw 的受保護 fetch 路徑。對於 受信任的供應商 API 主機，OpenClaw 只會針對該供應商主機名稱， 允許 Surge、Clash 和 sing-box fake-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）
之後是無需金鑰的備援：
  1. DuckDuckGo — 無需帳號或 API 金鑰的無金鑰 HTML 備援（順序 100）
  2. Ollama Web Search — 當你設定的本機 Ollama 主機可連線且已使用 ollama signin 登入時，可透過它使用無需金鑰的備援；主機需要時可重用 Ollama 供應商 bearer auth，並可在設定 OLLAMA_API_KEY 時直接呼叫 https://ollama.com 搜尋（順序 110）
  3. SearXNG — SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（順序 200）
如果未偵測到供應商，會備援到 Brave（你會收到提示設定金鑰的缺少金鑰錯誤）。
所有供應商金鑰欄位都支援 SecretRef 物件。位於 plugins.entries.<plugin>.config.webSearch.apiKey 下、Plugin 範圍的 SecretRefs 會針對 bundled API 支援 web search 供應商解析，包括 Brave、Exa、Firecrawl、 Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily， 無論供應商是透過 tools.web.search.provider 明確選取，還是 透過自動偵測選取。在自動偵測模式中，OpenClaw 只會解析 已選取的供應商金鑰 — 未選取的 SecretRefs 會保持未啟用，因此你可以 保留多個已設定的供應商，而不必為未使用的供應商支付解析成本。

​
設定

{
  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 會依據內建和已安裝 Plugin 清單宣告的網頁搜尋提供者 ID 進行驗證。像 "brvae" 這樣的拼字錯誤會使設定驗證失敗，而不是靜默退回自動偵測。如果設定的提供者只有過期的 Plugin 證據，例如解除安裝第三方 Plugin 後留下的 plugins.entries.<plugin> 區塊，OpenClaw 會保持啟動韌性並回報警告，讓你可以重新安裝該 Plugin，或執行 openclaw doctor --fix 清理過期設定。 web_fetch 備援提供者選擇是分開的：
  • 使用 tools.web.fetch.provider 選擇它
  • 或省略該欄位，讓 OpenClaw 從可用憑證中自動偵測第一個就緒的網頁擷取提供者
  • 非沙箱化的 web_fetch 可使用宣告 contracts.webFetchProviders 的已安裝 Plugin 提供者；沙箱化擷取會維持僅限內建提供者
  • 目前內建的網頁擷取提供者是 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 / Plugin 網頁搜尋憑證。 舊版 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
          },
        },
      },
    },
  },
}

​
工具參數

參數說明
query搜尋查詢（必填）
count要傳回的結果數（1-10，預設：5）
country2 字母 ISO 國家/地區代碼（例如 “US”、“DE”）
languageISO 639-1 語言代碼（例如 “en”、“de”）
search_lang搜尋語言代碼（僅限 Brave）
freshness時間篩選器：day、week、month 或 year
date_after此日期之後的結果（YYYY-MM-DD）
date_before此日期之前的結果（YYYY-MM-DD）
ui_langUI 語言代碼（僅限 Brave）
domain_filter網域允許清單/拒絕清單陣列（僅限 Perplexity）
max_tokens總內容預算，預設 25000（僅限 Perplexity）
max_tokens_per_page每頁權杖限制，預設 2048（僅限 Perplexity）
並非所有參數都適用於所有提供者。Brave llm-context 模式 會拒絕 ui_lang；date_before 也需要 date_after，因為 Brave 自訂 freshness 範圍需要開始和結束日期。 Gemini、Grok 和 Kimi 會傳回一個帶有引用的合成答案。它們 接受 count 以維持共用工具相容性，但這不會改變 grounded 答案形態。Gemini 支援 freshness、date_after 和 date_before，方式是將它們轉換為 Google Search grounding 時間範圍。 當你使用 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 使用 xAI 查詢 X（前身為 Twitter）貼文，並傳回 帶有引用的 AI 合成答案。它接受自然語言查詢與 選用的結構化篩選器。OpenClaw 只會在服務此工具呼叫的請求上啟用內建 xAI x_search 工具。
xAI 文件記載 x_search 支援關鍵字搜尋、語意搜尋、使用者 搜尋和討論串擷取。對於每則貼文的互動統計，例如轉貼、 回覆、書籤或瀏覽次數，建議針對精確貼文 URL 或狀態 ID 進行目標查詢。廣泛關鍵字搜尋可能找到正確貼文，但傳回的 每則貼文中繼資料較不完整。良好模式是：先定位貼文，然後 執行第二次 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 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)
  },
}

​
相關