Web 工具

OpenClaw 內建兩個輕量級 Web 工具：

web_search — 使用 Brave Search API、Gemini 搭配 Google 搜尋基底、Grok、Kimi 或 Perplexity Search API 搜尋網路。
web_fetch — HTTP 擷取 + 可讀性提取（HTML → markdown/文字）。

這些不是瀏覽器自動化。對於重度使用 JS 的網站或需要登入的頁面，請使用瀏覽器工具。

運作方式

web_search 呼叫你設定的供應商並回傳結果。
搜尋結果按查詢快取 15 分鐘（可設定）。
web_fetch 執行純 HTTP GET 並提取可讀內容（HTML → markdown/文字），不會執行 JavaScript。
web_fetch 預設為啟用（除非明確停用）。

各供應商的詳細設定請參閱 Brave Search 設定和 Perplexity Search 設定。

選擇搜尋供應商

供應商	結果格式	供應商專屬篩選器	備註	API 金鑰
Brave Search API	含摘要的結構化結果	`country`、`language`、`ui_lang`、時間	支援 Brave `llm-context` 模式	`BRAVE_API_KEY`
Gemini	AI 合成回答 + 引用	—	使用 Google 搜尋基底	`GEMINI_API_KEY`
Grok	AI 合成回答 + 引用	—	使用 xAI 網路基底回應	`XAI_API_KEY`
Kimi	AI 合成回答 + 引用	—	使用 Moonshot 網路搜尋	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
Perplexity Search API	含摘要的結構化結果	`country`、`language`、時間、`domain_filter`	支援內容提取控制；OpenRouter 使用 Sonar 相容路徑	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`

自動偵測

上表按字母排序。未明確設定 provider 時，執行時自動偵測按以下順序檢查：

Brave — BRAVE_API_KEY 環境變數或 tools.web.search.apiKey 設定
Gemini — GEMINI_API_KEY 環境變數或 tools.web.search.gemini.apiKey 設定
Grok — XAI_API_KEY 環境變數或 tools.web.search.grok.apiKey 設定
Kimi — KIMI_API_KEY / MOONSHOT_API_KEY 環境變數或 tools.web.search.kimi.apiKey 設定
Perplexity — PERPLEXITY_API_KEY、OPENROUTER_API_KEY 或 tools.web.search.perplexity.apiKey 設定

若找不到任何金鑰，會後備至 Brave（並顯示缺少金鑰的錯誤提示你進行設定）。

執行時 SecretRef 行為：

Web 工具的 SecretRef 在閘道啟動/重載時原子性解析。
在自動偵測模式下，OpenClaw 只解析被選中的供應商金鑰。未被選中的供應商 SecretRef 在被選中前保持非啟用狀態。
如果被選中的供應商 SecretRef 未解析且沒有環境變數後備，啟動/重載會立即失敗。

設定網路搜尋

使用 openclaw configure --section web 設定你的 API 金鑰並選擇供應商。

Brave Search

在 brave.com/search/api 建立 Brave Search API 帳號
在控制台中選擇 Search 方案並產生 API 金鑰。
執行 openclaw configure --section web 將金鑰儲存到設定中，或在環境中設定 BRAVE_API_KEY。

每個 Brave 方案包含每月 $5 免費額度（每月重置）。Search 方案每 1,000 次請求收費 $5，因此免費額度可涵蓋每月 1,000 次查詢。請在 Brave 控制台設定用量上限以避免意外收費。最新方案與定價請參閱 Brave API 入口。

Perplexity Search

在 perplexity.ai/settings/api 建立 Perplexity 帳號
在控制台產生 API 金鑰
執行 openclaw configure --section web 將金鑰儲存到設定中，或在環境中設定 PERPLEXITY_API_KEY。

若需使用舊版 Sonar/OpenRouter 相容性，改設定 OPENROUTER_API_KEY，或在 tools.web.search.perplexity.apiKey 中使用 sk-or-... 金鑰。設定 tools.web.search.perplexity.baseUrl 或 model 也會讓 Perplexity 切回 chat-completions 相容路徑。

詳情請參閱 Perplexity Search API 文件。

金鑰儲存位置

**透過設定：**執行 openclaw configure --section web。金鑰會儲存在供應商專屬的設定路徑下：

Brave：tools.web.search.apiKey
Gemini：tools.web.search.gemini.apiKey
Grok：tools.web.search.grok.apiKey
Kimi：tools.web.search.kimi.apiKey
Perplexity：tools.web.search.perplexity.apiKey

以上所有欄位也支援 SecretRef 物件。

**透過環境變數：**在閘道程序環境中設定供應商環境變數：

Brave：BRAVE_API_KEY
Gemini：GEMINI_API_KEY
Grok：XAI_API_KEY
Kimi：KIMI_API_KEY 或 MOONSHOT_API_KEY
Perplexity：PERPLEXITY_API_KEY 或 OPENROUTER_API_KEY

如果是閘道安裝，將這些放在 ~/.openclaw/.env（或你的服務環境）。參閱環境變數。

設定範例

Brave Search：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // 如已設定 BRAVE_API_KEY 則為選填 // pragma: allowlist secret
      },
    },
  },
}

Brave LLM Context 模式：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // 如已設定 BRAVE_API_KEY 則為選填 // pragma: allowlist secret
        brave: {
          mode: "llm-context",
        },
      },
    },
  },
}

llm-context 回傳提取的頁面片段用於基底，而非標準 Brave 摘要。此模式下 country 和 language / search_lang 仍可使用，但 ui_lang、 freshness、date_after 和 date_before 會被拒絕。

Perplexity Search：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // 如已設定 PERPLEXITY_API_KEY 則為選填
        },
      },
    },
  },
}

Perplexity 透過 OpenRouter / Sonar 相容：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "<openrouter-api-key>", // 如已設定 OPENROUTER_API_KEY 則為選填
          baseUrl: "https://openrouter.ai/api/v1",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

使用 Gemini（Google 搜尋基底）

Gemini 模型支援內建的 Google 搜尋基底，回傳由即時 Google 搜尋結果支撐的 AI 合成回答及引用。

取得 Gemini API 金鑰

前往 Google AI Studio
建立 API 金鑰
在閘道環境中設定 GEMINI_API_KEY，或設定 tools.web.search.gemini.apiKey

設定 Gemini 搜尋

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // API 金鑰（如已設定 GEMINI_API_KEY 則為選填）
          apiKey: "AIza...",
          // 模型（預設為 "gemini-2.5-flash"）
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

**環境變數方式：**在閘道環境中設定 GEMINI_API_KEY。如果是閘道安裝，將其放在 ~/.openclaw/.env。

注意事項

Gemini 基底的引用 URL 會自動從 Google 重導向 URL 解析為直接 URL。
重導向解析使用 SSRF 防護路徑（HEAD + 重導向檢查 + http/https 驗證）後回傳最終引用 URL。
重導向解析使用嚴格的 SSRF 預設值，因此指向私有/內部目標的重導向會被阻擋。
預設模型（gemini-2.5-flash）快速且經濟實惠。任何支援基底的 Gemini 模型都可使用。

web_search

使用你設定的供應商搜尋網路。

必要條件

tools.web.search.enabled 不能為 false（預設：啟用）
所選供應商的 API 金鑰：
- Brave：BRAVE_API_KEY 或 tools.web.search.apiKey
- Gemini：GEMINI_API_KEY 或 tools.web.search.gemini.apiKey
- Grok：XAI_API_KEY 或 tools.web.search.grok.apiKey
- Kimi：KIMI_API_KEY、MOONSHOT_API_KEY 或 tools.web.search.kimi.apiKey
- Perplexity：PERPLEXITY_API_KEY、OPENROUTER_API_KEY 或 tools.web.search.perplexity.apiKey
以上所有供應商金鑰欄位支援 SecretRef 物件。

設定

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // 如已設定 BRAVE_API_KEY 則為選填
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

工具參數

除非另外註明，所有參數適用於 Brave 和原生 Perplexity Search API。

Perplexity 的 OpenRouter / Sonar 相容路徑僅支援 query 和 freshness。如果你設定了 tools.web.search.perplexity.baseUrl / model、使用 OPENROUTER_API_KEY 或設定了 sk-or-... 金鑰，Search API 專屬篩選器會回傳明確錯誤。

參數	說明
`query`	搜尋查詢（必填）
`count`	回傳結果數（1-10，預設：5）
`country`	2 字元 ISO 國碼（例如 “US”、“DE”）
`language`	ISO 639-1 語言代碼（例如 “en”、“de”）
`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）

範例：

// 德國區域搜尋
await web_search({
  query: "TV online schauen",
  country: "DE",
  language: "de",
});

// 近期結果（過去一週）
await web_search({
  query: "TMBG interview",
  freshness: "week",
});

// 日期範圍搜尋
await web_search({
  query: "AI developments",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// 網域篩選（僅限 Perplexity）
await web_search({
  query: "climate research",
  domain_filter: ["nature.com", "science.org", ".edu"],
});

// 排除網域（僅限 Perplexity）
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

// 提取更多內容（僅限 Perplexity）
await web_search({
  query: "detailed AI research",
  max_tokens: 50000,
  max_tokens_per_page: 4096,
});

啟用 Brave llm-context 模式時，不支援 ui_lang、freshness、date_after 和 date_before。需要這些篩選器時請使用 Brave web 模式。

web_fetch

擷取 URL 並提取可讀內容。

web_fetch 必要條件

tools.web.fetch.enabled 不能為 false（預設：啟用）
選用 Firecrawl 後備：設定 tools.web.fetch.firecrawl.apiKey 或 FIRECRAWL_API_KEY。
tools.web.fetch.firecrawl.apiKey 支援 SecretRef 物件。

web_fetch 設定

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "FIRECRAWL_API_KEY_HERE", // 如已設定 FIRECRAWL_API_KEY 則為選填
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // 毫秒（1 天）
          timeoutSeconds: 60,
        },
      },
    },
  },
}

web_fetch 工具參數

url（必填，僅限 http/https）
extractMode（markdown | text）
maxChars（截斷過長頁面）

注意事項：

web_fetch 先使用 Readability（主內容提取），再使用 Firecrawl（如有設定）。兩者都失敗時回傳錯誤。
Firecrawl 請求使用反機器人繞過模式，預設快取結果。
Firecrawl SecretRef 僅在 Firecrawl 啟用時解析（tools.web.fetch.enabled !== false 且 tools.web.fetch.firecrawl.enabled !== false）。
如果 Firecrawl 啟用但其 SecretRef 未解析且沒有 FIRECRAWL_API_KEY 後備，啟動/重載會立即失敗。
web_fetch 預設傳送類 Chrome 的 User-Agent 和 Accept-Language；如需覆寫請修改 userAgent。
web_fetch 會阻擋私有/內部主機名稱，並重新檢查重導向（使用 maxRedirects 限制）。
maxChars 受 tools.web.fetch.maxCharsCap 上限限制。
web_fetch 在解析前會將下載的回應 body 大小限制在 tools.web.fetch.maxResponseBytes；超大的回應會被截斷並附帶警告。
web_fetch 是盡力提取；部分網站需要使用瀏覽器工具。
金鑰設定與服務細節請參閱 Firecrawl。
回應會快取（預設 15 分鐘）以減少重複擷取。
如果你使用工具設定檔/允許清單，請加入 web_search/web_fetch 或 group:web。
API 金鑰缺少時，web_search 會回傳簡短的設定提示及文件連結。