diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 97e52c39f..daef8018e 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,39 +1,39 @@ --- read_when: - - 你想在 OpenClaw 中使用 OpenAI 模型。 - - 你想使用 Codex 订阅凭证，而不是 API 密钥。 - - 你需要更严格的 GPT-5 智能体执行行为。 -summary: 在 OpenClaw 中使用 OpenAI，可通过 API 密钥或 Codex 订阅。 + - 你想在 OpenClaw 中使用 OpenAI 模型 + - 你想使用 Codex 订阅认证，而不是 API 密钥 + - 你需要更严格的 GPT-5 智能体执行行为 +summary: 在 OpenClaw 中使用 OpenAI API 密钥或 Codex 订阅 title: OpenAI x-i18n: - generated_at: "2026-04-12T11:08:20Z" + generated_at: "2026-04-21T01:38:03Z" model: gpt-5.4 provider: openai - source_hash: 6aeb756618c5611fed56e4bf89015a2304ff2e21596104b470ec6e7cb459d1c9 + source_hash: 4db510f037ec0dab5c2b419b242f182324543ad7feeaba515f71ed17f05a9486 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种凭证方式： +OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式： - **API 密钥** — 直接访问 OpenAI Platform，并按用量计费（`openai/*` 模型） -- **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型） +- **Codex 订阅** — 通过 ChatGPT/Codex 登录，并使用订阅访问（`openai-codex/*` 模型） -OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth。 +OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 ## 入门指南 -选择你偏好的凭证方式，并按照设置步骤进行操作。 +选择你偏好的认证方式，并按照设置步骤操作。 - **最适合：** 直接访问 API 并按用量计费。 + **最适合：** 直接 API 访问和按用量计费。 - 在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。 + 在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。 ```bash @@ -53,9 +53,9 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth - ### 路由摘要 + ### 路由概览 - | 模型引用 | 路由 | 凭证 | + | Model ref | 路由 | 认证 | |-----------|-------|------| | `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | | `openai/gpt-5.4-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | @@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth ``` - OpenClaw **不会** 在直接 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 + OpenClaw **不会** 在直接 API 路径上公开 `openai/gpt-5.3-codex-spark`。实际的 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 - **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。 + **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。 @@ -106,15 +106,15 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth - ### 路由摘要 + ### 路由概览 - | 模型引用 | 路由 | 凭证 | + | Model ref | 路由 | 认证 | |-----------|-------|------| | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 | | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） | - 这一路由与 `openai/gpt-5.4` 是有意分开的。使用 API 密钥配合 `openai/*` 以直接访问 Platform，而使用 `openai-codex/*` 以通过 Codex 订阅访问。 + 这一路由与 `openai/gpt-5.4` 是有意分开的。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。 ### 配置示例 @@ -126,7 +126,7 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth ``` - 如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，然后将刷新的凭证写回 Codex 存储。 + 如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期后，OpenClaw 会先重新读取外部 Codex 来源，再把刷新后的凭证写回 Codex 存储。 ### 上下文窗口上限 @@ -138,7 +138,7 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth - 原生 `contextWindow`：`1050000` - 默认运行时 `contextTokens` 上限：`272000` - 较小的默认上限在实践中通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： + 实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： ```json5 { @@ -169,7 +169,7 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth | 每次请求的最大图像数 | 4 | | 编辑模式 | 已启用（最多 5 张参考图像） | | 尺寸覆盖 | 支持 | -| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | +| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | ```json5 { @@ -195,7 +195,7 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth | 模式 | 文本生成视频、图像生成视频、单视频编辑 | | 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | -| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 | +| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 | ```json5 { @@ -211,15 +211,17 @@ OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth 有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 -## 个性覆盖层 +## GPT-5 提示词贡献 -OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI 专属提示词覆盖层。该覆盖层会让助手保持温暖、协作、简洁，并带有稍强一些的情感表达，但不会替代基础系统提示词。 +OpenClaw 会为 `openai/*` 和 `openai-codex/*` 的 GPT-5 系列运行添加一个 OpenAI 专用的 GPT-5 提示词贡献。它位于内置的 OpenAI 插件中，适用于 `gpt-5`、`gpt-5.2`、`gpt-5.4` 和 `gpt-5.4-mini` 等模型 id，不适用于较旧的 GPT-4.x 模型。 + +GPT-5 贡献默认会添加简洁的输出形式、工具调用和执行倾向指导。对于匹配的 GPT-5 模型，这些指导始终启用。友好交互风格层是单独的，并且可配置。 | 值 | 效果 | -| ---------------------- | ---------------------------------- | -| `"friendly"`（默认） | 启用 OpenAI 专属覆盖层 | +| ---------------------- | ------------------------------------------- | +| `"friendly"`（默认） | 启用友好交互风格层 | | `"on"` | `"friendly"` 的别名 | -| `"off"` | 仅使用基础 OpenClaw 提示词 | +| `"off"` | 仅禁用友好风格层 | @@ -241,26 +243,26 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI -运行时会以不区分大小写的方式处理这些值，因此 `"Off"` 和 `"off"` 都会禁用该覆盖层。 +运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 ## 语音与语音处理 - 内置的 `openai` 插件会为 `messages.tts` 接口注册语音合成功能。 + 内置的 `openai` 插件为 `messages.tts` 接口注册了语音合成功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 声音 | `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.voice` | `coral` | + | 速度 | `messages.tts.providers.openai.speed` | （未设置） | + | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts` 支持） | + | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -275,13 +277,13 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。 + 设置 `OPENAI_TTS_BASE_URL` 可以覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。 - 内置的 `openai` 插件会为 Voice Call 插件注册实时转录功能。 + 内置的 `openai` 插件为语音通话插件注册了实时转录功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| @@ -297,13 +299,13 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI - 内置的 `openai` 插件会为 Voice Call 插件注册实时语音功能。 + 内置的 `openai` 插件为语音通话插件注册了实时语音功能。 | 设置 | 配置路径 | 默认值 | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` | - | 声音 | `...openai.voice` | `alloy` | - | 温度 | `...openai.temperature` | `0.8` | + | 语音 | `...openai.voice` | `alloy` | + | Temperature | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | @@ -318,18 +320,18 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI ## 高级配置 - - 对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先、SSE 回退（`"auto"`）的策略。 + + OpenClaw 对 `openai/*` 和 `openai-codex/*` 都采用优先 WebSocket、回退 SSE（`"auto"`）的方式。 在 `"auto"` 模式下，OpenClaw 会： - - 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试 - - 发生失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话与轮次标识头 - - 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`） + - 在回退到 SSE 之前，重试一次早期 WebSocket 失败 + - 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次标识头 + - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`） | 值 | 行为 | |-------|----------| - | `"auto"`（默认） | WebSocket 优先，SSE 回退 | + | `"auto"`（默认） | 优先 WebSocket，回退到 SSE | | `"sse"` | 仅强制使用 SSE | | `"websocket"` | 仅强制使用 WebSocket | @@ -354,7 +356,7 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI - OpenClaw 默认会为 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。 + OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。 ```json5 // 禁用预热 @@ -379,7 +381,7 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI - **聊天 / UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。 ```json5 { @@ -395,7 +397,7 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI ``` - 会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置中的默认值。 + 会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。 @@ -424,16 +426,16 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI - - 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： + + 对于直接 OpenAI Responses 模型（位于 `api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务器端压缩： - - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） + - 强制设置 `store: true`（除非模型兼容性将 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`） + - 默认 `compact_threshold`：`contextWindow` 的 70%（如果不可用则为 `80000`） - 适用于 Azure OpenAI Responses 等兼容端点： + 对 Azure OpenAI Responses 这类兼容端点很有用： ```json5 { @@ -485,13 +487,13 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。 + `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性将 `supportsStore: false`。 - 对于 `openai/*` 和 `openai-codex/*` 上 GPT-5 系列的运行，OpenClaw 可以使用更严格的内嵌执行契约： + 对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约： ```json5 { @@ -504,29 +506,29 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI ``` 使用 `strict-agentic` 时，OpenClaw 会： - - 当工具操作可用时，不再将“仅做计划”的轮次视为成功推进 - - 通过“立即行动”的引导重试该轮 - - 对于较大工作自动启用 `update_plan` - - 如果模型持续只做计划而不行动，则显示明确的阻塞状态 + - 当工具操作可用时，不再将仅计划的轮次视为成功推进 + - 通过立即行动的引导重试该轮次 + - 对于实质性工作自动启用 `update_plan` + - 如果模型持续规划而不行动，则显示明确的受阻状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列将保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列会保持默认行为。 - OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI-compatible `/v1` 代理： + OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用 OpenAI-compatible `/v1` 代理： **原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）： - 当明确禁用推理时，保留 `reasoning: { effort: "none" }` - 默认将工具 schema 设为严格模式 - 仅在已验证的原生主机上附加隐藏归因头 - - 保留 OpenAI 专属请求整形（`service_tier`、`store`、推理兼容性、提示词缓存提示） + - 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示缓存提示） - **代理 / compatible 路由：** + **代理 / 兼容路由：** - 使用更宽松的兼容行为 - - 不强制严格工具 schema 或原生专属头 + - 不会强制使用严格工具 schema 或原生专用请求头 Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。 @@ -545,7 +547,7 @@ OpenClaw 会为 `openai/*` 和 `openai-codex/*` 运行添加一个小型 OpenAI 共享视频工具参数和提供商选择。 - - 凭证详情和凭证复用规则。 + + 认证细节和凭证复用规则。