chore(i18n): refresh zh-CN translations

2026-04-22 13:03:07 +00:00 · 2026-04-22 13:03:07 +00:00 · b4373d3ebd
commit b4373d3ebd
parent b635173598
1 changed files with 61 additions and 58 deletions
--- a/docs/zh-CN/providers/openai.md
+++ b/docs/zh-CN/providers/openai.md
@ -1,15 +1,15 @@
 ---
 read_when:
    - 你想在 OpenClaw 中使用 OpenAI 模型
-    - 你想使用 Codex 订阅认证，而不是 API 密钥
+    - 你希望使用 Codex 订阅认证，而不是 API 密钥
    - 你需要更严格的 GPT-5 智能体执行行为
 summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
 title: OpenAI
 x-i18n:
-    generated_at: "2026-04-21T20:53:31Z"
+    generated_at: "2026-04-22T13:02:09Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 692615b77885c0387d339d47c02ff056ba95d3608aa681882893a46d2a0f723f
+    source_hash: 7b0035cb879563a169294269e2fb39884194ec219373bc6e3edb1a8b47660b29
    source_path: providers/openai.md
    workflow: 15
 ---
@ -18,8 +18,8 @@ x-i18n:

 OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式：

- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
- **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
+- **API 密钥** —— 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型）
+- **Codex 订阅** —— 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）

 OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。

@ -29,7 +29,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA

 <Tabs>
  <Tab title="API 密钥（OpenAI Platform）">
-    **最适合：** 直接 API 访问和按使用量计费。
+    **最适合：** 直接 API 访问和按量计费。

    <Steps>
      <Step title="获取你的 API 密钥">
@ -46,7 +46,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
        openclaw onboard --openai-api-key "$OPENAI_API_KEY"
        ```
      </Step>
-      <Step title="验证模型可用">
+      <Step title="验证模型是否可用">
        ```bash
        openclaw models list --provider openai
        ```
@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
    ```

    <Warning>
-    OpenClaw **不会** 在直连 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
+    OpenClaw **不会**在直接 API 路径中暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
    </Warning>

  </Tab>

  <Tab title="Codex 订阅">
-    **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。
+    **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。

    <Steps>
      <Step title="运行 Codex OAuth">
@ -99,7 +99,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
        openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
        ```
      </Step>
-      <Step title="验证模型可用">
+      <Step title="验证模型是否可用">
        ```bash
        openclaw models list --provider openai-codex
        ```
@ -111,10 +111,10 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
    | 模型引用 | 路由 | 认证 |
    |-----------|-------|------|
    | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 |
-    | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） |
+    | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于权益） |

    <Note>
-    这一路由刻意与 `openai/gpt-5.4` 分开。使用 API 密钥配合 `openai/*` 进行直接 Platform 访问，使用 `openai-codex/*` 进行 Codex 订阅访问。
+    这一路径特意与 `openai/gpt-5.4` 分开。使用 API 密钥搭配 `openai/*` 进行直接 Platform 访问，使用 `openai-codex/*` 进行 Codex 订阅访问。
    </Note>

    ### 配置示例
@ -126,19 +126,19 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
    ```

    <Tip>
-    如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期后，OpenClaw 会先重新读取外部 Codex 来源，再将刷新后的凭证写回 Codex 存储。
+    如果新手引导复用了现有的 Codex CLI 登录，这些凭证会继续由 Codex CLI 管理。过期时，OpenClaw 会先重新读取外部 Codex 来源，再将刷新的凭证写回 Codex 存储。
    </Tip>

    ### 上下文窗口上限

-    OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。
+    OpenClaw 会将模型元数据与运行时上下文上限视为两个独立的值。

    对于 `openai-codex/gpt-5.4`：

    - 原生 `contextWindow`：`1050000`
    - 默认运行时 `contextTokens` 上限：`272000`

-    较小的默认上限在实践中具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
+    较小的默认上限在实践中具有更好的延迟和质量特性。你可以使用 `contextTokens` 覆盖它：

    ```json5
    {
@ -153,7 +153,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
    ```

    <Note>
-    使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。
+    使用 `contextWindow` 声明原生模型元数据。使用 `contextTokens` 限制运行时上下文预算。
    </Note>

  </Tab>
@ -169,7 +169,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
 | 每次请求的最大图像数 | 4 |
 | 编辑模式 | 已启用（最多 5 张参考图像） |
 | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
-| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API |
+| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API |

 ```json5
 {
@ -182,10 +182,11 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
 ```

 <Note>
-有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
+有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。
 </Note>

-`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
+`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。  
+`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。

 生成：

@ -206,10 +207,10 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
 | 能力 | 值 |
 | ---------------- | --------------------------------------------------------------------------------- |
 | 默认模型 | `openai/sora-2` |
-| 模式 | 文生视频、图生视频、单视频编辑 |
+| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
 | 参考输入 | 1 张图像或 1 个视频 |
 | 尺寸覆盖 | 支持 |
-| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
+| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 |

 ```json5
 {
@ -222,18 +223,20 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
 ```

 <Note>
-有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
+有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
 </Note>

 ## GPT-5 提示词贡献

-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 模型。
+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 贡献为人格持久性、执行安全、工具纪律、输出形态、完成检查和验证增加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层是独立且可配置的。
+内置的原生 Codex harness 提供商（`codex/*`）也会通过 Codex app-server 开发者指令应用同样的 GPT-5 行为和心跳覆盖层，因此即使 Codex 负责其余 harness 提示词，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动心跳指导。
+
+GPT-5 贡献添加了一个带标签的行为契约，用于规范人格持续性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层是独立的，并且可配置。

 | 值 | 效果 |
 | ---------------------- | ------------------------------------------- |
-| `"friendly"`（默认） | 启用友好的交互风格层 |
+| `"friendly"`（默认） | 启用友好交互风格层 |
 | `"on"` | `"friendly"` 的别名 |
 | `"off"` | 仅禁用友好风格层 |

@ -260,19 +263,19 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
 这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
 </Tip>

-## 语音和语音合成
+## 语音与语音处理

 <AccordionGroup>
  <Accordion title="语音合成（TTS）">
-    内置的 `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.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 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
    | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |

@ -291,13 +294,13 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    ```

    <Note>
-    设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS Base URL，而不会影响聊天 API 端点。
+    设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的基础 URL，而不会影响聊天 API 端点。
    </Note>

  </Accordion>

  <Accordion title="实时转录">
-    内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
+    内置的 `openai` 插件会为 Voice Call 插件注册实时转录功能。

    | 设置 | 配置路径 | 默认值 |
    |---------|------------|---------|
@ -313,13 +316,13 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
  </Accordion>

  <Accordion title="实时语音">
-    内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。
+    内置的 `openai` 插件会为 Voice Call 插件注册实时语音功能。

    | 设置 | 配置路径 | 默认值 |
    |---------|------------|---------|
    | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
    | 声音 | `...openai.voice` | `alloy` |
-    | 温度 | `...openai.temperature` | `0.8` |
+    | Temperature | `...openai.temperature` | `0.8` |
    | VAD 阈值 | `...openai.vadThreshold` | `0.5` |
    | 静音时长 | `...openai.silenceDurationMs` | `500` |
    | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
@ -334,14 +337,14 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
 ## 高级配置

 <AccordionGroup>
-  <Accordion title="传输协议（WebSocket 与 SSE）">
-    对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。
+  <Accordion title="传输方式（WebSocket 与 SSE）">
+    对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先、SSE 回退（`"auto"`）的方式。

    在 `"auto"` 模式下，OpenClaw 会：
-    - 在回退到 SSE 之前重试一次早期 WebSocket 失败
+    - 在回退到 SSE 之前，重试一次早期 WebSocket 失败
    - 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
-    - 为重试和重连附加稳定的会话和轮次身份标头
-    - 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`）
+    - 为重试和重连附加稳定的会话与轮次标识头
+    - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）

    | 值 | 行为 |
    |-------|----------|
@ -364,8 +367,8 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    ```

    相关 OpenAI 文档：
-    - [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
-    - [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
+    - [通过 WebSocket 使用 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
+    - [流式传输 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)

  </Accordion>

@ -395,7 +398,7 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    - **聊天 / 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
    {
@ -411,13 +414,13 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    ```

    <Note>
-    会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将返回到已配置的默认值。
+    会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。
    </Note>

  </Accordion>

  <Accordion title="优先处理（service_tier）">
-    OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
+    OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置：

    ```json5
    {
@ -435,21 +438,21 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    支持的值：`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 模型（`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`）

    <Tabs>
      <Tab title="显式启用">
-        适用于 Azure OpenAI Responses 这类兼容端点：
+        适用于 Azure OpenAI Responses 等兼容端点：

        ```json5
        {
@ -501,7 +504,7 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    </Tabs>

    <Note>
-    `responsesServerCompaction` 仅控制 `context_management` 注入。直连 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
+    `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性将 `supportsStore: false`。
    </Note>

  </Accordion>
@ -520,32 +523,32 @@ GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、
    ```

    使用 `strict-agentic` 时，OpenClaw 会：
-    - 当工具操作可用时，不再将仅规划的轮次视为成功进展
+    - 当工具操作可用时，不再将仅规划的轮次视为成功推进
    - 使用“立即行动”的引导重试该轮次
-    - 对于较大工作自动启用 `update_plan`
-    - 如果模型持续只做规划而不行动，则显式显示阻塞状态
+    - 为重要工作自动启用 `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/*`、`openai-codex/*`、Azure OpenAI）：
    - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
-    - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning
+    - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用推理设置
    - 默认将工具 schema 设为严格模式
-    - 仅在已验证的原生主机上附加隐藏归属标头
+    - 仅在经过验证的原生主机上附加隐藏归因头
    - 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）

    **代理 / 兼容路由：**
-    - 使用更宽松的兼容性行为
-    - 不强制严格工具 schema 或仅限原生的标头
+    - 使用更宽松的兼容行为
+    - 不强制严格工具 schema 或原生专用头

-    Azure OpenAI 使用原生传输和兼容性行为，但不会接收隐藏归属标头。
+    Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。

  </Accordion>
 </AccordionGroup>