11.8 Web工具

工具与技能工具与技能

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

  • web_search — 通过 Brave Search（默认）或 Perplexity Sonar（直连或 OpenRouter）搜索网页。
  • web_fetch — 纯 HTTP 抓取 + 可读内容提取（HTML → markdown/text）。

它们不是浏览器自动化。如果需要处理 JS-heavy 页面或登录流程，请使用 浏览器工具。

工作方式

  • web_search 调用配置的搜索提供商并返回结果。
    • Brave（默认）：返回结构化结果（标题、URL、摘要）。
    • Perplexity：返回带引用的 AI 汇总答案。
  • 搜索结果按查询缓存 15 分钟（可配置）。
  • web_fetch 进行 HTTP GET 并提取可读内容，不执行 JavaScript。
  • web_fetch 默认启用（除非显式关闭）。

选择搜索提供商

提供商优点限制API Key
Brave（默认） 速度快、结构化结果、提供免费额度 传统搜索结果 BRAVE_API_KEY
Perplexity AI 汇总答案、带引用、实时检索 需要 Perplexity 或 OpenRouter 访问 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY

详情请参考 Brave Search 设置 与 Perplexity Sonar。提供商在配置中设置：

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

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

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

获取 Brave API Key

  1. 在 Brave Search API 创建账号。
  2. 在控制台选择 Data for Search 计划（不是 Data for AI），生成 API key。
  3. 运行 openclaw configure --section web 写入配置（推荐），或在环境中设置 BRAVE_API_KEY。

Brave 提供免费额度与付费方案，具体以官方控制台为准。

Key 存放位置（推荐）

推荐：运行 openclaw configure --section web，会写入 ~/.openclaw/openclaw.json 的 tools.web.search.apiKey。环境变量方案：为 Gateway 进程设置 BRAVE_API_KEY，服务安装建议放在 ~/.openclaw/.env（或服务环境变量中）。详见 环境变量。

使用 Perplexity（直连或经 OpenRouter）

Perplexity Sonar 模型内置网页搜索并返回带引用的 AI 汇总答案。也可通过 OpenRouter 使用（无需信用卡，支持加密货币/预付费）。

获取 OpenRouter API Key

  1. 在 OpenRouter 创建账号。
  2. 充值（支持加密货币、预付费或信用卡）。
  3. 在账号设置中生成 API key。

配置 Perplexity 搜索

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "perplexity",
        perplexity: {
          // API key（若已设置 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 可省略）
          apiKey: "sk-or-v1-...",
          // Base URL（省略时会根据 key 类型自动判断）
          baseUrl: "https://openrouter.ai/api/v1",
          // 模型（默认 perplexity/sonar-pro）
          model: "perplexity/sonar-pro",
        },
      },
    },
  },
}

环境变量替代方案：在 Gateway 环境中设置 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY（服务安装可放 ~/.openclaw/.env）。如果未指定 baseUrl，OpenClaw 会根据 key 类型选择默认值：

  • PERPLEXITY_API_KEY 或 pplx-... → https://api.perplexity.ai
  • OPENROUTER_API_KEY 或 sk-or-... → https://openrouter.ai/api/v1
  • 未知 key 格式 → 走 OpenRouter（安全回退）

可用 Perplexity 模型

模型说明适用场景
perplexity/sonar快速回答 + 网页搜索快速查询
perplexity/sonar-pro（默认）更高准确度 + 网页搜索复杂问题
perplexity/sonar-reasoning强化推理 + 网页搜索需要推理的查询
perplexity/sonar-reasoning-pro更强推理 + 网页搜索深度分析
perplexity/sonar-deep-research深度研究（10–30 分钟）长周期研究

web_search

使用已配置的提供商进行网页搜索。

Requirements

  • tools.web.search.enabled 不能为 false（默认启用）。
  • 需要对应提供商的 API key：
    • Brave：BRAVE_API_KEY 或 tools.web.search.apiKey
    • Perplexity：OPENROUTER_API_KEY、PERPLEXITY_API_KEY 或 tools.web.search.perplexity.apiKey

Config

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE", // 若已设置 BRAVE_API_KEY 可省略
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

Tool parameters

  • query（必填）
  • count（1–10；默认使用配置中的 maxResults）
  • country（可选）：2 字母国家码，用于区域结果（如 DE、US、ALL）
  • search_lang（可选）：搜索结果语言（如 de、en、fr）
  • ui_lang（可选）：UI 元素语言
  • freshness（可选，仅 Brave）：按发现时间过滤（pd/pw/pm/py 或 YYYY-MM-DDtoYYYY-MM-DD）

示例：

// 德语地区搜索
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 并提取可读内容。

Requirements

  • tools.web.fetch.enabled 不能为 false（默认启用）。
  • 可选 Firecrawl 作为兜底：设置 tools.web.fetch.firecrawl.apiKey 或 FIRECRAWL_API_KEY。

Config

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 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", // 若已设置 FIRECRAWL_API_KEY 可省略
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
          maxAgeMs: 86400000, // 毫秒（1 天）
          timeoutSeconds: 60,
        },
      },
    },
  },
}

Tool parameters

  • url（必填，仅支持 http/https）
  • extractMode（markdown | text）
  • maxChars（截断超长页面）

说明：

  • web_fetch 会先尝试 Readability（主内容提取），失败再走 Firecrawl（如果已配置）。
  • Firecrawl 请求默认启用反爬模式并缓存结果。
  • web_fetch 默认发送类 Chrome 的 User-Agent 和 Accept-Language，必要时可覆盖 userAgent。
  • 会阻止私有/内网域名，并在重定向时重新校验（可用 maxRedirects 限制）。
  • 这是“尽力而为”的抽取策略，部分站点仍需浏览器工具。
  • Firecrawl 详情与 Key 设置参考 Firecrawl 文档。
  • 响应默认缓存 15 分钟，减少重复抓取。
  • 若使用工具配置文件/白名单，请添加 web_search / web_fetch 或 group:web。
  • 如果缺少 Brave key，web_search 会返回简短的设置提示与文档链接。