diff --git a/docs/zh-CN/tools/brave-search.md b/docs/zh-CN/tools/brave-search.md index a201b6c4e..85c6e6d96 100644 --- a/docs/zh-CN/tools/brave-search.md +++ b/docs/zh-CN/tools/brave-search.md @@ -1,16 +1,16 @@ --- read_when: - - 你想将 Brave Search 用于 `web_search` - - 你需要 `BRAVE_API_KEY` 或套餐详情 -summary: 用于 `web_search` 的 Brave Search API 设置 + - 你想使用 Brave Search 进行 web_search + - 你需要 BRAVE_API_KEY 或套餐详细信息 +summary: 用于 web_search 的 Brave Search API 设置 title: Brave 搜索 x-i18n: - generated_at: "2026-04-24T02:51:57Z" - model: gpt-5.4 + generated_at: "2026-05-02T03:43:37Z" + model: gpt-5.5 provider: openai - source_hash: 0a59df7a5d52f665673b82b76ec9dce7ca34bf4e7b678029f6f7f7c5340c173b + source_hash: d5b6624d078ba55e30fbac4dd863a0d016e2e8d160e32bcc406e5070998241ba source_path: tools/brave-search.md - workflow: 15 + workflow: 16 --- # Brave Search API @@ -20,7 +20,7 @@ OpenClaw 支持将 Brave Search API 作为 `web_search` 提供商。 ## 获取 API 密钥 1. 在 [https://brave.com/search/api/](https://brave.com/search/api/) 创建 Brave Search API 账户 -2. 在控制台中，选择 **Search** 套餐并生成 API 密钥。 +2. 在仪表板中，选择 **Search** 套餐并生成 API 密钥。 3. 将密钥存储在配置中，或在 Gateway 网关环境中设置 `BRAVE_API_KEY`。 ## 配置示例 @@ -51,13 +51,13 @@ OpenClaw 支持将 Brave Search API 作为 `web_search` 提供商。 } ``` -提供商专用的 Brave 搜索设置现在位于 `plugins.entries.brave.config.webSearch.*` 下。 -旧版的 `tools.web.search.apiKey` 仍会通过兼容层加载，但它不再是规范的配置路径。 +Brave 专用的搜索设置现在位于 `plugins.entries.brave.config.webSearch.*` 下。 +旧版 `tools.web.search.apiKey` 仍会通过兼容性 shim 加载，但它不再是规范配置路径。 -`webSearch.mode` 用于控制 Brave 传输方式： +`webSearch.mode` 控制 Brave 传输方式： -- `web`（默认）：标准的 Brave 网页搜索，返回标题、URL 和摘要 -- `llm-context`：Brave LLM Context API，返回预先提取的文本块和来源以用于依据支撑 +- `web`（默认）：普通 Brave 网页搜索，包含标题、URL 和摘要片段 +- `llm-context`：Brave LLM Context API，包含预提取的文本块和用于依据溯源的来源 ## 工具参数 @@ -66,15 +66,15 @@ OpenClaw 支持将 Brave Search API 作为 `web_search` 提供商。 -返回结果数量（1–10）。 +返回的结果数量（1–10）。 -2 位 ISO 国家代码（例如 `US`、`DE`）。 +2 字母 ISO 国家/地区代码（例如 `US`、`DE`）。 -搜索结果使用的 ISO 639-1 语言代码（例如 `en`、`de`、`fr`）。 +搜索结果的 ISO 639-1 语言代码（例如 `en`、`de`、`fr`）。 @@ -82,11 +82,11 @@ Brave 搜索语言代码（例如 `en`、`en-gb`、`zh-hans`）。 -UI 元素使用的 ISO 语言代码。 +UI 元素的 ISO 语言代码。 -时间过滤器——`day` 表示 24 小时。 +时间筛选器 — `day` 表示 24 小时。 @@ -121,18 +121,18 @@ await web_search({ }); ``` -## 注意事项 +## 备注 -- OpenClaw 使用 Brave **Search** 套餐。如果你使用的是旧版订阅（例如最初每月 2,000 次查询的免费套餐），它仍然有效，但不包含 LLM Context 或更高限速等较新功能。 -- 每个 Brave 套餐都包含 **每月 5 美元的免费额度**（按月续期）。Search 套餐的费用是每 1,000 次请求 5 美元，因此该额度可覆盖每月 1,000 次查询。请在 Brave 控制台中设置使用上限，以避免产生意外费用。当前套餐信息请参阅 [Brave API 门户](https://brave.com/search/api/)。 -- Search 套餐包含 LLM Context 端点和 AI 推理权利。若要存储结果以训练或微调模型，则需要具有明确存储权利的套餐。请参阅 Brave 的 [服务条款](https://api-dashboard.search.brave.com/terms-of-service)。 -- `llm-context` 模式返回有依据支撑的来源条目，而不是常规网页搜索摘要结构。 -- `llm-context` 模式不支持 `ui_lang`、`freshness`、`date_after` 或 `date_before`。 +- OpenClaw 使用 Brave **Search** 套餐。如果你有旧版订阅（例如原始 Free 套餐，每月 2,000 次查询），它仍然有效，但不包含 LLM Context 或更高速率限制等较新功能。 +- 每个 Brave 套餐都包含**每月 \$5 免费额度**（会续期）。Search 套餐每 1,000 次请求收费 \$5，因此该额度可覆盖每月 1,000 次查询。请在 Brave 仪表板中设置你的用量限制，以避免意外收费。有关当前套餐，请参阅 [Brave API 门户](https://brave.com/search/api/)。 +- Search 套餐包含 LLM Context 端点和 AI 推理权利。若要存储结果以训练或调优模型，需要具有明确存储权利的套餐。请参阅 Brave [服务条款](https://api-dashboard.search.brave.com/terms-of-service)。 +- `llm-context` 模式返回基于依据溯源的来源条目，而不是普通网页搜索摘要片段格式。 +- `llm-context` 模式支持 `freshness` 和有边界的 `date_after` + `date_before` 范围。它不支持 `ui_lang`；不带 `date_after` 的 `date_before` 会被拒绝，因为 Brave 要求自定义新鲜度范围同时包含开始日期和结束日期。 - `ui_lang` 必须包含区域子标签，例如 `en-US`。 -- 结果默认缓存 15 分钟（可通过 `cacheTtlMinutes` 配置）。 +- 默认情况下，结果会缓存 15 分钟（可通过 `cacheTtlMinutes` 配置）。 ## 相关内容 -- [Web Search 概览](/zh-CN/tools/web) -- 所有提供商和自动检测 +- [网页搜索概览](/zh-CN/tools/web) -- 所有提供商和自动检测 - [Perplexity Search](/zh-CN/tools/perplexity-search) -- 带域名过滤的结构化结果 - [Exa Search](/zh-CN/tools/exa-search) -- 带内容提取的神经搜索 diff --git a/docs/zh-CN/tools/web.md b/docs/zh-CN/tools/web.md index d756142d6..3db3aca31 100644 --- a/docs/zh-CN/tools/web.md +++ b/docs/zh-CN/tools/web.md @@ -1,45 +1,44 @@ --- read_when: - 你想启用或配置 web_search - - 你想要启用或配置 x_search + - 你想启用或配置 x_search - 你需要选择一个搜索提供商 - 你想了解自动检测和提供商回退 sidebarTitle: Web Search summary: web_search、x_search 和 web_fetch -- 搜索网页、搜索 X 帖子，或获取页面内容 title: Web 搜索 x-i18n: - generated_at: "2026-05-02T03:13:28Z" + generated_at: "2026-05-02T03:43:47Z" model: gpt-5.5 provider: openai - source_hash: 9e0140a3f472afe58d13ffc87bb3c91e3b5f7ddf49f883b38ae9b832e62cafe3 + source_hash: 873d953c068096a926940eb7065961814900417afdfbcf04946a6cefcd58f578 source_path: tools/web.md workflow: 16 --- -`web_search` 工具会使用你配置的提供商搜索网页并返回结果。结果会按查询缓存 15 分钟（可配置）。 +`web_search` 工具使用你配置的提供商搜索 Web，并返回结果。结果会按查询缓存 15 分钟（可配置）。 -OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于轻量级 URL 获取的 `web_fetch`。在此阶段，`web_fetch` 保持本地执行，而 `web_search` 和 `x_search` 可在底层使用 xAI Responses。 +OpenClaw 还包含用于 X（前 Twitter）帖子的 `x_search`，以及用于轻量级 URL 抓取的 `web_fetch`。在这个阶段，`web_fetch` 保持本地运行，而 `web_search` 和 `x_search` 可以在底层使用 xAI Responses。 `web_search` 是一个轻量级 HTTP 工具，不是浏览器自动化。对于 - JS 较重的网站或登录场景，请使用 [Web 浏览器](/zh-CN/tools/browser)。对于 - 获取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。 + JS 密集型网站或登录场景，请使用 [Web 浏览器](/zh-CN/tools/browser)。对于 + 抓取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。 ## 快速开始 - 选择一个提供商并完成任何必需设置。有些提供商不需要密钥，而有些使用 API 密钥。详情请参阅下面的提供商页面。 + 选择一个提供商并完成任何必需的设置。有些提供商不需要密钥，而其他提供商使用 API key。详情请参阅下面的提供商页面。 ```bash openclaw configure --section web ``` - 这会存储提供商和任何所需凭据。你也可以设置一个环境变量 - （例如 `BRAVE_API_KEY`），并对 API 支持的提供商跳过此步骤。 + 这会存储提供商和任何所需凭证。你也可以设置一个环境变量（例如 `BRAVE_API_KEY`），并对 API 支持的提供商跳过此步骤。 - + 智能体现在可以调用 `web_search`： ```javascript @@ -59,72 +58,72 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 - 带摘要片段的结构化结果。支持 `llm-context` 模式、国家/语言筛选器。提供免费层级。 + 带摘要片段的结构化结果。支持 `llm-context` 模式，以及国家/语言筛选。提供免费套餐。 - 免密钥回退。无需 API 密钥。基于非官方 HTML 的集成。 + 免密钥回退。不需要 API key。基于非官方 HTML 的集成。 - 神经 + 关键词搜索，支持内容提取（高亮、文本、摘要）。 + 神经网络 + 关键词搜索，并支持内容提取（高亮、文本、摘要）。 - 结构化结果。与 `firecrawl_search` 和 `firecrawl_scrape` 搭配用于深度提取效果最佳。 + 结构化结果。最适合与 `firecrawl_search` 和 `firecrawl_scrape` 搭配，用于深度提取。 - 通过 Google Search grounding 提供带引用的 AI 综合答案。 + 通过 Google Search grounding 提供带引用的 AI 合成答案。 - 通过 xAI web grounding 提供带引用的 AI 综合答案。 + 通过 xAI Web grounding 提供带引用的 AI 合成答案。 - 通过 Moonshot web search 提供带引用的 AI 综合答案。 + 通过 Moonshot Web 搜索提供带引用的 AI 合成答案。 - 通过 MiniMax Coding Plan 搜索 API 提供结构化结果。 + 通过 MiniMax Coding Plan search API 提供结构化结果。 - 通过已登录的本地 Ollama 主机或托管的 Ollama API 进行搜索。 + 通过已登录的本地 Ollama 主机或托管的 Ollama API 搜索。 带内容提取控制和域名筛选的结构化结果。 - 自托管元搜索。无需 API 密钥。聚合 Google、Bing、DuckDuckGo 等。 + 自托管元搜索。不需要 API key。聚合 Google、Bing、DuckDuckGo 等。 带搜索深度、主题筛选，以及用于 URL 提取的 `tavily_extract` 的结构化结果。 -### 提供商对比 +### 提供商比较 -| 提供商 | 结果样式 | 筛选器 | API 密钥 | +| 提供商 | 结果样式 | 筛选 | API key | | ----------------------------------------- | -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- | | [Brave](/zh-CN/tools/brave-search) | 结构化摘要片段 | 国家、语言、时间、`llm-context` 模式 | `BRAVE_API_KEY` | | [DuckDuckGo](/zh-CN/tools/duckduckgo-search) | 结构化摘要片段 | -- | 无（免密钥） | -| [Exa](/zh-CN/tools/exa-search) | 结构化 + 已提取内容 | 神经/关键词模式、日期、内容提取 | `EXA_API_KEY` | +| [Exa](/zh-CN/tools/exa-search) | 结构化 + 已提取内容 | 神经网络/关键词模式、日期、内容提取 | `EXA_API_KEY` | | [Firecrawl](/zh-CN/tools/firecrawl) | 结构化摘要片段 | 通过 `firecrawl_search` 工具 | `FIRECRAWL_API_KEY` | -| [Gemini](/zh-CN/tools/gemini-search) | AI 综合 + 引用 | -- | `GEMINI_API_KEY` | -| [Grok](/zh-CN/tools/grok-search) | AI 综合 + 引用 | -- | `XAI_API_KEY` | -| [Kimi](/zh-CN/tools/kimi-search) | AI 综合 + 引用 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | +| [Gemini](/zh-CN/tools/gemini-search) | AI 合成 + 引用 | -- | `GEMINI_API_KEY` | +| [Grok](/zh-CN/tools/grok-search) | AI 合成 + 引用 | -- | `XAI_API_KEY` | +| [Kimi](/zh-CN/tools/kimi-search) | AI 合成 + 引用 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` | | [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化摘要片段 | 区域（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` | -| [Ollama Web Search](/zh-CN/tools/ollama-search) | 结构化摘要片段 | -- | 已登录的本地主机无需密钥；直接 `https://ollama.com` 搜索使用 `OLLAMA_API_KEY` | +| [Ollama Web Search](/zh-CN/tools/ollama-search) | 结构化摘要片段 | -- | 已登录本地主机无需密钥；直接 `https://ollama.com` 搜索使用 `OLLAMA_API_KEY` | | [Perplexity](/zh-CN/tools/perplexity-search) | 结构化摘要片段 | 国家、语言、时间、域名、内容限制 | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` | -| [SearXNG](/zh-CN/tools/searxng-search) | 结构化摘要片段 | 类别、语言 | 无（自托管） | +| [SearXNG](/zh-CN/tools/searxng-search) | 结构化摘要片段 | 分类、语言 | 无（自托管） | | [Tavily](/zh-CN/tools/tavily) | 结构化摘要片段 | 通过 `tavily_search` 工具 | `TAVILY_API_KEY` | ## 自动检测 -## 原生 OpenAI 网页搜索 +## 原生 OpenAI Web 搜索 -当启用 OpenClaw 网页搜索且未固定托管提供商时，直接的 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 搜索。 +当 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 网页搜索 +## 原生 Codex Web 搜索 支持 Codex 的模型可以选择使用提供商原生 Responses `web_search` 工具，而不是 OpenClaw 托管的 `web_search` 函数。 - 在 `tools.web.search.openaiCodex` 下配置它 -- 它仅对支持 Codex 的模型激活（`openai-codex/*` 或使用 `api: "openai-codex-responses"` 的提供商） +- 它只会为支持 Codex 的模型激活（`openai-codex/*` 或使用 `api: "openai-codex-responses"` 的提供商） - 托管的 `web_search` 仍适用于非 Codex 模型 - `mode: "cached"` 是默认且推荐的设置 - `tools.web.search.enabled: false` 会同时禁用托管搜索和原生搜索 @@ -152,13 +151,13 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 } ``` -如果已启用原生 Codex 搜索，但当前模型不支持 Codex，OpenClaw 会保留正常的托管 `web_search` 行为。 +如果启用了原生 Codex 搜索，但当前模型不支持 Codex，OpenClaw 会保留正常的托管 `web_search` 行为。 -## 设置网页搜索 +## 设置 Web 搜索 文档和设置流程中的提供商列表按字母顺序排列。自动检测会保留单独的优先级顺序。 -如果未设置 `provider`，OpenClaw 会按以下顺序检查提供商，并使用第一个就绪的提供商： +如果未设置 `provider`，OpenClaw 会按此顺序检查提供商，并使用第一个已就绪的提供商： 首先是 API 支持的提供商： @@ -174,20 +173,14 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 之后是免密钥回退： -10. **DuckDuckGo** -- 无账号或 API 密钥的免密钥 HTML 回退（顺序 100） -11. **Ollama Web Search** -- 当你配置的本地 Ollama 主机可访问并已通过 `ollama signin` 登录时，通过它提供免密钥回退；当主机需要时可复用 Ollama 提供商 bearer 认证，并且在配置了 `OLLAMA_API_KEY` 时可调用直接 `https://ollama.com` 搜索（顺序 110） +10. **DuckDuckGo** -- 不需要账号或 API key 的免密钥 HTML 回退（顺序 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（你会收到缺少密钥的错误，提示你配置一个）。 +如果未检测到提供商，它会回退到 Brave（你会看到提示你配置密钥的缺失密钥错误）。 - 所有提供商密钥字段都支持 SecretRef 对象。位于 - `plugins.entries..config.webSearch.apiKey` 下的插件作用域 SecretRef - 会为内置的 API 支持网页搜索提供商解析，包括 Brave、Exa、Firecrawl、 - Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily， - 无论该提供商是通过 `tools.web.search.provider` 显式选择，还是通过自动检测选择。 - 在自动检测模式下，OpenClaw 仅解析所选提供商的密钥 -- 未选中的 SecretRef 保持非活动状态，因此你可以 - 保持多个提供商已配置，而无需为未使用的提供商支付解析成本。 + 所有提供商密钥字段都支持 SecretRef 对象。对于内置的 API 支持 Web 搜索提供商，包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily，位于 `plugins.entries..config.webSearch.apiKey` 下的插件作用域 SecretRef 都会被解析；无论提供商是通过 `tools.web.search.provider` 显式选择，还是通过自动检测选择。在自动检测模式下，OpenClaw 只解析所选提供商的密钥 -- 未选中的 SecretRef 保持非活动状态，因此你可以配置多个提供商，而不会为未使用的提供商支付解析成本。 ## 配置 @@ -208,34 +201,29 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 } ``` -提供商特定配置（API 密钥、基础 URL、模式）位于 -`plugins.entries..config.webSearch.*` 下。示例请参阅提供商页面。 +提供商专用配置（API key、基础 URL、模式）位于 `plugins.entries..config.webSearch.*` 下。示例请参阅提供商页面。 -`web_fetch` 回退提供商选择是独立的： +`web_fetch` 回退提供商选择是单独的： - 使用 `tools.web.fetch.provider` 选择它 -- 或省略该字段，让 OpenClaw 从可用凭据中自动检测第一个就绪的 web-fetch - 提供商 -- 非沙箱隔离的 `web_fetch` 可以使用声明了 - `contracts.webFetchProviders` 的已安装插件提供商；沙箱隔离的获取保持仅使用内置提供商 -- 目前内置的 web-fetch 提供商是 Firecrawl，配置位于 - `plugins.entries.firecrawl.config.webFetch.*` 下 +- 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个已就绪的 Web 抓取提供商 +- 非沙箱隔离的 `web_fetch` 可以使用声明了 `contracts.webFetchProviders` 的已安装插件提供商；沙箱隔离的抓取保持仅使用内置提供商 +- 目前内置的 Web 抓取提供商是 Firecrawl，配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下 -当你在 `openclaw onboard` 或 -`openclaw configure --section web` 期间选择 **Kimi** 时，OpenClaw 还可以询问： +当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Kimi** 时，OpenClaw 还可以询问： - Moonshot API 区域（`https://api.moonshot.ai/v1` 或 `https://api.moonshot.cn/v1`） -- 默认 Kimi 网页搜索模型（默认为 `kimi-k2.6`） +- 默认 Kimi Web 搜索模型（默认为 `kimi-k2.6`） -对于 `x_search`，请配置 `plugins.entries.xai.config.xSearch.*`。它使用与 Grok Web 搜索相同的 `XAI_API_KEY` 回退。 +对于 `x_search`，配置 `plugins.entries.xai.config.xSearch.*`。它使用与 Grok 网页搜索相同的 `XAI_API_KEY` 回退。 旧版 `tools.web.x_search.*` 配置会由 `openclaw doctor --fix` 自动迁移。 当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 Grok 时，OpenClaw 也可以使用同一个密钥提供可选的 `x_search` 设置。 -这是 Grok 路径中的一个单独后续步骤，而不是单独的顶层 Web 搜索提供商选择。如果你选择其他提供商，OpenClaw 不会显示 `x_search` 提示。 +这是 Grok 路径中的一个单独后续步骤，不是单独的顶层网页搜索提供商选项。如果你选择其他提供商，OpenClaw 不会显示 `x_search` 提示。 ### 存储 API 密钥 - + 运行 `openclaw configure --section web`，或直接设置密钥： ```json5 @@ -255,7 +243,7 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 ``` - + 在 Gateway 网关进程环境中设置提供商环境变量： ```bash @@ -263,42 +251,45 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 ``` 对于 Gateway 网关安装，请将它放入 `~/.openclaw/.env`。 - 请参阅 [环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。 + 参见 [环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。 ## 工具参数 -| 参数 | 描述 | -| --------------------- | ----------------------------------------------------- | -| `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） | +| 参数 | 说明 | +| --------------------- | ------------------------------------------------------ | +| `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） | - 并非所有参数都适用于所有提供商。Brave `llm-context` 模式会拒绝 `ui_lang`、`freshness`、`date_after` 和 `date_before`。 - Gemini、Grok 和 Kimi 会返回一个带引用的综合答案。它们接受 `count` 以兼容共享工具，但这不会改变基于来源的答案形态。 - 当你使用 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`，请使用它们的专用工具获取高级选项。 + 并非所有参数都适用于所有提供商。Brave `llm-context` 模式会拒绝 `ui_lang`；`date_before` 也需要 `date_after`，因为 Brave 自定义新鲜度范围要求同时提供开始日期和结束日期。 + Gemini、Grok 和 Kimi 会返回一个带引用的综合答案。它们接受 `count` 以兼容共享工具，但它不会改变基于依据的答案形态。 + 当你使用 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 -`x_search` 使用 xAI 查询 X（原 Twitter）帖子，并返回带引用的 AI 综合答案。它接受自然语言查询和可选的结构化筛选器。OpenClaw 仅在服务此工具调用的请求上启用内置 xAI `x_search` 工具。 +`x_search` 使用 xAI 查询 X（原 Twitter）帖子，并返回带引用的 AI 综合答案。它接受自然语言查询和可选的结构化过滤器。OpenClaw 仅在服务此工具调用的请求中启用内置 xAI `x_search` 工具。 - xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户搜索和话题串获取。对于转发、回复、书签或查看次数等单帖互动统计，请优先对精确帖子 URL 或状态 ID 进行定向查找。宽泛的关键词搜索可能找到正确帖子，但返回的单帖元数据不够完整。一个好的模式是：先定位帖子，然后运行第二次 `x_search` 查询，聚焦该精确帖子。 + xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户搜索和主题串获取。对于转帖、回复、书签或浏览量等单帖互动统计，优先使用针对准确帖子 URL 或状态 ID 的定向查找。宽泛的关键词搜索可能找到正确帖子，但返回的单帖元数据不够完整。一个好的模式是：先定位帖子，然后运行第二个聚焦该准确帖子的 `x_search` 查询。 ### x_search 配置 @@ -329,19 +320,19 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于 } ``` -当设置了 `plugins.entries.xai.config.xSearch.baseUrl` 时，`x_search` 会 POST 到 `/responses`。如果省略该字段，它会回退到 `plugins.entries.xai.config.webSearch.baseUrl`，然后回退到旧版 `tools.web.search.grok.baseUrl`，最后回退到公共 xAI 端点。 +当设置了 `plugins.entries.xai.config.xSearch.baseUrl` 时，`x_search` 会发布到 `/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 检查匹配帖子附带的视频 | +| 参数 | 说明 | +| ---------------------------- | ------------------------------------------------------ | +| `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 示例 @@ -386,9 +377,9 @@ await web_search({ }); ``` -## 工具配置档 +## 工具配置文件 -如果你使用工具配置档或允许列表，请添加 `web_search`、`x_search` 或 `group:web`： +如果你使用工具配置文件或允许列表，请添加 `web_search`、`x_search` 或 `group:web`： ```json5 { @@ -399,9 +390,9 @@ await web_search({ } ``` -## 相关 +## 相关内容 - [Web Fetch](/zh-CN/tools/web-fetch) -- 获取 URL 并提取可读内容 -- [Web Browser](/zh-CN/tools/browser) -- 用于 JS 密集型网站的完整浏览器自动化 +- [Web Browser](/zh-CN/tools/browser) -- 面向 JS 密集型站点的完整浏览器自动化 - [Grok Search](/zh-CN/tools/grok-search) -- 将 Grok 用作 `web_search` 提供商 -- [Ollama Web 搜索](/zh-CN/tools/ollama-search) -- 通过你的 Ollama 主机进行免密钥 Web 搜索 +- [Ollama Web 搜索](/zh-CN/tools/ollama-search) -- 通过你的 Ollama 主机进行免密钥网页搜索