网页搜索（Web Search）

web_search 工具使用你配置的提供商搜索网页并返回结果。结果按查询缓存 15 分钟（可配置）。

web_search 是轻量级 HTTP 工具，不是浏览器自动化。对于 JS 密集型站点或需要登录的页面，请使用 Web 浏览器。对于获取特定 URL，请使用 Web Fetch。

快速开始

第一步：获取 API Key

选择提供商并获取 API Key，各提供商页面有注册链接。

第二步：配置

openclaw configure --section web

这会存储密钥并设置提供商。你也可以设置环境变量（如 BRAVE_API_KEY）跳过此步骤。

第三步：使用

代理现在可以调用 web_search：

await web_search({ query: "OpenClaw plugin SDK" });

选择提供商

提供商	结果风格	过滤器	API Key
Brave	结构化摘要片段	国家、语言、时间、llm-context 模式	BRAVE_API_KEY
DuckDuckGo	结构化摘要片段	—	无（免 Key）
Exa	结构化 + 提取	神经/关键词模式、日期、内容提取	EXA_API_KEY
Firecrawl	结构化摘要片段	通过 firecrawl_search 工具	FIRECRAWL_API_KEY
Gemini	AI 综合 + 引用	—	GEMINI_API_KEY
Grok	AI 综合 + 引用	—	XAI_API_KEY
Kimi	AI 综合 + 引用	—	KIMI_API_KEY / MOONSHOT_API_KEY
Perplexity	结构化摘要片段	国家、语言、时间、域名、内容限制	PERPLEXITY_API_KEY / OPENROUTER_API_KEY
Tavily	结构化摘要片段	通过 tavily_search 工具	TAVILY_API_KEY

自动检测

提供商列表在文档和设置流程中按字母顺序排列，自动检测使用单独的优先级顺序：

若未设置 provider，OpenClaw 按以下顺序检查 API Key，使用第一个找到的：

1. Brave — BRAVE_API_KEY 或 plugins.entries.brave.config.webSearch.apiKey
2. Gemini — GEMINI_API_KEY 或 plugins.entries.google.config.webSearch.apiKey
3. Grok — XAI_API_KEY 或 plugins.entries.xai.config.webSearch.apiKey
4. Kimi — KIMI_API_KEY / MOONSHOT_API_KEY 或 plugins.entries.moonshot.config.webSearch.apiKey
5. Perplexity — PERPLEXITY_API_KEY / OPENROUTER_API_KEY 或 plugins.entries.perplexity.config.webSearch.apiKey
6. Firecrawl — FIRECRAWL_API_KEY 或 plugins.entries.firecrawl.config.webSearch.apiKey
7. Tavily — TAVILY_API_KEY 或 plugins.entries.tavily.config.webSearch.apiKey

若未找到任何 Key，回退到 Brave（你会收到缺少密钥的错误提示）。

所有提供商密钥字段支持 SecretRef 对象。在自动检测模式下，OpenClaw 仅解析所选提供商的密钥——未选中的 SecretRef 保持非活动状态。

配置

{
  tools: {
    web: {
      search: {
        enabled: true, // 默认：true
        provider: "brave", // 或省略以自动检测
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

提供商特定配置（API Key、基础 URL、模式）位于 plugins.entries.<plugin>.config.webSearch.* 下，详见各提供商页面。

存储 API Key

配置文件方式：

运行 openclaw configure --section web 或直接设置密钥：

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_KEY",
          },
        },
      },
    },
  },
}

环境变量方式：

在网关进程环境中设置提供商环境变量：

export BRAVE_API_KEY="YOUR_KEY"

对于网关安装，将其放入 ~/.openclaw/.env。

工具参数

参数	描述
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）

并非所有参数都适用于所有提供商。Brave llm-context 模式拒绝 ui_lang、freshness、date_after 和 date_before。Firecrawl 和 Tavily 通过 web_search 仅支持 query 和 count——使用其专属工具获取高级选项。

示例

// 基本搜索
await web_search({ query: "OpenClaw plugin SDK" });

// 德语特定搜索
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// 最近结果（过去一周）
await web_search({ query: "AI developments", freshness: "week" });

// 日期范围
await web_search({
  query: "climate research",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// 域名过滤（仅限 Perplexity）
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

工具配置文件

若使用工具配置文件或白名单，添加 web_search 或 group:web：

{
  tools: {
    allow: ["web_search"],
    // 或：allow: ["group:web"]（包含 web_search 和 web_fetch）
  },
}

相关链接

• Web Fetch——获取 URL 并提取可读内容
• Web 浏览器——用于 JS 密集型站点的完整浏览器自动化