内置工具

Web 搜索

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

OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 x_search，以及用于轻量级 URL 获取的 web_fetch。在此阶段，web_fetch 保持本地执行，而 web_search 和 x_search 可以在底层使用 xAI Responses。

快速开始

选择提供商

选择一个提供商并完成任何必需的设置。有些提供商无需密钥，而另一些使用 API 密钥。详情请参阅下面的提供商页面。

配置

bash

openclaw configure --section web

这会存储提供商和任何所需凭证。你也可以设置环境变量（例如 BRAVE_API_KEY），并跳过 API 支持提供商的此步骤。

使用它

智能体现在可以调用 web_search：

javascript

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

对于 X 帖子，请使用：

javascript

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

选择提供商

Brave Search

带摘要片段的结构化结果。支持 llm-context 模式、国家/地区和语言筛选。提供免费层级。

DuckDuckGo

无需密钥的后备选项。无需 API 密钥。基于非官方 HTML 的集成。

Exa

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

Firecrawl

结构化结果。最适合与 firecrawl_search 和 firecrawl_scrape 搭配进行深度提取。

Gemini

通过 Google Search grounding 提供带引用的 AI 综合答案。

Grok

通过 xAI Web grounding 提供带引用的 AI 综合答案。

Kimi

通过 Moonshot Web 搜索提供带引用的 AI 综合答案；未 grounding 的聊天后备会显式失败。

MiniMax Search

通过 MiniMax Token Plan 搜索 API 提供结构化结果。

Ollama Web 搜索

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

Perplexity

带内容提取控制和域名筛选的结构化结果。

SearXNG

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

Tavily

结构化结果，支持搜索深度、主题筛选，以及用于 URL 提取的 tavily_extract。

提供商对比

提供商	结果样式	筛选器	API 密钥
Brave	结构化摘要片段	国家/地区、语言、时间、`llm-context` 模式	`BRAVE_API_KEY`
DuckDuckGo	结构化摘要片段	--	无（无需密钥）
Exa	结构化 + 已提取	神经/关键词模式、日期、内容提取	`EXA_API_KEY`
Firecrawl	结构化摘要片段	通过 `firecrawl_search` 工具	`FIRECRAWL_API_KEY`
Gemini	AI 综合 + 引用	--	`GEMINI_API_KEY`
Grok	AI 综合 + 引用	--	`XAI_API_KEY`
Kimi	AI 综合 + 引用；未 grounding 的聊天后备会失败	--	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
MiniMax Search	结构化摘要片段	区域（`global` / `cn`）	`MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN`
Ollama Web 搜索	结构化摘要片段	--	已登录本地主机无需；直接搜索 `https://ollama.com` 需 `OLLAMA_API_KEY`
Perplexity	结构化摘要片段	国家/地区、语言、时间、域名、内容限制	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`
SearXNG	结构化摘要片段	类别、语言	无（自托管）
Tavily	结构化摘要片段	通过 `tavily_search` 工具	`TAVILY_API_KEY`

自动检测

原生 OpenAI Web 搜索

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

原生 Codex Web 搜索

支持 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 的受保护 fetch 路径。对于受信任的提供商 API 主机，OpenClaw 仅针对该提供商主机名允许 Surge、Clash 和 sing-box 在 198.18.0.0/15 与 fc00::/7 范围内的 fake-IP DNS 响应。其他私有、loopback、链路本地和元数据目标仍会被阻止。

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

设置 Web 搜索

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

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

首先是 API 支持的提供商：

Brave -- BRAVE_API_KEY 或 plugins.entries.brave.config.webSearch.apiKey（顺序 10）
MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY 或 plugins.entries.minimax.config.webSearch.apiKey（顺序 15）
Gemini -- plugins.entries.google.config.webSearch.apiKey、GEMINI_API_KEY 或 models.providers.google.apiKey（顺序 20）
Grok -- XAI_API_KEY 或 plugins.entries.xai.config.webSearch.apiKey（顺序 30）
Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY 或 plugins.entries.moonshot.config.webSearch.apiKey（顺序 40）
Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY 或 plugins.entries.perplexity.config.webSearch.apiKey（顺序 50）
Firecrawl -- FIRECRAWL_API_KEY 或 plugins.entries.firecrawl.config.webSearch.apiKey（顺序 60）
Exa -- EXA_API_KEY 或 plugins.entries.exa.config.webSearch.apiKey；可选的 plugins.entries.exa.config.webSearch.baseUrl 会覆盖 Exa 端点（顺序 65）
Tavily -- TAVILY_API_KEY 或 plugins.entries.tavily.config.webSearch.apiKey（顺序 70）

之后是无需密钥的后备选项：

DuckDuckGo -- 无需账户或 API 密钥的无密钥 HTML 后备选项（顺序 100）
Ollama Web 搜索 -- 当你配置的本地 Ollama 主机可访问并已通过 ollama signin 登录时，通过它提供无需密钥的后备选项；当主机需要时可复用 Ollama 提供商 bearer 认证，并且在配置 OLLAMA_API_KEY 后可调用直接的 https://ollama.com 搜索（顺序 110）
SearXNG -- SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（顺序 200）

如果未检测到提供商，它会回退到 Brave（你会收到缺少密钥的错误，提示你配置一个）。

配置

json5

{  tools: {    web: {      search: {        enabled: true, // default: true        provider: "brave", // or omit for auto-detection        maxResults: 5,        timeoutSeconds: 30,        cacheTtlMinutes: 15,      },    },  },}

提供商专用配置（API 密钥、基础 URL、模式）位于 plugins.entries.<plugin>.config.webSearch.* 下。Gemini 还可以复用 models.providers.google.apiKey 和 models.providers.google.baseUrl，作为优先级较低的回退项，在其专用 Web 搜索配置和 GEMINI_API_KEY 之后使用。示例见提供商页面。

tools.web.search.provider 会根据内置和已安装插件清单声明的 Web 搜索提供商 ID 进行验证。像 "brvae" 这样的拼写错误会导致配置验证失败，而不是静默回退到自动检测。如果配置的提供商只有过期的插件证据，例如卸载第三方插件后残留的 plugins.entries.<plugin> 块，OpenClaw 会保持启动韧性并报告警告，方便你重新安装插件，或运行 openclaw doctor --fix 清理过期配置。

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

使用 tools.web.fetch.provider 选择它
或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个就绪的 Web 抓取提供商
非沙箱隔离的 web_fetch 可以使用声明了 contracts.webFetchProviders 的已安装插件提供商；沙箱隔离的抓取保持仅限内置
目前内置的 Web 抓取提供商是 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 搜索模型（默认为 kimi-k2.6）

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

存储 API 密钥

Config file

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

json5

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

Environment variable

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

bash

export BRAVE_API_KEY="YOUR_KEY"

对于 Gateway 网关安装，请将它放在 ~/.openclaw/.env 中。请参阅环境变量。

工具参数

参数	描述
`query`	搜索查询（必需）
`count`	要返回的结果数（1-10，默认：5）
`country`	2 字母 ISO 国家/地区代码（例如 “US”、“DE”）
`language`	ISO 639-1 语言代码（例如 “en”、“de”）
`search_lang`	搜索语言代码（仅 Brave）
`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）

Warning

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

x_search

x_search 使用 xAI 查询 X（原 Twitter）帖子，并返回带引用的 AI 综合答案。它接受自然语言查询和可选的结构化筛选条件。OpenClaw 仅在服务此工具调用的请求上启用内置 xAI 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", // optional, overrides webSearch.baseUrl            inlineCitations: false,            maxTurns: 2,            timeoutSeconds: 30,            cacheTtlMinutes: 15,          },          webSearch: {            apiKey: "xai-...", // optional if an xAI auth profile or XAI_API_KEY is set            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL          },        },      },    },  },}

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

x_search 参数

参数	描述
`query`	搜索查询（必需）
`allowed_x_handles`	将结果限制为特定 X handle
`excluded_x_handles`	排除特定 X handle
`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

// Per-post stats: use the exact status URL or status ID when possibleawait x_search({  query: "https://x.com/huntharo/status/1905678901234567890",});

示例

javascript

// Basic searchawait web_search({ query: "OpenClaw plugin SDK" }); // German-specific searchawait web_search({ query: "TV online schauen", country: "DE", language: "de" }); // Recent results (past week)await web_search({ query: "AI developments", freshness: "week" }); // Date rangeawait web_search({  query: "climate research",  date_after: "2024-01-01",  date_before: "2024-06-30",}); // Domain filtering (Perplexity only)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"],    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)  },}

Web 搜索

快速开始

选择提供商

配置

使用它

选择提供商

提供商对比

自动检测

原生 OpenAI Web 搜索

原生 Codex Web 搜索

网络安全

设置 Web 搜索

配置

存储 API 密钥

Config file

Environment variable

工具参数

x_search

x_search 配置

x_search 参数

x_search 示例

示例

工具配置档案

相关内容

Molty