古法编程

Appearance

OpenClaw 的 web_search 支持 12 种网页搜索提供商，包括免 Key 的 DuckDuckGo 和自托管 SearXNG。未配置 provider 时按内置优先级自动检测第一个就绪提供商。x_search 可搜索 X 帖子，支持用户过滤和时间范围。Codex 模型可启用原生 Responses web_search，通过 tools.web.search.openaiCodex 配置。

OpenClaw 网页搜索配置：web_search、x_search 与提供商自动检测指南 ​

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

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

INFO

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" });

选择提供商 ​

Brave Search

结构化结果带摘要。支持 `llm-context` 模式、国家/语言过滤。提供免费套餐。

DuckDuckGo

免 Key 回退。无需 API Key。非官方 HTML 集成。

Exa

神经 + 关键词搜索，带内容提取（高亮、文本、摘要）。

Firecrawl

结构化结果。与 `firecrawl_search` 和 `firecrawl_scrape` 配合实现深层提取最佳。

Gemini

AI 综合答案 + 引用，通过 Google Search grounding。

Grok

AI 综合答案 + 引用，通过 xAI web grounding。

Kimi

AI 综合答案 + 引用，通过 Moonshot 网页搜索；未 grounding 的聊天兜底会明确失败。

MiniMax Search

通过 MiniMax Token Plan 搜索 API 获取结构化结果。

Ollama Web Search

通过已登录的本地 Ollama 主机或托管 Ollama API 搜索。

Perplexity

结构化结果，带内容提取控制和域名过滤。

SearXNG

自托管元搜索。无需 API Key。聚合 Google、Bing、DuckDuckGo 等。

Tavily

结构化结果，支持搜索深度、话题过滤和 `tavily_extract` 用于 URL 提取。

提供商对比 ​

提供商结果风格过滤器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 OAuth、XAI_API_KEY 或 plugins.entries.xai.config.webSearch.apiKey
KimiAI 综合 + 引用；未 grounding 的聊天兜底会明确失败--KIMI_API_KEY / MOONSHOT_API_KEY
MiniMax Search结构化摘要片段区域（global / cn）MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN
Ollama Web Search结构化摘要片段--已登录本地主机无需 Key；直接搜索 https://ollama.com 需 OLLAMA_API_KEY
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 / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY 或 plugins.entries.minimax.config.webSearch.apiKey（顺序 15）
  3. Gemini — plugins.entries.google.config.webSearch.apiKey、GEMINI_API_KEY 或 models.providers.google.apiKey（顺序 20）
  4. Grok — xAI OAuth、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；可选 plugins.entries.exa.config.webSearch.baseUrl 覆盖 Exa 端点（顺序 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 signin 登录；可复用 Ollama 提供商的 bearer 认证，配置 OLLAMA_API_KEY 后可直接搜索 https://ollama.com（顺序 110）
  3. SearXNG — SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（顺序 200）

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

INFO

所有提供商密钥字段支持 SecretRef 对象。插件级 SecretRef（plugins.entries.<plugin>.config.webSearch.apiKey）在内置 API 型 web 搜索提供商（包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity、Tavily）中会被解析，无论提供商标明是通过 tools.web.search.provider 明确选择还是通过自动检测选中。在自动检测模式下，OpenClaw 仅解析所选提供商的密钥——未选中的 SecretRef 保持非活动状态，因此你可以同时配置多个提供商而无需为未使用的提供商支付解析成本。

原生 OpenAI 网页搜索 ​

直接使用 OpenAI Responses 模型的流量在 OpenClaw 网页搜索启用且未锁定托管提供商时，会自动使用 OpenAI 托管的 web_search 工具。这是捆绑 OpenAI 插件中的提供商自有行为，仅适用于原生 OpenAI API 流量，不兼容 OpenAI 兼容代理 base URL 或 Azure 路由。将 tools.web.search.provider 设置为其他提供商（如 brave）可为 OpenAI 模型保留托管 web_search 工具，或将 tools.web.search.enabled: false 同时禁用托管搜索和原生 OpenAI 搜索。

原生 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 行为。

网络安全 ​

托管 web_search 提供商调用使用 OpenClaw 的受保护抓取路径。对于受信任的提供商 API 主机，OpenClaw 仅对该提供商主机名允许 Surge、Clash 和 sing-box fake-IP DNS 在 198.18.0.0/15 和 fc00::/7 范围内的回答。其他私有、回环、链路本地和元数据目的地仍被阻止。

此自动允许不适用于任意 web_fetch URL。对于 web_fetch，仅当你的受信任代理拥有这些合成范围时，才显式启用 tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange 和 tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange。

配置网页搜索 ​

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

提供商特定配置（API Key、基础 URL、模式）位于 plugins.entries.<plugin>.config.webSearch.* 下。Gemini 还可以在专用网页搜索配置和 GEMINI_API_KEY 之后，以较低优先级回退使用 models.providers.google.apiKey 和 models.providers.google.baseUrl。Grok 还可以使用来自 openclaw models auth login --provider xai --method oauth 的 xAI OAuth 认证配置文件；API Key 配置作为回退。

tools.web.search.provider 会对照捆绑和已安装插件声明中声明的网页搜索提供商 ID 进行验证。拼写错误（如 "brvae"）会导致配置验证失败，而非静默回退到自动检测。如果已配置的提供商仅有过期的插件证据（例如卸载第三方插件后残留 plugins.entries.<plugin> 块），OpenClaw 会在启动时保持韧性并报告警告，以便你重新安装插件或运行 openclaw doctor --fix 清理过期配置。

web_fetch 回退提供商选择是独立的：

  • 通过 tools.web.fetch.provider 选择
  • 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个就绪的 web-fetch 提供商
  • 非沙箱 web_fetch 可使用声明了 contracts.webFetchProviders 的已安装插件提供商；沙箱化抓取仅限捆绑提供商
  • 目前捆绑的 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.6）

x_search 配置在 plugins.entries.xai.config.xSearch.*。它使用与聊天相同的 xAI 认证配置文件，或 Grok 网页搜索使用的 XAI_API_KEY / 插件网页搜索凭证。旧版 tools.web.x_search.* 配置由 openclaw doctor --fix 自动迁移。当你在 openclaw onboard 或 openclaw configure --section web 时选择 Grok，OpenClaw 还可以提供可选的 x_search 设置（使用相同的凭证）。这是 Grok 路径内的独立后续步骤，而非单独的顶层网页搜索提供商选择。如果你选择其他提供商，OpenClaw 不会显示 x_search 提示。

存储 API Key ​

配置文件

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

json5
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_KEY", // pragma: allowlist secret
          },
        },
      },
    },
  },
}

环境变量

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

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）

WARNING

并非所有参数都适用于所有提供商。Brave llm-context 模式拒绝 ui_lang；date_before 还要求同时提供 date_after，因为 Brave 自定义时效范围需要开始和结束日期。Gemini、Grok 和 Kimi 返回一个带引用的综合答案，接受 count 参数以便兼容共享工具，但不改变 grounded 答案的形状。Gemini 支持 freshness、date_after 和 date_before，会将其转换为 Google Search grounding 时间范围。Perplexity 在使用 Sonar/OpenRouter 兼容路径（plugins.entries.perplexity.config.webSearch.baseUrl / model 或 OPENROUTER_API_KEY）时行为相同。SearXNG 仅对可信私有网络或回环主机接受 http://；公共 SearXNG 端点必须使用 https://。Firecrawl 和 Tavily 通过 web_search 仅支持 query 和 count——使用其专属工具获取高级选项。

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

INFO

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

x_search 配置 ​

json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            baseUrl: "https://api.x.ai/v1", // 可选，覆盖 webSearch.baseUrl
            inlineCitations: false,
            maxTurns: 2,
            timeoutSeconds: 30,
            cacheTtlMinutes: 15,
          },
          webSearch: {
            apiKey: "xai-...", // 如果已设置 xAI 认证配置文件或 XAI_API_KEY 则可选
            baseUrl: "https://api.x.ai/v1", // 可选，共享 xAI Responses base URL
          },
        },
      },
    },
  },
}

x_search 在设置 plugins.entries.xai.config.xSearch.baseUrl 时 POST 到 <baseUrl>/responses。如果该字段省略，则回退到 plugins.entries.xai.config.webSearch.baseUrl，然后是旧版 tools.web.search.grok.baseUrl，最后是公共 xAI 端点。

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）
  },
}

相关文档 ​

常见问题 ​

没有任何 API Key 能用 web_search 吗？ ​

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

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

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

x_search 需要单独的 API Key 吗？ ​

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

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

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