Web search

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

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

快速开始

Choose a 提供商
选择一个提供商并完成任何所需的设置。某些提供商不需要密钥，而其他的则使用 API 密钥。详情请参阅下方的提供商页面。
Configure
Terminal window
```
openclaw configure --section web
```
这将存储提供商以及任何所需的凭据。您也可以设置环境变量（例如 BRAVE_API_KEY）并针对 API 支持的提供商跳过此步骤。

Use it

代理现在可以调用 web_search：

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

对于 X 帖子，使用：

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

Choosing a 提供商

Brave Search

包含片段的结构化结果。支持 llm-context 模式、国家/语言过滤器。提供免费层级。

DuckDuckGo

无需密钥的回退方案。不需要 API 密钥。基于 HTML 的非官方集成。

Exa

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

Firecrawl

结构化结果。最好与 firecrawl_search 和 firecrawl_scrape 配合使用以进行深度提取。

Gemini

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

Grok

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

Kimi

通过 Moonshot 网络搜索提供带有引用的 AI 综合答案；无依据的聊天回退会明确失败。

MiniMax Search

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

Ollama Web Search

通过已登录的本地 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 综合 + 引用；在无依据的聊天回退时失败	—	`KIMI_API_KEY` / `MOONSHOT_API_KEY`
MiniMax Search	结构化片段	区域 (`global` / `cn`)	`MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN`
Ollama Web Search	结构化片段	—	已登录本地主机无限制；直接 `https://ollama.com` 搜索需要 `OLLAMA_API_KEY`
Perplexity	结构化片段	国家、语言、时间、域名、内容限制	`PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY`
SearXNG	结构化片段	类别、语言	无（自托管）
Tavily	结构化片段	通过 `tavily_search` 工具	`TAVILY_API_KEY`

自动检测

原生 OpenAI 网络搜索

当启用 OpenClaw 网络搜索且未锁定受管提供商时，Direct OpenAI Responses 模型会自动使用 OpenAI 托管的 OpenAIOpenAIweb_searchOpenClawOpenAIOpenAIAPIOpenAI 工具。这是捆绑的 OpenAI 插件中属于提供商的行为，仅适用于原生 OpenAI API 流量，不适用于 OpenAI 兼容的代理基础 URL 或 Azure 路由。将 tools.web.search.provider 设置为其他提供商（例如 brave）以为 OpenAI 模型保留受管 web_searchOpenAI 工具，或者设置 tools.web.search.enabled: falseOpenAI 以同时禁用受管搜索和原生 OpenAI 搜索。

原生 Codex 网络搜索

具备 Codex 功能的模型可以选择使用提供商原生的 Responses web_searchOpenClaw 工具，而不是 OpenClaw 的受管 web_search 函数。

在 tools.web.search.openaiCodex 下进行配置
它仅对具备 Codex 功能的模型激活（openai-codex/* 或使用 api: "openai-codex-responses" 的提供商）
受管 web_search 仍适用于非 Codex 模型
mode: "cached" 是默认设置也是推荐设置
tools.web.search.enabled: false 会同时禁用受管搜索和原生搜索

{
  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 将保持正常的受管 OpenClawweb_search 行为。

网络安全

受管 web_searchOpenClawAPIOpenClaw 提供商调用使用 OpenClaw 的防护获取路径。对于受信任的提供商 API 主机，OpenClaw 仅允许针对该提供商主机名在 198.18.0.0/15 和 fc00::/7 中使用 Surge、Clash 和 sing-box 的假 IP DNS 应答。其他私有、环回、链路本地和元数据目标仍然被阻止。

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

设置网络搜索

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

如果未设置 providerOpenClaw，OpenClaw 将按以下顺序检查提供商并使用第一个准备就绪的提供商：

首先是支持 API 的提供商：

Brave — BraveBRAVE_API_KEY 或 plugins.entries.brave.config.webSearch.apiKey（顺序 10）
MiniMax Search — MiniMaxMINIMAX_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 — PerplexityPERPLEXITY_API_KEY / OPENROUTER_API_KEY 或 plugins.entries.perplexity.config.webSearch.apiKey（顺序 50）
Firecrawl — FirecrawlFIRECRAWL_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 Search — 当配置的本地 Ollama 主机可达并使用 OllamaOllamaollama signinOllama 登录时，无需密钥的回退选项；当主机需要时，可以重用 Ollama 提供商的 bearer auth，并且在配置了 OLLAMA_API_KEY 时可以调用直接的 https://ollama.com 搜索（顺序 110）
SearXNG — SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（顺序 200）

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

配置

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

特定于提供商的配置（API 密钥、基础 URL、模式）位于 APIplugins.entries.<plugin>.config.webSearch.* 下。Gemini 还可以重用 models.providers.google.apiKey 和 models.providers.google.baseUrl 作为其专用 Web 搜索配置和 GEMINI_API_KEY 之后的较低优先级回退选项。请参阅提供商页面以获取示例。

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

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

通过 tools.web.fetch.provider 进行选择
或者省略该字段，让 OpenClaw 从可用的凭据中自动检测第一个就绪的网络获取提供商
非沙箱隔离的 web_fetch 可以使用声明了 contracts.webFetchProviders 的已安装插件提供商；沙箱隔离的获取操作则仅限于内置功能
目前内置的网络获取提供商是 Firecrawl，配置在 plugins.entries.firecrawl.config.webFetch.* 下

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

Moonshot API API 区域（https://api.moonshot.ai/v1 或 https://api.moonshot.cn/v1）
默认的 Kimi 网络搜索模型（默认为 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 webOpenClaw 期间选择 Grok 时， OpenClaw 还可以使用相同的密钥提供可选的 x_searchOpenClaw 设置。这是 Grok 路径中的一个独立后续步骤，而不是一个单独的顶级网络搜索提供商选择。如果您选择其他提供商，OpenClaw 将不会显示 x_search 提示。

存储 API 密钥

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

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

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

export BRAVE_API_KEY="YOUR_KEY"

对于网关安装，请将其放入 ~/.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 搜索基于事实的时间范围。当您使用 Sonar/Perplexity 兼容性路径（plugins.entries.perplexity.config.webSearch.baseUrl / model 或 OPENROUTER_API_KEY）时，OpenRouter 的行为方式相同。 SearXNG 仅接受受信任的专用网络或环回主机的 http://；公共 SearXNG 端点必须使用 https://。 Firecrawl 和 Tavily 仅通过 web_search 支持 query 和 count — 如需高级选项，请使用它们专用工具。

x_search

x_search 使用 xAI 查询 X（前 Twitter）帖子并返回带有引用的 AI 合成答案。它接受自然语言查询和可选的结构化筛选器。OpenClaw 仅在服务于此工具调用的请求上启用内置的 xAI x_search 工具。

x_search 配置

{
  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 用户名
`excluded_x_handles`	排除特定的 X 用户名
`from_date`	仅包含此日期及之后的帖子 (YYYY-MM-DD)
`to_date`	仅包含此日期及之前的帖子 (YYYY-MM-DD)
`enable_image_understanding`	允许 xAI 检查匹配帖子中附加的图片
`enable_video_understanding`	允许 xAI 检查匹配帖子中附加的视频

x_search 示例

await x_search({
  query: "dinner recipes",
  allowed_x_handles: ["nytfood"],
  from_date: "2026-03-01",
});

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

示例

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

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await 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：

{
  tools: {
    allow: ["web_search", "x_search"],
    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)
  },
}