古法编程

Appearance

本页介绍 OpenClaw 的网页搜索工具体系。web_search 支持 12 种提供商（含无 Key 的 DuckDuckGo/SearXNG/Ollama），未配置 provider 时按优先级自动检测。新增 x_search 工具搜索 X（Twitter）帖子，支持用户过滤、时间范围和多媒体理解。Codex 模型可启用原生 Responses web_search 工具。所有提供商密钥字段支持 SecretRef 对象。

网页搜索（Web Search） ​

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

OpenClaw 还包括用于搜索 X（原 Twitter）帖子的 x_search 和用于轻量 URL 抓取的 web_fetch。

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

快速开始 ​

第一步：选择提供商

选择提供商并完成所需设置。有些提供商无需 Key，有些需要 API Key。详见下方提供商页面。

第二步：配置

bash
openclaw configure --section web

这会存储提供商和所需凭证。你也可以设置环境变量（如 BRAVE_API_KEY）跳过此步骤。

第三步：使用

代理现在可以调用 web_search：

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

搜索 X 帖子：

javascript
await x_search({ query: "dinner recipes" });

选择提供商 ​

提供商结果风格过滤器API Key
Brave结构化摘要片段国家、语言、时间、llm-context 模式BRAVE_API_KEY
DuckDuckGo结构化摘要片段—无（免 Key）
Exa结构化 + 提取神经/关键词模式、日期、内容提取EXA_API_KEY
Firecrawl结构化摘要片段通过 firecrawl_search 工具FIRECRAWL_API_KEY
GeminiAI 综合 + 引用—GEMINI_API_KEY
GrokAI 综合 + 引用—XAI_API_KEY
KimiAI 综合 + 引用—KIMI_API_KEY / MOONSHOT_API_KEY
MiniMax Search结构化摘要片段区域（global / cn）MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY
Ollama Web Search结构化摘要片段—无（需 ollama signin）
Perplexity结构化摘要片段国家、语言、时间、域名、内容限制PERPLEXITY_API_KEY / OPENROUTER_API_KEY
SearXNG结构化摘要片段分类、语言无（自托管）
Tavily结构化摘要片段通过 tavily_search 工具TAVILY_API_KEY

自动检测 ​

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

若未设置 provider，OpenClaw 按以下顺序检查提供商，使用第一个就绪的：

API 优先（有 Key 的）：

  1. Brave — BRAVE_API_KEY 或 plugins.entries.brave.config.webSearch.apiKey（顺序 10）
  2. MiniMax Search — MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY 或 plugins.entries.minimax.config.webSearch.apiKey（顺序 15）
  3. Gemini — GEMINI_API_KEY 或 plugins.entries.google.config.webSearch.apiKey（顺序 20）
  4. Grok — XAI_API_KEY 或 plugins.entries.xai.config.webSearch.apiKey（顺序 30）
  5. Kimi — KIMI_API_KEY / MOONSHOT_API_KEY 或 plugins.entries.moonshot.config.webSearch.apiKey（顺序 40）
  6. Perplexity — PERPLEXITY_API_KEY / OPENROUTER_API_KEY 或 plugins.entries.perplexity.config.webSearch.apiKey（顺序 50）
  7. Firecrawl — FIRECRAWL_API_KEY 或 plugins.entries.firecrawl.config.webSearch.apiKey（顺序 60）
  8. Exa — EXA_API_KEY 或 plugins.entries.exa.config.webSearch.apiKey（顺序 65）
  9. Tavily — TAVILY_API_KEY 或 plugins.entries.tavily.config.webSearch.apiKey（顺序 70）

免 Key 回退（按顺序）：

  1. DuckDuckGo — 无需账号或 API Key 的免 Key HTML 回退（顺序 100）
  2. Ollama Web Search — 通过配置的 Ollama 主机的免 Key 回退；需要 Ollama 可达且已用 ollama signin 登录（顺序 110）
  3. SearXNG — SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（顺序 200）

若未检测到任何提供商，回退到 Brave（你会收到缺少密钥的错误提示，引导你配置）。

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

Codex 原生网页搜索 ​

Codex 兼容模型可选择使用提供商原生的 Responses web_search 工具，而非 OpenClaw 管理的 web_search 函数。

  • 在 tools.web.search.openaiCodex 下配置
  • 仅对 Codex 兼容模型（openai-codex/* 或使用 api: "openai-codex-responses" 的提供商）激活
  • 管理的 web_search 仍适用于非 Codex 模型
  • mode: "cached" 是默认且推荐的设置
  • tools.web.search.enabled: false 同时禁用管理和原生搜索
json5
{
  tools: {
    web: {
      search: {
        enabled: true,
        openaiCodex: {
          enabled: true,
          mode: "cached",
          allowedDomains: ["example.com"],
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "New York",
            timezone: "America/New_York",
          },
        },
      },
    },
  },
}

若启用了原生 Codex 搜索但当前模型不兼容 Codex，OpenClaw 保持正常的管理 web_search 行为。

配置 ​

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

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

web_fetch 备用提供商选择是独立的：

  • 通过 tools.web.fetch.provider 选择
  • 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个就绪的 web-fetch 提供商
  • 目前捆绑的 web-fetch 提供商是 Firecrawl，配置在 plugins.entries.firecrawl.config.webFetch.*

当你在 openclaw onboard 或 openclaw configure --section web 时选择 Kimi，OpenClaw 还可以询问：

  • Moonshot API 区域（https://api.moonshot.ai/v1 或 https://api.moonshot.cn/v1）
  • 默认 Kimi web-search 模型（默认 kimi-k2.5）

x_search 配置在 plugins.entries.xai.config.xSearch.*，使用与 Grok 网页搜索相同的 XAI_API_KEY 回退。旧版 tools.web.x_search.* 配置由 openclaw doctor --fix 自动迁移。当你在 onboard 时选择 Grok，OpenClaw 可以提供可选的 x_search 设置（使用相同的 Key，在 Grok 路径内的独立后续步骤）。

存储 API Key ​

配置文件方式：

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

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

环境变量方式：

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

bash
export BRAVE_API_KEY="YOUR_KEY"

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

工具参数 ​

参数描述
query搜索查询（必填）
count返回结果数（1-10，默认：5）
country2 字母 ISO 国家代码（如 "US"、"DE"）
languageISO 639-1 语言代码（如 "en"、"de"）
search_lang搜索语言代码（仅限 Brave）
freshness时效过滤：day、week、month 或 year
date_after此日期后的结果（YYYY-MM-DD）
date_before此日期前的结果（YYYY-MM-DD）
ui_langUI 语言代码（仅限 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。Gemini、Grok 和 Kimi 返回一个带引用的综合答案，接受 count 参数但不改变返回形状。SearXNG 仅对可信私有网络或回环主机接受 http://；公共 SearXNG 端点必须使用 https://。Firecrawl 和 Tavily 通过 web_search 仅支持 query 和 count——使用其专属工具获取高级选项。

x_search 使用 xAI 查询 X（原 Twitter）帖子，返回带引用的 AI 综合答案。接受自然语言查询和可选的结构化过滤器。OpenClaw 仅在处理该工具调用的请求上启用内置 xAI x_search 工具。

xAI 文档记载 x_search 支持关键词搜索、语义搜索、用户搜索和帖子线程获取。对于每条帖子的互动数据（转发、回复、书签、浏览量），优先用精确帖子 URL 或状态 ID 进行定向查询。广泛关键词搜索可能找到正确帖子但返回不完整的每帖子元数据。推荐模式：先定位帖子，再用 x_search 精确查询该帖子。

x_search 配置 ​

json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            inlineCitations: false,
            maxTurns: 2,
            timeoutSeconds: 30,
            cacheTtlMinutes: 15,
          },
          webSearch: {
            apiKey: "xai-...", // 若已设置 XAI_API_KEY 则可选
          },
        },
      },
    },
  },
}

x_search 参数 ​

参数描述
query搜索查询（必填）
allowed_x_handles限制结果为特定 X 用户名
excluded_x_handles排除特定 X 用户名
from_date仅包含此日期及之后的帖子（YYYY-MM-DD）
to_date仅包含此日期及之前的帖子（YYYY-MM-DD）
enable_image_understanding让 xAI 分析匹配帖子附带的图片
enable_video_understanding让 xAI 分析匹配帖子附带的视频

x_search 示例 ​

javascript
await x_search({
  query: "dinner recipes",
  allowed_x_handles: ["nytfood"],
  from_date: "2026-03-01",
});
javascript
// 每帖子统计：尽可能用精确状态 URL 或状态 ID
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

示例 ​

javascript
// 基本搜索
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、x_search 或 group:web：

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

相关链接 ​

常见问题 ​

Q: 没有任何 API Key 能用 web_search 吗？

A: 可以。DuckDuckGo 是完全免 Key 的回退提供商（自动检测顺序 100），Ollama Web Search 也不需要付费 Key（但需要本地 Ollama 服务且执行过 ollama signin）。若你自托管 SearXNG，配置 SEARXNG_BASE_URL 也无需付费 Key。推荐新手先用 DuckDuckGo 体验，有需求再换 Brave 等付费提供商提升质量。

Q: Gemini/Grok/Kimi 的搜索结果和 Brave/Perplexity 有什么不同？

A: Gemini、Grok 和 Kimi 是 AI 综合型提供商——它们返回一段带引用的综合答案，而非多条搜索结果列表。Brave、Perplexity、Tavily 等是结构化结果型提供商，返回多条独立摘要片段，适合代理自行筛选处理。AI 综合型对"直接问答"场景更便捷，结构化型对"需要多源比对"场景更灵活。

Q: x_search 需要单独的 API Key 吗？

A: x_search 使用与 Grok 网页搜索相同的 XAI_API_KEY，无需额外申请。在 onboard 时选择 Grok 后，OpenClaw 会在 Grok 配置路径内提供可选的 x_search 设置步骤。若已配置 XAI_API_KEY，直接在配置中启用 plugins.entries.xai.config.xSearch.enabled: true 即可使用。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策