chore(i18n): refresh zh-CN translations

2026-04-28 22:46:40 +00:00 · 2026-04-28 22:46:40 +00:00 · 6a1d50b35f
commit 6a1d50b35f
parent b66940c48d
9 changed files with 815 additions and 765 deletions
--- a/docs/zh-CN/channels/pairing.md
+++ b/docs/zh-CN/channels/pairing.md
@ -1,38 +1,38 @@
 ---
 read_when:
    - 设置私信访问控制
-    - 为新的 iOS/Android 节点配对
-    - 审查 OpenClaw 安全态势
-summary: 配对概览：批准谁可以给你发私信 + 哪些节点可以加入
+    - 配对新的 iOS/Android 节点
+    - 审查 OpenClaw 的安全态势
+summary: 配对概览：批准谁可以私信你 + 哪些节点可以加入
 title: 配对
 x-i18n:
-    generated_at: "2026-04-27T12:50:24Z"
-    model: gpt-5.4
+    generated_at: "2026-04-28T22:44:28Z"
+    model: gpt-5.5
    provider: openai
-    source_hash: e529167045272b0e34978aa94f6d2ba6e46afaafb08ad098575bf68737ff0925
+    source_hash: 123d1dccfab0a2ed8a415934eb508e373c4fe85e3d07adb5eb8aa9f3cf8a3fc9
    source_path: channels/pairing.md
-    workflow: 15
+    workflow: 16
 ---

-“配对”是 OpenClaw 明确的**所有者批准**步骤。  
-它用于两个场景：
+“配对”是 OpenClaw 的显式访问批准步骤。
+它用于两个位置：

-1. **私信配对**（谁被允许与机器人对话）
-2. **节点配对**（哪些设备/节点被允许加入 Gateway 网关网络）
+1. **私信配对**（谁可以与机器人对话）
+2. **节点配对**（哪些设备/节点可以加入 Gateway 网关网络）

-安全背景： [Security](/zh-CN/gateway/security)
+安全上下文：[安全](/zh-CN/gateway/security)

-## 1）私信配对（入站聊天访问）
+## 1) 私信配对（入站聊天访问）

-当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且在你批准之前，他们的消息**不会被处理**。
+当某个渠道配置了私信策略 `pairing` 时，未知发送者会收到一个短代码，并且他们的消息在你批准前**不会被处理**。

-默认私信策略记录在： [Security](/zh-CN/gateway/security)
+默认私信策略记录在：[安全](/zh-CN/gateway/security)

 配对代码：

- 8 个字符，大写，不含易混淆字符（`0O1I`）。
- **1 小时后过期**。机器人只会在创建新请求时发送配对消息（大致为每个发送者每小时一次）。
- 默认情况下，待处理的私信配对请求每个渠道最多 **3 个**；在其中一个过期或获批之前，额外请求会被忽略。
+- 8 个字符，大写，不包含易混淆字符（`0O1I`）。
+- **1 小时后过期**。机器人只会在创建新请求时发送配对消息（大约每个发送者每小时一次）。
+- 待处理的私信配对请求默认每个渠道最多 **3 个**；额外请求会被忽略，直到其中一个过期或获批。

 ### 批准发送者

@ -41,56 +41,69 @@ openclaw pairing list telegram
 openclaw pairing approve telegram <CODE>
 ```

+如果尚未配置命令所有者，批准私信配对代码也会将
+`commands.ownerAllowFrom` 引导设置为获批发送者，例如 `telegram:123456789`。
+这会为首次设置提供一个显式所有者，用于特权命令和 exec
+批准提示。所有者存在后，后续配对批准只会授予私信
+访问权限；它们不会添加更多所有者。
+
 支持的渠道：`bluebubbles`、`discord`、`feishu`、`googlechat`、`imessage`、`irc`、`line`、`matrix`、`mattermost`、`msteams`、`nextcloud-talk`、`nostr`、`openclaw-weixin`、`signal`、`slack`、`synology-chat`、`telegram`、`twitch`、`whatsapp`、`zalo`、`zalouser`。

-### 状态存储位置
+### 状态存放位置

 存储在 `~/.openclaw/credentials/` 下：

 - 待处理请求：`<channel>-pairing.json`
 - 已批准允许列表存储：
-  - 默认账户：`<channel>-allowFrom.json`
-  - 非默认账户：`<channel>-<accountId>-allowFrom.json`
+  - 默认账号：`<channel>-allowFrom.json`
+  - 非默认账号：`<channel>-<accountId>-allowFrom.json`

-账户作用域行为：
+账号作用域行为：

- 非默认账户只会读取/写入其带作用域的允许列表文件。
- 默认账户使用按渠道划分且不带作用域的允许列表文件。
+- 非默认账号只读写其作用域化的允许列表文件。
+- 默认账号使用渠道作用域的非作用域化允许列表文件。

-请将这些文件视为敏感内容（它们控制谁能访问你的助手）。
+请将这些文件视为敏感信息（它们控制对你的助手的访问）。

 <Note>
-这个存储仅用于私信访问。群组授权是分开的。批准私信配对代码不会自动允许该发送者运行群组命令，或在群组中控制机器人。对于群组访问，请配置该渠道明确的群组允许列表（例如 `groupAllowFrom`、`groups`，或者按渠道支持的每群组或每话题覆盖项）。
+配对允许列表存储用于私信访问。群组授权是单独的。
+批准私信配对代码不会自动允许该发送者运行群组
+命令或在群组中控制机器人。首个所有者引导是 `commands.ownerAllowFrom`
+中的单独配置状态，而群聊投递仍遵循该
+渠道的群组允许列表（例如 `groupAllowFrom`、`groups`，或根据渠道而定的按群组
+或按话题覆盖项）。
 </Note>

-## 2）节点设备配对（iOS/Android/macOS/无头节点）
+## 2) 节点设备配对（iOS/Android/macOS/无头节点）

-节点作为**设备**连接到 Gateway 网关，使用 `role: node`。Gateway 网关会创建设备配对请求，必须经过批准。
+节点以 `role: node` 的**设备**身份连接到 Gateway 网关。Gateway 网关
+会创建设备配对请求，且该请求必须获批。

 ### 通过 Telegram 配对（推荐用于 iOS）

-如果你使用 `device-pair` 插件，你可以完全通过 Telegram 完成首次设备配对：
+如果使用 `device-pair` 插件，你可以完全通过 Telegram 完成首次设备配对：

-1. 在 Telegram 中，向你的机器人发送：`/pair`
-2. 机器人会回复两条消息：一条说明消息，以及另一条单独的**设置代码**消息（便于在 Telegram 中复制/粘贴）。
-3. 在你的手机上，打开 OpenClaw iOS 应用 → Settings → Gateway。
+1. 在 Telegram 中，向你的机器人发送消息：`/pair`
+2. 机器人会回复两条消息：一条说明消息，以及一条单独的**设置代码**消息（便于在 Telegram 中复制/粘贴）。
+3. 在手机上，打开 OpenClaw iOS 应用 → 设置 → Gateway 网关。
 4. 粘贴设置代码并连接。
 5. 回到 Telegram：`/pair pending`（查看请求 ID、角色和作用域），然后批准。

-设置代码是一个经过 base64 编码的 JSON 负载，包含：
+设置代码是一个 base64 编码的 JSON 载荷，包含：

 - `url`：Gateway 网关 WebSocket URL（`ws://...` 或 `wss://...`）
- `bootstrapToken`：一个短期有效、仅限单设备的引导令牌，用于初始配对握手
+- `bootstrapToken`：用于初始配对握手的短期单设备引导令牌

-该引导令牌带有内置的配对引导配置：
+该引导令牌携带内置配对引导配置文件：

- 主要移交的 `node` 令牌保持为 `scopes: []`
- 任何移交的 `operator` 令牌都仍然受限于引导允许列表：
+- 主要移交的 `node` 令牌保持 `scopes: []`
+- 任何移交的 `operator` 令牌都保持受限于引导允许列表：
  `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`
- 引导作用域检查按角色前缀区分，而不是一个扁平的统一作用域池：
-  operator 作用域条目仅满足 operator 请求，而非 operator 角色
-  仍必须在其自身角色前缀下请求作用域
- 后续令牌轮换/撤销仍同时受设备已批准角色契约和调用方会话 operator 作用域的约束
+- 引导作用域检查按角色前缀划分，而不是一个扁平作用域池：
+  operator 作用域条目只满足 operator 请求，非 operator 角色
+  仍必须在它们自己的角色前缀下请求作用域
+- 后续令牌轮换/撤销仍同时受设备已批准的
+  角色合约和调用方会话的 operator 作用域限制

 在设置代码有效期间，请像对待密码一样对待它。

@ -102,15 +115,18 @@ openclaw devices approve <requestId>
 openclaw devices reject <requestId>
 ```

-如果同一设备使用不同的认证详情重试（例如不同的角色/作用域/公钥），之前的待处理请求会被替代，并创建一个新的 `requestId`。
+如果同一设备使用不同认证详情重试（例如不同
+角色/作用域/公钥），之前待处理的请求会被取代，并创建新的
+`requestId`。

 <Note>
-已配对的设备不会在无提示的情况下获得更广泛的访问权限。如果它重新连接并请求更多作用域或更宽泛的角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。请使用 `openclaw devices list` 对比当前已批准的访问权限与新请求的访问权限，然后再决定是否批准。
+已配对的设备不会静默获得更宽泛的访问权限。如果它重新连接并请求更多作用域或更宽泛角色，OpenClaw 会保持现有批准不变，并创建一个新的待处理升级请求。在批准前，使用 `openclaw devices list` 比较当前已批准访问权限与新请求的访问权限。
 </Note>

-### 可选：受信任 CIDR 的节点自动批准
+### 可选的受信任 CIDR 节点自动批准

-默认情况下，设备配对仍需手动处理。对于受严格控制的节点网络，你可以选择启用基于明确 CIDR 或精确 IP 的首次节点自动批准：
+默认情况下，设备配对仍为手动。对于严格受控的节点网络，
+你可以通过显式 CIDR 或精确 IP 选择启用首次节点自动批准：

 ```json5
 {
@ -124,30 +140,35 @@ openclaw devices reject <requestId>
 }
 ```

-这仅适用于没有请求任何作用域的全新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍然需要手动批准。角色、作用域、元数据和公钥变更仍然需要手动批准。
+这只适用于没有请求
+作用域的新 `role: node` 配对请求。Operator、浏览器、Control UI 和 WebChat 客户端仍需要手动
+批准。角色、作用域、元数据和公钥变更仍需要手动
+批准。

 ### 节点配对状态存储

 存储在 `~/.openclaw/devices/` 下：

- `pending.json`（短期存在；待处理请求会过期）
+- `pending.json`（短期；待处理请求会过期）
 - `paired.json`（已配对设备 + 令牌）

-### 说明
+### 注意事项

 - 旧版 `node.pair.*` API（CLI：`openclaw nodes pending|approve|reject|remove|rename`）是一个
-  独立的、由 Gateway 网关拥有的配对存储。WS 节点仍然需要设备配对。
- 配对记录是已批准角色的持久事实来源。活动设备令牌仍然受限于该已批准角色集合；已批准角色之外的零散令牌条目不会创建新的访问权限。
+  单独的 Gateway 网关自有配对存储。WS 节点仍需要设备配对。
+- 配对记录是已批准角色的持久事实来源。活动
+  设备令牌仍受限于该已批准角色集；已批准角色之外的零散令牌条目
+  不会创建新的访问权限。

 ## 相关文档

- 安全模型 + 提示注入： [Security](/zh-CN/gateway/security)
- 安全更新（运行 doctor）： [Updating](/zh-CN/install/updating)
+- 安全模型 + 提示注入：[安全](/zh-CN/gateway/security)
+- 安全更新（运行 Doctor）：[更新](/zh-CN/install/updating)
 - 渠道配置：
-  - Telegram： [Telegram](/zh-CN/channels/telegram)
-  - WhatsApp： [WhatsApp](/zh-CN/channels/whatsapp)
-  - Signal： [Signal](/zh-CN/channels/signal)
-  - BlueBubbles（iMessage）： [BlueBubbles](/zh-CN/channels/bluebubbles)
-  - iMessage（旧版）： [iMessage](/zh-CN/channels/imessage)
-  - Discord： [Discord](/zh-CN/channels/discord)
-  - Slack： [Slack](/zh-CN/channels/slack)
+  - Telegram：[Telegram](/zh-CN/channels/telegram)
+  - WhatsApp：[WhatsApp](/zh-CN/channels/whatsapp)
+  - Signal：[Signal](/zh-CN/channels/signal)
+  - BlueBubbles（iMessage）：[BlueBubbles](/zh-CN/channels/bluebubbles)
+  - iMessage（旧版）：[iMessage](/zh-CN/channels/imessage)
+  - Discord：[Discord](/zh-CN/channels/discord)
+  - Slack：[Slack](/zh-CN/channels/slack)
--- a/docs/zh-CN/channels/telegram.md
+++ b/docs/zh-CN/channels/telegram.md
@ -1,25 +1,25 @@
 ---
 read_when:
-    - 处理 Telegram 功能或网络钩子
+    - 开发 Telegram 功能或网络钩子
 summary: Telegram 机器人支持状态、能力和配置
 title: Telegram
 x-i18n:
-    generated_at: "2026-04-28T20:08:19Z"
+    generated_at: "2026-04-28T22:44:25Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 663fd2eecc7f2ff02622f5fde1a6ae3c97427f7aeda26f89a230529f3284df8b
+    source_hash: 2e334360bce47f1b90d1fad1fe08a13b1b976ec86e06c87647dc87f71852fc8a
    source_path: channels/telegram.md
    workflow: 16
 ---

-可用于生产环境的机器人私信和群组，基于 grammY。长轮询是默认模式；webhook 模式可选。
+可用于基于 grammY 的生产级机器人私信和群组。长轮询是默认模式；webhook 模式可选。

 <CardGroup cols={3}>
  <Card title="配对" icon="link" href="/zh-CN/channels/pairing">
    Telegram 的默认私信策略是配对。
  </Card>
  <Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
-    跨渠道诊断和修复手册。
+    跨渠道诊断和修复操作手册。
  </Card>
  <Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
    完整的渠道配置模式和示例。
@ -30,7 +30,7 @@ x-i18n:

 <Steps>
  <Step title="在 BotFather 中创建机器人令牌">
-    打开 Telegram 并与 **@BotFather** 聊天（确认用户名完全是 `@BotFather`）。
+    打开 Telegram 并与 **@BotFather** 聊天（确认账号名正好是 `@BotFather`）。

    运行 `/newbot`，按提示操作，并保存令牌。

@ -51,8 +51,8 @@ x-i18n:
 }
 ```

-    环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。
-    Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。
+    环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
+    Telegram **不**使用 `openclaw channels login telegram`；在配置/环境变量中配置令牌，然后启动 Gateway 网关。

  </Step>

@ -64,24 +64,24 @@ openclaw pairing list telegram
 openclaw pairing approve telegram <CODE>
 ```

-    配对码将在 1 小时后过期。
+    配对码会在 1 小时后过期。

  </Step>

  <Step title="将机器人添加到群组">
-    将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，使其与你的访问模型匹配。
+    将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配你的访问模型。
  </Step>
 </Steps>

 <Note>
-令牌解析顺序支持账号感知。实际使用中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。
+令牌解析顺序会感知账户。实际使用中，配置值优先于环境变量回退，并且 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。
 </Note>

-## Telegram 侧设置
+## Telegram 端设置

 <AccordionGroup>
  <Accordion title="隐私模式和群组可见性">
-    Telegram 机器人默认启用**隐私模式**，这会限制它们能接收的群组消息。
+    Telegram 机器人默认使用**隐私模式**，这会限制它们能接收的群组消息。

    如果机器人必须看到所有群组消息，可以：

@ -101,7 +101,7 @@ openclaw pairing approve telegram <CODE>

  <Accordion title="有用的 BotFather 开关">

-    - `/setjoingroups` 用于允许/拒绝添加到群组
+    - `/setjoingroups` 用于允许/拒绝加入群组
    - `/setprivacy` 用于群组可见性行为

  </Accordion>
@ -118,23 +118,24 @@ openclaw pairing approve telegram <CODE>
    - `open`（要求 `allowFrom` 包含 `"*"`）
    - `disabled`

-    `dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能向机器人发出命令。仅在有意公开且工具严格受限的机器人中使用；单所有者机器人应使用包含数字用户 ID 的 `allowlist`。
+    `dmPolicy: "open"` 配合 `allowFrom: ["*"]` 会让任何发现或猜到机器人用户名的 Telegram 账户都能命令该机器人。仅对有严格受限工具的有意公开机器人使用它；单所有者机器人应使用包含数字用户 ID 的 `allowlist`。

    `channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
-    `dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。
-    设置流程只会要求数字用户 ID。
-    如果你已升级且配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
-    如果你之前依赖配对存储的 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚未显式配置 ID 时）。
+    `dmPolicy: "allowlist"` 配合空的 `allowFrom` 会阻止所有私信，并会被配置验证拒绝。
+    设置过程只会请求数字用户 ID。
+    如果你升级后配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
+    如果你之前依赖配对存储的允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 还没有显式 ID 时）。

    对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并显式设置数字 `allowFrom` ID，以便在配置中保持持久的访问策略（而不是依赖之前的配对批准）。

-    常见误解：私信配对批准并不表示“该发送者在所有地方都已授权”。
-    配对只授予私信访问权限。群组发送者授权仍来自显式配置的 allowlist。
-    如果你希望“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。
+    常见误解：私信配对批准并不意味着“这个发送者在所有地方都已授权”。
+    配对授予私信访问权限。如果还没有命令所有者，第一次批准的配对还会设置 `commands.ownerAllowFrom`，以便仅所有者命令和执行批准有一个显式操作账户。
+    群组发送者授权仍来自显式配置允许列表。
+    如果你想要“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。

    ### 查找你的 Telegram 用户 ID

-    更安全（不使用第三方机器人）：
+    更安全（无第三方机器人）：

    1. 给你的机器人发送私信。
    2. 运行 `openclaw logs --follow`。
@ -146,18 +147,18 @@ openclaw pairing approve telegram <CODE>
 curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ```

-    第三方方法（隐私较低）：`@userinfobot` 或 `@getidsbot`。
+    第三方方法（隐私性较低）：`@userinfobot` 或 `@getidsbot`。

  </Tab>

-  <Tab title="群组策略和 allowlist">
-    两项控制会共同生效：
+  <Tab title="群组策略和允许列表">
+    两个控制项会一起生效：

    1. **允许哪些群组**（`channels.telegram.groups`）
       - 没有 `groups` 配置：
-         - 搭配 `groupPolicy: "open"`：任何群组都能通过群组 ID 检查
-         - 搭配 `groupPolicy: "allowlist"`（默认）：在添加 `groups` 条目（或 `"*"`）之前，群组会被阻止
-       - 已配置 `groups`：作为 allowlist 生效（显式 ID 或 `"*"`）
+         - 配合 `groupPolicy: "open"`：任何群组都可以通过群组 ID 检查
+         - 配合 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
+       - 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`）

    2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
       - `open`
@ -166,15 +167,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
    `groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
-    不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
-    非数字条目会被发送者授权忽略。
-    安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。
-    配对仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
+    不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 属于 `channels.telegram.groups`。
+    非数字条目会在发送者授权中被忽略。
+    安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
+    配对仅适用于私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
    如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
-    单所有者机器人的实用模式：将你的用户 ID 设置到 `channels.telegram.allowFrom`，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
-    运行时说明：如果完全缺失 `channels.telegram`，运行时默认采用失败关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
+    单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
+    运行时说明：如果完全缺少 `channels.telegram`，运行时默认会故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。

-    示例：允许某个特定群组中的任何成员：
+    示例：允许一个特定群组中的任何成员：

 ```json5
 {
@ -191,7 +192,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    示例：仅允许某个特定群组中的特定用户：
+    示例：仅允许一个特定群组内的特定用户：

 ```json5
 {
@ -209,11 +210,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ```

    <Warning>
-      常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。
+      常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。

-      - 将 `-1001234567890` 这样的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
-      - 当你想限制允许群组内哪些人可以触发机器人时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
-      - 仅当你希望允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
+      - 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
+      - 当你想限制已允许群组内哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
+      - 仅当你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。

    </Warning>

@ -234,9 +235,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `/activation always`
    - `/activation mention`

-    这些只更新会话状态。使用配置来实现持久化。
+    这些只会更新会话状态。使用配置来持久化。

-    持久化配置示例：
+    持久配置示例：

 ```json5
 {
@ -262,19 +263,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 ## 运行时行为

 - Telegram 由 Gateway 网关进程拥有。
- 路由是确定性的：Telegram 入站回复会回到 Telegram（模型不会选择渠道）。
- 入站消息会规范化为共享渠道信封，包含回复元数据和媒体占位符。
+- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。
+- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。
 - 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>` 以保持话题隔离。
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用支持线程感知的会话键进行路由，并为回复保留线程 ID。
- 长轮询使用 grammY runner，并按聊天/按线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
- 长轮询在每个 Gateway 网关进程内受保护，因此同一时间只有一个活动 poller 能使用机器人令牌。如果你仍看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部 poller 正在使用同一令牌。
- 默认情况下，长轮询 watchdog 会在 120 秒内没有完成的 `getUpdates` 存活性后触发重启。只有当你的部署在长时间运行的工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
+- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用感知线程的会话键路由它们，并保留线程 ID 用于回复。
+- 长轮询使用 grammY runner，并按聊天/线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
+- 每个 Gateway 网关进程内部都会保护长轮询，因此同一时间只有一个活跃轮询器可以使用一个机器人令牌。如果你仍看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个令牌。
+- 默认情况下，如果 120 秒内没有完成 `getUpdates` 活性检查，长轮询看门狗会触发重启。仅当你的部署在长时间运行的工作期间仍出现误报轮询卡顿重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。
 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。

 ## 功能参考

 <AccordionGroup>
-  <Accordion title="实时流式预览（消息编辑）">
+  <Accordion title="实时流预览（消息编辑）">
    OpenClaw 可以实时流式传输部分回复：

    - 直接聊天：预览消息 + `editMessageText`
@ -283,11 +284,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    要求：

    - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
-    - 在 Telegram 上，`progress` 映射为 `partial`（与跨渠道命名兼容）
+    - 在 Telegram 上，`progress` 映射到 `partial`（兼容跨渠道命名）
    - `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输启用时为 `true`）
-    - 会检测旧版 `channels.telegram.streamMode` 和布尔 `streaming` 值；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode`
+    - 会检测旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值；运行 `openclaw doctor --fix` 将它们迁移到 `channels.telegram.streaming.mode`

-    工具进度预览更新是在工具运行时显示的简短 “Working...” 行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持启用这些更新，以匹配 `v2026.4.22` 及更高版本中已发布的 OpenClaw 行为。要保留用于答案文本的已编辑预览，但隐藏工具进度行，请设置：
+    工具进度预览更新是工具运行时显示的简短“Working...”行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些内容启用，以匹配 `v2026.4.22` 及之后版本发布的 OpenClaw 行为。若要保留答案文本的已编辑预览但隐藏工具进度行，请设置：

    ```json
    {
@ -304,22 +305,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    }
    ```

-    仅当你希望只交付最终结果时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度杂讯会被抑制，而不是作为独立的 “Working...” 消息发送。批准提示、媒体载荷和错误仍会通过正常的最终交付路由。仅当你只想保留答案预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。
+    仅当你想要只交付最终消息时，才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立“Working...”消息发送。批准提示、媒体载荷和错误仍会通过正常的最终交付路由。仅当你只想保留答案预览编辑，同时隐藏工具进度状态行时，才使用 `streaming.preview.toolProgress: false`。

    对于纯文本回复：

    - 较短的私信/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原处执行最终编辑
-    - 约一分钟以上的旧预览：OpenClaw 会将完整回复作为新的最终消息发送，然后清理预览，使 Telegram 的可见时间戳反映完成时间，而不是预览创建时间
+    - 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间

-    对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。
+    对于复杂回复（例如媒体载荷），OpenClaw 会回退到普通的最终投递，然后清理预览消息。

-    预览流式传输与分块流式传输是分开的。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
+    预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。

    如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。

    仅限 Telegram 的推理流：

-    - `/reasoning stream` 会在生成过程中把推理发送到实时预览
+    - `/reasoning stream` 在生成过程中将推理发送到实时预览
    - 最终回答发送时不包含推理文本

  </Accordion>
@ -340,9 +341,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    原生命令默认值：

-    - `commands.native: "auto"` 会为 Telegram 启用原生命令
+    - `commands.native: "auto"` 为 Telegram 启用原生命令

-    添加自定义命令菜单条目：
+    添加自定义命令菜单项：

 ```json5
 {
@ -359,23 +360,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    规则：

-    - 名称会被规范化（去掉开头的 `/`，转换为小写）
+    - 名称会被规范化（去掉前导 `/`，转为小写）
    - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
    - 自定义命令不能覆盖原生命令
-    - 冲突或重复项会被跳过并记录日志
+    - 冲突项/重复项会被跳过并记录日志

-    备注：
+    注意：

-    - 自定义命令只是菜单条目；它们不会自动实现行为
-    - 插件/Skill 命令即使未显示在 Telegram 菜单中，输入时仍可能工作
+    - 自定义命令只是菜单项；它们不会自动实现行为
+    - 插件/skill 命令即使没有显示在 Telegram 菜单中，在输入时仍然可以工作

-    如果禁用原生命令，内置命令会被移除。自定义/插件命令在已配置时仍可能注册。
+    如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后可能仍会注册。

    常见设置失败：

-    - `setMyCommands failed` 带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然超出限制；请减少插件/Skill/自定义命令，或禁用 `channels.telegram.commands.native`。
-    - 当直接使用 Bot API curl 命令可工作，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 以 `404: Not Found` 失败时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，`openclaw doctor --fix` 会移除意外追加的 `/bot<TOKEN>`。
-    - `getMe returned 401` 表示 Telegram 拒绝了已配置的 bot token。请使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
+    - `setMyCommands failed` 带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/skill/自定义命令，或禁用 `channels.telegram.commands.native`。
+    - 当直接的 Bot API curl 命令可以工作，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 因 `404: Not Found` 失败时，可能表示 `channels.telegram.apiRoot` 被设置为完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，并且 `openclaw doctor --fix` 会移除意外的尾部 `/bot<TOKEN>`。
+    - `getMe returned 401` 表示 Telegram 拒绝了配置的机器人令牌。使用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此不会被报告为 webhook 清理失败。
    - `setMyCommands failed` 带有网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。

    ### 设备配对命令（`device-pair` 插件）
@ -387,12 +388,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    3. `/pair pending` 列出待处理请求（包括角色/作用域）
    4. 批准请求：
       - `/pair approve <requestId>` 用于显式批准
-       - `/pair approve` 用于只有一个待处理请求时
+       - 只有一个待处理请求时使用 `/pair approve`
       - `/pair approve latest` 用于最近的请求

-    设置代码携带一个短生命周期的引导 token。内置引导交接会把主节点 token 保持在 `scopes: []`；任何交接出的 operator token 都会限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。引导作用域检查带有角色前缀，因此该 operator 允许列表只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。
+    设置代码携带一个短生命周期的引导令牌。内置引导交接会将主节点令牌保持在 `scopes: []`；任何被交接的操作员令牌都限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 内。引导作用域检查带有角色前缀，因此该操作员允许列表只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。

-    如果设备使用已变更的认证详情重试（例如角色/作用域/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
+    如果设备使用已更改的认证详情（例如角色/作用域/公钥）重试，先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。

    更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。

@ -413,7 +414,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    按账号覆盖：
+    单账号覆盖：

 ```json5
 {
@ -439,7 +440,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `all`
    - `allowlist`（默认）

-    旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。
+    旧版 `capabilities: ["inlineButtons"]` 映射到 `inlineButtons: "all"`。

    消息操作示例：

@ -473,7 +474,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `editMessage`（`chatId`、`messageId`、`content`）
    - `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）

-    渠道消息操作会公开符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
+    渠道消息操作公开符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。

    门控控制：

@ -482,8 +483,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `channels.telegram.actions.reactions`
    - `channels.telegram.actions.sticker`（默认：禁用）

-    注意：`edit` 和 `topic-create` 目前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
-    运行时发送使用活动的配置/密钥快照（启动/重新加载），因此操作路径不会在每次发送时执行临时 SecretRef 重新解析。
+    注意：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
+    运行时发送使用活动的配置/密钥快照（启动/重新加载），因此操作路径不会在每次发送时执行临时的 SecretRef 重新解析。

    反应移除语义：[/tools/reactions](/zh-CN/tools/reactions)

@ -493,7 +494,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    Telegram 支持在生成输出中使用显式回复线程标签：

    - `[[reply_to_current]]` 回复触发消息
-    - `[[reply_to:<id>]]` 回复特定的 Telegram 消息 ID
+    - `[[reply_to:<id>]]` 回复特定 Telegram 消息 ID

    `channels.telegram.replyToMode` 控制处理方式：

@ -501,7 +502,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `first`
    - `all`

-    启用回复线程后，如果原始 Telegram 文本或说明文字可用，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 码元，因此更长的消息会从开头引用，并在 Telegram 拒绝引用时回退为普通回复。
+    启用回复线程，并且原始 Telegram 文本或标题可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 代码单元，因此更长的消息会从开头引用；如果 Telegram 拒绝该引用，则回退到普通回复。

    注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。

@ -510,20 +511,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
  <Accordion title="论坛话题和线程行为">
    论坛超级群组：

-    - 话题会话键会追加 `:topic:<threadId>`
-    - 回复和正在输入状态会发送到话题线程
+    - 话题会话键追加 `:topic:<threadId>`
+    - 回复和正在输入目标指向话题线程
    - 话题配置路径：
      `channels.telegram.groups.<chatId>.topics.<threadId>`

-    常规话题（`threadId=1`）的特殊情况：
+    常规话题（`threadId=1`）特殊情况：

-    - 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
+    - 消息发送会省略 `message_thread_id`（Telegram 拒绝 `sendMessage(...thread_id=1)`）
    - 正在输入操作仍会包含 `message_thread_id`

-    话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
-    `agentId` 仅适用于话题，不会从群组默认值继承。
+    话题继承：话题条目继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
+    `agentId` 仅限话题，不会从群组默认值继承。

-    **按话题路由智能体**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这会为每个话题提供自己隔离的工作区、记忆和会话。示例：
+    **按话题路由智能体**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这使每个话题拥有自己隔离的工作区、记忆和会话。示例：

    ```json5
    {
@ -543,24 +544,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    }
    ```

-    每个话题随后都会拥有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
+    然后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`

-    **持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定来固定 ACP harness 会话（`bindings[]`，带有 `type: "acp"` 和 `match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的话题限定 ID）。目前作用域限定为群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
+    **持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]`，其中包含 `type: "acp"` 和 `match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的话题限定 id）固定 ACP harness 会话。当前作用域限定在群组/超级群组中的论坛话题。请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。

-    **从聊天生成线程绑定 ACP**：`/acp spawn <agent> --thread here|auto` 会把当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内固定生成确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
+    **从聊天中生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 将当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内固定生成确认。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。

-    模板上下文会公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保留私信路由，但使用线程感知的会话键。
+    模板上下文公开 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天保留私信路由，但使用线程感知的会话键。

  </Accordion>

  <Accordion title="音频、视频和贴纸">
    ### 音频消息

-    Telegram 区分语音便条和音频文件。
+    Telegram 区分语音留言和音频文件。

    - 默认：音频文件行为
-    - 在智能体回复中使用标签 `[[audio_as_voice]]` 可强制以语音便条发送
-    - 入站语音便条转录会在智能体上下文中被框定为机器生成的、不受信任的文本；提及检测仍使用原始转录，因此受提及门控的语音消息会继续工作。
+    - 在智能体回复中使用标签 `[[audio_as_voice]]` 强制按语音留言发送
+    - 入站语音留言转录会在智能体上下文中被框定为机器生成的、不可信文本；提及检测仍使用原始转录，因此由提及门控的语音消息会继续工作。

    消息操作示例：

@ -576,7 +577,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    ### 视频消息

-    Telegram 区分视频文件和视频便条。
+    Telegram 区分视频文件和视频留言。

    消息操作示例：

@ -590,7 +591,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 }
 ```

-    视频便条不支持说明文字；提供的消息文本会单独发送。
+    视频留言不支持标题；提供的消息文本会单独发送。

    ### 贴纸

@ -612,7 +613,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"

    - `~/.openclaw/telegram/sticker-cache.json`

-    贴纸会被描述一次（如果可行），并被缓存以减少重复的视觉调用。
+    贴纸会被描述一次（如果可能）并缓存，以减少重复视觉调用。

    启用贴纸操作：

@ -653,7 +654,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
  </Accordion>

  <Accordion title="反应通知">
-    Telegram 反应会作为 `message_reaction` 更新到达（与消息载荷分开）。
+    Telegram 反应作为 `message_reaction` 更新到达（与消息载荷分离）。

    启用后，OpenClaw 会将如下系统事件加入队列：

@ -664,32 +665,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    - `channels.telegram.reactionNotifications`：`off | own | all`（默认：`own`）
    - `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认：`minimal`）

-    备注：
+    注意：

-    - `own` 表示仅用户对机器人发送消息的回应（通过已发送消息缓存尽力而为）。
-    - 回应事件仍遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
-    - Telegram 不会在回应更新中提供话题 ID。
+    - `own` 表示仅限用户对机器人已发送消息的反应（通过已发送消息缓存尽力而为）。
+    - 反应事件仍会遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
+    - Telegram 不会在反应更新中提供话题 ID。
      - 非论坛群组路由到群聊会话
-      - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题
+      - 论坛群组路由到群组通用话题会话（`:topic:1`），而不是精确的原始话题

-    用于轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
+    轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。

  </Accordion>

-  <Accordion title="确认回应">
-    `ackReaction` 会在 OpenClaw 处理传入消息时发送一个确认表情符号。
+  <Accordion title="确认反应">
+    `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。

    解析顺序：

    - `channels.telegram.accounts.<accountId>.ackReaction`
    - `channels.telegram.ackReaction`
    - `messages.ackReaction`
-    - 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"）
+    - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 “👀”）

-    注意：
+    注意事项：

-    - Telegram 期望使用 unicode 表情符号（例如 "👀"）。
-    - 使用 `""` 可为某个渠道或账号禁用该回应。
+    - Telegram 需要 unicode emoji（例如 “👀”）。
+    - 使用 `""` 可禁用某个渠道或账号的反应。

  </Accordion>

@ -716,28 +717,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
  </Accordion>

  <Accordion title="长轮询与 webhook">
-    默认使用长轮询。对于 webhook 模式，设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选设置 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。
+    默认使用长轮询。对于 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选设置 `webhookPath`、`webhookHost`、`webhookPort`（默认值为 `/telegram-webhook`、`127.0.0.1`、`8787`）。

    本地监听器绑定到 `127.0.0.1:8787`。对于公网入口，可以在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。

-    webhook 模式会先验证请求防护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。
-    随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理更新，因此较慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
+    Webhook 模式会先校验请求防护、Telegram 密钥令牌和 JSON 正文，然后再向 Telegram 返回 `200`。
+    随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。

  </Accordion>

  <Accordion title="限制、重试和 CLI 目标">
    - `channels.telegram.textChunkLimit` 默认值为 4000。
-    - `channels.telegram.chunkMode="newline"` 会优先按段落边界（空行）分割，然后再按长度分割。
-    - `channels.telegram.mediaMaxMb`（默认 100）限制传入和传出的 Telegram 媒体大小。
-    - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。
-    - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在轮询停滞重启出现误报时，才在 `30000` 到 `600000` 之间调整。
+    - `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。
+    - `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。
+    - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。
+    - `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在误报轮询停滞重启时，将其调到 `30000` 到 `600000` 之间。
    - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
-    - 回复/引用/转发的补充上下文目前会按收到的内容传递。
-    - Telegram 允许列表主要控制谁能触发智能体，并不是完整的补充上下文脱敏边界。
+    - 回复/引用/转发的补充上下文目前会按接收内容传递。
+    - Telegram 允许列表主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
    - 私信历史控制：
      - `channels.telegram.dmHistoryLimit`
      - `channels.telegram.dms["<user_id>"].historyLimit`
-    - `channels.telegram.retry` 配置适用于 Telegram 发送辅助逻辑（CLI/工具/操作），用于可恢复的出站 API 错误。
+    - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/操作），用于可恢复的出站 API 错误。

    CLI 发送目标可以是数字聊天 ID 或用户名：

@ -765,44 +766,44 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \

    Telegram 发送还支持：

-    - 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 创建内联键盘
+    - 当 `channels.telegram.capabilities.inlineButtons` 允许时，将 `--presentation` 与 `buttons` 块一起用于内联键盘
    - 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递
    - 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传

-    操作限制：
+    操作门控：

    - `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票
-    - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送能力
+    - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送功能

  </Accordion>

-  <Accordion title="Telegram 中的执行审批">
-    Telegram 支持在审批者私信中进行执行审批，并且可以选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。
+  <Accordion title="Telegram 中的 exec 审批">
+    Telegram 支持在审批者私信中进行 exec 审批，也可以选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。

    配置路径：

    - `channels.telegram.execApprovals.enabled`（当至少一个审批者可解析时自动启用）
-    - `channels.telegram.execApprovals.approvers`（回退到来自 `allowFrom` / `defaultTo` 的数字所有者 ID）
+    - `channels.telegram.execApprovals.approvers`（回退到来自 `commands.ownerAllowFrom`、`allowFrom` 或 `defaultTo` 的数字所有者 ID）
    - `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both`
    - `agentFilter`、`sessionFilter`

-    渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。执行审批默认在 30 分钟后过期。
+    渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认在 30 分钟后过期。

-    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标界面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 通过插件审批解析；其他 ID 会先通过执行审批解析。
+    内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。

-    参见[执行审批](/zh-CN/tools/exec-approvals)。
+    请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。

  </Accordion>
 </AccordionGroup>

 ## 错误回复控制

-当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以将其抑制。两个配置键控制此行为：
+当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制错误回复。两个配置键控制此行为：

-| 键                                  | 值                | 默认值  | 描述                                                                                     |
-| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `channels.telegram.errorPolicy`     | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。 |
-| `channels.telegram.errorCooldownMs` | 数字（毫秒）      | `60000` | 同一聊天两次错误回复之间的最短时间。防止故障期间出现错误刷屏。        |
+| 键                                  | 取值              | 默认值  | 描述                                                                                             |
+| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `channels.telegram.errorPolicy`     | `reply`, `silent` | `reply` | `reply` 会向聊天发送友好的错误消息。`silent` 会完全抑制错误回复。                                |
+| `channels.telegram.errorCooldownMs` | 数字（ms）        | `60000` | 向同一聊天发送错误回复的最小间隔。防止故障期间出现错误刷屏。                                     |

 支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。

@ -825,13 +826,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
 ## 故障排除

 <AccordionGroup>
-  <Accordion title="机器人不会响应群组中未提及它的消息">
+  <Accordion title="机器人不响应非提及群组消息">

    - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。
      - BotFather：`/setprivacy` -> Disable
-      - 然后将机器人从群组移除并重新添加
-    - 当配置期望接收未提及机器人的群组消息时，`openclaw channels status` 会发出警告。
-    - `openclaw channels status --probe` 可以检查明确的数字群组 ID；通配符 `"*"` 无法进行成员资格探测。
+      - 然后将机器人从群组中移除并重新添加
+    - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。
+    - `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员资格探测。
    - 快速会话测试：`/activation always`。

  </Accordion>
@ -840,7 +841,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \

    - 当 `channels.telegram.groups` 存在时，群组必须被列出（或包含 `"*"`）
    - 验证机器人在群组中的成员资格
-    - 查看日志：使用 `openclaw logs --follow` 查找跳过原因
+    - 查看日志：使用 `openclaw logs --follow` 查看跳过原因

  </Accordion>

@ -848,8 +849,8 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \

    - 授权你的发送者身份（配对和/或数字 `allowFrom`）
    - 即使群组策略为 `open`，命令授权仍然适用
-    - `setMyCommands failed` 并伴随 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单
-    - `setMyCommands failed` 并伴随网络/获取错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
+    - `setMyCommands failed` 并伴随 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/Skill/自定义命令，或禁用原生命令菜单
+    - `setMyCommands failed` 并伴随网络/fetch 错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题

  </Accordion>

@ -857,18 +858,18 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \

    - `getMe returned 401` 是配置的机器人令牌发生 Telegram 身份验证失败。
    - 在 BotFather 中重新复制或重新生成机器人令牌，然后为默认账号更新 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
-    - 启动期间出现 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“webhook 不存在”只会把同一个错误令牌失败推迟到后续 API 调用。
+    - 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“没有 webhook 存在”只会把同一个错误令牌失败推迟到后续 API 调用。

  </Accordion>

  <Accordion title="轮询或网络不稳定">

-    - 如果 AbortSignal 类型不匹配，Node 22+ 和自定义 fetch/代理可能触发立即中止行为。
-    - 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出口可能导致间歇性 Telegram API 失败。
-    - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复的网络错误重试。
-    - 如果日志包含 `Polling stall detected`，OpenClaw 默认会在 120 秒内没有完成的长轮询活性信号后重启轮询并重建 Telegram 传输。
-    - 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍然报告误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出口问题。
-    - 在直接出口/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
+    - Node 22+ 加自定义 fetch/proxy 时，如果 AbortSignal 类型不匹配，可能触发立即中止行为。
+    - 一些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站可能导致间歇性 Telegram API 失败。
+    - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些错误作为可恢复的网络错误重试。
+    - 如果日志包含 `Polling stall detected`，OpenClaw 默认会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。
+    - 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍报告误报轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
+    - 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：

 ```yaml
 channels:
@ -877,7 +878,7 @@ channels:
 ```

    - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
-    - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制选择地址族：
+    - 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作更好，请强制选择地址族：

 ```yaml
 channels:
@ -886,7 +887,7 @@ channels:
      autoSelectFamily: false
 ```

-    - 默认情况下，RFC 2544 基准范围答案（`198.18.0.0/15`）已经允许用于 Telegram 媒体下载。如果可信的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
+    - 默认已允许用于 Telegram 媒体下载的 RFC 2544 基准测试范围答案（`198.18.0.0/15`）。如果可信的假 IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：

 ```yaml
 channels:
@ -895,21 +896,22 @@ channels:
      dangerouslyAllowPrivateNetwork: true
 ```

-    - 同一个选择启用也可按账号设置：
+    - 同一个显式启用项也可按账号配置在
      `channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`。
-    - 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 基准范围。
+    - 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准测试范围。

    <Warning>
      `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram
-      媒体 SSRF 保护。仅在可信且由操作员控制的代理环境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且它们会合成 RFC 2544 基准
-      范围之外的私有或特殊用途答案。正常公网 Telegram 访问应保持关闭。
+      媒体 SSRF 保护。仅在受信任、由操作员控制的代理环境中使用它，
+      例如 Clash、Mihomo 或 Surge 假 IP 路由，并且它们会合成 RFC 2544
+      基准测试范围之外的私有或特殊用途答案。对于普通公网 Telegram 访问，请保持关闭。
    </Warning>

    - 环境覆盖（临时）：
      - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
      - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
      - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
-    - 验证 DNS 应答：
+    - 验证 DNS 响应：

 ```bash
 dig +short api.telegram.org A
@ -923,7 +925,7 @@ dig +short api.telegram.org AAAA

 ## 配置参考

-主要参考：[Telegram 配置参考](/zh-CN/gateway/config-channels#telegram)。
+主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。

 <Accordion title="高信号 Telegram 字段">

@ -931,11 +933,11 @@ dig +short api.telegram.org AAAA
 - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`）
 - 执行批准：`execApprovals`、`accounts.*.execApprovals`
 - 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
- 会话串/回复：`replyToMode`
+- 线程/回复：`replyToMode`
 - 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
- 格式/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
+- 格式化/交付：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
 - 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
- 自定义 API 根：`apiRoot`（仅 Bot API 根；不要包含 `/bot<TOKEN>`）
+- 自定义 API 根地址：`apiRoot`（仅限 Bot API 根地址；不要包含 `/bot<TOKEN>`）
 - webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
 - 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
 - 表情回应：`reactionNotifications`、`reactionLevel`
@ -945,14 +947,14 @@ dig +short api.telegram.org AAAA
 </Accordion>

 <Note>
-多账号优先级：配置两个或更多账号 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），以显式指定默认路由。否则，OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。
+多账号优先级：配置两个或更多账号 ID 时，设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以明确默认路由。否则 OpenClaw 会回退到第一个规范化账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 值。
 </Note>

 ## 相关内容

 <CardGroup cols={2}>
  <Card title="配对" icon="link" href="/zh-CN/channels/pairing">
-    将 Telegram 用户配对到 Gateway 网关。
+    将 Telegram 用户与 Gateway 网关配对。
  </Card>
  <Card title="群组" icon="users" href="/zh-CN/channels/groups">
    群组和话题允许列表行为。
--- a/docs/zh-CN/cli/doctor.md
+++ b/docs/zh-CN/cli/doctor.md
@ -1,23 +1,23 @@
 ---
 read_when:
-    - 你遇到连接/身份验证问题，并希望获得引导式修复
-    - 你已更新并想做一次基本检查
-summary: 用于 `openclaw doctor` 的 CLI 参考（健康检查 + 引导式修复）
+    - 你遇到了连接/身份验证问题，并想要引导式修复
+    - 你已更新，并想做一次完整性检查
+summary: CLI 参考：`openclaw doctor`（健康检查 + 引导式修复）
 title: Doctor
 x-i18n:
-    generated_at: "2026-04-28T11:47:52Z"
+    generated_at: "2026-04-28T22:44:34Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 00110787b9320f84aa3b57ea8b85120d412a97779fbf1e3d8f11f78c87d37676
+    source_hash: 9985c84d23861dd9468a4659ee00519573fe6d540c436548da0a68067dbabc4c
    source_path: cli/doctor.md
    workflow: 16
 ---

 # `openclaw doctor`

-针对 Gateway 网关和渠道的健康检查 + 快速修复。
+Gateway 网关和渠道的健康检查 + 快速修复。

-相关：
+相关内容：

 - 故障排除：[故障排除](/zh-CN/gateway/troubleshooting)
 - 安全审计：[安全](/zh-CN/gateway/security)
@ -36,36 +36,37 @@ openclaw doctor --generate-gateway-token

 - `--no-workspace-suggestions`：禁用工作区记忆/搜索建议
 - `--yes`：不提示，接受默认值
- `--repair`：不提示，应用建议的修复
+- `--repair`：不提示，应用推荐的修复
 - `--fix`：`--repair` 的别名
- `--force`：应用激进修复，包括必要时覆盖自定义服务配置
+- `--force`：应用强力修复，包括在需要时覆盖自定义服务配置
 - `--non-interactive`：无提示运行；仅执行安全迁移
 - `--generate-gateway-token`：生成并配置 Gateway 网关令牌
- `--deep`：扫描系统服务，查找额外的 Gateway 网关安装
+- `--deep`：扫描系统服务中的额外 Gateway 网关安装

-注意：
+注意事项：

- 交互式提示（如钥匙串/OAuth 修复）只会在 stdin 是 TTY 且**未**设置 `--non-interactive` 时运行。无头运行（cron、Telegram、无终端）会跳过提示。
- 性能：非交互式 `doctor` 运行会跳过预先加载插件，因此无头健康检查保持快速。交互式会话仍会在检查需要插件贡献时完整加载插件。
- `--fix`（`--repair` 的别名）会将备份写入 `~/.openclaw/openclaw.json.bak`，并删除未知配置键，同时列出每一项删除。
- 状态完整性检查现在会检测会话目录中的孤立转录文件。将它们归档为 `.deleted.<timestamp>` 需要交互式确认；`--fix`、`--yes` 和无头运行会将它们保留在原处。
- Doctor 还会扫描 `~/.openclaw/cron/jobs.json`（或 `cron.store`），查找旧版 cron 任务形态，并可在调度器运行时必须自动规范化它们之前就地重写。
- Doctor 会修复缺失的内置插件运行时依赖，而不会写入打包的全局安装。对于 root 拥有的 npm 安装或加固的 systemd 单元，将 `OPENCLAW_PLUGIN_STAGE_DIR` 设置为可写目录，例如 `/var/lib/openclaw/plugin-runtime-deps`；它也可以是路径列表，例如 `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`，其中较早的根目录是只读查找层，最后一个根目录是修复目标。
- 当插件发现健康时，Doctor 会通过从 `plugins.allow`/`plugins.entries` 中移除缺失的插件 ID，以及匹配的悬空渠道配置、心跳目标和渠道模型覆盖，修复过期的插件配置。
- Doctor 会通过禁用受影响的 `plugins.entries.<id>` 条目并移除其无效的 `config` 载荷，隔离无效插件配置。Gateway 网关启动时已经只会跳过该坏插件，因此其他插件和渠道可以继续运行。
- 当另一个 supervisor 拥有 Gateway 网关生命周期时，设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍会报告 Gateway 网关/服务健康状态并应用非服务修复，但会跳过服务安装/启动/重启/bootstrap 和旧版服务清理。
- 在 Linux 上，doctor 会忽略处于非活动状态的额外 Gateway 网关样式 systemd 单元，并且不会在修复期间重写正在运行的 systemd Gateway 网关服务的命令/入口点元数据。当你有意替换活动启动器时，请先停止服务，或使用 `openclaw gateway install --force`。
- Doctor 会将旧版扁平 Talk 配置（`talk.voiceId`、`talk.modelId` 及相关配置）自动迁移到 `talk.provider` + `talk.providers.<provider>`。
+- 交互式提示（如钥匙串/OAuth 修复）只会在 stdin 是 TTY 且**未**设置 `--non-interactive` 时运行。无界面运行（cron、Telegram、无终端）会跳过提示。
+- 性能：非交互式 `doctor` 运行会跳过预先加载插件，因此无界面健康检查会保持快速。交互式会话仍会在检查需要插件提供信息时完整加载插件。
+- `--fix`（`--repair` 的别名）会将备份写入 `~/.openclaw/openclaw.json.bak`，并删除未知配置键名，同时列出每项删除。
+- 状态完整性检查现在会检测会话目录中的孤立转录文件。将它们归档为 `.deleted.<timestamp>` 需要交互式确认；`--fix`、`--yes` 和无界面运行会保留它们。
+- Doctor 还会扫描 `~/.openclaw/cron/jobs.json`（或 `cron.store`）中的旧版 cron 任务结构，并可在调度器必须在运行时自动规范化它们之前就地重写。
+- Doctor 会修复缺失的内置插件运行时依赖，而不会写入打包的全局安装。对于 root 拥有的 npm 安装或加固的 systemd 单元，请将 `OPENCLAW_PLUGIN_STAGE_DIR` 设置为可写目录，例如 `/var/lib/openclaw/plugin-runtime-deps`；它也可以是路径列表，例如 `/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps`，其中较早的根目录是只读查找层，最后一个根目录是修复目标。
+- 当插件发现健康时，Doctor 会通过从 `plugins.allow`/`plugins.entries` 中移除缺失的插件 ID，以及匹配的悬空渠道配置、心跳目标和渠道模型覆盖，来修复过期插件配置。
+- Doctor 会隔离无效插件配置：禁用受影响的 `plugins.entries.<id>` 条目，并移除其无效的 `config` 载荷。Gateway 网关启动时已经只会跳过该异常插件，因此其他插件和渠道可以继续运行。
+- 当另一个监督程序拥有 Gateway 网关生命周期时，请设置 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。Doctor 仍会报告 Gateway 网关/服务健康状态并应用非服务修复，但会跳过服务安装/启动/重启/引导和旧版服务清理。
+- 在 Linux 上，Doctor 会忽略未激活的额外类 Gateway 网关 systemd 单元，并且不会在修复期间重写正在运行的 systemd Gateway 网关服务的命令/入口点元数据。如果你确实想替换活动启动器，请先停止服务，或使用 `openclaw gateway install --force`。
+- Doctor 会自动将旧版扁平 Talk 配置（`talk.voiceId`、`talk.modelId` 及相关项）迁移到 `talk.provider` + `talk.providers.<provider>`。
 - 当唯一差异是对象键顺序时，重复运行 `doctor --fix` 不再报告/应用 Talk 规范化。
- Doctor 包含记忆搜索就绪性检查，并可在缺少嵌入凭证时推荐 `openclaw configure --section model`。
- 如果启用了沙箱模式但 Docker 不可用，doctor 会报告一条高信号警告，并提供补救措施（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理且在当前命令路径中不可用，doctor 会报告只读警告，并且不会写入明文后备凭证。
- 如果在修复路径中渠道 SecretRef 检查失败，doctor 会继续执行并报告警告，而不是提前退出。
- Telegram `allowFrom` 用户名自动解析（`doctor --fix`）需要当前命令路径中有一个可解析的 Telegram 令牌。如果令牌检查不可用，doctor 会报告警告，并跳过该次自动解析。
+- Doctor 包含记忆搜索就绪性检查，并可在缺少嵌入凭证时推荐运行 `openclaw configure --section model`。
+- 当未配置命令所有者时，Doctor 会发出警告。命令所有者是允许运行仅所有者命令并批准危险操作的人类操作员账号。私信配对只允许某人与机器人对话；如果你在首个所有者引导机制存在之前批准过发送者，请显式设置 `commands.ownerAllowFrom`。
+- 如果启用了沙箱模式但 Docker 不可用，Doctor 会报告高信号警告并给出补救措施（`install Docker` 或 `openclaw config set agents.defaults.sandbox.mode off`）。
+- 如果 `gateway.auth.token`/`gateway.auth.password` 由 SecretRef 管理，且在当前命令路径中不可用，Doctor 会报告只读警告，并且不会写入明文后备凭证。
+- 如果渠道 SecretRef 检查在修复路径中失败，Doctor 会继续执行并报告警告，而不是提前退出。
+- Telegram `allowFrom` 用户名自动解析（`doctor --fix`）需要当前命令路径中有可解析的 Telegram 令牌。如果令牌检查不可用，Doctor 会报告警告，并跳过该轮自动解析。

 ## macOS：`launchctl` 环境变量覆盖

-如果你之前运行过 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖你的配置文件，并可能导致持久的“未授权”错误。
+如果你之前运行过 `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...`（或 `...PASSWORD`），该值会覆盖你的配置文件，并可能导致持续的“未授权”错误。

 ```bash
 launchctl getenv OPENCLAW_GATEWAY_TOKEN
@ -75,7 +76,7 @@ launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
 launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
 ```

-## 相关
+## 相关内容

 - [CLI 参考](/zh-CN/cli)
- [Gateway 网关 doctor](/zh-CN/gateway/doctor)
+- [Gateway 网关 Doctor](/zh-CN/gateway/doctor)
--- a/docs/zh-CN/cli/pairing.md
+++ b/docs/zh-CN/cli/pairing.md
@ -1,24 +1,24 @@
 ---
 read_when:
-    - 你正在使用配对模式私信，并且需要批准发送者
+    - 你正在使用配对模式私信，需要批准发送者
 summary: '`openclaw pairing` 的 CLI 参考（批准/列出配对请求）'
 title: 配对
 x-i18n:
-    generated_at: "2026-04-24T03:15:08Z"
-    model: gpt-5.4
+    generated_at: "2026-04-28T22:44:20Z"
+    model: gpt-5.5
    provider: openai
-    source_hash: 9e81dc407138e958e41d565b0addb600ad1ba5187627bb219f0b85b92bd112d1
+    source_hash: bffc70a8c08e298f42c8fbc2238fce06993572e72f333e87ad18dea3cf33fab5
    source_path: cli/pairing.md
-    workflow: 15
+    workflow: 16
 ---

 # `openclaw pairing`

-批准或查看私信配对请求（适用于支持配对的渠道）。
+批准或检查私信配对请求（适用于支持配对的渠道）。

-相关内容：
+相关：

- 配对流程： [配对](/zh-CN/channels/pairing)
+- 配对流程：[配对](/zh-CN/channels/pairing)

 ## 命令

@ -34,44 +34,51 @@ openclaw pairing approve --channel telegram --account work <code> --notify

 ## `pairing list`

-列出某个渠道的待处理配对请求。
+列出一个渠道的待处理配对请求。

 选项：

- `[channel]`：位置参数渠道 id
- `--channel <channel>`：显式指定渠道 id
- `--account <accountId>`：多账号渠道的账号 id
+- `[channel]`：位置参数渠道 ID
+- `--channel <channel>`：显式渠道 ID
+- `--account <accountId>`：多账号渠道的账号 ID
 - `--json`：机器可读输出

-注意事项：
+注意：

 - 如果配置了多个支持配对的渠道，你必须通过位置参数或 `--channel` 提供一个渠道。
- 只要渠道 id 有效，也允许使用扩展渠道。
+- 只要渠道 ID 有效，就允许使用扩展渠道。

 ## `pairing approve`

-批准待处理的配对代码，并允许该发送者。
+批准一个待处理的配对码，并允许该发送者。

 用法：

 - `openclaw pairing approve <channel> <code>`
 - `openclaw pairing approve --channel <channel> <code>`
- 当只配置了一个支持配对的渠道时，可使用 `openclaw pairing approve <code>`
+- 当恰好配置了一个支持配对的渠道时，可使用 `openclaw pairing approve <code>`

 选项：

- `--channel <channel>`：显式指定渠道 id
- `--account <accountId>`：多账号渠道的账号 id
- `--notify`：在同一渠道向请求者发送确认消息
+- `--channel <channel>`：显式渠道 ID
+- `--account <accountId>`：多账号渠道的账号 ID
+- `--notify`：在同一渠道向请求者发送确认

-## 注意事项
+所有者引导：

- 渠道输入：可通过位置参数传入（`pairing list telegram`），或使用 `--channel <channel>`。
- `pairing list` 支持多账号渠道的 `--account <accountId>`。
+- 如果你批准配对码时 `commands.ownerAllowFrom` 为空，OpenClaw 还会将已批准的发送者记录为命令所有者，使用渠道作用域条目，例如 `telegram:123456789`。
+- 这只会引导第一个所有者。后续配对批准不会替换或扩展 `commands.ownerAllowFrom`。
+- 命令所有者是被允许运行仅所有者命令并批准危险操作的人类操作员账号，例如 `/diagnostics`、`/export-trajectory`、`/config` 和 exec 批准。
+
+## 注意
+
+- 渠道输入：通过位置参数传入（`pairing list telegram`）或使用 `--channel <channel>`。
+- `pairing list` 支持用于多账号渠道的 `--account <accountId>`。
 - `pairing approve` 支持 `--account <accountId>` 和 `--notify`。
 - 如果只配置了一个支持配对的渠道，则允许使用 `pairing approve <code>`。
+- 如果你在此引导机制存在之前已经批准过某个发送者，请运行 `openclaw doctor`；当未配置命令所有者时，它会发出警告，并显示用于修复的 `openclaw config set commands.ownerAllowFrom ...` 命令。

-## 相关内容
+## 相关

 - [CLI 参考](/zh-CN/cli)
 - [渠道配对](/zh-CN/channels/pairing)
--- a/docs/zh-CN/cli/sessions.md
+++ b/docs/zh-CN/cli/sessions.md
@ -1,15 +1,15 @@
 ---
 read_when:
-    - 你想列出已存储的会话并查看最近的活动
-summary: '`openclaw sessions` 的 CLI 参考（列出已存储的会话 + 用法）'
+    - 你想列出已存储的会话并查看最近活动
+summary: CLI 参考：`openclaw sessions`（列出已存储会话 + 用法）
 title: 会话
 x-i18n:
-    generated_at: "2026-04-27T20:10:11Z"
-    model: gpt-5.4
+    generated_at: "2026-04-28T22:44:18Z"
+    model: gpt-5.5
    provider: openai
-    source_hash: 77bf1cdc5cb1688889ec5155241ed98a2c62204c56e727a1174c593a79c78ca8
+    source_hash: 9fea2014f538b00a27fa0078391a421843052333c5bcfc8100fced515eed0004
    source_path: cli/sessions.md
-    workflow: 15
+    workflow: 16
 ---

 # `openclaw sessions`
@ -28,14 +28,21 @@ openclaw sessions --json
 范围选择：

 - 默认：已配置的默认智能体存储
- `--verbose`：详细日志
+- `--verbose`：详细日志记录
 - `--agent <id>`：一个已配置的智能体存储
 - `--all-agents`：聚合所有已配置的智能体存储
- `--store <path>`：显式指定存储路径（不能与 `--agent` 或 `--all-agents` 组合使用）
+- `--store <path>`：显式存储路径（不能与 `--agent` 或 `--all-agents` 组合使用）

-`openclaw sessions --all-agents` 会读取已配置的智能体存储。Gateway 网关 和 ACP 的
-会话发现范围更广：它们还会包含在默认 `agents/` 根目录下或模板化的 `session.store` 根目录下找到的仅存在于磁盘上的存储。这些
-发现到的存储必须解析为智能体根目录内的常规 `sessions.json` 文件；符号链接和根目录外路径会被跳过。
+为已存储的会话导出轨迹包：
+
+```bash
+openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
+openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
+```
+
+这是所有者批准 exec 请求后，`/export-trajectory` 斜杠命令使用的命令路径。输出目录始终解析到所选工作区下的 `.openclaw/trajectory-exports/` 内。
+
+`openclaw sessions --all-agents` 会读取已配置的智能体存储。Gateway 网关和 ACP 会话发现范围更广：它们还会包括在默认 `agents/` 根目录或模板化 `session.store` 根目录下找到的仅磁盘存储。这些已发现的存储必须解析为智能体根目录内的常规 `sessions.json` 文件；符号链接和根目录外路径会被跳过。

 JSON 示例：

@ -60,7 +67,7 @@ JSON 示例：

 ## 清理维护

-立即运行维护（而不是等到下一次写入周期）：
+立即运行维护（而不是等待下一个写入周期）：

 ```bash
 openclaw sessions cleanup --dry-run
@ -73,17 +80,17 @@ openclaw sessions cleanup --json

 `openclaw sessions cleanup` 使用配置中的 `session.maintenance` 设置：

- 范围说明：`openclaw sessions cleanup` 会维护会话存储、转录记录以及轨迹 sidecar 文件。它不会清理 cron 运行日志（`cron/runs/<jobId>.jsonl`）；这些日志由 [Cron configuration](/zh-CN/automation/cron-jobs#configuration) 中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，并在 [Cron maintenance](/zh-CN/automation/cron-jobs#maintenance) 中说明。
+- 范围说明：`openclaw sessions cleanup` 维护会话存储、转录记录和轨迹 sidecar。它不会清理 cron 运行日志（`cron/runs/<jobId>.jsonl`），这些日志由 [Cron 配置](/zh-CN/automation/cron-jobs#configuration)中的 `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 管理，并在 [Cron 维护](/zh-CN/automation/cron-jobs#maintenance)中说明。

- `--dry-run`：预览将会清理或封顶多少条目，而不写入。
-  - 在文本模式下，dry-run 会打印按会话划分的操作表（`Action`、`Key`、`Age`、`Model`、`Flags`），这样你可以看到哪些会被保留，哪些会被移除。
+- `--dry-run`：预览会被清理/限制的条目数量，不写入。
+  - 在文本模式下，dry-run 会打印每个会话的操作表（`Action`、`Key`、`Age`、`Model`、`Flags`），这样你可以看到哪些会被保留、哪些会被移除。
 - `--enforce`：即使 `session.maintenance.mode` 为 `warn`，也应用维护。
- `--fix-missing`：移除其转录文件缺失的条目，即使这些条目按正常规则尚未达到过期或数量上限。
- `--active-key <key>`：保护特定活动键不被磁盘预算淘汰。
- `--agent <id>`：为一个已配置的智能体存储运行清理。
- `--all-agents`：为所有已配置的智能体存储运行清理。
- `--store <path>`：针对特定的 `sessions.json` 文件运行。
- `--json`：打印 JSON 摘要。配合 `--all-agents` 使用时，输出会包含每个存储各自的一份摘要。
+- `--fix-missing`：移除转录文件缺失的条目，即使它们通常尚未达到按时间/数量清理的条件。
+- `--active-key <key>`：保护指定活跃键，避免因磁盘预算驱逐。
+- `--agent <id>`：对一个已配置的智能体存储运行清理。
+- `--all-agents`：对所有已配置的智能体存储运行清理。
+- `--store <path>`：针对特定 `sessions.json` 文件运行。
+- `--json`：打印 JSON 摘要。使用 `--all-agents` 时，输出会包含每个存储的一份摘要。

 `openclaw sessions cleanup --all-agents --dry-run --json`：

@ -113,9 +120,9 @@ openclaw sessions cleanup --json
 }
 ```

-相关内容：
+相关：

- 会话配置：[Configuration reference](/zh-CN/gateway/config-agents#session)
+- 会话配置：[配置参考](/zh-CN/gateway/config-agents#session)

 ## 相关

--- a/docs/zh-CN/gateway/diagnostics.md
+++ b/docs/zh-CN/gateway/diagnostics.md
@ -1,20 +1,22 @@
 ---
 read_when:
    - 准备错误报告或支持请求
-    - 调试 Gateway 网关崩溃、重启、内存压力或超大负载
+    - 调试 Gateway 网关崩溃、重启、内存压力或超大载荷
    - 查看哪些诊断数据会被记录或脱敏
 summary: 为错误报告创建可共享的 Gateway 网关诊断包
 title: 诊断导出
 x-i18n:
-    generated_at: "2026-04-28T11:51:36Z"
+    generated_at: "2026-04-28T22:44:38Z"
    model: gpt-5.5
    provider: openai
-    source_hash: eca1381cfd603eb659a24cd92f2f79a7ed6a8aaf7f451d3662713e0be0ee637e
+    source_hash: e66f1391da77e531b5d3b0ed19600da222d80960d1b6e54d51925c04b06dae46
    source_path: gateway/diagnostics.md
    workflow: 16
 ---

-OpenClaw 可以创建一个本地诊断 zip 文件，可安全附加到错误报告中。它会合并经过清理的 Gateway 网关状态、健康状况、日志、配置形状以及最近的不含载荷的稳定性事件。
+OpenClaw 可以为错误报告创建本地诊断 zip。它会组合经过清理的 Gateway 网关状态、健康状况、日志、配置结构，以及最近的不含载荷的稳定性事件。
+
+在审核之前，请像对待密钥一样对待诊断包。它们的设计目标是省略或遮盖载荷和凭证，但仍会汇总本地 Gateway 网关日志和主机级运行时状态。

 ## 快速开始

@ -34,43 +36,57 @@ openclaw gateway diagnostics export --output openclaw-diagnostics.zip
 openclaw gateway diagnostics export --json
 ```

+## 聊天命令
+
+所有者可以在聊天中使用 `/diagnostics [note]` 请求本地 Gateway 网关导出。当错误发生在真实对话中，并且你想要一份可复制粘贴的支持报告时，请使用它：
+
+1. 在你发现问题的对话中发送 `/diagnostics`。如果有帮助，可以添加简短备注，例如 `/diagnostics bad tool choice`。
+2. OpenClaw 会发送诊断前言，并请求一次明确的 exec 批准。该批准会运行 `openclaw gateway diagnostics export --json`。不要通过 allow-all 规则批准诊断。
+3. 批准后，OpenClaw 会回复一份可粘贴的报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。
+
+在群聊中，所有者仍然可以运行 `/diagnostics`，但 OpenClaw 不会把诊断详情发回共享聊天。它会通过私有批准路由，将前言、批准提示、Gateway 网关导出结果，以及 Codex 会话/线程明细发送给所有者。群聊只会收到一条简短通知，说明诊断流程已私下发送。如果 OpenClaw 找不到私有所有者路由，该命令会默认失败，并要求所有者从私信中运行它。
+
+当活动的 OpenClaw 会话正在使用原生 OpenAI Codex harness 时，同一个 exec 批准也会覆盖一次 OpenAI 反馈上传，上传对象是 OpenClaw 已知的 Codex 运行时线程。该上传与本地 Gateway 网关 zip 分开，并且只会出现在 Codex harness 会话中。批准前，提示会说明批准诊断也会发送 Codex 反馈，但不会列出 Codex 会话或线程 ID。批准后，聊天回复会列出已发送到 OpenAI 服务器的线程对应的渠道、OpenClaw 会话 ID、Codex 线程 ID 和本地恢复命令。如果你拒绝或忽略批准，OpenClaw 不会运行导出，不会发送 Codex 反馈，也不会打印 Codex ID。
+
+这让常见的 Codex 调试循环很短：在 Telegram、Discord 或其他渠道中发现异常行为，运行 `/diagnostics`，批准一次，和支持人员共享报告，然后如果想自己检查原生 Codex 线程，就在本地运行打印出的 `codex resume <thread-id>` 命令。该检查工作流请参见 [Codex harness](/zh-CN/plugins/codex-harness#inspect-a-codex-thread-from-the-cli)。
+
 ## 导出内容

-该 zip 包括：
+zip 包含：

- `summary.md`：供支持人员阅读的人类可读概览。
+- `summary.md`：面向支持人员的可读概览。
 - `diagnostics.json`：配置、日志、状态、健康状况和稳定性数据的机器可读摘要。
 - `manifest.json`：导出元数据和文件列表。
- 经过清理的配置形状和非机密配置详情。
- 经过清理的日志摘要和最近已脱敏的日志行。
+- 经过清理的配置结构和非密钥配置详情。
+- 经过清理的日志摘要和最近经过遮盖的日志行。
 - 尽力获取的 Gateway 网关状态和健康状况快照。
- `stability/latest.json`：最新持久化的稳定性包（如果可用）。
+- `stability/latest.json`：可用时最新持久化的稳定性包。

-即使 Gateway 网关不健康，导出仍然有用。如果 Gateway 网关无法响应状态或健康状况请求，在可用时仍会收集本地日志、配置形状和最新稳定性包。
+即使 Gateway 网关不健康，导出也很有用。如果 Gateway 网关无法响应状态或健康状况请求，在可用时仍会收集本地日志、配置结构和最新稳定性包。

 ## 隐私模型

-诊断设计为可共享。导出会保留有助于调试的运行数据，例如：
+诊断的设计目标是可共享。导出会保留有助于调试的运维数据，例如：

 - 子系统名称、插件 ID、提供商 ID、渠道 ID 和已配置模式
- 状态码、持续时间、字节数、队列状态和内存读数
- 经过清理的日志元数据和已脱敏的运行消息
- 配置形状和非机密功能设置
+- 状态码、耗时、字节数、队列状态和内存读数
+- 经过清理的日志元数据和经过遮盖的运维消息
+- 配置结构和非密钥功能设置

-导出会省略或脱敏：
+导出会省略或遮盖：

 - 聊天文本、提示、指令、webhook 正文和工具输出
- 凭证、API 密钥、令牌、cookie 和机密值
+- 凭证、API key、令牌、cookie 和密钥值
 - 原始请求或响应正文
 - 账号 ID、消息 ID、原始会话 ID、主机名和本地用户名

-当日志消息看起来像用户、聊天、提示或工具载荷文本时，导出只会保留“消息已省略”以及字节数。
+当日志消息看起来像用户、聊天、提示或工具载荷文本时，导出只会保留消息已被省略这一事实以及字节数。

 ## 稳定性记录器

-默认情况下，启用诊断时，Gateway 网关会记录一个有界且不含载荷的稳定性流。它用于记录运行事实，而不是内容。
+默认情况下，启用诊断时，Gateway 网关会记录有界的、不含载荷的稳定性流。它用于记录运维事实，而不是内容。

-当 Gateway 网关持续运行但 Node.js 事件循环或 CPU 看起来已饱和时，同一个诊断心跳会记录存活性警告。这些 `diagnostic.liveness.warning` 事件包含事件循环延迟、事件循环利用率、CPU 核心比率，以及活跃/等待/排队的会话数量。它们本身不会重启 Gateway 网关。
+当 Gateway 网关持续运行但 Node.js 事件循环或 CPU 看起来饱和时，同一个诊断心跳会记录存活性警告。这些 `diagnostic.liveness.warning` 事件包含事件循环延迟、事件循环利用率、CPU 核心比率，以及活动/等待/排队会话计数。它们本身不会重启 Gateway 网关。

 检查实时记录器：

@ -86,7 +102,7 @@ openclaw gateway stability --json
 openclaw gateway stability --bundle latest
 ```

-从最新持久化的包创建诊断 zip：
+从最新持久化包创建诊断 zip：

 ```bash
 openclaw gateway stability --bundle latest --export
@ -94,7 +110,7 @@ openclaw gateway stability --bundle latest --export

 当存在事件时，持久化包位于 `~/.openclaw/logs/stability/` 下。

-## 有用选项
+## 常用选项

 ```bash
 openclaw gateway diagnostics export \
@ -103,9 +119,9 @@ openclaw gateway diagnostics export \
  --log-bytes 1000000
 ```

- `--output <path>`：写入指定的 zip 路径。
- `--log-lines <count>`：要包含的已清理日志行数上限。
- `--log-bytes <bytes>`：要检查的日志字节数上限。
+- `--output <path>`：写入到指定 zip 路径。
+- `--log-lines <count>`：要包含的最大清理后日志行数。
+- `--log-bytes <bytes>`：要检查的最大日志字节数。
 - `--url <url>`：用于状态和健康状况快照的 Gateway 网关 WebSocket URL。
 - `--token <token>`：用于状态和健康状况快照的 Gateway 网关令牌。
 - `--password <password>`：用于状态和健康状况快照的 Gateway 网关密码。
@ -125,9 +141,9 @@ openclaw gateway diagnostics export \
 }
 ```

-禁用诊断会减少错误报告详情。它不会影响正常的 Gateway 网关日志记录。
+禁用诊断会减少错误报告细节。它不会影响正常的 Gateway 网关日志记录。

-## 相关内容
+## 相关

 - [健康检查](/zh-CN/gateway/health)
 - [Gateway 网关 CLI](/zh-CN/cli/gateway#gateway-diagnostics-export)
--- a/docs/zh-CN/plugins/codex-harness.md
+++ b/docs/zh-CN/plugins/codex-harness.md
@ -2,149 +2,134 @@
 read_when:
    - 你想使用内置的 Codex app-server harness
    - 你需要 Codex harness 配置示例
-    - 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 PI
+    - 你希望仅使用 Codex 的部署直接失败，而不是回退到 Pi
 summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次
 title: Codex harness
 x-i18n:
-    generated_at: "2026-04-28T00:32:29Z"
-    model: gpt-5.4
+    generated_at: "2026-04-28T22:44:39Z"
+    model: gpt-5.5
    provider: openai
-    source_hash: 4275f06cfaba2cc1f3f03204993c5c8678939979f734aca08b8053bbc14d7d8f
+    source_hash: ab5e03f02121aee4fd328382dfdfd9bfce6a87158758a25b980e7208b22855bd
    source_path: plugins/codex-harness.md
-    workflow: 15
+    workflow: 16
 ---

-内置的 `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 嵌入式智能体轮次。                        |
-| 原生聊天控制命令                  | `/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 bind`, `/codex resume`, `/codex steer`, ... | 从消息对话绑定和控制 Codex app-server 线程。                                  |
+| Codex app-server 提供商/目录      | `codex` 内部机制，通过 harness 暴露                 | 让运行时发现并验证 app-server 模型。                                          |
+| Codex 媒体理解路径                | `codex/*` 图像模型兼容路径                          | 为受支持的图像理解模型运行有界的 Codex app-server 轮次。                      |
+| 原生钩子中继                      | 围绕 Codex 原生事件的插件钩子                       | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/完成事件。                       |

-启用该插件后，这些能力就会可用。但它**不会**：
+启用该插件会让这些能力可用。它**不会**：

- 为每个 OpenAI 模型都开始使用 Codex
+- 开始对每个 OpenAI 模型都使用 Codex
 - 将 `openai-codex/*` 模型引用转换为原生运行时
- 让 ACP/acpx 成为默认的 Codex 路径
- 热切换已经记录了 Pi 运行时的现有会话
- 替换 OpenClaw 的渠道投递、会话文件、auth-profile 存储或消息路由
+- 让 ACP/acpx 成为默认 Codex 路径
+- 热切换已经记录 PI 运行时的现有会话
+- 替换 OpenClaw 渠道投递、会话文件、认证配置文件存储或消息路由

-同一个插件也负责原生 `/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`
+- `before_message_write`，用于镜像转录记录
+- `before_agent_finalize`，通过 Codex `Stop` 中继
 - `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)。
+关于插件钩子语义本身，请参阅 [插件钩子](/zh-CN/plugins/hooks) 和 [插件守卫行为](/zh-CN/tools/plugin)。

-该 harness 默认关闭。新配置应保持 OpenAI 模型引用的规范形式为
-`openai/gpt-*`，并在需要原生 app-server 执行时，显式强制设置
-`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。为了兼容性，旧版 `codex/*` 模型引用仍会自动选择该 harness，但由运行时支持的旧版 provider 前缀不会作为常规模型/提供商选项显示。
+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 执行仍是显式运行时选择。

 ## 路由映射

-在修改配置之前，请先使用此表：
+更改配置前请使用此表：

-| 期望行为                                  | 模型引用                   | 运行时配置                             | 插件要求                    | 预期的 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 专属引用          | `agentRuntime.id: "auto"`              | 可选的插件运行时            | 取决于所选运行时               |
-| 显式 Codex ACP 适配器会话                 | ACP prompt/model dependent | `sessions_spawn` 配合 `runtime: "acp"` | 健康的 `acpx` 后端          | ACP task/session status        |
+| 期望行为                                    | 模型引用                   | 运行时配置                             | 插件要求                    | 预期 Status 标签              |
+| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ |
+| 通过普通 OpenClaw runner 使用 OpenAI API    | `openai/gpt-*`             | 省略或 `runtime: "pi"`                 | OpenAI provider             | `Runtime: OpenClaw Pi Default` |
+| 通过 PI 使用 Codex OAuth/订阅               | `openai-codex/gpt-*`       | 省略或 `runtime: "pi"`                 | OpenAI Codex OAuth 提供商   | `Runtime: OpenClaw Pi Default` |
+| 原生 Codex app-server 嵌入式轮次            | `openai/gpt-*`             | `agentRuntime.id: "codex"`             | `codex` 插件                | `Runtime: OpenAI Codex`        |
+| 使用保守自动模式的混合提供商                | 提供商特定引用             | `agentRuntime.id: "auto"`              | 可选插件运行时              | 取决于选中的运行时             |
+| 显式 Codex ACP 适配器会话                   | 取决于 ACP 提示词/模型     | `sessions_spawn` 搭配 `runtime: "acp"` | 健康的 `acpx` 后端          | ACP 任务/会话 Status           |

-关键区别在于 provider 与运行时：
+重要的区分是提供商与运行时：

- `openai-codex/*` 回答的是“Pi 应使用哪条 provider/auth 路径？”
- `agentRuntime.id: "codex"` 回答的是“此嵌入式轮次应由哪个循环执行？”
- `/codex ...` 回答的是“此聊天应绑定或控制哪个原生 Codex 对话？”
- ACP 回答的是“acpx 应启动哪个外部 harness 进程？”
+- `openai-codex/*` 回答“PI 应使用哪个提供商/认证路由？”
+- `agentRuntime.id: "codex"` 回答“哪个循环应执行这个嵌入式轮次？”
+- `/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 Platform API 访问，并提供 `OPENAI_API_KEY`。    |
+| `openai-codex/gpt-5.5`                        | 通过 OpenClaw/PI 使用 OpenAI Codex OAuth    | 你希望通过默认 PI runner 使用 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`；对于 Codex app-server harness，请使用 `openai/gpt-5.5` 搭配 Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，`openai/gpt-5.5` 就会支持直接通过 API key 访问。
+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，就会支持 `openai/gpt-5.5` 的直接 API key 访问。

-旧版 `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 警告意味着什么
+### Doctor 警告的含义

-当以下条件全部满足时，`openclaw doctor` 会发出警告：
+当以下条件全部为真时，`openclaw doctor` 会发出警告：

- 内置的 `codex` 插件已启用或被允许
+- 捆绑的 `codex` 插件已启用或被允许
 - 某个智能体的主模型是 `openai-codex/*`
- 该智能体的实际运行时不是 `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。修改配置后，请使用 `/new` 或 `/reset`，让该对话切换到 Codex。
+在 harness 固定之前创建的旧版会话，一旦已有转录历史，就会被视为已固定到 PI。更改配置后，使用 `/new` 或 `/reset` 将该对话选择加入 Codex。

-`/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 进程或 OpenClaw 的 Codex auth bridge 可用的 Codex 认证。
+- OpenClaw 中可用的捆绑 `codex` 插件。
+- Codex app-server `0.125.0` 或更新版本。捆绑插件默认管理兼容的 Codex app-server 二进制文件，因此 `PATH` 上的本地 `codex` 命令不会影响正常 harness 启动。
+- app-server 进程或 OpenClaw 的 Codex 认证桥接可用的 Codex 认证。

-该插件会拦截较旧或未标明版本的 app-server 握手。这可以确保 OpenClaw 运行在它已经测试过的协议表面上。
+该插件会阻止更旧或无版本的 app-server 握手。这让 OpenClaw 保持在已经测试过的协议表面上。

-对于 live 和 Docker smoke 测试，认证通常来自 Codex CLI 账户或 OpenClaw 的 `openai-codex` auth profile。本地 stdio app-server 启动在没有账户时，也可以回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。
+对于 live 和 Docker 冒烟测试，认证通常来自 Codex CLI 账户或 OpenClaw `openai-codex` 认证配置文件。本地 stdio app-server 启动也可以在没有账户时回退到 `CODEX_API_KEY` / `OPENAI_API_KEY`。

 ## 最小配置

-使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` harness：
+使用 `openai/gpt-5.5`，启用捆绑插件，并强制使用 `codex` harness：

 ```json5
 {
@ -166,7 +151,7 @@ Harness 选择并不是实时会话控制。当嵌入式轮次运行时，OpenCl
 }
 ```

-如果你的配置使用了 `plugins.allow`，也需要把 `codex` 加进去：
+如果你的配置使用 `plugins.allow`，也在那里包含 `codex`：

 ```json5
 {
@ -181,21 +166,19 @@ Harness 选择并不是实时会话控制。当嵌入式轮次运行时，OpenCl
 }
 ```

-对于把 `agents.defaults.model` 或某个智能体模型设置为
-`codex/<model>` 的旧配置，仍会自动启用内置 `codex` 插件。新配置应优先使用 `openai/<model>`，并配合上面的显式 `agentRuntime` 条目。
+将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>` 的旧版配置仍会自动启用捆绑的 `codex` 插件。新配置应优先使用 `openai/<model>` 加上面的显式 `agentRuntime` 条目。

-## 将 Codex 与其他模型一起使用
+## 将 Codex 与其他模型一起添加

-如果同一个智能体应在 Codex 和非 Codex provider 模型之间自由切换，请不要全局设置 `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"`，并为常规混合 provider 使用保留 Pi 回退。
- 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用
-  `openai/*`，并显式指定 Codex 运行时策略。
+- 将 Codex 放在专用智能体上，并设置 `agentRuntime.id: "codex"`。
+- 将默认智能体保留在 `agentRuntime.id: "auto"`，并为正常的混合提供商用法启用 PI 回退。
+- 仅为兼容性使用旧版 `codex/*` 引用。新配置应优先使用 `openai/*`，并显式设置 Codex 运行时策略。

-例如，下面的配置会让默认智能体保持正常的自动选择，并额外添加一个独立的 Codex 智能体：
+例如，以下配置会让默认智能体保持正常的自动选择，并添加一个单独的 Codex 智能体：

 ```json5
 {
@ -232,33 +215,33 @@ Harness 选择并不是实时会话控制。当嵌入式轮次运行时，OpenCl
 }
 ```

-采用这种结构后：
+使用这种形式时：

- 默认的 `main` 智能体使用常规 provider 路径和 Pi 兼容性回退。
- `codex` 智能体使用 Codex app-server harness。
- 如果 `codex` 智能体缺少 Codex 或当前不受支持，该轮次会直接失败，
-  而不是悄悄改用 Pi。
+- 默认的 `main` 智能体使用正常的提供商路径和 PI 兼容性回退。
+- `codex` 智能体使用 Codex 应用服务器 harness。
+- 如果 `codex` 智能体缺少 Codex 或不受支持，该轮会失败，而不是静默改用 PI。

 ## 智能体命令路由

-智能体应根据用户意图路由请求，而不是仅凭“Codex”这个词：
+智能体应按意图路由用户请求，而不是只按 “Codex” 这个词路由：

-| 用户要求……                                             | 智能体应使用……                                  |
-| ------------------------------------------------------ | ------------------------------------------------ |
-| “把这个聊天绑定到 Codex”                               | `/codex bind`                                    |
-| “在这里恢复 Codex 线程 `<id>`”                         | `/codex resume <id>`                             |
-| “显示 Codex 线程”                                      | `/codex threads`                                 |
-| “把 Codex 用作这个智能体的运行时”                      | 将配置改为 `agentRuntime.id`                     |
-| “用我的 ChatGPT/Codex 订阅配合普通 OpenClaw”           | `openai-codex/*` 模型引用                        |
+| 用户要求...                                         | 智能体应使用...                              |
+| -------------------------------------------------------- | ------------------------------------------------ |
+| “将此聊天绑定到 Codex”                                | `/codex bind`                                    |
+| “在这里恢复 Codex 线程 `<id>`”                        | `/codex resume <id>`                             |
+| “显示 Codex 线程”                                     | `/codex threads`                                 |
+| “为一次异常 Codex 运行提交支持报告”              | `/diagnostics [note]`                            |
+| “只为这个附加线程发送 Codex 反馈”      | `/codex diagnostics [note]`                      |
+| “将 Codex 用作此智能体的运行时”                | 将配置改为 `agentRuntime.id`               |
+| “在正常 OpenClaw 中使用我的 ChatGPT/Codex 订阅” | `openai-codex/*` 模型引用                      |
 | “通过 ACP/acpx 运行 Codex”                             | ACP `sessions_spawn({ runtime: "acp", ... })`    |
-| “在线程中启动 Claude Code/Gemini/OpenCode/Cursor”      | ACP/acpx，而不是 `/codex`，也不是原生子智能体    |
+| “在线程中启动 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
 {
@ -274,18 +257,17 @@ Harness 选择并不是实时会话控制。当嵌入式轮次运行时，OpenCl
 }
 ```

-环境变量覆盖：
+环境覆盖：

 ```bash
 OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 ```

-在强制使用 Codex 的情况下，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。只有在你明确希望缺失的 harness 选择由 Pi 处理时，才设置
-`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。
+强制使用 Codex 后，如果 Codex 插件被禁用、应用服务器版本过旧，或应用服务器无法启动，OpenClaw 会提前失败。只有当你有意希望 PI 处理缺失的 harness 选择时，才设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。

 ## 按智能体使用 Codex

-你可以让某一个智能体仅使用 Codex，而默认智能体继续保持正常的自动选择：
+你可以让一个智能体仅使用 Codex，同时默认智能体保持正常的自动选择：

 ```json5
 {
@ -316,17 +298,17 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 }
 ```

-使用常规会话命令在智能体和模型之间切换。`/new` 会创建一个全新的 OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其 sidecar app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮再次根据当前配置解析 harness。
+使用正常的会话命令切换智能体和模型。`/new` 会创建新的 OpenClaw 会话，Codex harness 会按需创建或恢复其旁车应用服务器线程。`/reset` 会清除此线程的 OpenClaw 会话绑定，并让下一轮再次从当前配置解析 harness。

 ## 模型发现

-默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置的回退目录，其中包括：
+默认情况下，Codex 插件会向应用服务器请求可用模型。如果发现失败或超时，它会使用内置回退目录：

 - GPT-5.5
 - GPT-5.4 mini
 - GPT-5.2

-你可以在 `plugins.entries.codex.config.discovery` 下调整发现行为：
+你可以在 `plugins.entries.codex.config.discovery` 下调整发现：

 ```json5
 {
@ -346,7 +328,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 }
 ```

-如果你希望启动时避免探测 Codex，并固定使用回退目录，请禁用发现：
+当你希望启动时避免探测 Codex，并固定使用回退目录时，可以禁用发现：

 ```json5
 {
@ -365,21 +347,19 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
 }
 ```

-## App-server 连接与策略
+## 应用服务器连接和策略

-默认情况下，插件会使用以下命令在本地启动由 OpenClaw 管理的 Codex 二进制文件：
+默认情况下，插件会在本地启动 OpenClaw 管理的 Codex 二进制文件：

 ```bash
 codex app-server --listen stdio://
 ```

-这个受管二进制文件被声明为内置插件运行时依赖，并与 `codex` 插件的其余依赖一起分阶段提供。这样可以让 app-server 版本与内置插件绑定，而不是取决于本地碰巧安装了哪个独立的 Codex CLI。只有在你明确想运行不同可执行文件时，才设置 `appServer.command`。
+受管理的二进制文件声明为内置插件运行时依赖，并与其余 `codex` 插件依赖一起暂存。这会将应用服务器版本绑定到内置插件，而不是绑定到本地碰巧安装的某个单独 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:
+要启用由 Codex guardian 审核的批准，请设置 `appServer.mode:
 "guardian"`：

 ```json5
@ -400,14 +380,11 @@ 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` 审核器值仍然作为兼容别名被接受，但新配置应使用
-`auto_review`。
+`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以混用预设和显式选择。较旧的 `guardian_subagent` 审核器值仍作为兼容别名被接受，但新配置应使用 `auto_review`。

-对于已经在运行的 app-server，请使用 WebSocket 传输：
+对于已运行的应用服务器，请使用 WebSocket 传输：

 ```json5
 {
@ -429,19 +406,15 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
 }
 ```

-默认情况下，stdio app-server 启动会继承 OpenClaw 的进程环境，
-但 OpenClaw 自己负责 Codex app-server 账户桥接。认证按以下顺序选择：
+Stdio 应用服务器启动默认继承 OpenClaw 的进程环境，但 OpenClaw 拥有 Codex 应用服务器账号桥接。认证按以下顺序选择：

-1. 智能体显式指定的 OpenClaw Codex auth profile。
-2. app-server 现有账户，例如本地 Codex CLI 的 ChatGPT 登录。
-3. 仅对本地 stdio app-server 启动，在没有 app-server 账户且仍需要 OpenAI 认证时，依次回退到 `CODEX_API_KEY`，然后是
-   `OPENAI_API_KEY`。
+1. 该智能体的显式 OpenClaw Codex 认证配置文件。
+2. 应用服务器的现有账号，例如本地 Codex CLI ChatGPT 登录。
+3. 仅限本地 stdio 应用服务器启动：当不存在应用服务器账号且仍需要 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 自己的账户。
+当 OpenClaw 看到 ChatGPT 订阅样式的 Codex 认证配置文件时，它会从生成的 Codex 子进程中移除 `CODEX_API_KEY` 和 `OPENAI_API_KEY`。这会让 Gateway 网关级 API 密钥仍可用于嵌入或直接 OpenAI 模型，而不会让原生 Codex 应用服务器轮次意外通过 API 计费。显式 Codex API 密钥配置文件和本地 stdio 环境密钥回退会使用应用服务器登录，而不是继承的子进程环境。WebSocket 应用服务器连接不会收到 Gateway 网关环境 API 密钥回退；请使用显式认证配置文件或远程应用服务器自己的账号。

-如果某个部署需要额外的环境隔离，请将这些变量添加到
-`appServer.clearEnv`：
+如果部署需要额外的环境隔离，请将这些变量添加到 `appServer.clearEnv`：

 ```json5
 {
@ -460,27 +433,27 @@ Guardian 模式使用 Codex 的原生自动审核审批路径。当 Codex 请求
 }
 ```

-`appServer.clearEnv` 只会影响已启动的 Codex app-server 子进程。
+`appServer.clearEnv` 只影响生成的 Codex 应用服务器子进程。

 支持的 `appServer` 字段：

-| 字段                | 默认值                                   | 含义                                                                                                                                |
+| 字段               | 默认值                                  | 含义                                                                                                                             |
 | ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `transport`         | `"stdio"`                                | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。                                                                              |
-| `command`           | 受管的 Codex 二进制文件                  | 用于 stdio 传输的可执行文件。留空则使用受管二进制文件；仅在你明确需要覆盖时设置。                                                   |
-| `args`              | `["app-server", "--listen", "stdio://"]` | stdio 传输的参数。                                                                                                                  |
-| `url`               | 未设置                                   | WebSocket app-server URL。                                                                                                          |
-| `authToken`         | 未设置                                   | WebSocket 传输的 Bearer token。                                                                                                     |
-| `headers`           | `{}`                                     | 额外的 WebSocket headers。                                                                                                          |
-| `clearEnv`          | `[]`                                     | OpenClaw 构建继承环境后，从已启动的 stdio app-server 进程中额外移除的环境变量名称。                                                 |
-| `requestTimeoutMs`  | `60000`                                  | app-server 控制平面调用的超时时间。                                                                                                 |
-| `mode`              | `"yolo"`                                 | YOLO 或 guardian 审核执行的预设。                                                                                                   |
-| `approvalPolicy`    | `"never"`                                | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。                                                                                     |
-| `sandbox`           | `"danger-full-access"`                   | 发送到线程启动/恢复的原生 Codex 沙箱模式。                                                                                          |
-| `approvalsReviewer` | `"user"`                                 | 使用 `"auto_review"` 可让 Codex 审核原生审批提示。`guardian_subagent` 仍然是旧版别名。                                              |
-| `serviceTier`       | 未设置                                   | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版取值会被忽略。                                            |
+| `transport`         | `"stdio"`                                | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。                                                                            |
+| `command`           | 托管的 Codex 二进制文件                     | stdio 传输协议使用的可执行文件。保持未设置以使用托管二进制文件；仅在明确覆盖时设置。                        |
+| `args`              | `["app-server", "--listen", "stdio://"]` | stdio 传输协议的参数。                                                                                                      |
+| `url`               | 未设置                                    | WebSocket app-server URL。                                                                                                           |
+| `authToken`         | 未设置                                    | WebSocket 传输协议的 Bearer 令牌。                                                                                               |
+| `headers`           | `{}`                                     | 额外的 WebSocket 标头。                                                                                                            |
+| `clearEnv`          | `[]`                                     | OpenClaw 构建继承环境后，从派生的 stdio app-server 进程中移除的额外环境变量名称。 |
+| `requestTimeoutMs`  | `60000`                                  | app-server 控制平面调用的超时时间。                                                                                         |
+| `mode`              | `"yolo"`                                 | YOLO 或 guardian 审核执行的预设。                                                                                     |
+| `approvalPolicy`    | `"never"`                                | 发送到线程 start/resume/turn 的原生 Codex 审批策略。                                                                      |
+| `sandbox`           | `"danger-full-access"`                   | 发送到线程 start/resume 的原生 Codex 沙箱模式。                                                                              |
+| `approvalsReviewer` | `"user"`                                 | 使用 `"auto_review"` 让 Codex 审核原生审批提示。`guardian_subagent` 仍是旧版别名。                        |
+| `serviceTier`       | 未设置                                    | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。                           |

-环境变量覆盖仍可用于本地测试：
+本地测试仍可使用环境覆盖：

 - `OPENCLAW_CODEX_APP_SERVER_BIN`
 - `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -488,25 +461,24 @@ 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 在单独的设置指南中介绍：
-[Codex Computer Use](/zh-CN/plugins/codex-computer-use)。
+计算机使用在自己的设置指南中说明：
+[Codex 计算机使用](/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 工具调用。

-如果要在 Codex marketplace 流程之外直接访问 TryCua 驱动程序，请使用
-`openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`
-注册 `cua-driver mcp`。有关 Codex 持有的 Computer Use 与直接 MCP 注册之间的区别，请参阅
-[Codex Computer Use](/zh-CN/plugins/codex-computer-use)。
+若要在 Codex marketplace 流程之外直接访问 TryCua 驱动，请使用 `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'` 注册
+`cua-driver mcp`。
+请参阅 [Codex 计算机使用](/zh-CN/plugins/codex-computer-use)，了解 Codex 拥有的计算机使用与直接 MCP 注册之间的区别。

 最小配置：

@ -536,24 +508,22 @@ Computer Use 在单独的设置指南中介绍：
 }
 ```

-可以通过命令界面检查或安装该设置：
+可以从命令界面检查或安装该设置：

 - `/codex computer-use status`
 - `/codex computer-use install`
 - `/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)。
+计算机使用仅适用于 macOS，并且在 Codex MCP 服务器能够控制应用前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 MCP 服务器不可用，Codex 模式轮次会在线程启动前失败，而不是在没有原生计算机使用工具的情况下静默运行。请参阅
+[Codex 计算机使用](/zh-CN/plugins/codex-computer-use)，了解 marketplace 选项、远程目录限制、Status 原因和故障排除。

 当 `computerUse.autoInstall` 为 true 时，如果 Codex 尚未发现本地 marketplace，OpenClaw 可以从
-`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`
-注册标准内置的 Codex Desktop marketplace。更改运行时或 Computer Use 配置后，请使用 `/new` 或 `/reset`，以免现有会话继续保留旧的 Pi 或 Codex 线程绑定。
+`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` 注册标准内置 Codex Desktop marketplace。更改运行时或计算机使用配置后，请使用 `/new` 或 `/reset`，以免现有会话继续保留旧的 PI 或 Codex 线程绑定。

-## 常见方案
+## 常用配方

-使用默认 stdio 传输的本地 Codex：
+使用默认 stdio 传输协议的本地 Codex：

 ```json5
 {
@ -567,7 +537,7 @@ Computer Use 仅支持 macOS，并且在 Codex MCP 服务器能够控制应用
 }
 ```

-仅使用 Codex 的 harness 校验：
+仅 Codex 的 harness 验证：

 ```json5
 {
@ -589,7 +559,7 @@ Computer Use 仅支持 macOS，并且在 Codex MCP 服务器能够控制应用
 }
 ```

-由 Guardian 审核的 Codex 审批：
+经过 guardian 审核的 Codex 审批：

 ```json5
 {
@ -611,7 +581,7 @@ Computer Use 仅支持 macOS，并且在 Codex MCP 服务器能够控制应用
 }
 ```

-带显式 headers 的远程 app-server：
+带显式标头的远程 app-server：

 ```json5
 {
@ -634,144 +604,158 @@ Computer Use 仅支持 macOS，并且在 Codex MCP 服务器能够控制应用
 }
 ```

-模型切换仍然由 OpenClaw 控制。当某个 OpenClaw 会话附加到现有的 Codex 线程时，下一轮会再次把当前选定的
-OpenAI 模型、provider、审批策略、沙箱和服务层级发送给
-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 线程。
- `/codex compact` 请求 Codex app-server 压缩当前附加的线程。
- `/codex review` 为当前附加的线程启动 Codex 原生审查。
- `/codex computer-use status` 检查已配置的 Computer Use 插件和 MCP 服务器。
- `/codex computer-use install` 安装已配置的 Computer Use 插件并重新加载 MCP 服务器。
- `/codex account` 显示账户和速率限制状态。
- `/codex mcp` 列出 Codex app-server MCP 服务器状态。
+- `/codex compact` 要求 Codex app-server 压缩已附加的线程。
+- `/codex review` 为已附加的线程启动 Codex 原生审查。
+- `/codex diagnostics [note]` 会在发送已附加线程的 Codex 诊断反馈前请求确认。
+- `/codex computer-use status` 检查已配置的计算机使用插件和 MCP 服务器。
+- `/codex computer-use install` 安装已配置的计算机使用插件并重新加载 MCP 服务器。
+- `/codex account` 显示账户和速率限制 Status。
+- `/codex mcp` 列出 Codex app-server MCP 服务器 Status。
 - `/codex skills` 列出 Codex app-server Skills。

-`/codex resume` 会写入与 harness 正常轮次使用的相同 sidecar 绑定文件。在下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持启用扩展历史记录。
+### 常见调试工作流

-该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，则各个控制方法会报告为
-`unsupported by this Codex app-server`。
+当由 Codex 支持的智能体在 Telegram、Discord、Slack 或其他渠道中做出意外行为时，请从发生问题的对话开始：
+
+1. 运行 `/diagnostics bad tool choice after image upload`，或另一条描述你所见情况的简短备注。
+2. 批准一次诊断请求。该批准会创建本地 Gateway 网关诊断 zip，并且因为该会话使用 Codex harness，还会将相关的 Codex 反馈包发送到 OpenAI 服务器。
+3. 将完成后的诊断回复复制到 bug 报告或支持讨论中。它包含本地包路径、隐私摘要、OpenClaw 会话 ID、Codex 线程 ID，以及每个 Codex 线程的一行 `Inspect locally`。
+4. 如果你想自行调试该运行，请在终端中运行打印出的 `Inspect locally` 命令。它看起来像 `codex resume <thread-id>`，会打开原生 Codex 线程，以便你检查对话、在本地继续，或询问 Codex 为什么选择某个特定工具或计划。
+
+仅当你明确想为当前附加的线程上传 Codex 反馈，而不需要完整 OpenClaw
+Gateway 网关诊断包时，才使用 `/codex diagnostics [note]`。对于大多数支持报告，`/diagnostics [note]` 是更好的起点，因为它会在一条回复中把本地 Gateway 网关状态和 Codex 线程 ID 关联起来。请参阅 [诊断导出](/zh-CN/gateway/diagnostics)，了解完整的隐私模型和群聊行为。
+
+核心 OpenClaw 还公开了仅限所有者使用的 `/diagnostics [note]`，作为通用
+Gateway 网关诊断命令。它的审批提示会显示敏感数据前言，链接到 [诊断导出](/zh-CN/gateway/diagnostics)，并且每次都通过显式 exec 审批请求
+`openclaw gateway diagnostics export --json`。不要使用允许所有规则来批准诊断。批准后，OpenClaw 会发送一份可粘贴的报告，其中包含本地包路径和清单摘要。当活跃 OpenClaw 会话使用 Codex harness 时，同一个批准也会授权将相关 Codex 反馈包发送到
+OpenAI 服务器。审批提示会说明将发送 Codex 反馈，但不会在批准前列出 Codex 会话或线程 ID。
+
+如果所有者在群聊中调用 `/diagnostics`，OpenClaw 会保持共享渠道整洁：群组只会收到一条简短通知，而诊断前言、审批提示以及 Codex 会话/线程 ID 会通过私有审批路由发送给所有者。如果没有私有所有者路由，OpenClaw 会拒绝群组请求，并要求所有者从私信中运行它。
+
+已批准的 Codex 上传会调用 Codex app-server `feedback/upload`，并要求
+app-server 在可用时包含每个列出线程和派生 Codex 子线程的日志。上传通过 Codex 的常规反馈路径发送到 OpenAI 服务器；如果该 app-server 中禁用了 Codex 反馈，该命令会返回 app-server 错误。完成后的诊断回复会列出已发送线程的渠道、OpenClaw 会话 ID、Codex 线程 ID，以及本地
+`codex resume <thread-id>` 命令。如果你拒绝或忽略审批，OpenClaw 不会打印这些 Codex ID。此上传不会替代本地 Gateway 网关诊断导出。
+
+`/codex resume` 会写入与 harness 正常轮次所用相同的 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选择的 OpenClaw 模型传入 app-server，并保持扩展历史记录启用。
+
+### 从 CLI 检查 Codex 线程
+
+理解一次异常 Codex 运行的最快方式，通常是直接打开原生 Codex 线程：
+
+```sh
+codex resume <thread-id>
+```
+
+当你在渠道对话中发现 bug，并想检查有问题的 Codex 会话、在本地继续它，或询问 Codex 为什么做出某个工具或推理选择时，请使用此方法。最简单的路径通常是先运行 `/diagnostics [note]`：你批准后，完成的报告会列出每个 Codex 线程，并打印一个 `Inspect locally` 命令，例如 `codex resume <thread-id>`。你可以将该命令直接复制到终端中。
+
+你也可以从当前聊天的 `/codex binding` 获取线程 ID，或从近期 Codex app-server 线程的 `/codex threads [filter]` 获取线程 ID，然后在 shell 中运行相同的 `codex resume` 命令。
+
+该命令接口要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露相应的 JSON-RPC 方法，单个控制方法会报告为 `unsupported by this Codex app-server`。

 ## 钩子边界

 Codex harness 有三层钩子：

-| 层级                                  | 持有方                   | 目的                                                                |
+| 层级                                  | 所有者                   | 用途                                                                |
 | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
-| 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 原生钩子                        | 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 会为每个线程注入 Codex 配置，用于 `PreToolUse`、`PostToolUse`、`PermissionRequest` 和 `Stop`。其他 Codex 钩子（例如 `SessionStart` 和 `UserPromptSubmit`）仍然是 Codex 层级的控制项；它们不会在 v1 合约中作为 OpenClaw 插件钩子暴露。

-对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用之后执行该工具，因此 OpenClaw 会在 harness 适配器中触发其持有的插件和中间件行为。对于 Codex 原生工具，Codex 持有规范工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法重写原生 Codex 线程。
+对于 OpenClaw 动态工具，OpenClaw 会在 Codex 请求调用后执行该工具，因此 OpenClaw 会在 harness 适配器中触发其拥有的插件和中间件行为。对于 Codex 原生工具，Codex 拥有规范工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法重写原生 Codex 线程。

-压缩和 LLM 生命周期投影来自 Codex app-server 通知以及 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。OpenClaw 的
-`before_compaction`、`after_compaction`、`llm_input` 和
-`llm_output` 事件属于适配器级观察结果，而不是对 Codex 内部请求或压缩负载的逐字节捕获。
+压缩和 LLM 生命周期投影来自 Codex app-server 通知和 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。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 拥有更多原生模型循环，而 OpenClaw 会围绕该边界适配其插件和会话表面。

-Codex 运行时 v1 中支持的内容：
+Codex 运行时 v1 支持：

-| 界面                                          | 支持情况                               | 原因                                                                                                                                                                                                   |
-| --------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 通过 Codex 运行 OpenAI 模型循环               | 支持                                   | Codex app-server 持有 OpenAI 轮次、原生线程恢复和原生工具续接。                                                                                                                                       |
-| OpenClaw 渠道路由与投递                       | 支持                                   | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道仍然位于模型运行时之外。                                                                                                                      |
-| OpenClaw 动态工具                             | 支持                                   | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍然在执行路径中。                                                                                                                                  |
-| 提示词和上下文插件                            | 支持                                   | OpenClaw 会在启动或恢复线程之前构建提示词叠加层，并将上下文投影到 Codex 轮次中。                                                                                                                    |
-| 上下文引擎生命周期                            | 支持                                   | 对 Codex 轮次执行 assemble、ingest 或轮次后的维护，以及上下文引擎压缩协调。                                                                                                                          |
-| 动态工具钩子                                  | 支持                                   | `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 模型循环                 | 支持                                    | 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 运行时 v1 中不支持的内容：
+Codex 运行时 v1 不支持：

-| 界面                                                | 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 的 pre/post 压缩钩子。                    |
-| 逐字节的模型 API 请求捕获                           | OpenClaw 可以捕获 app-server 请求和通知，但最终的 OpenAI API 请求由 Codex 核心在内部构建。                                                     | 需要 Codex 的模型请求追踪事件或调试 API。                                                |
+| 原生工具参数变更                                    | Codex 原生工具前置钩子可以阻止，但 OpenClaw 不会重写 Codex 原生工具参数。                                                                      | 需要 Codex 钩子/架构支持替换工具输入。                                                    |
+| 可编辑的 Codex 原生转录历史                         | Codex 拥有规范的原生线程历史。OpenClaw 拥有镜像，并可以投影未来上下文，但不应变更不受支持的内部状态。                                         | 如果需要原生线程手术式修改，请添加显式 Codex app-server API。                             |
+| Codex 原生工具记录的 `tool_result_persist`          | 该钩子转换 OpenClaw 拥有的转录写入，而不是 Codex 原生工具记录。                                                                                | 可以镜像转换后的记录，但规范重写需要 Codex 支持。                                        |
+| 丰富的原生压缩元数据                                | OpenClaw 会观察压缩开始和完成，但不会接收稳定的保留/丢弃列表、token delta 或摘要载荷。                                                        | 需要更丰富的 Codex 压缩事件。                                                            |
+| 压缩干预                                            | 当前 OpenClaw 压缩钩子在 Codex 模式下是通知层级的。                                                                                            | 如果插件需要否决或重写原生压缩，请添加 Codex 前置/后置压缩钩子。                         |
+| 逐字节模型 API 请求捕获                             | OpenClaw 可以捕获 app-server 请求和通知，但 Codex core 会在内部构建最终 OpenAI API 请求。                                                      | 需要 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 插件界面。
+原生钩子中继有意保持通用，但 v1 支持合约仅限于 OpenClaw 测试过的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP `PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。在运行时合约明确命名某个未来 Codex 钩子事件之前，不要假设每个未来 Codex 钩子事件都是 OpenClaw 插件表面。

-对于 `PermissionRequest`，只有在策略作出决定时，OpenClaw 才会返回显式的允许或拒绝结果。无决定结果并不等于允许。Codex 会将其视为“钩子未作决定”，并继续走自己的 guardian 或用户审批路径。
+对于 `PermissionRequest`，OpenClaw 只会在策略做出决定时返回显式允许或拒绝决策。无决策结果不是允许。Codex 会将其视为没有钩子决策，并回退到自己的 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 reasoning 或计划记录。目前，OpenClaw 只记录原生压缩的开始和完成信号。它还不会公开人类可读的压缩摘要，也不会提供 Codex 在压缩后保留了哪些条目的可审计列表。
+当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该镜像包括用户提示、最终助手文本，以及 app-server 发出时的轻量级 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未暴露人类可读的压缩摘要，或可审计的 Codex 在压缩后保留了哪些条目的列表。

-由于 Codex 持有规范的原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它只会在 OpenClaw 写入由 OpenClaw 持有的会话转录工具结果时生效。
+因为 Codex 拥有规范原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它只在 OpenClaw 正在写入 OpenClaw 拥有的会话转录工具结果时适用。

-媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解仍然继续使用匹配的 provider/模型设置，例如
-`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` 提供商：** 对于新的配置，这是预期行为。选择一个带有 `agentRuntime.id: "codex"` 的 `openai/gpt-*` 模型（或旧版 `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-*` 和其他 provider 引用在 `auto` 模式下会继续走各自的正常 provider 路径。如果你强制设置了
-`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 网关以清除过期的原生钩子注册。如果 `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)
- [Model providers](/zh-CN/concepts/model-providers)
+- [模型提供商](/zh-CN/concepts/model-providers)
 - [OpenAI provider](/zh-CN/providers/openai)
 - [Status](/zh-CN/cli/status)
- [Plugin hooks](/zh-CN/plugins/hooks)
- [Configuration reference](/zh-CN/gateway/configuration-reference)
- [Testing](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)
+- [插件钩子](/zh-CN/plugins/hooks)
+- [配置参考](/zh-CN/gateway/configuration-reference)
+- [测试](/zh-CN/help/testing-live#live-codex-app-server-harness-smoke)
--- a/docs/zh-CN/tools/slash-commands.md
+++ b/docs/zh-CN/tools/slash-commands.md
@ -3,20 +3,20 @@ read_when:
    - 使用或配置聊天命令
    - 调试命令路由或权限
 sidebarTitle: Slash commands
-summary: 斜杠命令：文本与原生命令、配置和支持的命令
+summary: 斜杠命令：文本与原生、配置和支持的命令
 title: 斜杠命令
 x-i18n:
-    generated_at: "2026-04-28T12:06:33Z"
+    generated_at: "2026-04-28T22:44:27Z"
    model: gpt-5.5
    provider: openai
-    source_hash: e799ffb979cb405ee29e606ac914684595ddb59d7f878fab741c7dda90401a4c
+    source_hash: f9dfa0d86b953fe83989f117a27e5c05ee151ee7bd54c9db3c4190db4418043b
    source_path: tools/slash-commands.md
    workflow: 16
 ---

-命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
+命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 作为别名）。

-当对话或话题绑定到 ACP 会话时，普通的后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该表面启用了命令处理，`/status` 和 `/unfocus` 就保持本地处理。
+当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器；只要该界面启用了命令处理，`/status` 和 `/unfocus` 也会保持本地处理。

 有两个相关系统：

@ -28,15 +28,15 @@ x-i18n:
    `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。

    - 指令会在模型看到消息前从消息中剥离。
-    - 在普通聊天消息中（不是仅含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
-    - 在仅含指令的消息中（消息只包含指令），它们会持久化到会话并回复确认。
-    - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被视为纯文本。
+    - 在普通聊天消息中（不是纯指令），它们会被当作“内联提示”，并且**不会**持久化会话设置。
+    - 在纯指令消息中（消息只包含指令），它们会持久化到会话，并回复确认消息。
+    - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作纯文本处理。

  </Accordion>
  <Accordion title="Inline shortcuts">
-    仅限允许列表/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
+    仅限允许列表中/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。

-    它们会立即运行，在模型看到消息前被剥离，剩余文本继续走正常流程。
+    它们会立即运行，在模型看到消息前被剥离，并且剩余文本会继续进入正常流程。

  </Accordion>
 </AccordionGroup>
@ -69,28 +69,28 @@ x-i18n:
 ```

 <ParamField path="commands.text" type="boolean" default="true">
-  启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将此项设置为 `false`，文本命令仍然可用。
+  启用在聊天消息中解析 `/...`。在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将此项设为 `false`，文本命令仍会工作。
 </ParamField>
 <ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
-  注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
+  注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
 </ParamField>
 <ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
-  在支持时原生注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
+  在支持时以原生方式注册 **skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
 </ParamField>
 <ParamField path="commands.bash" type="boolean" default="false">
-  启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
+  启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
 </ParamField>
 <ParamField path="commands.bashForegroundMs" type="number" default="2000">
-  控制 bash 在切换到后台模式之前等待多久（`0` 表示立即转入后台）。
+  控制 bash 在切换到后台模式前等待多久（`0` 表示立即进入后台）。
 </ParamField>
 <ParamField path="commands.config" type="boolean" default="false">
  启用 `/config`（读取/写入 `openclaw.json`）。
 </ParamField>
 <ParamField path="commands.mcp" type="boolean" default="false">
-  启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
+  启用 `/mcp`（读取/写入 OpenClaw 管理的、位于 `mcp.servers` 下的 MCP 配置）。
 </ParamField>
 <ParamField path="commands.plugins" type="boolean" default="false">
-  启用 `/plugins`（插件发现/Status，以及安装 + 启用/停用控制）。
+  启用 `/plugins`（插件发现/Status 以及安装 + 启用/禁用控制）。
 </ParamField>
 <ParamField path="commands.debug" type="boolean" default="false">
  启用 `/debug`（仅运行时覆盖）。
@ -99,111 +99,113 @@ x-i18n:
  启用 `/restart` 以及 Gateway 网关重启工具操作。
 </ParamField>
 <ParamField path="commands.ownerAllowFrom" type="string[]">
-  为仅所有者命令/工具表面设置显式所有者允许列表。独立于 `commands.allowFrom`。
+  为仅所有者命令/工具界面设置显式所有者允许列表。这是可批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。
 </ParamField>
 <ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
-  按渠道设置：使仅所有者命令在该表面运行时要求具备**所有者身份**。当为 `true` 时，发送者必须匹配一个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上失败关闭。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表门控，请保持此项关闭。
+  按渠道设置：让仅所有者命令需要**所有者身份**才能在该界面运行。当为 `true` 时，发送者必须匹配某个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足条件 — 仅所有者命令会在该渠道上默认失败关闭。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令允许列表来门控，请保持此项关闭。
 </ParamField>
 <ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
  控制所有者 ID 在系统提示词中的显示方式。
 </ParamField>
 <ParamField path="commands.ownerDisplaySecret" type="string">
-  可选设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
+  可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
 </ParamField>
 <ParamField path="commands.allowFrom" type="object">
-  用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 表示全局默认值；提供商特定键会覆盖它。
+  用于命令授权的按提供商允许列表。配置后，它就是命令和指令的唯一授权来源（会忽略渠道允许列表/配对以及 `commands.useAccessGroups`）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
 </ParamField>
 <ParamField path="commands.useAccessGroups" type="boolean" default="true">
-  当未设置 `commands.allowFrom` 时，强制执行命令的允许列表/策略。
+  在未设置 `commands.allowFrom` 时，为命令强制执行允许列表/策略。
 </ParamField>

 ## 命令列表

 当前事实来源：

- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 生成的停靠命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件的 `registerCommand()` 调用
- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面以及已安装/启用的插件
+- 核心内置项来自 `src/auto-reply/commands-registry.shared.ts`
+- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
+- 插件命令来自插件 `registerCommand()` 调用
+- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的插件

 ### 核心内置命令

 <AccordionGroup>
  <Accordion title="Sessions and runs">
-    - `/new [model]` 启动一个新会话；`/reset` 是重置别名。
-    - `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 ID，并在原位重新运行启动/系统提示加载。
+    - `/new [model]` 启动新会话；`/reset` 是重置别名。
+    - `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 ID，并在原位置重新运行启动/系统提示词加载。
    - `/compact [instructions]` 压缩会话上下文。参见 [压缩](/zh-CN/concepts/compaction)。
    - `/stop` 中止当前运行。
-    - `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
+    - `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期。
    - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
-    - `/export-trajectory [path]` 为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。别名：`/trajectory`。
+    - `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示词、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。

  </Accordion>
  <Accordion title="Model and run controls">
-    - `/think <level>` 设置思考级别。选项来自活动模型的提供商配置档案；常见级别为 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在受支持处可用。别名：`/thinking`、`/t`。
+    - `/think <level>` 设置思考级别。选项来自活动模型的提供商配置；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在支持处可用。别名：`/thinking`、`/t`。
    - `/verbose on|off|full` 切换详细输出。别名：`/v`。
-    - `/trace on|off` 为当前会话切换插件跟踪输出。
+    - `/trace on|off` 切换当前会话的插件 trace 输出。
    - `/fast [status|on|off]` 显示或设置快速模式。
    - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
    - `/elevated [on|off|ask|full]` 切换提权模式。别名：`/elev`。
    - `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
    - `/model [name|#|status]` 显示或设置模型。
-    - `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某个提供商的模型。
-    - `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 等选项。
+    - `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商或某个提供商的模型。
+    - `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`）以及 `debounce:2s cap:25 drop:summarize` 等选项。

  </Accordion>
  <Accordion title="Discovery and status">
    - `/help` 显示简短帮助摘要。
    - `/commands` 显示生成的命令目录。
-    - `/tools [compact|verbose]` 显示当前智能体现在可以使用的内容。
-    - `/status` 显示执行/运行时状态，包括 `Execution`/`Runtime` 标签，以及可用时的提供商使用量/配额。
+    - `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。
+    - `/status` 显示执行/运行时 Status，包括可用时的 `Execution`/`Runtime` 标签以及提供商使用量/配额。
+    - `/diagnostics [note]` 是用于 Gateway 网关错误和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求显式 exec 批准；不要用允许全部规则批准 diagnostics。批准后，它会发送一份可粘贴报告，其中包含本地包路径、manifest 摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一次批准还会向 OpenAI 服务器发送相关 Codex 反馈，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume <thread-id>` 命令。参见 [Diagnostics 导出](/zh-CN/gateway/diagnostics)。
    - `/crestodian <request>` 从所有者私信运行 Crestodian 设置和修复助手。
    - `/tasks` 列出当前会话的活动/最近后台任务。
-    - `/context [list|detail|json]` 说明上下文如何组装。
+    - `/context [list|detail|json]` 解释上下文如何组装。
    - `/whoami` 显示你的发送者 ID。别名：`/id`。
-    - `/usage off|tokens|full|cost` 控制每条响应的用量页脚，或打印本地成本摘要。
+    - `/usage off|tokens|full|cost` 控制每次响应的使用量页脚，或打印本地成本摘要。

  </Accordion>
  <Accordion title="Skills, allowlists, approvals">
-    - `/skill <name> [input]` 按名称运行一个 Skills。
+    - `/skill <name> [input]` 按名称运行 skill。
    - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
-    - `/approve <id> <decision>` 处理 exec 审批提示。
-    - `/btw <question>` 提出一个旁路问题，而不改变后续会话上下文。参见 [BTW](/zh-CN/tools/btw)。
+    - `/approve <id> <decision>` 解决 exec 批准提示。
+    - `/btw <question>` 提出旁支问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。

  </Accordion>
  <Accordion title="Subagents and ACP">
    - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
    - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
-    - `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到一个会话目标。
+    - `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。
    - `/unfocus` 移除当前绑定。
    - `/agents` 列出当前会话的线程绑定智能体。
    - `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
-    - `/steer <id|#> <message>` 向正在运行的子智能体发送引导消息。别名：`/tell`。
+    - `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。

  </Accordion>
-  <Accordion title="Owner-only writes and admin">
-    - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
-    - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
-    - `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入操作仅限所有者。需要 `commands.plugins: true`。
-    - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。
-    - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
-    - `/send on|off|inherit` 设置发送策略。仅限所有者。
+  <Accordion title="仅所有者写入和管理">
+    - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者。需要 `commands.config: true`。
+    - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者。需要 `commands.mcp: true`。
+    - `/plugins list|inspect|show|get|install|enable|disable` 检查或更改插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。
+    - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅所有者。需要 `commands.debug: true`。
+    - `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。
+    - `/send on|off|inherit` 设置发送策略。仅所有者。

  </Accordion>
-  <Accordion title="Voice, TTS, channel control">
+  <Accordion title="语音、TTS、渠道控制">
    - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。
    - `/activation mention|always` 设置群组激活模式。
    - `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
-    - `!poll [sessionId]` 检查后台 bash 作业。
-    - `!stop [sessionId]` 停止后台 bash 作业。
+    - `!poll [sessionId]` 检查后台 bash 任务。
+    - `!stop [sessionId]` 停止后台 bash 任务。

  </Accordion>
 </AccordionGroup>

-### 生成的停靠命令
+### 生成的 dock 命令

-停靠命令会将当前会话的回复路由切换到另一个已链接的
-渠道。有关设置、示例和故障排除，请参见[渠道停靠](/zh-CN/concepts/channel-docking)。
+Dock 命令会将当前会话的回复路由切换到另一个已关联的
+渠道。设置、
+示例和故障排除请参见[渠道停靠](/zh-CN/concepts/channel-docking)。

 Dock 命令由支持原生命令的渠道插件生成。当前内置集合：

@ -212,89 +214,89 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
 - `/dock-slack`（别名：`/dock_slack`）
 - `/dock-telegram`（别名：`/dock_telegram`）

-在直接聊天中使用 dock 命令，可以将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送到选定的渠道对端。
+在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留同一个会话上下文，但该会话后续回复会发送到所选的渠道对端。

-Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者没有关联到 Discord 对端，该命令会回复一条设置提示，而不是继续进入普通聊天。
+Dock 命令需要 `session.identityLinks`。源发送者和目标对端必须在同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天流程。

-Docking 只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道 allowlist，或将 transcript 历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或其他生成的 dock 命令再次切换路由。
+Docking 只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令可再次切换路由。

 ### 内置插件命令

-内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
+内置插件可以添加更多斜杠命令。此仓库当前的内置命令：

 - `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。
+- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。
 - `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
 - `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置的 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
- 仅 QQBot 可用的命令：
+- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
+- 仅 QQBot 的命令：
  - `/bot-ping`
  - `/bot-version`
  - `/bot-help`
  - `/bot-upgrade`
  - `/bot-logs`

-### 动态 Skills 命令
+### 动态 skill 命令

-用户可调用的 Skills 也会公开为斜杠命令：
+用户可调用的 skills 也会公开为斜杠命令：

- `/skill <name> [input]` 始终可作为通用入口点使用。
- 当 Skills/插件注册它们时，Skills 也可能显示为 `/prose` 这样的直接命令。
- 原生 Skills 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
+- `/skill <name> [input]` 始终作为通用入口点可用。
+- 当 skill/插件注册它们时，skills 也可能显示为 `/prose` 这样的直接命令。
+- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。

 <AccordionGroup>
  <Accordion title="参数和解析器说明">
-    - 命令接受命令和参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
+    - 命令可在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
    - `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
-    - 如需完整的提供商用量明细，请使用 `openclaw status --usage`。
+    - 如需完整的提供商用量细分，请使用 `openclaw status --usage`。
    - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
-    - 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
-    - `/usage` 控制每条回复的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志打印本地成本摘要。
-    - `/restart` 默认启用；设置 `commands.restart: false` 可将其禁用。
-    - `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包，或 `clawhub:<pkg>`。
-    - `/plugins enable|disable` 会更新插件配置，并可能提示需要重启。
+    - 在多账号渠道中，面向配置的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
+    - `/usage` 控制每次回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。
+    - `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
+    - `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:<pkg>`。
+    - `/plugins enable|disable` 会更新插件配置，并可能提示重启。

  </Accordion>
  <Accordion title="渠道特定行为">
-    - 仅 Discord 可用的原生命令：`/vc join|leave|status` 控制语音频道（不可作为文本使用）。`join` 需要一个 guild 和选定的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。
+    - 仅 Discord 原生命令：`/vc join|leave|status` 控制语音频道（不可作为文本使用）。`join` 需要一个服务器以及选中的语音/舞台频道。需要 `channels.discord.voice` 和原生命令。
    - Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
    - ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。

  </Accordion>
-  <Accordion title="详细 / 跟踪 / 快速 / reasoning 安全">
-    - `/verbose` 用于调试和获得额外可见性；正常使用时请保持**关闭**。
-    - `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通的 verbose 工具噪声关闭。
-    - `/fast on|off` 会持久化会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它并回退到配置默认值。
-    - `/fast` 与提供商相关：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
-    - 相关时仍会显示工具失败摘要，但详细失败文本只有在 `/verbose` 为 `on` 或 `full` 时才会包含。
-    - `/reasoning`、`/verbose` 和 `/trace` 在群组环境中存在风险：它们可能暴露你不想公开的内部 reasoning、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。
+  <Accordion title="Verbose / trace / fast / reasoning 安全性">
+    - `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。
+    - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具杂项输出关闭。
+    - `/fast on|off` 会持久化会话覆盖。使用 Sessions UI 的 `inherit` 选项清除它，并回退到配置默认值。
+    - `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公开 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
+    - 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
+    - `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能暴露你不打算公开的内部推理、工具输出或插件诊断。优先保持关闭，尤其是在群聊中。

  </Accordion>
  <Accordion title="模型切换">
    - `/model` 会立即持久化新的会话模型。
-    - 如果智能体处于空闲状态，下一次运行会立即使用它。
-    - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只在干净的重试点重启到新模型。
-    - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到之后的重试机会或下一次用户轮次。
-    - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式不同，也不会授予远程配置权限。
+    - 如果智能体空闲，下一次运行会立即使用它。
+    - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。
+    - 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到稍后的重试机会或下一次用户回合。
+    - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这与消息渠道救援模式分开，并且不会授予远程配置权限。

  </Accordion>
  <Accordion title="快速路径和内联快捷方式">
-    - **快速路径：** 来自 allowlisted 发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
-    - **群组提及门控：** 来自 allowlisted 发送者的纯命令消息会绕过提及要求。
-    - **内联快捷方式（仅限 allowlisted 发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。
+    - **快速路径：**来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
+    - **群组提及门控：**来自允许列表发送者的纯命令消息会绕过提及要求。
+    - **内联快捷方式（仅允许列表发送者）：**某些命令在嵌入普通消息时也可用，并会在模型看到剩余文本之前被剥离。
      - 示例：`hey /status` 会触发 Status 回复，剩余文本继续走普通流程。
-    - 当前支持：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
+    - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
    - 未授权的纯命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。

  </Accordion>
-  <Accordion title="Skills 命令和原生参数">
-    - **Skills 命令：** `user-invocable` Skills 会公开为斜杠命令。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
-      - `/skill <name> [input]` 按名称运行 Skills（当原生命令限制阻止为每个 Skills 创建命令时很有用）。
-      - 默认情况下，Skills 命令会作为普通请求转发给模型。
-      - Skills 可以选择声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性，无模型）。
+  <Accordion title="Skill 命令和原生参数">
+    - **Skill 命令：**`user-invocable` skills 会公开为斜杠命令。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
+      - `/skill <name> [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。
+      - 默认情况下，skill 命令会作为普通请求转发给模型。
+      - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。
      - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。
-    - **原生命令参数：** Discord 对动态选项使用自动补全（省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会跟随该会话的 `/model` 覆盖。
+    - **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会基于目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖。

  </Accordion>
 </AccordionGroup>
@ -303,25 +305,25 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访

 `/tools` 回答的是运行时问题，而不是配置问题：**此智能体现在在这个对话中可以使用什么**。

- 默认 `/tools` 很紧凑，并针对快速浏览优化。
- `/tools verbose` 会添加简短描述。
- 支持参数的原生命令表面会公开相同的模式切换：`compact|verbose`。
+- 默认 `/tools` 紧凑，并针对快速浏览优化。
+- `/tools verbose` 添加简短描述。
+- 支持参数的原生命令界面会公开同样的模式切换：`compact|verbose`。
 - 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
 - `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。

-对于 profile 和覆盖编辑，请使用 Control UI Tools 面板或配置/catalog 表面，而不是将 `/tools` 视为静态 catalog。
+如需编辑 profile 和覆盖，请使用 Control UI Tools 面板或配置/catalog 界面，而不是把 `/tools` 当作静态目录。

-## 用量表面（哪里显示什么）
+## 用量界面（哪里显示什么）

- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，仅剩余的百分比字段会在显示前反转，`model_remains` 响应会优先使用聊天模型条目和带模型标记的 plan 标签。
- **Token/cache 行**在 `/status` 中可以在实时会话快照稀疏时回退到最新 transcript 用量条目。现有非零实时值仍然优先，transcript 回退也可以恢复活动运行时模型标签，以及在存储总数缺失或更小时恢复更大的、面向 prompt 的总数。
- **执行与运行时：** `/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
- **每条回复的 token/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复）。
- `/model status` 关注的是**模型/凭证/端点**，不是用量。
+- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，`model_remains` 响应会优先使用聊天模型条目以及带模型标签的计划标签。
+- **Token/缓存行**在 `/status` 中可在实时会话快照稀疏时回退到最新转录用量条目。现有非零实时值仍然优先，转录回退也可以恢复活动运行时模型标签，以及当存储总数缺失或较小时恢复更大的面向提示的总数。
+- **执行 vs 运行时：**`/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的主体报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
+- **每次回复 token/成本**由 `/usage off|tokens|full` 控制（附加到普通回复）。
+- `/model status` 关注的是**模型/认证/端点**，不是用量。

 ## 模型选择（`/model`）

-`/model` 实现为一条 directive。
+`/model` 作为指令实现。

 示例：

@ -336,14 +338,14 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访

 说明：

- `/model` 和 `/model list` 会显示紧凑的编号选择器（模型族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉菜单以及 Submit 步骤的交互式选择器。
+- `/model` 和 `/model list` 显示紧凑的编号选择器（模型系列 + 可用提供商）。
+- 在 Discord 上，`/model` 和 `/models` 会打开交互式选择器，包含提供商和模型下拉框以及 Submit 步骤。
 - `/model <#>` 从该选择器中选择（并在可能时优先使用当前提供商）。
- `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如可用）。
+- `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。

 ## 调试覆盖

-`/debug` 允许你设置**仅运行时**配置覆盖（内存中，不写入磁盘）。仅 owner 可用。默认禁用；使用 `commands.debug: true` 启用。
+`/debug` 可让你设置**仅运行时**配置覆盖（内存中，而非磁盘）。仅限所有者使用。默认禁用；使用 `commands.debug: true` 启用。

 示例：

@ -359,9 +361,9 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访
 覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。
 </Note>

-## 插件 trace 输出
+## 插件跟踪输出

-`/trace` 允许你切换**会话范围的插件 trace/debug 行**，而无需开启完整 verbose 模式。
+`/trace` 可让你切换**会话作用域的插件跟踪/调试行**，而无需开启完整详细模式。

 示例：

@ -371,18 +373,18 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访
 /trace off
 ```

-说明：
+注意：

- 不带参数的 `/trace` 会显示当前会话 trace 状态。
- `/trace on` 为当前会话启用插件 trace 行。
- `/trace off` 再次禁用它们。
- 插件 trace 行可以显示在 `/status` 中，也可以在普通助手回复后作为后续诊断消息出现。
- `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时配置覆盖。
- `/trace` 不会替代 `/verbose`；普通 verbose 工具/Status 输出仍属于 `/verbose`。
+- 不带参数的 `/trace` 会显示当前会话的跟踪状态。
+- `/trace on` 会为当前会话启用插件跟踪行。
+- `/trace off` 会再次禁用它们。
+- 插件跟踪行可能出现在 `/status` 中，也可能在普通助手回复后作为后续诊断消息出现。
+- `/trace` 不会取代 `/debug`；`/debug` 仍用于管理仅运行时配置覆盖。
+- `/trace` 不会取代 `/verbose`；普通详细工具/Status 输出仍属于 `/verbose`。

 ## 配置更新

-`/config` 会写入你的磁盘配置（`openclaw.json`）。仅 owner 可用。默认禁用；使用 `commands.config: true` 启用。
+`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；使用 `commands.config: true` 启用。

 示例：

@ -400,7 +402,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访

 ## MCP 更新

-`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；通过 `commands.mcp: true` 启用。
+`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；使用 `commands.mcp: true` 启用。

 示例：

@ -412,12 +414,12 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访
 ```

 <Note>
-`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器会决定哪些传输协议实际可执行。
+`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。
 </Note>

 ## 插件更新

-`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。
+`/plugins` 可让操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。

 示例：

@ -430,28 +432,28 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访
 ```

 <Note>
- `/plugins list` 和 `/plugins show` 会针对当前工作区和磁盘上的配置执行真实的插件发现。
+- `/plugins list` 和 `/plugins show` 会基于当前工作区加磁盘配置执行真实的插件发现。
 - `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
- 启用/禁用更改后，请重启 Gateway 网关以应用这些更改。
+- 启用/禁用更改后，请重启 Gateway 网关以应用它们。

 </Note>

-## 界面说明
+## 接入面说明

 <AccordionGroup>
-  <Accordion title="每个界面的会话">
-    - **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。
-    - **原生命令** 使用隔离会话：
+  <Accordion title="Sessions per surface">
+    - **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。
+    - **原生命令**使用隔离会话：
      - Discord：`agent:<agentId>:discord:slash:<userId>`
      - Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
-      - Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定向到聊天会话）
-    - **`/stop`** 以活跃聊天会话为目标，因此它可以中止当前运行。
+      - Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位聊天会话）
+    - **`/stop`** 定位活跃聊天会话，以便它可以中止当前运行。

  </Accordion>
-  <Accordion title="Slack 细节">
-    仍然支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时 Block Kit 按钮发送。
+  <Accordion title="Slack specifics">
+    仍支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格命令。如果你启用 `commands.native`，必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。

-    Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
+    Slack 原生例外：注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 仍可在 Slack 消息中使用。

  </Accordion>
 </AccordionGroup>
@ -460,15 +462,15 @@ Docking 只会更改活动会话路由。它不会创建渠道账号、授予访

 `/btw` 是关于当前会话的快速**附带问题**。

-与普通聊天不同：
+不同于普通聊天：

 - 它使用当前会话作为背景上下文，
 - 它作为单独的**无工具**一次性调用运行，
- 它不会更改未来的会话上下文，
+- 它不会改变未来的会话上下文，
 - 它不会写入转录历史，
- 它会作为实时附带结果发送，而不是普通的助手消息。
+- 它会作为实时附带结果发送，而不是普通助手消息。

-当你希望在主任务继续进行时获得临时澄清，`/btw` 会很有用。
+当你想在主任务继续进行时临时澄清某个问题，`/btw` 很有用。

 示例：

--- a/docs/zh-CN/tools/trajectory.md
+++ b/docs/zh-CN/tools/trajectory.md
@ -2,32 +2,34 @@
 read_when:
    - 调试智能体为何以某种方式回答、失败或调用工具
    - 导出 OpenClaw 会话的支持包
-    - 排查提示词上下文、工具调用、运行时错误或用量元数据
+    - 调查提示词上下文、工具调用、运行时错误或用量元数据
    - 禁用或重新定位轨迹捕获
 summary: 导出已脱敏的轨迹包，用于调试 OpenClaw 智能体会话
 title: 轨迹包
 x-i18n:
-    generated_at: "2026-04-28T12:07:02Z"
+    generated_at: "2026-04-28T22:45:06Z"
    model: gpt-5.5
    provider: openai
-    source_hash: df51c82ee5609ce19480c5b7f6fe037acda0e4ce927d5a748c9685c1809689d9
+    source_hash: 8dad01b3662d5e75b7626eb7ed3c3ac2dce4e3a7db2ba5952d7086c721151d1f
    source_path: tools/trajectory.md
    workflow: 16
 ---

-轨迹捕获是 OpenClaw 的每会话飞行记录器。它会为每次智能体运行记录一条结构化时间线，然后 `/export-trajectory` 会将当前会话打包成已脱敏的支持包。
+轨迹捕获是 OpenClaw 的按会话飞行记录器。它会为每次智能体运行记录一条结构化时间线，然后 `/export-trajectory` 会将当前会话打包成经过脱敏的支持包。

 当你需要回答这类问题时使用它：

 - 发送给模型的提示词、系统提示词和工具是什么？
- 哪些转录消息和工具调用促成了这个回答？
- 这次运行是超时、中止、压缩，还是遇到了提供商错误？
- 哪个模型、插件、Skills 和运行时设置处于激活状态？
+- 哪些转录消息和工具调用导致了这个回答？
+- 这次运行是否超时、中止、压缩，或遇到了提供商错误？
+- 哪个模型、插件、Skills 和运行时设置处于启用状态？
 - 提供商返回了哪些用量和提示词缓存元数据？

+如果你要为实时 Gateway 网关问题提交范围较广的支持报告，请先使用 [`/diagnostics`](/zh-CN/gateway/diagnostics#chat-command)。诊断会收集经过清理的 Gateway 网关包，并且对于 OpenAI Codex harness 会话，还可以在获得批准后将 Codex 反馈发送到 OpenAI 服务器。当你明确需要详细的按会话提示词、工具和转录时间线时，请使用 `/export-trajectory`。
+
 ## 快速开始

-在当前会话中发送：
+在活动会话中发送：

 ```text
 /export-trajectory
@ -45,7 +47,7 @@ OpenClaw 会将包写入工作区下：
 .openclaw/trajectory-exports/openclaw-trajectory-<session>-<timestamp>/
 ```

-你可以选择一个相对输出目录名称：
+你可以选择一个相对输出目录名：

 ```text
 /export-trajectory bug-1234
@ -53,13 +55,21 @@ OpenClaw 会将包写入工作区下：

 自定义路径会在 `.openclaw/trajectory-exports/` 内解析。绝对路径和 `~` 路径会被拒绝。

+轨迹包可能包含提示词、模型消息、工具 schema、工具结果、运行时事件和本地路径。因此，聊天斜杠命令每次都会通过 exec 审批。当你确实要创建包时，只批准这一次导出；不要使用 allow-all。在群聊中，OpenClaw 会将审批提示和导出结果私下发送给所有者，而不是把轨迹详情发回共享房间。
+
+对于本地检查或支持工作流，你也可以直接运行已批准的命令路径：
+
+```bash
+openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
+```
+
 ## 访问权限

 轨迹导出是所有者命令。发送者必须通过该渠道的常规命令授权检查和所有者检查。

-## 记录内容
+## 会记录什么

-默认情况下，OpenClaw 智能体运行会启用轨迹捕获。
+对于 OpenClaw 智能体运行，轨迹捕获默认开启。

 运行时事件包括：

@ -72,7 +82,7 @@ OpenClaw 会将包写入工作区下：
 - `trace.artifacts`
 - `session.ended`

-转录事件也会从当前会话分支重建：
+转录事件也会从活动会话分支重建：

 - 用户消息
 - 助手消息
@ -82,7 +92,7 @@ OpenClaw 会将包写入工作区下：
 - 模型变更
 - 标签和自定义会话条目

-事件会按 JSON Lines 写入，并带有这个架构标记：
+事件会以 JSON Lines 写入，并带有这个 schema 标记：

 ```json
 {
@ -93,20 +103,20 @@ OpenClaw 会将包写入工作区下：

 ## 包文件

-导出的包可以包含：
+导出的包可能包含：

 | 文件                  | 内容                                                                                       |
 | --------------------- | ---------------------------------------------------------------------------------------------- |
-| `manifest.json`       | 包架构、源文件、事件计数和生成的文件列表                             |
+| `manifest.json`       | 包 schema、源文件、事件计数和生成的文件列表                             |
 | `events.jsonl`        | 有序的运行时和转录时间线                                                        |
-| `session-branch.json` | 已脱敏的当前转录分支和会话头                                           |
+| `session-branch.json` | 经过脱敏的活动转录分支和会话头                                           |
 | `metadata.json`       | OpenClaw 版本、操作系统/运行时、模型、配置快照、插件、Skills 和提示词元数据     |
 | `artifacts.json`      | 最终 Status、错误、用量、提示词缓存、压缩次数、助手文本和工具元数据 |
-| `prompts.json`        | 已提交的提示词和选定的提示词构建详情                                         |
+| `prompts.json`        | 已提交的提示词和所选的提示词构建详情                                         |
 | `system-prompt.txt`   | 捕获到的最新已编译系统提示词                                                   |
 | `tools.json`          | 捕获到的发送给模型的工具定义                                              |

-`manifest.json` 会列出该包中存在的文件。当会话未捕获对应的运行时数据时，某些文件会被省略。
+`manifest.json` 会列出该包中存在的文件。当会话没有捕获对应的运行时数据时，某些文件会被省略。

 ## 捕获位置

@ -122,34 +132,34 @@ OpenClaw 还会在会话旁边写入一个尽力而为的指针文件：
 <session>.trajectory-path.json
 ```

-设置 `OPENCLAW_TRAJECTORY_DIR` 可将运行时轨迹 sidecar 存储在专用目录中：
+设置 `OPENCLAW_TRAJECTORY_DIR`，可将运行时轨迹 sidecar 存储到专用目录中：

 ```bash
 export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories
 ```

-设置此变量后，OpenClaw 会在该目录中为每个会话 ID 写入一个 JSONL 文件。
+设置此变量后，OpenClaw 会在该目录中为每个会话 id 写入一个 JSONL 文件。

-当所属会话条目被会话磁盘预算修剪、封顶或驱逐时，会话维护会移除轨迹 sidecar。会话目录之外的运行时文件只有在指针目标仍能证明其属于该会话时才会被移除。
+当所属的会话条目被修剪、受上限限制或因会话磁盘预算而被逐出时，会话维护会移除轨迹 sidecar。会话目录之外的运行时文件只有在指针目标仍能证明其属于该会话时才会被移除。

 ## 禁用捕获

-在启动 OpenClaw 之前设置 `OPENCLAW_TRAJECTORY=0`：
+在启动 OpenClaw 前设置 `OPENCLAW_TRAJECTORY=0`：

 ```bash
 export OPENCLAW_TRAJECTORY=0
 ```

-这会禁用运行时轨迹捕获。`/export-trajectory` 仍然可以导出转录分支，但可能会缺少仅运行时文件，例如已编译上下文、提供商产物和提示词元数据。
+这会禁用运行时轨迹捕获。`/export-trajectory` 仍然可以导出转录分支，但可能缺少仅运行时文件，例如已编译上下文、提供商产物和提示词元数据。

-## 隐私与限制
+## 隐私和限制

-轨迹包是为支持和调试设计的，不适合公开发布。OpenClaw 会在写入导出文件前脱敏敏感值：
+轨迹包用于支持和调试，不适合公开发布。OpenClaw 会在写入导出文件前脱敏敏感值：

 - 凭证和已知类似密钥的载荷字段
- 图片数据
+- 图像数据
 - 本地状态路径
- 工作区路径，会替换为 `$WORKSPACE_DIR`
+- 工作区路径，替换为 `$WORKSPACE_DIR`
 - 检测到的主目录路径

 导出器还会限制输入大小：
@ -157,29 +167,29 @@ export OPENCLAW_TRAJECTORY=0
 - 运行时 sidecar 文件：50 MiB
 - 会话文件：50 MiB
 - 运行时事件：200,000
- 导出事件总数：250,000
+- 导出的事件总数：250,000
 - 单条运行时事件行超过 256 KiB 时会被截断

-在团队外共享包之前，请先检查包。脱敏是尽力而为，无法知道每个应用特定的密钥。
+在团队外共享包之前，请先审查包。脱敏是尽力而为的，无法知道每个应用特定的密钥。

 ## 故障排除

 如果导出没有运行时事件：

- 确认 OpenClaw 启动时未设置 `OPENCLAW_TRAJECTORY=0`
+- 确认 OpenClaw 启动时没有设置 `OPENCLAW_TRAJECTORY=0`
 - 检查 `OPENCLAW_TRAJECTORY_DIR` 是否指向可写目录
 - 在会话中再运行一条消息，然后重新导出
 - 检查 `manifest.json` 中的 `runtimeEventCount`

 如果命令拒绝输出路径：

- 使用类似 `bug-1234` 的相对名称
+- 使用像 `bug-1234` 这样的相对名称
 - 不要传入 `/tmp/...` 或 `~/...`
 - 将导出保留在 `.openclaw/trajectory-exports/` 内

-如果导出因大小错误而失败，说明会话或 sidecar 超出了导出安全限制。请启动新会话，或导出更小的复现。
+如果导出因大小错误而失败，说明会话或 sidecar 超出了导出安全限制。请启动新会话，或导出一个更小的复现。

-## 相关内容
+## 相关

 - [Diffs](/zh-CN/tools/diffs)
 - [会话管理](/zh-CN/concepts/session)