Web 搜索

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

OpenClaw 还包括用于 X（前 Twitter）帖子的 x_search，以及用于轻量级 URL 抓取的 web_fetch。在这一阶段，web_fetch 保持本地运行，而 web_search 和 x_search 可以在底层使用 xAI Responses。

# 快速开始

openclaw configure --section web

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

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

# 选择提供商

# 提供商对比

# 自动检测

# 原生 OpenAI web search

当启用 OpenClaw 网页搜索且未固定托管提供商时，直接的 OpenAI Responses 模型会自动使用 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 会同时禁用托管搜索和原生搜索

{
  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、link-local 和 metadata 目标仍会被阻止。

这种自动放行不适用于任意 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）

之后是免密钥备用方案：

10. DuckDuckGo -- 免密钥 HTML 备用方案，无需账户或 API 密钥（顺序 100）
11. Ollama Web Search -- 通过你配置的本地 Ollama 主机提供免密钥备用方案，前提是该主机可访问且已使用 ollama signin 登录；当主机需要时可复用 Ollama provider bearer auth，并且在配置 OLLAMA_API_KEY 后可直接调用 https://ollama.com 搜索（顺序 110）
12. 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 key、基础 URL、模式）位于 plugins.entries.<plugin>.config.webSearch.* 下。Gemini 也可以在其专用 Web 搜索配置和 GEMINI_API_KEY 之后，以较低优先级复用 models.providers.google.apiKey 和 models.providers.google.baseUrl 作为回退。示例请参阅提供商页面。

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.*。它使用与 Grok Web 搜索相同的 XAI_API_KEY 回退。 旧版 tools.web.x_search.* 配置会由 openclaw doctor --fix 自动迁移。 当你在 openclaw onboard 或 openclaw configure --section web 期间选择 Grok 时，OpenClaw 也可以使用同一个 key 提供可选的 x_search 设置。 这是 Grok 路径中的一个独立后续步骤，不是单独的顶层 Web 搜索提供商选择。如果你选择其他提供商，OpenClaw 不会显示 x_search 提示。

# 存储 API key

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

export BRAVE_API_KEY="YOUR_KEY"

# 工具参数

# 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 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 参数

# 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 抓取 -- 抓取 URL 并提取可读内容
• Web 浏览器 -- 面向 JS 密集型站点的完整浏览器自动化
• Grok 搜索 -- 将 Grok 用作 web_search 提供商
• Ollama Web 搜索 -- 通过你的 Ollama 主机进行免 key Web 搜索