chore(i18n): refresh zh-CN translations

2026-04-20 06:39:57 +00:00 · 2026-04-20 06:39:57 +00:00 · b3901b9fb8
commit b3901b9fb8
parent d702bc1930
5 changed files with 1363 additions and 1349 deletions
--- a/docs/zh-CN/channels/troubleshooting.md
+++ b/docs/zh-CN/channels/troubleshooting.md
@ -1,23 +1,23 @@
 ---
 read_when:
    - 渠道传输显示已连接，但回复失败
-    - 在深入查看提供商文档之前，你需要先进行渠道专属检查
-summary: 按渠道划分的快速故障排除，包含各渠道的故障特征和修复方法
+    - 在深入查看提供商文档之前，你需要先进行渠道专项检查
+summary: 按渠道划分的快速故障排除，包含各渠道的失败特征和修复方法
 title: 渠道故障排除
 x-i18n:
-    generated_at: "2026-04-05T08:18:13Z"
+    generated_at: "2026-04-20T06:31:00Z"
    model: gpt-5.4
    provider: openai
-    source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f
+    source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528
    source_path: channels/troubleshooting.md
    workflow: 15
 ---

 # 渠道故障排除

-当某个渠道已连接但行为不正确时，请使用此页面。
+当渠道已连接但行为异常时，请使用本页。

-## 命令排查阶梯
+## 命令检查阶梯

 请先按顺序运行以下命令：

@ -32,109 +32,110 @@ openclaw channels status --probe
 健康基线：

 - `Runtime: running`
- `RPC probe: ok`
+- `Connectivity probe: ok`
+- `Capability: read-only`、`write-capable` 或 `admin-capable`
 - 渠道探测显示传输已连接，并且在支持的情况下显示 `works` 或 `audit ok`

 ## WhatsApp

-### WhatsApp 故障特征
+### WhatsApp 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
-| 已连接但没有私信回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换私信策略/允许列表。 |
+| 已连接但没有 私信 回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换 私信 策略 / 允许列表。 |
 | 群组消息被忽略 | 检查配置中的 `requireMention` 和提及模式 | 提及机器人，或放宽该群组的提及策略。 |
-| 随机断开/重复登录循环 | `openclaw channels status --probe` + 日志 | 重新登录，并确认凭证目录状态正常。 |
+| 随机断开 / 反复重新登录 | `openclaw channels status --probe` + 日志 | 重新登录，并确认凭证目录状态正常。 |

-完整故障排除：[/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
+完整故障排除：[/channels/whatsapp#troubleshooting](/zh-CN/channels/whatsapp#troubleshooting)

 ## Telegram

-### Telegram 故障特征
+### Telegram 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | ----------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
-| 有 `/start` 但没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对，或更改私信策略。 |
-| 机器人在线，但群组始终没有响应 | 验证提及要求和机器人的隐私模式 | 关闭隐私模式以获得群组可见性，或提及机器人。 |
-| 发送失败并伴随网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS/IPv6/代理路由。 |
-| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件/Skills/自定义 Telegram 命令，或禁用原生菜单。 |
-| 升级后允许列表将你拦截 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 |
+| `/start` 之后没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对，或更改 私信 策略。 |
+| 机器人在线，但群组始终无响应 | 验证提及要求和机器人的隐私模式 | 为群组可见性禁用隐私模式，或提及机器人。 |
+| 发送失败并出现网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS / IPv6 / 代理路由。 |
+| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件 / Skills / 自定义 Telegram 命令，或禁用原生菜单。 |
+| 升级后允许列表把你拦住了 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 |

-完整故障排除：[/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
+完整故障排除：[/channels/telegram#troubleshooting](/zh-CN/channels/telegram#troubleshooting)

 ## Discord

-### Discord 故障特征
+### Discord 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
-| 机器人在线，但没有服务器回复 | `openclaw channels status --probe` | 允许该服务器/频道，并验证消息内容 intent。 |
-| 群组消息被忽略 | 检查日志中是否有提及门控丢弃记录 | 提及机器人，或将服务器/频道的 `requireMention: false`。 |
-| 私信回复缺失 | `openclaw pairing list discord` | 批准私信配对，或调整私信策略。 |
+| 机器人在线，但没有服务器回复 | `openclaw channels status --probe` | 允许对应服务器 / 渠道，并验证消息内容 intent。 |
+| 群组消息被忽略 | 检查日志中因提及门控而丢弃的记录 | 提及机器人，或将服务器 / 渠道的 `requireMention: false`。 |
+| 私信 回复缺失 | `openclaw pairing list discord` | 批准 私信 配对，或调整 私信 策略。 |

-完整故障排除：[/channels/discord#troubleshooting](/channels/discord#troubleshooting)
+完整故障排除：[/channels/discord#troubleshooting](/zh-CN/channels/discord#troubleshooting)

 ## Slack

-### Slack 故障特征
+### Slack 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Socket mode 已连接但没有响应 | `openclaw channels status --probe` | 验证 app token + bot token 以及所需权限范围；对于使用 SecretRef 的配置，留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
-| 私信被阻止 | `openclaw pairing list slack` | 批准配对，或放宽私信策略。 |
-| 频道消息被忽略 | 检查 `groupPolicy` 和频道允许列表 | 允许该频道，或将策略切换为 `open`。 |
+| Socket 模式已连接但没有响应 | `openclaw channels status --probe` | 验证 app token + bot token 以及所需作用域；在使用 SecretRef 的配置中，注意查看 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 |
+| 私信 被拦截 | `openclaw pairing list slack` | 批准配对，或放宽 私信 策略。 |
+| 渠道消息被忽略 | 检查 `groupPolicy` 和渠道允许列表 | 允许该渠道，或将策略切换为 `open`。 |

-完整故障排除：[/channels/slack#troubleshooting](/channels/slack#troubleshooting)
+完整故障排除：[/channels/slack#troubleshooting](/zh-CN/channels/slack#troubleshooting)

 ## iMessage 和 BlueBubbles

-### iMessage 和 BlueBubbles 故障特征
+### iMessage 和 BlueBubbles 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
-| 没有入站事件 | 验证 webhook/服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 |
-| 在 macOS 上可以发送但无法接收 | 检查 Messages 自动化的 macOS 隐私权限 | 重新授予 TCC 权限并重启渠道进程。 |
-| 私信发送者被阻止 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 |
+| 没有入站事件 | 验证 webhook / 服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 |
+| 在 macOS 上能发送但不能接收 | 检查 macOS 中 Messages 自动化的隐私权限 | 重新授予 TCC 权限并重启渠道进程。 |
+| 私信 发送者被拦截 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 |

 完整故障排除：

- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting)
- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
+- [/channels/imessage#troubleshooting](/zh-CN/channels/imessage#troubleshooting)
+- [/channels/bluebubbles#troubleshooting](/zh-CN/channels/bluebubbles#troubleshooting)

 ## Signal

-### Signal 故障特征
+### Signal 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
-| 守护进程可达，但机器人无响应 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL/账号和接收模式。 |
-| 私信被阻止 | `openclaw pairing list signal` | 批准发送者，或调整私信策略。 |
-| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者/群组，或放宽门控规则。 |
+| 守护进程可达，但机器人无响应 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL / 账户以及接收模式。 |
+| 私信 被拦截 | `openclaw pairing list signal` | 批准发送者，或调整 私信 策略。 |
+| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者 / 群组，或放宽门控条件。 |

-完整故障排除：[/channels/signal#troubleshooting](/channels/signal#troubleshooting)
+完整故障排除：[/channels/signal#troubleshooting](/zh-CN/channels/signal#troubleshooting)

 ## QQ Bot

-### QQ Bot 故障特征
+### QQ Bot 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
 | 机器人回复“去了火星” | 验证配置中的 `appId` 和 `clientSecret` | 设置凭证，或重启 Gateway 网关。 |
 | 没有入站消息 | `openclaw channels status --probe` | 在 QQ 开放平台上验证凭证。 |
 | 语音未转写 | 检查 STT 提供商配置 | 配置 `channels.qqbot.stt` 或 `tools.media.audio`。 |
-| 主动消息未送达 | 检查 QQ 平台的交互要求 | 如果近期没有交互，QQ 可能会阻止机器人主动发送消息。 |
+| 主动消息未送达 | 检查 QQ 平台的交互要求 | 如果近期没有交互，QQ 可能会阻止机器人主动发消息。 |

-完整故障排除：[/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting)
+完整故障排除：[/channels/qqbot#troubleshooting](/zh-CN/channels/qqbot#troubleshooting)

 ## Matrix

-### Matrix 故障特征
+### Matrix 失败特征

-| 症状 | 最快检查方式 | 修复方法 |
+| 症状 | 最快检查 | 修复方法 |
 | ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
 | 已登录但忽略房间消息 | `openclaw channels status --probe` | 检查 `groupPolicy`、房间允许列表和提及门控。 |
-| 私信不处理 | `openclaw pairing list matrix` | 批准发送者，或调整私信策略。 |
+| 私信 不处理 | `openclaw pairing list matrix` | 批准发送者，或调整 私信 策略。 |
 | 加密房间失败 | `openclaw matrix verify status` | 重新验证设备，然后检查 `openclaw matrix verify backup status`。 |
-| 备份恢复处于待处理/损坏状态 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或使用恢复密钥重新运行。 |
-| 交叉签名/bootstrap 看起来不正常 | `openclaw matrix verify bootstrap` | 一次性修复密钥存储、交叉签名和备份状态。 |
+| 备份恢复处于待处理 / 已损坏 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或使用恢复密钥重新运行。 |
+| 交叉签名 / 引导看起来异常 | `openclaw matrix verify bootstrap` | 一次性修复密钥存储、交叉签名和备份状态。 |

-完整设置和配置：[Matrix](/channels/matrix)
+完整设置和配置：[Matrix](/zh-CN/channels/matrix)
--- a/docs/zh-CN/gateway/index.md
+++ b/docs/zh-CN/gateway/index.md
@ -1,33 +1,33 @@
 ---
 read_when:
    - 运行或调试 Gateway 网关进程
-summary: Gateway 网关服务、生命周期和运维的运行手册
-title: Gateway 网关运行手册
+summary: Gateway 网关服务、生命周期与运维的操作手册
+title: Gateway 网关操作手册
 x-i18n:
-    generated_at: "2026-04-06T15:28:29Z"
+    generated_at: "2026-04-20T06:30:59Z"
    model: gpt-5.4
    provider: openai
-    source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd
+    source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8
    source_path: gateway/index.md
    workflow: 15
 ---

-# Gateway 网关运行手册
+# Gateway 网关操作手册

-将此页面用于 Gateway 网关服务的首日启动和后续运维。
+将此页面用于 Gateway 网关服务的第 1 天启动和第 2 天运维操作。

 <CardGroup cols={2}>
  <Card title="深度故障排除" icon="siren" href="/zh-CN/gateway/troubleshooting">
-    按症状优先的诊断，附带精确的命令步骤和日志特征。
+    按症状优先的诊断，提供精确的命令步骤和日志特征。
  </Card>
  <Card title="配置" icon="sliders" href="/zh-CN/gateway/configuration">
    面向任务的设置指南 + 完整配置参考。
  </Card>
  <Card title="密钥管理" icon="key-round" href="/zh-CN/gateway/secrets">
-    SecretRef 合约、运行时快照行为，以及迁移/重载操作。
+    `SecretRef` 合约、运行时快照行为，以及迁移/重新加载操作。
  </Card>
  <Card title="密钥计划合约" icon="shield-check" href="/zh-CN/gateway/secrets-plan-contract">
-    精确的 `secrets apply` 目标/路径规则，以及仅 ref 的 auth-profile 行为。
+    精确的 `secrets apply` 目标/路径规则，以及仅引用的 auth-profile 行为。
  </Card>
 </CardGroup>

@ -38,7 +38,7 @@ x-i18n:

 ```bash
 openclaw gateway --port 18789
-# 调试/跟踪输出镜像到 stdio
+# debug/trace 镜像输出到 stdio
 openclaw gateway --port 18789 --verbose
 # 强制终止所选端口上的监听器，然后启动
 openclaw gateway --force
@ -54,7 +54,7 @@ openclaw status
 openclaw logs --follow
 ```

-健康基线：`Runtime: running` 和 `RPC probe: ok`。
+健康基线：`Runtime: running`、`Connectivity probe: ok`，以及与你预期匹配的 `Capability: ...`。当你需要读取范围的 RPC 证明，而不仅仅是可达性时，请使用 `openclaw gateway status --require-rpc`。

  </Step>

@ -64,33 +64,35 @@ openclaw logs --follow
 openclaw channels status --probe
 ```

-当 Gateway 网关可达时，这会运行按账户划分的实时渠道探测和可选审计。
-如果 Gateway 网关不可达，CLI 会回退为仅基于配置的渠道摘要，而不是实时探测输出。
+当 Gateway 网关可达时，这会按账户运行实时的渠道探测和可选审计。
+如果 Gateway 网关不可达，CLI 会回退到仅基于配置的渠道摘要，
+而不是实时探测输出。

  </Step>
 </Steps>

 <Note>
-Gateway 网关配置重载会监听活动配置文件路径（从 profile/state 默认值解析，或在设置了 `OPENCLAW_CONFIG_PATH` 时使用该值）。
+Gateway 网关配置重载会监视当前激活的配置文件路径（从 profile/state 默认值解析，或在设置时使用 `OPENCLAW_CONFIG_PATH`）。
 默认模式为 `gateway.reload.mode="hybrid"`。
-首次成功加载后，运行中的进程会提供当前内存中的活动配置快照；成功重载后会以原子方式替换该快照。
+首次成功加载后，运行中的进程会提供当前激活的内存配置快照；成功重载后会原子性地替换该快照。
 </Note>

 ## 运行时模型

- 一个始终在线的进程，用于路由、控制平面和渠道连接。
- 一个复用的单端口，用于：
+- 一个始终运行的进程，用于路由、控制平面和渠道连接。
+- 一个用于以下内容的单一复用端口：
  - WebSocket 控制/RPC
-  - HTTP API、与 OpenAI 兼容（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`）
+  - HTTP API、OpenAI 兼容接口（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`）
  - Control UI 和 hooks
 - 默认绑定模式：`loopback`。
- 默认要求身份验证。共享密钥设置使用
+- 默认需要认证。共享密钥设置使用
  `gateway.auth.token` / `gateway.auth.password`（或
-  `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），非 loopback 的反向代理设置可以使用 `gateway.auth.mode: "trusted-proxy"`。
+  `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），而非 `loopback`
+  的反向代理设置可以使用 `gateway.auth.mode: "trusted-proxy"`。

-## 与 OpenAI 兼容的端点
+## OpenAI 兼容端点

-OpenClaw 当前最有价值的兼容性接口是：
+OpenClaw 现在最有价值的兼容性接口为：

 - `GET /v1/models`
 - `GET /v1/models/{id}`
@ -98,19 +100,19 @@ OpenClaw 当前最有价值的兼容性接口是：
 - `POST /v1/chat/completions`
 - `POST /v1/responses`

-为什么这组接口很重要：
+为什么这一组很重要：

- 大多数 Open WebUI、LobeChat 和 LibreChat 集成都会先探测 `/v1/models`。
- 许多 RAG 和记忆管道都依赖 `/v1/embeddings`。
+- 大多数 Open WebUI、LobeChat 和 LibreChat 集成会先探测 `/v1/models`。
+- 许多 RAG 和 memory 流水线依赖 `/v1/embeddings`。
 - 原生面向智能体的客户端越来越倾向于使用 `/v1/responses`。

 规划说明：

 - `/v1/models` 以智能体优先：它会返回 `openclaw`、`openclaw/default` 和 `openclaw/<agentId>`。
 - `openclaw/default` 是稳定别名，始终映射到已配置的默认智能体。
- 当你想覆盖后端提供商/模型时，请使用 `x-openclaw-model`；否则，选定智能体的常规模型和嵌入设置仍然会保持控制权。
+- 如果你想覆盖后端 provider/model，请使用 `x-openclaw-model`；否则将继续由所选智能体的常规模型和 embedding 设置进行控制。

-所有这些都运行在主 Gateway 网关端口上，并与 Gateway 网关其余 HTTP API 共享同一个受信任操作员身份验证边界。
+所有这些都运行在 Gateway 网关主端口上，并使用与 Gateway 网关其余 HTTP API 相同的可信操作员认证边界。

 ### 端口和绑定优先级

@ -124,9 +126,9 @@ OpenClaw 当前最有价值的兼容性接口是：
 | `gateway.reload.mode` | 行为 |
 | --------------------- | ------------------------------------------ |
 | `off`                 | 不进行配置重载 |
-| `hot`                 | 仅应用热安全变更 |
-| `restart`             | 遇到需要重载的变更时重启 |
-| `hybrid`（默认）    | 安全时热应用，需要时重启 |
+| `hot`                 | 仅应用热更新安全的变更 |
+| `restart`             | 遇到需要重启的变更时重启 |
+| `hybrid` （默认）    | 安全时热应用，需要时重启 |

 ## 操作员命令集

@ -143,14 +145,14 @@ openclaw doctor
 ```

 `gateway status --deep` 用于额外的服务发现（LaunchDaemons/systemd 系统
-单元/schtasks），而不是更深入的 RPC 健康探测。
+units/schtasks），而不是更深入的 RPC 健康探测。

 ## 多个 Gateway 网关（同一主机）

-大多数安装应当每台机器运行一个 Gateway 网关。单个 Gateway 网关可以托管多个
+大多数安装应在每台机器上运行一个 Gateway 网关。单个 Gateway 网关可以承载多个
 智能体和渠道。

-只有当你有意需要隔离或救援机器人时，才需要多个 Gateway 网关。
+只有当你明确需要隔离或一个救援 bot 时，才需要多个 Gateway 网关。

 有用的检查：

@ -159,12 +161,12 @@ openclaw gateway status --deep
 openclaw gateway probe
 ```

-预期结果：
+预期表现：

 - `gateway status --deep` 可能会报告 `Other gateway-like services detected (best effort)`
-  并在仍然存在陈旧的 launchd/systemd/schtasks 安装时打印清理提示。
- 当有多个目标响应时，`gateway probe` 可能会警告 `multiple reachable gateways`。
- 如果这是有意的，请为每个 Gateway 网关隔离端口、配置/state 和工作区根目录。
+  并在仍存在陈旧的 launchd/systemd/schtasks 安装时打印清理提示。
+- 当多个目标都有响应时，`gateway probe` 可能会警告 `multiple reachable gateways`。
+- 如果这是有意为之，请为每个 Gateway 网关隔离端口、配置/state 和 workspace 根目录。

 详细设置：[/gateway/multiple-gateways](/zh-CN/gateway/multiple-gateways)。

@ -177,18 +179,19 @@ openclaw gateway probe
 ssh -N -L 18789:127.0.0.1:18789 user@host
 ```

-然后在本地将客户端连接到 `ws://127.0.0.1:18789`。
+然后让客户端在本地连接到 `ws://127.0.0.1:18789`。

 <Warning>
-SSH 隧道不会绕过 Gateway 网关身份验证。对于共享密钥身份验证，即使通过隧道，客户端仍然
-必须发送 `token`/`password`。对于带身份模式，请求仍然必须满足该身份验证路径。
+SSH 隧道不会绕过 Gateway 网关认证。对于共享密钥认证，即使通过隧道，客户端
+仍然必须发送 `token`/`password`。对于带身份的模式，
+请求仍然必须满足该认证路径。
 </Warning>

-参见：[Remote Gateway](/zh-CN/gateway/remote)、[Authentication](/zh-CN/gateway/authentication)、[Tailscale](/zh-CN/gateway/tailscale)。
+参见：[远程 Gateway 网关](/zh-CN/gateway/remote)、[认证](/zh-CN/gateway/authentication)、[Tailscale](/zh-CN/gateway/tailscale)。

-## 监督与服务生命周期
+## 监管和服务生命周期

-对于接近生产环境的可靠性，请使用受监督的运行方式。
+为了获得接近生产环境的可靠性，请使用受监管的运行方式。

 <Tabs>
  <Tab title="macOS（launchd）">
@ -200,7 +203,7 @@ openclaw gateway restart
 openclaw gateway stop
 ```

-LaunchAgent 标签是 `ai.openclaw.gateway`（默认）或 `ai.openclaw.<profile>`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。
+LaunchAgent 标签为 `ai.openclaw.gateway`（默认）或 `ai.openclaw.<profile>`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。

  </Tab>

@ -212,13 +215,13 @@ systemctl --user enable --now openclaw-gateway[-<profile>].service
 openclaw gateway status
 ```

-要在注销后继续持久运行，请启用 lingering：
+要在登出后保持持久运行，请启用 lingering：

 ```bash
 sudo loginctl enable-linger <user>
 ```

-当你需要自定义安装路径时，可使用以下手动用户单元示例：
+当你需要自定义安装路径时，可使用手动用户 unit 示例：

 ```ini
 [Unit]
@ -251,30 +254,31 @@ openclaw gateway stop
 ```

 原生 Windows 托管启动使用名为 `OpenClaw Gateway`
-的计划任务（命名 profile 则为 `OpenClaw Gateway (<profile>)`）。如果计划任务
-创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹启动器，该启动器指向 state 目录中的 `gateway.cmd`。
+的计划任务（对于命名 profile，则为 `OpenClaw Gateway (<profile>)`）。如果计划任务
+创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹启动器，
+其指向 state 目录中的 `gateway.cmd`。

  </Tab>

  <Tab title="Linux（系统服务）">

-对多用户/始终在线的主机，请使用系统单元。
+对多用户/始终在线主机，请使用系统 unit。

 ```bash
 sudo systemctl daemon-reload
 sudo systemctl enable --now openclaw-gateway[-<profile>].service
 ```

-使用与用户单元相同的服务主体，但将其安装到
-`/etc/systemd/system/openclaw-gateway[-<profile>].service` 下，并在你的 `openclaw` 二进制位于其他位置时调整
-`ExecStart=`。
+使用与用户 unit 相同的服务主体，但将其安装到
+`/etc/systemd/system/openclaw-gateway[-<profile>].service` 下，并在你的
+`openclaw` 二进制文件位于其他位置时调整 `ExecStart=`。

  </Tab>
 </Tabs>

 ## 一台主机上的多个 Gateway 网关

-大多数设置应该只运行**一个** Gateway 网关。
+大多数设置应只运行**一个** Gateway 网关。
 只有在需要严格隔离/冗余时才使用多个（例如救援 profile）。

 每个实例的检查清单：
@ -291,7 +295,7 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla
 OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
 ```

-参见：[Multiple gateways](/zh-CN/gateway/multiple-gateways)。
+参见：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。

 ### 开发 profile 快速路径

@ -301,25 +305,25 @@ openclaw --dev gateway --allow-unconfigured
 openclaw --dev status
 ```

-默认值包括隔离的 state/config 和基础 Gateway 网关端口 `19001`。
+默认值包括隔离的 state/config，以及基础 Gateway 网关端口 `19001`。

 ## 协议快速参考（操作员视角）

 - 第一个客户端帧必须是 `connect`。
 - Gateway 网关返回 `hello-ok` 快照（`presence`、`health`、`stateVersion`、`uptimeMs`、limits/policy）。
 - `hello-ok.features.methods` / `events` 是保守的发现列表，而不是
-  对每个可调用辅助路由的自动生成完整导出。
+  每个可调用辅助路由的自动生成清单。
 - 请求：`req(method, params)` → `res(ok/payload|error)`。
 - 常见事件包括 `connect.challenge`、`agent`、`chat`、
  `session.message`、`session.tool`、`sessions.changed`、`presence`、`tick`、
-  `health`、`heartbeat`、配对/审批生命周期事件，以及 `shutdown`。
+  `health`、`heartbeat`、pairing/approval 生命周期事件以及 `shutdown`。

-智能体运行分两个阶段：
+智能体运行分为两个阶段：

 1. 立即接受确认（`status:"accepted"`）
-2. 最终完成响应（`status:"ok"|"error"`），中间会流式发送 `agent` 事件。
+2. 最终完成响应（`status:"ok"|"error"`），其间会流式发送 `agent` 事件。

-完整协议文档参见：[Gateway Protocol](/zh-CN/gateway/protocol)。
+查看完整协议文档：[Gateway 协议](/zh-CN/gateway/protocol)。

 ## 运维检查

@ -328,7 +332,7 @@ openclaw --dev status
 - 打开 WS 并发送 `connect`。
 - 预期收到带快照的 `hello-ok` 响应。

-### 就绪性
+### 就绪状态

 ```bash
 openclaw gateway status
@ -336,26 +340,26 @@ openclaw channels status --probe
 openclaw health
 ```

-### 间隙恢复
+### 缺口恢复

-事件不会重放。遇到序列缺口时，请先刷新状态（`health`、`system-presence`）再继续。
+事件不会重放。出现序列缺口时，在继续之前刷新状态（`health`、`system-presence`）。

 ## 常见故障特征

 | 特征 | 可能问题 |
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `refusing to bind gateway ... without auth`                    | 非 loopback 绑定且没有有效的 Gateway 网关身份验证路径 |
+| `refusing to bind gateway ... without auth`                    | 非 `loopback` 绑定，但没有有效的 Gateway 网关认证路径 |
 | `another gateway instance is already listening` / `EADDRINUSE` | 端口冲突 |
 | `Gateway start blocked: set gateway.mode=local`                | 配置被设为远程模式，或损坏配置中缺少本地模式标记 |
-| `unauthorized` during connect                                  | 客户端与 Gateway 网关之间的身份验证不匹配 |
+| `unauthorized` during connect                                  | 客户端与 Gateway 网关之间的认证不匹配 |

-如需完整诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。
+如需完整的诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。

 ## 安全保证

- 当 Gateway 网关不可用时，Gateway 网关协议客户端会快速失败（不会隐式回退到直接渠道）。
- 无效的首帧或非 `connect` 首帧会被拒绝并关闭连接。
- 优雅关闭会在 socket 关闭前发送 `shutdown` 事件。
+- 当 Gateway 网关不可用时，Gateway 协议客户端会快速失败（不会隐式回退到直接渠道）。
+- 无效的/非 `connect` 的首帧会被拒绝并关闭连接。
+- 优雅关闭会在 socket 关闭前发出 `shutdown` 事件。

 ---

@ -364,6 +368,6 @@ openclaw health
 - [故障排除](/zh-CN/gateway/troubleshooting)
 - [后台进程](/zh-CN/gateway/background-process)
 - [配置](/zh-CN/gateway/configuration)
- [健康状态](/zh-CN/gateway/health)
+- [健康](/zh-CN/gateway/health)
 - [Doctor](/zh-CN/gateway/doctor)
- [身份验证](/zh-CN/gateway/authentication)
+- [认证](/zh-CN/gateway/authentication)
--- a/docs/zh-CN/gateway/troubleshooting.md
+++ b/docs/zh-CN/gateway/troubleshooting.md
@ -1,14 +1,14 @@
 ---
 read_when:
-    - 故障排除中心已将你引导到此处，以进行更深入的诊断
-    - 你需要按症状分类且稳定的运行手册章节，并提供精确命令
+    - 故障排除中心将你指向这里，以便进行更深入的诊断
+    - 你需要基于稳定症状的运行手册章节，并提供精确命令
 summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册
 title: 故障排除
 x-i18n:
-    generated_at: "2026-04-10T20:41:20Z"
+    generated_at: "2026-04-20T06:31:00Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5
+    source_hash: 853275aaf4ebddb9d2fd358df2e9fdc893dafdc7960d69c4f145ce615d5cbc1e
    source_path: gateway/troubleshooting.md
    workflow: 15
 ---
@ -16,11 +16,11 @@ x-i18n:
 # 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` 和 `RPC probe: ok`。
+- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。
 - `openclaw doctor` 报告没有阻塞性的配置或服务问题。
- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。
+- `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,17 +47,17 @@ openclaw models status
 openclaw config get agents.defaults.models
 ```

-请检查：
+检查以下内容：

- 所选的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。
- 当前的 Anthropic 凭证不具备长上下文使用资格。
+- 选中的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。
+- 当前的 Anthropic 凭证没有长上下文使用资格。
 - 请求只会在需要走 1M beta 路径的长会话或模型运行中失败。

 修复选项：

-1. 为该模型禁用 `context1m`，回退到普通上下文窗口。
+1. 为该模型禁用 `context1m`，回退到正常上下文窗口。
 2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。
-3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时运行仍可继续。
+3. 配置回退模型，这样当 Anthropic 长上下文请求被拒绝时，运行仍可继续。

 相关内容：

@ -65,12 +65,12 @@ openclaw config get agents.defaults.models
 - [/reference/token-use](/zh-CN/reference/token-use)
 - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/zh-CN/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)

-## 本地 OpenAI 兼容后端可通过直接探测，但智能体运行失败
+## 本地 OpenAI 兼容后端直接探测通过，但智能体运行失败

-在以下情况使用本节：
+当出现以下情况时，使用本节：

- `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。
+- 很小的直接请求成功，但 OpenClaw 智能体运行因后端或模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端无法处理更大的智能体运行时提示词形状。
+- 禁用工具后失败减少但没有消失 → 工具 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 智能体轮次仍在后端内部崩溃，请将其视为上游服务器或模型限制，并基于已接受的 payload 形状向上游提交复现案例。

 相关内容：

@ -107,9 +107,9 @@ openclaw logs --follow
 - [/gateway/configuration](/zh-CN/gateway/configuration)
 - [/gateway/configuration-reference#openai-compatible-endpoints](/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 是否不匹配。
+- 私信发送者的配对仍在等待批准。
+- 群组提及门控（`requireMention`、`mentionPatterns`）。
+- 渠道或群组允许列表不匹配。

 常见特征：

- `drop guild message (mention required` → 群消息在被提及之前会被忽略。
- `pairing request` → 发送者需要获批。
- `blocked` / `allowlist` → 发送者或渠道被策略过滤。
+- `drop guild message (mention required` → 群消息会被忽略，直到出现提及。
+- `pairing request` → 发送者需要审批。
+- `blocked` / `allowlist` → 发送者或渠道被策略过滤了。

 相关内容：

@ -137,9 +137,9 @@ openclaw logs --follow
 - [/channels/pairing](/zh-CN/channels/pairing)
 - [/channels/groups](/zh-CN/channels/groups)

-## Dashboard 控制 UI 连接问题
+## 仪表板控制 UI 连接问题

-当 dashboard/控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
+当仪表板 / 控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。

 ```bash
 openclaw gateway status
@ -149,36 +149,36 @@ openclaw doctor
 openclaw gateway status --json
 ```

-请检查：
+检查以下内容：

- 探测 URL 和 dashboard URL 是否正确。
- 客户端与 Gateway 网关之间的认证模式或令牌是否不匹配。
- 是否在需要设备身份的场景下使用了 HTTP。
+- 正确的探测 URL 和仪表板 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`）。
- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的载荷，或使用了过期时间戳。
- `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备令牌执行一次可信重试。
- 该缓存令牌重试会复用与已配对设备令牌一同存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保持其请求的作用域集合不变。
- 在该重试路径之外，连接认证优先级依次为：显式共享令牌/密码优先，然后是显式 `deviceToken`，再然后是已存储设备令牌，最后是 bootstrap 令牌。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个错误并发重试，第二次可能显示 `retry later`，而不是出现两个普通的不匹配错误。
- 浏览器源 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 源会使用单独的桶。
- 在该重试之后仍反复出现 `unauthorized` → 共享令牌或设备令牌已漂移；如果需要，请刷新令牌配置，并重新批准/轮换设备令牌。
- `gateway connect failed:` → 主机、端口或 URL 目标错误。
+- `device identity required` → 非安全上下文或缺少设备认证。
+- `origin not allowed` → 浏览器的 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器源发起连接，但未显式加入允许列表）。
+- `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。
+- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的 payload（或使用了过期时间戳）。
+- 带有 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可以使用缓存的设备 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 源会使用单独的桶。
+- 在该重试之后仍然重复出现 `unauthorized` → 共享 token 或设备 token 已漂移；如有需要，请刷新 token 配置并重新批准或轮换设备 token。
+- `gateway connect failed:` → host / port / url 目标错误。

-### 认证详情代码速查表
+### 认证细节代码快速对照表

-使用失败的 `connect` 响应中的 `error.details.code` 来决定下一步操作：
+使用失败 `connect` 响应中的 `error.details.code` 来决定下一步操作：

-| 详情代码                     | 含义                              | 建议操作                                                                                                                                                                                                                                                                                 |
-| ---------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AUTH_TOKEN_MISSING`         | 客户端未发送必需的共享令牌。      | 在客户端中粘贴/设置令牌后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。                                                                                                                                                         |
-| `AUTH_TOKEN_MISMATCH`        | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方则保持请求的作用域不变。如果仍失败，请运行 [token drift recovery checklist](/cli/devices#token-drift-recovery-checklist)。                              |
-| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存令牌已过期或被撤销。    | 使用 [devices CLI](/cli/devices) 轮换或重新批准设备令牌，然后重新连接。                                                                                                                                                                                                                 |
-| `PAIRING_REQUIRED`           | 设备身份已知，但未获批用于此角色。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。                                                                                                                                                                                                  |
+| 细节代码 | 含义 | 建议操作 |
+| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AUTH_TOKEN_MISSING` | 客户端没有发送必需的共享 token。 | 在客户端中粘贴或设置该 token，然后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
+| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储的已批准 scope；显式 `deviceToken` / `scopes` 调用方则保留请求的 scope。如果仍然失败，请运行 [token 漂移恢复清单](/cli/devices#token-drift-recovery-checklist)。 |
+| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备 token 已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换或重新批准设备 token，然后重新连接。 |
+| `PAIRING_REQUIRED` | 设备身份已知，但尚未被批准用于此角色。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。 |

 设备认证 v2 迁移检查：

@ -188,16 +188,16 @@ openclaw doctor
 openclaw gateway status
 ```

-如果日志显示 nonce/签名错误，请更新正在连接的客户端，并验证它是否：
+如果日志显示 nonce 或 signature 错误，请更新正在连接的客户端，并确认它：

 1. 等待 `connect.challenge`
-2. 对绑定该 challenge 的载荷进行签名
-3. 在 `connect.params.device.nonce` 中发送相同的 challenge nonce
+2. 对绑定到 challenge 的 payload 进行签名
+3. 使用相同的 challenge nonce 发送 `connect.params.device.nonce`

-如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝：
+如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：

- 已配对设备令牌会话只能管理**它们自己的**设备，除非调用方同时具有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方会话已经持有的 operator 作用域
+- 已配对设备的 token 会话只能管理**它们自己的**设备，除非调用方同时具有 `operator.admin`
+- `openclaw devices rotate --scope ...` 只能请求调用方当前会话已经持有的 operator scope

 相关内容：

@ -209,7 +209,7 @@ openclaw gateway status

 ## Gateway 网关服务未运行

-当服务已安装但进程无法持续运行时使用本节。
+当服务已安装但进程无法保持运行时，使用本节。

 ```bash
 openclaw gateway status
@ -219,20 +219,20 @@ openclaw doctor
 openclaw gateway status --deep   # 也会扫描系统级服务
 ```

-请检查：
+检查以下内容：

- `Runtime: stopped` 以及退出提示。
- 服务配置不匹配（`Config (cli)` 对比 `Config (service)`）。
+- `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 网关认证路径（令牌/密码，或在已配置时使用 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 / password，或已配置的 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)。

 相关内容：

@ -242,7 +242,7 @@ openclaw gateway status --deep   # 也会扫描系统级服务

 ## Gateway 网关探测警告

-当 `openclaw gateway probe` 能探测到目标，但仍打印警告块时使用本节。
+当 `openclaw gateway probe` 能探测到目标，但仍打印出警告块时，使用本节。

 ```bash
 openclaw gateway probe
@ -250,17 +250,18 @@ openclaw gateway probe --json
 openclaw gateway probe --ssh user@gateway-host
 ```

-请检查：
+检查以下内容：

 - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
- 警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域或未解析的认证引用有关。
+- 警告是否与 SSH 回退、多个 Gateway 网关、缺失 scope，或未解析的认证引用有关。

 常见特征：

- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了已配置的目标或 loopback 目标的直接探测。
- `multiple reachable gateways detected` → 有多个目标作出响应。通常这表示有意的多 Gateway 网关部署，或存在陈旧/重复的监听器。
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接已成功，但详细 RPC 受作用域限制；请配对设备身份，或使用带有 `operator.read` 的凭证。
- 未解析的 `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 受 scope 限制；请配对设备身份或使用带有 `operator.read` 的凭证。
+- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但该客户端在获得正常 operator 访问前仍需要完成配对或审批。
+- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标的认证材料不可用。

 相关内容：

@ -268,9 +269,9 @@ openclaw gateway probe --ssh user@gateway-host
 - [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)
 - [/gateway/remote](/zh-CN/gateway/remote)

-## 渠道已连接但消息不流转
+## 渠道已连接但消息不流动

-如果渠道状态显示已连接，但消息流转已中断，请重点检查策略、权限以及渠道特定的投递规则。
+如果渠道状态显示已连接，但消息流已中断，请重点检查策略、权限和渠道特定的投递规则。

 ```bash
 openclaw channels status --probe
@ -280,16 +281,16 @@ openclaw logs --follow
 openclaw config get channels
 ```

-请检查：
+检查以下内容：

 - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
- 群组 allowlist 和提及要求。
+- 群组允许列表和提及要求。
 - 缺失的渠道 API 权限或 scopes。

 常见特征：

 - `mention required` → 消息因群组提及策略而被忽略。
- `pairing` / 待批准痕迹 → 发送者尚未获批。
+- `pairing` / 待审批痕迹 → 发送者尚未获批。
 - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证或权限问题。

 相关内容：
@ -301,7 +302,7 @@ openclaw config get channels

 ## Cron 和 heartbeat 投递

-如果 cron 或 heartbeat 没有运行，或者运行了但未投递，请先验证调度器状态，再检查投递目标。
+如果 cron 或 heartbeat 没有运行，或者运行了但没有投递，请先验证调度器状态，再检查投递目标。

 ```bash
 openclaw cron status
@ -311,9 +312,9 @@ openclaw system heartbeat last
 openclaw logs --follow
 ```

-请检查：
+检查以下内容：

- Cron 已启用，并存在下一次唤醒时间。
+- Cron 已启用，并且存在下次唤醒时间。
 - 作业运行历史状态（`ok`、`skipped`、`error`）。
 - Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。

@ -321,11 +322,11 @@ openclaw logs --follow

 - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
 - `cron: timer tick failed` → 调度器 tick 失败；请检查文件、日志或运行时错误。
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时间窗口之外。
+- `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`。
+- `heartbeat: unknown accountId` → heartbeat 投递目标使用了无效的 account id。
+- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖配置）被设置为 `block`。

 相关内容：

@ -335,7 +336,7 @@ openclaw logs --follow

 ## 已配对节点的工具失败

-如果某个节点已完成配对，但工具调用失败，请分别隔离前台状态、权限状态和批准状态。
+如果节点已配对，但工具失败，请分别排查前台状态、权限状态和审批状态。

 ```bash
 openclaw nodes status
@ -345,18 +346,18 @@ openclaw logs --follow
 openclaw status
 ```

-请检查：
+检查以下内容：

- 节点在线，并具有预期能力。
- 相机、麦克风、位置、屏幕等操作系统权限是否已授予。
- Exec 批准和 allowlist 状态。
+- 节点在线，并具备预期能力。
+- 相机、麦克风、位置、屏幕等操作系统权限已授予。
+- Exec 审批和允许列表状态。

 常见特征：

 - `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。
 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。
- `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 拦截。
+- `SYSTEM_RUN_DENIED: approval required` → exec 审批待处理。
+- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表拦截。

 相关内容：

@ -366,7 +367,7 @@ openclaw status

 ## 浏览器工具失败

-当浏览器工具操作失败，但 Gateway 网关本身健康时使用本节。
+当浏览器工具操作失败，但 Gateway 网关本身是健康的时，使用本节。

 ```bash
 openclaw browser status
@ -376,7 +377,7 @@ openclaw logs --follow
 openclaw doctor
 ```

-请检查：
+检查以下内容：

 - 是否设置了 `plugins.allow`，并且其中包含 `browser`。
 - 浏览器可执行文件路径是否有效。
@ -385,34 +386,34 @@ openclaw doctor

 常见特征：

- `unknown command "browser"` 或 `unknown command 'browser'` → 内置的 browser 插件被 `plugins.allow` 排除了。
- 浏览器工具缺失或不可用，而 `browser.enabled=true` → `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 使用了错误或超出范围的端口。
- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有任何已打开的本地 Chrome 标签页。
- `Remote CDP for profile "<name>" is not reachable` → 从 Gateway 网关主机无法访问所配置的远程 CDP 端点。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only 配置文件没有可达目标，或者 HTTP 端点有响应但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装不包含完整的 Playwright 包；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 配置文件中的对话框钩子不支持超时覆盖。
- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍要求使用托管浏览器或原始 CDP 配置文件。
- attach-only 或远程 CDP 配置文件中存在陈旧的视口 / 深色模式 / 语言区域 / 离线覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 关闭当前控制会话，释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。
+- `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 包；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 配置文件上的对话框钩子不支持超时覆盖。
+- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置文件。
+- 在仅附加或远程 CDP 配置文件上出现陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭当前活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。

 相关内容：

 - [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
 - [/tools/browser](/zh-CN/tools/browser)

-## 如果你升级后某些功能突然损坏
+## 如果你升级后突然出现问题

-大多数升级后的故障都源于配置漂移，或者当前开始强制执行了更严格的默认值。
+大多数升级后的故障都源于配置漂移，或更严格的默认行为现在开始生效。

-### 1）认证和 URL 覆盖行为已更改
+### 1) 认证和 URL 覆盖行为已改变

 ```bash
 openclaw gateway status
@ -421,17 +422,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` → 端点可达，但认证错误。

-### 2）绑定和认证护栏更严格了
+### 2) 绑定和认证护栏更加严格

 ```bash
 openclaw config get gateway.bind
@ -441,17 +442,17 @@ openclaw gateway status
 openclaw logs --follow
 ```

-检查内容：
+需要检查的内容：

- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或已正确配置的非 loopback `trusted-proxy` 部署。
+- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token / password 认证，或正确配置的非 loopback `trusted-proxy` 部署。
 - 旧键如 `gateway.token` 不能替代 `gateway.auth.token`。

 常见特征：

- `refusing to bind gateway ... without auth` → 非 loopback 绑定但没有有效的 Gateway 网关认证路径。
- `RPC probe: failed` 而运行时仍在运行 → Gateway 网关存活，但当前认证或 URL 无法访问。
+- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址。
+- `Connectivity probe: failed`，但运行时处于运行状态 → Gateway 网关活着，但用当前认证或 URL 无法访问。

-### 3）配对和设备身份状态已更改
+### 3) 配对和设备身份状态已改变

 ```bash
 openclaw devices list
@ -460,17 +461,17 @@ openclaw logs --follow
 openclaw doctor
 ```

-检查内容：
+需要检查的内容：

- dashboard/节点是否存在待批准的设备请求。
- 在策略或身份变化后，私信是否存在待批准配对。
+- 仪表板或节点是否有待批准的设备审批。
+- 在策略或身份变更后，私信配对审批是否仍待处理。

 常见特征：

- `device identity required` → 未满足设备认证要求。
- `pairing required` → 发送者或设备必须先获批。
+- `device identity required` → 设备认证未满足。
+- `pairing required` → 发送者或设备必须获批。

-如果在这些检查之后，服务配置和运行时仍然不一致，请使用相同的 profile/状态目录重新安装服务元数据：
+如果在完成以上检查后，服务配置与运行时仍然不一致，请从相同的 profile / 状态目录重新安装服务元数据：

 ```bash
 openclaw gateway install --force
--- a/docs/zh-CN/help/faq.md
+++ b/docs/zh-CN/help/faq.md
--- a/docs/zh-CN/help/troubleshooting.md
+++ b/docs/zh-CN/help/troubleshooting.md
@ -2,24 +2,24 @@
 read_when:
    - OpenClaw 无法正常工作，而你需要最快速的修复路径
    - 在深入查看详细操作手册之前，你想先走一遍分诊流程
-summary: OpenClaw 的按症状分类故障排除中心
-title: 常规故障排除
+summary: OpenClaw 的按症状优先故障排除中心
+title: 常见故障排除
 x-i18n:
-    generated_at: "2026-04-10T20:41:21Z"
+    generated_at: "2026-04-20T06:31:02Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a
+    source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88
    source_path: help/troubleshooting.md
    workflow: 15
 ---

 # 故障排除

-如果你只有 2 分钟，就把这个页面当作分诊入口。
+如果你只有 2 分钟，把这个页面当作分诊入口。

 ## 最初的六十秒

-按顺序运行这一组完全相同的命令：
+按顺序运行下面这组精确的排查步骤：

 ```bash
 openclaw status
@ -31,15 +31,15 @@ openclaw channels status --probe
 openclaw logs --follow
 ```

-一行概括“正常输出”：
+一行看懂“正常输出”：

 - `openclaw status` → 显示已配置的渠道，且没有明显的认证错误。
- `openclaw status --all` → 提供完整报告，并且可以分享。
- `openclaw gateway probe` → 预期的 Gateway 网关目标可访问（`Reachable: yes`）。“`RPC: limited - missing scope: operator.read`”表示诊断能力受限，不是连接失败。
- `openclaw gateway status` → 显示 `Runtime: running` 和 `RPC probe: ok`。
+- `openclaw status --all` → 完整报告存在，并且可以分享。
+- `openclaw gateway probe` → 可以访问预期的 Gateway 网关目标（`Reachable: yes`）。`Capability: ...` 会告诉你探测能够证明的认证级别，而 `Read probe: limited - missing scope: operator.read` 表示诊断能力降级，不是连接失败。
+- `openclaw gateway status` → 显示 `Runtime: running`、`Connectivity probe: ok`，以及合理的 `Capability: ...` 行。如果你还需要验证读权限范围的 RPC 证明，请使用 `--require-rpc`。
 - `openclaw doctor` → 没有阻塞性的配置或服务错误。
- `openclaw channels status --probe` → 如果 Gateway 网关可访问，会返回每个账户的实时传输状态，以及诸如 `works` 或 `audit ok` 之类的探测 / 审计结果；如果 Gateway 网关不可访问，该命令会回退为仅基于配置的摘要。
- `openclaw logs --follow` → 活动持续稳定，没有重复出现的致命错误。
+- `openclaw channels status --probe` → 当 Gateway 网关可达时，会返回每个账户的实时传输状态，以及诸如 `works` 或 `audit ok` 这样的探测/审计结果；如果 Gateway 网关不可达，该命令会回退为仅配置摘要。
+- `openclaw logs --follow` → 活动持续稳定，没有反复出现的致命错误。

 ## Anthropic 长上下文 429

@ -47,27 +47,29 @@ openclaw logs --follow
 `HTTP 429: rate_limit_error: Extra usage is required for long context requests`，
 请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。

-## 本地兼容 OpenAI 的后端可直接工作，但在 OpenClaw 中失败
+## 本地 OpenAI 兼容后端直接可用，但在 OpenClaw 中失败

-如果你的本地或自托管 `/v1` 后端可以响应简短的直接
-`/v1/chat/completions` 探测，但在 `openclaw infer model run` 或正常的智能体回合中失败：
+如果你的本地或自托管 `/v1` 后端可以响应小型直接
+`/v1/chat/completions` 探测，但在 `openclaw infer model run` 或正常
+智能体 回合中失败：

-1. 如果错误提到 `messages[].content` 期望为字符串，请设置
+1. 如果错误提到 `messages[].content` 需要字符串，设置
   `models.providers.<provider>.models[].compat.requiresStringContent: true`。
-2. 如果该后端仍然只在 OpenClaw 智能体回合中失败，请设置
-   `models.providers.<provider>.models[].compat.supportsTools: false`，然后重试。
-3. 如果很小的直接调用仍然可用，但更大的 OpenClaw 提示词会导致后端崩溃，请将剩余问题视为上游模型 / 服务器限制，并继续查看详细操作手册：
+2. 如果该后端仍然只在 OpenClaw 智能体 回合中失败，设置
+   `models.providers.<provider>.models[].compat.supportsTools: false` 然后重试。
+3. 如果极小的直接调用仍然可用，但更大的 OpenClaw 提示词会让后端崩溃，将剩余问题视为上游模型/服务器限制，并继续查看详细操作手册：
   [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)

-## 插件安装失败并提示缺少 openclaw extensions
+## 插件安装失败，提示缺少 openclaw extensions

-如果安装失败并显示 `package.json missing openclaw.extensions`，说明该插件包仍在使用 OpenClaw 已不再接受的旧结构。
+如果安装失败并显示 `package.json missing openclaw.extensions`，说明该插件包
+使用了 OpenClaw 已不再接受的旧结构。

-在插件包中修复：
+在插件包中这样修复：

 1. 在 `package.json` 中添加 `openclaw.extensions`。
 2. 将入口指向已构建的运行时文件（通常是 `./dist/index.js`）。
-3. 重新发布插件，然后再次运行 `openclaw plugins install <package>`。
+3. 重新发布该插件，然后再次运行 `openclaw plugins install <package>`。

 示例：

@ -87,22 +89,22 @@ openclaw logs --follow

 ```mermaid
 flowchart TD
-  A[OpenClaw 无法正常工作] --> B{首先是哪里出问题}
+  A[OpenClaw 无法正常工作] --> B{最先出问题的是什么}
  B --> C[没有回复]
  B --> D[仪表板或 Control UI 无法连接]
  B --> E[Gateway 网关无法启动或服务未运行]
-  B --> F[渠道已连接，但消息不流动]
-  B --> G[Cron 或心跳未触发或未送达]
-  B --> H[节点已配对，但 camera canvas screen exec 工具失败]
+  B --> F[渠道已连接但消息不流转]
+  B --> G[Cron 或心跳没有触发或没有送达]
+  B --> H[节点已配对，但 camera canvas screen exec 失败]
  B --> I[浏览器工具失败]

-  C --> C1[/“没有回复”部分/]
-  D --> D1[/“Control UI”部分/]
-  E --> E1[/“Gateway 网关”部分/]
-  F --> F1[/“渠道流转”部分/]
-  G --> G1[/“自动化”部分/]
-  H --> H1[/“节点工具”部分/]
-  I --> I1[/“浏览器”部分/]
+  C --> C1[/无回复部分/]
+  D --> D1[/Control UI 部分/]
+  E --> E1[/Gateway 网关部分/]
+  F --> F1[/渠道流转部分/]
+  G --> G1[/自动化部分/]
+  H --> H1[/节点工具部分/]
+  I --> I1[/浏览器部分/]
 ```

 <AccordionGroup>
@ -118,14 +120,15 @@ flowchart TD
    正常输出应类似于：

    - `Runtime: running`
-    - `RPC probe: ok`
+    - `Connectivity probe: ok`
+    - `Capability: read-only`、`write-capable` 或 `admin-capable`
    - 你的渠道显示传输已连接，并且在支持的情况下，`channels status --probe` 中会显示 `works` 或 `audit ok`
-    - 发送方显示为已获准（或者私信策略为开放 / 允许列表）
+    - 发送方显示已获批准（或 私信 策略为开放/允许列表）

    常见日志特征：

    - `drop guild message (mention required` → Discord 中的提及门控阻止了该消息。
-    - `pairing request` → 发送方尚未获准，正在等待私信配对批准。
+    - `pairing request` → 发送方未获批准，正在等待 私信 配对批准。
    - 渠道日志中的 `blocked` / `allowlist` → 发送方、房间或群组被过滤。

    详细页面：
@ -147,20 +150,21 @@ flowchart TD

    正常输出应类似于：

-    - 在 `openclaw gateway status` 中显示 `Dashboard: http://...`
-    - `RPC probe: ok`
+    - `openclaw gateway status` 中显示 `Dashboard: http://...`
+    - `Connectivity probe: ok`
+    - `Capability: read-only`、`write-capable` 或 `admin-capable`
    - 日志中没有认证循环

    常见日志特征：

-    - `device identity required` → HTTP / 非安全上下文无法完成设备认证。
-    - `origin not allowed` → 浏览器 `Origin` 不在 Control UI 的 Gateway 网关目标允许范围内。
-    - 带有重试提示的 `AUTH_TOKEN_MISMATCH`（`canRetryWithDeviceToken=true`）→ 可能会自动执行一次受信任的设备令牌重试。
+    - `device identity required` → HTTP/非安全上下文无法完成设备认证。
+    - `origin not allowed` → 浏览器 `Origin` 不被该 Control UI Gateway 网关目标允许。
+    - 带有重试提示（`canRetryWithDeviceToken=true`）的 `AUTH_TOKEN_MISMATCH` → 可能会自动进行一次可信设备令牌重试。
    - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则会保留其请求的作用域集合。
-    - 在异步 Tailscale Serve 的 Control UI 路径中，同一 `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。
-    - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → 来自同一 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。
-    - 在那次重试之后仍然反复出现 `unauthorized` → 错误的令牌 / 密码、认证模式不匹配，或已配对设备令牌过期。
-    - `gateway connect failed:` → UI 正在指向错误的 URL / 端口，或 Gateway 网关不可达。
+    - 在异步 Tailscale Serve Control UI 路径中，对于同一个 `{scope, ip}` 的失败尝试会在限制器记录失败之前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。
+    - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → 来自同一个 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。
+    - 在该重试之后反复出现 `unauthorized` → 令牌/密码错误、认证模式不匹配，或已配对设备令牌已过期。
+    - `gateway connect failed:` → UI 指向了错误的 URL/端口，或 Gateway 网关不可达。

    详细页面：

@ -183,12 +187,13 @@ flowchart TD

    - `Service: ... (loaded)`
    - `Runtime: running`
-    - `RPC probe: ok`
+    - `Connectivity probe: ok`
+    - `Capability: read-only`、`write-capable` 或 `admin-capable`

    常见日志特征：

    - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或者配置文件缺少本地模式标记，需要修复。
-    - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（令牌 / 密码，或按配置启用的受信任代理）。
+    - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径（令牌/密码，或已配置的 trusted-proxy）的情况下拒绝绑定非 loopback 地址。
    - `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。

    详细页面：
@ -199,7 +204,7 @@ flowchart TD

  </Accordion>

-  <Accordion title="渠道已连接，但消息不流动">
+  <Accordion title="渠道已连接但消息不流转">
    ```bash
    openclaw status
    openclaw gateway status
@ -211,14 +216,14 @@ flowchart TD
    正常输出应类似于：

    - 渠道传输已连接。
-    - 配对 / 允许列表检查通过。
-    - 在要求提及的地方，提及已被识别。
+    - 配对/允许列表检查已通过。
+    - 在需要时，提及已被检测到。

    常见日志特征：

-    - `mention required` → 群组中的提及门控阻止了处理。
-    - `pairing` / `pending` → 私信发送方尚未获准。
-    - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → 渠道权限令牌问题。
+    - `mention required` → 群组提及门控阻止了处理。
+    - `pairing` / `pending` → 私信 发送方尚未获批准。
+    - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限令牌问题。

    详细页面：

@ -227,7 +232,7 @@ flowchart TD

  </Accordion>

-  <Accordion title="Cron 或心跳未触发或未送达">
+  <Accordion title="Cron 或心跳没有触发或没有送达">
    ```bash
    openclaw status
    openclaw gateway status
@ -239,17 +244,17 @@ flowchart TD

    正常输出应类似于：

-    - `cron.status` 显示为已启用，并有下一次唤醒时间。
+    - `cron.status` 显示已启用，并带有下一次唤醒时间。
    - `cron runs` 显示最近的 `ok` 条目。
-    - 心跳已启用，并且不在活跃时间之外。
+    - 心跳已启用，且不在活跃时段之外。

    常见日志特征：

    - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
-    - 带有 `reason=quiet-hours` 的 `heartbeat skipped` → 当前处于配置的活跃时间之外。
-    - 带有 `reason=empty-heartbeat-file` 的 `heartbeat skipped` → `HEARTBEAT.md` 存在，但只包含空白 / 仅标题的脚手架内容。
-    - 带有 `reason=no-tasks-due` 的 `heartbeat skipped` → `HEARTBEAT.md` 的任务模式已启用，但当前没有任何任务间隔到期。
-    - 带有 `reason=alerts-disabled` 的 `heartbeat skipped` → 所有心跳可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。
+    - 带有 `reason=quiet-hours` 的 `heartbeat skipped` → 当前不在配置的活跃时段内。
+    - 带有 `reason=empty-heartbeat-file` 的 `heartbeat skipped` → `HEARTBEAT.md` 存在，但只包含空白/仅标题的骨架内容。
+    - 带有 `reason=no-tasks-due` 的 `heartbeat skipped` → `HEARTBEAT.md` 任务模式已启用，但尚无任务到达间隔时间。
+    - 带有 `reason=alerts-disabled` 的 `heartbeat skipped` → 所有心跳可见性均被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。
    - `requests-in-flight` → 主通道繁忙；心跳唤醒被延后。
    - `unknown accountId` → 心跳投递目标账户不存在。

@ -261,7 +266,7 @@ flowchart TD

    </Accordion>

-    <Accordion title="节点已配对，但工具在 camera canvas screen exec 上失败">
+    <Accordion title="节点已配对，但工具中的 camera canvas screen exec 失败">
      ```bash
      openclaw status
      openclaw gateway status
@ -272,16 +277,16 @@ flowchart TD

      正常输出应类似于：

-      - 节点列出为已连接，并已为 `node` 角色完成配对。
-      - 你调用的命令所需能力存在。
+      - 节点显示为已连接，并且已按 `node` 角色完成配对。
+      - 你正在调用的命令具备相应能力。
      - 该工具的权限状态已授予。

      常见日志特征：

-      - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。
+      - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切到前台。
      - `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝或缺失。
-      - `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待中。
-      - `SYSTEM_RUN_DENIED: allowlist miss` → 该命令不在 exec 允许列表中。
+      - `SYSTEM_RUN_DENIED: approval required` → exec 审批仍在等待中。
+      - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 允许列表中。

      详细页面：

@ -291,7 +296,7 @@ flowchart TD

    </Accordion>

-    <Accordion title="Exec 突然要求批准">
+    <Accordion title="Exec 突然开始要求审批">
      ```bash
      openclaw config get tools.exec.host
      openclaw config get tools.exec.security
@ -301,14 +306,14 @@ flowchart TD

      发生了什么变化：

-      - 如果 `tools.exec.host` 未设置，则默认值是 `auto`。
-      - `host=auto` 在启用沙箱运行时时会解析为 `sandbox`，否则解析为 `gateway`。
-      - `host=auto` 只负责路由；无提示的 “YOLO” 行为来自于 gateway / node 上的 `security=full` 加 `ask=off`。
-      - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认值为 `full`。
-      - 未设置的 `tools.exec.ask` 默认值为 `off`。
-      - 结果：如果你现在看到了批准提示，说明某些主机本地或按会话的策略，相比当前默认值收紧了 exec。
+      - 如果 `tools.exec.host` 未设置，默认值是 `auto`。
+      - `host=auto` 在沙箱运行时处于活动状态时会解析为 `sandbox`，否则解析为 `gateway`。
+      - `host=auto` 只负责路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。
+      - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认是 `full`。
+      - 未设置的 `tools.exec.ask` 默认是 `off`。
+      - 结果：如果你看到了审批提示，说明某些主机本地或按会话生效的策略把 exec 收紧到了偏离当前默认值的状态。

-      恢复当前默认的无批准行为：
+      恢复当前默认的“无需审批”行为：

      ```bash
      openclaw config set tools.exec.host gateway
@ -320,14 +325,14 @@ flowchart TD
      更安全的替代方案：

      - 如果你只是想要稳定的主机路由，只设置 `tools.exec.host=gateway`。
-      - 如果你想使用主机 exec，但仍希望在允许列表未命中时进行审核，请使用 `security=allowlist` 搭配 `ask=on-miss`。
+      - 如果你想使用主机 exec，但仍希望在允许列表未命中时进行审查，可使用 `security=allowlist` 搭配 `ask=on-miss`。
      - 如果你希望 `host=auto` 重新解析为 `sandbox`，请启用沙箱模式。

      常见日志特征：

      - `Approval required.` → 命令正在等待 `/approve ...`。
-      - `SYSTEM_RUN_DENIED: approval required` → 节点主机 exec 批准仍在等待中。
-      - `exec host=sandbox requires a sandbox runtime for this session` → 发生了隐式 / 显式的沙箱选择，但沙箱模式已关闭。
+      - `SYSTEM_RUN_DENIED: approval required` → 节点主机 exec 审批仍在等待中。
+      - `exec host=sandbox requires a sandbox runtime for this session` → 隐式或显式选择了 sandbox，但沙箱模式未开启。

      详细页面：

@ -348,20 +353,20 @@ flowchart TD

      正常输出应类似于：

-      - 浏览器状态显示 `running: true`，并且已选定浏览器 / 配置文件。
-      - `openclaw` 已启动，或者 `user` 可以看到本地 Chrome 标签页。
+      - 浏览器状态显示 `running: true`，以及选定的浏览器/配置文件。
+      - `openclaw` 能启动，或者 `user` 可以看到本地 Chrome 标签页。

      常见日志特征：

-      - `unknown command "browser"` 或 `unknown command 'browser'` → 已设置 `plugins.allow`，但其中不包含 `browser`。
+      - `unknown command "browser"` 或 `unknown command 'browser'` → 设置了 `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 使用了不受支持的协议。
-      - `browser.cdpUrl has invalid port` → 配置的 CDP URL 使用了错误或超出范围的端口。
+      - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。
      - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
      - `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从当前主机无法访问。
      - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可用的实时 CDP 目标。
-      - attach-only 或远程 CDP 配置文件上的过期 viewport / 深色模式 / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭当前控制会话并释放仿真状态，而无需重启 Gateway 网关。
+      - attach-only 或远程 CDP 配置文件上存在过期的视口 / 深色模式 / 区域设置 / 离线覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>`，关闭活动控制会话并释放模拟状态，而无需重启 Gateway 网关。

      详细页面：

@ -377,7 +382,7 @@ flowchart TD
 ## 相关内容

 - [常见问题](/zh-CN/help/faq) — 常见问题
- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特有的问题
- [Doctor](/zh-CN/gateway/doctor) — 自动化健康检查与修复
+- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关专属问题
+- [Doctor](/zh-CN/gateway/doctor) — 自动健康检查与修复
 - [渠道故障排除](/zh-CN/channels/troubleshooting) — 渠道连接问题
 - [自动化故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和心跳问题