OpenClaw从入门到应用——工具（Tools）：网络搜索工具

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》OpenClaw 内置了两个轻量级的网络工具web_search— 使用 Brave Search API、带 Google Search grounding 的 Gemini、Grok、Kimi 或 Perplexity Search API 搜索网络。web_fetch— HTTP 获取 可读内容提取HTML → markdown/文本。这些工具并非浏览器自动化工具。对于重度依赖 JavaScript 的网站或需要登录的场景请使用浏览器工具。工作原理web_search调用您配置的服务商并返回结果。结果按查询缓存 15 分钟可配置。web_fetch执行简单的 HTTP GET 请求并提取可读内容HTML → markdown/文本。它不会执行 JavaScript。web_fetch默认处于启用状态除非明确禁用。有关特定服务商的详细信息请参阅 Brave Search 设置 和 Perplexity Search 设置。选择搜索服务商服务商结果形态服务商特定过滤器备注API 密钥Brave Search API带有摘要的结构化结果country、language、ui_lang、时间支持 Bravellm-context模式BRAVE_API_KEYGeminiAI 合成的答案 引用来源—使用 Google Search groundingGEMINI_API_KEYGrokAI 合成的答案 引用来源—使用 xAI 网络接地响应XAI_API_KEYKimiAI 合成的答案 引用来源—使用 Moonshot 网络搜索KIMI_API_KEY/MOONSHOT_API_KEYPerplexity 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配置如果未找到任何密钥将回退到 Brave您将收到一个缺少密钥的错误提示您进行配置。运行时 SecretRef 行为网络工具的 SecretRef 在网关启动/重载时原子性地解析。在自动检测模式下OpenClaw 仅解析所选服务商的密钥。未选中服务商的 SecretRef 保持非活动状态直到被选中。如果所选服务商的 SecretRef 未解析且没有服务商环境变量作为后备启动/重载将快速失败。设置网络搜索使用openclaw configure --section web来设置您的 API 密钥并选择服务商。Brave Search在 brave.com/search/api 创建一个 Brave Search API 帐户。在仪表板中选择Search套餐并生成一个 API 密钥。运行openclaw configure --section web将密钥存储在配置中或在您的环境中设置BRAVE_API_KEY。每个 Brave 套餐每月包含$5 的免费额度续期。Search套餐每 1,000 次请求花费 $5因此该额度涵盖每月 1,000 次查询。在Brave 仪表板中设置您的用量限制以避免意外扣费。请参阅Brave API 门户 了解当前套餐和定价。Perplexity Search在 perplexity.ai/settings/api 创建一个 Perplexity 帐户。在仪表板中生成一个 API 密钥。运行openclaw configure --section web将密钥存储在配置中或在您的环境中设置PERPLEXITY_API_KEY。对于旧版 Sonar/OpenRouter 兼容性请设置OPENROUTER_API_KEY代替或使用sk-or-...密钥配置tools.web.search.perplexity.apiKey。设置tools.web.search.perplexity.baseUrl或model也会使 Perplexity 回退到聊天补全兼容路径。有关更多详细信息请参阅 Perplexity Search API 文档。密钥的存储位置通过配置运行openclaw configure --section web。它会将密钥存储在服务商特定的配置路径下Brave:tools.web.search.apiKeyGemini:tools.web.search.gemini.apiKeyGrok:tools.web.search.grok.apiKeyKimi:tools.web.search.kimi.apiKeyPerplexity:tools.web.search.perplexity.apiKey所有这些字段也支持 SecretRef 对象。通过环境变量在网关进程环境中设置服务商环境变量Brave:BRAVE_API_KEYGemini:GEMINI_API_KEYGrok:XAI_API_KEYKimi:KIMI_API_KEY或MOONSHOT_API_KEYPerplexity:PERPLEXITY_API_KEY或OPENROUTER_API_KEY对于网关安装请将这些内容放入~/.openclaw/.env或您的服务环境中。请参阅 环境变量。配置示例Brave Search{ tools: { web: { search: { enabled: true, provider: brave, apiKey: YOUR_BRAVE_API_KEY, // 如果已设置 BRAVE_API_KEY则为可选 // pragma: allowlist secret }, }, }, }Brave LLM Context 模式{ tools: { web: { search: { enabled: true, provider: brave, apiKey: YOUR_BRAVE_API_KEY, // 如果已设置 BRAVE_API_KEY则为可选 // 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-..., // 如果已设置 PERPLEXITY_API_KEY则为可选 }, }, }, }, }通过 OpenRouter / Sonar 兼容性使用 Perplexity{ tools: { web: { search: { enabled: true, provider: perplexity, perplexity: { apiKey: openrouter-api-key, // 如果已设置 OPENROUTER_API_KEY则为可选 baseUrl: https://openrouter.ai/api/v1, model: perplexity/sonar-pro, }, }, }, }, }使用 Gemini (Google Search grounding)Gemini 模型支持内置的 Google Search grounding它会返回由实时 Google 搜索结果支持、并附带引用来源的 AI 合成答案。获取 Gemini API 密钥前往 Google AI Studio创建一个 API 密钥在网关环境中设置GEMINI_API_KEY或配置tools.web.search.gemini.apiKey设置 Gemini 搜索{ tools: { web: { search: { provider: gemini, gemini: { // API 密钥如果已设置 GEMINI_API_KEY则为可选 apiKey: AIza..., // 模型默认为 gemini-2.5-flash model: gemini-2.5-flash, }, }, }, }, }环境变量替代方案在网关环境中设置GEMINI_API_KEY。对于网关安装请将其放入~/.openclaw/.env。注意事项Gemini 背景信息grounding返回的引用 URL 会自动从 Google 的重定向 URL 解析为直接 URL。重定向解析在返回最终引用 URL 之前使用 SSRF 防护路径HEAD 重定向检查 http/https 验证。重定向解析使用严格的 SSRF 默认设置因此会阻止指向私有/内部目标的重定向。默认模型gemini-2.5-flash速度快且性价比高。任何支持背景信息grounding的 Gemini 模型都可以使用。web_search使用您配置的服务商搜索网络。要求tools.web.search.enabled不能为false默认启用您所选服务商的 API 密钥Brave:BRAVE_API_KEY或tools.web.search.apiKeyGemini:GEMINI_API_KEY或tools.web.search.gemini.apiKeyGrok:XAI_API_KEY或tools.web.search.grok.apiKeyKimi:KIMI_API_KEY、MOONSHOT_API_KEY或tools.web.search.kimi.apiKeyPerplexity:PERPLEXITY_API_KEY、OPENROUTER_API_KEY或tools.web.search.perplexity.apiKey以上所有服务商密钥字段均支持 SecretRef 对象。配置{ tools: { web: { search: { enabled: true, apiKey: BRAVE_API_KEY_HERE, // 如果已设置 BRAVE_API_KEY则为可选 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-...密钥那么仅限 Search API 使用的过滤器将返回明确的错误。参数描述query搜索查询必需count返回的结果数量1-10默认5country2 个字母的 ISO 国家代码例如 “US”、“DE”languageISO 639-1 语言代码例如 “en”、“de”freshness时间过滤器day、week、month或yeardate_after此日期之后的结果 (YYYY-MM-DD)date_before此日期之前的结果 (YYYY-MM-DD)ui_langUI 语言代码仅限 Bravedomain_filter域名允许/拒绝列表数组仅限 Perplexitymax_tokens总内容预算默认 25000仅限 Perplexitymax_tokens_per_page每页令牌限制默认 2048仅限 Perplexity示例// 德语特定搜索awaitweb_search({query:TV online schauen,country:DE,language:de,});// 近期结果过去一周awaitweb_search({query:TMBG interview,freshness:week,});// 日期范围搜索awaitweb_search({query:AI developments,date_after:2024-01-01,date_before:2024-06-30,});// 域名过滤仅限 Perplexityawaitweb_search({query:climate research,domain_filter:[nature.com,science.org,.edu],});// 排除域名仅限 Perplexityawaitweb_search({query:product reviews,domain_filter:[-reddit.com,-pinterest.com],});// 更多内容提取仅限 Perplexityawaitweb_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, // 如果已设置 FIRECRAWL_API_KEY则为可选 baseUrl: https://api.firecrawl.dev, onlyMainContent: true, maxAgeMs: 86400000, // 毫秒1 天 timeoutSeconds: 60, }, }, }, }, }web_fetch 工具参数url必需仅限 http/httpsextractModemarkdown|textmaxChars截断过长的页面注意事项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是尽力而为的提取某些网站可能需要使用浏览器工具。有关密钥设置和服务详情请参阅 Firecrawl。响应将被缓存默认 15 分钟以减少重复获取。如果您使用工具配置文件/允许列表请添加web_search/web_fetch或group:web。如果缺少 API 密钥web_search会返回一个简短的设置提示及文档链接。