chore(i18n): refresh zh-CN translations

docs/zh-CN/gateway/protocol.md

@@ -2,29 +2,29 @@
 read_when:
     - 实现或更新 Gateway 网关 WS 客户端
     - 调试协议不匹配或连接失败
-    - 重新生成协议 schema / 模型
+    - 重新生成协议 schema/模型
 summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制
 title: Gateway 网关协议
 x-i18n:
-    generated_at: "2026-04-24T18:08:44Z"
+    generated_at: "2026-04-25T22:27:13Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 03f729a1ee755cdd8a8dd1fef5ae1cb0111ec16818bd9080acd2ab0ca2dbc677
+    source_hash: a2411ebd50a883028e2d8e88a4a79e4c1350cefd37a12f293de9686e3bc067ea
     source_path: gateway/protocol.md
     workflow: 15
 ---
 
-Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
+Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输层**。所有客户端（CLI、web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
 
 ## 传输
 
 - WebSocket，带有 JSON 负载的文本帧。
 - 第一帧**必须**是一个 `connect` 请求。
-- 连接前帧大小上限为 64 KiB。成功握手后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断时，过大的入站帧和缓慢的出站缓冲区会先发出 `payload.large` 事件，然后 Gateway 网关才会关闭连接或丢弃受影响的帧。这些事件会保留大小、限制、界面和安全原因码。它们不会保留消息正文、附件内容、原始帧正文、令牌、cookies 或密钥值。
+- 连接前帧的上限为 64 KiB。握手成功后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断后，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭连接或丢弃受影响帧之前发出 `payload.large` 事件。这些事件会保留大小、限制、表面以及安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、Cookie 或秘密值。
 
 ## 握手（connect）
 
-Gateway 网关 → 客户端（连接前挑战）：
+Gateway 网关 → 客户端（连接前质询）：
 
 ```json
 {
@@ -91,9 +91,9 @@ Gateway 网关 → 客户端：
 }
 ```
 
-`server`、`features`、`snapshot` 和 `policy` 都是 schema 中的必填项（`src/gateway/protocol/schema/frames.ts`）。`canvasHostUrl` 是可选项。`auth` 会在可用时报告协商后的角色 / 作用域，并在 Gateway 网关签发设备令牌时包含 `deviceToken`。
+`server`、`features`、`snapshot` 和 `policy` 都是 schema（`src/gateway/protocol/schema/frames.ts`）要求的必填项。`canvasHostUrl` 是可选项。`auth` 会在可用时报告协商后的角色/作用域，并在 Gateway 网关签发设备令牌时包含 `deviceToken`。
 
-当未签发设备令牌时，`hello-ok.auth` 仍可以报告协商后的权限：
+未签发设备令牌时，`hello-ok.auth` 仍然可以报告协商后的权限：
 
 ```json
 {
@@ -104,7 +104,9 @@ Gateway 网关 → 客户端：
 }
 ```
 
-当签发了设备令牌时，`hello-ok` 还会包含：
+受信任的同进程后端客户端（`client.id: "gateway-client"`、`client.mode: "backend"`）在使用共享 Gateway 网关 token/password 通过直接 loopback 连接进行身份验证时，可以省略 `device`。此路径保留用于内部控制平面 RPC，可避免过期的 CLI/设备配对基线阻碍本地后端工作，例如子智能体会话更新。远程客户端、浏览器来源客户端、节点客户端以及显式设备令牌/设备身份客户端仍然使用常规配对和作用域升级检查。
+
+签发设备令牌时，`hello-ok` 还会包含：
 
 ```json
 {
@@ -116,7 +118,7 @@ Gateway 网关 → 客户端：
 }
 ```
 
-在受信任的 bootstrap 交接过程中，`hello-ok.auth` 还可能在 `deviceTokens` 中包含额外的有界角色条目：
+在受信任的引导交接期间，`hello-ok.auth` 还可能在 `deviceTokens` 中包含额外的有界角色条目：
 
 ```json
 {
@@ -135,7 +137,7 @@ Gateway 网关 → 客户端：
 }
 ```
 
-对于内置的 node/operator bootstrap 流程，主节点令牌保持为 `scopes: []`，而任何交接的 operator 令牌都保持受限于 bootstrap operator allowlist（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。Bootstrap 作用域检查仍然保持角色前缀：operator 条目只满足 operator 请求，而非 operator 角色仍然需要其自身角色前缀下的作用域。
+对于内置的 node/operator 引导流程，主 node 令牌保持 `scopes: []`，而任何交接的 operator 令牌都保持受限于引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。引导作用域检查保持按角色前缀区分：operator 条目只满足 operator 请求，而非 operator 角色仍然需要其自身角色前缀下的作用域。
 
 ### 节点示例
 
@@ -178,7 +180,7 @@ Gateway 网关 → 客户端：
 - **响应**：`{type:"res", id, ok, payload|error}`
 - **事件**：`{type:"event", event, payload, seq?, stateVersion?}`
 
-有副作用的方法需要 **idempotency keys**（见 schema）。
+具有副作用的方法需要 **idempotency keys**（参见 schema）。
 
 ## 角色 + 作用域
 
@@ -200,104 +202,104 @@ Gateway 网关 → 客户端：
 
 带有 `includeSecrets: true` 的 `talk.config` 需要 `operator.talk.secrets`（或 `operator.admin`）。
 
-由插件注册的 Gateway 网关 RPC 方法可以请求其自己的 operator 作用域，但保留的核心管理前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。
+由插件注册的 Gateway 网关 RPC 方法可以请求它们自己的 operator 作用域，但保留的核心管理前缀（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终解析为 `operator.admin`。
 
-方法作用域只是第一道关卡。某些通过 `chat.send` 到达的斜杠命令还会额外应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。
+方法作用域只是第一道关卡。某些通过 `chat.send` 到达的斜杠命令会在此基础上应用更严格的命令级检查。例如，持久化的 `/config set` 和 `/config unset` 写入需要 `operator.admin`。
 
-`node.pair.approve` 也在基础方法作用域之上额外有一个批准时作用域检查：
+`node.pair.approve` 在基础方法作用域之上还有额外的审批时作用域检查：
 
 - 无命令请求：`operator.pairing`
-- 带非 exec 节点命令的请求：`operator.pairing` + `operator.write`
+- 带有非 exec 节点命令的请求：`operator.pairing` + `operator.write`
 - 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求：
   `operator.pairing` + `operator.admin`
 
-### caps/commands/permissions（node）
+### Caps/commands/permissions（node）
 
 节点在连接时声明能力声明：
 
-- `caps`：高级能力类别。
-- `commands`：用于调用的命令 allowlist。
+- `caps`：高层能力类别。
+- `commands`：用于 invoke 的命令允许列表。
 - `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
 
-Gateway 网关将这些视为**声明**，并在服务器端强制执行 allowlist。
+Gateway 网关将这些视为**声明**，并执行服务端允许列表。
 
 ## 在线状态
 
 - `system-presence` 返回按设备身份键控的条目。
-- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，这样 UI 即使在同一设备同时以 **operator** 和 **node** 身份连接时，也能显示为单行。
+- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此 UI 即使在设备同时以 **operator** 和 **node** 身份连接时，也能为其显示单独一行。
 
-## 广播事件作用域
+## 广播事件作用域限制
 
-服务器推送的 WebSocket 广播事件受作用域控制，因此仅配对作用域或仅节点会话不会被动接收会话内容。
+服务端推送的 WebSocket 广播事件受作用域门控，因此仅具备配对作用域或仅节点的会话不会被动接收会话内容。
 
 - **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。
-- **插件定义的 `plugin.*` 广播** 会根据插件注册方式受限于 `operator.write` 或 `operator.admin`。
-- **状态和传输事件**（`heartbeat`、`presence`、`tick`、连接 / 断开生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状态。
-- **未知的广播事件族** 默认受作用域控制（默认拒绝），除非已注册的处理器显式放宽它们。
+- **插件定义的 `plugin.*` 广播** 会根据插件注册方式，门控到 `operator.write` 或 `operator.admin`。
+- **Status 和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状态。
+- **未知广播事件族** 默认受作用域门控（默认关闭，fail-closed），除非注册的处理程序明确放宽它们。
 
-每个客户端连接都维护自己的按客户端递增序列号，因此即使不同客户端看到的是经过不同作用域过滤后的事件流子集，广播在该 socket 上仍能保持单调有序。
+每个客户端连接都保留自己的每客户端序列号，因此即使不同客户端看到的事件流子集因作用域过滤而不同，广播在该 socket 上仍保持单调顺序。
 
 ## 常见 RPC 方法族
 
-公共 WS 表面比上面的握手 / 认证示例更广。这不是生成的导出清单 —— `hello-ok.features.methods` 是从 `src/gateway/server-methods-list.ts` 加载的保守发现列表，并结合已加载的插件 / 渠道方法导出构建而成。请将其视为功能发现，而不是 `src/gateway/server-methods/*.ts` 的完整枚举。
+公共 WS 表面比上面的握手/认证示例更广。这不是生成的导出——`hello-ok.features.methods` 是一个保守的发现列表，基于 `src/gateway/server-methods-list.ts` 加上已加载插件/渠道方法导出构建。应将其视为功能发现，而不是对 `src/gateway/server-methods/*.ts` 的完整枚举。
 
 <AccordionGroup>
-  <Accordion title="系统与身份">
-    - `health` 返回缓存的或刚探测到的 Gateway 网关健康状态快照。
-    - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它会保留操作元数据，例如事件名称、计数、字节大小、内存读数、队列 / 会话状态、渠道 / 插件名称和会话 id。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookies 或密钥值。需要 `operator.read` 作用域。
-    - `status` 返回类似 `/status` 的 Gateway 网关摘要；敏感字段仅对具有 admin 作用域的 operator 客户端可见。
-    - `gateway.identity.get` 返回 relay 和 pairing 流程使用的 Gateway 网关设备身份。
+  <Accordion title="系统和身份">
+    - `health` 返回缓存的或新探测的 Gateway 网关健康快照。
+    - `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它会保留操作元数据，例如事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称以及会话 id。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie 或秘密值。需要 operator.read 作用域。
+    - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅包含在具有 admin 作用域的 operator 客户端中。
+    - `gateway.identity.get` 返回用于 relay 和配对流程的 Gateway 网关设备身份。
     - `system-presence` 返回当前已连接 operator/node 设备的在线状态快照。
-    - `system-event` 追加一个系统事件，并可更新 / 广播在线状态上下文。
-    - `last-heartbeat` 返回最新持久化的 heartbeat 事件。
-    - `set-heartbeats` 切换 Gateway 网关上的 heartbeat 处理。
+    - `system-event` 追加一个系统事件，并且可以更新/广播在线状态上下文。
+    - `last-heartbeat` 返回最新持久化的心跳事件。
+    - `set-heartbeats` 切换 Gateway 网关上的心跳处理。
   </Accordion>
 
-  <Accordion title="模型与使用情况">
+  <Accordion title="模型和用量">
     - `models.list` 返回运行时允许的模型目录。
-    - `usage.status` 返回提供商用量窗口 / 剩余额度摘要。
-    - `usage.cost` 返回某个日期范围内聚合后的成本使用摘要。
+    - `usage.status` 返回提供商用量窗口/剩余额度摘要。
+    - `usage.cost` 返回某个日期范围的聚合成本用量摘要。
     - `doctor.memory.status` 返回活动默认智能体工作区的向量内存 / embedding 就绪状态。
-    - `sessions.usage` 返回按会话划分的使用摘要。
-    - `sessions.usage.timeseries` 返回单个会话的时间序列使用情况。
-    - `sessions.usage.logs` 返回单个会话的使用日志条目。
+    - `sessions.usage` 返回每个会话的用量摘要。
+    - `sessions.usage.timeseries` 返回单个会话的时序用量。
+    - `sessions.usage.logs` 返回单个会话的用量日志条目。
   </Accordion>
 
-  <Accordion title="渠道与登录辅助">
-    - `channels.status` 返回内置 + 内置插件渠道 / 插件状态摘要。
-    - `channels.logout` 在某个渠道支持登出时，对指定渠道 / 账号执行登出。
-    - `web.login.start` 为当前支持二维码的 web 渠道提供商启动二维码 / web 登录流程。
-    - `web.login.wait` 等待该二维码 / web 登录流程完成，并在成功时启动渠道。
-    - `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。
+  <Accordion title="渠道和登录辅助">
+    - `channels.status` 返回内置 + 内置打包渠道/插件的 Status 摘要。
+    - `channels.logout` 在渠道支持登出的情况下，登出特定渠道/账户。
+    - `web.login.start` 为当前支持 QR/web 登录的 web 渠道提供商启动一个 QR/web 登录流程。
+    - `web.login.wait` 等待该 QR/web 登录流程完成，并在成功后启动渠道。
+    - `push.test` 向已注册的 iOS 节点发送一个测试 APNs 推送。
     - `voicewake.get` 返回已存储的唤醒词触发器。
-    - `voicewake.set` 更新唤醒词触发器并广播该变更。
+    - `voicewake.set` 更新唤醒词触发器并广播更改。
   </Accordion>
 
-  <Accordion title="消息与日志">
-    - `send` 是直接的出站投递 RPC，用于在聊天运行器之外按渠道 / 账号 / 线程目标发送消息。
-    - `logs.tail` 返回已配置 Gateway 网关文件日志的尾部内容，支持 cursor/limit 和最大字节数控制。
+  <Accordion title="消息和日志">
+    - `send` 是聊天运行器之外、针对渠道/账户/线程目标发送的直接出站投递 RPC。
+    - `logs.tail` 返回已配置的 Gateway 网关文件日志尾部，支持 cursor/limit 和最大字节控制。
   </Accordion>
 
-  <Accordion title="Talk 与 TTS">
-    - `talk.config` 返回生效的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
-    - `talk.mode` 为 WebChat / Control UI 客户端设置 / 广播当前 Talk 模式状态。
-    - `talk.speak` 通过活动中的 Talk 语音提供商合成语音。
-    - `tts.status` 返回 TTS 启用状态、活动提供商、回退提供商和提供商配置状态。
+  <Accordion title="Talk 和 TTS">
+    - `talk.config` 返回有效的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
+    - `talk.mode` 为 WebChat/Control UI 客户端设置/广播当前 Talk 模式状态。
+    - `talk.speak` 通过活动的 Talk speech 提供商合成语音。
+    - `tts.status` 返回 TTS 启用状态、活动提供商、后备提供商以及提供商配置状态。
     - `tts.providers` 返回可见的 TTS 提供商清单。
     - `tts.enable` 和 `tts.disable` 切换 TTS 偏好状态。
     - `tts.setProvider` 更新首选 TTS 提供商。
-    - `tts.convert` 执行一次性文本转语音转换。
+    - `tts.convert` 运行一次性文本转语音转换。
   </Accordion>
 
-  <Accordion title="密钥、配置、更新和向导">
-    - `secrets.reload` 重新解析活动的 SecretRefs，并且仅在完全成功时替换运行时密钥状态。
-    - `secrets.resolve` 为特定命令 / 目标集解析命令目标密钥分配。
+  <Accordion title="Secrets、配置、更新和向导">
+    - `secrets.reload` 重新解析活动 SecretRefs，并且仅在完全成功时替换运行时秘密状态。
+    - `secrets.resolve` 为特定命令/目标集合解析面向命令目标的秘密分配。
     - `config.get` 返回当前配置快照和哈希值。
     - `config.set` 写入经过验证的配置负载。
     - `config.patch` 合并部分配置更新。
     - `config.apply` 验证并替换完整配置负载。
-    - `config.schema` 返回由 Control UI 和 CLI 工具使用的实时配置 schema 负载：schema、`uiHints`、版本和生成元数据，包括运行时可加载时的插件 + 渠道 schema 元数据。该 schema 包含从 UI 使用的相同标签和帮助文本派生出的字段 `title` / `description` 元数据，包括嵌套对象、通配符、数组项，以及在存在匹配字段文档时的 `anyOf` / `oneOf` / `allOf` 组合分支。
-    - `config.schema.lookup` 返回单个配置路径的路径范围查询负载：规范化路径、浅层 schema 节点、匹配的 hint + `hintPath`，以及供 UI/CLI 深入查看的直接子项摘要。查询 schema 节点保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数值 / 字符串 / 数组 / 对象边界，以及如 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 之类的标记）。子项摘要公开 `key`、规范化的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。
+    - `config.schema` 返回 Control UI 和 CLI 工具使用的实时配置 schema 负载：schema、`uiHints`、版本和生成元数据，包括在运行时可以加载时的插件 + 渠道 schema 元数据。该 schema 包含字段 `title` / `description` 元数据，来源于 UI 使用的相同标签和帮助文本；在存在匹配字段文档时，也包括嵌套对象、通配符、数组项以及 `anyOf` / `oneOf` / `allOf` 组合分支。
+    - `config.schema.lookup` 为单个配置路径返回路径范围查找负载：规范化路径、浅层 schema 节点、匹配的提示 + `hintPath`，以及供 UI/CLI 逐层钻取的直接子项摘要。查找 schema 节点保留面向用户的文档和常见验证字段（`title`、`description`、`type`、`enum`、`const`、`format`、`pattern`、数值/字符串/数组/对象边界，以及 `additionalProperties`、`deprecated`、`readOnly`、`writeOnly` 等标记）。子项摘要公开 `key`、规范化后的 `path`、`type`、`required`、`hasChildren`，以及匹配的 `hint` / `hintPath`。
     - `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。
     - `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 暴露新手引导向导。
   </Accordion>
@@ -305,56 +307,56 @@ Gateway 网关将这些视为**声明**，并在服务器端强制执行 allowli
   <Accordion title="智能体和工作区辅助">
     - `agents.list` 返回已配置的智能体条目。
     - `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区连接。
-    - `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为某个智能体公开的 bootstrap 工作区文件。
-    - `agent.identity.get` 返回某个智能体或会话的生效助手身份。
-    - `agent.wait` 等待一次运行结束，并在可用时返回终态快照。
+    - `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为某个智能体公开的引导工作区文件。
+    - `agent.identity.get` 返回某个智能体或会话的有效助手身份。
+    - `agent.wait` 等待某次运行完成，并在可用时返回终态快照。
   </Accordion>
 
   <Accordion title="会话控制">
     - `sessions.list` 返回当前会话索引。
     - `sessions.subscribe` 和 `sessions.unsubscribe` 为当前 WS 客户端切换会话变更事件订阅。
-    - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为单个会话切换 transcript / 消息事件订阅。
+    - `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为单个会话切换 transcript/消息事件订阅。
     - `sessions.preview` 返回特定会话键的有界 transcript 预览。
-    - `sessions.resolve` 解析或规范化一个会话目标。
+    - `sessions.resolve` 解析或规范化会话目标。
     - `sessions.create` 创建新的会话条目。
     - `sessions.send` 向现有会话发送消息。
     - `sessions.steer` 是活动会话的中断并引导变体。
     - `sessions.abort` 中止某个会话的活动工作。
-    - `sessions.patch` 更新会话元数据 / 覆盖项。
+    - `sessions.patch` 更新会话元数据/覆盖项。
     - `sessions.reset`、`sessions.delete` 和 `sessions.compact` 执行会话维护。
     - `sessions.get` 返回完整存储的会话行。
-    - 聊天执行仍使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。`chat.history` 会为 UI 客户端执行显示规范化：从可见文本中移除内联指令标签，去除纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）和泄漏的 ASCII / 全角模型控制标记，省略纯静默标记的助手行，例如精确的 `NO_REPLY` / `no_reply`，并且过大的行可被替换为占位符。
+    - 聊天执行仍然使用 `chat.history`、`chat.send`、`chat.abort` 和 `chat.inject`。对 UI 客户端来说，`chat.history` 已做显示规范化：可见文本中的内联指令标签会被剥离，纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）和泄露的 ASCII/全角模型控制令牌会被剥离，纯静默令牌的助手行（例如精确的 `NO_REPLY` / `no_reply`）会被省略，过大的行可能会被占位符替换。
   </Accordion>
 
   <Accordion title="设备配对和设备令牌">
-    - `device.pair.list` 返回待处理和已批准的已配对设备。
+    - `device.pair.list` 返回待处理和已批准的配对设备。
     - `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。
-    - `device.token.rotate` 在已批准的角色和作用域边界内轮换已配对设备令牌。
-    - `device.token.revoke` 吊销已配对设备令牌。
+    - `device.token.rotate` 在已批准的角色和作用域边界内轮换某个配对设备令牌。
+    - `device.token.revoke` 撤销某个配对设备令牌。
   </Accordion>
 
   <Accordion title="节点配对、调用和待处理工作">
-    - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject` 和 `node.pair.verify` 涵盖节点配对和 bootstrap 验证。
-    - `node.list` 和 `node.describe` 返回已知 / 已连接的节点状态。
-    - `node.rename` 更新已配对节点标签。
+    - `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject` 和 `node.pair.verify` 涵盖节点配对和引导验证。
+    - `node.list` 和 `node.describe` 返回已知/已连接节点状态。
+    - `node.rename` 更新某个已配对节点标签。
     - `node.invoke` 将命令转发到已连接节点。
-    - `node.invoke.result` 返回一次调用请求的结果。
-    - `node.event` 将节点发起的事件携带回 Gateway 网关。
+    - `node.invoke.result` 返回某个 invoke 请求的结果。
+    - `node.event` 将节点来源事件携回 Gateway 网关。
     - `node.canvas.capability.refresh` 刷新带作用域的 canvas 能力令牌。
     - `node.pending.pull` 和 `node.pending.ack` 是已连接节点队列 API。
-    - `node.pending.enqueue` 和 `node.pending.drain` 管理离线 / 断开节点的持久待处理工作。
+    - `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接节点的持久待处理工作。
   </Accordion>
 
-  <Accordion title="批准方法族">
-    - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 批准请求以及待处理批准的查询 / 重放。
-    - `exec.approval.waitDecision` 等待一个待处理 exec 批准，并返回最终决定（或在超时时返回 `null`）。
-    - `exec.approvals.get` 和 `exec.approvals.set` 管理 Gateway 网关 exec 批准策略快照。
-    - `exec.approvals.node.get` 和 `exec.approvals.node.set` 通过节点 relay 命令管理节点本地 exec 批准策略。
-    - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的批准流程。
+  <Accordion title="审批方法族">
+    - `exec.approval.request`、`exec.approval.get`、`exec.approval.list` 和 `exec.approval.resolve` 涵盖一次性 exec 审批请求，以及待处理审批的查找/重放。
+    - `exec.approval.waitDecision` 等待一个待处理 exec 审批并返回最终决定（或在超时时返回 `null`）。
+    - `exec.approvals.get` 和 `exec.approvals.set` 管理 Gateway 网关 exec 审批策略快照。
+    - `exec.approvals.node.get` 和 `exec.approvals.node.set` 通过节点 relay 命令管理节点本地 exec 审批策略。
+    - `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的审批流程。
   </Accordion>
 
   <Accordion title="自动化、Skills 和工具">
-    - 自动化：`wake` 安排立即或下一个 heartbeat 注入唤醒文本；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划任务。
+    - 自动化：`wake` 安排立即或下一次心跳时注入唤醒文本；`cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs` 管理计划工作。
     - Skills 和工具：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`。
   </Accordion>
 </AccordionGroup>
@@ -362,176 +364,173 @@ Gateway 网关将这些视为**声明**，并在服务器端强制执行 allowli
 ### 常见事件族
 
 - `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅 transcript 的聊天事件。
-- `session.message` 和 `session.tool`：已订阅会话的 transcript / 事件流更新。
-- `sessions.changed`：会话索引或元数据已更改。
+- `session.message` 和 `session.tool`：已订阅会话的 transcript/事件流更新。
+- `sessions.changed`：会话索引或元数据已变更。
 - `presence`：系统在线状态快照更新。
-- `tick`：周期性 keepalive / 存活事件。
-- `health`：Gateway 网关健康状态快照更新。
-- `heartbeat`：heartbeat 事件流更新。
-- `cron`：cron 运行 / 作业变更事件。
+- `tick`：周期性 keepalive / 存活性事件。
+- `health`：Gateway 网关健康快照更新。
+- `heartbeat`：心跳事件流更新。
+- `cron`：cron 运行/任务变更事件。
 - `shutdown`：Gateway 网关关闭通知。
 - `node.pair.requested` / `node.pair.resolved`：节点配对生命周期。
-- `node.invoke.request`：节点调用请求广播。
-- `device.pair.requested` / `device.pair.resolved`：已配对设备生命周期。
-- `voicewake.changed`：唤醒词触发器配置已更改。
-- `exec.approval.requested` / `exec.approval.resolved`：exec 批准生命周期。
-- `plugin.approval.requested` / `plugin.approval.resolved`：插件批准生命周期。
+- `node.invoke.request`：节点 invoke 请求广播。
+- `device.pair.requested` / `device.pair.resolved`：配对设备生命周期。
+- `voicewake.changed`：唤醒词触发器配置已变更。
+- `exec.approval.requested` / `exec.approval.resolved`：exec 审批生命周期。
+- `plugin.approval.requested` / `plugin.approval.resolved`：插件审批生命周期。
 
 ### 节点辅助方法
 
-- 节点可以调用 `skills.bins` 以获取当前 Skills 可执行文件列表，用于自动允许检查。
+- 节点可以调用 `skills.bins` 以获取当前技能可执行文件列表，用于自动允许检查。
 
 ### operator 辅助方法
 
-- operator 可以调用 `commands.list`（`operator.read`）来获取某个智能体的运行时命令清单。
-  - `agentId` 是可选的；省略它即可读取默认智能体工作区。
-  - `scope` 控制主 `name` 指向哪个表面：
-    - `text` 返回不带前导 `/` 的主文本命令标记
-    - `native` 和默认的 `both` 路径会在可用时返回 provider 感知的原生命令名称
+- operator 可以调用 `commands.list`（`operator.read`）以获取某个智能体的运行时命令清单。
+  - `agentId` 是可选项；省略时读取默认智能体工作区。
+  - `scope` 控制主 `name` 目标对应哪个表面：
+    - `text` 返回不带前导 `/` 的主文本命令令牌
+    - `native` 和默认的 `both` 路径会在可用时返回具备 provider 感知的原生命名
   - `textAliases` 携带精确的斜杠别名，例如 `/model` 和 `/m`。
-  - `nativeName` 在存在时携带 provider 感知的原生命令名称。
-  - `provider` 是可选的，仅影响原生命名以及原生插件命令可用性。
-  - `includeArgs=false` 会从响应中省略序列化的参数元数据。
-- operator 可以调用 `tools.catalog`（`operator.read`）来获取某个智能体的运行时工具目录。响应包含分组工具和来源元数据：
+  - `nativeName` 在存在时携带具备 provider 感知的原生命令名。
+  - `provider` 是可选项，只影响原生命名以及原生插件命令可用性。
+  - `includeArgs=false` 会从响应中省略序列化参数元数据。
+- operator 可以调用 `tools.catalog`（`operator.read`）以获取某个智能体的运行时工具目录。响应包含分组工具和来源元数据：
   - `source`：`core` 或 `plugin`
   - `pluginId`：当 `source="plugin"` 时的插件所有者
   - `optional`：某个插件工具是否为可选
-- operator 可以调用 `tools.effective`（`operator.read`）来获取某个会话的运行时生效工具清单。
-  - `sessionKey` 是必填项。
-  - Gateway 网关会从服务器端的会话中派生受信任的运行时上下文，而不是接受调用方提供的 auth 或投递上下文。
-  - 响应具有会话作用域，并反映当前活动对话此刻可使用的内容，包括 core、plugin 和 channel 工具。
-- operator 可以调用 `skills.status`（`operator.read`）来获取某个智能体可见的 Skills 清单。
-  - `agentId` 是可选的；省略它即可读取默认智能体工作区。
-  - 响应包含资格、缺失要求、配置检查和已净化的安装选项，而不会暴露原始密钥值。
-- operator 可以调用 `skills.search` 和 `skills.detail`（`operator.read`）来获取 ClawHub 发现元数据。
-- operator 可以通过两种模式调用 `skills.install`（`operator.admin`）：
-  - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将一个 skill 文件夹安装到默认智能体工作区的 `skills/` 目录中。
+- operator 可以调用 `tools.effective`（`operator.read`）以获取某个会话的运行时有效工具清单。
+  - `sessionKey` 为必填。
+  - Gateway 网关从服务端的会话派生受信任运行时上下文，而不是接受调用方提供的 auth 或投递上下文。
+  - 响应按会话范围限定，并反映当前活动对话此刻可使用的内容，包括 core、plugin 和渠道工具。
+- operator 可以调用 `skills.status`（`operator.read`）以获取某个智能体的可见技能清单。
+  - `agentId` 是可选项；省略时读取默认智能体工作区。
+  - 响应包含资格、缺失要求、配置检查和已清理的安装选项，但不会暴露原始秘密值。
+- operator 可以调用 `skills.search` 和 `skills.detail`（`operator.read`）以获取 ClawHub 发现元数据。
+- operator 可以调用 `skills.install`（`operator.admin`），支持两种模式：
+  - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将某个技能文件夹安装到默认智能体工作区的 `skills/` 目录。
   - Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
-    在 Gateway 网关主机上运行已声明的 `metadata.openclaw.install` 动作。
-- operator 可以通过两种模式调用 `skills.update`（`operator.admin`）：
-  - ClawHub 模式更新一个已跟踪的 slug，或更新默认智能体工作区中的所有已跟踪 ClawHub 安装。
+    在 Gateway 网关主机上运行声明的 `metadata.openclaw.install` 操作。
+- operator 可以调用 `skills.update`（`operator.admin`），支持两种模式：
+  - ClawHub 模式更新一个已跟踪 slug，或更新默认智能体工作区中的所有已跟踪 ClawHub 安装项。
   - 配置模式修补 `skills.entries.<skillKey>` 值，例如 `enabled`、`apiKey` 和 `env`。
 
-## Exec 批准
+## Exec 审批
 
-- 当某个 exec 请求需要批准时，Gateway 网关会广播 `exec.approval.requested`。
+- 当某个 exec 请求需要审批时，Gateway 网关会广播 `exec.approval.requested`。
 - operator 客户端通过调用 `exec.approval.resolve` 来处理（需要 `operator.approvals` 作用域）。
-- 对于 `host=node`，`exec.approval.request` 必须包含 `systemRunPlan`（规范化的 `argv`/`cwd`/`rawCommand`/会话元数据）。缺少 `systemRunPlan` 的请求会被拒绝。
-- 批准后，被转发的 `node.invoke system.run` 调用会重用该规范化 `systemRunPlan` 作为权威的命令 / cwd / 会话上下文。
-- 如果调用方在 prepare 与最终获批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝该运行，而不是信任被修改的负载。
+- 对于 `host=node`，`exec.approval.request` 必须包含 `systemRunPlan`（规范的 `argv`/`cwd`/`rawCommand`/会话元数据）。缺少 `systemRunPlan` 的请求会被拒绝。
+- 审批完成后，被转发的 `node.invoke system.run` 调用会复用该规范 `systemRunPlan`，作为权威的命令/cwd/会话上下文。
+- 如果调用方在 prepare 和最终获批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝此次运行，而不是信任被修改的负载。
 
 ## 智能体投递回退
 
-- `agent` 请求可以包含 `deliver=true` 以请求出站投递。
+- `agent` 请求可以包含 `deliver=true`，以请求出站投递。
 - `bestEffortDeliver=false` 保持严格行为：未解析或仅内部的投递目标会返回 `INVALID_REQUEST`。
-- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退为仅会话执行（例如内部 / webchat 会话或多渠道配置含糊不清的情况）。
+- `bestEffortDeliver=true` 允许在无法解析外部可投递路由时回退到仅会话执行（例如内部/webchat 会话或有歧义的多渠道配置）。
 
 ## 版本控制
 
 - `PROTOCOL_VERSION` 位于 `src/gateway/protocol/schema/protocol-schemas.ts`。
-- 客户端发送 `minProtocol` + `maxProtocol`；服务器会拒绝不匹配的情况。
-- Schemas + 模型从 TypeBox 定义生成：
+- 客户端发送 `minProtocol` + `maxProtocol`；服务端会拒绝不匹配情况。
+- Schemas + 模型由 TypeBox 定义生成：
   - `pnpm protocol:gen`
   - `pnpm protocol:gen:swift`
   - `pnpm protocol:check`
 
 ### 客户端常量
 
-`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在协议 v3 中保持稳定，并且是第三方客户端预期的基线。
+`src/gateway/client.ts` 中的参考客户端使用这些默认值。这些值在协议 v3 中保持稳定，也是第三方客户端的预期基线。
 
 | 常量 | 默认值 | 来源 |
 | ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
 | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
-| 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
-| 预认证 / connect-challenge 超时 | `10_000` ms | `src/gateway/handshake-timeouts.ts`（限制在 `250`–`10_000`） |
-| 初始重连退避 | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
-| 最大重连退避 | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
-| device-token 关闭后的快速重试限制 | `250` ms | `src/gateway/client.ts` |
-| `terminate()` 之前的强制停止宽限期 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
+| 请求超时（每个 RPC） | `30_000` ms | `src/gateway/client.ts`（`requestTimeoutMs`） |
+| 预认证 / 连接质询超时 | `10_000` ms | `src/gateway/handshake-timeouts.ts`（限制为 `250`–`10_000`） |
+| 初始重连退避 | `1_000` ms | `src/gateway/client.ts`（`backoffMs`） |
+| 最大重连退避 | `30_000` ms | `src/gateway/client.ts`（`scheduleReconnect`） |
+| 设备令牌关闭后的快速重试限制 | `250` ms | `src/gateway/client.ts` |
+| `terminate()` 前的强制停止宽限期 | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
 | `stopAndWait()` 默认超时 | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
 | 默认 tick 间隔（`hello-ok` 之前） | `30_000` ms | `src/gateway/client.ts` |
-| Tick 超时关闭 | 当静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` |
+| tick 超时关闭 | 当静默超过 `tickIntervalMs * 2` 时使用代码 `4000` | `src/gateway/client.ts` |
 | `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024`（25 MB） | `src/gateway/server-constants.ts` |
 
-服务器会在 `hello-ok` 中公布生效的 `policy.tickIntervalMs`、`policy.maxPayload` 和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。
+服务端会在 `hello-ok` 中公布有效的 `policy.tickIntervalMs`、`policy.maxPayload` 和 `policy.maxBufferedBytes`；客户端应遵循这些值，而不是握手前的默认值。
 
 ## 认证
 
-- 共享密钥 Gateway 网关认证使用 `connect.params.auth.token` 或 `connect.params.auth.password`，具体取决于已配置的认证模式。
-- 带身份的模式，例如 Tailscale Serve
-  （`gateway.auth.allowTailscale: true`）或非 loopback 的
-  `gateway.auth.mode: "trusted-proxy"`，会通过请求头而不是 `connect.params.auth.*` 来满足连接认证检查。
-- 私有入口的 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公开 / 不受信任的入口上暴露该模式。
-- 配对后，Gateway 网关会签发一个限定到连接角色 + 作用域的**设备令牌**。它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以供后续连接使用。
+- 共享密钥 Gateway 网关认证使用 `connect.params.auth.token` 或 `connect.params.auth.password`，取决于已配置的认证模式。
+- 带身份的模式，例如 Tailscale Serve（`gateway.auth.allowTailscale: true`）或非 loopback 的 `gateway.auth.mode: "trusted-proxy"`，会通过请求头而不是 `connect.params.auth.*` 来满足连接认证检查。
+- 私有入口 `gateway.auth.mode: "none"` 会完全跳过共享密钥连接认证；不要在公共/不受信任入口上暴露此模式。
+- 配对后，Gateway 网关会签发一个按连接角色 + 作用域限定的**设备令牌**。它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化，以供将来连接使用。
 - 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。
-- 使用该**已存储**设备令牌重连时，也应重用该令牌已存储的已批准作用域集合。这可以保留先前已授予的读取 / 探测 / 状态访问权限，并避免在重连时悄悄收缩为更窄的隐式仅管理员作用域。
+- 使用该**已存储**设备令牌重新连接时，也应复用该令牌已存储的已批准作用域集合。这样可以保留已授予的读取/探测/状态访问权限，并避免静默将重连收缩为更窄的隐式仅 admin 作用域。
 - 客户端侧连接认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）：
-  - `auth.password` 是正交的，设置时总会被转发。
-  - `auth.token` 按优先级填充：首先是显式共享令牌，其次是显式 `deviceToken`，然后是已存储的按设备令牌（按 `deviceId` + `role` 键控）。
-  - 只有在上述都未解析出 `auth.token` 时，才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。
-  - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌，仅对**受信任端点**启用 —— local loopback，或者带有固定 `tlsFingerprint` 的 `wss://`。未固定证书的公共 `wss://` 不符合条件。
-- 额外的 `hello-ok.auth.deviceTokens` 条目是 bootstrap 交接令牌。只有当连接在受信任传输上使用 bootstrap auth 时，才持久化它们，例如 `wss://` 或 loopback / 本地配对。
-- 如果客户端提供了**显式** `deviceToken` 或显式 `scopes`，则该调用方请求的作用域集合仍然是权威的；仅当客户端重用已存储的按设备令牌时，才会重用缓存作用域。
-- 设备令牌可通过 `device.token.rotate` 和 `device.token.revoke` 轮换 / 吊销（需要 `operator.pairing` 作用域）。
-- 令牌签发 / 轮换始终受限于该设备配对条目中记录的已批准角色集合；轮换令牌不能将设备扩展到配对批准从未授予的角色。
-- 对于已配对设备令牌会话，除非调用方还具有 `operator.admin`，否则设备管理是自限域的：非管理员调用方只能移除 / 吊销 / 轮换其**自己的**设备条目。
-- `device.token.rotate` 还会根据调用方当前会话作用域检查请求的 operator 作用域集合。非管理员调用方不能将令牌轮换为比自己当前持有更宽的 operator 作用域集合。
-- 认证失败包含 `error.details.code` 以及恢复提示：
+  - `auth.password` 是正交的，设置后总会被转发。
+  - `auth.token` 按优先级顺序填充：首先是显式共享令牌，然后是显式 `deviceToken`，再然后是已存储的按设备令牌（按 `deviceId` + `role` 键控）。
+  - 仅当以上都未解析出 `auth.token` 时才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。
+  - 在一次性 `AUTH_TOKEN_MISMATCH` 重试中自动提升已存储设备令牌的行为，仅对**受信任端点**开放——loopback，或带固定 `tlsFingerprint` 的 `wss://`。未固定的公共 `wss://` 不符合条件。
+- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。仅当连接在受信任传输（如 `wss://` 或 loopback/local pairing）上使用引导认证时，才应持久化它们。
+- 如果客户端提供了**显式** `deviceToken` 或显式 `scopes`，则调用方请求的该作用域集合仍然是权威值；仅当客户端复用已存储的按设备令牌时，才会复用缓存作用域。
+- 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。
+- 令牌签发/轮换始终受限于该设备配对条目中记录的已批准角色集合；轮换令牌不能将设备扩展到配对批准从未授予的角色。
+- 对于配对设备令牌会话，除非调用方还具有 `operator.admin`，否则设备管理是自限定的：非 admin 调用方只能移除/撤销/轮换其**自己的**设备条目。
+- `device.token.rotate` 还会根据调用方当前会话作用域检查所请求的 operator 作用域集合。非 admin 调用方不能将令牌轮换为比其当前持有范围更广的 operator 作用域集合。
+- 认证失败会包含 `error.details.code` 和恢复提示：
   - `error.details.canRetryWithDeviceToken`（布尔值）
   - `error.details.recommendedNextStep`（`retry_with_device_token`、`update_auth_configuration`、`update_auth_credentials`、`wait_then_retry`、`review_auth_configuration`）
 - `AUTH_TOKEN_MISMATCH` 的客户端行为：
   - 受信任客户端可以尝试使用缓存的按设备令牌进行一次有界重试。
-  - 如果该重试失败，客户端应停止自动重连循环，并提示操作员采取行动。
+  - 如果该重试失败，客户端应停止自动重连循环，并向 operator 展示操作指引。
 
 ## 设备身份 + 配对
 
-- 节点应包含稳定的设备身份（`device.id`），从密钥对指纹派生。
+- 节点应包含稳定的设备身份（`device.id`），该身份派生自密钥对指纹。
 - Gateway 网关按设备 + 角色签发令牌。
-- 新的设备 ID 需要配对批准，除非启用了本地自动批准。
+- 新设备 ID 需要配对批准，除非启用了本地自动批准。
 - 配对自动批准以直接本地 local loopback 连接为中心。
-- OpenClaw 也为受信任共享密钥辅助流程提供了一个狭窄的后端 / 容器本地自连接路径。
-- 同主机 tailnet 或 LAN 连接在配对上仍视为远程，仍需批准。
+- OpenClaw 还为受信任的共享密钥辅助流程提供了一条狭义的后端/容器本地自连接路径。
+- 同一主机上的 tailnet 或 LAN 连接在配对上仍被视为远程连接，并且需要批准。
 - 所有 WS 客户端都必须在 `connect` 期间包含 `device` 身份（operator + node）。
-  Control UI 仅可在以下模式中省略它：
-  - `gateway.controlUi.allowInsecureAuth=true`，用于仅 localhost 的不安全 HTTP 兼容模式。
+  仅在以下模式下，Control UI 才可以省略它：
+  - `gateway.controlUi.allowInsecureAuth=true`，用于仅 localhost 的不安全 HTTP 兼容性。
   - 成功的 `gateway.auth.mode: "trusted-proxy"` operator Control UI 认证。
-  - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急破窗，严重降低安全性）。
-- 所有连接都必须签署服务器提供的 `connect.challenge` nonce。
+  - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（紧急破玻璃开关，严重降低安全性）。
+- 所有连接都必须对服务端提供的 `connect.challenge` nonce 进行签名。
 
 ### 设备认证迁移诊断
 
-对于仍使用挑战前签名行为的旧客户端，`connect` 现在会在 `error.details.code` 下返回 `DEVICE_AUTH_*` 详情代码，并带有稳定的 `error.details.reason`。
+对于仍使用质询前签名行为的旧客户端，`connect` 现在会在 `error.details.code` 下返回 `DEVICE_AUTH_*` 详细代码，并附带稳定的 `error.details.reason`。
 
 常见迁移失败：
 
 | 消息 | details.code | details.reason | 含义 |
 | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
 | `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | 客户端省略了 `device.nonce`（或发送了空值）。 |
-| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用了过期 / 错误的 nonce 进行签名。 |
+| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | 客户端使用了过期/错误的 nonce 进行签名。 |
 | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | 签名负载与 v2 负载不匹配。 |
-| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 已签名时间戳超出允许的时间偏差。 |
+| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | 签名时间戳超出允许的时钟偏差。 |
 | `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` 与公钥指纹不匹配。 |
-| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公钥格式 / 规范化失败。 |
+| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | 公钥格式/规范化失败。 |
 
 迁移目标：
 
 - 始终等待 `connect.challenge`。
-- 对包含服务器 nonce 的 v2 负载进行签名。
+- 对包含服务端 nonce 的 v2 负载进行签名。
 - 在 `connect.params.device.nonce` 中发送相同的 nonce。
 - 首选签名负载是 `v3`，它除了 device/client/role/scopes/token/nonce 字段外，还绑定 `platform` 和 `deviceFamily`。
-- 为了兼容性，旧版 `v2` 签名仍然可被接受，但已配对设备的元数据固定仍会在重连时控制命令策略。
+- 为了兼容性，旧版 `v2` 签名仍然可接受，但配对设备元数据固定仍会在重连时控制命令策略。
 
 ## TLS + 固定
 
 - WS 连接支持 TLS。
-- 客户端可选择固定 Gateway 网关证书指纹（参见 `gateway.tls`
-  配置，以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
+- 客户端可以选择固定 Gateway 网关证书指纹（参见 `gateway.tls` 配置以及 `gateway.remote.tlsFingerprint` 或 CLI `--tls-fingerprint`）。
 
 ## 范围
 
-此协议公开**完整的 Gateway 网关 API**（状态、渠道、模型、聊天、智能体、会话、节点、批准等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。
+该协议公开**完整 Gateway 网关 API**（状态、渠道、模型、聊天、智能体、会话、节点、审批等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schemas 定义。
 
 ## 相关内容
 
-- [Bridge protocol](/zh-CN/gateway/bridge-protocol)
-- [Gateway runbook](/zh-CN/gateway)
+- [Bridge protocol（旧版节点，历史参考）](/zh-CN/gateway/bridge-protocol)
+- [Gateway 网关运行手册](/zh-CN/gateway)

docs/zh-CN/gateway/troubleshooting.md

@@ -1,26 +1,26 @@
 ---
 read_when:
-    - 故障排除中心将你引导到这里，以进行更深入的诊断。
-    - 你需要按症状组织、结构稳定，并包含精确命令的运行手册章节。
-summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除手册
+    - 故障排除中心已将你引导到这里，以便进行更深入的诊断
+    - 你需要基于稳定症状的运行手册章节，并包含精确命令
+summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册
 title: 故障排除
 x-i18n:
-    generated_at: "2026-04-25T05:54:46Z"
+    generated_at: "2026-04-25T22:27:12Z"
     model: gpt-5.4
     provider: openai
-    source_hash: c2270f05cf34592269894278e1eb75b8d47c02a4ff1c74bf62afb3d8f4fc4640
+    source_hash: 801ad437164d4bd5b834e5018e4d73d452a61d6e6f084093bb736b4531c428c1
     source_path: gateway/troubleshooting.md
     workflow: 15
 ---
 
 # Gateway 网关故障排除
 
-本页是深度运行手册。
-如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
+此页面是深度运行手册。
+如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
 
 ## 命令阶梯
 
-先按以下顺序运行这些命令：
+先运行这些命令，并按以下顺序执行：
 
 ```bash
 openclaw status
@@ -32,13 +32,13 @@ openclaw channels status --probe
 
 预期的健康信号：
 
-- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。
-- `openclaw doctor` 报告没有阻塞性的配置/服务问题。
-- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。
+- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。
+- `openclaw doctor` 报告没有阻塞性的配置或服务问题。
+- `openclaw channels status --probe` 显示每个账户的实时传输状态，并且在支持的情况下，显示如 `works` 或 `audit ok` 之类的探测 / 审计结果。
 
-## Anthropic 429：长上下文需要额外配额
+## Anthropic 429：长上下文需要额外用量
 
-当日志/错误中包含以下内容时，使用本节：
+当日志 / 错误中包含以下内容时使用本节：
 `HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
 
 ```bash
@@ -47,30 +47,30 @@ openclaw models status
 openclaw config get agents.defaults.models
 ```
 
-请检查：
+查找以下内容：
 
-- 所选的 Anthropic Opus/Sonnet 模型是否设置了 `params.context1m: true`。
-- 当前的 Anthropic 凭证是否没有资格使用长上下文。
-- 请求是否仅在需要走 1M beta 路径的长会话/模型运行中失败。
+- 所选的 Anthropic Opus / Sonnet 模型设置了 `params.context1m: true`。
+- 当前的 Anthropic 凭证不具备长上下文用量资格。
+- 请求仅在需要使用 1M beta 路径的长会话 / 模型运行中失败。
 
 修复选项：
 
-1. 为该模型禁用 `context1m`，回退到普通上下文窗口。
-2. 使用有资格发起长上下文请求的 Anthropic 凭证，或切换到 Anthropic API key。
-3. 配置回退模型，这样在 Anthropic 长上下文请求被拒绝时，运行仍可继续。
+1. 对该模型禁用 `context1m`，回退到普通上下文窗口。
+2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换为 Anthropic API key。
+3. 配置后备模型，以便在 Anthropic 长上下文请求被拒绝时，运行仍可继续。
 
 相关内容：
 
 - [Anthropic](/zh-CN/providers/anthropic)
-- [Token 使用和成本](/zh-CN/reference/token-use)
+- [令牌使用与成本](/zh-CN/reference/token-use)
 - [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
 
 ## 本地 OpenAI-compatible 后端直接探测通过，但智能体运行失败
 
-当出现以下情况时，使用本节：
+当出现以下情况时使用本节：
 
-- `curl ... /v1/models` 正常
-- 很小的直接 `/v1/chat/completions` 调用正常
+- `curl ... /v1/models` 可正常工作
+- 很小的直接 `/v1/chat/completions` 调用可正常工作
 - OpenClaw 模型运行仅在正常智能体轮次中失败
 
 ```bash
@@ -82,24 +82,24 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
 openclaw logs --follow
 ```
 
-请检查：
+查找以下内容：
 
-- 直接的小请求成功，但 OpenClaw 运行只在更大的提示词下失败
-- 后端报错 `messages[].content` 期望是字符串
-- 后端崩溃只出现在更大的提示 token 数或完整智能体运行时提示词下
+- 很小的直接调用成功，但 OpenClaw 运行仅在较大提示词下失败
+- 后端报错称 `messages[].content` 应为字符串
+- 后端仅在较大的提示词 token 数或完整智能体运行时提示词下崩溃
 
 常见特征：
 
-- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方式：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
-- 很小的直接请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的智能体运行时提示词形态时崩溃。
-- 禁用工具后失败减少但未消失 → 工具 schema 确实增加了压力，但剩余问题仍然是上游模型/服务器容量限制或后端 bug。
+- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容分片。修复方法：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
+- 很小的直接请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的 Agent Runtimes 提示词形态时出错。
+- 禁用工具后失败有所减少，但并未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量限制或后端 bug。
 
 修复选项：
 
-1. 为仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
-2. 为无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。
-3. 在可能的情况下减轻提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或改用长上下文支持更强的后端。
-4. 如果很小的直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并在上游提交一个包含已接受负载形态的复现。
+1. 对仅接受字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
+2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。
+3. 在可能的情况下减轻提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用对长上下文支持更强的后端。
+4. 如果很小的直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，则应将其视为上游服务器 / 模型限制，并向上游提交 repro，附上已被接受的负载形态。
 
 相关内容：
 
@@ -107,9 +107,9 @@ openclaw logs --follow
 - [配置](/zh-CN/gateway/configuration)
 - [OpenAI-compatible 端点](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints)
 
-## 没有回复
+## 无回复
 
-如果渠道在线但没有任何响应，在重新连接任何东西之前，先检查路由和策略。
+如果渠道已上线但没有任何响应，请在重新连接任何内容之前先检查路由和策略。
 
 ```bash
 openclaw status
@@ -119,17 +119,17 @@ openclaw config get channels
 openclaw logs --follow
 ```
 
-请检查：
+查找以下内容：
 
-- 私信发送者是否处于待配对状态。
+- 私信发送者的配对仍待处理。
 - 群组提及门控（`requireMention`、`mentionPatterns`）。
-- 渠道/群组 allowlist 是否不匹配。
+- 渠道 / 群组 allowlist 不匹配。
 
 常见特征：
 
-- `drop guild message (mention required` → 群组消息在被提及之前会被忽略。
+- `drop guild message (mention required` → 群消息在被提及之前会被忽略。
 - `pairing request` → 发送者需要批准。
-- `blocked` / `allowlist` → 发送者/渠道被策略过滤。
+- `blocked` / `allowlist` → 发送者 / 渠道被策略过滤。
 
 相关内容：
 
@@ -137,9 +137,9 @@ openclaw logs --follow
 - [配对](/zh-CN/channels/pairing)
 - [群组](/zh-CN/channels/groups)
 
-## Dashboard / Control UI 连接问题
+## Dashboard 控制 UI 连接性
 
-当 dashboard/Control UI 无法连接时，检查 URL、认证模式和安全上下文假设。
+当 dashboard / 控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
 
 ```bash
 openclaw gateway status
@@ -149,36 +149,38 @@ openclaw doctor
 openclaw gateway status --json
 ```
 
-请检查：
+查找以下内容：
 
-- 探测 URL 和 dashboard URL 是否正确。
-- 客户端与 Gateway 网关之间的认证模式/token 是否不匹配。
-- 在需要设备身份的场景下是否使用了 HTTP。
+- 正确的探测 URL 和 dashboard URL。
+- 客户端与 Gateway 网关之间的认证模式 / token 不匹配。
+- 在需要设备身份时却使用了 HTTP。
 
 常见特征：
 
 - `device identity required` → 非安全上下文，或缺少设备认证。
-- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正在从非 loopback 浏览器来源连接，但没有显式 allowlist）。
-- `device nonce required` / `device nonce mismatch` → 客户端没有完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
+- `origin not allowed` → 浏览器的 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器来源连接，但未显式加入 allowlist）。
+- `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。
 - `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载（或使用了过期时间戳）。
-- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次受信任的重试。
-- 该缓存 token 重试会复用与配对设备 token 一起存储的缓存 scope 集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留它们请求的 scope 集合。
-- 在该重试路径之外，连接认证优先级依次为：显式共享 token/password、显式 `deviceToken`、已存储的设备 token、bootstrap token。
-- 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, ip}` 的失败尝试会在限流器记录失败之前串行化。因此，同一客户端两个错误的并发重试，第二次可能会显示 `retry later`，而不是两个普通的不匹配错误。
-- 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一标准化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的 bucket。
-- 在该重试之后反复出现 `unauthorized` → 共享 token/设备 token 漂移；如有需要，请刷新 token 配置并重新批准/轮换设备 token。
-- `gateway connect failed:` → host/port/url 目标错误。
+- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次可信重试。
+- 该缓存 token 的重试会复用与已配对设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保持其请求的作用域集合不变。
+- 在该重试路径之外，连接认证优先级依次为：显式共享 token / 密码、显式 `deviceToken`、已存储设备 token、bootstrap token。
+- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限速器记录失败之前串行化。因此，同一客户端的两次并发错误重试中，第二次可能会显示 `retry later`，而不是两个普通的不匹配错误。
+- 浏览器来源的 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一标准化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源使用的是单独的 bucket。
+- 在该重试之后仍重复出现 `unauthorized` → 共享 token / 设备 token 漂移；如有需要，刷新 token 配置，并重新批准 / 轮换设备 token。
+- `gateway connect failed:` → 主机 / 端口 / URL 目标错误。
 
 ### 认证详细代码速查表
 
-使用失败的 `connect` 响应中的 `error.details.code` 来决定下一步操作：
+使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作：
 
-| 详细代码 | 含义 | 建议操作 |
+| 详细代码 | 含义 | 推荐操作 |
 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AUTH_TOKEN_MISSING` | 客户端没有发送必需的共享 token。 | 在客户端中粘贴/设置 token，然后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
-| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许执行一次受信任的重试。缓存 token 重试会复用已存储且已批准的 scopes；显式 `deviceToken` / `scopes` 调用方保留请求的 scopes。如果仍然失败，请运行 [token 漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
-| `AUTH_DEVICE_TOKEN_MISMATCH` | 按设备缓存的 token 已过期或被撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换/重新批准设备 token，然后重新连接。 |
-| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。在你审核请求的访问权限后，scope/role 升级也使用相同流程。 |
+| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享 token。 | 在客户端中粘贴 / 设置 token 后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
+| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 的重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方保持请求的作用域不变。如果仍失败，请运行 [token 漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
+| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存 token 已过期或被撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换 / 重新批准设备 token，然后重新连接。 |
+| `PAIRING_REQUIRED` | 设备身份需要批准。请检查 `error.details.reason`，其值可能为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后运行 `openclaw devices approve <requestId>`。在你审查请求的访问权限后，作用域 / 角色升级也使用相同流程。 |
+
+使用共享 Gateway 网关 token / 密码进行认证的直接 loopback 后端 RPC，不应依赖 CLI 已配对设备的基础作用域。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请验证调用方使用的是 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制显式 `deviceIdentity` 或设备 token。
 
 设备认证 v2 迁移检查：
 
@@ -188,16 +190,16 @@ openclaw doctor
 openclaw gateway status
 ```
 
-如果日志显示 nonce/signature 错误，请更新正在连接的客户端，并验证它：
+如果日志显示 nonce / signature 错误，请更新发起连接的客户端，并验证它：
 
 1. 等待 `connect.challenge`
 2. 对绑定 challenge 的负载进行签名
-3. 发送 `connect.params.device.nonce`，并使用相同的 challenge nonce
+3. 使用相同的 challenge nonce 发送 `connect.params.device.nonce`
 
 如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：
 
-- 配对设备 token 会话只能管理**它们自己的**设备，除非调用方还具有 `operator.admin`
-- `openclaw devices rotate --scope ...` 只能请求调用方会话当前已经持有的 operator scopes
+- 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方还具有 `operator.admin`
+- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域
 
 相关内容：
 
@@ -216,23 +218,23 @@ openclaw gateway status
 openclaw status
 openclaw logs --follow
 openclaw doctor
-openclaw gateway status --deep   # 也会扫描系统级服务
+openclaw gateway status --deep   # also scan system-level services
 ```
 
-请检查：
+查找以下内容：
 
-- `Runtime: stopped` 以及退出提示。
+- `Runtime: stopped`，并带有退出提示。
 - 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
-- 端口/监听冲突。
-- 使用 `--deep` 时是否存在额外的 launchd/systemd/schtasks 安装。
+- 端口 / 监听器冲突。
+- 使用 `--deep` 时发现额外的 launchd / systemd / schtasks 安装。
 - `Other gateway-like services detected (best effort)` 清理提示。
 
 常见特征：
 
-- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或者重新运行 `openclaw onboard --mode local` / `openclaw setup`，重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
-- `refusing to bind gateway ... without auth` → 非 loopback 绑定时，没有有效的 gateway 认证路径（token/password，或在已配置情况下的 trusted-proxy）。
+- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖并丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或者重新运行 `openclaw onboard --mode local` / `openclaw setup`，以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
+- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（token / 密码，或在已配置时使用 trusted-proxy）。
 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。
-- `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd/systemd/schtasks 单元。大多数部署应当每台机器只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
+- `Other gateway-like services detected (best effort)` → 存在过时或并行的 launchd / systemd / schtasks 单元。大多数设置应当每台机器只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置 / 状态 / 工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
 
 相关内容：
 
@@ -240,9 +242,9 @@ openclaw gateway status --deep   # 也会扫描系统级服务
 - [配置](/zh-CN/gateway/configuration)
 - [Doctor](/zh-CN/gateway/doctor)
 
-## Gateway 网关已恢复最后一次已知正确配置
+## Gateway 网关已恢复上次已知正常配置
 
-当 Gateway 网关能够启动，但日志显示它恢复了 `openclaw.json` 时，使用本节。
+当 Gateway 网关能够启动，但日志显示它恢复了 `openclaw.json` 时，请使用本节。
 
 ```bash
 openclaw logs --follow
@@ -251,21 +253,21 @@ openclaw config validate
 openclaw doctor
 ```
 
-请检查：
+查找以下内容：
 
 - `Config auto-restored from last-known-good`
 - `gateway: invalid config was restored from last-known-good backup`
 - `config reload restored last-known-good config after invalid-config`
-- 活动配置旁边是否存在带时间戳的 `openclaw.json.clobbered.*` 文件
-- 是否存在一条以 `Config recovery warning` 开头的主智能体系统事件
+- 活动配置旁边带时间戳的 `openclaw.json.clobbered.*` 文件
+- 以 `Config recovery warning` 开头的主智能体系统事件
 
 发生了什么：
 
-- 被拒绝的配置在启动或热重载期间未通过验证。
+- 被拒绝的配置在启动期间或热重载期间未通过验证。
 - OpenClaw 将被拒绝的负载保留为 `.clobbered.*`。
-- 活动配置已从最后一次验证通过的最后一次已知正确副本恢复。
+- 活动配置已从上次验证通过的 last-known-good 副本中恢复。
 - 下一次主智能体轮次会收到警告，不要盲目重写被拒绝的配置。
-- 如果所有验证问题都位于 `plugins.entries.<id>...` 之下，OpenClaw 不会恢复整个文件。插件本地失败会继续显式暴露，而不相关的用户设置会保留在活动配置中。
+- 如果所有验证问题都位于 `plugins.entries.<id>...` 之下，OpenClaw 不会恢复整个文件。插件本地失败会继续明确报出，而不相关的用户设置会保留在活动配置中。
 
 检查并修复：
 
@@ -279,18 +281,18 @@ openclaw doctor
 
 常见特征：
 
-- 存在 `.clobbered.*` → 外部直接编辑或启动时读取的内容已被恢复。
-- 存在 `.rejected.*` → 一次由 OpenClaw 发起的配置写入在提交前未通过 schema 或 clobber 检查。
-- `Config write rejected:` → 该写入尝试删除必需结构、大幅缩小文件，或持久化无效配置。
-- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与最后一次已知正确备份相比，它丢失了字段或体积变小。
-- `Config last-known-good promotion skipped` → 候选配置中包含已脱敏的密钥占位符，例如 `***`。
+- 存在 `.clobbered.*` → 外部直接编辑或启动读取的内容已被恢复。
+- 存在 `.rejected.*` → OpenClaw 自身发起的配置写入在提交前未通过 schema 或 clobber 检查。
+- `Config write rejected:` → 该写入尝试删除必需结构、显著缩小文件，或持久化无效配置。
+- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与 last-known-good 备份相比，它丢失了字段或大小发生了下降。
+- `Config last-known-good promotion skipped` → 候选内容包含已脱敏的密钥占位符，例如 `***`。
 
 修复选项：
 
-1. 如果恢复后的活动配置是正确的，就保留它。
-2. 仅从 `.clobbered.*` 或 `.rejected.*` 中复制你真正想要的键，然后用 `openclaw config set` 或 `config.patch` 应用。
+1. 如果恢复后的活动配置正确，就保留它。
+2. 仅从 `.clobbered.*` 或 `.rejected.*` 中复制你原本打算修改的键，然后通过 `openclaw config set` 或 `config.patch` 应用它们。
 3. 重启前运行 `openclaw config validate`。
-4. 如果你手动编辑，请保留完整的 JSON5 配置，而不是只保留你想修改的部分对象。
+4. 如果你手动编辑，请保留完整的 JSON5 配置，而不是只保留你想更改的那部分对象。
 
 相关内容：
 
@@ -301,7 +303,7 @@ openclaw doctor
 
 ## Gateway 网关探测警告
 
-当 `openclaw gateway probe` 确实探测到了某些内容，但仍然打印出一段警告时，使用本节。
+当 `openclaw gateway probe` 能探测到某些目标，但仍打印警告块时，请使用本节。
 
 ```bash
 openclaw gateway probe
@@ -309,18 +311,18 @@ openclaw gateway probe --json
 openclaw gateway probe --ssh user@gateway-host
 ```
 
-请检查：
+查找以下内容：
 
 - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
-- 警告是否与 SSH 回退、多个 Gateway 网关、缺失 scopes，或未解析的认证引用有关。
+- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。
 
 常见特征：
 
-- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了直接配置目标/loopback 目标。
-- `multiple reachable gateways detected` → 有多个目标响应。通常这意味着有意的多 Gateway 网关部署，或存在陈旧/重复监听器。
-- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功了，但详细 RPC 受 scope 限制；请配对设备身份，或使用带有 `operator.read` 的凭证。
-- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但该客户端在获得正常 operator 访问前仍需配对/批准。
-- 无法解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标所需的认证材料不可用。
+- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了已配置的 / loopback 直接目标。
+- `multiple reachable gateways detected` → 有多个目标作出了响应。这通常意味着有意的多 Gateway 网关设置，或者存在过时 / 重复的监听器。
+- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用具有 `operator.read` 的凭证。
+- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在获得正常 operator 访问前仍需要配对 / 批准。
+- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此次命令路径中，目标所需的认证材料不可用。
 
 相关内容：
 
@@ -328,9 +330,9 @@ openclaw gateway probe --ssh user@gateway-host
 - [同一主机上的多个 Gateway 网关](/zh-CN/gateway#multiple-gateways-same-host)
 - [远程访问](/zh-CN/gateway/remote)
 
-## 渠道已连接，但消息不流动
+## 渠道已连接但消息未流动
 
-如果渠道状态显示已连接，但消息流是死的，请重点检查策略、权限和渠道特定的投递规则。
+如果渠道状态显示已连接，但消息流已中断，请重点检查策略、权限和渠道特定的投递规则。
 
 ```bash
 openclaw channels status --probe
@@ -340,17 +342,17 @@ openclaw logs --follow
 openclaw config get channels
 ```
 
-请检查：
+查找以下内容：
 
 - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
 - 群组 allowlist 和提及要求。
-- 是否缺少渠道 API 权限/scopes。
+- 缺失的渠道 API 权限 / scopes。
 
 常见特征：
 
 - `mention required` → 消息因群组提及策略而被忽略。
-- `pairing` / 待批准相关痕迹 → 发送者尚未获批。
-- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证/权限问题。
+- `pairing` / 待批准痕迹 → 发送者尚未获批。
+- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证 / 权限问题。
 
 相关内容：
 
@@ -361,7 +363,7 @@ openclaw config get channels
 
 ## Cron 和 heartbeat 投递
 
-如果 cron 或 heartbeat 没有运行，或没有成功投递，请先验证调度器状态，再检查投递目标。
+如果 cron 或 heartbeat 未运行或未投递，请先验证调度器状态，再检查投递目标。
 
 ```bash
 openclaw cron status
@@ -371,31 +373,31 @@ openclaw system heartbeat last
 openclaw logs --follow
 ```
 
-请检查：
+查找以下内容：
 
-- Cron 是否启用，以及是否存在下次唤醒时间。
-- 作业运行历史状态（`ok`、`skipped`、`error`）。
+- Cron 已启用，并且存在下次唤醒时间。
+- 任务运行历史状态（`ok`、`skipped`、`error`）。
 - Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
 
 常见特征：
 
 - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
-- `cron: timer tick failed` → 调度器 tick 失败；请检查文件/日志/运行时错误。
-- `heartbeat skipped` 且 `reason=quiet-hours` → 当前在活跃时间窗口之外。
-- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。
-- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含一个 `tasks:` 块，但本次 tick 没有任何任务到期。
-- `heartbeat: unknown accountId` → heartbeat 投递目标的账号 id 无效。
-- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖项）被设置为 `block`。
+- `cron: timer tick failed` → 调度器 tick 失败；请检查文件 / 日志 / 运行时错误。
+- `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活跃时段窗口内。
+- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / markdown 标题，因此 OpenClaw 会跳过模型调用。
+- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但在当前 tick 中没有任何任务到期。
+- `heartbeat: unknown accountId` → heartbeat 投递目标的账户 id 无效。
+- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目的地，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖配置）被设置为 `block`。
 
 相关内容：
 
-- [计划任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting)
-- [计划任务](/zh-CN/automation/cron-jobs)
+- [定时任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting)
+- [定时任务](/zh-CN/automation/cron-jobs)
 - [Heartbeat](/zh-CN/gateway/heartbeat)
 
-## 已配对节点上的工具失败
+## 已配对节点的工具失败
 
-如果某个节点已配对，但工具失败，请分别排查前台状态、权限状态和批准状态。
+如果节点已配对但工具失败，请分别确认前台状态、权限状态和批准状态。
 
 ```bash
 openclaw nodes status
@@ -405,16 +407,16 @@ openclaw logs --follow
 openclaw status
 ```
 
-请检查：
+查找以下内容：
 
-- 节点是否在线，并具备预期能力。
-- 相机/麦克风/定位/屏幕的操作系统权限是否已授予。
+- 节点在线，并具备预期能力。
+- 相机 / 麦克风 / 位置 / 屏幕的 OS 权限授予状态。
 - Exec 批准和 allowlist 状态。
 
 常见特征：
 
-- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。
-- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。
+- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须处于前台。
+- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少 OS 权限。
 - `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。
 - `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 阻止。
 
@@ -426,7 +428,7 @@ openclaw status
 
 ## 浏览器工具失败
 
-当 Gateway 网关本身健康，但浏览器工具操作仍然失败时，使用本节。
+当浏览器工具操作失败，但 Gateway 网关本身是健康的时，请使用本节。
 
 ```bash
 openclaw browser status
@@ -436,46 +438,46 @@ openclaw logs --follow
 openclaw doctor
 ```
 
-请检查：
+查找以下内容：
 
-- 是否已设置 `plugins.allow`，并且其中包含 `browser`。
-- 浏览器可执行文件路径是否有效。
-- CDP 配置文件是否可达。
-- 对于 `existing-session` / `user` 配置文件，本地 Chrome 是否可用。
+- 是否设置了 `plugins.allow`，并且其中包含 `browser`。
+- 有效的浏览器可执行文件路径。
+- CDP 配置文件可达性。
+- `existing-session` / `user` 配置文件所需的本地 Chrome 是否可用。
 
 常见特征：
 
-- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。
-- 当 `browser.enabled=true` 时 browser 工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件根本没有加载。
+- `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。
+- 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。
 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。
 - `browser.executablePath not found` → 配置的路径无效。
 - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。
 - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。
-- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 还无法附加到所选的浏览器数据目录。请打开浏览器的 inspect 页面，启用远程调试，保持浏览器打开，批准首次附加提示，然后重试。如果不需要登录状态，优先使用受管的 `openclaw` profile。
-- `No Chrome tabs found for profile="user"` → Chrome MCP 附加 profile 没有打开的本地 Chrome 标签页。
-- `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点无法从 Gateway 网关主机访问。
-- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile 没有可访问的目标，或者 HTTP 端点虽然有响应，但 CDP WebSocket 仍然无法打开。
-- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置 browser 插件的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍然可以使用，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出仍不可用。
-- `fullPage is not supported for element screenshots` → 截图请求同时使用了 `--full-page` 和 `--ref` 或 `--element`。
-- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 的截图调用必须使用页面捕获或快照 `--ref`，而不是 CSS `--element`。
-- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，而不是 CSS 选择器。
-- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP profiles 上，每次调用只发送一个上传文件。
-- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profiles 上的对话框钩子不支持超时覆盖。
-- `existing-session type does not support timeoutMs overrides.` → 对于 `profile="user"` / Chrome MCP existing-session profiles 上的 `act:type`，请省略 `timeoutMs`；如果需要自定义超时，请使用受管或 CDP 浏览器 profile。
-- `existing-session evaluate does not support timeoutMs overrides.` → 对于 `profile="user"` / Chrome MCP existing-session profiles 上的 `act:evaluate`，请省略 `timeoutMs`；如果需要自定义超时，请使用受管或 CDP 浏览器 profile。
-- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要受管浏览器或原始 CDP profile。
-- attach-only 或远程 CDP profiles 上出现陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>`，关闭当前控制会话并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。
+- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚未成功附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器开启，批准首次附加提示，然后重试。如果不需要登录状态，优先使用受管的 `openclaw` 配置文件。
+- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
+- `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机无法访问。
+- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可访问目标，或者 HTTP 端点虽然有响应，但 CDP WebSocket 仍无法打开。
+- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件所需的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可使用，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出仍不可用。
+- `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。
+- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用整页捕获或快照 `--ref`，而不是 CSS `--element`。
+- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 文件上传钩子需要使用快照引用，而不是 CSS 选择器。
+- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件中，每次调用只能上传一个文件。
+- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件中的对话框钩子不支持超时覆盖。
+- `existing-session type does not support timeoutMs overrides.` → 在 `profile="user"` / Chrome MCP existing-session 配置文件上，对 `act:type` 省略 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
+- `existing-session evaluate does not support timeoutMs overrides.` → 在 `profile="user"` / Chrome MCP existing-session 配置文件上，对 `act:evaluate` 省略 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
+- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要受管浏览器或原始 CDP 配置文件。
+- attach-only 或远程 CDP 配置文件上存在陈旧的视口 / 深色模式 / 区域设置 / 离线覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>`，关闭活动控制会话并释放 Playwright / CDP 仿真状态，而无需重启整个 Gateway 网关。
 
 相关内容：
 
 - [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)
 - [浏览器（OpenClaw 托管）](/zh-CN/tools/browser)
 
-## 如果你升级后突然出现问题
+## 如果你升级后突然出现故障
 
-大多数升级后的故障都与配置漂移或现在开始强制执行的更严格默认值有关。
+大多数升级后的故障都源于配置漂移，或是现在开始强制执行了更严格的默认值。
 
-### 1) 认证和 URL 覆盖行为已更改
+### 1) 认证和 URL 覆盖行为发生了变化
 
 ```bash
 openclaw gateway status
@@ -484,17 +486,17 @@ openclaw config get gateway.remote.url
 openclaw config get gateway.auth.mode
 ```
 
-检查项：
+检查内容：
 
-- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程端，而你的本地服务其实是正常的。
-- 显式 `--url` 调用不会回退到已存储的凭证。
+- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。
+- 显式 `--url` 调用不会回退到已存储凭证。
 
 常见特征：
 
 - `gateway connect failed:` → URL 目标错误。
-- `unauthorized` → 端点可达，但认证错误。
+- `unauthorized` → 端点可访问，但认证错误。
 
-### 2) 绑定和认证护栏更严格了
+### 2) 绑定和认证保护措施变得更严格
 
 ```bash
 openclaw config get gateway.bind
@@ -504,17 +506,17 @@ openclaw gateway status
 openclaw logs --follow
 ```
 
-检查项：
+检查内容：
 
-- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 gateway 认证路径：共享 token/password 认证，或正确配置的非 loopback `trusted-proxy` 部署。
+- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token / 密码认证，或正确配置的非 loopback `trusted-proxy` 部署。
 - 像 `gateway.token` 这样的旧键不会替代 `gateway.auth.token`。
 
 常见特征：
 
-- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 gateway 认证路径。
-- 运行时已启动，但 `Connectivity probe: failed` → Gateway 网关存活，但使用当前认证/url 无法访问。
+- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。
+- 运行时已启动但 `Connectivity probe: failed` → Gateway 网关存活，但使用当前 auth / URL 无法访问。
 
-### 3) 配对和设备身份状态已更改
+### 3) 配对和设备身份状态发生了变化
 
 ```bash
 openclaw devices list
@@ -523,17 +525,17 @@ openclaw logs --follow
 openclaw doctor
 ```
 
-检查项：
+检查内容：
 
-- dashboard/节点是否存在待批准的设备请求。
-- 策略或身份变化后，私信配对是否有待批准项。
+- dashboard / 节点存在待批准的设备请求。
+- 策略或身份变更后，存在待批准的私信配对请求。
 
 常见特征：
 
 - `device identity required` → 设备认证未满足。
-- `pairing required` → 发送者/设备必须先获批。
+- `pairing required` → 发送者 / 设备必须先获批。
 
-如果完成以上检查后，服务配置和运行时仍然不一致，请使用相同的 profile/状态目录重新安装服务元数据：
+如果在检查之后，服务配置与运行时仍然不一致，请从同一个配置文件 / 状态目录重新安装服务元数据：
 
 ```bash
 openclaw gateway install --force