chore(i18n): refresh zh-CN translations

docs/zh-CN/gateway/health.md

@@ -1,14 +1,14 @@
 ---
 read_when:
-    - 诊断渠道连接性或 Gateway 网关健康状态
+    - 诊断渠道连接或 Gateway 网关健康状况
     - 了解健康检查 CLI 命令和选项
-summary: 健康检查命令与 Gateway 网关健康监控
+summary: 健康检查命令和 Gateway 网关健康监控
 title: 健康检查
 x-i18n:
-    generated_at: "2026-04-05T08:23:20Z"
+    generated_at: "2026-04-23T00:48:54Z"
     model: gpt-5.4
     provider: openai
-    source_hash: b8824bca34c4d1139f043481c75f0a65d83e54008898c34cf69c6f98fd04e819
+    source_hash: 5ddcbe6fa913c5ba889f78cb417124c96b562cf8939410b1d6f66042dfb51a9f
     source_path: gateway/health.md
     workflow: 15
 ---
@@ -19,50 +19,52 @@ x-i18n:
 
 ## 快速检查
 
-- `openclaw status` —— 本地摘要：Gateway 网关可达性/模式、更新提示、已关联渠道的认证时长、sessions + 最近活动。
-- `openclaw status --all` —— 完整本地诊断（只读、彩色、可安全复制粘贴用于调试）。
-- `openclaw status --deep` —— 向正在运行的 Gateway 网关请求实时健康探测（`health` 携带 `probe:true`），包括在支持时按账号划分的渠道探测。
-- `openclaw health` —— 向正在运行的 Gateway 网关请求其健康快照（仅 WS；CLI 不会直接连接渠道 socket）。
-- `openclaw health --verbose` —— 强制执行实时健康探测，并打印 Gateway 网关连接详情。
-- `openclaw health --json` —— 机器可读的健康快照输出。
-- 在 WhatsApp/WebChat 中将 `/status` 作为单独消息发送，以在不调用智能体的情况下获取状态回复。
+- `openclaw status` — 本地摘要：Gateway 网关可达性/模式、更新提示、已关联渠道的凭证有效期、会话 + 最近活动。
+- `openclaw status --all` — 完整本地诊断（只读、带颜色、可安全粘贴用于调试）。
+- `openclaw status --deep` — 向正在运行的 Gateway 网关请求实时健康探测（`health` 且 `probe:true`），包括支持时按账号划分的渠道探测。
+- `openclaw health` — 向正在运行的 Gateway 网关请求其健康快照（仅 `WS`；CLI 不会直接连接渠道套接字）。
+- `openclaw health --verbose` — 强制执行实时健康探测，并打印 Gateway 网关连接详情。
+- `openclaw health --json` — 机器可读的健康快照输出。
+- 在 WhatsApp/WebChat 中单独发送 `/status` 消息，可在不调用智能体的情况下获取状态回复。
 - 日志：跟踪 `/tmp/openclaw/openclaw-*.log`，并筛选 `web-heartbeat`、`web-reconnect`、`web-auto-reply`、`web-inbound`。
 
 ## 深度诊断
 
-- 磁盘上的凭证：`ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json`（mtime 应该是最近的）。
-- 会话存储：`ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json`（路径可在配置中覆盖）。数量和最近接收者会通过 `status` 显示。
-- 重新关联流程：当日志中出现状态码 409–515 或 `loggedOut` 时，运行 `openclaw channels logout && openclaw channels login --verbose`。（注意：在配对后，二维码登录流程会在状态 515 时自动重启一次。）
+- 磁盘上的凭证：`ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json`（`mtime` 应该是最近的）。
+- 会话存储：`ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json`（路径可在配置中覆盖）。`status` 会显示数量和最近的接收方。
+- 重新关联流程：当日志中出现状态码 `409–515` 或 `loggedOut` 时，运行 `openclaw channels logout && openclaw channels login --verbose`。（注意：配对后，二维码登录流程会在状态 `515` 时自动重启一次。）
+- 默认启用诊断。除非设置了 `diagnostics.enabled: false`，否则 Gateway 网关会记录运行事实。内存事件会记录 RSS/堆字节数、阈值压力和增长压力。超大负载事件会记录哪些内容被拒绝、截断或分块，以及可用时的大小和限制。它们不会记录消息文本、附件内容、webhook 正文、原始请求或响应正文、令牌、Cookie 或机密值。同一个心跳还会启动有界稳定性记录器，可通过 `openclaw gateway stability` 或 `diagnostics.stability` Gateway 网关 RPC 访问。当存在事件时，致命的 Gateway 网关退出、关闭超时和重启启动失败会将最新的记录器快照持久化到 `~/.openclaw/logs/stability/`；可使用 `openclaw gateway stability --bundle latest` 检查最新保存的 bundle。
+- 对于 bug 报告，运行 `openclaw gateway diagnostics export` 并附上生成的 zip。该导出会合并 Markdown 摘要、最新稳定性 bundle、已净化的日志元数据、已净化的 Gateway 网关状态/健康快照以及配置结构。它设计为可共享：聊天文本、webhook 正文、工具输出、凭证、Cookie、账号/消息标识符和机密值会被省略或脱敏。
 
 ## 健康监控配置
 
-- `gateway.channelHealthCheckMinutes`：Gateway 网关检查渠道健康状态的频率。默认：`5`。设置为 `0` 可全局禁用健康监控重启。
-- `gateway.channelStaleEventThresholdMinutes`：某个已连接渠道在被健康监控视为陈旧并重启之前，允许空闲的最长时间。默认：`30`。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。
-- `gateway.channelMaxRestartsPerHour`：按渠道/账号统计的、健康监控重启的滚动一小时上限。默认：`10`。
-- `channels.<provider>.healthMonitor.enabled`：在保持全局监控启用的同时，为某个特定渠道禁用健康监控重启。
-- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号覆盖项，其优先级高于渠道级设置。
-- 这些按渠道划分的覆盖项适用于当前暴露该能力的内置渠道监控器：Discord、Google Chat、iMessage、Microsoft Teams、Signal、Slack、Telegram 和 WhatsApp。
+- `gateway.channelHealthCheckMinutes`：Gateway 网关检查渠道健康状态的频率。默认值：`5`。设为 `0` 可全局禁用健康监控重启。
+- `gateway.channelStaleEventThresholdMinutes`：已连接渠道在被健康监控视为陈旧并重启之前，可以保持空闲多长时间。默认值：`30`。请保持该值大于或等于 `gateway.channelHealthCheckMinutes`。
+- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内由健康监控触发重启的上限。默认值：`10`。
+- `channels.<provider>.healthMonitor.enabled`：在保持全局监控启用的同时，禁用特定渠道的健康监控重启。
+- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号覆盖项，优先于渠道级设置。
+- 这些按渠道划分的覆盖项适用于当前公开这些功能的内置渠道监控器：Discord、Google Chat、iMessage、Microsoft Teams、Signal、Slack、Telegram 和 WhatsApp。
 
-## 当某些内容失败时
+## 失败时的处理
 
-- `logged out` 或状态码 409–515 → 使用 `openclaw channels logout` 然后 `openclaw channels login` 重新关联。
-- Gateway 网关不可达 → 启动它：`openclaw gateway --port 18789`（如果端口繁忙，请使用 `--force`）。
-- 没有入站消息 → 确认已关联手机在线，且发送者已被允许（`channels.whatsapp.allowFrom`）；对于群聊，请确保允许列表 + 提及规则匹配（`channels.whatsapp.groups`、`agents.list[].groupChat.mentionPatterns`）。
+- `logged out` 或状态码 `409–515` → 使用 `openclaw channels logout`，然后运行 `openclaw channels login` 重新关联。
+- Gateway 网关不可达 → 启动它：`openclaw gateway --port 18789`（如果端口被占用，使用 `--force`）。
+- 没有入站消息 → 确认已关联的手机处于在线状态，并且发送方被允许（`channels.whatsapp.allowFrom`）；对于群聊，确保允许列表和提及规则匹配（`channels.whatsapp.groups`、`agents.list[].groupChat.mentionPatterns`）。
 
-## 专用的 “health” 命令
+## 专用 “health” 命令
 
 `openclaw health` 会向正在运行的 Gateway 网关请求其健康快照（CLI 不会直接连接渠道
-socket）。默认情况下，它可以返回一个新的缓存 Gateway 网关快照；随后
-Gateway 网关会在后台刷新该缓存。`openclaw health --verbose` 则会强制执行
-实时探测。该命令会在可用时报告已关联凭证/认证时长、
-按渠道划分的探测摘要、会话存储摘要以及探测耗时。如果
-Gateway 网关不可达，或探测失败/超时，它会以非零状态退出。
+套接字）。默认情况下，它可以返回一个较新的缓存 Gateway 网关快照；随后
+Gateway 网关会在后台刷新该缓存。`openclaw health --verbose` 则会强制
+执行实时探测。该命令会在可用时报告已关联凭证/凭证有效期、
+按渠道划分的探测摘要、会话存储摘要以及探测耗时。如果 Gateway 网关不可达，或者探测失败/超时，
+它会以非零状态退出。
 
 选项：
 
 - `--json`：机器可读的 JSON 输出
-- `--timeout <ms>`：覆盖默认的 10 秒探测超时
-- `--verbose`：强制实时探测并打印 Gateway 网关连接详情
+- `--timeout <ms>`：覆盖默认的 `10s` 探测超时
+- `--verbose`：强制执行实时探测，并打印 Gateway 网关连接详情
 - `--debug`：`--verbose` 的别名
 
-健康快照包括：`ok`（布尔值）、`ts`（时间戳）、`durationMs`（探测耗时）、按渠道划分的状态、智能体可用性，以及会话存储摘要。
+健康快照包括：`ok`（布尔值）、`ts`（时间戳）、`durationMs`（探测耗时）、按渠道划分的状态、智能体可用性以及会话存储摘要。

docs/zh-CN/gateway/protocol.md

@@ -2,30 +2,31 @@
 read_when:
     - 实现或更新 Gateway 网关 WS 客户端
     - 调试协议不匹配或连接失败
-    - 重新生成协议 schema/模型
+    - 重新生成协议 schema / 模型
 summary: Gateway 网关 WebSocket 协议：握手、帧、版本控制
 title: Gateway 网关协议
 x-i18n:
-    generated_at: "2026-04-21T20:16:08Z"
+    generated_at: "2026-04-23T00:48:56Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 6efa76f5f0faa6c10a8515b0cf457233e48551e3484a605dffaf6459ddff9231
+    source_hash: 9d4ea65fbe31962ed8ece04a645cfe5aaff9fee8b5f89bc896b461cd45567634
     source_path: gateway/protocol.md
     workflow: 15
 ---
 
 # Gateway 网关协议（WebSocket）
 
-Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输协议**。所有客户端（CLI、web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
+Gateway 网关 WS 协议是 OpenClaw 的**单一控制平面 + 节点传输层**。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）都通过 WebSocket 连接，并在握手时声明其**角色** + **作用域**。
 
 ## 传输
 
 - WebSocket，使用带有 JSON 负载的文本帧。
-- 第一帧**必须**是 `connect` 请求。
+- 第一帧**必须**是一个 `connect` 请求。
+- 连接前的帧大小上限为 64 KiB。成功握手后，客户端应遵循 `hello-ok.policy.maxPayload` 和 `hello-ok.policy.maxBufferedBytes` 限制。启用诊断时，过大的入站帧和缓慢的出站缓冲区会先发出 `payload.large` 事件，然后 Gateway 网关才会关闭连接或丢弃受影响的帧。这些事件会保留大小、限制、表面、以及安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、cookie 或密钥值。
 
 ## 握手（connect）
 
-Gateway 网关 → 客户端（连接前质询）：
+Gateway 网关 → 客户端（连接前挑战）：
 
 ```json
 {
@@ -92,9 +93,9 @@ Gateway 网关 → 客户端：
 }
 ```
 
-`server`、`features`、`snapshot` 和 `policy` 都是 schema 要求的字段（`src/gateway/protocol/schema/frames.ts`）。`canvasHostUrl` 是可选字段。`auth` 会在可用时报告协商后的角色/作用域，并在 Gateway 网关签发设备令牌时包含 `deviceToken`。
+根据 schema（`src/gateway/protocol/schema/frames.ts`），`server`、`features`、`snapshot` 和 `policy` 都是必需的。`canvasHostUrl` 是可选项。`auth` 会在可用时报告协商后的角色/作用域，并在 Gateway 网关签发设备令牌时包含 `deviceToken`。
 
-当未签发设备令牌时，`hello-ok.auth` 仍然可以报告协商后的权限：
+当未签发设备令牌时，`hello-ok.auth` 仍可报告协商后的权限：
 
 ```json
 {
@@ -105,7 +106,7 @@ Gateway 网关 → 客户端：
 }
 ```
 
-当签发了设备令牌时，`hello-ok` 还会包含：
+当签发设备令牌时，`hello-ok` 还会包含：
 
 ```json
 {
@@ -117,7 +118,7 @@ Gateway 网关 → 客户端：
 }
 ```
 
-在受信任的引导交接期间，`hello-ok.auth` 还可能在 `deviceTokens` 中包含额外的受限角色条目：
+在受信任的 bootstrap 交接期间，`hello-ok.auth` 还可以在 `deviceTokens` 中包含额外的有界角色条目：
 
 ```json
 {
@@ -136,9 +137,9 @@ Gateway 网关 → 客户端：
 }
 ```
 
-对于内置的 node/operator 引导流程，主 node 令牌保持为 `scopes: []`，而任何交接的 operator 令牌都会保持受限于引导 operator 允许列表（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。引导作用域检查仍然按角色前缀进行：operator 条目只满足 operator 请求，非 operator 角色仍然需要其自身角色前缀下的作用域。
+对于内置的 node/operator bootstrap 流程，主 node 令牌保持为 `scopes: []`，任何交接出去的 operator 令牌都保持限制在 bootstrap operator 允许列表内（`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`）。Bootstrap 作用域检查仍保持角色前缀规则：operator 条目只满足 operator 请求，而非 operator 角色仍然需要其自身角色前缀下的作用域。
 
-### Node 示例
+### 节点示例
 
 ```json
 {
@@ -179,7 +180,7 @@ Gateway 网关 → 客户端：
 - **响应**：`{type:"res", id, ok, payload|error}`
 - **事件**：`{type:"event", event, payload, seq?, stateVersion?}`
 
-有副作用的方法需要 **idempotency keys**（参见 schema）。
+有副作用的方法需要 **幂等键**（参见 schema）。
 
 ## 角色 + 作用域
 
@@ -201,56 +202,57 @@ 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`
-- 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求：
-  `operator.pairing` + `operator.admin`
+- 带有非 exec node 命令的请求：`operator.pairing` + `operator.write`
+- 包含 `system.run`、`system.run.prepare` 或 `system.which` 的请求：`operator.pairing` + `operator.admin`
 
-### Caps/commands/permissions（node）
+### caps/commands/permissions（node）
 
-节点在连接时声明能力声明：
+节点在连接时声明能力主张：
 
-- `caps`：高层能力类别。
+- `caps`：高级能力类别。
 - `commands`：用于 invoke 的命令允许列表。
 - `permissions`：细粒度开关（例如 `screen.record`、`camera.capture`）。
 
-Gateway 网关将这些视为**声明**，并在服务端强制执行允许列表。
+Gateway 网关将这些视为**主张**，并在服务器端强制执行允许列表。
 
 ## 在线状态
 
-- `system-presence` 返回按设备标识键控的条目。
-- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，因此 UI 即使在设备同时以 **operator** 和 **node** 身份连接时，也可以为每台设备显示单独一行。
+- `system-presence` 返回按设备身份键控的条目。
+- 在线状态条目包含 `deviceId`、`roles` 和 `scopes`，这样 UI 就能为单个设备显示一行，
+  即使它同时以 **operator** 和 **node** 身份连接。
 
 ## 广播事件作用域控制
 
-服务端推送的 WebSocket 广播事件受作用域门控，以确保仅配对作用域或仅 node 的会话不会被动接收会话内容。
+服务器推送的 WebSocket 广播事件会进行作用域门控，因此仅具备 pairing 作用域或仅 node 的会话不会被动接收会话内容。
 
 - **聊天、智能体和工具结果帧**（包括流式 `agent` 事件和工具调用结果）至少需要 `operator.read`。没有 `operator.read` 的会话会完全跳过这些帧。
-- **插件定义的 `plugin.*` 广播** 会根据插件注册方式，被门控到 `operator.write` 或 `operator.admin`。
-- **状态和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）保持不受限制，以便每个已认证会话都能观察到传输健康状态。
-- **未知广播事件族** 默认受作用域门控（默认拒绝），除非已注册的处理器显式放宽限制。
+- **插件定义的 `plugin.*` 广播** 会被门控到 `operator.write` 或 `operator.admin`，具体取决于插件注册它们的方式。
+- **状态和传输事件**（`heartbeat`、`presence`、`tick`、连接/断开生命周期等）仍然不受限制，以便每个已认证会话都能观察到传输健康状态。
+- **未知广播事件族** 默认进行作用域门控（失败时关闭），除非已注册的处理器显式放宽它们。
 
-每个客户端连接都会维护各自的每客户端序列号，因此即使不同客户端看到的是经过不同作用域过滤后的事件流子集，广播在该 socket 上仍会保持单调顺序。
+每个客户端连接都维护自己的按客户端计数的序列号，因此即使不同客户端看到的事件流子集因作用域过滤而不同，广播在该 socket 上仍保持单调有序。
 
 ## 常见 RPC 方法族
 
-本页不是自动生成的完整转储，但公共 WS 接口比上面的握手/认证示例更广。这些是 Gateway 网关当前公开的主要方法族。
+本页不是生成的完整转储，但公开的 WS 表面比上面的握手/认证示例更广。这些是 Gateway 网关当前暴露的主要方法族。
 
-`hello-ok.features.methods` 是一个保守的发现列表，由 `src/gateway/server-methods-list.ts` 加上已加载的插件/渠道方法导出构建而成。应将其视为功能发现，而不是 `src/gateway/server-methods/*.ts` 中实现的每个可调用辅助函数的自动生成转储。
+`hello-ok.features.methods` 是一个保守的发现列表，基于 `src/gateway/server-methods-list.ts` 加上已加载的插件/渠道方法导出构建。应将其视为功能发现，而不是对 `src/gateway/server-methods/*.ts` 中每个可调用辅助函数的生成式转储。
 
-### 系统和标识
+### 系统和身份
 
 - `health` 返回缓存的或新探测的 Gateway 网关健康快照。
+- `diagnostics.stability` 返回最近的有界诊断稳定性记录器。它会保留事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称以及会话 id 等操作元数据。它不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookie 或密钥值。需要 operator 读取作用域。
 - `status` 返回 `/status` 风格的 Gateway 网关摘要；敏感字段仅对具有 admin 作用域的 operator 客户端包含。
-- `gateway.identity.get` 返回 relay 和配对流程使用的 Gateway 网关设备标识。
+- `gateway.identity.get` 返回 relay 和 pairing 流程所使用的 Gateway 网关设备身份。
 - `system-presence` 返回当前已连接 operator/node 设备的在线状态快照。
-- `system-event` 追加系统事件，并可更新/广播在线状态上下文。
+- `system-event` 追加一条系统事件，并可更新/广播在线状态上下文。
 - `last-heartbeat` 返回最近持久化的 heartbeat 事件。
 - `set-heartbeats` 切换 Gateway 网关上的 heartbeat 处理。
 
@@ -258,282 +260,273 @@ Gateway 网关将这些视为**声明**，并在服务端强制执行允许列
 
 - `models.list` 返回运行时允许的模型目录。
 - `usage.status` 返回提供商用量窗口/剩余额度摘要。
-- `usage.cost` 返回某日期范围的聚合成本用量摘要。
-- `doctor.memory.status` 返回活动默认智能体工作区的向量记忆 / embedding 就绪状态。
-- `sessions.usage` 返回按会话聚合的用量摘要。
-- `sessions.usage.timeseries` 返回单个会话的时序用量。
+- `usage.cost` 返回日期范围内聚合的成本用量摘要。
+- `doctor.memory.status` 返回活动默认智能体工作区的向量内存 / embedding 就绪状态。
+- `sessions.usage` 返回按会话划分的用量摘要。
+- `sessions.usage.timeseries` 返回单个会话的时间序列用量。
 - `sessions.usage.logs` 返回单个会话的用量日志条目。
 
 ### 渠道和登录辅助
 
-- `channels.status` 返回内置 + 内置插件渠道/插件状态摘要。
-- `channels.logout` 在渠道支持登出的情况下，登出特定渠道/账号。
-- `web.login.start` 为当前支持 QR 的 web 渠道提供商启动 QR/web 登录流程。
-- `web.login.wait` 等待该 QR/web 登录流程完成，并在成功时启动渠道。
-- `push.test` 向已注册的 iOS node 发送测试 APNs 推送。
+- `channels.status` 返回内置 + 内置插件渠道状态摘要。
+- `channels.logout` 在渠道支持登出的情况下，为特定渠道/账号执行登出。
+- `web.login.start` 为当前支持 QR 的 Web 渠道提供商启动 QR/Web 登录流程。
+- `web.login.wait` 等待该 QR/Web 登录流程完成，并在成功后启动渠道。
+- `push.test` 向已注册的 iOS 节点发送测试 APNs 推送。
 - `voicewake.get` 返回已存储的唤醒词触发器。
-- `voicewake.set` 更新唤醒词触发器并广播更改。
+- `voicewake.set` 更新唤醒词触发器并广播变更。
 
 ### 消息和日志
 
-- `send` 是直接的出站投递 RPC，用于在聊天运行器之外，按渠道/账号/线程目标发送消息。
-- `logs.tail` 返回配置的 Gateway 网关文件日志尾部，支持 cursor/limit 和最大字节数控制。
+- `send` 是直接的出站投递 RPC，用于在 chat runner 之外，向特定渠道/账号/线程目标发送消息。
+- `logs.tail` 返回已配置的 Gateway 网关文件日志尾部，并支持 cursor/limit 和 max-byte 控制。
 
 ### Talk 和 TTS
 
-- `talk.config` 返回生效的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
-- `talk.mode` 为 WebChat/Control UI 客户端设置/广播当前 Talk 模式状态。
-- `talk.speak` 通过活动的 Talk 语音提供商合成语音。
-- `tts.status` 返回 TTS 启用状态、活动提供商、后备提供商和提供商配置状态。
+- `talk.config` 返回生效中的 Talk 配置负载；`includeSecrets` 需要 `operator.talk.secrets`（或 `operator.admin`）。
+- `talk.mode` 为 WebChat/控制 UI 客户端设置/广播当前 Talk 模式状态。
+- `talk.speak` 通过当前活动的 Talk 语音提供商合成语音。
+- `tts.status` 返回 TTS 启用状态、当前提供商、后备提供商以及提供商配置状态。
 - `tts.providers` 返回可见的 TTS 提供商清单。
 - `tts.enable` 和 `tts.disable` 切换 TTS 偏好设置状态。
 - `tts.setProvider` 更新首选 TTS 提供商。
-- `tts.convert` 执行一次性文本转语音转换。
+- `tts.convert` 运行一次性文本转语音转换。
 
-### Secrets、配置、更新和向导
+### 密钥、配置、更新和向导
 
-- `secrets.reload` 重新解析活动 SecretRefs，并且仅在完全成功时替换运行时 secret 状态。
-- `secrets.resolve` 为特定命令/目标集解析命令目标 secret 赋值。
+- `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`。
-- `update.run` 运行 Gateway 网关更新流程，并且仅在更新本身成功时安排重启。
-- `wizard.start`、`wizard.next`、`wizard.status` 和 `wizard.cancel` 通过 WS RPC 公开新手引导向导。
+- `config.schema` 返回供控制 UI 和 CLI 工具使用的实时配置 schema 负载：schema、`uiHints`、版本和生成元数据，包括运行时可加载时的插件 + 渠道 schema 元数据。该 schema 包含从 UI 使用的相同标签和帮助文本派生的字段 `title` / `description` 元数据，包括嵌套对象、通配符、数组项，以及在存在匹配字段文档时的 `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 暴露新手引导向导。
 
 ### 现有主要方法族
 
 #### 智能体和工作区辅助
 
 - `agents.list` 返回已配置的智能体条目。
-- `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区接线。
-- `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为某个智能体公开的引导工作区文件。
-- `agent.identity.get` 返回某个智能体或会话的生效助手身份。
+- `agents.create`、`agents.update` 和 `agents.delete` 管理智能体记录和工作区连接。
+- `agents.files.list`、`agents.files.get` 和 `agents.files.set` 管理为某个智能体公开的 bootstrap 工作区文件。
+- `agent.identity.get` 返回某个智能体或会话的有效助手身份。
 - `agent.wait` 等待一次运行结束，并在可用时返回终态快照。
 
 #### 会话控制
 
 - `sessions.list` 返回当前会话索引。
 - `sessions.subscribe` 和 `sessions.unsubscribe` 为当前 WS 客户端切换会话变更事件订阅。
-- `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为单个会话切换 transcript/message 事件订阅。
+- `sessions.messages.subscribe` 和 `sessions.messages.unsubscribe` 为单个会话切换 transcript/消息事件订阅。
 - `sessions.preview` 返回特定会话键的有界 transcript 预览。
-- `sessions.resolve` 解析或规范化某个会话目标。
+- `sessions.resolve` 解析或规范化会话目标。
 - `sessions.create` 创建新的会话条目。
 - `sessions.send` 向现有会话发送消息。
-- `sessions.steer` 是针对活动会话的中断并转向变体。
+- `sessions.steer` 是针对活动会话的中断并引导变体。
 - `sessions.abort` 中止某个会话的活动工作。
 - `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`。
+- `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`），并且可将过大的行替换为占位符。
 
 #### 设备配对和设备令牌
 
-- `device.pair.list` 返回待处理和已批准的已配对设备。
+- `device.pair.list` 返回待处理和已批准的配对设备。
 - `device.pair.approve`、`device.pair.reject` 和 `device.pair.remove` 管理设备配对记录。
 - `device.token.rotate` 在已批准的角色和作用域边界内轮换已配对设备令牌。
-- `device.token.revoke` 撤销已配对设备令牌。
+- `device.token.revoke` 吊销已配对设备令牌。
 
-#### Node 配对、调用和待处理工作
+#### 节点配对、调用和待处理工作
 
-- `node.pair.request`、`node.pair.list`、`node.pair.approve`、
-  `node.pair.reject` 和 `node.pair.verify` 涵盖 node 配对和引导验证。
-- `node.list` 和 `node.describe` 返回已知/已连接的 node 状态。
-- `node.rename` 更新已配对 node 标签。
-- `node.invoke` 将命令转发给已连接 node。
-- `node.invoke.result` 返回某次 invoke 请求的结果。
-- `node.event` 将 node 发起的事件携带回 Gateway 网关。
-- `node.canvas.capability.refresh` 刷新有作用域限制的 canvas 能力令牌。
-- `node.pending.pull` 和 `node.pending.ack` 是已连接 node 的队列 API。
-- `node.pending.enqueue` 和 `node.pending.drain` 管理离线/断开连接 node 的持久待处理工作。
+- `node.pair.request`、`node.pair.list`、`node.pair.approve`、`node.pair.reject` 和 `node.pair.verify` 涵盖节点配对和 bootstrap 验证。
+- `node.list` 和 `node.describe` 返回已知/已连接的节点状态。
+- `node.rename` 更新已配对节点标签。
+- `node.invoke` 将命令转发到已连接节点。
+- `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` 管理离线/断开连接节点的持久待处理工作。
 
-#### 审批方法族
+#### 批准方法族
 
-- `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` 通过 node relay 命令管理 node 本地 exec 审批策略。
-- `plugin.approval.request`、`plugin.approval.list`、
-  `plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的审批流程。
+- `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` 通过节点中继命令管理节点本地 exec 批准策略。
+- `plugin.approval.request`、`plugin.approval.list`、`plugin.approval.waitDecision` 和 `plugin.approval.resolve` 涵盖插件定义的批准流程。
 
 #### 其他主要方法族
 
-- 自动化：
-  - `wake` 调度立即或下一次 heartbeat 的唤醒文本注入
-  - `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、
-    `cron.run`、`cron.runs`
-- Skills/工具：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`
+- automation：
+  - `wake` 安排立即或在下一个 heartbeat 时注入唤醒文本
+  - `cron.list`、`cron.status`、`cron.add`、`cron.update`、`cron.remove`、`cron.run`、`cron.runs`
+- skills/tools：`commands.list`、`skills.*`、`tools.catalog`、`tools.effective`
 
 ### 常见事件族
 
 - `chat`：UI 聊天更新，例如 `chat.inject` 和其他仅 transcript 的聊天事件。
 - `session.message` 和 `session.tool`：已订阅会话的 transcript/事件流更新。
-- `sessions.changed`：会话索引或元数据已更改。
+- `sessions.changed`：会话索引或元数据已变更。
 - `presence`：系统在线状态快照更新。
 - `tick`：周期性 keepalive / 存活事件。
 - `health`：Gateway 网关健康快照更新。
 - `heartbeat`：heartbeat 事件流更新。
 - `cron`：cron 运行/任务变更事件。
 - `shutdown`：Gateway 网关关闭通知。
-- `node.pair.requested` / `node.pair.resolved`：node 配对生命周期。
-- `node.invoke.request`：node invoke 请求广播。
+- `node.pair.requested` / `node.pair.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`：插件审批生命周期。
+- `voicewake.changed`：唤醒词触发器配置已变更。
+- `exec.approval.requested` / `exec.approval.resolved`：exec 批准生命周期。
+- `plugin.approval.requested` / `plugin.approval.resolved`：插件批准生命周期。
 
-### Node 辅助方法
+### 节点辅助方法
 
-- Nodes 可以调用 `skills.bins` 来获取当前 Skills 可执行文件列表，用于自动允许检查。
+- 节点可以调用 `skills.bins` 以获取当前 Skills 可执行文件列表，用于自动允许检查。
 
 ### Operator 辅助方法
 
-- Operators 可以调用 `commands.list`（`operator.read`）来获取某个智能体的运行时命令清单。
-  - `agentId` 是可选的；省略它可读取默认智能体工作区。
-  - `scope` 控制主 `name` 针对哪个接口：
+- Operator 可以调用 `commands.list`（`operator.read`）以获取某个智能体的运行时命令清单。
+  - `agentId` 是可选的；省略它即可读取默认智能体工作区。
+  - `scope` 控制主 `name` 所指向的表面：
     - `text` 返回不带前导 `/` 的主文本命令令牌
-    - `native` 和默认的 `both` 路径会在可用时返回提供商感知的原生命令名称
+    - `native` 和默认的 `both` 路径会在可用时返回具备提供商感知能力的原生命名
   - `textAliases` 携带精确的斜杠别名，例如 `/model` 和 `/m`。
-  - `nativeName` 在存在时携带提供商感知的原生命令名称。
-  - `provider` 是可选的，仅影响原生命名以及原生插件命令可用性。
+  - `nativeName` 在存在时携带具备提供商感知能力的原生命令名。
+  - `provider` 是可选的，仅影响原生命名以及原生插件命令的可用性。
   - `includeArgs=false` 会从响应中省略序列化参数元数据。
-- Operators 可以调用 `tools.catalog`（`operator.read`）来获取某个智能体的运行时工具目录。响应包含已分组的工具和来源元数据：
+- Operator 可以调用 `tools.catalog`（`operator.read`）以获取某个智能体的运行时工具目录。响应包括分组后的工具和来源元数据：
   - `source`：`core` 或 `plugin`
-  - 当 `source="plugin"` 时，`pluginId` 为插件归属方
-  - `optional`：插件工具是否为可选
-- Operators 可以调用 `tools.effective`（`operator.read`）来获取某个会话的运行时生效工具清单。
-  - `sessionKey` 是必填项。
-  - Gateway 网关会从服务端会话中派生受信任的运行时上下文，而不是接受调用方提供的 auth 或投递上下文。
-  - 响应具有会话作用域，并反映当前活动对话此刻可使用的内容，包括 core、plugin 和渠道工具。
-- Operators 可以调用 `skills.status`（`operator.read`）来获取某个智能体可见的 Skills 清单。
-  - `agentId` 是可选的；省略它可读取默认智能体工作区。
-  - 响应包含资格、缺失要求、配置检查和已清洗的安装选项，而不会暴露原始 secret 值。
-- Operators 可以调用 `skills.search` 和 `skills.detail`（`operator.read`）来获取 ClawHub 发现元数据。
-- Operators 可以通过两种模式调用 `skills.install`（`operator.admin`）：
-  - ClawHub 模式：`{ source: "clawhub", slug, version?, force? }` 将某个 skill 文件夹安装到默认智能体工作区的 `skills/` 目录中。
+  - `pluginId`：当 `source="plugin"` 时的插件所有者
+  - `optional`：某个插件工具是否为可选
+- Operator 可以调用 `tools.effective`（`operator.read`）以获取某个会话的运行时有效工具清单。
+  - `sessionKey` 是必需的。
+  - Gateway 网关从服务端会话派生受信任的运行时上下文，而不是接受调用方提供的认证或投递上下文。
+  - 响应是按会话作用域返回的，并反映当前活动对话此刻可使用的内容，包括核心、插件和渠道工具。
+- 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/` 目录中。
   - Gateway 网关安装器模式：`{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
     在 Gateway 网关宿主机上运行已声明的 `metadata.openclaw.install` 操作。
-- Operators 可以通过两种模式调用 `skills.update`（`operator.admin`）：
-  - ClawHub 模式会更新默认智能体工作区中一个被跟踪的 slug，或全部被跟踪的 ClawHub 安装。
-  - 配置模式会修补 `skills.entries.<skillKey>` 值，例如 `enabled`、
-    `apiKey` 和 `env`。
+- Operator 可以用两种模式调用 `skills.update`（`operator.admin`）：
+  - ClawHub 模式会更新一个已跟踪的 slug，或默认智能体工作区中所有已跟踪的 ClawHub 安装项。
+  - 配置模式会修补 `skills.entries.<skillKey>` 值，例如 `enabled`、`apiKey` 和 `env`。
 
-## Exec 审批
+## Exec 批准
 
-- 当某个 exec 请求需要审批时，Gateway 网关会广播 `exec.approval.requested`。
-- Operator 客户端通过调用 `exec.approval.resolve` 来处理（需要 `operator.approvals` 作用域）。
+- 当某个 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` 作为权威的 command/cwd/session 上下文。
-- 如果调用方在 prepare 和最终获批的 `system.run` 转发之间篡改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝该运行，而不是信任被篡改的负载。
+- 批准后，转发的 `node.invoke system.run` 调用会复用该规范 `systemRunPlan` 作为权威的命令/cwd/会话上下文。
+- 如果调用方在 prepare 和最终获批的 `system.run` 转发之间修改了 `command`、`rawCommand`、`cwd`、`agentId` 或 `sessionKey`，Gateway 网关会拒绝此次运行，而不是信任被修改后的负载。
 
-## 智能体投递后备
+## 智能体投递回退
 
 - `agent` 请求可以包含 `deliver=true` 以请求出站投递。
-- `bestEffortDeliver=false` 保持严格行为：未解析或仅内部的投递目标会返回 `INVALID_REQUEST`。
-- `bestEffortDeliver=true` 允许在无法解析出外部可投递路径时回退到仅会话执行（例如内部/webchat 会话或多渠道配置不明确时）。
+- `bestEffortDeliver=false` 保持严格行为：无法解析或仅内部可用的投递目标会返回 `INVALID_REQUEST`。
+- `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 中保持稳定，并且是第三方客户端的预期基线。
 
-| Constant | Default | Source |
-| --- | --- | --- |
+| 常量 | 默认值 | 来源 |
+| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
 | `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`) |
-| 设备令牌关闭后的快速重试限制 | `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 间隔（`hello-ok` 之前） | `30_000` ms | `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.*` 来满足 connect 认证检查。
-- 私有入口的 `gateway.auth.mode: "none"` 会完全跳过共享密钥 connect 认证；不要在公共/不受信任的入口上暴露该模式。
-- 配对完成后，Gateway 网关会签发一个**设备令牌**，其作用域受限于连接角色 + 作用域。它会在 `hello-ok.auth.deviceToken` 中返回，客户端应将其持久化以用于后续连接。
-- 客户端应在任何成功连接后持久化主 `hello-ok.auth.deviceToken`。
-- 使用该**已存储**设备令牌重新连接时，也应复用该令牌已存储的已批准作用域集合。这样可以保留已经授予的读取/探测/状态访问权限，并避免重连时静默收缩为更窄的隐式仅 admin 作用域。
-- 客户端侧 connect 认证组装（`src/gateway/client.ts` 中的 `selectConnectAuth`）：
-  - `auth.password` 是独立项，只要设置就始终会被转发。
-  - `auth.token` 按优先级顺序填充：首先是显式共享令牌，然后是显式 `deviceToken`，最后是按 `deviceId` + `role` 键控的每设备存储令牌。
-  - 只有在上述都未解析出 `auth.token` 时，才会发送 `auth.bootstrapToken`。共享令牌或任何已解析的设备令牌都会抑制它。
-  - 在一次性 `AUTH_TOKEN_MISMATCH` 重试时，自动提升为已存储设备令牌仅对**受信任端点**开放——loopback，或带固定 `tlsFingerprint` 的 `wss://`。未固定证书的公共 `wss://` 不符合条件。
-- 额外的 `hello-ok.auth.deviceTokens` 条目是引导交接令牌。只有当连接使用了受信任传输（如 `wss://` 或 loopback/本地配对）上的引导认证时，才应持久化它们。
-- 如果客户端提供了**显式** `deviceToken` 或显式 `scopes`，则该调用方请求的作用域集仍然是权威值；只有当客户端正在复用已存储的每设备令牌时，才会复用缓存作用域。
-- 设备令牌可以通过 `device.token.rotate` 和 `device.token.revoke` 轮换/撤销（需要 `operator.pairing` 作用域）。
-- 令牌签发/轮换始终受限于该设备配对条目中记录的已批准角色集合；轮换令牌不能将设备扩展到配对审批从未授予的角色。
-- 对于已配对设备令牌会话，除非调用方还拥有 `operator.admin`，否则设备管理是自作用域的：非 admin 调用方只能移除/撤销/轮换其**自己的**设备条目。
-- `device.token.rotate` 还会根据调用方当前会话作用域检查所请求的 operator 作用域集。非 admin 调用方不能将令牌轮换为比其当前所持有更宽的 operator 作用域集。
+- 基于共享密钥的 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` 重试中，自动提升已存储设备令牌仅对**受信任端点**开放——loopback，或带固定 `tlsFingerprint` 的 `wss://`。未做固定的公共 `wss://` 不符合条件。
+- 附加的 `hello-ok.auth.deviceTokens` 条目是 bootstrap 交接令牌。仅当连接在受信任传输上使用 bootstrap 认证时才持久化它们，例如 `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 显示操作指引。
+- 客户端对 `AUTH_TOKEN_MISMATCH` 的行为：
+  - 受信任客户端可以尝试使用缓存的按设备令牌进行一次有界重试。
+  - 如果该重试失败，客户端应停止自动重连循环并提示 operator 采取操作。
 
 ## 设备身份 + 配对
 
-- Nodes 应包含稳定的设备身份（`device.id`），该身份由密钥对指纹派生。
-- Gateway 网关按设备 + 角色签发令牌。
-- 新的设备 ID 需要配对审批，除非启用了本地自动审批。
-- 配对自动审批以直接本地 local loopback 连接为中心。
-- OpenClaw 还具有一条狭窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。
-- 同主机 tailnet 或 LAN 连接在配对上仍被视为远程连接，仍需要审批。
-- 所有 WS 客户端都必须在 `connect` 期间包含 `device` 身份（operator + node）。
-  Control UI 仅可在以下模式中省略它：
+- 节点应包含稳定的设备身份（`device.id`），它来源于密钥对指纹。
+- Gateway 网关会按设备 + 角色签发令牌。
+- 新设备 id 需要配对批准，除非启用了本地自动批准。
+- 配对自动批准主要围绕直接的 local loopback 连接。
+- OpenClaw 还为受信任的共享密钥辅助流程提供了一个狭窄的后端/容器本地自连接路径。
+- 同一主机上的 tailnet 或 LAN 连接在配对上仍被视为远程连接，并且需要批准。
+- 所有 WS 客户端都必须在 `connect` 时包含 `device` 身份（operator + node）。
+  仅在以下模式下，控制 UI 才可以省略它：
   - `gateway.controlUi.allowInsecureAuth=true`，用于仅 localhost 的不安全 HTTP 兼容性。
-  - 成功的 `gateway.auth.mode: "trusted-proxy"` operator Control UI 认证。
-  - `gateway.controlUi.dangerouslyDisableDeviceAuth=true`（破窗应急，严重降低安全性）。
-- 所有连接都必须对服务端提供的 `connect.challenge` nonce 进行签名。
+  - 成功通过 `gateway.auth.mode: "trusted-proxy"` 的 operator 控制 UI 认证。
+  - `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`。
 
 常见迁移失败：
 
-| Message | details.code | 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` | 公钥格式/规范化失败。 |
 
 迁移目标：
 
 - 始终等待 `connect.challenge`。
-- 对包含服务端 nonce 的 v2 负载进行签名。
+- 对包含服务器 nonce 的 v2 负载进行签名。
 - 在 `connect.params.device.nonce` 中发送相同的 nonce。
 - 首选签名负载是 `v3`，它除了 device/client/role/scopes/token/nonce 字段外，还绑定了 `platform` 和 `deviceFamily`。
-- 为了兼容性，旧版 `v2` 签名仍然被接受，但已配对设备的元数据固定仍会在重连时控制命令策略。
+- 为了兼容性，旧版 `v2` 签名仍然可被接受，但已配对设备的元数据固定仍会在重连时控制命令策略。
 
 ## TLS + 固定
 
@@ -542,4 +535,4 @@ Gateway 网关将这些视为**声明**，并在服务端强制执行允许列
 
 ## 范围
 
-该协议公开了**完整的 Gateway 网关 API**（status、channels、models、chat、agent、sessions、nodes、approvals 等）。确切接口由 `src/gateway/protocol/schema.ts` 中的 TypeBox schemas 定义。
+此协议公开了**完整的 Gateway 网关 API**（状态、渠道、模型、聊天、智能体、会话、节点、批准等）。确切表面由 `src/gateway/protocol/schema.ts` 中的 TypeBox schema 定义。