chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
9f093c6c81
commit
d315a33d14
@ -1,71 +1,71 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要一份按提供商划分的模型设置参考
|
||||
- 你想要模型提供商的示例配置或 CLI 新手引导命令
|
||||
- 你想要模型提供商的配置示例或 CLI 新手引导命令
|
||||
sidebarTitle: Model providers
|
||||
summary: 模型提供商概览，含示例配置和 CLI 流程
|
||||
summary: 模型提供商概览，包含示例配置 + CLI 流程
|
||||
title: 模型提供商
|
||||
x-i18n:
|
||||
generated_at: "2026-05-06T04:01:36Z"
|
||||
generated_at: "2026-05-06T08:42:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 304f20e10cbcd4465b7b843e398452b1b93a19cfaefd9f4d4edc213d7e003542
|
||||
source_hash: 8375caf4bacbb360e57637801d06a9d7898b36d440b82885d993b8248cd4daff
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
LLM/模型提供商（不是 WhatsApp/Telegram 之类的聊天渠道）参考。模型选择规则请参阅 [Models](/zh-CN/concepts/models)。
|
||||
LLM/模型提供商的参考（不是 WhatsApp/Telegram 这样的聊天渠道）。模型选择规则见 [Models](/zh-CN/concepts/models)。
|
||||
|
||||
## 快速规则
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="模型引用和 CLI 辅助工具">
|
||||
<Accordion title="模型引用和 CLI 辅助命令">
|
||||
- 模型引用使用 `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 会将其视为“使此模型可用”，而不是“替换当前主模型”。
|
||||
添加或重新认证提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在其认证配置补丁中返回推荐的默认模型，但当主模型已存在时，configure 会将其视为“使此模型可用”，而不是“替换当前主模型”。
|
||||
|
||||
若要有意切换默认模型，请使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。
|
||||
要有意切换默认模型，请使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI provider/运行时拆分">
|
||||
OpenAI 系列路由按前缀区分：
|
||||
|
||||
- `openai/<model>` 加 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。这是通常的 ChatGPT/Codex 订阅设置。
|
||||
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。这是常见的 ChatGPT/Codex 订阅设置。
|
||||
- `openai-codex/<model>` 在 PI 中使用 Codex OAuth。
|
||||
- 不带 Codex 运行时覆盖的 `openai/<model>` 使用 PI 中的直接 OpenAI API key 提供商。
|
||||
- 没有 Codex 运行时覆盖的 `openai/<model>` 会在 PI 中使用直接的 OpenAI API 密钥提供商。
|
||||
|
||||
请参阅 [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>` 引用启用。
|
||||
|
||||
设置 `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 中，Codex OAuth 使用 `openai-codex/gpt-5.5`；当你的账户公开它时，直接 API 密钥流量在 PI 中使用 `openai/gpt-5.5`。
|
||||
|
||||
</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/*` 引用会迁移回规范提供商引用，并单独记录运行时。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 插件所有的提供商行为
|
||||
## 插件拥有的提供商行为
|
||||
|
||||
大多数提供商特定逻辑都位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置文件等。
|
||||
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置文件等。
|
||||
|
||||
完整的提供商 SDK 钩子列表和内置插件示例位于 [Provider plugins](/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` 静态包仅用于兼容性，共享 runner 逻辑不再读取它。
|
||||
</Note>
|
||||
|
||||
## API key 轮换
|
||||
## API 密钥轮换
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="密钥来源和优先级">
|
||||
@ -76,37 +76,37 @@ LLM/模型提供商（不是 WhatsApp/Telegram 之类的聊天渠道）参考。
|
||||
- `<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>
|
||||
</AccordionGroup>
|
||||
|
||||
## 内置提供商（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 密钥表现不同，请用 `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` 启用
|
||||
- 可以通过 `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 路由还会保留 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`）
|
||||
- 首选 Claude CLI 配置会保持模型引用为规范形式，并单独选择 CLI
|
||||
- 直接公开 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 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,9 +141,9 @@ 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 引用：`openai/gpt-5.5`，搭配 `agents.defaults.agentRuntime.id: "codex"`
|
||||
- 原生 Codex 应用服务器 harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
|
||||
- 旧版模型引用：`codex/gpt-*`
|
||||
- 插件边界：`openai-codex/*` 加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。
|
||||
@ -154,9 +154,10 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 使用已再次被
|
||||
- 隐藏的 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 运行时路径，请使用 `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`。
|
||||
- 策略说明：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 密钥设置和本地目录公开公共 API 路线时，使用不带 Codex 运行时覆盖的 `openai/gpt-5.5`。
|
||||
- 较旧的 `openai-codex/gpt-5.1*`、`openai-codex/gpt-5.2*` 和 `openai-codex/gpt-5.3*` 引用会被抑制，因为 ChatGPT/Codex OAuth 账户会拒绝它们；请改用 `openai-codex/gpt-5.5` 或原生 Codex 运行时路线。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -189,7 +190,7 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 使用已再次被
|
||||
Z.AI Coding Plan 或通用 API 端点。
|
||||
</Card>
|
||||
<Card title="MiniMax" href="/zh-CN/providers/minimax">
|
||||
MiniMax Coding Plan OAuth 或 API key 访问。
|
||||
MiniMax Coding Plan OAuth 或 API 密钥访问。
|
||||
</Card>
|
||||
<Card title="Qwen Cloud" href="/zh-CN/providers/qwen">
|
||||
Qwen Cloud 提供商表面，以及 Alibaba DashScope 和 Coding Plan 端点映射。
|
||||
@ -198,7 +199,7 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 使用已再次被
|
||||
|
||||
### 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`
|
||||
@ -210,31 +211,31 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 使用已再次被
|
||||
}
|
||||
```
|
||||
|
||||
### Google Gemini（API key）
|
||||
### Google Gemini（API 密钥）
|
||||
|
||||
- 提供商：`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-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`
|
||||
- 直接运行 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` 插件的一部分提供。
|
||||
|
||||
<Steps>
|
||||
<Step title="Install Gemini CLI">
|
||||
<Step title="安装 Gemini CLI">
|
||||
<Tabs>
|
||||
<Tab title="brew">
|
||||
```bash
|
||||
@ -248,57 +249,57 @@ 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`
|
||||
- 凭证：`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`
|
||||
- 认证：`AI_GATEWAY_API_KEY`
|
||||
- 凭证：`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 网关
|
||||
|
||||
- 提供商：`kilocode`
|
||||
- 认证：`KILOCODE_API_KEY`
|
||||
- 凭证：`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` |
|
||||
@ -307,9 +308,9 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
|
||||
| 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` |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `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` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` or `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` |
|
||||
@ -321,44 +322,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（豆包） | `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-compat）。Gemini 后端引用仅保留代理 Gemini 思维签名清理。
|
||||
仅在经过验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的提示缓存的 cache-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 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 兼容的 base URL 是 `https://api.cerebras.ai/v1`。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 通过 `models.providers` 使用提供商（自定义/基础 URL）
|
||||
## 通过 `models.providers` 配置提供商（自定义/base URL）
|
||||
|
||||
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
|
||||
|
||||
下面的许多内置提供商插件已经发布了默认目录。只有在你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 `models.providers.<id>` 条目。
|
||||
下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认 base 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 作为内置提供商插件发布。默认使用内置提供商；只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
|
||||
Moonshot 作为内置提供商插件交付。默认使用内置提供商；仅当你需要覆盖 base URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
|
||||
|
||||
- 提供商：`moonshot`
|
||||
- 凭证：`MOONSHOT_API_KEY`
|
||||
@ -396,7 +397,7 @@ Kimi K2 模型 ID：
|
||||
}
|
||||
```
|
||||
|
||||
### Kimi 编程
|
||||
### Kimi 编码
|
||||
|
||||
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
|
||||
@ -417,10 +418,10 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
|
||||
### Volcano Engine（Doubao）
|
||||
|
||||
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问能力。
|
||||
Volcano Engine（火山引擎）提供对 Doubao 和中国其他模型的访问。
|
||||
|
||||
- 提供商：`volcengine`（编程：`volcengine-plan`）
|
||||
- 凭证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 提供商：`volcengine`（编码：`volcengine-plan`）
|
||||
- 认证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 示例模型：`volcengine-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
|
||||
|
||||
@ -432,9 +433,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
}
|
||||
```
|
||||
|
||||
新手引导默认使用编程模型接口，但通用的 `volcengine/*` 目录也会同时注册。
|
||||
新手引导默认使用编码表面，但通用 `volcengine/*` 目录也会同时注册。
|
||||
|
||||
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先选择 `volcengine/*` 和 `volcengine-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。
|
||||
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商范围选择器。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="标准模型">
|
||||
@ -445,7 +446,7 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
|
||||
|
||||
</Tab>
|
||||
<Tab title="编程模型（volcengine-plan）">
|
||||
<Tab title="编码模型（volcengine-plan）">
|
||||
- `volcengine-plan/ark-code-latest`
|
||||
- `volcengine-plan/doubao-seed-code`
|
||||
- `volcengine-plan/kimi-k2.5`
|
||||
@ -457,10 +458,10 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
|
||||
### BytePlus（国际版）
|
||||
|
||||
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
|
||||
BytePlus ARK 为国际用户提供对与 Volcano Engine 相同模型的访问。
|
||||
|
||||
- 提供商：`byteplus`（编程：`byteplus-plan`）
|
||||
- 凭证：`BYTEPLUS_API_KEY`
|
||||
- 提供商：`byteplus`（编码：`byteplus-plan`）
|
||||
- 认证：`BYTEPLUS_API_KEY`
|
||||
- 示例模型：`byteplus-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
|
||||
|
||||
@ -472,9 +473,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
|
||||
}
|
||||
```
|
||||
|
||||
新手引导默认使用编程模型接口，但通用的 `byteplus/*` 目录也会同时注册。
|
||||
新手引导默认使用编码表面，但通用 `byteplus/*` 目录也会同时注册。
|
||||
|
||||
在新手引导/配置模型选择器中，BytePlus 凭证选项会优先选择 `byteplus/*` 和 `byteplus-plan/*` 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。
|
||||
在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商范围选择器。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="标准模型">
|
||||
@ -483,7 +484,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
|
||||
- `byteplus/glm-4-7-251222`（GLM 4.7）
|
||||
|
||||
</Tab>
|
||||
<Tab title="编程模型（byteplus-plan）">
|
||||
<Tab title="编码模型（byteplus-plan）">
|
||||
- `byteplus-plan/ark-code-latest`
|
||||
- `byteplus-plan/doubao-seed-code`
|
||||
- `byteplus-plan/kimi-k2.5`
|
||||
@ -498,7 +499,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,32 +528,32 @@ 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` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
|
||||
- MiniMax API key（全球）：`--auth-choice minimax-global-api`
|
||||
- MiniMax API key（中国）：`--auth-choice minimax-cn-api`
|
||||
- 认证：`MINIMAX_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用于 `minimax-portal`
|
||||
|
||||
设置详情、模型选项和配置片段请参阅 [/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 兼容流式传输路径上，OpenClaw 默认禁用 thinking，除非你显式设置它，并且 `/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 认证路径上都由插件拥有的 `MiniMax-VL-01`
|
||||
- Web 搜索保留在提供商 ID `minimax`
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio 作为内置提供商插件随 OpenClaw 提供，并使用原生 API：
|
||||
LM Studio 作为内置提供商插件发布，使用原生 API：
|
||||
|
||||
- 提供商：`lmstudio`
|
||||
- 凭证：`LM_API_TOKEN`
|
||||
- 默认推理 base URL：`http://localhost:1234/v1`
|
||||
- 认证：`LM_API_TOKEN`
|
||||
- 默认推理基础 URL：`http://localhost:1234/v1`
|
||||
|
||||
然后设置模型（替换为 `http://localhost:1234/api/v1/models` 返回的 ID 之一）：
|
||||
然后设置模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -562,14 +563,14 @@ LM Studio 作为内置提供商插件随 OpenClaw 提供，并使用原生 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 作为内置提供商插件随 OpenClaw 提供，并使用 Ollama 的原生 API：
|
||||
Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：
|
||||
|
||||
- 提供商：`ollama`
|
||||
- 凭证：无需凭证（本地服务器）
|
||||
- 认证：无需（本地服务器）
|
||||
- 示例模型：`ollama/llama3.3`
|
||||
- 安装：[https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
@ -586,23 +587,23 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
当你使用 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地的 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会把 Ollama 直接添加到 `openclaw onboard` 和模型选择器。新手引导、云端/本地模式和自定义配置请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
|
||||
当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器。请参阅 [/providers/ollama](/zh-CN/providers/ollama) 了解新手引导、云端/本地模式和自定义配置。
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM 作为面向本地/自托管 OpenAI 兼容服务器的内置提供商插件随 OpenClaw 提供：
|
||||
vLLM 作为本地/自托管 OpenAI 兼容服务器的内置提供商插件发布：
|
||||
|
||||
- 提供商：`vllm`
|
||||
- 凭证：可选（取决于你的服务器）
|
||||
- 默认 base URL：`http://127.0.0.1:8000/v1`
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:8000/v1`
|
||||
|
||||
要在本地选择启用自动发现（如果你的服务器不强制认证，任意值都可以）：
|
||||
要在本地选择启用自动设备发现（如果你的服务器不强制认证，任意值都可用）：
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
然后设置模型（替换为 `/v1/models` 返回的 ID 之一）：
|
||||
然后设置模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -612,23 +613,23 @@ export VLLM_API_KEY="vllm-local"
|
||||
}
|
||||
```
|
||||
|
||||
详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
|
||||
请参阅 [/providers/vllm](/zh-CN/providers/vllm) 了解详情。
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang 作为面向快速自托管 OpenAI 兼容服务器的内置提供商插件随 OpenClaw 提供：
|
||||
SGLang 作为快速自托管 OpenAI 兼容服务器的内置提供商插件发布：
|
||||
|
||||
- 提供商：`sglang`
|
||||
- 凭证：可选（取决于你的服务器）
|
||||
- 默认 base URL：`http://127.0.0.1:30000/v1`
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:30000/v1`
|
||||
|
||||
要在本地选择启用自动发现（如果你的服务器不强制认证，任意值都可以）：
|
||||
要在本地选择启用自动设备发现（如果你的服务器不强制认证，任意值都可用）：
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
然后设置模型（替换为 `/v1/models` 返回的 ID 之一）：
|
||||
然后设置模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -638,7 +639,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 +679,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"]`
|
||||
@ -689,16 +690,16 @@ 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 归因标头。
|
||||
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），把额外 JSON 合并进出站请求体。
|
||||
- 对于 vLLM chat-template 控制项，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
|
||||
- 对于较慢的本地模型，或远程局域网/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、标头、正文流式传输和总的受保护 fetch 中止时间，而不会增加整个智能体运行时超时。
|
||||
- 模型提供商 HTTP 调用仅允许为已配置提供商 `baseUrl` 主机名接收 Surge、Clash 和 sing-box 在 `198.18.0.0/15` 与 `fc00::/7` 中的 fake-IP DNS 应答。其他私有、环回、链路本地和元数据目标仍需要显式选择启用 `models.providers.<id>.request.allowPrivateNetwork: true`。
|
||||
- 如果 `baseUrl` 为空或被省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
|
||||
- 出于安全考虑，在非原生 `openai-completions` 端点上，即使显式设置了 `compat.supportsDeveloperRole: true`，也仍会被覆盖。
|
||||
- 对于非直连端点上的 `api: "anthropic-messages"`（除规范 `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 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 中止时间，而不会增加整个智能体运行时超时。
|
||||
- 模型提供商 HTTP 调用仅允许为已配置提供商 `baseUrl` 主机名使用 `198.18.0.0/15` 和 `fc00::/7` 中的 Surge、Clash 和 sing-box fake-IP DNS 答案。其他私有、loopback、链路本地和元数据目标仍需要显式选择启用 `models.providers.<id>.request.allowPrivateNetwork: true`。
|
||||
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
|
||||
- 为安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
|
||||
- 对非直连端点上的 `api: "anthropic-messages"`（除规范 `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>
|
||||
@ -711,11 +712,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) - 每个提供商的设置指南
|
||||
|
||||
@ -6,79 +6,79 @@ read_when:
|
||||
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T04:52:01Z"
|
||||
generated_at: "2026-05-06T08:43:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: cdffcdf53d9b17a19450c2ce47103db116e54a71a8dd432d981f5ece81cc38b3
|
||||
source_hash: b5606cafb8dfec888b922874202aa0fdcad8cbd4fec1a1e15a9074ad14bc5486
|
||||
source_path: providers/openai.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenAI 提供面向 GPT 模型的开发者 API，Codex 也可通过 OpenAI 的 Codex 客户端作为 ChatGPT 方案中的编码智能体使用。OpenClaw 将这些使用面保持分离，确保配置保持可预测。
|
||||
OpenAI 为 GPT 模型提供开发者 API，Codex 也可通过 OpenAI 的 Codex 客户端作为 ChatGPT 计划中的编码智能体使用。OpenClaw 将这些表面分开，确保配置保持可预测。
|
||||
|
||||
OpenClaw 支持三种 OpenAI 系列路由。大多数想要 Codex 行为的 ChatGPT/Codex 订阅用户应使用原生 Codex 应用服务器运行时。模型前缀选择提供商/模型名称；单独的运行时设置选择由谁执行嵌入式 Agent loop：
|
||||
|
||||
- **API key** - 使用按量计费的 OpenAI Platform 直接访问（`openai/*` 模型）
|
||||
- **API key** - 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型）
|
||||
- **带原生 Codex 运行时的 Codex 订阅** - ChatGPT/Codex 登录加 Codex 应用服务器执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
|
||||
- **通过 PI 的 Codex 订阅** - 使用普通 OpenClaw PI 运行器的 ChatGPT/Codex 登录（`openai-codex/*` 模型）
|
||||
- **通过 PI 的 Codex 订阅** - 使用常规 OpenClaw PI 运行器进行 ChatGPT/Codex 登录（`openai-codex/*` 模型）
|
||||
|
||||
OpenAI 明确支持在外部工具和 OpenClaw 这类工作流中使用订阅 OAuth。
|
||||
OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。
|
||||
|
||||
提供商、模型、运行时和渠道是彼此独立的层。如果这些标签混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再更改配置。
|
||||
提供商、模型、运行时和渠道是独立层。如果这些标签被混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再更改配置。
|
||||
|
||||
## 快速选择
|
||||
|
||||
| 目标 | 使用 | 说明 |
|
||||
| 目标 | 使用 | 说明 |
|
||||
| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
|
||||
| 带原生 Codex 运行时的 ChatGPT/Codex 订阅 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 推荐给大多数用户的 Codex 设置。使用 `openai-codex` 凭证登录。 |
|
||||
| 直接 API key 计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API key 新手引导。 |
|
||||
| 通过 PI 使用 ChatGPT/Codex 订阅凭证 | `openai-codex/gpt-5.5` | 仅在你有意使用普通 PI 运行器时使用。 |
|
||||
| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 配合使用。 |
|
||||
| 通过 PI 的 ChatGPT/Codex 订阅凭证 | `openai-codex/gpt-5.5` | 仅在你有意使用常规 PI 运行器时使用。 |
|
||||
| 图像生成或编辑 | `openai/gpt-image-2` | 可使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth。 |
|
||||
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
|
||||
|
||||
## 命名映射
|
||||
|
||||
这些名称相似，但不可互换：
|
||||
|
||||
| 你看到的名称 | 层 | 含义 |
|
||||
| 你看到的名称 | 层级 | 含义 |
|
||||
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
|
||||
| `openai-codex` | 提供商前缀 | 通过普通 OpenClaw PI 运行器使用的 OpenAI Codex OAuth/订阅路由。 |
|
||||
| `openai-codex` | 提供商前缀 | 通过常规 OpenClaw PI 运行器使用的 OpenAI Codex OAuth/订阅路由。 |
|
||||
| `codex` 插件 | 插件 | 内置 OpenClaw 插件，提供原生 Codex 应用服务器运行时和 `/codex` 聊天控制。 |
|
||||
| `agentRuntime.id: codex` | Agent runtime | 强制嵌入式轮次使用原生 Codex 应用服务器 harness。 |
|
||||
| `/codex ...` | 聊天命令集 | 从会话中绑定/控制 Codex 应用服务器线程。 |
|
||||
| `agentRuntime.id: codex` | 智能体运行时 | 强制嵌入式轮次使用原生 Codex 应用服务器 harness。 |
|
||||
| `/codex ...` | 聊天命令集 | 从对话中绑定/控制 Codex 应用服务器线程。 |
|
||||
| `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
|
||||
|
||||
这意味着配置可以有意同时包含 `openai-codex/*` 和 `codex` 插件。当你既想通过 PI 使用 Codex OAuth，又想让原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会针对这种组合发出警告，以便你确认这是有意设置；它不会重写该配置。
|
||||
这意味着配置可以有意同时包含 `openai-codex/*` 和 `codex` 插件。如果你想通过 PI 使用 Codex OAuth，同时也想提供原生 `/codex` 聊天控制，这就是有效配置。`openclaw doctor` 会对这种组合发出警告，以便你确认这是有意为之；它不会重写配置。
|
||||
|
||||
<Note>
|
||||
GPT-5.5 可通过直接 OpenAI Platform API key 访问和订阅/OAuth 路由使用。对于 ChatGPT/Codex 订阅加原生 Codex 执行，请使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。仅在通过 PI 使用 Codex OAuth 时使用 `openai-codex/gpt-5.5`；或者在不覆盖 Codex 运行时的情况下使用 `openai/gpt-5.5` 处理直接 `OPENAI_API_KEY` 流量。
|
||||
GPT-5.5 可通过直接 OpenAI Platform API key 访问和订阅/OAuth 路由使用。对于 ChatGPT/Codex 订阅加原生 Codex 执行，请使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。仅在通过 PI 使用 Codex OAuth 时使用 `openai-codex/gpt-5.5`；若不使用 Codex 运行时覆盖项，则使用 `openai/gpt-5.5` 处理直接 `OPENAI_API_KEY` 流量。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置 Codex 应用服务器插件。OpenClaw 只会在你通过 `agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时启用该插件。
|
||||
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置 Codex 应用服务器插件。只有当你通过 `agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。
|
||||
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告并保持路由不变。
|
||||
</Note>
|
||||
|
||||
## OpenClaw 功能覆盖
|
||||
|
||||
| OpenAI 能力 | OpenClaw 使用面 | Status |
|
||||
| OpenAI 能力 | OpenClaw 表面 | Status |
|
||||
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
|
||||
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
|
||||
| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
|
||||
| Codex 应用服务器 harness | 带 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
|
||||
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
|
||||
| 服务器端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
|
||||
| 图像 | `image_generate` | 是 |
|
||||
| 视频 | `video_generate` | 是 |
|
||||
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
|
||||
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
|
||||
| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | 语音通话 `realtime.provider: "openai"` / Control UI Talk | 是 |
|
||||
| 嵌入 | 记忆嵌入提供商 | 是 |
|
||||
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
|
||||
| Embeddings | 记忆嵌入提供商 | 是 |
|
||||
|
||||
## 记忆嵌入
|
||||
|
||||
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_search` 索引和查询嵌入提供支持：
|
||||
OpenClaw 可使用 OpenAI 或兼容 OpenAI 的嵌入端点，为 `memory_search` 索引和查询嵌入提供支持：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -93,32 +93,32 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
}
|
||||
```
|
||||
|
||||
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆片段和批量索引使用 `documentInputType`。完整示例见[记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
|
||||
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将这些作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆分块和批量索引使用 `documentInputType`。完整示例见[记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
|
||||
|
||||
## 入门指南
|
||||
|
||||
选择你偏好的凭证方法并按照设置步骤操作。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key（OpenAI Platform）">
|
||||
<Tab title="API key (OpenAI Platform)">
|
||||
**最适合：** 直接 API 访问和按量计费。
|
||||
|
||||
<Steps>
|
||||
<Step title="获取你的 API key">
|
||||
从 [OpenAI Platform 控制台](https://platform.openai.com/api-keys)创建或复制 API key。
|
||||
<Step title="Get your API key">
|
||||
从 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制 API key。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
<Step title="Run onboarding">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
|
||||
或直接传入 key：
|
||||
或直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型可用">
|
||||
<Step title="Verify the model is available">
|
||||
```bash
|
||||
openclaw models list --provider openai
|
||||
```
|
||||
@ -129,12 +129,12 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
|
||||
| 模型引用 | 运行时配置 | 路由 | 凭证 |
|
||||
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
|
||||
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 应用服务器 harness | Codex 应用服务器 |
|
||||
|
||||
<Note>
|
||||
`openai/*` 是直接 OpenAI API key 路由，除非你显式强制使用 Codex 应用服务器 harness。通过默认 PI 运行器使用 Codex OAuth 时使用 `openai-codex/*`；使用原生 Codex 应用服务器执行时，使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
|
||||
`openai/*` 是直接 OpenAI API key 路由，除非你显式强制使用 Codex 应用服务器 harness。通过默认 PI 运行器使用 Codex OAuth 时使用 `openai-codex/*`；使用 `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` 可进行原生 Codex 应用服务器执行。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -147,16 +147,16 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **不会**暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也不会暴露它。
|
||||
OpenClaw 不会公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也不会公开它。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Codex 订阅">
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅，通过原生 Codex 应用服务器执行，而不是单独的 API key。Codex 云需要 ChatGPT 登录。
|
||||
<Tab title="Codex subscription">
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅并通过原生 Codex 应用服务器执行，而不是使用单独的 API key。Codex cloud 需要 ChatGPT 登录。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行 Codex OAuth">
|
||||
<Step title="Run Codex OAuth">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-codex
|
||||
```
|
||||
@ -167,25 +167,25 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
对于无头或不适合回调的设置，添加 `--device-code`，使用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调：
|
||||
对于无头或不便使用回调的设置，添加 `--device-code`，以使用 ChatGPT 设备代码流程登录，而不是 localhost 浏览器回调：
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
```
|
||||
</Step>
|
||||
<Step title="使用原生 Codex 运行时">
|
||||
<Step title="Use the native Codex runtime">
|
||||
```bash
|
||||
openclaw config set plugins.entries.codex '{"enabled":true}' --strict-json --merge
|
||||
openclaw config set agents.defaults.model.primary openai/gpt-5.5
|
||||
openclaw config set agents.defaults.agentRuntime '{"id":"codex"}' --strict-json
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证 Codex 凭证可用">
|
||||
<Step title="Verify Codex auth is available">
|
||||
```bash
|
||||
openclaw models list --provider openai-codex
|
||||
```
|
||||
|
||||
Gateway 网关运行后，在聊天中发送 `/codex status` 或 `/codex models`，验证原生应用服务器运行时。
|
||||
Gateway 网关运行后，在聊天中发送 `/codex status` 或 `/codex models`，以验证原生应用服务器运行时。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -193,17 +193,21 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
|
||||
| 模型引用 | 运行时配置 | 路由 | 凭证 |
|
||||
|-----------|----------------|-------|------|
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | 原生 Codex 应用服务器 harness | Codex 登录或所选 `openai-codex` 配置文件 |
|
||||
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.4-mini` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | 原生 Codex 应用服务器 harness | Codex 登录或选定的 `openai-codex` 配置文件 |
|
||||
| `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.4-mini` | omitted / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非插件显式声明 `openai-codex` | Codex 登录 |
|
||||
|
||||
<Warning>
|
||||
不要配置旧版 `openai-codex/gpt-5.1*`、`openai-codex/gpt-5.2*` 或 `openai-codex/gpt-5.3*` 模型引用。ChatGPT/Codex OAuth 账户现在会拒绝这些模型。PI OAuth 路由请使用 `openai-codex/gpt-5.5`；原生 Codex 运行时执行请使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
|
||||
</Warning>
|
||||
|
||||
<Note>
|
||||
继续对 auth/profile 命令使用 `openai-codex` 提供商 ID。
|
||||
继续使用 `openai-codex` provider id 执行身份验证/配置文件命令。
|
||||
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。
|
||||
它不会选择或自动启用内置的 Codex app-server harness。对于常见的订阅加原生运行时设置，请使用
|
||||
`openai-codex` 登录，但保持模型引用为 `openai/gpt-5.5`，并设置
|
||||
`agentRuntime.id: "codex"`。
|
||||
它不会选择或自动启用内置的 Codex app-server harness。对于常见的
|
||||
订阅加原生运行时设置，请使用 `openai-codex` 登录，但将模型引用保持为
|
||||
`openai/gpt-5.5`，并设置 `agentRuntime.id: "codex"`。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -220,36 +224,40 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
}
|
||||
```
|
||||
|
||||
如果要改为让 Codex OAuth 保持在普通 PI runner 上，请使用
|
||||
`openai-codex/gpt-5.5`，并省略 Codex 运行时覆盖。
|
||||
如果要改为让 Codex OAuth 继续使用普通 PI 运行器，请使用
|
||||
`openai-codex/gpt-5.5` 并省略 Codex 运行时覆盖。
|
||||
|
||||
<Note>
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的 agent 认证存储中管理生成的凭证。
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的 agent 身份验证存储中管理生成的凭证。
|
||||
</Note>
|
||||
|
||||
### Status 指示器
|
||||
|
||||
聊天中的 `/status` 会显示当前会话正在使用哪个模型运行时。
|
||||
默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选择内置的 Codex app-server harness 时，`/status` 会显示
|
||||
`Runtime: OpenAI Codex`。现有会话会保留其记录的 harness ID，因此如果你希望 `/status` 反映新的 PI/Codex 选择，请在更改 `agentRuntime` 后使用
|
||||
聊天 `/status` 会显示当前会话正在使用哪个模型运行时。
|
||||
默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选择内置
|
||||
Codex app-server harness 后，`/status` 会显示
|
||||
`Runtime: OpenAI Codex`。现有会话会保留已记录的 harness id，因此如果你希望
|
||||
`/status` 反映新的 PI/Codex 选择，请在更改 `agentRuntime` 后使用
|
||||
`/new` 或 `/reset`。
|
||||
|
||||
### Doctor 警告
|
||||
|
||||
如果启用了内置 `codex` 插件，同时选择了 `openai-codex/*` 路由，
|
||||
`openclaw doctor` 会警告该模型仍然通过 PI 解析。
|
||||
只有在该 PI 订阅认证路由是有意为之时，才保持配置不变。当你想要原生 Codex app-server 执行时，请切换到 `openai/<model>` 加 `agentRuntime.id: "codex"`。
|
||||
`openclaw doctor` 会警告该模型仍通过 PI 解析。
|
||||
只有在这个 PI 订阅身份验证路由是有意使用时，才保持配置不变。
|
||||
当你想要原生 Codex app-server 执行时，请切换到 `openai/<model>` 加
|
||||
`agentRuntime.id: "codex"`。
|
||||
|
||||
### 上下文窗口上限
|
||||
|
||||
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
|
||||
OpenClaw 将模型元数据和运行时上下文上限视为不同的值。
|
||||
|
||||
对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
|
||||
|
||||
- 原生 `contextWindow`：`1000000`
|
||||
- 默认运行时 `contextTokens` 上限：`272000`
|
||||
|
||||
较小的默认上限在实践中具有更好的延迟和质量特征。使用 `contextTokens` 覆盖它：
|
||||
较小的默认上限在实践中具有更好的延迟和质量特性。可使用 `contextTokens` 覆盖它：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,41 +277,47 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
|
||||
### 目录恢复
|
||||
|
||||
当存在 `gpt-5.5` 的上游 Codex 目录元数据时，OpenClaw 会使用它。如果 live Codex 设备发现遗漏了 `openai-codex/gpt-5.5` 行，而账号已通过认证，OpenClaw 会合成该 OAuth 模型行，这样 cron、子 agent 和配置的默认模型运行就不会因
|
||||
`Unknown model` 而失败。
|
||||
当存在 `gpt-5.5` 的上游 Codex 目录元数据时，OpenClaw 会使用它。
|
||||
如果实时 Codex 发现省略了 `openai-codex/gpt-5.5` 行，而账户已完成身份验证，
|
||||
OpenClaw 会合成该 OAuth 模型行，以便 cron、sub-agent 和已配置的默认模型运行不会因
|
||||
`Unknown model` 失败。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 原生 Codex app-server 认证
|
||||
## 原生 Codex app-server 身份验证
|
||||
|
||||
原生 Codex app-server harness 使用 `openai/*` 模型引用加
|
||||
`agentRuntime.id: "codex"`，但其认证仍然基于账号。OpenClaw
|
||||
按以下顺序选择认证：
|
||||
`agentRuntime.id: "codex"`，但它的身份验证仍然基于账户。OpenClaw
|
||||
按以下顺序选择身份验证：
|
||||
|
||||
1. 绑定到 agent 的显式 OpenClaw `openai-codex` 认证配置文件。
|
||||
2. app-server 的现有账号，例如本地 Codex CLI ChatGPT 登录。
|
||||
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账号但仍需要
|
||||
OpenAI 认证时，使用 `CODEX_API_KEY`，然后使用
|
||||
1. 显式绑定到 agent 的 OpenClaw `openai-codex` 身份验证配置文件。
|
||||
2. app-server 的现有账户，例如本地 Codex CLI ChatGPT 登录。
|
||||
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账户且仍需要
|
||||
OpenAI 身份验证时，使用 `CODEX_API_KEY`，然后使用
|
||||
`OPENAI_API_KEY`。
|
||||
|
||||
这意味着本地 ChatGPT/Codex 订阅登录不会仅仅因为 Gateway 网关进程也为直接 OpenAI 模型或嵌入设置了 `OPENAI_API_KEY` 而被替换。环境 API key 回退只适用于本地 stdio 无账号路径；它不会发送到 WebSocket app-server 连接。选择订阅式 Codex 配置文件时，OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
|
||||
排除在生成的 stdio app-server 子进程之外，并通过 app-server login RPC 发送所选凭证。
|
||||
这意味着本地 ChatGPT/Codex 订阅登录不会仅仅因为 gateway 进程也有用于直连 OpenAI 模型
|
||||
或嵌入的 `OPENAI_API_KEY` 而被替换。环境 API key 回退仅用于本地 stdio 无账户路径；
|
||||
它不会发送到 WebSocket app-server 连接。选择订阅式 Codex
|
||||
配置文件时，OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY`
|
||||
排除在生成的 stdio app-server 子进程之外，并通过 app-server 登录 RPC
|
||||
发送所选凭证。
|
||||
|
||||
## 图像生成
|
||||
|
||||
内置 `openai` 插件通过 `image_generate` 工具注册图像生成。
|
||||
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
|
||||
它通过相同的 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
|
||||
|
||||
| 能力 | OpenAI API key | Codex OAuth |
|
||||
| ------------------------- | ---------------------------------- | ------------------------------------ |
|
||||
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
|
||||
| 传输 | OpenAI Images API | Codex Responses 后端 |
|
||||
| 每次请求的最大图像数 | 4 | 4 |
|
||||
| 身份验证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
|
||||
| 传输协议 | OpenAI Images API | Codex Responses 后端 |
|
||||
| 每个请求的最大图像数 | 4 | 4 |
|
||||
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
|
||||
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
|
||||
| 纵横比 / 分辨率 | 不转发到 OpenAI Images API | 安全时映射到支持的尺寸 |
|
||||
| 宽高比/分辨率 | 不转发到 OpenAI Images API | 在安全时映射到支持的尺寸 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -316,15 +330,21 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_sear
|
||||
```
|
||||
|
||||
<Note>
|
||||
请参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
请参阅 [图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` 是 OpenAI 文本到图像生成和图像编辑的默认值。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可用作显式模型覆盖。对于透明背景 PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；当前的 `gpt-image-2` API 会拒绝
|
||||
`background: "transparent"`。
|
||||
`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认值。
|
||||
`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。
|
||||
透明背景 PNG/WebP 输出请使用 `openai/gpt-image-1.5`；当前
|
||||
`gpt-image-2` API 会拒绝 `background: "transparent"`。
|
||||
|
||||
对于透明背景请求，agent 应使用 `model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"` 以及
|
||||
`background: "transparent"` 调用 `image_generate`；较旧的 `openai.background` 提供商选项仍被接受。OpenClaw 还会保护公共 OpenAI 和
|
||||
OpenAI Codex OAuth 路由，将默认 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其配置的部署/模型名称。
|
||||
对于透明背景请求，agent 应调用 `image_generate`，并设置
|
||||
`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及
|
||||
`background: "transparent"`；旧的 `openai.background` provider 选项
|
||||
仍被接受。OpenClaw 还会通过将默认 `openai/gpt-image-2` 透明请求
|
||||
重写为 `gpt-image-1.5`，来保护公开 OpenAI 和
|
||||
OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点会保留
|
||||
其配置的部署/模型名称。
|
||||
|
||||
同一设置也暴露给无头 CLI 运行：
|
||||
|
||||
@ -337,14 +357,19 @@ openclaw infer image generate \
|
||||
--json
|
||||
```
|
||||
|
||||
从输入文件开始时，请对 `openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。
|
||||
从输入文件开始时，对 `openclaw infer image edit` 使用相同的
|
||||
`--output-format` 和 `--background` 标志。
|
||||
`--openai-background` 仍可作为 OpenAI 专用别名使用。
|
||||
|
||||
对于 Codex OAuth 安装，请保持相同的 `openai/gpt-image-2` 引用。配置了
|
||||
对于 Codex OAuth 安装，请保持相同的 `openai/gpt-image-2` 引用。当配置了
|
||||
`openai-codex` OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth
|
||||
访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API key。若要改用直接 OpenAI Images API 路由，请显式配置 `models.providers.openai`，并设置 API key、自定义 base URL 或 Azure 端点。
|
||||
访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试
|
||||
`OPENAI_API_KEY`，也不会对该请求静默回退到 API key。若你想要改用
|
||||
直连 OpenAI Images API 路由，请使用 API key、自定义 base URL 或 Azure
|
||||
端点显式配置 `models.providers.openai`。
|
||||
如果该自定义图像端点位于受信任的 LAN/私有地址上，还要设置
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入，OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在这个选择加入，
|
||||
否则 OpenClaw 会保持阻止私有/内部 OpenAI 兼容图像端点。
|
||||
|
||||
生成：
|
||||
|
||||
@ -371,10 +396,10 @@ openclaw infer image generate \
|
||||
| 能力 | 值 |
|
||||
| ------------ | --------------------------------------------------------------------------------- |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 模式 | 文本到视频、图像到视频、单视频编辑 |
|
||||
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
|
||||
| 参考输入 | 1 张图像或 1 个视频 |
|
||||
| 尺寸覆盖 | 支持 |
|
||||
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略并产生工具警告 |
|
||||
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -387,25 +412,25 @@ openclaw infer image generate \
|
||||
```
|
||||
|
||||
<Note>
|
||||
请参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
请参阅 [视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
|
||||
</Note>
|
||||
|
||||
## GPT-5 提示贡献
|
||||
## GPT-5 提示词贡献
|
||||
|
||||
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 提示贡献。它按模型 ID 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型不会收到。
|
||||
OpenClaw 为跨提供商的 GPT-5 系列运行添加了共享 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容 GPT-5 引用会收到相同的覆盖。较旧的 GPT-4.x 模型不会收到。
|
||||
|
||||
内置原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 Heartbeat 叠加层，因此即使 Codex 拥有 harness 提示的其余部分，通过 `agentRuntime.id: "codex"` 强制路由的 `openai/gpt-5.x` 会话仍保留相同的跟进和主动 Heartbeat 指导。
|
||||
内置原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和 heartbeat 覆盖，因此通过 `agentRuntime.id: "codex"` 强制使用的 `openai/gpt-5.x` 会话会保留相同的跟进和主动 heartbeat 指导，即使 harness 提示词的其余部分由 Codex 拥有。
|
||||
|
||||
GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、执行安全、工具纪律、输出形状、完成检查和验证。渠道特定的回复和静默消息行为保留在共享 OpenClaw 系统提示和出站投递策略中。GPT-5 指导始终为匹配模型启用。友好的交互风格层是独立且可配置的。
|
||||
GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、完成检查和验证添加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导始终会为匹配模型启用。友好的交互风格层是独立且可配置的。
|
||||
|
||||
| 值 | 效果 |
|
||||
| ------------------------ | ---------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好的交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
| 值 | 效果 |
|
||||
| ---------------------- | ---------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好的交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="配置">
|
||||
<Tab title="Config">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -426,18 +451,18 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
当共享 `agents.defaults.promptOverlays.gpt5.personality` 设置未设置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。
|
||||
当未设置共享 `agents.defaults.promptOverlays.gpt5.personality` 设置时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
|
||||
</Note>
|
||||
|
||||
## 语音和语音识别
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="语音合成（TTS）">
|
||||
内置 `openai` 插件为 `messages.tts` 表面注册语音合成。
|
||||
<Accordion title="Speech synthesis (TTS)">
|
||||
内置 `openai` 插件为 `messages.tts` surface 注册语音合成。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
@ -445,14 +470,14 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
|
||||
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音留言使用 `opus`，文件使用 `mp3` |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音留言为 `opus`，文件为 `mp3` |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
| 基础 URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
| 额外请求体 | `messages.tts.providers.openai.extraBody` / `extra_body` | （未设置） |
|
||||
|
||||
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
|
||||
|
||||
`extraBody` 会在 OpenClaw 生成的字段之后合并到 `/audio/speech` 请求 JSON 中，因此可将它用于需要额外键（例如 `lang`）的 OpenAI 兼容端点。原型键会被忽略。
|
||||
`extraBody` 会在 OpenClaw 生成的字段之后合并到 `/audio/speech` 请求 JSON 中，因此可将其用于需要 `lang` 等额外键的 OpenAI 兼容端点。原型键会被忽略。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -472,16 +497,15 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="语音转文本">
|
||||
内置 `openai` 插件通过 OpenClaw 的媒体理解转写接口注册批量语音转文本。
|
||||
<Accordion title="Speech-to-text">
|
||||
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。
|
||||
|
||||
- 默认模型：`gpt-4o-transcribe`
|
||||
- 端点：OpenAI REST `/v1/audio/transcriptions`
|
||||
- 输入路径：multipart 音频文件上传
|
||||
- OpenClaw 中任何使用入站音频转写的地方都支持，包括 Discord 语音频道片段和渠道音频附件，即
|
||||
`tools.media.audio`
|
||||
- 只要入站音频转录使用 `tools.media.audio`，OpenClaw 即支持，包括 Discord 语音频道片段和渠道音频附件
|
||||
|
||||
若要强制入站音频转写使用 OpenAI：
|
||||
若要强制 OpenAI 用于入站音频转录：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -501,30 +525,30 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
}
|
||||
```
|
||||
|
||||
当共享音频媒体配置或单次调用转写请求提供语言和提示词提示时，它们会转发给 OpenAI。
|
||||
当共享音频媒体配置或逐调用转录请求提供语言和 prompt 提示时，它们会转发给 OpenAI。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时转写">
|
||||
内置 `openai` 插件为 Voice Call 插件注册实时转写。
|
||||
<Accordion title="Realtime transcription">
|
||||
内置的 `openai` 插件为 Voice Call 插件注册实时转录。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| 语言 | `...openai.language` | （未设置） |
|
||||
| 提示词 | `...openai.prompt` | （未设置） |
|
||||
| Prompt | `...openai.prompt` | （未设置） |
|
||||
| 静默时长 | `...openai.silenceDurationMs` | `800` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频为 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。此流式提供商用于 Voice Call 的实时转写路径；Discord 语音目前会录制短片段，并改用批量 `tools.media.audio` 转写路径。
|
||||
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并使用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前会录制短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时语音">
|
||||
内置 `openai` 插件为 Voice Call 插件注册实时语音。
|
||||
<Accordion title="Realtime voice">
|
||||
内置的 `openai` 插件为 Voice Call 插件注册实时语音。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
@ -536,11 +560,11 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
通过后端实时桥接的 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向 tool 调用。使用 G.711 u-law 音频格式。
|
||||
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI，用于后端实时桥接。支持双向工具调用。使用 G.711 u-law 音频格式。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk 使用 OpenAI 浏览器实时会话，通过 Gateway 网关签发的临时客户端密钥，并针对 OpenAI Realtime API 直接进行浏览器 WebRTC SDP 交换。维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 这一段会在 Node 中签发客户端密钥，使用模拟麦克风媒体生成浏览器 SDP offer，将其发布到 OpenAI，并应用 SDP answer，且不会记录密钥。
|
||||
Control UI Talk 使用 OpenAI 浏览器实时会话，其中包含由 Gateway 网关签发的临时客户端密钥，并通过浏览器直接与 OpenAI Realtime API 进行 WebRTC SDP 交换。维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 分支会在 Node 中签发客户端密钥，使用模拟麦克风媒体生成浏览器 SDP offer，将其提交到 OpenAI，并应用 SDP answer，且不会记录密钥。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -548,24 +572,21 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
|
||||
## Azure OpenAI 端点
|
||||
|
||||
内置 `openai` provider 可以通过覆盖基础 URL，将图像生成指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求形态。
|
||||
内置的 `openai` provider 可以通过覆盖基础 URL，将图像生成定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求形态。
|
||||
|
||||
<Note>
|
||||
实时语音使用单独的配置路径
|
||||
（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
|
||||
不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置见 [语音和语音功能](#voice-and-speech) 下的 **实时语音** 折叠面板。
|
||||
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。有关它的 Azure 设置，请参阅 [语音和语音合成](#voice-and-speech) 下的 **实时语音** 折叠项。
|
||||
</Note>
|
||||
|
||||
在以下情况下使用 Azure OpenAI：
|
||||
|
||||
- 你已有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你需要 Azure 提供的区域数据驻留或合规控制
|
||||
- 你想让流量保留在现有 Azure 租户内
|
||||
- 你想将流量保留在现有 Azure 租户内
|
||||
|
||||
### 配置
|
||||
|
||||
若要通过内置 `openai` provider 使用 Azure 图像生成，请将
|
||||
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（不是 OpenAI Platform key）：
|
||||
若要通过内置的 `openai` provider 使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（不是 OpenAI Platform key）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -580,79 +601,77 @@ GPT-5 贡献添加了一个带标签的行为契约，涵盖人格持久性、
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会识别以下 Azure 主机后缀，并用于 Azure 图像生成路由：
|
||||
OpenClaw 会为 Azure 图像生成路由识别以下 Azure 主机后缀：
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
- `*.cognitiveservices.azure.com`
|
||||
|
||||
对于已识别 Azure 主机上的图像生成请求，OpenClaw 会：
|
||||
对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会：
|
||||
|
||||
- 发送 `api-key` 标头，而不是 `Authorization: Bearer`
|
||||
- 使用按部署限定的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 使用部署作用域路径（`/openai/deployments/{deployment}/...`）
|
||||
- 向每个请求追加 `?api-version=...`
|
||||
- 对 Azure 图像生成调用使用默认 600 秒请求超时。
|
||||
单次调用的 `timeoutMs` 值仍会覆盖此默认值。
|
||||
- 对 Azure 图像生成调用使用 600 秒默认请求超时。
|
||||
逐调用 `timeoutMs` 值仍会覆盖此默认值。
|
||||
|
||||
其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保持标准 OpenAI 图像请求形态。
|
||||
其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保留标准 OpenAI 图像请求形态。
|
||||
|
||||
<Note>
|
||||
`openai` provider 的图像生成路径上的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。早期版本会将任何自定义 `openai.baseUrl` 当作公共 OpenAI 端点处理，并且在对接 Azure 图像部署时会失败。
|
||||
`openai` provider 图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。早期版本会将任何自定义 `openai.baseUrl` 当作公共 OpenAI 端点处理，并且会在 Azure 图像部署上失败。
|
||||
</Note>
|
||||
|
||||
### API 版本
|
||||
|
||||
设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定 Azure 预览版或 GA 版本：
|
||||
设置 `AZURE_OPENAI_API_VERSION`，可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
变量未设置时，默认值为 `2024-12-01-preview`。
|
||||
未设置该变量时，默认值为 `2024-12-01-preview`。
|
||||
|
||||
### 模型名称就是部署名称
|
||||
### 模型名称是部署名称
|
||||
|
||||
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 ID。
|
||||
|
||||
如果你创建了名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 的部署：
|
||||
如果你创建了一个名为 `gpt-image-2-prod`、用于服务 `gpt-image-2` 的部署：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
|
||||
同一部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
|
||||
|
||||
### 区域可用性
|
||||
|
||||
Azure 图像生成目前仅在部分区域可用
|
||||
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
|
||||
`uaenorth`）。创建部署前，请检查 Microsoft 当前的区域列表，并确认你的区域提供具体模型。
|
||||
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请检查 Microsoft 当前的区域列表，并确认你的区域提供该特定模型。
|
||||
|
||||
### 参数差异
|
||||
|
||||
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上的某些 `background` 值），或仅在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体部署和 API 版本支持的参数集。
|
||||
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上的某些 `background` 值），或仅在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的特定部署和 API 版本所支持的参数集。
|
||||
|
||||
<Note>
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 — 见 [高级配置](#advanced-configuration) 下的 **原生与 OpenAI 兼容路由** 折叠面板。
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 — 请参阅 [高级配置](#advanced-configuration) 下的 **原生路由与 OpenAI 兼容路由** 折叠项。
|
||||
|
||||
对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用新手引导流程或专用 Azure provider 配置；仅设置 `openai.baseUrl` 不会套用 Azure API/鉴权形态。另有一个单独的 `azure-openai-responses/*` provider；见下方服务器端压缩折叠面板。
|
||||
对于 Azure 上的聊天或 Responses 流量（图像生成以外），请使用新手引导流程或专用 Azure provider 配置 — 仅设置 `openai.baseUrl` 不会采用 Azure API/auth 形态。另有一个 `azure-openai-responses/*` provider；请参阅下面的服务端压缩折叠项。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="传输（WebSocket 与 SSE）">
|
||||
<Accordion title="Transport (WebSocket vs SSE)">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并以 SSE 作为回退（`"auto"`）。
|
||||
|
||||
在 `"auto"` 模式下，OpenClaw：
|
||||
- 在回退到 SSE 前，会重试一次早期 WebSocket 失败
|
||||
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
|
||||
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重新连接附加稳定的会话和回合身份标头
|
||||
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
- 为重试和重新连接附加稳定的会话与轮次身份标头
|
||||
- 在传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
|
||||
| 值 | 行为 |
|
||||
|-------|----------|
|
||||
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
|
||||
| `"auto"`（默认） | 优先 WebSocket，SSE 回退 |
|
||||
| `"sse"` | 仅强制使用 SSE |
|
||||
| `"websocket"` | 仅强制使用 WebSocket |
|
||||
|
||||
@ -674,13 +693,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
|
||||
```
|
||||
|
||||
相关 OpenAI 文档：
|
||||
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [通过 WebSocket 使用 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WebSocket 预热">
|
||||
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首次回合延迟。
|
||||
<Accordion title="WebSocket warm-up">
|
||||
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。
|
||||
|
||||
```json5
|
||||
// Disable warm-up
|
||||
@ -699,13 +718,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="快速模式">
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 暴露共享快速模式开关：
|
||||
<Accordion title="Fast mode">
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 公开共享的快速模式开关：
|
||||
|
||||
- **聊天/UI：** `/fast status|on|off`
|
||||
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有 `service_tier` 值会保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
|
||||
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有 `service_tier` 值会保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -720,13 +739,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
|
||||
```
|
||||
|
||||
<Note>
|
||||
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话会回到已配置的默认值。
|
||||
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话会回到配置的默认值。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="优先处理（service_tier）">
|
||||
OpenAI 的 API 通过 `service_tier` 暴露优先处理。可在 OpenClaw 中按模型设置它：
|
||||
<Accordion title="Priority processing (service_tier)">
|
||||
OpenAI 的 API 通过 `service_tier` 公开优先处理。在 OpenClaw 中按模型设置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -743,19 +762,19 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
|
||||
支持的值：`auto`、`default`、`flex`、`priority`。
|
||||
|
||||
<Warning>
|
||||
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
|
||||
`serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="服务端压缩（Responses API）">
|
||||
对于直接的 OpenAI Responses 模型（`openai/*` 位于 `api.openai.com`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：
|
||||
<Accordion title="服务器端压缩（Responses API）">
|
||||
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务器端压缩：
|
||||
|
||||
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
|
||||
- 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
|
||||
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
|
||||
|
||||
这适用于内置的 Pi harness 路径，以及嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
|
||||
这适用于内置 Pi harness 路径，以及嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="显式启用">
|
||||
@ -811,7 +830,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
|
||||
`responsesServerCompaction` 只控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -830,35 +849,35 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
|
||||
```
|
||||
|
||||
使用 `strict-agentic` 时，OpenClaw：
|
||||
- 当工具操作可用时，不再将仅计划的轮次视为成功进展
|
||||
- 使用立即行动引导重试该轮次
|
||||
- 为实质性工作自动启用 `update_plan`
|
||||
- 如果模型持续只做计划而不行动，则暴露明确的阻塞状态
|
||||
- 当工具操作可用时，不再把仅包含计划的轮次视为成功进展
|
||||
- 使用立即行动 steer 重试该轮次
|
||||
- 对实质性工作自动启用 `update_plan`
|
||||
- 如果模型持续只规划而不行动，则显示明确的受阻状态
|
||||
|
||||
<Note>
|
||||
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和更早的模型系列保持默认行为。
|
||||
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生路由与 OpenAI 兼容路由">
|
||||
OpenClaw 对待直接的 OpenAI、Codex 和 Azure OpenAI 端点的方式不同于通用的 OpenAI 兼容 `/v1` 代理：
|
||||
OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理不同于通用 OpenAI 兼容 `/v1` 代理：
|
||||
|
||||
**原生路由**（`openai/*`、Azure OpenAI）：
|
||||
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
|
||||
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的推理
|
||||
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的推理
|
||||
- 默认将工具 schema 设为严格模式
|
||||
- 仅在已验证的原生主机上附加隐藏归因标头
|
||||
- 保留仅 OpenAI 使用的请求塑形（`service_tier`、`store`、推理兼容性、prompt-cache 提示）
|
||||
- 仅在已验证的原生主机上附加隐藏归因头
|
||||
- 保留仅 OpenAI 使用的请求塑形（`service_tier`、`store`、推理兼容性、提示缓存提示）
|
||||
|
||||
**代理/兼容路由：**
|
||||
- 使用更宽松的兼容行为
|
||||
- 从非原生 `openai-completions` 载荷中剥离 Completions `store`
|
||||
- 接受高级 `params.extra_body`/`params.extraBody` 透传 JSON，用于 OpenAI 兼容的 Completions 代理
|
||||
- 接受 `params.chat_template_kwargs`，用于 vLLM 等 OpenAI 兼容的 Completions 代理
|
||||
- 不强制使用严格工具 schema 或仅原生使用的标头
|
||||
- 从非原生 `openai-completions` 载荷中移除 Completions `store`
|
||||
- 接受高级 `params.extra_body`/`params.extraBody` 透传 JSON，用于 OpenAI 兼容 Completions 代理
|
||||
- 接受 `params.chat_template_kwargs`，用于 vLLM 等 OpenAI 兼容 Completions 代理
|
||||
- 不强制使用严格工具 schema 或仅原生使用的请求头
|
||||
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user