Web 工具

OpenClaw 內建的輕量級網路工具：web_search 搜尋和 web_fetch 內容擷取。

OpenClaw 內建兩個輕量級網路工具：

web_search — 透過 Brave Search API（預設）、Perplexity Sonar 或 Gemini 搭配 Google Search grounding 搜尋網路。
web_fetch — HTTP 擷取 + 可讀性提取（HTML 轉換為 markdown/text）。

這些不是瀏覽器自動化。對於 JS 密集型網站或登入操作，請使用瀏覽器工具。

運作方式

web_search 呼叫你設定的供應商並回傳結果。
- Brave（預設）：回傳結構化結果（標題、URL、摘要）。
- Perplexity：回傳帶有引用的 AI 合成答案，來自即時網路搜尋。
- Gemini：回傳基於 Google Search 的 AI 合成答案，附帶引用。
結果依查詢快取 15 分鐘（可設定）。
web_fetch 執行純 HTTP GET 並提取可讀內容（HTML 轉換為 markdown/text）。它不會執行 JavaScript。
web_fetch 預設啟用（除非明確停用）。

選擇搜尋供應商

供應商	優點	缺點	API 金鑰
Brave（預設）	快速、結構化結果、免費方案	傳統搜尋結果	`BRAVE_API_KEY`
Perplexity	AI 合成答案、引用、即時	需要 Perplexity 或 OpenRouter 存取	`OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY`
Gemini	Google Search grounding、AI 合成	需要 Gemini API 金鑰	`GEMINI_API_KEY`

參閱 Brave Search 設定和 Perplexity Sonar 了解供應商特定的詳細資訊。

自動偵測

若未明確設定 provider，OpenClaw 會根據可用的 API 金鑰自動偵測要使用的供應商，依以下順序檢查：

Brave — BRAVE_API_KEY 環境變數或 search.apiKey 設定
Gemini — GEMINI_API_KEY 環境變數或 search.gemini.apiKey 設定
Perplexity — PERPLEXITY_API_KEY / OPENROUTER_API_KEY 環境變數或 search.perplexity.apiKey 設定
Grok — XAI_API_KEY 環境變數或 search.grok.apiKey 設定

若找不到金鑰，則退回到 Brave（你會收到缺少金鑰的錯誤提示設定一個）。

明確指定供應商

在設定中指定供應商：

{
  tools: {
    web: {
      search: {
        provider: "brave", // 或 "perplexity" 或 "gemini"
      },
    },
  },
}

範例：切換到 Perplexity Sonar（直接 API）：

{
  tools: {
    web: {
      search: {
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...",
          baseUrl: "https://api.perplexity.ai",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

取得 Brave API 金鑰

在 https://brave.com/search/api/ 建立 Brave Search API 帳戶。
在儀表板中，選擇 Data for Search 方案（不是 “Data for AI”）並產生 API 金鑰。
執行 openclaw configure --section web 將金鑰儲存到設定（建議），或在環境中設定 BRAVE_API_KEY。

Brave 提供免費方案和付費方案；詳情請查看 Brave API 入口網站了解目前的限制和定價。

金鑰設定位置（建議）

建議： 執行 openclaw configure --section web。它會將金鑰儲存在 ~/.openclaw/openclaw.json 的 tools.web.search.apiKey 下。

環境替代方案： 在閘道程序環境中設定 BRAVE_API_KEY。對於閘道安裝，將其放在 ~/.openclaw/.env（或你的服務環境）中。參閱環境變數。

使用 Perplexity（直接或透過 OpenRouter）

Perplexity Sonar 模型具有內建的網路搜尋功能，回傳帶有引用的 AI 合成答案。你可以透過 OpenRouter 使用它們（不需要信用卡 — 支援加密貨幣/預付）。

取得 OpenRouter API 金鑰

在 https://openrouter.ai/ 建立帳戶
新增額度（支援加密貨幣、預付或信用卡）
在帳戶設定中產生 API 金鑰

設定 Perplexity 搜尋

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          // API 金鑰（若設定了 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 則為選用）
          apiKey: "sk-or-v1-...",
          // 基礎 URL（省略時根據金鑰感知預設）
          baseUrl: "https://openrouter.ai/api/v1",
          // 模型（預設為 perplexity/sonar-pro）
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

環境替代方案： 在閘道環境中設定 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY。對於閘道安裝，將其放在 ~/.openclaw/.env。

若未設定基礎 URL，OpenClaw 會根據 API 金鑰來源選擇預設值：

PERPLEXITY_API_KEY 或 pplx-... -> https://api.perplexity.ai
OPENROUTER_API_KEY 或 sk-or-... -> https://openrouter.ai/api/v1
未知金鑰格式 -> OpenRouter（安全退回）

可用的 Perplexity 模型

模型	描述	最適用於
`perplexity/sonar`	快速問答搭配網路搜尋	快速查詢
`perplexity/sonar-pro`（預設）	多步推理搭配網路搜尋	複雜問題
`perplexity/sonar-reasoning-pro`	思維鏈分析	深度研究

使用 Gemini（Google Search grounding）

Gemini 模型支援內建的 Google Search grounding，回傳由即時 Google Search 結果支援的 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 grounding 的引用 URL 會自動從 Google 的重新導向 URL 解析為直接 URL。
重新導向解析使用 SSRF 防護路徑（HEAD + 重新導向檢查 + http/https 驗證）後再回傳最終引用 URL。
預設模型（gemini-2.5-flash）快速且具成本效益。任何支援 grounding 的 Gemini 模型都可使用。

web_search

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

需求

tools.web.search.enabled 不得為 false（預設：啟用）
你所選供應商的 API 金鑰：
- Brave：BRAVE_API_KEY 或 tools.web.search.apiKey
- Perplexity：OPENROUTER_API_KEY、PERPLEXITY_API_KEY 或 tools.web.search.perplexity.apiKey

設定

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

工具參數

query（必填）
count（1-10；預設來自設定）
country（選用）：2 字母國碼用於區域特定結果（例如 “DE”、“US”、“ALL”）。省略時 Brave 選擇其預設區域。
search_lang（選用）：搜尋結果的 ISO 語言代碼（例如 “de”、“en”、“fr”）
ui_lang（選用）：UI 元素的 ISO 語言代碼
freshness（選用）：依發現時間過濾
- Brave：pd、pw、pm、py 或 YYYY-MM-DDtoYYYY-MM-DD
- Perplexity：pd、pw、pm、py

web_fetch

擷取 URL 並提取可讀內容。

web_fetch 需求

tools.web.fetch.enabled 不得為 false（預設：啟用）
選用 Firecrawl 備援：設定 tools.web.fetch.firecrawl.apiKey 或 FIRECRAWL_API_KEY。

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 請求使用反機器人規避模式並預設快取結果。
web_fetch 預設傳送類 Chrome 的 User-Agent 和 Accept-Language；若需要可覆寫 userAgent。
web_fetch 封鎖私有/內部主機名稱並重新檢查重新導向（使用 maxRedirects 限制）。
maxChars 受 tools.web.fetch.maxCharsCap 限制。
web_fetch 在解析前將下載的回應主體大小限制在 tools.web.fetch.maxResponseBytes；過大的回應會被截斷並包含警告。
web_fetch 為盡力而為的提取；部分網站需要使用瀏覽器工具。
參閱 Firecrawl 了解金鑰設定和服務詳情。
回應會被快取（預設 15 分鐘）以減少重複擷取。
若你使用工具配置檔/允許清單，請新增 web_search/web_fetch 或 group:web。
若缺少 Brave 金鑰，web_search 會回傳附帶文件連結的簡短設定提示。