Web 工具

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

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

这些不是浏览器自动化。对于 JS 重度的站点或登录，使用 Browser tool。

工作原理

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

选择搜索提供商

Provider（提供商）	Pros（优点）	Cons（缺点）	API Key
Brave（默认）	快速、结构化结果、免费套餐	传统搜索结果	BRAVE_API_KEY
Perplexity	AI 合成答案、引用、实时	需要 Perplexity 或 OpenRouter 访问	OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY

有关特定提供商的详细信息，参见 Brave Search setup 和 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

在 https://brave.com/search/api/ 创建 Brave Search API 账户
在 dashboard（仪表板）中，选择 Data for Search 计划（不是 "Data for AI"）并生成 API key。
运行 openclaw configure --section web 将 key 存储在配置中（推荐），或在你的环境中设置 BRAVE_API_KEY。

Brave 提供免费套餐加付费计划；查看 Brave API 门户以了解当前的限制和定价。

在哪里设置 key（推荐）

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

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

使用 Perplexity（直连或通过 OpenRouter）

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

获取 OpenRouter API key

在 https://openrouter.ai/ 创建账户
添加积分（支持加密货币、预付费或信用卡）
在你的账户设置中生成 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-aware 默认值）
          baseUrl: "https://openrouter.ai/api/v1",
          // Model（默认为 perplexity/sonar-pro）
          model: "perplexity/sonar-pro"
        }
      }
    }
  }
}

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

如果未设置 base URL，OpenClaw 根据 API key 来源选择默认值：

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

可用的 Perplexity 模型

Model（模型）	Description（描述）	Best for（最适合）
perplexity/sonar	带网页搜索的快速 Q&A	快速查找
perplexity/sonar-pro（默认）	带网页搜索的多步推理	复杂问题
perplexity/sonar-reasoning-pro	思维链分析	深度研究

web_search

使用你配置的 provider 搜索网页。

要求

tools.web.search.enabled 不能为 false（默认：启用）
你选择的 provider 的 API key：
- 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）

示例：

// 德国特定搜索
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 并提取可读内容。

要求

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

配置

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

工具参数

url（必需，仅 http/https）
extractMode（markdown | text）
maxChars（截断长页面）

注意事项：

web_fetch 首先使用 Readability（主要内容提取），然后使用 Firecrawl（如果配置了）。如果两者都失败，工具返回错误。
Firecrawl 请求使用 bot-circumvention（反机器人规避）模式并默认缓存结果。
web_fetch 默认发送类 Chrome 的 User-Agent 和 Accept-Language；如果需要，覆盖 userAgent。
web_fetch 阻止私有/内部 hostnames 并重新检查 redirects（使用 maxRedirects 限制）。
web_fetch 是尽力而为的提取；某些站点需要浏览器工具。
有关 key 设置和服务详细信息，参见 Firecrawl。
响应被缓存（默认 15 分钟）以减少重复抓取。
如果你使用 tool profiles/allowlists（工具配置文件/允许列表），添加 web_search/web_fetch 或 group:web。
如果缺少 Brave key，web_search 返回带有文档链接的简短设置提示。

← 返回文档首页