跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

web_search 工具会使用你配置的提供商搜索网页并返回结果。结果会按查询缓存 15 分钟（可配置）。 OpenClaw 还包含用于 X（原 Twitter）帖子的 x_search，以及用于轻量级 URL 获取的 web_fetch。在此阶段，web_fetch 保持本地执行，而 web_search 和 x_search 可以在底层使用 xAI Responses。
web_search 是轻量级 HTTP 工具，不是浏览器自动化。对于 大量依赖 JS 的网站或登录场景，请使用 Web Browser。对于 获取特定 URL，请使用 Web Fetch。

​
快速开始

1

Choose a provider

选择一个提供商并完成所有必需设置。一些提供商 无需密钥，而其他提供商使用 API key。详情请参见下方的 提供商页面。
2

Configure

openclaw configure --section web
这会存储提供商以及任何需要的凭证。你也可以设置环境变量 （例如 BRAVE_API_KEY），并对 API 支持的 提供商跳过此步骤。
3

Use it

智能体现在可以调用 web_search：
await web_search({ query: "OpenClaw plugin SDK" });
对于 X 帖子，请使用：
await x_search({ query: "dinner recipes" });

​
选择提供商

Brave Search

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

DuckDuckGo

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

Exa

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

Firecrawl

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

Gemini

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

Grok

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

Kimi

通过 Moonshot web search 提供带引用的 AI 综合答案；未 grounding 的聊天回退会明确失败。

MiniMax Search

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

Ollama Web Search

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

Perplexity

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

SearXNG

自托管元搜索。不需要 API key。聚合 Google、Bing、DuckDuckGo 等。

Tavily

带搜索深度、主题筛选和用于 URL 提取的 tavily_extract 的结构化结果。

​
提供商对比

提供商结果样式筛选API key
Brave结构化片段国家、语言、时间、llm-context 模式BRAVE_API_KEY
DuckDuckGo结构化片段—无（无需密钥）
Exa结构化 + 已提取内容神经/关键词模式、日期、内容提取EXA_API_KEY
Firecrawl结构化片段通过 firecrawl_search 工具FIRECRAWL_API_KEY
GeminiAI 综合答案 + 引用—GEMINI_API_KEY
GrokAI 综合答案 + 引用—XAI_API_KEY
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结构化片段—已登录的本地主机无需；直接 https://ollama.com 搜索使用 OLLAMA_API_KEY
Perplexity结构化片段国家、语言、时间、域名、内容限制PERPLEXITY_API_KEY / OPENROUTER_API_KEY
SearXNG结构化片段类别、语言无（自托管）
Tavily结构化片段通过 tavily_search 工具TAVILY_API_KEY

​
自动检测

当 OpenClaw web search 已启用且未固定托管提供商时，直接的 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 的模型可以选择使用提供商原生 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 会同时停用托管搜索和原生搜索
{
  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 fake-IP DNS 应答中的 198.18.0.0/15 和 fc00::/7，但仅限该提供商主机名。 其他私有、loopback、link-local 和元数据目标仍会被阻止。 此自动放行不适用于任意 web_fetch URL。对于 web_fetch，仅当你的受信任代理拥有这些合成地址范围时，才显式启用 tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange 和 tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange。 文档和设置流程中的提供商列表按字母顺序排列。自动检测保留 单独的优先级顺序。 如果未设置 provider，OpenClaw 会按以下顺序检查提供商，并使用 第一个已就绪的提供商： 先检查 API 支持的提供商：
  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_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）
之后是无需密钥的回退方案：
  1. DuckDuckGo — 无需账号或 API key 的免密钥 HTML 回退方案（顺序 100）
  2. Ollama Web Search — 当你配置的本地 Ollama 主机可访问且已通过 ollama signin 登录时，通过该主机提供无需密钥的回退；当主机需要时可复用 Ollama 提供商 bearer 认证，并且在配置 OLLAMA_API_KEY 后可调用直接 https://ollama.com 搜索（顺序 110）
  3. SearXNG — SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（顺序 200）
如果未检测到提供商，它会回退到 Brave（你将收到缺少密钥的 错误，提示你配置一个）。
所有提供商密钥字段都支持 SecretRef 对象。 plugins.entries.<plugin>.config.webSearch.apiKey 下插件作用域的 SecretRef 会为内置的 API 支持 web search 提供商解析，包括 Brave、Exa、Firecrawl、 Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily， 无论提供商是通过 tools.web.search.provider 显式选择， 还是通过自动检测选择。在自动检测模式下，OpenClaw 只会解析 所选提供商密钥 — 未选中的 SecretRef 保持非活动状态，因此你可以 配置多个提供商，而无需为未使用的提供商支付解析成本。

​
配置

{
  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 之后优先级较低的 fallback。示例请参见提供商页面。 tools.web.search.provider 会根据内置和已安装插件清单声明的 Web 搜索提供商 ID 进行验证。像 "brvae" 这样的拼写错误会导致配置验证失败，而不是静默 fallback 到自动检测。如果已配置的提供商只有过时的插件证据，例如卸载第三方插件后遗留的 plugins.entries.<plugin> 块，OpenClaw 会保持启动韧性并报告警告，这样你可以重新安装插件，或运行 openclaw doctor --fix 清理过时配置。 web_fetch fallback 提供商选择是独立的：
  • 使用 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.*。它使用与 Grok Web 搜索相同的 XAI_API_KEY fallback。 旧版 tools.web.x_search.* 配置会由 openclaw doctor --fix 自动迁移。 当你在 openclaw onboard 或 openclaw configure --section web 期间选择 Grok 时，OpenClaw 还可以用相同密钥提供可选的 x_search 设置。 这是 Grok 路径内的一个独立后续步骤，不是单独的顶层 Web 搜索提供商选项。如果你选择其他提供商，OpenClaw 不会显示 x_search 提示。

​
存储 API 密钥

运行 openclaw configure --section web，或直接设置密钥：
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_KEY", // pragma: allowlist secret
          },
        },
      },
    },
  },
}

​
工具参数

参数描述
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；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 仅对受信任的私有网络或 local loopback 主机接受 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 配置

{
  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 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 发帖。如果省略该字段，它会 fallback 到 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)
  },
}

​
相关内容

  • Web Fetch — 抓取 URL 并提取可读内容
  • Web Browser — 面向 JS 密集型站点的完整浏览器自动化
  • Grok Search — 将 Grok 作为 web_search 提供商
  • Ollama Web 搜索 — 通过你的 Ollama 主机进行免密钥 Web 搜索