Web 工具

OpenClaw 自带两个轻量级 Web 工具：

web_search — 使用 Brave Search API、Gemini（Google Search grounding）、Grok、Kimi 或 Perplexity Search API 搜索网络。
web_fetch — HTTP 抓取 + 可读性提取（HTML → markdown/文本）。

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

工作原理

web_search 调用你配置的提供商并返回结果。
结果按查询缓存 15 分钟（可配置）。
web_fetch 发起普通 HTTP GET 请求并提取可读内容（HTML → markdown/文本）。它不会执行 JavaScript。
web_fetch 默认启用（除非显式禁用）。

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

选择搜索提供商

提供商	结果形式	提供商特定过滤器	说明	API key
Brave Search API	带摘要的结构化结果	`country`、`language`、`ui_lang`、时间	支持 Brave `llm-context` 模式	`BRAVE_API_KEY`
Gemini	AI 合成答案 + 引用	—	使用 Google Search grounding	`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 配置

如果没有找到任何 key，回退到 Brave（你会看到缺少 key 的错误并提示配置）。

运行时 SecretRef 行为：

Web 工具的 SecretRef 在 Gateway 启动/重新加载时原子性解析。
自动检测模式下，OpenClaw 只解析选定提供商的 key。未选定提供商的 SecretRef 保持非活跃状态直到被选定。
如果选定提供商的 SecretRef 未解析且没有提供商环境变量备选，启动/重新加载会快速失败。

配置 Web 搜索

使用 openclaw configure --section web 设置 API key 并选择提供商。

Brave Search

在 brave.com/search/api 创建 Brave Search API 账户
在控制台中选择 Search 计划并生成 API key。
运行 openclaw configure --section web 将 key 存入配置，或在环境中设置 BRAVE_API_KEY。

每个 Brave 计划包含 $5/月的免费额度（每月续期）。Search 计划每 1,000 次请求 $5，所以免费额度覆盖 1,000 次查询/月。在 Brave 控制台设置使用量限制以避免意外扣费。详见 Brave API 门户了解当前计划和定价。

Perplexity Search

在 perplexity.ai/settings/api 创建 Perplexity 账户
在控制台生成 API key
运行 openclaw configure --section web 将 key 存入配置，或在环境中设置 PERPLEXITY_API_KEY。

对于旧版 Sonar/OpenRouter 兼容性，改为设置 OPENROUTER_API_KEY，或用 sk-or-... key 配置 tools.web.search.perplexity.apiKey。设置 tools.web.search.perplexity.baseUrl 或 model 也会让 Perplexity 回到 chat-completions 兼容路径。

参见 Perplexity Search API 文档了解更多。

存储 key 的位置

通过配置： 运行 openclaw configure --section web。它将 key 存储在提供商特定的配置路径下：

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 对象。

通过环境变量： 在 Gateway 进程环境中设置提供商环境变量：

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

对于 Gateway 安装，将这些放在 ~/.openclaw/.env（或你的服务环境）中。参见环境变量。

配置示例

Brave Search：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
      },
    },
  },
}

Brave LLM Context 模式：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "YOUR_BRAVE_API_KEY", // optional if BRAVE_API_KEY is set // pragma: allowlist secret
        brave: {
          mode: "llm-context",
        },
      },
    },
  },
}

llm-context 返回提取的页面片段用于 grounding，而非标准 Brave 摘要。该模式下，country 和 language / search_lang 仍然有效，但 ui_lang、freshness、date_after 和 date_before 会被拒绝。

Perplexity Search：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "pplx-...", // optional if PERPLEXITY_API_KEY is set
        },
      },
    },
  },
}

Perplexity 通过 OpenRouter / Sonar 兼容：

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          apiKey: "<openrouter-api-key>", // optional if OPENROUTER_API_KEY is set
          baseUrl: "https://openrouter.ai/api/v1",
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

使用 Gemini（Google Search grounding）

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

获取 Gemini API key

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

配置 Gemini 搜索

{
  tools: {
    web: {
      search: {
        provider: "gemini",
        gemini: {
          // API key (optional if GEMINI_API_KEY is set)
          apiKey: "AIza...",
          // Model (defaults to "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 key：
- 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
以上所有提供商 key 字段都支持 SecretRef 对象。

配置

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // optional if BRAVE_API_KEY is set
        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-... key，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", // optional if FIRECRAWL_API_KEY is set
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // ms (1 day)
          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 在解析前将下载的响应体大小限制在 tools.web.fetch.maxResponseBytes；超大响应会被截断并包含警告。
web_fetch 是尽力提取；某些站点需要用 browser 工具。
参见 Firecrawl 了解 key 设置和服务详情。
响应会缓存（默认 15 分钟）以减少重复抓取。
如果你使用工具配置文件/白名单，添加 web_search/web_fetch 或 group:web。
API key 缺失时，web_search 返回简短的设置提示并附带文档链接。