chore(i18n): refresh zh-CN translations

docs/zh-CN/cli/gateway.md

@@ -1,16 +1,16 @@
 ---
 read_when:
     - 从 CLI 运行 Gateway 网关（开发环境或服务器）
-    - 调试 Gateway 网关的凭证、绑定模式和连接性
+    - 调试 Gateway 网关身份验证、绑定模式和连接性
     - 通过 Bonjour 发现 Gateway 网关（本地 + 广域 DNS-SD）
 sidebarTitle: Gateway
-summary: OpenClaw Gateway 网关 CLI (`openclaw gateway`) — 运行、查询和发现 Gateway 网关
+summary: OpenClaw Gateway 网关 CLI (`openclaw gateway`) — 运行、查询并发现网关
 title: Gateway 网关
 x-i18n:
-    generated_at: "2026-04-28T20:56:43Z"
+    generated_at: "2026-04-29T18:57:48Z"
     model: gpt-5.5
     provider: openai
-    source_hash: 25680abf3f6f32fe9a5eea846ce6223c0d82896b5ae0bc09ea6bd8403ac34cfd
+    source_hash: fe53f1ec289bf463766634a9b03bc234e109fdddf35b3fa3958fb8c5255c81a9
     source_path: cli/gateway.md
     workflow: 16
 ---
@@ -22,10 +22,10 @@ Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、
     本地 mDNS + 广域 DNS-SD 设置。
   </Card>
   <Card title="设备发现概览" href="/zh-CN/gateway/discovery">
-    OpenClaw 如何通告和发现 Gateway 网关。
+    OpenClaw 如何通告和查找 Gateway 网关。
   </Card>
   <Card title="配置" href="/zh-CN/gateway/configuration">
-    顶层 gateway 配置键。
+    顶层 Gateway 网关配置键。
   </Card>
 </CardGroup>
 
@@ -45,12 +45,12 @@ openclaw gateway run
 
 <AccordionGroup>
   <Accordion title="启动行为">
-    - 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。仅将 `--allow-unconfigured` 用于临时/开发运行。
-    - `openclaw onboard --mode local` 和 `openclaw setup` 应写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置并修复，而不是隐式假定为本地模式。
-    - 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝替你“猜测为本地”。
-    - 绑定到回环地址以外且没有身份验证会被阻止（安全护栏）。
-    - `SIGUSR1` 在获得授权时会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，而 Gateway 网关工具/配置的应用/更新仍会允许）。
-    - `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或原始模式输入包装 CLI，请在退出前恢复终端。
+    - 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。对临时/开发运行使用 `--allow-unconfigured`。
+    - `openclaw onboard --mode local` 和 `openclaw setup` 预期会写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置并修复，而不是隐式假设为本地模式。
+    - 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测本地”。
+    - 未启用身份验证时，禁止绑定到 loopback 之外的地址（安全防护）。
+    - 授权时，`SIGUSR1` 会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，同时仍允许 Gateway 网关工具/配置应用/更新）。
+    - `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。
 
   </Accordion>
 </AccordionGroup>
@@ -58,7 +58,7 @@ openclaw gateway run
 ### 选项
 
 <ParamField path="--port <port>" type="number">
-  WebSocket 端口（默认值来自配置/环境；通常为 `18789`）。
+  WebSocket 端口（默认来自配置/环境；通常为 `18789`）。
 </ParamField>
 <ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
   监听器绑定模式。
@@ -67,7 +67,7 @@ openclaw gateway run
   身份验证模式覆盖。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  令牌覆盖（也会为该进程设置 `OPENCLAW_GATEWAY_TOKEN`）。
+  Token 覆盖（也会为进程设置 `OPENCLAW_GATEWAY_TOKEN`）。
 </ParamField>
 <ParamField path="--password <password>" type="string">
   密码覆盖。
@@ -82,16 +82,16 @@ openclaw gateway run
   关闭时重置 Tailscale serve/funnel 配置。
 </ParamField>
 <ParamField path="--allow-unconfigured" type="boolean">
-  允许在配置中没有 `gateway.mode=local` 时启动 Gateway 网关。仅为临时/开发引导绕过启动保护；不会写入或修复配置文件。
+  允许在配置中没有 `gateway.mode=local` 时启动 Gateway 网关。仅为临时/开发引导绕过启动防护；不会写入或修复配置文件。
 </ParamField>
 <ParamField path="--dev" type="boolean">
   如果缺失，则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
 </ParamField>
 <ParamField path="--reset" type="boolean">
-  重置开发配置 + 凭据 + 会话 + 工作区（需要 `--dev`）。
+  重置开发配置 + 凭证 + 会话 + 工作区（需要 `--dev`）。
 </ParamField>
 <ParamField path="--force" type="boolean">
-  启动前终止选定端口上的任何现有监听器。
+  启动前终止所选端口上的任何现有监听器。
 </ParamField>
 <ParamField path="--verbose" type="boolean">
   详细日志。
@@ -100,7 +100,7 @@ openclaw gateway run
   仅在控制台显示 CLI 后端日志（并启用 stdout/stderr）。
 </ParamField>
 <ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
-  WebSocket 日志样式。
+  Websocket 日志样式。
 </ParamField>
 <ParamField path="--compact" type="boolean">
   `--ws-log compact` 的别名。
@@ -118,8 +118,9 @@ openclaw gateway run
 
 ### 启动性能分析
 
-- 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 可在 Gateway 网关启动期间记录阶段耗时，包括每阶段 `eventLoopMax` 延迟，以及已安装索引、清单注册表、启动规划和 owner-map 工作的插件查询表耗时。
-- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 可对 Gateway 网关启动进行基准测试。该基准测试会记录首个进程输出、`/healthz`、`/readyz`、启动跟踪耗时、事件循环延迟，以及插件查询表耗时详情。
+- 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 以在 Gateway 网关启动期间记录阶段耗时，包括每个阶段的 `eventLoopMax` 延迟，以及 installed-index、manifest registry、启动规划和 owner-map 工作的插件查找表耗时。
+- 将 `OPENCLAW_DIAGNOSTICS=timeline` 与 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` 一起设置，可为外部 QA harness 写入尽力而为的 JSONL 启动诊断时间线。你也可以在配置中用 `diagnostics.flags: ["timeline"]` 启用该标志；路径仍由环境变量提供。添加 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 可包含事件循环样本。
+- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 对 Gateway 网关启动进行基准测试。该基准测试会记录首个进程输出、`/healthz`、`/readyz`、启动跟踪耗时、事件循环延迟和插件查找表耗时详情。
 
 ## 查询正在运行的 Gateway 网关
 
@@ -127,14 +128,14 @@ openclaw gateway run
 
 <Tabs>
   <Tab title="输出模式">
-    - 默认：人类可读（TTY 中带颜色）。
-    - `--json`：机器可读 JSON（无样式/加载指示器）。
+    - 默认：人类可读（在 TTY 中带颜色）。
+    - `--json`：机器可读 JSON（无样式/spinner）。
     - `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI，同时保留人类可读布局。
 
   </Tab>
   <Tab title="共享选项">
     - `--url <url>`：Gateway 网关 WebSocket URL。
-    - `--token <token>`：Gateway 网关令牌。
+    - `--token <token>`：Gateway 网关 token。
     - `--password <password>`：Gateway 网关密码。
     - `--timeout <ms>`：超时/预算（因命令而异）。
     - `--expect-final`：等待“final”响应（智能体调用）。
@@ -143,7 +144,7 @@ openclaw gateway run
 </Tabs>
 
 <Note>
-设置 `--url` 时，CLI 不会回退到配置或环境凭据。请显式传入 `--token` 或 `--password`。缺少显式凭据是错误。
+设置 `--url` 时，CLI 不会回退到配置或环境凭证。请显式传入 `--token` 或 `--password`。缺少显式凭证会报错。
 </Note>
 
 ### `gateway health`
@@ -152,11 +153,11 @@ openclaw gateway run
 openclaw gateway health --url ws://127.0.0.1:18789
 ```
 
-HTTP `/healthz` 端点是存活探测：服务器能够响应 HTTP 后就会返回。HTTP `/readyz` 端点更严格，在启动边车、渠道或配置的钩子仍在稳定时会保持红色。本地或已认证的详细就绪响应包含一个 `eventLoop` 诊断块，其中包括事件循环延迟、事件循环利用率、CPU 核心比例和 `degraded` 标志。
+HTTP `/healthz` 端点是存活探针：一旦服务器可以响应 HTTP，它就会返回。HTTP `/readyz` 端点更严格，并会在启动 sidecar、渠道或已配置钩子仍在稳定时保持红色。本地或已认证的详细就绪响应包含一个 `eventLoop` 诊断块，其中包含事件循环延迟、事件循环利用率、CPU 核心比例和 `degraded` 标志。
 
 ### `gateway usage-cost`
 
-从会话日志获取用量成本摘要。
+从会话日志获取 usage-cost 摘要。
 
 ```bash
 openclaw gateway usage-cost
@@ -181,16 +182,16 @@ openclaw gateway stability --json
 ```
 
 <ParamField path="--limit <limit>" type="number" default="25">
-  要包含的最近事件最大数量（最大 `1000`）。
+  要包含的最近事件的最大数量（最大 `1000`）。
 </ParamField>
 <ParamField path="--type <type>" type="string">
-  按诊断事件类型筛选，例如 `payload.large` 或 `diagnostic.memory.pressure`。
+  按诊断事件类型过滤，例如 `payload.large` 或 `diagnostic.memory.pressure`。
 </ParamField>
 <ParamField path="--since-seq <seq>" type="number">
-  仅包含诊断序列号之后的事件。
+  仅包含某个诊断序列号之后的事件。
 </ParamField>
 <ParamField path="--bundle [path]" type="string">
-  读取持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅使用 `--bundle`）读取状态目录下的最新包，也可以直接传入包 JSON 路径。
+  读取持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅 `--bundle`）读取状态目录下最新的包，或直接传入包 JSON 路径。
 </ParamField>
 <ParamField path="--export" type="boolean">
   写入可共享的支持诊断 zip，而不是打印稳定性详情。
@@ -201,15 +202,15 @@ openclaw gateway stability --json
 
 <AccordionGroup>
   <Accordion title="隐私和包行为">
-    - 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie、秘密值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用记录器。
-    - 在 Gateway 网关致命退出、关闭超时和重启启动失败时，如果记录器中有事件，OpenClaw 会将相同的诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 检查最新包；`--limit`、`--type` 和 `--since-seq` 也适用于包输出。
+    - 记录保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、token、cookie、机密值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用记录器。
+    - 在 Gateway 网关致命退出、关闭超时和重启启动失败时，如果记录器有事件，OpenClaw 会将相同的诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 检查最新的包；`--limit`、`--type` 和 `--since-seq` 也适用于包输出。
 
   </Accordion>
 </AccordionGroup>
 
 ### `gateway diagnostics export`
 
-写入本地诊断 zip，设计用于附加到 bug 报告。有关隐私模型和包内容，请参阅 [诊断导出](/zh-CN/gateway/diagnostics)。
+写入一个本地诊断 zip，设计用于附加到 bug 报告。有关隐私模型和包内容，请参阅 [诊断导出](/zh-CN/gateway/diagnostics)。
 
 ```bash
 openclaw gateway diagnostics export
@@ -218,7 +219,7 @@ openclaw gateway diagnostics export --json
 ```
 
 <ParamField path="--output <path>" type="string">
-  输出 zip 路径。默认为状态目录下的支持导出。
+  输出 zip 路径。默认是状态目录下的支持导出。
 </ParamField>
 <ParamField path="--log-lines <count>" type="number" default="5000">
   要包含的最大已清理日志行数。
@@ -230,7 +231,7 @@ openclaw gateway diagnostics export --json
   用于健康快照的 Gateway 网关 WebSocket URL。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  用于健康快照的 Gateway 网关令牌。
+  用于健康快照的 Gateway 网关 token。
 </ParamField>
 <ParamField path="--password <password>" type="string">
   用于健康快照的 Gateway 网关密码。
@@ -242,16 +243,16 @@ openclaw gateway diagnostics export --json
   跳过持久化稳定性包查找。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  以 JSON 打印写入路径、大小和清单。
+  将写入路径、大小和清单以 JSON 形式打印。
 </ParamField>
 
-导出包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关状态/健康快照，以及存在时的最新稳定性包。
+导出内容包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关 Status/健康快照，以及存在时最新的稳定性包。
 
-它旨在用于共享。它保留有助于调试的运行详情，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 ID、提供商 ID、非秘密功能设置，以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭据、Cookie、账户/消息标识符、提示/指令文本、主机名和秘密值。当 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时，导出只保留消息已被省略这一事实及其字节数。
+它旨在共享。它保留有助于调试的运行细节，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 ID、提供商 ID、非机密功能设置，以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭证、cookie、账号/消息标识符、提示词/指令文本、主机名和机密值。当 LogTape 风格的消息看起来像用户/聊天/工具 payload 文本时，导出仅保留有消息被省略以及其字节数。
 
 ### `gateway status`
 
-`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks），以及可选的连接性/身份验证能力探测。
+`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks），以及可选的连接性/身份验证能力探针。
 
 ```bash
 openclaw gateway status
@@ -260,44 +261,44 @@ openclaw gateway status --require-rpc
 ```
 
 <ParamField path="--url <url>" type="string">
-  添加显式探测目标。仍会探测已配置的远程目标 + localhost。
+  添加显式探针目标。仍会探测已配置的远程目标 + localhost。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  用于探测的令牌身份验证。
+  探针的 token 身份验证。
 </ParamField>
 <ParamField path="--password <password>" type="string">
-  用于探测的密码身份验证。
+  探针的密码身份验证。
 </ParamField>
 <ParamField path="--timeout <ms>" type="number" default="10000">
-  探测超时。
+  探针超时。
 </ParamField>
 <ParamField path="--no-probe" type="boolean">
-  跳过连接性探测（仅服务视图）。
+  跳过连接性探针（仅服务视图）。
 </ParamField>
 <ParamField path="--deep" type="boolean">
-  也扫描系统级服务。
+  同时扫描系统级服务。
 </ParamField>
 <ParamField path="--require-rpc" type="boolean">
-  将默认连接性探测升级为读取探测，并在该读取探测失败时以非零状态退出。不能与 `--no-probe` 组合。
+  将默认连接性探针升级为读取探针，并在该读取探针失败时以非零状态退出。不能与 `--no-probe` 组合使用。
 </ParamField>
 
 <AccordionGroup>
   <Accordion title="Status 语义">
     - `gateway status` 即使在本地 CLI 配置缺失或无效时，也仍可用于诊断。
-    - 默认的 `gateway status` 会验证服务状态、WebSocket 连接，以及握手时可见的身份验证能力。它不会验证读/写/管理员操作。
-    - 诊断探测对于首次设备身份验证是非变更性的：当已有缓存设备令牌时会复用它，但不会仅为了检查状态而创建新的 CLI 设备身份或只读设备配对记录。
-    - `gateway status` 会在可能时为探测身份验证解析已配置的身份验证 SecretRefs。
-    - 如果此命令路径中必需的身份验证 SecretRef 未解析，且探测连接性/身份验证失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析密钥来源。
-    - 如果探测成功，会抑制未解析的 auth-ref 警告，以避免误报。
-    - 当正在监听的服务还不够、你还需要读范围 RPC 调用也健康时，请在脚本和自动化中使用 `--require-rpc`。
-    - `--deep` 会尽力扫描额外的 launchd/systemd/schtasks 安装。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。
-    - 人类可读输出包含已解析的文件日志路径，以及 CLI 与服务配置路径/有效性快照，帮助诊断配置文件或状态目录漂移。
+    - 默认的 `gateway status` 会验证服务状态、WebSocket 连接，以及握手时可见的认证能力。它不会验证读/写/admin 操作。
+    - 对首次设备认证，诊断探测不会变更状态：如果已有缓存的设备令牌，它们会复用该令牌，但不会仅为了检查 Status 而创建新的 CLI 设备身份或只读设备配对记录。
+    - `gateway status` 会在可能时解析已配置的认证 SecretRefs，用于探测认证。
+    - 如果此命令路径中无法解析必需的认证 SecretRef，当探测连接/认证失败时，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析密钥来源。
+    - 如果探测成功，未解析认证引用警告会被抑制，以避免误报。
+    - 在脚本和自动化中，如果仅有监听中的服务还不够，并且你还需要读范围 RPC 调用也健康，请使用 `--require-rpc`。
+    - `--deep` 会尽力扫描额外的 launchd/systemd/schtasks 安装。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上只运行一个 Gateway 网关。
+    - 人类可读输出包含解析后的文件日志路径，以及 CLI 与服务配置路径/有效性快照，用于帮助诊断配置文件或状态目录漂移。
 
   </Accordion>
-  <Accordion title="Linux systemd 身份验证漂移检查">
-    - 在 Linux systemd 安装中，服务身份验证漂移检查会从单元读取 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件以及可选的 `-` 文件）。
+  <Accordion title="Linux systemd 认证漂移检查">
+    - 在 Linux systemd 安装中，服务认证漂移检查会从 unit 读取 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件，以及可选的 `-` 文件）。
     - 漂移检查会使用合并后的运行时环境解析 `gateway.auth.token` SecretRefs（先使用服务命令环境，再回退到进程环境）。
-    - 如果令牌身份验证实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或模式未设置且密码可能胜出并且没有令牌候选项可胜出），令牌漂移检查会跳过配置令牌解析。
+    - 如果令牌认证实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或 mode 未设置且 password 可能胜出并且没有 token 候选能胜出），令牌漂移检查会跳过配置令牌解析。
 
   </Accordion>
 </AccordionGroup>
@@ -307,16 +308,16 @@ openclaw gateway status --require-rpc
 `gateway probe` 是“调试一切”的命令。它始终会探测：
 
 - 你配置的远程 Gateway 网关（如果已设置），以及
-- localhost（loopback）**即使已配置远程目标**。
+- localhost（loopback），**即使已经配置了远程目标**。
 
-如果你传入 `--url`，该显式目标会添加到两者之前。人类可读输出会将目标标记为：
+如果传入 `--url`，该显式目标会被添加到两者之前。人类可读输出会将目标标记为：
 
 - `URL (explicit)`
 - `Remote (configured)` 或 `Remote (configured, inactive)`
 - `Local loopback`
 
 <Note>
-如果多个 Gateway 网关可访问，它会全部打印出来。当你使用隔离的配置文件/端口（例如救援机器人）时，支持多个 Gateway 网关，但大多数安装仍只运行单个 Gateway 网关。
+如果多个 Gateway 网关可达，它会打印全部目标。当你使用隔离的配置文件/端口时（例如救援机器人），支持多个 Gateway 网关，但大多数安装仍只运行单个 Gateway 网关。
 </Note>
 
 ```bash
@@ -327,12 +328,12 @@ openclaw gateway probe --json
 <AccordionGroup>
   <Accordion title="解读">
     - `Reachable: yes` 表示至少一个目标接受了 WebSocket 连接。
-    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 报告探测可验证的身份验证能力。它与可达性是分开的。
+    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 报告探测能证明的认证能力。它独立于可达性。
     - `Read probe: ok` 表示读范围详情 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也成功了。
     - `Read probe: limited - missing scope: operator.read` 表示连接成功，但读范围 RPC 受限。这会报告为**降级**可达性，而不是完全失败。
-    - `Connect: ok` 之后的 `Read probe: failed` 表示 Gateway 网关接受了 WebSocket 连接，但后续读诊断超时或失败。这同样是**降级**可达性，而不是不可访问的 Gateway 网关。
-    - 与 `gateway status` 类似，探测会复用现有缓存设备身份验证，但不会创建首次设备身份或配对状态。
-    - 只有在没有任何被探测目标可达时，退出码才为非零。
+    - `Connect: ok` 之后的 `Read probe: failed` 表示 Gateway 网关接受了 WebSocket 连接，但后续读诊断超时或失败。这同样是**降级**可达性，而不是 Gateway 网关不可达。
+    - 与 `gateway status` 一样，probe 会复用现有缓存的设备认证，但不会创建首次设备身份或配对状态。
+    - 只有在没有任何被探测目标可达时，退出码才是非零。
 
   </Accordion>
   <Accordion title="JSON 输出">
@@ -341,36 +342,36 @@ openclaw gateway probe --json
     - `ok`：至少一个目标可达。
     - `degraded`：至少一个目标接受了连接，但未完成完整详情 RPC 诊断。
     - `capability`：在可达目标中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
-    - `primaryTargetId`：按以下顺序作为活跃胜出者处理的最佳目标：显式 URL、SSH 隧道、已配置远程目标，然后是 local loopback。
-    - `warnings[]`：尽力提供的警告记录，包含 `code`、`message` 以及可选的 `targetIds`。
-    - `network`：从当前配置和主机网络派生的 local loopback/tailnet URL 提示。
-    - `discovery.timeoutMs` 和 `discovery.count`：此次探测实际使用的设备发现预算/结果数量。
+    - `primaryTargetId`：按以下顺序作为活跃胜出者处理的最佳目标：显式 URL、SSH 隧道、配置的远程目标，然后是 local loopback。
+    - `warnings[]`：尽力提供的警告记录，包含 `code`、`message` 和可选的 `targetIds`。
+    - `network`：从当前配置和主机网络推导出的 local loopback/tailnet URL 提示。
+    - `discovery.timeoutMs` 和 `discovery.count`：此次探测实际使用的设备发现预算/结果计数。
 
     每个目标（`targets[].connect`）：
 
     - `ok`：连接后的可达性 + 降级分类。
     - `rpcOk`：完整详情 RPC 成功。
-    - `scopeLimited`：详情 RPC 因缺少操作员范围而失败。
+    - `scopeLimited`：详情 RPC 因缺少 operator scope 而失败。
 
     每个目标（`targets[].auth`）：
 
-    - `role`：可用时在 `hello-ok` 中报告的身份验证角色。
+    - `role`：可用时在 `hello-ok` 中报告的认证角色。
     - `scopes`：可用时在 `hello-ok` 中报告的已授予范围。
-    - `capability`：该目标暴露的身份验证能力分类。
+    - `capability`：该目标暴露的认证能力分类。
 
   </Accordion>
   <Accordion title="常见警告代码">
-    - `ssh_tunnel_failed`：SSH 隧道设置失败；命令已回退到直接探测。
-    - `multiple_gateways`：多个目标可达；除非你有意运行隔离配置文件（例如救援机器人），否则这并不常见。
-    - `auth_secretref_unresolved`：无法为失败目标解析已配置的身份验证 SecretRef。
+    - `ssh_tunnel_failed`：SSH 隧道设置失败；命令回退到直接探测。
+    - `multiple_gateways`：多个目标可达；除非你有意运行隔离配置文件，例如救援机器人，否则这并不常见。
+    - `auth_secretref_unresolved`：无法为失败目标解析已配置的认证 SecretRef。
     - `probe_scope_limited`：WebSocket 连接成功，但读探测因缺少 `operator.read` 而受限。
 
   </Accordion>
 </AccordionGroup>
 
-#### 通过 SSH 访问远程（与 Mac 应用一致）
+#### 通过 SSH 远程连接（与 Mac 应用保持一致）
 
-macOS 应用的“通过 SSH 访问远程”模式使用本地端口转发，让远程 Gateway 网关（可能只绑定到 loopback）可通过 `ws://127.0.0.1:<port>` 访问。
+macOS 应用的“通过 SSH 远程连接”模式会使用本地端口转发，使远程 Gateway 网关（可能只绑定到 loopback）可在 `ws://127.0.0.1:<port>` 访问。
 
 CLI 等效命令：
 
@@ -385,7 +386,7 @@ openclaw gateway probe --ssh user@gateway-host
   身份文件。
 </ParamField>
 <ParamField path="--ssh-auto" type="boolean">
-  从已解析的设备发现端点（`local.` 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 提示会被忽略。
+  从解析后的设备发现端点（`local.` 加上配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 的提示会被忽略。
 </ParamField>
 
 配置（可选，用作默认值）：
@@ -395,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host
 
 ### `gateway call <method>`
 
-低层 RPC 辅助命令。
+底层 RPC 辅助命令。
 
 ```bash
 openclaw gateway call status
@@ -418,7 +419,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
   超时预算。
 </ParamField>
 <ParamField path="--expect-final" type="boolean">
-  主要用于智能体式 RPC，这类 RPC 会在最终负载之前流式传输中间事件。
+  主要用于 agent 风格的 RPC，这类 RPC 会在最终载荷之前流式传输中间事件。
 </ParamField>
 <ParamField path="--json" type="boolean">
   机器可读 JSON 输出。
@@ -440,7 +441,7 @@ openclaw gateway uninstall
 
 ### 使用包装器安装
 
-当托管服务必须通过另一个可执行文件启动时使用 `--wrapper`，例如密钥管理器 shim 或 run-as 辅助程序。包装器会接收正常的 Gateway 网关参数，并负责最终用这些参数 exec `openclaw` 或 Node。
+当托管服务必须通过另一个可执行文件启动时，请使用 `--wrapper`，例如密钥管理器 shim 或 run-as 辅助程序。包装器会接收正常的 Gateway 网关参数，并负责最终以这些参数 exec `openclaw` 或 Node。
 
 ```bash
 cat > ~/.local/bin/openclaw-doppler <<'EOF'
@@ -454,7 +455,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
 openclaw gateway restart
 ```
 
-你也可以通过环境设置包装器。`gateway install` 会验证路径是可执行文件，将包装器写入服务 `ProgramArguments`，并在服务环境中持久化 `OPENCLAW_WRAPPER`，用于之后的强制重装、更新和 Doctor 修复。
+你也可以通过环境设置包装器。`gateway install` 会验证该路径是可执行文件，将包装器写入服务 `ProgramArguments`，并在服务环境中持久化 `OPENCLAW_WRAPPER`，供后续强制重新安装、更新和 Doctor 修复使用。
 
 ```bash
 OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
@@ -476,16 +477,16 @@ openclaw gateway restart
 
   </Accordion>
   <Accordion title="生命周期行为">
-    - 使用 `gateway restart` 重启托管服务。不要将 `gateway stop` 和 `gateway start` 串联起来作为重启替代；在 macOS 上，`gateway stop` 会有意先禁用 LaunchAgent 再停止它。
-    - 生命周期命令接受 `--json`，用于脚本。
+    - 使用 `gateway restart` 重启托管服务。不要串联 `gateway stop` 和 `gateway start` 来替代重启；在 macOS 上，`gateway stop` 会有意先禁用 LaunchAgent 再停止它。
+    - 生命周期命令接受 `--json`，用于脚本编写。
 
   </Accordion>
-  <Accordion title="安装时的身份验证和 SecretRefs">
-    - 当令牌身份验证需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证 SecretRef 可解析，但不会将已解析令牌持久化到服务环境元数据中。
-    - 如果令牌身份验证需要令牌且已配置的令牌 SecretRef 未解析，安装会封闭失败，而不是持久化回退明文。
-    - 对于 `gateway run` 上的密码身份验证，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或基于 SecretRef 的 `gateway.auth.password`，而不是内联 `--password`。
-    - 在推断身份验证模式下，仅 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装令牌要求；安装托管服务时请使用持久配置（`gateway.auth.password` 或配置 `env`）。
-    - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，安装会被阻止，直到显式设置模式。
+  <Accordion title="安装时的认证和 SecretRefs">
+    - 当令牌认证需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证 SecretRef 可解析，但不会将解析后的令牌持久化到服务环境元数据中。
+    - 如果令牌认证需要令牌且配置的令牌 SecretRef 无法解析，安装会失败关闭，而不是持久化回退明文。
+    - 对于 `gateway run` 上的密码认证，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或由 SecretRef 支持的 `gateway.auth.password`，而不是内联 `--password`。
+    - 在推断认证模式下，仅存在于 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装令牌要求；安装托管服务时请使用持久配置（`gateway.auth.password` 或配置 `env`）。
+    - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，安装会被阻止，直到显式设置 mode。
 
   </Accordion>
 </AccordionGroup>
@@ -495,19 +496,19 @@ openclaw gateway restart
 `gateway discover` 会扫描 Gateway 网关信标（`_openclaw-gw._tcp`）。
 
 - 组播 DNS-SD：`local.`
-- 单播 DNS-SD（广域 Bonjour）：选择一个域名（示例：`openclaw.internal.`）并设置 split DNS + DNS 服务器；参见 [Bonjour](/zh-CN/gateway/bonjour)。
+- 单播 DNS-SD（广域 Bonjour）：选择一个域名（示例：`openclaw.internal.`）并设置 split DNS + DNS 服务器；请参阅 [Bonjour](/zh-CN/gateway/bonjour)。
 
-只有启用了 Bonjour 设备发现（默认）的 Gateway 网关才会播发该信标。
+只有启用了 Bonjour 发现（默认）的 Gateway 网关会广播信标。
 
-广域设备发现记录包括（TXT）：
+广域发现记录包括（TXT）：
 
 - `role`（Gateway 网关角色提示）
 - `transport`（传输提示，例如 `gateway`）
 - `gatewayPort`（WebSocket 端口，通常为 `18789`）
-- `sshPort`（可选；当它不存在时，客户端默认 SSH 目标为 `22`）
+- `sshPort`（可选；缺失时客户端默认 SSH 目标为 `22`）
 - `tailnetDns`（MagicDNS 主机名，可用时）
 - `gatewayTls` / `gatewayTlsSha256`（TLS 已启用 + 证书指纹）
-- `cliPath`（写入广域区域的远程安装提示）
+- `cliPath`（写入广域 zone 的远程安装提示）
 
 ### `gateway discover`
 
@@ -516,10 +517,10 @@ openclaw gateway discover
 ```
 
 <ParamField path="--timeout <ms>" type="number" default="2000">
-  每条命令的超时时间（browse/resolve）。
+  每条命令的超时（browse/resolve）。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  机器可读输出（也会禁用样式/加载指示器）。
+  机器可读输出（也会禁用样式/spinner）。
 </ParamField>
 
 示例：
@@ -530,9 +531,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
 ```
 
 <Note>
-- CLI 会在启用配置的广域域名时扫描 `local.` 加上该域名。
-- JSON 输出中的 `wsUrl` 派生自解析后的服务端点，而不是来自仅 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
-- 在 `local.` mDNS 上，只有当 `discovery.mdns.mode` 为 `full` 时，才会广播 `sshPort` 和 `cliPath`。广域 DNS-SD 仍会写入 `cliPath`；`sshPort` 在那里也保持可选。
+- CLI 会扫描 `local.`，并在启用已配置的广域域名时同时扫描该域名。
+- JSON 输出中的 `wsUrl` 派生自解析后的服务端点，而不是仅 TXT 提示，例如 `lanHost` 或 `tailnetDns`。
+- 在 `local.` mDNS 上，只有当 `discovery.mdns.mode` 为 `full` 时才会广播 `sshPort` 和 `cliPath`。广域 DNS-SD 仍会写入 `cliPath`；`sshPort` 在那里也保持可选。
 
 </Note>
 

docs/zh-CN/diagnostics/flags.md

@@ -1,24 +1,24 @@
 ---
 read_when:
-    - 你需要定向调试日志，而不提高全局日志级别
-    - 你需要采集特定子系统的日志以供支持使用
+    - 你需要在不提高全局日志级别的情况下获取定向调试日志
+    - 你需要捕获特定子系统的日志以便支持排查
 summary: 用于定向调试日志的诊断标志
 title: 诊断标志
 x-i18n:
-    generated_at: "2026-04-24T04:01:58Z"
-    model: gpt-5.4
+    generated_at: "2026-04-29T18:57:41Z"
+    model: gpt-5.5
     provider: openai
-    source_hash: b7e5ec9c5e28ef51f1e617baf62412897df8096f227a74d86a0824e269aafd9d
+    source_hash: 486051e54c456dedcae5dce59e253add3554d8417660bfc97a75d21fa5fdd6f5
     source_path: diagnostics/flags.md
-    workflow: 15
+    workflow: 16
 ---
 
-诊断标志可让你启用定向调试日志，而无需在所有地方开启详细日志。标志为选择启用，除非某个子系统检查这些标志，否则不会产生任何影响。
+诊断标志可让你启用有针对性的调试日志，而不必到处开启详细日志记录。标志需要显式启用；除非某个子系统检查它们，否则不会产生任何效果。
 
 ## 工作原理
 
 - 标志是字符串（不区分大小写）。
-- 你可以在配置中启用标志，或通过环境变量覆盖。
+- 你可以在配置中启用标志，也可以通过环境变量覆盖启用。
 - 支持通配符：
   - `telegram.*` 匹配 `telegram.http`
   - `*` 启用所有标志
@@ -43,7 +43,7 @@ x-i18n:
 }
 ```
 
-更改标志后，重启 Gateway 网关。
+更改标志后重启 Gateway 网关。
 
 ## 环境变量覆盖（一次性）
 
@@ -57,15 +57,41 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
 OPENCLAW_DIAGNOSTICS=0
 ```
 
+## 时间线产物
+
+`timeline` 标志会为外部 QA harness 写入结构化的启动和运行时计时事件：
+
+```bash
+OPENCLAW_DIAGNOSTICS=timeline \
+OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \
+openclaw gateway run
+```
+
+你也可以在配置中启用它：
+
+```json
+{
+  "diagnostics": {
+    "flags": ["timeline"]
+  }
+}
+```
+
+时间线文件路径仍来自 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH`。当仅从配置启用 `timeline` 时，最早的配置加载 span 不会发出，因为 OpenClaw 还没有读取配置；后续启动 span 会使用配置标志。
+
+`OPENCLAW_DIAGNOSTICS=1`、`OPENCLAW_DIAGNOSTICS=all` 和 `OPENCLAW_DIAGNOSTICS=*` 也会启用时间线，因为它们会启用每一个诊断标志。当你只需要 JSONL 计时产物时，优先使用 `timeline`。
+
+时间线记录使用 `openclaw.diagnostics.v1` 信封。事件可以包含进程 ID、阶段名称、span 名称、持续时间、插件 ID、依赖数量、事件循环延迟样本、提供商操作名称、子进程退出状态，以及启动错误名称/消息。请将时间线文件视为本地诊断产物；在机器外共享之前先审阅它们。
+
 ## 日志写入位置
 
-这些标志会将日志写入标准诊断日志文件。默认情况下：
+标志会将日志发出到标准诊断日志文件。默认情况下：
 
 ```
 /tmp/openclaw/openclaw-YYYY-MM-DD.log
 ```
 
-如果你设置了 `logging.file`，则改用该路径。日志格式为 JSONL（每行一个 JSON 对象）。仍会根据 `logging.redactSensitive` 应用脱敏。
+如果你设置了 `logging.file`，则改用该路径。日志是 JSONL（一行一个 JSON 对象）。脱敏仍会基于 `logging.redactSensitive` 应用。
 
 ## 提取日志
 
@@ -75,13 +101,13 @@ OPENCLAW_DIAGNOSTICS=0
 ls -t /tmp/openclaw/openclaw-*.log | head -n 1
 ```
 
-筛选 Telegram HTTP 诊断日志：
+筛选 Telegram HTTP 诊断：
 
 ```bash
 rg "telegram http error" /tmp/openclaw/openclaw-*.log
 ```
 
-或者在复现问题时实时查看：
+或者在复现时跟踪：
 
 ```bash
 tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
@@ -89,13 +115,13 @@ tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
 
 对于远程 Gateway 网关，你也可以使用 `openclaw logs --follow`（参见 [/cli/logs](/zh-CN/cli/logs)）。
 
-## 说明
+## 备注
 
-- 如果 `logging.level` 设置得高于 `warn`，这些日志可能会被抑制。默认的 `info` 是可以的。
-- 这些标志可以安全地保持启用；它们只会影响特定子系统的日志量。
-- 使用 [/logging](/zh-CN/logging) 更改日志目标、级别和脱敏设置。
+- 如果 `logging.level` 设置得高于 `warn`，这些日志可能会被抑制。默认的 `info` 没问题。
+- 标志可以安全地保持启用；它们只会影响特定子系统的日志量。
+- 使用 [/logging](/zh-CN/logging) 更改日志目标位置、级别和脱敏。
 
-## 相关内容
+## 相关
 
 - [Gateway 网关诊断](/zh-CN/gateway/diagnostics)
 - [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting)