openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-03 19:40:34 +00:00
parent 6ddeacef95
commit 9ff211e6f4
2 changed files with 237 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
docs/zh-CN/concepts/model-providers.md
View File

@ -1,20 +1,20 @@
---
read_when:
- 你需要一份按提供商划分的模型设置参考
- 你想要模型提供商的示例配置或 CLI 新手引导命令
- 你想要模型提供商的配置示例或 CLI 新手引导命令
sidebarTitle: Model providers
summary: 模型提供商概览，包含示例配置 + CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-05-03T04:50:48Z"
generated_at: "2026-05-03T19:38:21Z"
model: gpt-5.5
provider: openai
source_hash: bfb12090228ec89bc116558fe3e0bf9977c750550ef8efbf55b1af6c873c9825
source_hash: b2c94e8f0c8d70cd772990e4d9d41a5670855eef4aea5162e021f18d5ee6c899
source_path: concepts/model-providers.md
workflow: 16
---
LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
模型提供商（LLM/model providers）的参考资料（不是 WhatsApp/Telegram 这样的聊天渠道）。如需了解模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
## 快速规则
@ -23,12 +23,12 @@ LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 设置后，`agents.defaults.models` 会作为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 按模型覆盖这些默认值。
- 回退规则、冷却探测和会话覆盖持久化：[模型故障转移](/zh-CN/concepts/model-failover)。
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖这些默认值。
- 回退规则、冷却探测和会话级覆盖持久化：[模型故障转移](/zh-CN/concepts/model-failover)。
</Accordion>
<Accordion title="添加提供商认证不会更改你的主模型">
当你添加提供商或重新认证提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在它们的认证配置补丁中返回推荐的默认模型，但如果主模型已存在，configure 会将其视为“使此模型可用”，而不是“替换当前主模型”。
<Accordion title="添加提供商凭证不会更改你的主模型">
当你添加或重新认证提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍然可能在其凭证配置补丁中返回推荐的默认模型，但如果主模型已经存在，configure 会将其视为“让此模型可用”，而不是“替换当前主模型”。
若要有意切换默认模型，请使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。
@ -40,15 +40,15 @@ LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考
- `openai-codex/<model>` 在 PI 中使用 Codex OAuth。
- 没有 Codex 运行时覆盖的 `openai/<model>` 在 PI 中使用直接的 OpenAI API key 提供商。
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果 provider/运行时拆分让你困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
插件自动启用遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
插件自动启用遵循同一边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
当设置 `agentRuntime.id: "codex"` 时，GPT-5.5 可通过原生 Codex 应用服务器 harness 使用；对于 Codex OAuth，可通过 PI 中的 `openai-codex/gpt-5.5` 使用；当你的账号开放该模型时，对于直接 API key 流量，可通过 PI 中的 `openai/gpt-5.5` 使用。
设置 `agentRuntime.id: "codex"` 时，可以通过原生 Codex 应用服务器 harness 使用 GPT-5.5；在 PI 中通过 `openai-codex/gpt-5.5` 使用 Codex OAuth；当你的账户公开该能力时，在 PI 中通过 `openai/gpt-5.5` 使用直接 API key 流量。
</Accordion>
<Accordion title="CLI 运行时">
CLI 运行时使用相同的拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
CLI 运行时使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在需要本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并单独记录运行时。
@ -57,12 +57,12 @@ LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考
## 插件拥有的提供商行为
大多数提供商特定逻辑位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具架构清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置档案等能力。
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置等。
提供商 SDK 钩子和内置插件示例的完整列表位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于另一个更深层的扩展面。
提供商 SDK 钩子和内置插件示例的完整列表位于 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于另一个更深层的扩展表面。
<Note>
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具架构规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑不再读取它。
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑不再读取它。
</Note>
## API key 轮换
@ -71,17 +71,17 @@ LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考
<Accordion title="密钥来源和优先级">
通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，优先级最高）
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并去重值。
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并对值去重。
</Accordion>
<Accordion title="何时触发轮换">
- 请求只会在遇到速率限制响应时使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
<Accordion title="轮换何时生效">
- 仅在速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非速率限制故障会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。
</Accordion>
@ -89,25 +89,25 @@ LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）的参考
## 内置提供商（pi-ai 目录）
OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型。
OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置凭证并选择模型。
### OpenAI
- 提供商：`openai`
- 认证：`OPENAI_API_KEY`
- 凭证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4-mini`
- 如果特定安装或 API key 表现不同，请使用 `openclaw models list --provider openai` 验证账号/模型可用性。
- 如果特定安装或 API key 的行为不同，请使用 `openclaw models list --provider openai` 验证账户/模型可用性。
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- OpenAI 优先处理可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你想要显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示和 OpenAI reasoning 兼容载荷塑形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，并且当前 Codex 目录未公开它
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority`
- 当你需要显式层级而不是共享 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容负载整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
```json5
{
@ -118,18 +118,18 @@ OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers`
### Anthropic
- 提供商：`anthropic`
- 认证：`ANTHROPIC_API_KEY`
- 凭证：`ANTHROPIC_API_KEY`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 直接公共 Anthropic 请求支持共享 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- 首选 Claude CLI 配置会保持模型引用规范，并单独选择 CLI
后端：`anthropic/claude-opus-4-7` 搭配
`agents.defaults.agentRuntime.id: "claude-cli"`。旧版
`claude-cli/claude-opus-4-7` 引用仍可用于兼容性。
<Note>
Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再次被允许，因此除非 Anthropic 发布新策略，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 使用视为此集成的获准方式。Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在优先使用 Claude CLI 复用和可用时的 `claude -p`。
Anthropic 工作人员告知我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新策略，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受认可方式。Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在优先复用 Claude CLI，并在可用时使用 `claude -p`。
</Note>
```json5
@ -141,7 +141,7 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再
### OpenAI Codex OAuth
- 提供商：`openai-codex`
- 认证：OAuth（ChatGPT）
- 凭证：OAuth（ChatGPT）
- PI 模型引用：`openai-codex/gpt-5.5`
- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"`
- 原生 Codex 应用服务器 harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
@ -150,13 +150,13 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中转发
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority`
- `openai-codex/gpt-5.5` 使用 Codex 目录原生的 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可使用 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具/工作流。
- 对于常见的订阅加原生 Codex 运行时路由，请使用 `openai-codex` 认证登录，但配置 `openai/gpt-5.5` 加 `agents.defaults.agentRuntime.id: "codex"`。
- 仅当你想通过 PI 使用 Codex OAuth/订阅路由时，才使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录公开公共 API 路由时，请使用没有 Codex 运行时覆盖的 `openai/gpt-5.5`。
- 对于常见的订阅加原生 Codex 运行时路线，请使用 `openai-codex` 凭证登录，但配置 `openai/gpt-5.5` 加 `agents.defaults.agentRuntime.id: "codex"`。
- 仅当你想通过 PI 使用 Codex OAuth/订阅路线时，才使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录公开公共 API 路线时，请使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。
```json5
{
@ -192,13 +192,13 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再
MiniMax Coding Plan OAuth 或 API key 访问。
</Card>
<Card title="Qwen Cloud" href="/zh-CN/providers/qwen">
Qwen Cloud 提供商表面，以及 Alibaba DashScope 和 Coding Plan 端点映射。
Qwen Cloud 提供商表面，加上 Alibaba DashScope 和 Coding Plan 端点映射。
</Card>
</CardGroup>
### OpenCode
- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- 凭证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
- Zen 运行时提供商：`opencode`
- Go 运行时提供商：`opencode-go`
- 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.6`
@ -214,13 +214,13 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再
- 提供商：`google`
- 凭证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单一覆盖）
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖项）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- 别名：接受 `google/gemini-3.1-pro`，并将其规范化为 Google 的实时 Gemini API id：`google/gemini-3.1-pro-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会规范化为 `google/gemini-3-flash-preview`
- 别名：接受 `google/gemini-3.1-pro`，并将其规范化为 Google 的实时 Gemini API id，即 `google/gemini-3.1-pro-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 省略固定的 `thinkingLevel`；Gemini 2.5 发送 `thinkingBudget: -1`。
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会作为 OpenClaw `cacheRead` 显示
- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
### Google Vertex 和 Gemini CLI
@ -228,13 +228,13 @@ Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 使用已再
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
<Warning>
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后 Google 账号受到了限制。如果你选择继续，请查看 Google 条款并使用非关键账号。
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后遇到了 Google 账号限制。如果你选择继续，请查看 Google 条款并使用非关键账号。
</Warning>
Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
<Steps>
<Step title="安装 Gemini CLI">
<Step title="Install Gemini CLI">
<Tabs>
<Tab title="brew">
```bash
@ -248,57 +248,57 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
</Tab>
</Tabs>
</Step>
<Step title="启用插件">
<Step title="Enable plugin">
```bash
openclaw plugins enable google
```
</Step>
<Step title="登录">
<Step title="Login">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不**需要把客户端 id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会把令牌存储在 Gateway 网关主机上的凭证配置文件中。
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不需要**把客户端 id 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置文件中。
</Step>
<Step title="设置项目（如果需要）">
<Step title="Set project (if needed)">
如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
</Step>
</Steps>
Gemini CLI JSON 回复会从 `response` 解析；用量回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会规范化为 OpenClaw `cacheRead`。
### Z.AI (GLM)
### Z.AI（GLM）
- 提供商：`zai`
- 凭证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5.1`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定表面
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定入口面
### Vercel AI Gateway
### Vercel AI Gateway 网关
- 提供商：`vercel-ai-gateway`
- 凭证：`AI_GATEWAY_API_KEY`
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、`vercel-ai-gateway/moonshotai/kimi-k2.6`
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway
### Kilo Gateway 网关
- 提供商：`kilocode`
- 凭证：`KILOCODE_API_KEY`
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- Base URL：`https://api.kilo.ai/api/gateway/`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录随附 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 设备发现可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 拥有，不在 OpenClaw 中硬编码。
- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 网关负责，不在 OpenClaw 中硬编码。
有关设置详情，请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
| 提供商 | Id | 凭证环境变量 | 示例模型 |
| 提供商 | Id | 凭证环境变量 | 示例模型 |
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
@ -321,44 +321,44 @@ Gemini CLI JSON 回复会从 `response` 解析；用量回退到 `stats`，其
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
| Venice | `venice` | `VENICE_API_KEY` | — |
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
| Volcano Engine（Doubao） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` |
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
#### 需要了解的细节
#### 值得了解的特性
<AccordionGroup>
<Accordion title="OpenRouter">
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的提示缓存 cache-TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容性）。由 Gemini 支持的引用仅保留代理 Gemini 思考签名清理。
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI refs 可用于 OpenRouter 管理的提示缓存 TTL，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的成形处理（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容）。Gemini 后端的 refs 仅保留代理 Gemini 思考签名清理。
</Accordion>
<Accordion title="Kilo Gateway">
由 Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
Gemini 后端的 refs 遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的 refs 会跳过代理推理注入。
</Accordion>
<Accordion title="MiniMax">
API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。
API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍由插件拥有的 `MiniMax-VL-01` 媒体提供商处理。
</Accordion>
<Accordion title="NVIDIA">
模型 ID 使用 `nvidia/<vendor>/<model>` 命名空间（例如 `nvidia/nvidia/nemotron-...` 与 `nvidia/moonshotai/kimi-k2.5` 并列）；选择器会保留字面量 `<provider>/<model-id>` 组合，而发送到 API 的规范键保持单前缀。
模型 ID 使用 `nvidia/<vendor>/<model>` 命名空间（例如 `nvidia/nvidia/nemotron-...` 以及 `nvidia/moonshotai/kimi-k2.5`）；选择器会保留字面上的 `<provider>/<model-id>` 组合，而发送到 API 的规范键仍保持单前缀。
</Accordion>
<Accordion title="xAI">
使用 xAI Responses 路径。`grok-4.3` 是内置的默认聊天模型。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为对应的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
使用 xAI Responses 路径。`grok-4.3` 是内置的默认聊天模型。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
</Accordion>
<Accordion title="Cerebras">
作为内置的 `cerebras` 提供商插件提供。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
作为内置的 `cerebras` 提供商插件随附。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
</Accordion>
</AccordionGroup>
## 通过 `models.providers` 使用提供商（自定义/基础 URL）
## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
下方许多内置提供商插件已经发布默认目录。只有在你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
Gateway 网关模型能力检查还会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义模型或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，以便 WebChat 和节点来源的附件路径将图像作为原生模型输入传递，而不是作为纯文本媒体引用。
Gateway 网关模型能力检查也会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，这样 WebChat 和节点来源附件路径会将图像作为原生模型输入传递，而不是作为纯文本媒体 refs。
### Moonshot AI（Kimi）
### Moonshot AI (Kimi)
Moonshot 作为内置提供商插件提供。默认使用内置提供商，仅当你需要覆盖基础 URL 或模型元数据时才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件随附。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 凭证：`MOONSHOT_API_KEY`
@ -417,10 +417,10 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的访问能力。
Volcano Engine（火山引擎）提供在中国访问 Doubao 和其他模型的能力。
- 提供商：`volcengine`（编码：`volcengine-plan`）
- 凭证：`VOLCANO_ENGINE_API_KEY`
- 认证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
@ -432,9 +432,9 @@ Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的
}
```
新手引导默认使用编码能力面，但通用的 `volcengine/*` 目录也会同时注册。
新手引导默认使用编码表面，但通用的 `volcengine/*` 目录会同时注册。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商限定选择器。
<Tabs>
<Tab title="标准模型">
@ -457,10 +457,10 @@ Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的
### BytePlus（国际版）
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
BytePlus ARK 为国际用户提供访问与 Volcano Engine 相同模型的能力。
- 提供商：`byteplus`（编码：`byteplus-plan`）
- 凭证：`BYTEPLUS_API_KEY`
- 认证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -472,9 +472,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
}
```
新手引导默认使用编码能力面，但通用的 `byteplus/*` 目录也会同时注册。
新手引导默认使用编码表面，但通用的 `byteplus/*` 目录会同时注册。
在新手引导/配置模型选择器中，BytePlus 凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商限定选择器。
<Tabs>
<Tab title="标准模型">
@ -498,7 +498,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
- 提供商：`synthetic`
- 凭证：`SYNTHETIC_API_KEY`
- 认证：`SYNTHETIC_API_KEY`
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5`
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
@ -527,29 +527,29 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
- MiniMax API key（全球）：`--auth-choice minimax-global-api`
- MiniMax API key（中国）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api`
- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api`
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
有关设置详情、模型选项和配置片段，请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
请参阅 [/providers/minimax](/zh-CN/providers/minimax) 了解设置详情、模型选项和配置片段。
<Note>
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用 thinking，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置 thinking，否则 OpenClaw 默认会禁用它，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
</Note>
插件拥有的能力拆分：
由插件拥有的能力划分：
- 文本/聊天默认值保留在 `minimax/MiniMax-M2.7`
- 图像生成是 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解是在两个 MiniMax 凭证路径上都由插件拥有的 `MiniMax-VL-01`
- Web 搜索保留在提供商 ID `minimax`
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两个 MiniMax 认证路径上都由插件拥有，使用 `MiniMax-VL-01`
- Web 搜索保留在提供商 ID `minimax` 上
### LM Studio
LM Studio 作为内置提供商插件发布，使用原生 API：
LM Studio 作为内置提供商插件随附，使用原生 API：
- 提供商：`lmstudio`
- 凭证：`LM_API_TOKEN`
- 认证：`LM_API_TOKEN`
- 默认推理基础 URL：`http://localhost:1234/v1`
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
@ -562,14 +562,14 @@ LM Studio 作为内置提供商插件发布，使用原生 API：
}
```
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。如果你希望 LM Studio JIT 加载、TTL 和自动驱逐拥有模型生命周期，请设置 `models.providers.lmstudio.params.preload: false`。有关设置和故障排除，请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。如果你希望由 LM Studio JIT 加载、TTL 和自动驱逐来接管模型生命周期，请设置 `models.providers.lmstudio.params.preload: false`。请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio) 了解设置和故障排除。
### Ollama
Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：
Ollama 作为内置提供商插件随附，并使用 Ollama 的原生 API：
- 提供商：`ollama`
- 凭证：不需要（本地服务器）
- 认证：不需要（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：[https://ollama.com/download](https://ollama.com/download)
@ -586,17 +586,17 @@ ollama pull llama3.3
}
```
当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在 `http://127.0.0.1:11434` 被本地检测到，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
当你使用 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地的 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接加入 `openclaw onboard` 和模型选择器。请参阅 [/providers/ollama](/zh-CN/providers/ollama) 了解新手引导、云端/本地模式和自定义配置。
### vLLM
vLLM 作为内置提供商插件发布，用于本地/自托管的 OpenAI 兼容服务器：
vLLM 作为内置提供商插件随附，用于本地/自托管的 OpenAI 兼容服务器：
- 提供商：`vllm`
- 凭证：可选（取决于你的服务器）
- 认证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
若要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
@ -612,17 +612,17 @@ export VLLM_API_KEY="vllm-local"
}
```
有关详情，请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
请参阅 [/providers/vllm](/zh-CN/providers/vllm) 了解详情。
### SGLang
SGLang 作为内置提供商插件发布，用于快速自托管的 OpenAI 兼容服务器：
SGLang 作为内置提供商插件随附，用于快速的自托管 OpenAI 兼容服务器：
- 提供商：`sglang`
- 凭证：可选（取决于你的服务器）
- 认证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
若要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
@ -638,7 +638,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
有关详情，请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
请参阅 [/providers/sglang](/zh-CN/providers/sglang) 了解详情。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -678,7 +678,7 @@ export SGLANG_API_KEY="sglang-local"
<AccordionGroup>
<Accordion title="默认可选字段">
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。省略时，OpenClaw 默认使用：
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
@ -690,14 +690,15 @@ export SGLANG_API_KEY="sglang-local"
</Accordion>
<Accordion title="代理路由整形规则">
- 对于非原生端点（任何非空 `baseUrl` 且其主机不是 `api.openai.com`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因头。
- 对于非原生端点（任何非空且主机不是 `api.openai.com` 的 `baseUrl`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免因不支持 `developer` 角色而触发提供商 400 错误。
- 代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求整形：没有 `service_tier`、没有 Responses `store`、没有 Completions `store`、没有提示缓存提示、没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因标头。
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。
- 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总的受保护 fetch 中止时间，而不会增加整个智能体运行时超时时间。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全，显式的 `compat.supportsDeveloperRole: true` 在非原生 `openai-completions` 端点上仍会被覆盖。
- 对于非直连端点（canonical `anthropic` 以外的任何提供商，或主机不是公开 `api.anthropic.com` 端点的自定义 `models.providers.anthropic.baseUrl`）上的 `api: "anthropic-messages"`，OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
- 对于 vLLM 聊天模板控制项，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、标头、正文流式传输以及总的受保护 fetch 中止，而不会增加整个智能体运行时超时时间。
- 模型提供商 HTTP 调用仅允许为已配置提供商 `baseUrl` 主机名使用 `198.18.0.0/15` 和 `fc00::/7` 中的 Surge、Clash 和 sing-box fake-IP DNS 响应。其他私有、回环、链路本地和元数据目标仍然需要显式选择启用 `models.providers.<id>.request.allowPrivateNetwork: true`。
- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
- 为了安全，在非原生 `openai-completions` 端点上，即使显式设置 `compat.supportsDeveloperRole: true`，仍会被覆盖。
- 对于非直连端点上的 `api: "anthropic-messages"`（除规范的 `anthropic` 之外的任何提供商，或主机不是公共 `api.anthropic.com` 端点的自定义 `models.providers.anthropic.baseUrl`），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
</Accordion>
</AccordionGroup>
@ -710,11 +711,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另请参阅：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
另请参阅：[配置](/zh-CN/gateway/configuration) 获取完整配置示例。
## 相关内容
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [提供商](/zh-CN/providers) — 各提供商设置指南
- [提供商](/zh-CN/providers) — 按提供商划分的设置指南

219
docs/zh-CN/tools/web.md
View File

@ -8,21 +8,21 @@ sidebarTitle: Web Search
summary: web_search、x_search 和 web_fetch -- 搜索网页、搜索 X 帖子，或获取页面内容
title: Web 搜索
x-i18n:
generated_at: "2026-05-02T07:14:00Z"
generated_at: "2026-05-03T19:38:30Z"
model: gpt-5.5
provider: openai
source_hash: faa333a522a6690e92e8bd00c6096c84b386a97cbfeb508654929a409b39b8ef
source_hash: 84de67b51f02e3b901bfa55017ae8e88de49295dfe6ed1103a45f034e073c087
source_path: tools/web.md
workflow: 16
---
`web_search` 工具会使用你配置的提供商搜索 Web，并返回结果。结果会按查询缓存 15 分钟（可配置）。
`web_search` 工具会使用你配置的提供商搜索网页并返回结果。结果会按查询缓存 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。
<Info>
`web_search` 是一个轻量级 HTTP 工具，不是浏览器自动化。对于
JS 较重的网站或需要登录的场景，请使用 [Web Browser](/zh-CN/tools/browser)。如需
`web_search` 是轻量级 HTTP 工具，不是浏览器自动化。对于
大量依赖 JS 的网站或登录场景，请使用 [Web Browser](/zh-CN/tools/browser)。对于
获取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。
</Info>
@ -30,15 +30,17 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
<Steps>
<Step title="Choose a provider">
选择一个提供商并完成任何必需的设置。有些提供商无需密钥，
而另一些则使用 API key。详情请参阅下面的提供商页面。
选择一个提供商并完成所有必需设置。一些提供商
无需密钥，而其他提供商使用 API key。详情请参见下方的
提供商页面。
</Step>
<Step title="Configure">
```bash
openclaw configure --section web
```
这会存储提供商和任何所需凭证。你也可以设置一个环境变量
（例如 `BRAVE_API_KEY`），并对 API 支持的提供商跳过此步骤。
这会存储提供商以及任何需要的凭证。你也可以设置环境变量
（例如 `BRAVE_API_KEY`），并对 API 支持的
提供商跳过此步骤。
</Step>
<Step title="Use it">
智能体现在可以调用 `web_search`：
@ -60,28 +62,28 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
<CardGroup cols={2}>
<Card title="Brave Search" icon="shield" href="/zh-CN/tools/brave-search">
带摘要片段的结构化结果。支持 `llm-context` 模式、国家/语言筛选器。提供免费层级。
带片段的结构化结果。支持 `llm-context` 模式、国家/语言筛选。提供免费层。
</Card>
<Card title="DuckDuckGo" icon="bird" href="/zh-CN/tools/duckduckgo-search">
无需密钥的后备选项。不需要 API key。非官方的基于 HTML 的集成。
无需密钥的回退方案。不需要 API key。基于非官方 HTML 的集成。
</Card>
<Card title="Exa" icon="brain" href="/zh-CN/tools/exa-search">
神经搜索 + 关键词搜索，并提供内容提取（高亮、文本、摘要）。
神经搜索 + 关键词搜索，并支持内容提取（高亮、文本、摘要）。
</Card>
<Card title="Firecrawl" icon="flame" href="/zh-CN/tools/firecrawl">
结构化结果。最适合搭配 `firecrawl_search` 和 `firecrawl_scrape` 进行深度提取。
结构化结果。最适合与 `firecrawl_search` 和 `firecrawl_scrape` 搭配用于深度提取。
</Card>
<Card title="Gemini" icon="sparkles" href="/zh-CN/tools/gemini-search">
通过 Google Search grounding 提供带引用的 AI 合成答案。
通过 Google Search grounding 提供带引用的 AI 综合答案。
</Card>
<Card title="Grok" icon="zap" href="/zh-CN/tools/grok-search">
通过 xAI Web grounding 提供带引用的 AI 合成答案。
通过 xAI web grounding 提供带引用的 AI 综合答案。
</Card>
<Card title="Kimi" icon="moon" href="/zh-CN/tools/kimi-search">
通过 Moonshot Web 搜索提供带引用的 AI 合成答案；未 grounding 的聊天后备会明确失败。
通过 Moonshot web search 提供带引用的 AI 综合答案；未 grounding 的聊天回退会明确失败。
</Card>
<Card title="MiniMax Search" icon="globe" href="/zh-CN/tools/minimax-search">
通过 MiniMax Token Plan 搜索 API 提供结构化结果。
通过 MiniMax Token Plan search API 提供结构化结果。
</Card>
<Card title="Ollama Web Search" icon="globe" href="/zh-CN/tools/ollama-search">
通过已登录的本地 Ollama 主机或托管的 Ollama API 搜索。
@ -90,45 +92,45 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
带内容提取控制和域名筛选的结构化结果。
</Card>
<Card title="SearXNG" icon="server" href="/zh-CN/tools/searxng-search">
自托管元搜索。不需要 API key。聚合 Google、Bing、DuckDuckGo 等来源。
自托管元搜索。不需要 API key。聚合 Google、Bing、DuckDuckGo 等。
</Card>
<Card title="Tavily" icon="globe" href="/zh-CN/tools/tavily">
带搜索深度、主题筛选以及用于 URL 提取的 `tavily_extract` 的结构化结果。
带搜索深度、主题筛选和用于 URL 提取的 `tavily_extract` 的结构化结果。
</Card>
</CardGroup>
### 提供商比较
### 提供商对比
| 提供商 | 结果样式 | 筛选器 | API key |
| 提供商 | 结果样式 | 筛选 | 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` |
| [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 合成 + 引用；未 grounding 的聊天后备会失败 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化摘要片段 | 区域（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN` |
| [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) | 结构化摘要片段 | 分类、语言 | 无（自托管） |
| [Tavily](/zh-CN/tools/tavily) | 结构化摘要片段 | 通过 `tavily_search` 工具 | `TAVILY_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` |
| [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 综合答案 + 引用；未 grounding 的聊天回退会失败 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化片段 | 区域（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN` |
| [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) | 结构化片段 | 类别、语言 | 无（自托管） |
| [Tavily](/zh-CN/tools/tavily) | 结构化片段 | 通过 `tavily_search` 工具 | `TAVILY_API_KEY` |
## 自动检测
## 原生 OpenAI Web 搜索
## 原生 OpenAI web search
当 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 搜索。
当 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 Web 搜索
## 原生 Codex web search
支持 Codex 的模型可以选择使用提供商原生 Responses `web_search` 工具，而不是 OpenClaw 托管的 `web_search` 函数。
支持 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` 会同时禁用托管搜索和原生搜索
- `tools.web.search.enabled: false` 会同时停用托管搜索和原生搜索
```json5
{
@ -153,17 +155,29 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
}
```
如果已启用原生 Codex 搜索，但当前模型不支持 Codex，OpenClaw 会保持正常的托管 `web_search` 行为。
如果原生 Codex 搜索已启用，但当前模型不支持 Codex，OpenClaw 会保持正常的托管 `web_search` 行为。
## 设置 Web 搜索
## 网络安全
文档和设置流程中的提供商列表按字母顺序排列。自动检测使用
托管 `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`。
## 设置 web search
文档和设置流程中的提供商列表按字母顺序排列。自动检测保留
单独的优先级顺序。
如果未设置 `provider`，OpenClaw 会按以下顺序检查提供商，并使用
第一个已就绪的提供商：
首先是 API 支持的提供商：
先检查 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）
@ -175,23 +189,24 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
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** -- 无需账号或 API key 的无密钥 HTML 后备（顺序 100）
11. **Ollama Web Search** -- 当你配置的本地 Ollama 主机可访问且已通过 `ollama signin` 登录时，通过该主机提供无密钥后备；当主机需要时可复用 Ollama provider bearer auth，并且在配置 `OLLAMA_API_KEY` 后可直接调用 `https://ollama.com` 搜索（顺序 110）
10. **DuckDuckGo** -- 无需账号或 API key 的免密钥 HTML 回退方案（顺序 100）
11. **Ollama Web Search** -- 当你配置的本地 Ollama 主机可访问且已通过 `ollama signin` 登录时，通过该主机提供无需密钥的回退；当主机需要时可复用 Ollama 提供商 bearer 认证，并且在配置 `OLLAMA_API_KEY` 后可调用直接 `https://ollama.com` 搜索（顺序 110）
12. **SearXNG** -- `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（顺序 200）
如果未检测到提供商，它会回退到 Brave（你会收到缺少密钥的
错误，提示你配置一个密钥）。
如果未检测到提供商，它会回退到 Brave（你将收到缺少密钥的
错误，提示你配置一个）。
<Note>
所有提供商密钥字段都支持 SecretRef 对象。`plugins.entries.<plugin>.config.webSearch.apiKey`
下的插件作用域 SecretRef 会为内置的 API 支持 Web 搜索提供商解析，
包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily，
无论该提供商是通过 `tools.web.search.provider` 显式选择，
还是通过自动检测选中。在自动检测模式下，OpenClaw 只解析
所选提供商的密钥 -- 未选中的 SecretRef 保持非活动状态，因此你可以
保持配置多个提供商，而无需为未使用的提供商支付解析成本。
所有提供商密钥字段都支持 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 保持非活动状态，因此你可以
配置多个提供商，而无需为未使用的提供商支付解析成本。
</Note>
## 配置
@ -212,29 +227,32 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
}
```
提供商专用配置（API keys、基础 URL、模式）位于
`plugins.entries.<plugin>.config.webSearch.*` 下。Gemini 也可以在其专用 Web 搜索配置和 `GEMINI_API_KEY` 之后，以较低优先级
后备复用 `models.providers.google.apiKey` 和 `models.providers.google.baseUrl`。示例请参阅
提供商页面。
提供商特定配置（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"` 这样的拼写错误会导致配置验证失败，而不是静默回退到自动检测。如果配置的提供商只有过期的插件证据，例如卸载第三方插件后遗留的 `plugins.entries.<plugin>` 块，OpenClaw 会保持启动韧性并报告警告，以便你重新安装插件，或运行 `openclaw doctor --fix` 清理过期配置。
`tools.web.search.provider` 会根据内置和已安装插件清单声明的 Web 搜索提供商 ID 进行验证。像 `"brvae"` 这样的拼写错误会导致配置验证失败，而不是静默 fallback 到自动检测。如果已配置的提供商只有过时的插件证据，例如卸载第三方插件后遗留的
`plugins.entries.<plugin>` 块，OpenClaw 会保持启动韧性并报告警告，这样你可以重新安装插件，或运行 `openclaw doctor --fix` 清理过时配置。
`web_fetch` 回退提供商选择是独立的：
`web_fetch` fallback 提供商选择是独立的：
- 使用 `tools.web.fetch.provider` 选择它
- 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个就绪的 Web 抓取提供商
- 非沙箱隔离的 `web_fetch` 可以使用声明了 `contracts.webFetchProviders` 的已安装插件提供商；沙箱隔离的抓取保持仅限内置
- 目前内置的 Web 抓取提供商是 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 Web 搜索模型（默认为 `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 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` 提示。
当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 Grok 时，OpenClaw 还可以用相同密钥提供可选的 `x_search` 设置。
这是 Grok 路径内的一个独立后续步骤，不是单独的顶层 Web 搜索提供商选项。如果你选择其他提供商，OpenClaw 不会显示 `x_search` 提示。
### 存储 API 密钥
@ -266,22 +284,22 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
export BRAVE_API_KEY="YOUR_KEY"
```
对于 Gateway 网关安装，请将它放入 `~/.openclaw/.env`。
请参阅[环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。
对于 Gateway 网关安装，请将其放入 `~/.openclaw/.env`。
请参见 [环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。
</Tab>
</Tabs>
## 工具参数
| 参数 | 描述 |
| --------------------- | ----------------------------------------------------- |
| `query` | 搜索查询（必需） |
| `count` | 要返回的结果数（1-10，默认值：5） |
| `country` | 2 字母 ISO 国家/地区代码（例如 "US"、"DE"） |
| `language` | ISO 639-1 语言代码（例如 "en"、"de"） |
| 参数 | 描述 |
| --------------------- | ------------------------------------------------------ |
| `query` | 搜索查询（必填） |
| `count` | 要返回的结果数（1-10，默认值：5） |
| `country` | 2 字母 ISO 国家/地区代码（例如 "US"、"DE"） |
| `language` | ISO 639-1 语言代码（例如 "en"、"de"） |
| `search_lang` | 搜索语言代码（仅 Brave） |
| `freshness` | 时间筛选：`day`、`week`、`month` 或 `year` |
| `freshness` | 时间过滤器：`day`、`week`、`month` 或 `year` |
| `date_after` | 此日期之后的结果（YYYY-MM-DD） |
| `date_before` | 此日期之前的结果（YYYY-MM-DD） |
| `ui_lang` | UI 语言代码（仅 Brave） |
@ -290,19 +308,24 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
| `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 仅对可信的私有网络或 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` 以兼容共享工具，但这不会改变有依据答案的形态。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`，高级选项请使用它们的专用工具。
</Warning>
## x_search
`x_search` 使用 xAI 查询 X（前 Twitter）帖子，并返回带引用的 AI 综合答案。它接受自然语言查询和可选的结构化筛选器。OpenClaw 仅在服务此工具调用的请求上启用内置 xAI `x_search` 工具。
`x_search` 使用 xAI 查询 X（原 Twitter）帖子，并返回带引用的 AI 合成答案。它接受自然语言查询和可选的结构化过滤器。OpenClaw 仅在处理此工具调用的请求上启用内置 xAI `x_search`
工具。
<Note>
xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户搜索和线程抓取。对于转发、回复、书签或浏览量等单帖互动统计，优先针对确切帖子 URL 或状态 ID 进行定向查询。广泛的关键词搜索可能找到正确帖子，但返回的单帖元数据可能不够完整。一个好的模式是：先定位帖子，然后运行第二个聚焦于该确切帖子的 `x_search` 查询。
xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户搜索和主题串抓取。对于每个帖子的互动统计，例如转发、回复、收藏或浏览量，优先对精确帖子 URL
或状态 ID 进行定向查找。宽泛的关键词搜索可能找到正确帖子，但返回的每帖元数据不够完整。一个好的模式是：先定位帖子，然后运行第二个聚焦于该精确帖子的 `x_search` 查询。
</Note>
### x_search 配置
@ -333,19 +356,19 @@ OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于
}
```
当设置了 `plugins.entries.xai.config.xSearch.baseUrl` 时，`x_search` 会向 `<baseUrl>/responses` 发送请求。如果省略该字段，它会回退到 `plugins.entries.xai.config.webSearch.baseUrl`，然后是旧版 `tools.web.search.grok.baseUrl`，最后是公共 xAI 端点。
设置 `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 检查匹配帖子附带的视频 |
| 参数 | 描述 |
| ---------------------------- | ------------------------------------------------------ |
| `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 示例
@ -406,6 +429,6 @@ 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 主机进行免密钥 Web 搜索