Web 工具

OpenClaw 提供两个轻量级的 Web 工具：

web_search — 通过 Brave Search API（默认）、Perplexity Sonar、Gemini（Google 搜索 Grounding）、Grok 或 Kimi 搜索网页。
web_fetch — HTTP 获取 + 可读性提取（HTML → markdown/文本）。

这些不是浏览器自动化。对于 JS 密集型网站或需要登录的场景，请使用浏览器工具。

工作原理

web_search 调用你配置的提供商并返回结果。
- Brave（默认）：返回结构化结果（标题、URL、摘要）。
- Perplexity：返回基于实时网络搜索的 AI 合成答案及引用。
- Gemini：返回基于 Google 搜索 Grounding 的 AI 合成答案及引用。
- 结果按查询缓存 15 分钟（可配置）。
web_fetch 执行纯 HTTP GET 并提取可读内容（HTML → markdown/文本）。它不执行 JavaScript。
web_fetch 默认启用（除非显式禁用）。

选择搜索提供商

提供商	优点	缺点	API 密钥
Brave（默认）	快速、结构化结果	传统搜索结果；AI 使用条款适用	`BRAVE_API_KEY`
Perplexity	AI 合成答案、引用、实时	需要 Perplexity 或 OpenRouter 访问权限	`OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY`
Gemini	Google 搜索 Grounding、AI 合成	需要 Gemini API 密钥	`GEMINI_API_KEY`
Grok	xAI 网络支持的响应	需要 xAI API 密钥	`XAI_API_KEY`
Kimi	Moonshot 网络搜索能力	需要 Moonshot API 密钥	`KIMI_API_KEY` / `MOONSHOT_API_KEY`

参见 Brave Search 设置和 Perplexity Sonar 了解提供商特定的详情。

自动检测

如果未显式设置 provider，OpenClaw 会根据可用的 API 密钥自动检测使用哪个提供商，按以下顺序检查：

Brave — BRAVE_API_KEY 环境变量或 tools.web.search.apiKey 配置
Gemini — GEMINI_API_KEY 环境变量或 tools.web.search.gemini.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 配置
Grok — XAI_API_KEY 环境变量或 tools.web.search.grok.apiKey 配置

如果未找到任何密钥，回退到 Brave（你会收到缺失密钥的错误提示，引导你进行配置）。

显式指定提供商

在配置中设置提供商：

json5

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

示例：切换到 Perplexity Sonar（直接 API）：

json5

{
  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 门户了解当前的限制和定价。Brave 条款对搜索结果的某些 AI 相关用途有限制。请查阅 Brave 服务条款并确认你的预期用途符合规定。如有法律问题，请咨询你的法律顾问。

密钥存储位置（推荐）

推荐： 运行 openclaw configure --section web。它会将密钥存储在 ~/.openclaw/openclaw.json 的 tools.web.search.apiKey 下。

环境变量替代方案： 在 Gateway 进程环境中设置 BRAVE_API_KEY。对于 gateway 安装，将其放在 ~/.openclaw/.env（或你的服务环境中）。参见环境变量。

使用 Perplexity（直接或通过 OpenRouter）

Perplexity Sonar 模型具有内置的网络搜索能力，返回带有引用的 AI 合成答案。你可以通过 OpenRouter 使用它们（无需信用卡 - 支持加密货币/预付卡）。

获取 OpenRouter API 密钥

在 https://openrouter.ai/ 创建账户
充值（支持加密货币、预付卡或信用卡）
在账户设置中生成 API 密钥

设置 Perplexity 搜索

json5

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

环境变量替代方案： 在 Gateway 环境中设置 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY。对于 gateway 安装，将其放在 ~/.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 搜索 Grounding）

Gemini 模型支持内置的 Google 搜索 Grounding，返回基于实时 Google 搜索结果的 AI 合成答案及引用。

获取 Gemini API 密钥

前往 Google AI Studio
创建 API 密钥
在 Gateway 环境中设置 GEMINI_API_KEY，或配置 tools.web.search.gemini.apiKey

设置 Gemini 搜索

json5

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // API 密钥（如果已设置 GEMINI_API_KEY 则可选）
          apiKey: "AIza...",
          // 模型（默认为 "gemini-2.5-flash"）
          model: "gemini-2.5-flash",
        },
      },
    },
  },
}

环境变量替代方案： 在 Gateway 环境中设置 GEMINI_API_KEY。对于 gateway 安装，将其放在 ~/.openclaw/.env 中。

说明

Gemini Grounding 的引用 URL 会自动从 Google 的重定向 URL 解析为直接 URL。
重定向解析使用 SSRF 防护路径（HEAD + 重定向检查 + http/https 验证）后返回最终引用 URL。
重定向解析使用严格的 SSRF 默认值，因此重定向到私有/内部目标会被阻止。
默认模型（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
- 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

配置

json5

{
  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

示例：

javascript

// 德国特定搜索
await web_search({
  query: "TV online schauen",
  count: 10,
  country: "DE",
  search_lang: "de",
});

// 法语搜索配法语 UI
await web_search({
  query: "actualités",
  country: "FR",
  search_lang: "fr",
  ui_lang: "fr",
});

// 最近结果（过去一周）
await web_search({
  query: "TMBG interview",
  freshness: "pw",
});

web_fetch

获取 URL 并提取可读内容。

web_fetch 要求

tools.web.fetch.enabled 不能为 false（默认：启用）
可选的 Firecrawl 回退：设置 tools.web.fetch.firecrawl.apiKey 或 FIRECRAWL_API_KEY。

web_fetch 配置

json5

{
  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 返回一个简短的设置提示和文档链接。

Web 工具 ​

工作原理 ​

选择搜索提供商 ​

自动检测 ​

显式指定提供商 ​

获取 Brave API 密钥 ​

密钥存储位置（推荐） ​

使用 Perplexity（直接或通过 OpenRouter） ​

获取 OpenRouter API 密钥 ​

设置 Perplexity 搜索 ​

可用的 Perplexity 模型 ​

使用 Gemini（Google 搜索 Grounding） ​

获取 Gemini API 密钥 ​

设置 Gemini 搜索 ​

说明 ​

web_search ​

要求 ​

配置 ​

工具参数 ​

web_fetch ​

web_fetch 要求 ​

web_fetch 配置 ​

web_fetch 工具参数 ​

Web 工具

工作原理

选择搜索提供商

自动检测

显式指定提供商

获取 Brave API 密钥

密钥存储位置（推荐）

使用 Perplexity（直接或通过 OpenRouter）

获取 OpenRouter API 密钥

设置 Perplexity 搜索

可用的 Perplexity 模型

使用 Gemini（Google 搜索 Grounding）

获取 Gemini API 密钥

设置 Gemini 搜索

说明

web_search

要求

配置

工具参数

web_fetch

web_fetch 要求

web_fetch 配置

web_fetch 工具参数