Web 工具

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

web_search — 通过 Brave Search API（默认）或 Perplexity Sonar（直接或通过 OpenRouter）进行网页搜索。
web_fetch — HTTP 获取 + 可读内容提取（HTML → markdown/文本）。

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

工作原理

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

选择搜索服务提供商

提供商	优点	缺点	API 密钥
Brave（默认）	快速、结构化结果、免费层级	传统的搜索结果	`BRAVE_API_KEY`
Perplexity	AI 合成的答案、引用、实时	需要 Perplexity 或 OpenRouter 访问	`OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY`

查看 Brave Search 设置和 Perplexity Sonar 以获取提供商特定的详细信息。

在配置中设置提供商：

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

示例：切换到 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 key (optional if OPENROUTER_API_KEY or PERPLEXITY_API_KEY is set)
          apiKey: "sk-or-v1-...",
          // Base URL (key-aware default if omitted)
          baseUrl: "https://openrouter.ai/api/v1",
          // Model (defaults to 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`	思维链分析	深度研究

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", // optional if BRAVE_API_KEY is set
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

工具参数

query（必需）
count（1–10；默认来自配置）
country（可选）：两位字母的国家代码用于特定区域的结果（例如，“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)

示例：

// German-specific search
await web_search({
  query: "TV online schauen",
  count: 10,
  country: "DE",
  search_lang: "de",
});

// French search with French UI
await web_search({
  query: "actualités",
  country: "FR",
  search_lang: "fr",
  ui_lang: "fr",
});

// Recent results (past week)
await web_search({
  query: "TMBG interview",
  freshness: "pw",
});

web_fetch

获取 URL 并提取可读内容。

要求

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

配置

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        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,
        },
      },
    },
  },
}

工具参数

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 是尽力提取；某些站点可能需要浏览器工具。
查看 Firecrawl 以获取密钥设置和服务详细信息。
响应被缓存（默认 15 分钟）以减少重复获取。
如果你使用工具配置文件/白名单，添加 web_search/web_fetch 或 group:web。
如果缺少 Brave 密钥，web_search 返回一个简短的设置提示和文档链接。