chore(i18n): refresh zh-CN translations

docs/zh-CN/plugins/codex-harness.md

@@ -2,63 +2,77 @@
 read_when:
     - 你想使用内置的 Codex app-server harness
     - 你需要 Codex harness 配置示例
-    - 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 PI
-summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体回合
+    - 你希望仅使用 Codex 的部署在失败时直接报错，而不是回退到 Pi
+summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次
 title: Codex harness
 x-i18n:
-    generated_at: "2026-04-27T23:44:15Z"
+    generated_at: "2026-04-27T23:52:41Z"
     model: gpt-5.4
     provider: openai
-    source_hash: ef9654bdc6a2cb44726a53002f2735d823119d2e0379adc68907d8a0980ba4c2
+    source_hash: c048ff928fb0b601b6a75631f9e33bbf23d08d1c21ad762b22ac3fb182d862ff
     source_path: plugins/codex-harness.md
     workflow: 15
 ---
 
-内置的 `codex` 插件让 OpenClaw 通过 Codex app-server 而不是内置的 PI harness 运行嵌入式智能体回合。
+内置的 `codex` 插件让 OpenClaw 通过 Codex app-server，而不是内置的 Pi harness，来运行嵌入式智能体轮次。
 
-当你希望由 Codex 接管底层智能体会话时，请使用此插件：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。
+当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。
 
-如果你正在熟悉相关概念，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。简而言之：`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。
+如果你正在熟悉这一部分，请先从 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 开始。简而言之：
+`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、
+Discord、Slack 或其他渠道仍然是通信界面。
 
 ## 此插件会改变什么
 
-内置的 `codex` 插件提供了几项彼此独立的能力：
+内置的 `codex` 插件提供若干彼此独立的能力：
 
-| 能力 | 使用方式 | 作用 |
+| 能力 | 你的使用方式 | 它的作用 |
 | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
-| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体回合。 |
+| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体轮次。 |
 | 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 在消息会话中绑定并控制 Codex app-server 线程。 |
-| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并校验 app-server 模型。 |
-| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为支持的图像理解模型运行受限的 Codex app-server 回合。 |
-| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/终结事件。 |
+| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并验证 app-server 模型。 |
+| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行受限的 Codex app-server 轮次。 |
+| 原生 hook 转发 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 观察/拦截受支持的 Codex 原生工具/终结事件。 |
 
-启用该插件会让这些能力可用。它**不会**：
+启用该插件会使这些能力可用。它**不会**：
 
-- 为每个 OpenAI 模型都开始使用 Codex
+- 开始对每个 OpenAI 模型都使用 Codex
 - 将 `openai-codex/*` 模型引用转换为原生运行时
 - 让 ACP/acpx 成为默认的 Codex 路径
-- 热切换已经记录为 PI 运行时的现有会话
+- 热切换已经记录为 Pi 运行时的现有会话
 - 替换 OpenClaw 的渠道投递、会话文件、auth-profile 存储或消息路由
 
-同一个插件也负责原生 `/codex` 聊天控制命令界面。如果插件已启用，且用户希望从聊天中绑定、恢复、引导、停止或检查 Codex 线程，智能体应优先使用 `/codex ...`，而不是 ACP。只有当用户明确要求 ACP/acpx，或正在测试 ACP Codex 适配器时，ACP 才是显式后备方案。
+同一个插件也负责原生 `/codex` 聊天控制命令界面。如果
+插件已启用，并且用户要求从聊天中绑定、恢复、引导、停止或检查
+Codex 线程，智能体应优先使用 `/codex ...` 而不是 ACP。只有当用户明确要求 ACP/acpx，或正在测试 ACP
+Codex 适配器时，ACP 才是显式回退路径。
 
-原生 Codex 回合将 OpenClaw 插件钩子保留为公开兼容层。这些是进程内的 OpenClaw 钩子，而不是 Codex `hooks.json` 命令钩子：
+原生 Codex 轮次仍将 OpenClaw 插件钩子作为公共兼容层。
+这些是进程内的 OpenClaw 钩子，不是 Codex `hooks.json` 命令钩子：
 
 - `before_prompt_build`
 - `before_compaction`, `after_compaction`
 - `llm_input`, `llm_output`
 - `before_tool_call`, `after_tool_call`
 - 用于镜像转录记录的 `before_message_write`
-- 通过 Codex `Stop` 中继的 `before_agent_finalize`
+- 通过 Codex `Stop` 转发的 `before_agent_finalize`
 - `agent_end`
 
-插件还可以注册运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公开的 `tool_result_persist` 插件钩子不同，后者用于转换由 OpenClaw 拥有的转录工具结果写入。
+插件还可以注册运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、并在结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公共
+`tool_result_persist` 插件钩子不同，后者会转换由 OpenClaw 拥有的转录工具结果写入。
 
-关于插件钩子语义本身，请参阅 [Plugin hooks](/zh-CN/plugins/hooks) 和 [Plugin guard behavior](/zh-CN/tools/plugin)。
+关于插件钩子语义本身，请参见 [Plugin hooks](/zh-CN/plugins/hooks)
+和 [Plugin guard behavior](/zh-CN/tools/plugin)。
 
-默认情况下，harness 处于关闭状态。新的配置应保持 OpenAI 模型引用为规范形式 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。出于兼容性考虑，旧版 `codex/*` 模型引用仍会自动选择该 harness，但由运行时支持的旧版提供商前缀不会显示为普通的模型/提供商选项。
+该 harness 默认关闭。新配置应保持 OpenAI 模型引用
+规范为 `openai/gpt-*`，并在希望使用原生 app-server 执行时显式强制
+`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
+旧版 `codex/*` 模型引用仍会自动选择该 harness 以保持兼容，但由运行时支持的旧版提供商前缀不会显示为普通模型/提供商选项。
 
-如果启用了 `codex` 插件，但主模型仍然是 `openai-codex/*`，`openclaw doctor` 会发出警告，而不是更改路由。这是有意为之：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生 app-server 执行始终是一个显式运行时选择。
+如果启用了 `codex` 插件，但主模型仍然是
+`openai-codex/*`，`openclaw doctor` 会给出警告，而不是更改路由。这是
+有意为之：`openai-codex/*` 仍然是 Pi Codex OAuth/订阅路径，而
+原生 app-server 执行仍然是一个显式的运行时选择。
 
 ## 路由映射
 
@@ -67,65 +81,97 @@ x-i18n:
 | 期望行为 | 模型引用 | 运行时配置 | 插件要求 | 预期 Status 标签 |
 | ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
 | 通过普通 OpenClaw 运行器使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` |
-| 通过 PI 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` |
-| 原生 Codex app-server 嵌入式回合 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` |
-| 使用保守自动模式的混合提供商 | provider-specific refs | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于所选运行时 |
-| 显式 Codex ACP 适配器会话 | ACP prompt/model dependent | `sessions_spawn` 搭配 `runtime: "acp"` | 正常工作的 `acpx` 后端 | ACP 任务/会话状态 |
+| 通过 Pi 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` |
+| 原生 Codex app-server 嵌入式轮次 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` |
+| 启用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于所选运行时 |
+| 显式 Codex ACP 适配器会话 | 取决于 ACP prompt/model | `sessions_spawn` 搭配 `runtime: "acp"` | 健康的 `acpx` 后端 | ACP 任务/会话状态 |
 
-关键区别在于提供商与运行时：
+这里最重要的区分是提供商与运行时：
 
-- `openai-codex/*` 回答的是“PI 应该使用哪条提供商/认证路由？”
-- `agentRuntime.id: "codex"` 回答的是“哪个循环应执行这个嵌入式回合？”
-- `/codex ...` 回答的是“这个聊天应绑定或控制哪个原生 Codex 会话？”
+- `openai-codex/*` 回答的是“Pi 应该使用哪条提供商/认证路径？”
+- `agentRuntime.id: "codex"` 回答的是“哪个 loop 应该执行这次
+  嵌入式轮次？”
+- `/codex ...` 回答的是“此聊天应绑定或控制哪个原生 Codex 会话？”
 - ACP 回答的是“acpx 应启动哪个外部 harness 进程？”
 
 ## 选择正确的模型前缀
 
-OpenAI 系列路由对前缀非常敏感。当你想通过 PI 使用 Codex OAuth 时，使用 `openai-codex/*`；当你想直接访问 OpenAI API，或强制使用原生 Codex app-server harness 时，使用 `openai/*`：
+OpenAI 系列路由对前缀很敏感。当你希望
+通过 Pi 使用 Codex OAuth 时，请使用 `openai-codex/*`；当你希望直接使用 OpenAI API，或
+当你强制使用原生 Codex app-server harness 时，请使用 `openai/*`：
 
 | 模型引用 | 运行时路径 | 使用场景 |
 | --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
-| `openai/gpt-5.4` | 通过 OpenClaw/PI 管道的 OpenAI provider | 你希望使用 `OPENAI_API_KEY` 访问当前直接可用的 OpenAI Platform API。 |
-| `openai-codex/gpt-5.5` | 通过 OpenClaw/PI 的 OpenAI Codex OAuth | 你希望使用默认 PI 运行器的 ChatGPT/Codex 订阅认证。 |
-| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望为嵌入式智能体回合使用原生 Codex app-server 执行。 |
+| `openai/gpt-5.4` | 通过 OpenClaw/Pi 流程使用 OpenAI provider | 你希望使用 `OPENAI_API_KEY` 访问当前的 OpenAI Platform API。 |
+| `openai-codex/gpt-5.5` | 通过 OpenClaw/Pi 使用 OpenAI Codex OAuth | 你希望使用默认 Pi 运行器，通过 ChatGPT/Codex 订阅认证。 |
+| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望为嵌入式智能体轮次使用原生 Codex app-server 执行。 |
 
-GPT-5.5 当前在 OpenClaw 中仅支持订阅/OAuth。PI OAuth 请使用 `openai-codex/gpt-5.5`，或者将 `openai/gpt-5.5` 与 Codex app-server harness 搭配使用。OpenAI 一旦在公共 API 中启用 GPT-5.5，就会支持对 `openai/gpt-5.5` 的直接 API 密钥访问。
+GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。请使用
+`openai-codex/gpt-5.5` 进行 Pi OAuth，或使用 `openai/gpt-5.5` 搭配 Codex
+app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，
+就支持通过 API key 直接访问 `openai/gpt-5.5`。
 
-旧版 `codex/gpt-*` 引用仍然作为兼容别名被接受。Doctor 兼容迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅作为后备的旧版引用则保持不变，因为运行时是为整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 加上 `agentRuntime.id: "codex"`。
+旧版 `codex/gpt-*` 引用仍然接受为兼容性别名。Doctor
+兼容迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅用于回退的旧版引用则保持不变，因为运行时是针对整个智能体容器配置的。
+新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生
+app-server harness 配置应使用 `openai/gpt-*`，并加上
+`agentRuntime.id: "codex"`。
 
-`agents.defaults.imageModel` 也遵循同样的前缀拆分。当图像理解应通过 OpenAI Codex OAuth provider 路径运行时，使用 `openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 回合运行时，使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体回合开始前失败。
+`agents.defaults.imageModel` 也遵循相同的前缀区分。如果你希望图像理解通过 OpenAI
+Codex OAuth 提供商路径运行，请使用 `openai-codex/gpt-*`。如果你希望图像理解通过受限的 Codex app-server 轮次运行，请使用
+`codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始之前失败。
 
-使用 `/status` 可确认当前会话的实际 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关中的结构化 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时/后备策略，以及在 `auto` 模式下每个插件候选项的支持结果。
+使用 `/status` 来确认当前会话实际使用的 harness。如果结果出乎意料，请为 `agents/harness` 子系统启用调试日志，
+并检查 Gateway 网关中的结构化 `agent harness selected` 记录。它
+包含所选 harness id、选择原因、运行时/回退策略，以及在
+`auto` 模式下，每个插件候选项的支持结果。
 
 ### doctor 警告意味着什么
 
-当以下条件全部成立时，`openclaw doctor` 会发出警告：
+当以下条件全部满足时，`openclaw doctor` 会发出警告：
 
-- 内置 `codex` 插件已启用或被允许
+- 内置的 `codex` 插件已启用或被允许
 - 某个智能体的主模型是 `openai-codex/*`
 - 该智能体的实际运行时不是 `codex`
 
-之所以有这个警告，是因为用户常常会认为“启用了 Codex 插件”就意味着“使用原生 Codex app-server 运行时”。OpenClaw 不会自动做出这个跳转。这个警告表示：
+之所以有这个警告，是因为用户经常认为“已启用 Codex 插件”就意味着
+“使用原生 Codex app-server 运行时”。OpenClaw 不会自动做出这种推断。这个警告表示：
 
-- 如果你本来就是要通过 PI 使用 ChatGPT/Codex OAuth，**则无需更改**。
-- 如果你想使用原生 app-server 执行，请将模型改为 `openai/<model>`，并设置 `agentRuntime.id: "codex"`。
-- 现有会话在运行时变更后仍需要执行 `/new` 或 `/reset`，因为会话运行时固定是粘性的。
+- 如果你本来就打算通过 Pi 使用 ChatGPT/Codex OAuth，**则无需更改**。
+- 如果你想使用原生 app-server
+  执行，请将模型改为 `openai/<model>`，并设置
+  `agentRuntime.id: "codex"`。
+- 现有会话在运行时更改后仍需要 `/new` 或 `/reset`，
+  因为会话运行时固定是粘性的。
 
-Harness 选择不是实时会话控制。当一个嵌入式回合运行时，OpenClaw 会在该会话上记录所选 harness id，并在后续同一会话 id 的回合中继续使用它。当你希望未来会话使用另一种 harness 时，请更改 `agentRuntime` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有会话于 PI 和 Codex 之间切换之前，请先使用 `/new` 或 `/reset` 启动一个新会话。这可以避免将同一份转录通过两套不兼容的原生会话系统重放。
+Harness 选择不是实时会话控制。当嵌入式轮次运行时，
+OpenClaw 会在该会话上记录所选的 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来的会话使用另一个 harness 时，请更改 `agentRuntime` 配置或
+`OPENCLAW_AGENT_RUNTIME`；在现有会话于 Pi 和 Codex 之间切换之前，请使用 `/new` 或 `/reset` 启动新会话。
+这样可以避免通过两个不兼容的原生会话系统来重放同一份转录。
 
-在引入 harness 固定机制之前创建的旧会话，只要已有转录历史，就会被视为固定到 PI。更改配置后，如需让该会话改用 Codex，请使用 `/new` 或 `/reset`。
+在 harness 固定机制引入之前创建的旧会话，只要它们已有转录历史，
+就会被视为固定到 Pi。更改配置后，如需让该会话改用
+Codex，请使用 `/new` 或 `/reset`。
 
-`/status` 会显示实际模型运行时。默认 PI harness 显示为 `Runtime: OpenClaw Pi Default`，而 Codex app-server harness 显示为 `Runtime: OpenAI Codex`。
+`/status` 会显示实际的模型运行时。默认的 Pi harness 显示为
+`Runtime: OpenClaw Pi Default`，而 Codex app-server harness 显示为
+`Runtime: OpenAI Codex`。
 
 ## 要求
 
-- OpenClaw，并且可用内置的 `codex` 插件。
-- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理一个兼容的 Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响正常的 harness 启动。
-- app-server 进程可用的 Codex 认证信息。
+- OpenClaw，且内置 `codex` 插件可用。
+- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理兼容的
+  Codex app-server 二进制文件，因此 `PATH` 上本地的 `codex` 命令
+  不会影响正常的 harness 启动。
+- app-server 进程或 OpenClaw 的 Codex auth
+  bridge 可用的 Codex 认证。
 
-该插件会阻止较旧或没有版本信息的 app-server 握手，以确保 OpenClaw 始终运行在其已测试过的协议接口上。
+该插件会阻止较旧或未带版本的 app-server 握手。这能让
+OpenClaw 保持在它已测试过的协议接口上。
 
-对于实时和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。
+对于 live 和 Docker 冒烟测试，认证通常来自 Codex CLI 账户
+或 OpenClaw `openai-codex` auth profile。本地 stdio app-server 启动
+在没有账户时，也可以回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。
 
 ## 最小配置
 
@@ -151,7 +197,7 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope
 }
 ```
 
-如果你的配置使用 `plugins.allow`，也要在其中包含 `codex`：
+如果你的配置使用 `plugins.allow`，也请将 `codex` 包含进去：
 
 ```json5
 {
@@ -166,19 +212,27 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope
 }
 ```
 
-将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>` 的旧配置，仍会自动启用内置 `codex` 插件。新的配置应优先使用 `openai/<model>`，再加上上面显式的 `agentRuntime` 条目。
+旧配置如果将 `agents.defaults.model` 或某个智能体模型设置为
+`codex/<model>`，仍会自动启用内置 `codex` 插件。新配置应优先
+使用 `openai/<model>`，并配合上面的显式 `agentRuntime` 条目。
 
 ## 将 Codex 与其他模型一起使用
 
-如果同一个智能体需要在 Codex 与非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用到该智能体或会话的每个嵌入式回合。如果你在强制该运行时的情况下选择了 Anthropic 模型，OpenClaw 仍会尝试使用 Codex harness，并以失败关闭，而不是悄悄地通过 PI 路由该回合。
+如果同一个智能体应该在 Codex 和非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。
+强制运行时会应用到该智能体或会话的每一次
+嵌入式轮次。如果你在强制该运行时的情况下选择了 Anthropic 模型，
+OpenClaw 仍会尝试使用 Codex harness，并且会以失败关闭的方式报错，而不是静默地通过 Pi 路由该轮次。
 
-请改用以下几种配置形式之一：
+请改用以下其中一种方式：
 
-- 将 Codex 放在一个专用智能体上，并设置 `agentRuntime.id: "codex"`。
-- 将默认智能体保留为 `agentRuntime.id: "auto"`，并为普通混合提供商用法保留 PI 后备。
-- 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用 `openai/*`，并配合显式的 Codex 运行时策略。
+- 将 Codex 放到一个专用智能体上，并设置 `agentRuntime.id: "codex"`。
+- 将默认智能体保持为 `agentRuntime.id: "auto"`，并为常规混合
+  提供商使用保留 Pi 回退。
+- 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用
+  `openai/*`，再加上显式的 Codex 运行时策略。
 
-例如，下面的配置会让默认智能体保持正常的自动选择，并额外添加一个单独的 Codex 智能体：
+例如，下面的配置会让默认智能体保持正常的自动选择，
+并额外添加一个独立的 Codex 智能体：
 
 ```json5
 {
@@ -215,31 +269,37 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope
 }
 ```
 
-采用这种形式时：
+采用这种方式：
 
-- 默认的 `main` 智能体使用普通提供商路径和 PI 兼容后备。
+- 默认的 `main` 智能体使用常规提供商路径和 Pi 兼容性回退。
 - `codex` 智能体使用 Codex app-server harness。
-- 如果 `codex` 智能体缺少 Codex 或不受支持，该回合会直接失败，而不是悄悄使用 PI。
+- 如果 `codex` 智能体缺少 Codex，或 Codex 对其不受支持，该轮次会直接失败，
+  而不是悄悄改为使用 Pi。
 
 ## 智能体命令路由
 
-智能体应根据用户意图路由请求，而不是仅凭 “Codex” 这个词：
+智能体应根据用户意图来路由请求，而不只是看到 “Codex” 这个词：
 
-| 用户请求的是…… | 智能体应使用…… |
+| 用户要求的是... | 智能体应使用... |
 | -------------------------------------------------------- | ------------------------------------------------ |
-| “将这个聊天绑定到 Codex” | `/codex bind` |
+| “将此聊天绑定到 Codex” | `/codex bind` |
 | “在这里恢复 Codex 线程 `<id>`” | `/codex resume <id>` |
 | “显示 Codex 线程” | `/codex threads` |
-| “将 Codex 用作这个智能体的运行时” | 将 `agentRuntime.id` 改为相应配置 |
-| “使用我的 ChatGPT/Codex 订阅并搭配普通 OpenClaw” | `openai-codex/*` 模型引用 |
+| “将 Codex 用作此智能体的运行时” | 将配置改为 `agentRuntime.id` |
+| “用我的 ChatGPT/Codex 订阅配合普通 OpenClaw” | `openai-codex/*` 模型引用 |
 | “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` |
 | “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 |
 
-只有在 ACP 已启用、可分发并由已加载的运行时后端支持时，OpenClaw 才会向智能体公开 ACP 启动指导。如果 ACP 不可用，系统提示和插件 Skills 不应向智能体传授 ACP 路由方式。
+只有在 ACP 已启用、可分发，并且由已加载的运行时后端支持时，
+OpenClaw 才会向智能体公开 ACP 启动指引。如果 ACP 不可用，
+系统提示和插件 Skills 不应向智能体传授 ACP
+路由方式。
 
-## 仅 Codex 的部署
+## 仅使用 Codex 的部署
 
-当你需要证明每个嵌入式智能体回合都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不使用 PI 后备，因此 `fallback: "none"` 是可选的，但通常作为文档说明很有用：
+当你需要证明每个嵌入式智能体轮次
+都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不会回退到 Pi，因此
+`fallback: "none"` 是可选的，但通常有助于作为文档说明：
 
 ```json5
 {
@@ -261,11 +321,15 @@ Harness 选择不是实时会话控制。当一个嵌入式回合运行时，Ope
 OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 ```
 
-在强制使用 Codex 的情况下，如果 Codex 插件被禁用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 会尽早失败。只有在你明确希望 PI 接管缺失的 harness 选择时，才设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
+强制使用 Codex 后，如果 Codex 插件被禁用、app-server
+版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。只有在你确实希望 Pi 处理
+缺失的 harness 选择时，才设置
+`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
 
-## 按智能体使用 Codex
+## 按智能体配置 Codex
 
-你可以让某一个智能体仅使用 Codex，而默认智能体继续保留正常的自动选择：
+你可以让某一个智能体仅使用 Codex，同时让默认智能体保持正常的
+自动选择：
 
 ```json5
 {
@@ -296,11 +360,15 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 }
 ```
 
-使用普通会话命令即可切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，Codex harness 会根据需要创建或恢复其 sidecar app-server 线程。`/reset` 会清除此线程的 OpenClaw 会话绑定，并让下一个回合再次根据当前配置解析 harness。
+使用普通会话命令即可切换智能体和模型。`/new` 会创建一个全新的
+OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其附属 app-server
+线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，
+并让下一轮再次根据当前配置解析 harness。
 
 ## 模型发现
 
-默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的后备目录，包含：
+默认情况下，Codex 插件会向 app-server 请求可用模型。如果
+发现失败或超时，它会使用内置的回退目录，包含：
 
 - GPT-5.5
 - GPT-5.4 mini
@@ -326,7 +394,8 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 }
 ```
 
-如果你希望启动时避免探测 Codex，而是固定使用后备目录，请禁用发现：
+如果你希望启动时避免探测 Codex，并固定使用
+回退目录，请禁用发现：
 
 ```json5
 {
@@ -345,19 +414,27 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 }
 ```
 
-## App-server 连接和策略
+## App-server 连接与策略
 
-默认情况下，插件会在本地使用以下命令启动由 OpenClaw 管理的 Codex 二进制文件：
+默认情况下，插件会在本地使用以下命令启动 OpenClaw 管理的 Codex 二进制文件：
 
 ```bash
 codex app-server --listen stdio://
 ```
 
-该托管二进制文件被声明为内置插件运行时依赖项，并与 `codex` 插件的其余依赖项一起准备就绪。这可以让 app-server 版本绑定到内置插件，而不是绑定到本地碰巧安装的某个独立 Codex CLI。只有在你明确想运行不同可执行文件时，才设置 `appServer.command`。
+该受管二进制文件被声明为内置插件运行时依赖，并与
+`codex` 插件的其他依赖一起暂存。
+这样可以将 app-server 版本绑定到内置插件，而不是绑定到本地碰巧安装的独立 Codex CLI。
+只有在你明确希望运行其他可执行文件时，才设置 `appServer.command`。
 
-默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 `sandbox: "danger-full-access"`。这是用于自主心跳的可信本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人可响应的原生审批提示上。
+默认情况下，OpenClaw 以 YOLO 模式启动本地 Codex harness 会话：
+`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及
+`sandbox: "danger-full-access"`。这是用于
+自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而无需停下来等待
+无人可答复的原生审批提示。
 
-如果要启用由 Codex guardian 审核的审批，请设置 `appServer.mode: "guardian"`：
+若要启用由 Codex guardian 审核的审批，请设置 `appServer.mode:
+"guardian"`：
 
 ```json5
 {
@@ -377,11 +454,20 @@ codex app-server --listen stdio://
 }
 ```
 
-Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求离开沙箱、在工作区之外写入，或添加网络访问等权限时，Codex 会将该审批请求路由给原生审核器，而不是人工提示。审核器会套用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多护栏，但仍需要无人值守的智能体持续推进，请使用 Guardian。
+Guardian 模式使用 Codex 原生自动审核审批路径。当 Codex 请求
+离开沙箱、在工作区外写入，或添加网络访问等权限时，
+Codex 会将该审批请求路由给原生审核者，而不是向人类发出提示。
+审核者会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你希望有比 YOLO 模式更多的防护，
+但仍需要无人值守的智能体持续推进工作时，请使用 Guardian。
 
-`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。单独的策略字段仍然会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。旧的 `guardian_subagent` reviewer 值仍然作为兼容别名被接受，但新配置应使用 `auto_review`。
+`guardian` 预设会展开为 `approvalPolicy: "on-request"`、
+`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。
+各个策略字段仍然可以覆盖 `mode`，因此高级部署可以将
+该预设与显式选择混用。较旧的 `guardian_subagent` 审核者值
+仍接受为兼容性别名，但新配置应使用
+`auto_review`。
 
-对于已经在运行的 app-server，请使用 WebSocket 传输：
+对于已在运行的 app-server，请使用 WebSocket 传输：
 
 ```json5
 {
@@ -403,22 +489,62 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
 }
 ```
 
+默认情况下，stdio app-server 启动会继承 OpenClaw 的进程环境，
+但 OpenClaw 负责 Codex app-server 账户 bridge。认证按以下顺序选择：
+
+1. 智能体的显式 OpenClaw Codex auth profile。
+2. app-server 现有的账户，例如本地 Codex CLI ChatGPT 登录。
+3. 仅对本地 stdio app-server 启动，当不存在 app-server 账户且仍需要 OpenAI 认证时，依次使用 `CODEX_API_KEY`，然后
+   `OPENAI_API_KEY`。
+
+当 OpenClaw 识别到 ChatGPT 订阅风格的 Codex auth profile 时，它会从已启动的 Codex 子进程中移除
+`CODEX_API_KEY` 和 `OPENAI_API_KEY`。
+这样既能保留 Gateway 网关级别的 API key 供 embeddings 或直接 OpenAI 模型使用，
+又能避免原生 Codex app-server 轮次意外通过 API 计费。
+显式的 Codex API-key profile 和本地 stdio 环境变量 key 回退会使用
+app-server 登录，而不是继承子进程环境。WebSocket app-server 连接
+不会接收 Gateway 网关环境变量 API key 回退；请使用显式 auth profile，或使用远程
+app-server 自身的账户。
+
+如果某个部署需要额外的环境隔离，请将这些变量添加到
+`appServer.clearEnv`：
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          appServer: {
+            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`appServer.clearEnv` 只会影响已启动的 Codex app-server 子进程。
+
 支持的 `appServer` 字段：
 
 | 字段 | 默认值 | 含义 |
-| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 |
-| `command` | 托管的 Codex 二进制文件 | 用于 stdio 传输的可执行文件。留空时使用托管二进制文件；仅在明确覆盖时设置。 |
-| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输的参数。 |
+| `command` | 受管 Codex 二进制文件 | 用于 stdio 传输的可执行文件。保持未设置即可使用受管二进制文件；仅在明确覆盖时设置。 |
+| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 |
 | `url` | 未设置 | WebSocket app-server URL。 |
-| `authToken` | 未设置 | WebSocket 传输的 Bearer token。 |
-| `headers` | `{}` | 额外的 WebSocket 标头。 |
+| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 |
+| `headers` | `{}` | 额外的 WebSocket headers。 |
+| `clearEnv` | `[]` | 在 OpenClaw 构建完继承环境后，从已启动的 stdio app-server 进程中额外移除的环境变量名。 |
 | `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 |
-| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 |
-| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/回合的原生 Codex 审批策略。 |
+| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 |
+| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 |
 | `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 |
 | `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 可让 Codex 审核原生审批提示。`guardian_subagent` 仍是旧版别名。 |
-| `serviceTier` | 未设置 | 可选的 Codex app-server service tier：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 |
+| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 |
 
 环境变量覆盖仍可用于本地测试：
 
@@ -428,16 +554,22 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
 - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
 - `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
 
-当 `appServer.command` 未设置时，`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过托管二进制文件。
+当 `appServer.command` 未设置时，`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过受管二进制文件。
 
-`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用 `plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试中使用 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，推荐使用配置，因为这样可以将插件行为与 Codex harness 设置的其余部分放在同一个经过审查的文件中。
+`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用
+`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试中使用
+`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，更推荐使用配置，
+因为这样可以将插件行为与 Codex harness 设置的其余部分保存在同一个经审查的文件中。
 
 ## Computer Use
 
-Computer Use 有单独的设置指南：
+Computer Use 在其单独的设置指南中说明：
 [Codex Computer Use](/zh-CN/plugins/codex-computer-use)。
 
-简而言之：OpenClaw 不会内置桌面控制应用，也不会自行执行桌面操作。它会准备 Codex app-server，验证 `computer-use` MCP 服务器是否可用，然后让 Codex 在 Codex 模式回合中处理原生 MCP 工具调用。
+简而言之：OpenClaw 不会内置桌面控制应用，也不会自行执行
+桌面操作。它会准备 Codex app-server，验证
+`computer-use` MCP 服务器是否可用，然后在 Codex 模式轮次期间让 Codex 处理原生
+MCP 工具调用。
 
 最小配置：
 
@@ -474,11 +606,18 @@ Computer Use 有单独的设置指南：
 - `/codex computer-use install --source <marketplace-source>`
 - `/codex computer-use install --marketplace-path <path>`
 
-Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 MCP 服务器不可用，Codex 模式回合会在线程启动前失败，而不是悄悄在没有原生 Computer Use 工具的情况下运行。有关 marketplace 选择、远程目录限制、状态原因和故障排除，请参阅 [Codex Computer Use](/zh-CN/plugins/codex-computer-use)。
+Computer Use 仅适用于 macOS，并且在 Codex MCP
+服务器能够控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true，而 MCP
+服务器不可用，则 Codex 模式轮次会在线程启动前失败，而不是在没有原生 Computer Use 工具的情况下静默运行。有关
+marketplace 选择、远程目录限制、状态原因和故障排除，请参见
+[Codex Computer Use](/zh-CN/plugins/codex-computer-use)。
 
-当 `computerUse.autoInstall` 为 true 时，如果 Codex 尚未发现本地 marketplace，OpenClaw 可以从 `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准内置的 Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使用 `/new` 或 `/reset`，这样现有会话就不会继续保留旧的 PI 或 Codex 线程绑定。
+当 `computerUse.autoInstall` 为 true 时，如果 Codex 尚未发现本地 marketplace，
+OpenClaw 可以从
+`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准的内置 Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使用 `/new` 或 `/reset`，
+以免现有会话继续保留旧的 Pi 或 Codex 线程绑定。
 
-## 常用配方
+## 常见配方
 
 使用默认 stdio 传输的本地 Codex：
 
@@ -494,7 +633,7 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前，
 }
 ```
 
-仅 Codex 的 harness 验证：
+仅使用 Codex 的 harness 验证：
 
 ```json5
 {
@@ -538,7 +677,7 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前，
 }
 ```
 
-带显式标头的远程 app-server：
+带显式 headers 的远程 app-server：
 
 ```json5
 {
@@ -561,15 +700,20 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前，
 }
 ```
 
-模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时，下一个回合会再次将当前选定的 OpenAI 模型、提供商、审批策略、沙箱和 service tier 发送给 app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选择的模型继续运行。
+模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时，
+下一轮会再次将当前选定的
+OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给
+app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留
+线程绑定，但会要求 Codex 使用新选定的模型继续。
 
 ## Codex 命令
 
-内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用的，适用于任何支持 OpenClaw 文本命令的渠道。
+内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用的，
+可在任何支持 OpenClaw 文本命令的渠道上工作。
 
 常见形式：
 
-- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。
+- `/codex status` 显示实时 app-server 连通性、模型、账户、速率限制、MCP 服务器和 Skills。
 - `/codex models` 列出实时 Codex app-server 模型。
 - `/codex threads [filter]` 列出最近的 Codex 线程。
 - `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有 Codex 线程。
@@ -581,100 +725,164 @@ Computer Use 仅适用于 macOS，在 Codex MCP 服务器控制应用之前，
 - `/codex mcp` 列出 Codex app-server MCP 服务器状态。
 - `/codex skills` 列出 Codex app-server Skills。
 
-`/codex resume` 会写入与 harness 在普通回合中使用的相同 sidecar 绑定文件。在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传递给 app-server，并继续启用扩展历史记录。
+`/codex resume` 会写入与 harness 在
+正常轮次中使用的同一个附属绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，向
+app-server 传入当前选定的 OpenClaw 模型，并保持启用扩展历史记录。
 
-该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，单个控制方法会被报告为 `unsupported by this Codex app-server`。
+该命令界面要求使用 Codex app-server `0.125.0` 或更高版本。如果未来或自定义的 app-server 未暴露相应的 JSON-RPC 方法，
+各个控制方法会显示为 `unsupported by this Codex app-server`。
 
-## 钩子边界
+## Hook 边界
 
-Codex harness 有三层钩子：
+Codex harness 有三层 hook：
 
-| 层级 | 所有者 | 用途 |
+| 层级 | 所有者 | 目的 |
 | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
-| OpenClaw 插件钩子 | OpenClaw | 在 PI 和 Codex harness 之间提供产品/插件兼容性。 |
-| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐回合适配器行为。 |
-| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 |
+| OpenClaw 插件钩子 | OpenClaw | 提供跨 Pi 和 Codex harness 的产品/插件兼容性。 |
+| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 |
+| Codex 原生 hooks | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 |
 
-OpenClaw 不会使用项目级或全局 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。对于受支持的原生工具和权限桥接，OpenClaw 会为每个线程注入 Codex 配置，用于 `PreToolUse`、`PostToolUse`、`PermissionRequest` 和 `Stop`。其他 Codex 钩子，例如 `SessionStart` 和 `UserPromptSubmit`，仍然是 Codex 级控制；在 v1 合约中，它们不会作为 OpenClaw 插件钩子暴露。
+OpenClaw 不会使用项目级或全局 Codex `hooks.json` 文件来路由
+OpenClaw 插件行为。对于受支持的原生工具和权限桥接，
+OpenClaw 会为 `PreToolUse`、`PostToolUse`、
+`PermissionRequest` 和 `Stop` 注入逐线程 Codex 配置。其他 Codex hooks，如 `SessionStart` 和
+`UserPromptSubmit`，仍然是 Codex 级控制；在 v1 合约中，它们不会作为
+OpenClaw 插件钩子暴露。
 
-对于 OpenClaw 动态工具，Codex 发起调用请求后，OpenClaw 才会执行工具，因此 OpenClaw 会在 harness 适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像部分事件，但除非 Codex 通过 app-server 或原生钩子回调公开该操作，否则它无法重写原生 Codex 线程。
+对于 OpenClaw 动态工具，在 Codex 请求调用后，OpenClaw 才会执行该工具，因此
+OpenClaw 会在
+harness 适配器中触发其所拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范的工具记录。
+OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生 hook
+回调暴露该操作，否则它无法改写原生 Codex
+线程。
 
-压缩和 LLM 生命周期投影来自 Codex app-server 通知以及 OpenClaw 适配器状态，而不是来自原生 Codex 钩子命令。OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 `llm_output` 事件是适配器级观察结果，而不是对 Codex 内部请求或压缩载荷的逐字节捕获。
+压缩和 LLM 生命周期投影来自 Codex app-server
+通知以及 OpenClaw 适配器状态，而不是原生 Codex hook 命令。
+OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和
+`llm_output` 事件是适配器级观察结果，而不是对
+Codex 内部请求或压缩负载的逐字节捕获。
 
-Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为用于轨迹和调试的 `codex_app_server.hook` 智能体事件。它们不会调用 OpenClaw 插件钩子。
+Codex 原生 `hook/started` 和 `hook/completed` app-server 通知
+会投影为 `codex_app_server.hook` 智能体事件，用于轨迹记录和调试。
+它们不会调用 OpenClaw 插件钩子。
 
 ## V1 支持合约
 
-Codex 模式并不是底层只换了一个模型调用的 PI。Codex 拥有更多原生模型循环，而 OpenClaw 会围绕这一边界适配自己的插件和会话界面。
+Codex 模式并不是仅仅在底层换了模型调用的 Pi。Codex 接管了更多
+原生模型 loop，而 OpenClaw 会围绕这一边界来适配其插件和会话界面。
 
-Codex 运行时 v1 中支持的内容：
+Codex runtime v1 中支持的内容：
 
 | 界面 | 支持情况 | 原因 |
 | --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 负责 OpenAI 回合、原生线程恢复和原生工具续接。 |
-| OpenClaw 渠道路由和投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道仍然位于模型运行时之外。 |
-| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍处于执行路径中。 |
-| 提示和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程之前构建提示叠加层，并将上下文投影到 Codex 回合中。 |
-| 上下文引擎生命周期 | 支持 | 组装、摄取或回合后维护，以及上下文引擎压缩协调，都适用于 Codex 回合。 |
-| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 拥有的动态工具运行。 |
-| 生命周期钩子 | 作为适配器观察结果支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会使用真实的 Codex 模式载荷触发。 |
-| 最终答案修订门控 | 通过原生钩子中继支持 | Codex `Stop` 会中继到 `before_agent_finalize`；`revise` 会在最终完成前请求 Codex 再进行一次模型推理。 |
-| 原生 shell、patch 和 MCP 阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会针对已承诺的原生工具界面进行中继，包括 Codex app-server `0.125.0` 或更高版本上的 MCP 载荷。支持阻止，不支持参数重写。 |
-| 原生权限策略 | 通过原生钩子中继支持 | 当运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略进行路由。如果 OpenClaw 不返回决策，Codex 会继续沿用其正常的 guardian 或用户审批路径。 |
-| app-server 轨迹捕获 | 支持 | OpenClaw 会记录其发送给 app-server 的请求，以及从 app-server 收到的通知。 |
+| 通过 Codex 的 OpenAI 模型 loop | 支持 | Codex app-server 负责 OpenAI 轮次、原生线程恢复和原生工具续接。 |
+| OpenClaw 渠道路由与投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 及其他渠道保持在模型运行时之外。 |
+| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。 |
+| Prompt 和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程前构建 prompt 覆盖层，并将上下文投射到 Codex 轮次中。 |
+| 上下文引擎生命周期 | 支持 | Codex 轮次会运行 assemble、ingest 或轮次后维护，以及上下文引擎压缩协调。 |
+| 动态工具 hooks | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 拥有的动态工具运行。 |
+| 生命周期 hooks | 作为适配器观察结果受支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式负载触发。 |
+| 最终答案修订门控 | 通过原生 hook 转发支持 | Codex `Stop` 会转发到 `before_agent_finalize`；`revise` 会在最终完成前请求 Codex 再进行一次模型轮次。 |
+| 原生 shell、patch 和 MCP 的拦截或观察 | 通过原生 hook 转发支持 | Codex `PreToolUse` 和 `PostToolUse` 会为已提交的原生工具界面进行转发，包括 Codex app-server `0.125.0` 或更高版本中的 MCP 负载。支持拦截；不支持参数改写。 |
+| 原生权限策略 | 通过原生 hook 转发支持 | 当运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 不返回决定，Codex 会继续走其正常的 guardian 或用户审批路径。 |
+| App-server 轨迹捕获 | 支持 | OpenClaw 会记录其发送给 app-server 的请求，以及从 app-server 接收到的通知。 |
 
-Codex 运行时 v1 中不支持的内容：
+Codex runtime v1 中不支持的内容：
 
 | 界面 | V1 边界 | 未来路径 |
 | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| 原生工具参数变更 | Codex 原生 pre-tool 钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持替换工具输入。 |
-| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，并可以投影未来上下文，但不应修改不受支持的内部结构。 | 如果需要原生线程手术操作，则添加显式 Codex app-server API。 |
-| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子转换的是 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范重写需要 Codex 支持。 |
-| 丰富的原生压缩元数据 | OpenClaw 可以观察压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 变化量或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 |
-| 压缩干预 | 当前 OpenClaw 压缩钩子在 Codex 模式下仅限通知级别。 | 如果插件需要否决或重写原生压缩，则添加 Codex 前/后压缩钩子。 |
-| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但 Codex core 会在内部构建最终的 OpenAI API 请求。 | 需要 Codex 模型请求追踪事件或调试 API。 |
+| 原生工具参数变更 | Codex 原生 pre-tool hooks 可以拦截，但 OpenClaw 不会改写 Codex 原生工具参数。 | 需要 Codex hook/schema 支持替换工具输入。 |
+| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，并可以投射未来上下文，但不应修改不受支持的内部结构。 | 如果需要原生线程手术能力，应添加显式的 Codex app-server API。 |
+| 用于 Codex 原生工具记录的 `tool_result_persist` | 该 hook 转换的是由 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范改写需要 Codex 支持。 |
+| 丰富的原生压缩元数据 | OpenClaw 可以观察到压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 差值或摘要负载。 | 需要更丰富的 Codex 压缩事件。 |
+| 压缩干预 | 当前 OpenClaw 的压缩 hooks 在 Codex 模式下仅为通知级。 | 如果插件需要否决或改写原生压缩，则需要添加 Codex pre/post compaction hooks。 |
+| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但最终的 OpenAI API 请求由 Codex 核心在内部构建。 | 需要 Codex 模型请求追踪事件或调试 API。 |
 
-## 工具、媒体和压缩
+## 工具、媒体与压缩
 
-Codex harness 只会改变底层的嵌入式智能体执行器。
+Codex harness 只改变底层的嵌入式智能体执行器。
 
-OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过正常的 OpenClaw 投递路径处理。
+OpenClaw 仍然会构建工具列表，并从
+harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批和消息工具输出
+仍然通过正常的 OpenClaw 投递路径继续处理。
 
-原生钩子中继有意保持通用，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP 的 `PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。在运行时合约明确命名前，不要假设未来每个 Codex 钩子事件都会成为 OpenClaw 插件界面。
+原生 hook 转发被有意设计为通用机制，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具和权限路径。在
+Codex runtime 中，这包括 shell、patch 和 MCP 的 `PreToolUse`、
+`PostToolUse` 以及 `PermissionRequest` 负载。不要假设未来每个
+Codex hook 事件都会成为 OpenClaw 插件界面，除非运行时合约明确命名了它。
 
-对于 `PermissionRequest`，只有在策略做出决定时，OpenClaw 才会返回显式的允许或拒绝决策。无决策结果并不等于允许。Codex 会将其视为没有钩子决策，并回退到它自己的 guardian 或用户审批路径。
+对于 `PermissionRequest`，只有在策略做出决定时，OpenClaw 才会返回明确的允许或拒绝决定。
+无决定结果并不等于允许。Codex 会将其视为没有
+hook 决定，并回退到其自身的 guardian 或用户审批路径。
 
-当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件审批流程进行路由。Codex 的 `request_user_input` 提示会被发送回原始聊天，而下一个排队的后续消息会回答那个原生服务器请求，而不是作为额外上下文进行引导。其他 MCP 征询请求仍然会以失败关闭。
+当 Codex 将 `_meta.codex_approval_kind` 标记为
+`"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件
+审批流程进行路由。Codex 的 `request_user_input` 提示会被发回
+发起聊天，而下一条排队的后续消息会回答该原生
+服务器请求，而不是作为额外上下文进行引导。其他 MCP 征询请求仍会以失败关闭方式处理。
 
-当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset` 以及未来的模型或 harness 切换。这个镜像包括用户提示、最终助手文本，以及 app-server 发出这些内容时的轻量级 Codex 推理或计划记录。当前，OpenClaw 只记录原生压缩开始和完成信号。它尚未公开可供人类阅读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。
+当所选模型使用 Codex harness 时，原生线程压缩会委托给
+Codex app-server。OpenClaw 仍会保留一个转录镜像，用于渠道
+历史记录、搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该
+镜像包括用户 prompt、最终助手文本，以及当 app-server 发出时的轻量级 Codex
+推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未公开
+人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的
+可审计列表。
 
-由于 Codex 拥有规范的原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它只在 OpenClaw 正在写入由 OpenClaw 拥有的会话转录工具结果时生效。
+由于 Codex 拥有规范的原生线程，`tool_result_persist` 当前不会
+改写 Codex 原生工具结果记录。它仅适用于
+OpenClaw 正在写入由 OpenClaw 拥有的会话转录工具结果时。
 
-媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用对应的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
+媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解
+仍然继续使用匹配的提供商/模型设置，例如
+`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和
+`messages.tts`。
 
 ## 故障排除
 
-**Codex 没有作为普通 `/model` provider 出现：** 这对新配置来说是预期行为。请选择 `openai/gpt-*` 模型，并设置 `agentRuntime.id: "codex"`（或使用旧版 `codex/*` 引用），启用 `plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了 `codex`。
+**Codex 没有显示为普通的 `/model` 提供商：** 这对于
+新配置是预期行为。请选择一个 `openai/gpt-*` 模型，并设置
+`agentRuntime.id: "codex"`（或使用旧版 `codex/*` 引用），启用
+`plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了
+`codex`。
 
-**OpenClaw 使用的是 PI 而不是 Codex：** `agentRuntime.id: "auto"` 在没有 Codex harness 接管该运行时，仍可能使用 PI 作为兼容后端。测试时请设置 `agentRuntime.id: "codex"` 以强制选择 Codex。强制使用 Codex 运行时现在会直接失败，而不是回退到 PI，除非你显式设置 `agentRuntime.fallback: "pi"`。一旦选择了 Codex app-server，它的失败会直接暴露出来，不需要额外的后备配置。
+**OpenClaw 使用的是 Pi 而不是 Codex：** 当没有 Codex harness 认领该运行时，`agentRuntime.id: "auto"` 仍可能使用 Pi 作为
+兼容性后端。测试时请设置
+`agentRuntime.id: "codex"` 以强制选择 Codex。现在，强制的 Codex
+运行时会直接失败，而不是回退到 Pi，除非你
+显式设置 `agentRuntime.fallback: "pi"`。一旦选择了 Codex app-server，
+其失败会直接暴露出来，而不需要额外的回退配置。
 
-**app-server 被拒绝：** 请升级 Codex，使 app-server 握手报告版本为 `0.125.0` 或更新版本。相同版本号的预发布版本或带构建后缀的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为 OpenClaw 测试所依据的协议下限是稳定版 `0.125.0`。
+**app-server 被拒绝：** 升级 Codex，使 app-server 握手
+报告版本 `0.125.0` 或更高。相同版本号的预发布版或带构建后缀的
+版本，如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为
+OpenClaw 测试的是稳定版 `0.125.0` 协议下限。
 
-**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`，或禁用发现。
+**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`
+或禁用发现功能。
 
-**WebSocket 传输立即失败：** 请检查 `appServer.url`、`authToken`，并确认远程 app-server 使用的是相同版本的 Codex app-server 协议。
+**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，
+以及远程 app-server 是否使用相同的 Codex app-server 协议版本。
 
-**非 Codex 模型使用了 PI：** 这是预期行为，除非你为该智能体强制设置了 `agentRuntime.id: "codex"`，或者选择了旧版 `codex/*` 引用。普通的 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下会保留其正常的提供商路径。如果你强制设置了 `agentRuntime.id: "codex"`，则该智能体的每个嵌入式回合都必须是 Codex 支持的 OpenAI 模型。
+**非 Codex 模型使用了 Pi：** 这是预期行为，除非你为该智能体强制设置了
+`agentRuntime.id: "codex"`，或者选择了旧版
+`codex/*` 引用。普通的 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下仍会走其正常
+提供商路径。如果你强制设置了 `agentRuntime.id: "codex"`，那么该智能体的每一次嵌入式
+轮次都必须是 Codex 支持的 OpenAI 模型。
 
-**Computer Use 已安装，但工具无法运行：** 请在一个新会话中检查 `/codex computer-use status`。如果某个工具报告 `Native hook relay unavailable`，请使用 `/new` 或 `/reset`；如果问题仍然存在，请重启 Gateway 网关以清除过时的原生钩子注册。如果 `computer-use.list_apps` 超时，请重启 Codex Computer Use 或 Codex Desktop，然后重试。
+**Computer Use 已安装，但工具无法运行：** 请在新会话中检查
+`/codex computer-use status`。如果某个工具报告
+`Native hook relay unavailable`，请使用 `/new` 或 `/reset`；如果仍然存在，请重启
+Gateway 网关以清除过期的原生 hook 注册。如果 `computer-use.list_apps`
+超时，请重启 Codex Computer Use 或 Codex Desktop 后重试。
 
 ## 相关内容
 
 - [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness)
 - [Agent Runtimes](/zh-CN/concepts/agent-runtimes)
-- [模型提供商](/zh-CN/concepts/model-providers)
+- [Model providers](/zh-CN/concepts/model-providers)
 - [OpenAI provider](/zh-CN/providers/openai)
 - [Status](/zh-CN/cli/status)
-- [插件钩子](/zh-CN/plugins/hooks)
-- [配置参考](/zh-CN/gateway/configuration-reference)
+- [Plugin hooks](/zh-CN/plugins/hooks)
+- [Configuration reference](/zh-CN/gateway/configuration-reference)
 - [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)

docs/zh-CN/providers/openai.md

@@ -6,34 +6,34 @@ read_when:
 summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
 title: OpenAI
 x-i18n:
-    generated_at: "2026-04-27T13:31:48Z"
+    generated_at: "2026-04-27T23:52:39Z"
     model: gpt-5.4
     provider: openai
-    source_hash: f6a33485bb8372dca81d91d35a4fddca315613336adf601efa7ef9a418bf8480
+    source_hash: b9cce8535a4ed5991fc931783daa8908fd2ba1e6e183ea5bcbbcffcfad9f76bd
     source_path: providers/openai.md
     workflow: 15
 ---
 
-OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端，作为 ChatGPT 计划中的编码智能体使用。OpenClaw 将这些能力面分开处理，以便让配置保持可预测。
+OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端作为 ChatGPT 计划中的编程智能体使用。OpenClaw 将这些能力面分开处理，以便让配置保持可预测。
 
-OpenClaw 支持三种 OpenAI 家族路由。模型前缀用于选择提供商 / 认证路由；另一个单独的运行时设置用于选择由谁执行嵌入式 Agent loop：
+OpenClaw 支持三种 OpenAI 家族路由。模型前缀会选择提供商 / 认证路由；单独的运行时设置会选择由谁执行嵌入式 Agent loop：
 
 - **API 密钥** — 通过直接 OpenAI Platform 访问并按用量计费（`openai/*` 模型）
-- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
+- **通过 PI 使用 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
 - **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，加上 `agents.defaults.agentRuntime.id: "codex"`）
 
-OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。
+OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
 
-提供商、模型、运行时和渠道是彼此独立的层。如果你把这些标签混在一起了，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再修改配置。
+提供商、模型、运行时和渠道是彼此独立的层。如果你把这些标签混在了一起，请在修改配置前先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
 
 ## 快速选择
 
 | 目标 | 使用方式 | 说明 |
 | --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
-| 直接 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY`，或运行 OpenAI API 密钥新手引导。 |
-| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。对于订阅配置，这是最佳首选。 |
-| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
-| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 搭配使用。 |
+| 直接使用 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 |
+| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | 适用于 Codex OAuth 的默认 PI 路由。是订阅配置的首选。 |
+| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加上 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
+| 图像生成或编辑 | `openai/gpt-image-2` | 可配合 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 |
 | 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
 
 ## 命名映射
@@ -43,21 +43,21 @@ OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订
 | 你看到的名称 | 层级 | 含义 |
 | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
 | `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
-| `openai-codex` | 提供商前缀 | 通过常规 OpenClaw PI runner 使用 OpenAI Codex OAuth / 订阅路由。 |
+| `openai-codex` | 提供商前缀 | 通过标准 OpenClaw PI 运行器使用 OpenAI Codex OAuth / 订阅的路由。 |
 | `codex` plugin | 插件 | OpenClaw 内置插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
 | `agentRuntime.id: codex` | Agent 运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
 | `/codex ...` | 聊天命令集 | 在对话中绑定 / 控制 Codex app-server 线程。 |
 | `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
 
-这意味着，一个配置中可以有意同时包含 `openai-codex/*` 和 `codex` plugin。当你希望通过 PI 使用 Codex OAuth，同时又希望可使用原生 `/codex` 聊天控制时，这样做是有效的。`openclaw doctor` 会对这种组合发出警告，以便你确认这是有意为之；它不会重写该配置。
+这意味着一个配置中可以有意同时包含 `openai-codex/*` 和 `codex` plugin。当你希望通过 PI 使用 Codex OAuth，同时也希望原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对这种组合发出警告，以便你确认这是有意为之；它不会重写该配置。
 
 <Note>
-GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问，以及订阅 / OAuth 路由访问。对直接 `OPENAI_API_KEY` 流量，请使用 `openai/gpt-5.5`；对通过 PI 的 Codex OAuth，请使用 `openai-codex/gpt-5.5`；若要使用原生 Codex app-server harness，请使用 `openai/gpt-5.5` 并配合 `agentRuntime.id: "codex"`。
+GPT-5.5 同时支持直接 OpenAI Platform API 密钥访问和订阅 / OAuth 路由。对直接 `OPENAI_API_KEY` 流量使用 `openai/gpt-5.5`，对通过 PI 使用 Codex OAuth 使用 `openai-codex/gpt-5.5`，或者将 `openai/gpt-5.5` 与 `agentRuntime.id: "codex"` 一起使用以启用原生 Codex app-server harness。
 </Note>
 
 <Note>
-启用 OpenAI plugin，或选择 `openai-codex/*` 模型，并不会启用内置的 Codex app-server plugin。只有在你明确通过 `agentRuntime.id: "codex"` 选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。
-如果内置 `codex` plugin 已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告，并保持该路由不变。
+启用 OpenAI plugin，或选择 `openai-codex/*` 模型，并不会启用内置的 Codex app-server plugin。只有当你显式选择原生 Codex harness（使用 `agentRuntime.id: "codex"`）或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。
+如果内置的 `codex` plugin 已启用，但 `openai-codex/*` 仍然通过 PI 解析，`openclaw doctor` 会发出警告并保持该路由不变。
 </Note>
 
 ## OpenClaw 功能覆盖范围
@@ -65,20 +65,20 @@ GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问，以及订阅
 | OpenAI 能力 | OpenClaw 能力面 | Status |
 | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
 | 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
-| Codex 订阅模型 | 带有 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
-| Codex app-server harness | 带有 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
-| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
+| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
+| Codex app-server harness | 带 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
+| 服务端 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 | 是 |
-| Embeddings | memory embedding provider | 是 |
+| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
+| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
+| Embeddings | Memory Wiki 嵌入提供商 | 是 |
 
 ## Memory embeddings
 
-OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼容 OpenAI 的嵌入端点：
+OpenClaw 可以将 OpenAI 或与 OpenAI 兼容的嵌入端点用于 `memory_search` 的索引和查询嵌入：
 
 ```json5
 {
@@ -93,15 +93,15 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼
 }
 ```
 
-对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆分块和批量索引使用 `documentInputType`。完整示例请参阅 [Memory configuration reference](/zh-CN/reference/memory-config#provider-specific-config)。
+对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；索引后的内存分块和批量索引使用 `documentInputType`。完整示例请参阅 [Memory 配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
 
 ## 入门指南
 
-选择你偏好的认证方式，并按照设置步骤操作。
+选择你偏好的认证方式，并按步骤完成设置。
 
 <Tabs>
   <Tab title="API 密钥（OpenAI Platform）">
-    **最适合：** 直接 API 访问和按量计费。
+    **最适合：** 直接 API 访问和按用量计费。
 
     <Steps>
       <Step title="获取你的 API 密钥">
@@ -129,12 +129,12 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼
 
     | 模型引用 | 运行时配置 | 路由 | 认证 |
     | ---------------------- | -------------------------- | --------------------------- | ---------------- |
-    | `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: "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` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
 
     <Note>
-    `openai/*` 是直接 OpenAI API 密钥路由，除非你显式强制使用 Codex app-server harness。对于通过默认 PI runner 的 Codex OAuth，请使用 `openai-codex/*`；若要使用原生 Codex app-server 执行，请使用 `openai/gpt-5.5` 并配合 `agentRuntime.id: "codex"`。
+    `openai/*` 默认是直接 OpenAI API 密钥路由，除非你显式强制使用 Codex app-server harness。通过默认 PI 运行器使用 Codex OAuth 时，请使用 `openai-codex/*`；若要原生 Codex app-server 执行，则使用 `openai/gpt-5.5` 并设置 `agentRuntime.id: "codex"`。
     </Note>
 
     ### 配置示例
@@ -147,7 +147,7 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼
     ```
 
     <Warning>
-    OpenClaw **不**公开提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也未公开它。
+    OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也未提供它。
     </Warning>
 
   </Tab>
@@ -167,7 +167,7 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼
         openclaw models auth login --provider openai-codex
         ```
 
-        对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT device-code 流程登录，而不是使用 localhost 浏览器回调：
+        对于无头环境或不适合回调的环境，可以添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
 
         ```bash
         openclaw models auth login --provider openai-codex --device-code
@@ -189,12 +189,12 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼
 
     | 模型引用 | 运行时配置 | 路由 | 认证 |
     |-----------|----------------|-------|------|
-    | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
-    | `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非某个插件显式声明 `openai-codex` | Codex 登录 |
-    | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server auth |
+    | `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
+    | `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍然是 PI，除非某个插件显式接管 `openai-codex` | Codex 登录 |
+    | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 认证 |
 
     <Note>
-    对于认证 / 配置文件命令，请继续使用 `openai-codex` provider id。`openai-codex/*` 模型前缀也是通过 PI 的 Codex OAuth 的显式路由。
+    认证 / 配置文件命令仍应使用 `openai-codex` 提供商 id。`openai-codex/*` 模型前缀也是通过 PI 使用 Codex OAuth 的显式路由。
     它不会选择或自动启用内置的 Codex app-server harness。
     </Note>
 
@@ -207,55 +207,75 @@ OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼
     ```
 
     <Note>
-    新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的 device-code 流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
+    新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭据。
     </Note>
 
     ### Status 指示器
 
-    聊天中的 `/status` 会显示当前会话启用了哪个模型运行时。默认的 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选择内置 Codex app-server harness 时，`/status` 会显示 `Runtime: OpenAI Codex`。现有会话会保留其已记录的 harness id，因此如果你在更改 `agentRuntime` 后希望 `/status` 反映新的 PI / Codex 选择，请使用 `/new` 或 `/reset`。
+    聊天中的 `/status` 会显示当前会话正在使用的模型运行时。
+    默认的 PI harness 会显示为 `Runtime: OpenClaw Pi Default`。选择内置 Codex app-server harness 时，`/status` 会显示
+    `Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `agentRuntime` 后希望 `/status` 反映新的 PI / Codex 选择，请使用
+    `/new` 或 `/reset`。
 
     ### Doctor 警告
 
-    如果在选择此标签页中的 `openai-codex/*` 路由时，内置的 `codex` plugin 也已启用，`openclaw doctor` 会警告该模型仍然通过 PI 解析。如果这是你预期的订阅认证路由，请保持配置不变。只有当你想要原生 Codex app-server 执行时，才切换到 `openai/<model>` 加 `agentRuntime.id: "codex"`。
+    如果启用了内置 `codex` plugin，同时本标签页中选择了
+    `openai-codex/*` 路由，`openclaw doctor` 会警告该模型
+    仍然通过 PI 解析。如果这正是你想要的订阅认证路由，请保持配置不变。只有当你想要原生 Codex
+    app-server 执行时，才切换为 `openai/<model>` 加上
+    `agentRuntime.id: "codex"`。
 
-### 上下文窗口上限
+    ### 上下文窗口上限
 
-OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
+    OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
 
-对于通过 Codex OAuth 的 `openai-codex/gpt-5.5`：
+    对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
 
-- 原生 `contextWindow`：`1000000`
-- 默认运行时 `contextTokens` 上限：`272000`
+    - 原生 `contextWindow`：`1000000`
+    - 默认运行时 `contextTokens` 上限：`272000`
 
-在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
+    在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
 
-```json5
-{
-  models: {
-    providers: {
-      "openai-codex": {
-        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
+    ```json5
+    {
+      models: {
+        providers: {
+          "openai-codex": {
+            models: [{ id: "gpt-5.5", contextTokens: 160000 }],
+          },
+        },
       },
-    },
-  },
-}
-```
+    }
+    ```
 
-<Note>
-使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。
-</Note>
+    <Note>
+    使用 `contextWindow` 来声明模型的原生元数据。使用 `contextTokens` 来限制运行时上下文预算。
+    </Note>
 
-### 目录恢复
+    ### 目录恢复
 
-当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果实时 Codex 发现未返回 `openai-codex/gpt-5.5` 这一行，但账户已完成认证，OpenClaw 会合成这一 OAuth 模型行，以避免 cron、子智能体和已配置的默认模型运行因 `Unknown model` 而失败。
+    当存在时，OpenClaw 会对 `gpt-5.5` 使用上游 Codex 目录元数据。如果实时 Codex 发现结果中缺少 `openai-codex/gpt-5.5` 这一行，而账户又已完成认证，OpenClaw 会合成这一 OAuth 模型条目，以避免 cron、子智能体和已配置默认模型的运行因 `Unknown model` 而失败。
 
   </Tab>
 </Tabs>
 
+## 原生 Codex app-server 认证
+
+原生 Codex app-server harness 使用 `openai/*` 模型引用加上
+`agentRuntime.id: "codex"`，但其认证仍然基于账户。OpenClaw
+按以下顺序选择认证方式：
+
+1. 绑定到该智能体的显式 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 密钥回退仅适用于本地 stdio 无账户路径；它不会发送到 WebSocket app-server 连接。当选择订阅式 Codex 配置文件时，OpenClaw 还会将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 排除在生成的 stdio app-server 子进程之外，并通过 app-server 登录 RPC 发送所选凭据。
+
 ## 图像生成
 
-内置的 `openai` plugin 通过 `image_generate` 工具注册图像生成功能。
-它支持使用同一个 `openai/gpt-image-2` 模型引用，通过 OpenAI API 密钥进行图像生成，以及通过 Codex OAuth 进行图像生成。
+内置的 `openai` plugin 通过 `image_generate` 工具注册图像生成。
+它同时支持使用 OpenAI API 密钥进行图像生成，以及通过同一个 `openai/gpt-image-2` 模型引用进行 Codex OAuth 图像生成。
 
 | 能力 | OpenAI API 密钥 | Codex OAuth |
 | ------------------------- | ---------------------------------- | ------------------------------------ |
@@ -263,9 +283,9 @@ OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值
 | 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
 | 传输 | OpenAI Images API | Codex Responses 后端 |
 | 每次请求的最大图像数 | 4 | 4 |
-| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
+| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） |
 | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
-| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 |
+| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射到受支持的尺寸 |
 
 ```json5
 {
@@ -278,12 +298,16 @@ OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值
 ```
 
 <Note>
-有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/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"`。
 
-对于透明背景请求，智能体应调用 `image_generate`，并设置 `model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及 `background: "transparent"`；旧的 `openai.background` 提供商选项仍然被接受。OpenClaw 还会通过将默认 `openai/gpt-image-2` 的透明背景请求重写为 `gpt-image-1.5`，来保护公共 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点则保留它们已配置的部署 / 模型名称。
+对于透明背景请求，智能体应调用 `image_generate`，并使用
+`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及
+`background: "transparent"`；较旧的 `openai.background` 提供商选项仍然受支持。OpenClaw 还会通过将默认的 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5` 来保护公共 OpenAI 和
+OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署 / 模型名称。
 
 相同设置也适用于无头 CLI 运行：
 
@@ -296,11 +320,13 @@ 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` 引用。当配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会在该请求中静默回退到 API 密钥。如果你想改用直接 OpenAI Images API 路由，请显式配置 `models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。
-如果该自定义图像端点位于受信任的 LAN / 私有地址上，还要设置 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有这一显式启用项，OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。
+对于 Codex OAuth 安装，继续使用相同的 `openai/gpt-image-2` 引用。当配置了
+`openai-codex` OAuth 配置文件时，OpenClaw 会解析已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。对于该请求，它不会先尝试 `OPENAI_API_KEY`，也不会静默回退到 API 密钥。如果你希望改为直接 OpenAI Images API 路由，请使用 API 密钥、自定义 base URL 或 Azure 端点显式配置 `models.providers.openai`。
+如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需设置
+`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有此显式启用项，OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。
 
 生成：
 
@@ -322,15 +348,15 @@ openclaw infer image generate \
 
 ## 视频生成
 
-内置的 `openai` plugin 通过 `video_generate` 工具注册视频生成功能。
+内置的 `openai` plugin 通过 `video_generate` 工具注册视频生成。
 
 | 能力 | 值 |
 | ---------------- | --------------------------------------------------------------------------------- |
 | 默认模型 | `openai/sora-2` |
-| 模式 | 文生视频、图生视频、单视频编辑 |
+| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
 | 参考输入 | 1 张图像或 1 个视频 |
 | 尺寸覆盖 | 支持 |
-| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
+| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 |
 
 ```json5
 {
@@ -343,16 +369,16 @@ openclaw infer image generate \
 ```
 
 <Note>
-有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/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 行为和心跳覆盖层，因此，强制通过 `agentRuntime.id: "codex"` 的 `openai/gpt-5.x` 会话，即使其余 harness 提示词由 Codex 控制，也会保留相同的跟进行为和主动心跳指导。
+内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此即使 Codex 接管了其余的 harness 提示，被强制通过 `agentRuntime.id: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动心跳指引。
 
-GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层是独立且可配置的。
+GPT-5 提示贡献为人格持续性、执行安全、工具纪律、输出形状、完成检查和验证添加了带标签的行为契约。渠道特定的回复和静默消息行为则保留在共享的 OpenClaw 系统提示和出站传递策略中。GPT-5 指引始终对匹配模型启用。友好交互风格层是独立的，并且可配置。
 
 | 值 | 效果 |
 | ---------------------- | ------------------------------------------- |
@@ -382,14 +408,14 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
 </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）">
@@ -398,14 +424,14 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
     | 设置 | 配置路径 | 默认值 |
     |---------|------------|---------|
     | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
-    | 语音 | `messages.tts.providers.openai.voice` | `coral` |
+    | 音色 | `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
     {
@@ -426,14 +452,16 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
   </Accordion>
 
   <Accordion title="语音转文本">
-    内置的 `openai` plugin 通过 OpenClaw 的媒体理解转录能力面注册了批量语音转文本功能。
+    内置的 `openai` plugin 通过
+    OpenClaw 的媒体理解转录能力面注册了批量语音转文本。
 
     - 默认模型：`gpt-4o-transcribe`
     - 端点：OpenAI REST `/v1/audio/transcriptions`
     - 输入路径：multipart 音频文件上传
-    - 在 OpenClaw 中，凡是入站音频转录使用 `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道音频附件
+    - 在 OpenClaw 中，凡是入站音频转录使用
+      `tools.media.audio` 的地方都受支持，包括 Discord 语音频道片段和渠道音频附件
 
-    若要为入站音频转录强制使用 OpenAI：
+    如需为入站音频转录强制使用 OpenAI：
 
     ```json5
     {
@@ -453,36 +481,36 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
     }
     ```
 
-    当共享音频媒体配置或按调用的转录请求提供了语言和提示词提示时，OpenClaw 会将它们转发给 OpenAI。
+    当通过共享音频媒体配置或按次转录请求提供语言和提示时，OpenAI 会接收并使用这些提示信息。
 
   </Accordion>
 
   <Accordion title="实时转录">
-    内置的 `openai` plugin 为 Voice Call 插件注册了实时转录功能。
+    内置的 `openai` plugin 为 Voice Call plugin 注册了实时转录功能。
 
     | 设置 | 配置路径 | 默认值 |
     |---------|------------|---------|
     | 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
     | 语言 | `...openai.language` | （未设置） |
-    | 提示词 | `...openai.prompt` | （未设置） |
+    | 提示 | `...openai.prompt` | （未设置） |
     | 静音时长 | `...openai.silenceDurationMs` | `800` |
     | VAD 阈值 | `...openai.vadThreshold` | `0.5` |
     | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
 
     <Note>
-    使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
+    使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前则会录制短片段，并改用批量 `tools.media.audio` 转录路径。
     </Note>
 
   </Accordion>
 
   <Accordion title="实时语音">
-    内置的 `openai` plugin 为 Voice Call 插件注册了实时语音功能。
+    内置的 `openai` plugin 为 Voice Call plugin 注册了实时语音功能。
 
     | 设置 | 配置路径 | 默认值 |
     |---------|------------|---------|
     | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
-    | 语音 | `...openai.voice` | `alloy` |
-    | Temperature | `...openai.temperature` | `0.8` |
+    | 音色 | `...openai.voice` | `alloy` |
+    | 温度 | `...openai.temperature` | `0.8` |
     | VAD 阈值 | `...openai.vadThreshold` | `0.5` |
     | 静音时长 | `...openai.silenceDurationMs` | `500` |
     | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
@@ -492,9 +520,9 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
     </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>
@@ -502,15 +530,14 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
 
 ## Azure OpenAI 端点
 
-内置的 `openai` provider 可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求格式。
+内置的 `openai` 提供商可以通过覆盖 base 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 OpenAI 订阅、配额或企业协议
 - 你需要 Azure 提供的区域数据驻留或合规控制
@@ -518,9 +545,9 @@ GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持
 
 ### 配置
 
-若要通过内置的 `openai` provider 使用 Azure 进行图像生成，请将
+若要通过内置 `openai` 提供商使用 Azure 进行图像生成，请将
 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
-Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
+Azure OpenAI 密钥（而非 OpenAI Platform 密钥）：
 
 ```json5
 {
@@ -535,33 +562,33 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
 }
 ```
 
-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}/...`）
-- 为每个请求追加 `?api-version=...`
+- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
+- 使用按部署作用域划分的路径（`/openai/deployments/{deployment}/...`）
+- 为每个请求附加 `?api-version=...`
 - 对 Azure 图像生成调用使用默认 600 秒请求超时。
-  每次调用的 `timeoutMs` 值仍会覆盖此默认值。
+  按次调用的 `timeoutMs` 值仍会覆盖此默认值。
 
 其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的
 OpenAI 图像请求格式。
 
 <Note>
-`openai` provider 的 Azure 图像生成路由需要
+`openai` 提供商图像生成路径的 Azure 路由要求
 OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
-`openai.baseUrl` 视为公共 OpenAI 端点，从而在 Azure 图像部署上失败。
+`openai.baseUrl` 按公共 OpenAI 端点处理，因此无法用于 Azure
+图像部署。
 </Note>
 
 ### API 版本
 
-设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的
-Azure 预览版或正式版版本：
+设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定某个 Azure 预览版或 GA 版本：
 
 ```bash
 export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
@@ -571,58 +598,54 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
 
 ### 模型名称就是部署名称
 
-Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 id。
+Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` 提供商路由的 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` 提供商路由的图像生成调用。
 
 ### 区域可用性
 
-Azure 图像生成目前仅在部分区域可用
+Azure 图像生成当前仅在部分区域可用
 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
-`uaenorth`）。创建部署前，请先查看 Microsoft 最新的区域列表，并确认你的区域中提供该特定模型。
+`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) 下的 **原生 vs OpenAI-compatible routes** 折叠项。
+OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-configuration) 下 **原生与 OpenAI 兼容路由** 折叠项。
 
-对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用
-新手引导流程或专用的 Azure provider 配置 —— 仅设置
-`openai.baseUrl` 不会启用 Azure API / 认证格式。另有一个独立的
-`azure-openai-responses/*` provider；请参阅下方的
-服务端压缩折叠项。
+若要在 Azure 上使用聊天或 Responses 流量（除图像生成外），请使用新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl` 并不会自动采用 Azure 的 API / 认证格式。另有单独的
+`azure-openai-responses/*` 提供商；请参阅下方的服务端压缩折叠项。
 </Note>
 
 ## 高级配置
 
 <AccordionGroup>
-  <Accordion title="传输方式（WebSocket vs SSE）">
-    OpenClaw 对 `openai/*` 和 `openai-codex/*` 都使用 WebSocket 优先、SSE 回退（`"auto"`）。
+  <Accordion title="传输（WebSocket 与 SSE）">
+    对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 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 回退 |
-    | `"sse"` | 强制仅使用 SSE |
-    | `"websocket"` | 强制仅使用 WebSocket |
+    | `"sse"` | 仅强制使用 SSE |
+    | `"websocket"` | 仅强制使用 WebSocket |
 
     ```json5
     {
@@ -668,12 +691,12 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
   </Accordion>
 
   <Accordion title="快速模式">
-    OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的快速模式开关：
+    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
     {
@@ -694,7 +717,7 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
   </Accordion>
 
   <Accordion title="优先处理（service_tier）">
-    OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
+    OpenAI 的 API 通过 `service_tier` 提供优先处理能力。在 OpenClaw 中可按模型设置：
 
     ```json5
     {
@@ -711,7 +734,7 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
     支持的值：`auto`、`default`、`flex`、`priority`。
 
     <Warning>
-    `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 原样不变。
+    `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保留 `service_tier` 原样，不做处理。
     </Warning>
 
   </Accordion>
@@ -719,11 +742,11 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
   <Accordion title="服务端压缩（Responses API）">
     对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI plugin 的 Pi harness 流包装器会自动启用服务端压缩：
 
-    - 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`）
+    - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
     - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
-    - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`）
+    - 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
 
-    这适用于内置 Pi harness 路径，也适用于嵌入式运行使用的 OpenAI provider 钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
+    这适用于内置 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI 提供商钩子。原生 Codex app-server harness 则通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
 
     <Tabs>
       <Tab title="显式启用">
@@ -779,13 +802,13 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
     </Tabs>
 
     <Note>
-    `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。
+    `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。
     </Note>
 
   </Accordion>
 
   <Accordion title="严格智能体式 GPT 模式">
-    对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
+    对于 `openai/*` 上的 GPT-5 家族运行，OpenClaw 可以使用更严格的嵌入式执行契约：
 
     ```json5
     {
@@ -797,36 +820,36 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
     }
     ```
 
-    使用 `strict-agentic` 时，OpenClaw 会：
-    - 当有可用工具操作时，不再将仅计划轮次视为成功进展
-    - 通过“立即行动”的引导重试该轮次
-    - 对于实质性工作，自动启用 `update_plan`
-    - 如果模型持续规划但不执行，则显式显示阻塞状态
+    在 `strict-agentic` 模式下，OpenClaw 会：
+    - 当工具操作可用时，不再将仅有计划的轮次视为成功进展
+    - 使用“立即行动”的引导重试该轮次
+    - 对于实质性工作自动启用 `update_plan`
+    - 如果模型持续只做计划而不执行操作，则显示明确的阻塞状态
 
     <Note>
-    仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧的模型家族保持默认行为。
+    仅适用于 OpenAI 和 Codex 的 GPT-5 家族运行。其他提供商和较旧的模型家族会保留默认行为。
     </Note>
 
   </Accordion>
 
-  <Accordion title="原生 vs OpenAI-compatible 路由">
-    OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI-compatible `/v1` 代理：
+  <Accordion title="原生路由与 OpenAI 兼容路由">
+    OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理：
 
     **原生路由**（`openai/*`、Azure OpenAI）：
     - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
     - 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning
     - 默认将工具 schema 设为严格模式
-    - 仅在已验证的原生主机上附加隐藏归因头
-    - 保留 OpenAI 专用请求格式（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示）
+    - 仅在已验证的原生主机上附加隐藏归因请求头
+    - 保留 OpenAI 专用请求整形（`service_tier`、`store`、reasoning 兼容性、提示缓存提示）
 
     **代理 / 兼容路由：**
     - 使用更宽松的兼容行为
-    - 从非原生 `openai-completions` 负载中剥离 Completions `store`
-    - 为 OpenAI-compatible Completions 代理接受高级 `params.extra_body` / `params.extraBody` 透传 JSON
-    - 为 OpenAI-compatible Completions 代理（如 vLLM）接受 `params.chat_template_kwargs`
-    - 不会强制使用严格工具 schema 或原生专用头
+    - 从非原生 `openai-completions` 负载中移除 Completions `store`
+    - 接受面向 OpenAI 兼容 Completions 代理的高级 `params.extra_body` / `params.extraBody` 透传 JSON
+    - 接受面向 OpenAI 兼容 Completions 代理（如 vLLM）的 `params.chat_template_kwargs`
+    - 不强制使用严格工具 schema 或原生专用请求头
 
-    Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。
+    Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。
 
   </Accordion>
 </AccordionGroup>
@@ -844,6 +867,6 @@ OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configurat
     共享视频工具参数和提供商选择。
   </Card>
   <Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
-    认证细节和凭证复用规则。
+    认证细节和凭据复用规则。
   </Card>
 </CardGroup>