chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
1ba6cd5c1e
commit
5bb8dff807
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要一份按提供商划分的模型设置参考
|
||||
- 你想要模型提供商的示例配置或 CLI 新手引导命令
|
||||
- 你需要模型提供商的示例配置或 CLI 新手引导命令
|
||||
sidebarTitle: Model providers
|
||||
summary: 模型提供商概览，包含示例配置和 CLI 流程
|
||||
summary: 模型提供商概览，含示例配置 + CLI 流程
|
||||
title: 模型提供商
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T04:06:10Z"
|
||||
generated_at: "2026-04-29T16:29:06Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: ee6c7fc1a87ec8db7df291ac87281e13b43b0b4e2076e1084698932b9a3bf1b9
|
||||
source_hash: 3902194674d6d4e17a8477c28addb39b8e04c3b498eb6a0305e82c2f1b5d737e
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
**LLM/模型提供商**参考（不是 WhatsApp/Telegram 这样的聊天渠道）。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
|
||||
模型提供商（而不是 WhatsApp/Telegram 这样的聊天渠道）的 **LLM/模型提供商**参考。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
|
||||
|
||||
## 快速规则
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="模型引用和 CLI 辅助命令">
|
||||
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
|
||||
- 设置 `agents.defaults.models` 后，它会作为允许列表。
|
||||
- 设置后，`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)。
|
||||
@ -30,19 +30,19 @@ x-i18n:
|
||||
<Accordion title="OpenAI provider/运行时拆分">
|
||||
OpenAI 系列路由按前缀区分：
|
||||
|
||||
- `openai/<model>` 使用 PI 中直接的 OpenAI API key 提供商。
|
||||
- `openai/<model>` 使用 PI 中的直接 OpenAI API key 提供商。
|
||||
- `openai-codex/<model>` 使用 PI 中的 Codex OAuth。
|
||||
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex app-server harness。
|
||||
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。
|
||||
|
||||
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [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>` 引用启用。
|
||||
|
||||
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API key 流量，通过 PI 中的 `openai-codex/gpt-5.5` 用于 Codex OAuth，并在设置 `agentRuntime.id: "codex"` 时通过原生 Codex app-server harness 使用。
|
||||
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API key 流量，通过 PI 中的 `openai-codex/gpt-5.5` 用于 Codex OAuth，并且在设置 `agentRuntime.id: "codex"` 时可用于原生 Codex 应用服务器 harness。
|
||||
|
||||
</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/*` 引用会迁移回规范提供商引用，并单独记录运行时。
|
||||
|
||||
@ -51,57 +51,57 @@ x-i18n:
|
||||
|
||||
## 插件拥有的提供商行为
|
||||
|
||||
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置文件等。
|
||||
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置等。
|
||||
|
||||
提供商 SDK 钩子和内置插件示例的完整列表位于[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于一个单独、更深入的扩展表面。
|
||||
提供商 SDK 钩子和内置插件示例的完整列表位于 [Provider plugins](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于独立且更深层的扩展表面。
|
||||
|
||||
<Note>
|
||||
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助工具。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑已不再读取它。
|
||||
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助函数。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容，shared runner 逻辑不再读取它。
|
||||
</Note>
|
||||
|
||||
## API key 轮换
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="key 来源和优先级">
|
||||
通过以下方式配置多个 key：
|
||||
<Accordion title="密钥来源和优先级">
|
||||
通过以下方式配置多个密钥：
|
||||
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
|
||||
- `<PROVIDER>_API_KEYS`（逗号或分号列表）
|
||||
- `<PROVIDER>_API_KEY`（主 key）
|
||||
- `<PROVIDER>_API_KEY`（主密钥）
|
||||
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
|
||||
|
||||
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。key 选择顺序会保留优先级并去重值。
|
||||
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并对值去重。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="何时触发轮换">
|
||||
- 仅在限速响应时才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
|
||||
- 非限速失败会立即失败；不会尝试 key 轮换。
|
||||
- 当所有候选 key 都失败时，会返回最后一次尝试的最终错误。
|
||||
<Accordion title="轮换何时触发">
|
||||
- 仅在速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
|
||||
- 非速率限制故障会立即失败；不会尝试密钥轮换。
|
||||
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 内置提供商（pi-ai 目录）
|
||||
|
||||
OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型。
|
||||
OpenClaw 随附 pi-ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择模型。
|
||||
|
||||
### OpenAI
|
||||
|
||||
- 提供商：`openai`
|
||||
- 凭证：`OPENAI_API_KEY`
|
||||
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_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` 验证账号/模型可用性。
|
||||
- CLI：`openclaw onboard --auth-choice openai-api-key`
|
||||
- 默认传输协议是 `auto`（WebSocket 优先，SSE 回退）
|
||||
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- 默认传输协议为 `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` 启用
|
||||
- 可以通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
|
||||
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority`
|
||||
- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
|
||||
- 当你需要显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
|
||||
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不应用于通用 OpenAI 兼容代理
|
||||
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示，以及 OpenAI reasoning 兼容的载荷整形；代理路由不会
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
|
||||
- 原生 OpenAI 路由还会保留 Responses 的 `store`、prompt-cache 提示，以及 OpenAI reasoning-compat 负载整形；代理路由不会
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -112,15 +112,18 @@ OpenClaw 随附 pi‑ai 目录。这些提供商**不需要** `models.providers`
|
||||
### Anthropic
|
||||
|
||||
- 提供商：`anthropic`
|
||||
- 凭证：`ANTHROPIC_API_KEY`
|
||||
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_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`）
|
||||
- 首选 Claude CLI 配置会保持模型引用规范化，并单独选择 CLI 后端：`anthropic/claude-opus-4-7` 搭配 `agents.defaults.agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 引用仍可用于兼容。
|
||||
- 直接的公共 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
|
||||
@ -132,21 +135,21 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被
|
||||
### OpenAI Codex OAuth
|
||||
|
||||
- 提供商：`openai-codex`
|
||||
- 凭证：OAuth（ChatGPT）
|
||||
- 认证：OAuth（ChatGPT）
|
||||
- PI 模型引用：`openai-codex/gpt-5.5`
|
||||
- 原生 Codex app-server harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"`
|
||||
- 原生 Codex app-server harness 引用：`openai/gpt-5.5`，并设置 `agents.defaults.agentRuntime.id: "codex"`
|
||||
- 原生 Codex app-server harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
|
||||
- 旧版模型引用：`codex/gpt-*`
|
||||
- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex app-server 插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。
|
||||
- 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`）
|
||||
- 默认传输协议为 `auto`（优先 WebSocket，回退到 SSE）
|
||||
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- `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 Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。
|
||||
- 当你想使用 Codex OAuth/订阅路由时，请使用 `openai-codex/gpt-5.5`；当你的 API-key 设置和本地目录公开公共 API 路由时，请使用 `openai/gpt-5.5`。
|
||||
- 与直接 `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 OAuth/订阅路由时，请使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录公开公共 API 路由时，请使用 `openai/gpt-5.5`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -169,20 +172,20 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被
|
||||
### 其他订阅式托管选项
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="GLM models" href="/zh-CN/providers/glm">
|
||||
<Card title="GLM 模型" href="/zh-CN/providers/glm">
|
||||
Z.AI Coding Plan 或通用 API 端点。
|
||||
</Card>
|
||||
<Card title="MiniMax" href="/zh-CN/providers/minimax">
|
||||
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`
|
||||
@ -197,28 +200,28 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被
|
||||
### Google Gemini（API key）
|
||||
|
||||
- 提供商：`google`
|
||||
- 凭证：`GEMINI_API_KEY`
|
||||
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖项）
|
||||
- 认证：`GEMINI_API_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
|
||||
|
||||
- 提供商：`google-vertex`、`google-gemini-cli`
|
||||
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
|
||||
<Warning>
|
||||
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遇到 Google 账号限制。请查阅 Google 条款；如果选择继续，请使用非关键账号。
|
||||
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后受到 Google 账号限制。如果你选择继续，请查阅 Google 条款并使用非关键账号。
|
||||
</Warning>
|
||||
|
||||
Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
|
||||
Gemini CLI OAuth 作为内置 `google` 插件的一部分交付。
|
||||
|
||||
<Steps>
|
||||
<Step title="Install Gemini CLI">
|
||||
<Step title="安装 Gemini CLI">
|
||||
<Tabs>
|
||||
<Tab title="brew">
|
||||
```bash
|
||||
@ -232,27 +235,27 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Step>
|
||||
<Step title="Enable plugin">
|
||||
<Step title="启用插件">
|
||||
```bash
|
||||
openclaw plugins enable google
|
||||
```
|
||||
</Step>
|
||||
<Step title="Login">
|
||||
<Step title="登录">
|
||||
```bash
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
|
||||
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不要**把客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置档案中。
|
||||
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不会**把客户端 ID 或密钥粘贴进 `openclaw.json`。CLI 登录流程会把令牌存储在 Gateway 网关主机上的凭证配置文件中。
|
||||
|
||||
</Step>
|
||||
<Step title="Set project (if needed)">
|
||||
<Step title="设置项目（如需要）">
|
||||
如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw `cacheRead`。
|
||||
|
||||
### Z.AI (GLM)
|
||||
### Z.AI（GLM）
|
||||
|
||||
- 提供商：`zai`
|
||||
- 凭证：`ZAI_API_KEY`
|
||||
@ -261,85 +264,88 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
|
||||
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
|
||||
- `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`
|
||||
- 基础 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`；实时 `https://api.kilo.ai/api/gateway/models` 设备发现可以进一步扩展运行时目录。
|
||||
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 拥有，不在 OpenClaw 中硬编码。
|
||||
|
||||
设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
|
||||
请参阅 [/providers/kilocode](/zh-CN/providers/kilocode) 了解设置详情。
|
||||
|
||||
### 其他内置提供商插件
|
||||
|
||||
| 提供商 | ID | 认证环境变量 | 示例模型 |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` |
|
||||
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
|
||||
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
|
||||
| Groq | `groq` | `GROQ_API_KEY` | — |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
|
||||
| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
|
||||
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
|
||||
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
|
||||
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
|
||||
| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` |
|
||||
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` |
|
||||
| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` |
|
||||
| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` |
|
||||
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
|
||||
| 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` |
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
| 提供商 | ID | 凭证环境变量 | 示例模型 |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` |
|
||||
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
|
||||
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
|
||||
| Groq | `groq` | `GROQ_API_KEY` | — |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
|
||||
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
|
||||
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
|
||||
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
|
||||
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
|
||||
| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/nemotron-3-super-120b-a12b` |
|
||||
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` |
|
||||
| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` |
|
||||
| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` |
|
||||
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
|
||||
| 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` |
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
|
||||
#### 值得了解的细节
|
||||
#### 值得了解的特殊情况
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenRouter">
|
||||
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管的提示缓存的缓存 TTL 条件，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的塑形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容性）。Gemini 后端引用只保留代理 Gemini 思维签名清理。
|
||||
仅在已验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管提示缓存的缓存 TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整理（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 支持的引用仅保留代理 Gemini 思考签名清理。
|
||||
</Accordion>
|
||||
<Accordion title="Kilo Gateway">
|
||||
Gemini 后端引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
|
||||
Gemini 支持的引用遵循同一条代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax">
|
||||
API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。
|
||||
API 密钥新手引导会写入显式的纯文本 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 的规范键保持单前缀。
|
||||
</Accordion>
|
||||
<Accordion title="xAI">
|
||||
使用 xAI Responses 路径。`/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 路径。`/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`。
|
||||
</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 和节点来源附件路径会将图像作为原生模型输入传递，而不是作为纯文本媒体引用。
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
### Moonshot AI（Kimi）
|
||||
|
||||
Moonshot 作为内置提供商插件随附。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
|
||||
Moonshot 作为内置提供商插件随附。默认使用内置提供商，仅当你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
|
||||
|
||||
- 提供商：`moonshot`
|
||||
- 凭证：`MOONSHOT_API_KEY`
|
||||
@ -379,10 +385,10 @@ Kimi K2 模型 ID：
|
||||
|
||||
### Kimi 编码
|
||||
|
||||
Kimi 编码使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
|
||||
- 提供商：`kimi`
|
||||
- 认证：`KIMI_API_KEY`
|
||||
- 凭证：`KIMI_API_KEY`
|
||||
- 示例模型：`kimi/kimi-code`
|
||||
|
||||
```json5
|
||||
@ -394,14 +400,14 @@ Kimi 编码使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
}
|
||||
```
|
||||
|
||||
旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。
|
||||
旧版 `kimi/k2p5` 仍会作为兼容模型 ID 被接受。
|
||||
|
||||
### Volcano Engine（Doubao）
|
||||
### 火山引擎（豆包）
|
||||
|
||||
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
|
||||
火山引擎（Volcano Engine）在中国提供对豆包和其他模型的访问。
|
||||
|
||||
- 提供商：`volcengine`（编码：`volcengine-plan`）
|
||||
- 认证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 凭证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 示例模型：`volcengine-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
|
||||
|
||||
@ -413,9 +419,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
}
|
||||
```
|
||||
|
||||
新手引导默认使用编码界面，但通用的 `volcengine/*` 目录会同时注册。
|
||||
新手引导默认使用编码界面，但通用 `volcengine/*` 目录也会同时注册。
|
||||
|
||||
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商限定选择器。
|
||||
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="标准模型">
|
||||
@ -438,10 +444,10 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
|
||||
### BytePlus（国际版）
|
||||
|
||||
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
|
||||
BytePlus ARK 为国际用户提供对与火山引擎相同模型的访问。
|
||||
|
||||
- 提供商：`byteplus`（编码：`byteplus-plan`）
|
||||
- 认证：`BYTEPLUS_API_KEY`
|
||||
- 凭证：`BYTEPLUS_API_KEY`
|
||||
- 示例模型：`byteplus-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
|
||||
|
||||
@ -453,9 +459,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
|
||||
}
|
||||
```
|
||||
|
||||
新手引导默认使用编码界面，但通用的 `byteplus/*` 目录会同时注册。
|
||||
新手引导默认使用编码界面，但通用 `byteplus/*` 目录也会同时注册。
|
||||
|
||||
在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商限定选择器。
|
||||
在新手引导/配置模型选择器中，BytePlus 凭证选项会同时优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个限定提供商范围的空选择器。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="标准模型">
|
||||
@ -508,14 +514,14 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
|
||||
|
||||
- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth`
|
||||
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
|
||||
- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api`
|
||||
- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api`
|
||||
- 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`
|
||||
|
||||
有关设置详情、模型选项和配置片段，请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
|
||||
|
||||
<Note>
|
||||
在 MiniMax 的兼容 Anthropic 的流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用 thinking，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
在 MiniMax 兼容 Anthropic 的流式传输路径上，除非你显式设置，OpenClaw 默认会禁用思考，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
</Note>
|
||||
|
||||
插件拥有的能力拆分：
|
||||
@ -527,13 +533,13 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio 作为内置提供商插件发布，使用原生 API：
|
||||
LM Studio 作为内置提供商插件交付，并使用原生 API：
|
||||
|
||||
- 提供商：`lmstudio`
|
||||
- 凭证：`LM_API_TOKEN`
|
||||
- 默认推理基础 URL：`http://localhost:1234/v1`
|
||||
|
||||
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
|
||||
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的 ID 之一）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -543,11 +549,11 @@ LM Studio 作为内置提供商插件发布，使用原生 API：
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。有关设置和故障排除，请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
|
||||
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。有关设置和故障排除，请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：
|
||||
Ollama 作为内置提供商插件交付，并使用 Ollama 的原生 API：
|
||||
|
||||
- 提供商：`ollama`
|
||||
- 凭证：不需要（本地服务器）
|
||||
@ -567,23 +573,23 @@ 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"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的 ID 之一）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -597,19 +603,19 @@ export VLLM_API_KEY="vllm-local"
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang 作为内置提供商插件发布，用于快速的自托管兼容 OpenAI 的服务器：
|
||||
SGLang 作为内置提供商插件交付，用于快速的自托管 OpenAI 兼容服务器：
|
||||
|
||||
- 提供商：`sglang`
|
||||
- 凭证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:30000/v1`
|
||||
|
||||
要在本地选择启用自动设备发现（如果你的服务器不强制凭证，任何值都可以）：
|
||||
要在本地选择启用自动发现（如果你的服务器不强制要求凭证，任何值都可以）：
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的 ID 之一）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -667,18 +673,18 @@ export SGLANG_API_KEY="sglang-local"
|
||||
- `contextWindow: 200000`
|
||||
- `maxTokens: 8192`
|
||||
|
||||
推荐：设置与你的代理/模型限制匹配的显式值。
|
||||
建议：设置与你的代理/模型限制匹配的显式值。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="代理路由整形规则">
|
||||
- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl`，且其主机不是 `api.openai.com`），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 中止时间，而不会增加整个 Agent 运行时超时。
|
||||
<Accordion title="代理路由塑形规则">
|
||||
- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl`，且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
|
||||
- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求塑形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 OpenClaw 归因标头。
|
||||
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求正文中。
|
||||
- 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
|
||||
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、标头、正文流式传输以及总的受保护 fetch 中止时间，而不会增加整个 Agent 运行时超时。
|
||||
- 如果 `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"]`。
|
||||
- 为了安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
|
||||
- 对于非直连端点上的 `api: "anthropic-messages"`（canonical `anthropic` 以外的任何提供商，或自定义 `models.providers.anthropic.baseUrl`，且其主机不是公共 `api.anthropic.com` 端点），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不受支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -693,7 +699,7 @@ openclaw models list
|
||||
|
||||
另请参阅：[配置](/zh-CN/gateway/configuration)，了解完整配置示例。
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
|
||||
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
|
||||
|
||||
@ -1,35 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中免费使用开放模型
|
||||
- 你需要设置 `NVIDIA_API_KEY`
|
||||
summary: 在 OpenClaw 中使用 NVIDIA 与 OpenAI 兼容的 API
|
||||
- 你需要设置 NVIDIA_API_KEY
|
||||
summary: 在 OpenClaw 中使用 NVIDIA 的 OpenAI 兼容 API
|
||||
title: NVIDIA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:01:10Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T16:28:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2d056be5be012be537ba5c4d5812ea15ec440e5a552b235854e2078064376192
|
||||
source_hash: 297cc25cf5235bb51f3962c2a1b8799ca6544d57e701c42e9b1e1c7d881ad32b
|
||||
source_path: providers/nvidia.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
NVIDIA 在 `https://integrate.api.nvidia.com/v1` 提供了一个与 OpenAI 兼容的 API，
|
||||
可免费使用开放模型。请使用来自
|
||||
[build.nvidia.com](https://build.nvidia.com/settings/api-keys) 的 API key 进行身份验证。
|
||||
NVIDIA 在 `https://integrate.api.nvidia.com/v1` 提供 OpenAI 兼容 API，可免费使用开放模型。使用来自 [build.nvidia.com](https://build.nvidia.com/settings/api-keys) 的 API 密钥进行身份验证。
|
||||
|
||||
## 快速开始
|
||||
## 入门指南
|
||||
|
||||
<Steps>
|
||||
<Step title="获取你的 API key">
|
||||
在 [build.nvidia.com](https://build.nvidia.com/settings/api-keys) 创建一个 API key。
|
||||
<Step title="获取你的 API 密钥">
|
||||
在 [build.nvidia.com](https://build.nvidia.com/settings/api-keys) 创建一个 API 密钥。
|
||||
</Step>
|
||||
<Step title="导出 key 并运行新手引导">
|
||||
<Step title="导出密钥并运行新手引导">
|
||||
```bash
|
||||
export NVIDIA_API_KEY="nvapi-..."
|
||||
openclaw onboard --auth-choice skip
|
||||
openclaw onboard --auth-choice nvidia-api-key
|
||||
```
|
||||
</Step>
|
||||
<Step title="设置一个 NVIDIA 模型">
|
||||
<Step title="设置 NVIDIA 模型">
|
||||
```bash
|
||||
openclaw models set nvidia/nvidia/nemotron-3-super-120b-a12b
|
||||
```
|
||||
@ -37,10 +35,15 @@ NVIDIA 在 `https://integrate.api.nvidia.com/v1` 提供了一个与 OpenAI 兼
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
如果你传入 `--token` 而不是使用环境变量，该值会出现在 shell 历史记录和
|
||||
`ps` 输出中。能用时请优先使用 `NVIDIA_API_KEY` 环境变量。
|
||||
如果你传入 `--nvidia-api-key` 而不是环境变量，该值会进入 shell 历史记录和 `ps` 输出。尽可能优先使用 `NVIDIA_API_KEY` 环境变量。
|
||||
</Warning>
|
||||
|
||||
对于非交互式设置，你也可以直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice nvidia-api-key --nvidia-api-key "nvapi-..."
|
||||
```
|
||||
|
||||
## 配置示例
|
||||
|
||||
```json5
|
||||
@ -64,43 +67,38 @@ NVIDIA 在 `https://integrate.api.nvidia.com/v1` 提供了一个与 OpenAI 兼
|
||||
|
||||
## 内置目录
|
||||
|
||||
| 模型引用 | 名称 | 上下文 | 最大输出 |
|
||||
| ------------------------------------------ | ---------------------------- | ------- | ---------- |
|
||||
| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 |
|
||||
| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 |
|
||||
| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 |
|
||||
| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 |
|
||||
| 模型 ref | 名称 | 上下文 | 最大输出 |
|
||||
| ------------------------------------------ | ---------------------------- | ------- | -------- |
|
||||
| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 |
|
||||
| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 |
|
||||
| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 |
|
||||
| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 |
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="自动启用行为">
|
||||
当设置了 `NVIDIA_API_KEY` 环境变量时，该提供商会自动启用。
|
||||
除了 key 之外，无需显式提供商配置。
|
||||
当设置了 `NVIDIA_API_KEY` 环境变量时，提供商会自动启用。除了密钥以外，不需要显式的提供商配置。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="目录与定价">
|
||||
内置目录是静态的。由于 NVIDIA 目前为列出的模型提供免费 API 访问，
|
||||
因此源码中的成本默认值为 `0`。
|
||||
<Accordion title="目录和定价">
|
||||
内置目录是静态的。由于 NVIDIA 目前为列出的模型提供免费 API 访问权限，源代码中的成本默认值为 `0`。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="与 OpenAI 兼容的端点">
|
||||
NVIDIA 使用标准的 `/v1` completions 端点。任何与 OpenAI 兼容的
|
||||
工具通常都可以直接配合 NVIDIA base URL 使用。
|
||||
<Accordion title="OpenAI 兼容端点">
|
||||
NVIDIA 使用标准的 `/v1` 补全端点。任何 OpenAI 兼容工具都应可直接配合 NVIDIA base URL 使用。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Tip>
|
||||
NVIDIA 模型目前可免费使用。最新可用性和
|
||||
速率限制详情请查看
|
||||
[build.nvidia.com](https://build.nvidia.com/)。
|
||||
NVIDIA 模型目前可免费使用。请查看 [build.nvidia.com](https://build.nvidia.com/) 获取最新的可用性和速率限制详情。
|
||||
</Tip>
|
||||
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择提供商、模型引用和故障转移行为。
|
||||
选择提供商、模型 ref 和故障转移行为。
|
||||
</Card>
|
||||
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference" icon="gear">
|
||||
智能体、模型和提供商的完整配置参考。
|
||||
|
||||
@ -5,17 +5,17 @@ read_when:
|
||||
summary: Exec 工具用法、stdin 模式和 TTY 支持
|
||||
title: 执行工具
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T12:05:40Z"
|
||||
generated_at: "2026-04-29T16:29:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d951a4e73cc854d767c1084de9054d1c07857599c6f6c5e3f6a00b718b768c51
|
||||
source_hash: 7949cfde9f141202a3bc36c2be72ecdf6d43305b5f16fb02835a69bcaa46067b
|
||||
source_path: tools/exec.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
在工作区中运行 shell 命令。通过 `process` 支持前台 + 后台执行。
|
||||
如果 `process` 被禁用，`exec` 会同步运行，并忽略 `yieldMs`/`background`。
|
||||
后台会话按智能体划定作用域；`process` 只能看到同一智能体的会话。
|
||||
如果 `process` 被禁用，`exec` 会同步运行并忽略 `yieldMs`/`background`。
|
||||
后台会话按智能体划分作用域；`process` 只能看到同一智能体创建的会话。
|
||||
|
||||
## 参数
|
||||
|
||||
@ -28,11 +28,11 @@ x-i18n:
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="env" type="object">
|
||||
合并到继承环境之上的键/值环境覆盖项。
|
||||
叠加到继承环境上的键/值环境覆盖。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="yieldMs" type="number" default="10000">
|
||||
在此延迟（毫秒）后自动将命令转入后台。
|
||||
经过此延迟（毫秒）后自动将命令转入后台。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="background" type="boolean" default="false">
|
||||
@ -40,19 +40,19 @@ x-i18n:
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="timeout" type="number" default="tools.exec.timeoutSec">
|
||||
覆盖本次调用配置的 exec 超时时间。仅当命令应在没有 exec 进程超时的情况下运行时，才设置 `timeout: 0`。
|
||||
覆盖此次调用配置的 exec 超时。仅当命令应在没有 exec 进程超时的情况下运行时，才设置 `timeout: 0`。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="pty" type="boolean" default="false">
|
||||
在可用时在伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
|
||||
可用时在伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
|
||||
执行位置。`auto` 会在沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`。
|
||||
执行位置。当沙箱运行时处于活动状态时，`auto` 解析为 `sandbox`，否则解析为 `gateway`。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
|
||||
`gateway` / `node` 执行的强制执行模式。
|
||||
`gateway` / `node` 执行的强制模式。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
|
||||
@ -60,61 +60,52 @@ x-i18n:
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="node" type="string">
|
||||
`host=node` 时的节点 id/名称。
|
||||
当 `host=node` 时的节点 ID/名称。
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="elevated" type="boolean" default="false">
|
||||
请求提升模式 — 跳出沙箱并进入配置的主机路径。仅当 elevated 解析为 `full` 时，才会强制使用 `security=full`。
|
||||
请求提升模式 —— 逃离沙箱并进入配置的主机路径。只有当 elevated 解析为 `full` 时，才会强制 `security=full`。
|
||||
</ParamField>
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- `host` 默认为 `auto`：当会话的沙箱运行时处于活动状态时使用沙箱，否则使用 Gateway 网关。
|
||||
- `auto` 是默认路由策略，不是通配符。允许从 `auto` 按调用指定 `host=node`；只有在没有沙箱运行时处于活动状态时，才允许按调用指定 `host=gateway`。
|
||||
- 在没有额外配置的情况下，`host=auto` 仍然“即用即通”：没有沙箱意味着它解析为 `gateway`；有活动沙箱意味着它留在沙箱中。
|
||||
- `elevated` 会跳出沙箱并进入配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认值为 `host=node`）时是 `node`。它仅在当前会话/提供商启用了提升访问权限时可用。
|
||||
- `host` 只接受 `auto`、`sandbox`、`gateway` 或 `node`。它不是主机名选择器；类似主机名的值会在命令运行前被拒绝。
|
||||
- `auto` 是默认路由策略，不是通配符。允许从 `auto` 按调用设置 `host=node`；只有在没有活动沙箱运行时时，才允许按调用设置 `host=gateway`。
|
||||
- 无需额外配置，`host=auto` 仍然“直接可用”：没有沙箱时解析为 `gateway`；存在实时沙箱时则留在沙箱中。
|
||||
- `elevated` 会逃离沙箱并进入配置的主机路径：默认是 `gateway`，当 `tools.exec.host=node`（或会话默认值为 `host=node`）时为 `node`。仅当当前会话/提供商启用了 elevated 访问时才可用。
|
||||
- `gateway`/`node` 审批由 `~/.openclaw/exec-approvals.json` 控制。
|
||||
- `node` 需要已配对的节点（配套应用或无头节点主机）。
|
||||
- 如果有多个可用节点，请设置 `exec.node` 或 `tools.exec.node` 来选择一个。
|
||||
- `exec host=node` 是节点唯一的 shell 执行路径；旧版 `nodes.run` 包装器已移除。
|
||||
- `timeout` 适用于前台、后台、`yieldMs`、Gateway 网关、沙箱和节点 `system.run` 执行。如果省略，OpenClaw 会使用 `tools.exec.timeoutSec`；显式的 `timeout: 0` 会为该调用禁用 exec 进程超时。
|
||||
- 在非 Windows 主机上，exec 会在设置了 `SHELL` 时使用它；如果 `SHELL` 是 `fish`，它会优先使用 `PATH`
|
||||
中的 `bash`（或 `sh`）以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 `SHELL`。
|
||||
- 在 Windows 主机上，exec 会优先发现 PowerShell 7（`pwsh`）（Program Files、ProgramW6432，然后是 PATH），
|
||||
然后回退到 Windows PowerShell 5.1。
|
||||
- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖项（`LD_*`/`DYLD_*`），以
|
||||
防止二进制劫持或代码注入。
|
||||
- OpenClaw 会在生成的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），这样 shell/profile 规则就能检测 exec 工具上下文。
|
||||
- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 来选择一个。
|
||||
- `exec host=node` 是节点唯一的 shell 执行路径；旧版 `nodes.run` 包装器已被移除。
|
||||
- `timeout` 适用于前台、后台、`yieldMs`、Gateway 网关、沙箱和节点 `system.run` 执行。如果省略，OpenClaw 使用 `tools.exec.timeoutSec`；显式 `timeout: 0` 会禁用该次调用的 exec 进程超时。
|
||||
- 在非 Windows 主机上，exec 会在已设置时使用 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 使用 `bash`（或 `sh`），以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 `SHELL`。
|
||||
- 在 Windows 主机上，exec 优先发现 PowerShell 7（`pwsh`）（Program Files、ProgramW6432，然后是 PATH），然后回退到 Windows PowerShell 5.1。
|
||||
- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或代码注入。
|
||||
- OpenClaw 会在生成的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），以便 shell/profile 规则可以检测 exec 工具上下文。
|
||||
- `openclaw channels login` 会被 `exec` 阻止，因为它是交互式渠道认证流程；请在 Gateway 网关主机上的终端中运行它，或在存在渠道原生登录工具时从聊天中使用该工具。
|
||||
- 重要：沙箱隔离**默认关闭**。如果沙箱隔离关闭，隐式 `host=auto`
|
||||
会解析为 `gateway`。显式 `host=sandbox` 仍会安全失败，而不是静默
|
||||
在 Gateway 网关主机上运行。启用沙箱隔离，或使用带审批的 `host=gateway`。
|
||||
- 脚本预检检查（针对常见 Python/Node shell 语法错误）只检查有效 `workdir`
|
||||
边界内的文件。如果脚本路径解析到 `workdir` 外部，则会跳过该文件的预检。
|
||||
- 对于现在开始的长时间运行工作，启动一次即可，并在启用自动
|
||||
完成唤醒且命令输出内容或失败时依赖它。
|
||||
使用 `process` 查看日志、状态、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟
|
||||
调度。
|
||||
- 对于应稍后发生或按计划发生的工作，请使用 cron，而不是
|
||||
`exec` sleep/delay 模式。
|
||||
- 重要：沙箱隔离**默认关闭**。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会关闭失败，而不是静默地在 Gateway 网关主机上运行。请启用沙箱隔离，或使用带审批的 `host=gateway`。
|
||||
- 脚本预检检查（用于常见 Python/Node shell 语法错误）只检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 外部，则会跳过该文件的预检。
|
||||
- 对于现在开始的长时间运行工作，只启动一次，并在启用时依赖命令输出或失败触发的自动完成唤醒。使用 `process` 查看日志、Status、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
|
||||
- 对于应在稍后或按计划发生的工作，请使用 cron，而不是 `exec` sleep/延迟模式。
|
||||
|
||||
## 配置
|
||||
|
||||
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，后台 exec 会话会在退出时将系统事件加入队列并请求心跳。
|
||||
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过此值时，发出一次“正在运行”通知（0 表示禁用）。
|
||||
- `tools.exec.timeoutSec`（默认：1800）：每条命令的默认 exec 超时时间（秒）。按调用设置的 `timeout` 会覆盖它；按调用设置 `timeout: 0` 会禁用 exec 进程超时。
|
||||
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，转入后台的 exec 会话会在退出时排入一个系统事件并请求心跳。
|
||||
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当受审批门控的 exec 运行超过此时间时，发出一次“运行中”通知（0 表示禁用）。
|
||||
- `tools.exec.timeoutSec`（默认：1800）：每条命令的默认 exec 超时秒数。按调用的 `timeout` 会覆盖它；按调用的 `timeout: 0` 会禁用 exec 进程超时。
|
||||
- `tools.exec.host`（默认：`auto`；当沙箱运行时处于活动状态时解析为 `sandbox`，否则解析为 `gateway`）
|
||||
- `tools.exec.security`（默认：沙箱为 `deny`，Gateway 网关 + 节点在未设置时为 `full`）
|
||||
- `tools.exec.security`（默认：沙箱为 `deny`，未设置时 Gateway 网关 + 节点为 `full`）
|
||||
- `tools.exec.ask`（默认：`off`）
|
||||
- 无审批主机 exec 是 Gateway 网关 + 节点的默认行为。如果你想要审批/允许列表行为，请同时收紧 `tools.exec.*` 和主机 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
|
||||
- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是来自 `host=auto`。如果你想强制 Gateway 网关或节点路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
|
||||
- 无审批的主机 exec 是 Gateway 网关 + 节点的默认值。如果你想要审批/允许列表行为，请同时收紧 `tools.exec.*` 和主机 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
|
||||
- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是来自 `host=auto`。如果你想强制使用 Gateway 网关或节点路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
|
||||
- 在 `security=full` 加 `ask=off` 模式下，主机 exec 会直接遵循配置的策略；没有额外的启发式命令混淆预过滤器或脚本预检拒绝层。
|
||||
- `tools.exec.node`（默认：未设置）
|
||||
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器 eval 形式（例如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`）始终需要显式审批。`allow-always` 仍可持久化良性解释器/脚本调用，但内联 eval 形式仍会每次提示。
|
||||
- `tools.exec.pathPrepend`：要为 exec 运行添加到 `PATH` 前面的目录列表（仅 Gateway 网关 + 沙箱）。
|
||||
- `tools.exec.safeBins`：仅 stdin 的安全二进制文件，无需显式允许列表条目即可运行。有关行为详情，请参见 [安全二进制文件](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。
|
||||
- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的其他显式可信目录。`PATH` 条目永远不会自动受信任。内置默认值为 `/bin` 和 `/usr/bin`。
|
||||
- `tools.exec.safeBinProfiles`：每个安全二进制文件的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
|
||||
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器 eval 形式（例如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`）始终需要显式审批。`allow-always` 仍可持久保存良性的解释器/脚本调用，但内联 eval 形式仍会每次提示。
|
||||
- `tools.exec.pathPrepend`：要为 exec 运行前置到 `PATH` 的目录列表（仅 Gateway 网关 + 沙箱）。
|
||||
- `tools.exec.safeBins`：只读 stdin 的安全二进制命令，无需显式允许列表条目即可运行。行为细节见[安全二进制命令](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。
|
||||
- `tools.exec.safeBinTrustedDirs`：额外显式信任的目录，用于 `safeBins` 路径检查。`PATH` 条目永远不会自动受信任。内置默认值是 `/bin` 和 `/usr/bin`。
|
||||
- `tools.exec.safeBinProfiles`：每个安全二进制命令的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
|
||||
|
||||
示例：
|
||||
|
||||
@ -130,14 +121,11 @@ x-i18n:
|
||||
|
||||
### PATH 处理
|
||||
|
||||
- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖项。守护进程本身仍使用最小 `PATH` 运行：
|
||||
- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍使用最小 `PATH`：
|
||||
- macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin`
|
||||
- Linux：`/usr/local/bin`、`/usr/bin`、`/bin`
|
||||
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。
|
||||
OpenClaw 会在 profile sourcing 后通过内部 env var（无 shell 插值）添加 `env.PATH` 前缀；
|
||||
`tools.exec.pathPrepend` 在这里也适用。
|
||||
- `host=node`：只会把你传入的非阻止 env 覆盖项发送到节点。主机执行会拒绝 `env.PATH` 覆盖项，并且节点主机会忽略它们。如果你需要在节点上增加 PATH 条目，
|
||||
请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
|
||||
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。OpenClaw 会在 profile sourcing 后通过内部环境变量前置 `env.PATH`（无 shell 插值）；`tools.exec.pathPrepend` 也适用于此处。
|
||||
- `host=node`：只有你传递的未被阻止的环境覆盖会发送到节点。主机执行会拒绝 `env.PATH` 覆盖，节点主机也会忽略它们。如果你需要在节点上添加 PATH 条目，请配置节点主机服务环境（systemd/launchd）或将工具安装到标准位置。
|
||||
|
||||
按智能体绑定节点（在配置中使用智能体列表索引）：
|
||||
|
||||
@ -148,9 +136,9 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
|
||||
控制 UI：Nodes 选项卡包含一个小型“Exec 节点绑定”面板，用于相同设置。
|
||||
|
||||
## 会话覆盖项（`/exec`）
|
||||
## 会话覆盖（`/exec`）
|
||||
|
||||
使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**按会话**默认值。
|
||||
使用 `/exec` 设置 `host`、`security`、`ask` 和 `node` 的**按会话**默认值。
|
||||
发送不带参数的 `/exec` 可显示当前值。
|
||||
|
||||
示例：
|
||||
@ -162,51 +150,37 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
## 授权模型
|
||||
|
||||
`/exec` 仅对**已授权发送者**生效（渠道允许列表/配对加 `commands.useAccessGroups`）。
|
||||
它只更新**会话状态**，不会写入配置。要硬性禁用 exec，请通过工具
|
||||
策略拒绝它（`tools.deny: ["exec"]` 或按智能体设置）。除非你显式设置
|
||||
`security=full` 和 `ask=off`，否则主机审批仍会适用。
|
||||
它只更新**会话状态**，不会写入配置。要硬禁用 exec，请通过工具策略拒绝它（`tools.deny: ["exec"]` 或按智能体设置）。除非你显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。
|
||||
|
||||
## Exec 审批（配套应用 / 节点主机）
|
||||
|
||||
沙箱隔离的智能体可以要求在 `exec` 于 Gateway 网关或节点主机上运行之前进行逐请求审批。
|
||||
沙箱隔离智能体可以要求在 `exec` 于 Gateway 网关或节点主机上运行前逐请求审批。
|
||||
有关策略、允许列表和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
|
||||
|
||||
当需要审批时，exec 工具会立即返回
|
||||
`status: "approval-pending"` 和审批 id。审批通过（或拒绝 / 超时）后，
|
||||
Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在
|
||||
`tools.exec.approvalRunningNoticeMs` 后仍在运行，会发出一次 `Exec running` 通知。
|
||||
在具有原生审批卡片/按钮的渠道上，智能体应优先依赖该
|
||||
原生 UI，并且仅当工具结果明确说明聊天审批不可用或手动审批是唯一
|
||||
路径时，才包含手动 `/approve` 命令。
|
||||
需要审批时，exec 工具会立即返回 `status: "approval-pending"` 和审批 ID。一旦批准（或拒绝 / 超时），Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在 `tools.exec.approvalRunningNoticeMs` 后仍在运行，则会发出一次 `Exec running` 通知。
|
||||
在带有原生审批卡片/按钮的渠道上，智能体应优先依赖该原生 UI，并且只有当工具结果明确表示聊天审批不可用或手动审批是唯一路径时，才包含手动 `/approve` 命令。
|
||||
|
||||
## 允许列表 + 安全二进制文件
|
||||
## 允许列表 + 安全二进制命令
|
||||
|
||||
手动允许列表强制执行会匹配已解析的二进制路径 glob 和裸命令名
|
||||
glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg` 时，`rg` 可以匹配
|
||||
`/opt/homebrew/bin/rg`，但不能匹配 `./rg` 或 `/tmp/rg`。
|
||||
当 `security=allowlist` 时，只有在每个管道
|
||||
片段都位于允许列表中或是安全二进制文件时，shell 命令才会自动允许。链式调用（`;`、`&&`、`||`）和重定向
|
||||
会在允许列表模式下被拒绝，除非每个顶层片段都满足
|
||||
允许列表（包括安全二进制文件）。仍不支持重定向。
|
||||
持久的 `allow-always` 信任不会绕过该规则：链式命令仍要求每个
|
||||
顶层片段都匹配。
|
||||
手动允许列表强制执行会匹配解析后的二进制路径 glob 和裸命令名 glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg` 时，`rg` 可以匹配 `/opt/homebrew/bin/rg`，但不能匹配 `./rg` 或 `/tmp/rg`。
|
||||
当 `security=allowlist` 时，只有在每个管道段都位于允许列表中或是安全二进制命令时，shell 命令才会自动允许。链接（`;`、`&&`、`||`）和重定向在允许列表模式下会被拒绝，除非每个顶级段都满足允许列表（包括安全二进制命令）。重定向仍不受支持。
|
||||
持久 `allow-always` 信任不会绕过该规则：链接命令仍要求每个顶级段都匹配。
|
||||
|
||||
`autoAllowSkills` 是 exec 审批中的一个单独便利路径。它不同于
|
||||
手动路径允许列表条目。对于严格的显式信任，请保持 `autoAllowSkills` 禁用。
|
||||
`autoAllowSkills` 是 exec 审批中的独立便捷路径。它不同于手动路径允许列表条目。若要严格显式信任，请保持 `autoAllowSkills` 禁用。
|
||||
|
||||
将这两类控制用于不同任务：
|
||||
为不同任务使用这两个控制项：
|
||||
|
||||
- `tools.exec.safeBins`：小型、仅 stdin 的流过滤器。
|
||||
- `tools.exec.safeBinTrustedDirs`：用于安全二进制文件可执行路径的显式额外可信目录。
|
||||
- `tools.exec.safeBinProfiles`：用于自定义安全二进制文件的显式 argv 策略。
|
||||
- `tools.exec.safeBins`：小型、只读 stdin 的流过滤器。
|
||||
- `tools.exec.safeBinTrustedDirs`：用于安全二进制可执行路径的显式额外信任目录。
|
||||
- `tools.exec.safeBinProfiles`：自定义安全二进制命令的显式 argv 策略。
|
||||
- allowlist：对可执行路径的显式信任。
|
||||
|
||||
不要把 `safeBins` 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式允许列表条目，并保持启用审批提示。
|
||||
不要把 `safeBins` 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式允许列表条目，并保持审批提示启用。
|
||||
当解释器/运行时 `safeBins` 条目缺少显式配置档案时，`openclaw security audit` 会发出警告，并且 `openclaw doctor --fix` 可以搭建缺失的自定义 `safeBinProfiles` 条目。
|
||||
当你显式地把 `jq` 等行为范围较广的二进制文件重新添加到 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
|
||||
如果你显式允许列入解释器，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。
|
||||
当你显式地把 `jq` 等宽行为范围的二进制文件重新添加到 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
|
||||
如果你显式允许列出解释器，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。
|
||||
|
||||
完整策略细节和示例请参阅 [Exec 审批](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [安全二进制文件与允许列表](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。
|
||||
有关完整策略详情和示例，请参阅 [Exec 审批](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [Safe bins 与允许列表](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。
|
||||
|
||||
## 示例
|
||||
|
||||
@ -223,7 +197,8 @@ glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg`
|
||||
{"tool":"process","action":"poll","sessionId":"<id>"}
|
||||
```
|
||||
|
||||
轮询用于按需查看 Status，而不是等待循环。如果启用了自动完成唤醒，当命令产生输出或失败时，它可以唤醒会话。
|
||||
轮询用于按需获取状态，而不是等待循环。如果启用了自动完成唤醒，
|
||||
命令在输出内容或失败时可以唤醒会话。
|
||||
|
||||
发送按键（tmux 风格）：
|
||||
|
||||
@ -239,7 +214,7 @@ glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg`
|
||||
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
|
||||
```
|
||||
|
||||
粘贴（默认带括号粘贴）：
|
||||
粘贴（默认使用括号粘贴）：
|
||||
|
||||
```json
|
||||
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
|
||||
@ -248,7 +223,8 @@ glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg`
|
||||
## apply_patch
|
||||
|
||||
`apply_patch` 是 `exec` 的子工具，用于结构化的多文件编辑。
|
||||
它默认对 OpenAI 和 OpenAI Codex 模型启用。仅当你想禁用它，或将其限制为特定模型时，才使用配置：
|
||||
它默认对 OpenAI 和 OpenAI Codex 模型启用。仅当你想禁用它或将其限制到特定模型时，
|
||||
才使用配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -260,17 +236,17 @@ glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg`
|
||||
}
|
||||
```
|
||||
|
||||
注意：
|
||||
注意事项：
|
||||
|
||||
- 仅适用于 OpenAI/OpenAI Codex 模型。
|
||||
- 工具策略仍然适用；`allow: ["write"]` 会隐式允许 `apply_patch`。
|
||||
- 配置位于 `tools.exec.applyPatch` 下。
|
||||
- `tools.exec.applyPatch.enabled` 默认为 `true`；将其设置为 `false` 可为 OpenAI 模型禁用该工具。
|
||||
- `tools.exec.applyPatch.workspaceOnly` 默认为 `true`（限制在工作区内）。只有在你有意让 `apply_patch` 写入/删除工作区目录之外的内容时，才将其设置为 `false`。
|
||||
- `tools.exec.applyPatch.enabled` 默认值为 `true`；将其设为 `false` 可为 OpenAI 模型禁用该工具。
|
||||
- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（限制在工作区内）。仅当你有意希望 `apply_patch` 在工作区目录之外写入/删除时，才将其设为 `false`。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门禁
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 在沙箱隔离环境中运行命令
|
||||
- [后台进程](/zh-CN/gateway/background-process) — 长时间运行的 exec 和 process 工具
|
||||
- [安全](/zh-CN/gateway/security) — 工具策略和提升访问权限
|
||||
- [安全](/zh-CN/gateway/security) — 工具策略和提权访问
|
||||
|
||||
Loading…
Reference in New Issue
Block a user