chore(i18n): refresh zh-CN translations

2026-04-29 08:51:17 +00:00 · 2026-04-29 08:51:17 +00:00 · ba9de0f6ac
commit ba9de0f6ac
parent dfe59628f3
3 changed files with 514 additions and 469 deletions
--- a/docs/zh-CN/help/debugging.md
+++ b/docs/zh-CN/help/debugging.md
@ -1,26 +1,26 @@
 ---
 read_when:
-    - 你需要检查原始模型输出是否泄露推理内容
-    - 你想在迭代过程中以监视模式运行 Gateway 网关
-    - 你需要一个可重复的调试工作流
-summary: 调试工具：监视模式、原始模型流和推理泄漏追踪
+    - 你需要检查原始模型输出是否存在推理泄露
+    - 你想在迭代开发时以监听模式运行 Gateway 网关
+    - 你需要一套可重复的调试工作流
+summary: 调试工具：监视模式、原始模型流，以及追踪推理泄漏
 title: 调试
 x-i18n:
-    generated_at: "2026-04-28T17:10:23Z"
+    generated_at: "2026-04-29T08:48:31Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 13a49773e39041c77d4562aadcf03669bb5e66801be9908954e971a27f924cd4
+    source_hash: c3c4ba151cf1ef1dd689077cee93467b7bc77b765665231028941a345b5345ea
    source_path: help/debugging.md
    workflow: 16
 ---

-流式输出的调试辅助工具，尤其适用于提供商将推理内容混入普通文本的情况。
+用于流式输出的调试辅助工具，尤其适用于提供商将推理混入普通文本的情况。

-## 运行时调试覆盖
+## 运行时调试覆盖项

-在聊天中使用 `/debug` 设置**仅运行时**配置覆盖（保存在内存中，不写入磁盘）。
-`/debug` 默认禁用；使用 `commands.debug: true` 启用。
-当你需要切换晦涩设置但不想编辑 `openclaw.json` 时，这很方便。
+在聊天中使用 `/debug` 设置**仅运行时**配置覆盖项（内存中，而非磁盘中）。
+`/debug` 默认禁用；用 `commands.debug: true` 启用。
+当你需要切换晦涩设置而不编辑 `openclaw.json` 时，这很方便。

 示例：

@ -31,11 +31,11 @@ x-i18n:
 /debug reset
 ```

-`/debug reset` 会清除所有覆盖，并恢复为磁盘上的配置。
+`/debug reset` 会清除所有覆盖项，并恢复为磁盘上的配置。

 ## 会话跟踪输出

-当你想在一个会话中查看插件拥有的跟踪/调试行，但不想开启完整详细模式时，使用 `/trace`。
+当你想在一个会话中查看插件拥有的跟踪/调试行，而不启用完整详细模式时，使用 `/trace`。

 示例：

@ -46,11 +46,11 @@ x-i18n:
 ```

 将 `/trace` 用于插件诊断，例如 Active Memory 调试摘要。
-继续使用 `/verbose` 查看常规的详细 Status/工具输出，并继续使用 `/debug` 进行仅运行时配置覆盖。
+继续将 `/verbose` 用于常规详细 Status/工具输出，并继续将 `/debug` 用于仅运行时配置覆盖项。

 ## 插件生命周期跟踪

-当插件生命周期命令感觉很慢，并且你需要内置的阶段拆解来查看插件元数据、设备发现、注册表、运行时镜像、配置变更和刷新工作时，使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。该跟踪是选择性启用的，并写入 stderr，因此 JSON 命令输出仍保持可解析。
+当插件生命周期命令感觉很慢，并且你需要针对插件元数据、设备发现、注册表、运行时镜像、配置变更和刷新工作的内置阶段拆解时，使用 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`。该跟踪需要显式启用，并写入 stderr，因此 JSON 命令输出仍可解析。

 示例：

@ -66,19 +66,19 @@ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
 [plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
 ```

-在使用 CPU 分析器之前，先用它调查插件生命周期。
-如果命令从源码检出目录运行，建议在 `pnpm build` 后用 `node dist/entry.js ...` 测量构建后的运行时；`pnpm openclaw ...` 也会把源码运行器开销计入测量。
+在使用 CPU 分析器之前，用它来调查插件生命周期。
+如果命令从源码检出目录运行，优先在 `pnpm build` 后用 `node dist/entry.js ...` 测量构建后的运行时；`pnpm openclaw ...` 也会测到源码运行器开销。

 ## 临时 CLI 调试计时

-OpenClaw 保留 `src/cli/debug-timing.ts` 作为本地调查的小型辅助工具。
-它有意默认不接入 CLI 启动、命令路由或任何命令。只在调试慢命令时使用它，然后在落地行为变更前移除 import 和 span。
+OpenClaw 保留 `src/cli/debug-timing.ts` 作为本地调查的小辅助工具。
+它有意默认不接入 CLI 启动、命令路由或任何命令。仅在调试慢命令时使用它，然后在落地行为变更前移除导入和计时段。

-当某个命令很慢，而你需要快速查看阶段拆解，再决定是使用 CPU 分析器还是修复特定子系统时，使用它。
+当某个命令很慢，并且你需要快速的阶段拆解，再决定是使用 CPU 分析器还是修复特定子系统时，使用它。

-### 添加临时 span
+### 添加临时计时段

-在你正在调查的代码附近添加该辅助工具。例如，在调试 `openclaw models list` 时，`src/commands/models/list.list-command.ts` 中的临时补丁可能如下所示：
+在你调查的代码附近添加辅助工具。例如，在调试 `openclaw models list` 时，`src/commands/models/list.list-command.ts` 中的临时补丁可能如下所示：

 ```ts
 // Temporary debugging only. Remove before landing.
@ -101,12 +101,12 @@ const loaded = await timing.timeAsync(
 准则：

 - 用 `debug:` 作为临时阶段名称的前缀。
- 只在疑似慢的区段周围添加少量 span。
- 相比辅助函数名称，优先使用 `registry`、`auth_store` 或 `rows` 这类宽泛阶段。
+- 只在疑似慢的部分周围添加少量计时段。
+- 优先使用 `registry`、`auth_store` 或 `rows` 这类宽泛阶段，而不是辅助函数名称。
 - 对同步工作使用 `time()`，对 promise 使用 `timeAsync()`。
- 保持 stdout 干净。该辅助工具写入 stderr，因此命令 JSON 输出保持可解析。
- 在打开最终修复 PR 前移除临时 import 和 span。
- 在 issue 或 PR 中包含计时输出或简短摘要，以说明优化依据。
+- 保持 stdout 干净。辅助工具写入 stderr，因此命令 JSON 输出保持可解析。
+- 在打开最终修复 PR 前移除临时导入和计时段。
+- 在解释优化的 issue 或 PR 中包含计时输出或简短摘要。

 ### 使用可读输出运行

@ -116,7 +116,7 @@ const loaded = await timing.timeAsync(
 OPENCLAW_DEBUG_TIMING=1 pnpm openclaw models list --all --provider moonshot
 ```

-临时 `models list` 调查的示例输出：
+一次临时 `models list` 调查的示例输出：

 ```text
 OpenClaw CLI debug timing: models list
@ -145,18 +145,18 @@ moonshot/kimi-k2.6                         text+image  256k  no    no
  36.9s     +0ms complete rows=5
 ```

-从该输出得出的发现：
+此输出中的发现：

 | 阶段                                     |       时间 | 含义                                                                                                    |
 | ---------------------------------------- | ---------: | ------------------------------------------------------------------------------------------------------- |
-| `debug:models:list:auth_store`           |      20.3s | auth-profile 存储加载是最大成本，应优先调查。                                                           |
-| `debug:models:list:ensure_models_json`   |       5.0s | 同步 `models.json` 的开销已经值得检查是否可缓存或跳过。                                                 |
-| `debug:models:list:load_model_registry`  |       5.9s | 注册表构建和提供商可用性工作也是有意义的成本。                                                         |
-| `debug:models:list:read_registry_models` |       2.4s | 读取所有注册表模型并非免费，对 `--all` 可能有影响。                                                     |
+| `debug:models:list:auth_store`           |      20.3s | 凭证配置存储加载是最大成本，应首先调查。                                                                |
+| `debug:models:list:ensure_models_json`   |       5.0s | 同步 `models.json` 的成本足够高，值得检查缓存或跳过条件。                                               |
+| `debug:models:list:load_model_registry`  |       5.9s | 注册表构建和提供商可用性工作也是有意义的成本。                                                          |
+| `debug:models:list:read_registry_models` |       2.4s | 读取所有注册表模型并非免费，对 `--all` 可能很重要。                                                     |
 | 行追加阶段                               | 总计 3.2s | 构建五个显示行仍需数秒，因此过滤路径值得进一步查看。                                                    |
 | `debug:models:list:print_model_table`    |        0ms | 渲染不是瓶颈。                                                                                          |

-这些发现足以指导下一次补丁，而无需在生产路径中保留计时代码。
+这些发现足以指导下一个补丁，而无需在生产路径中保留计时代码。

 ### 使用 JSON 输出运行

@ -191,36 +191,58 @@ rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \
  --glob '!*.test.ts'
 ```

-除非该 PR 明确是在添加永久诊断界面，否则该命令不应返回任何临时插桩调用点。对于常规性能修复，只保留行为变更、测试，以及包含计时证据的简短说明。
+除非 PR 明确添加永久诊断表面，否则该命令不应返回任何临时插桩调用点。对于常规性能修复，只保留行为变更、测试和带有计时证据的简短说明。

-对于更深层的 CPU 热点，请使用 Node 分析（`--cpu-prof`）或外部分析器，而不是添加更多计时包装器。
+对于更深层的 CPU 热点，使用 Node 分析（`--cpu-prof`）或外部分析器，而不是添加更多计时包装器。

-## Gateway 网关 watch 模式
+## Gateway 网关监视模式

-为了快速迭代，在文件 watcher 下运行 Gateway 网关：
+为了快速迭代，在文件监视器下运行 Gateway 网关：

 ```bash
 pnpm gateway:watch
 ```

-这会映射到：
+默认情况下，这会启动或重启名为 `openclaw-gateway-watch-main` 的 tmux 会话（或特定于配置档案/端口的变体，例如 `openclaw-gateway-watch-dev-19001`），并从交互式终端自动附加。非交互式 shell、CI 和智能体 exec 调用会保持分离并改为打印附加说明。需要时手动附加：
+
+```bash
+tmux attach -t openclaw-gateway-watch-main
+```
+
+tmux 窗格运行原始监视器：

 ```bash
 node scripts/watch-node.mjs gateway --force
 ```

-该 watcher 会在 `src/` 下与构建相关的文件、插件源文件、插件 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变化时重启。插件元数据变更会重启 Gateway 网关，但不会强制执行 `tsdown` 重新构建；源码和配置变更仍会先重新构建 `dist`。
+不想使用 tmux 时使用前台模式：

-在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们都会在每次重启时透传。现在，对同一仓库/标志组合重新运行相同的 watch 命令时，会替换旧 watcher，而不会留下重复的 watcher 父进程。
+```bash
+pnpm gateway:watch:raw
+# or
+OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
+```

-## 开发配置文件 + 开发 Gateway 网关（--dev）
+在保留 tmux 管理的同时禁用自动附加：

-使用开发配置文件来隔离状态，并启动一个安全、可丢弃的设置用于调试。这里有**两个** `--dev` 标志：
+```bash
+OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
+```

- **全局 `--dev`（profile）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之偏移）。
- **`gateway --dev`：告诉 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
+tmux 包装器会将常见的非机密运行时选择器带入窗格，例如 `OPENCLAW_PROFILE`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、`OPENCLAW_GATEWAY_PORT` 和 `OPENCLAW_SKIP_CHANNELS`。将提供商凭证放在你的常规配置档案/配置中，或对一次性短暂密钥使用原始前台模式。

-推荐流程（开发配置文件 + 开发引导）：
+监视器会在 `src/` 下与构建相关的文件、插件源文件、插件 `package.json` 和 `openclaw.plugin.json` 元数据、`tsconfig.json`、`package.json` 以及 `tsdown.config.ts` 发生变化时重启。插件元数据变更会重启 Gateway 网关，而不会强制 `tsdown` 重新构建；源码和配置变更仍会先重新构建 `dist`。
+
+在 `gateway:watch` 后添加任何 Gateway 网关 CLI 标志，它们会在每次重启时透传。重新运行相同的监视命令会重新生成命名的 tmux 窗格，原始监视器仍会保留其单监视器锁，因此重复的监视器父进程会被替换，而不是堆积。
+
+## 开发配置档案 + 开发 Gateway 网关（--dev）
+
+使用开发配置档案来隔离状态，并启动一个安全、可丢弃的设置用于调试。有**两个** `--dev` 标志：
+
+- **全局 `--dev`（配置档案）：** 将状态隔离到 `~/.openclaw-dev` 下，并将 Gateway 网关端口默认为 `19001`（派生端口随之偏移）。
+- **`gateway --dev`：告知 Gateway 网关在缺失时自动创建默认配置 + 工作区**（并跳过 BOOTSTRAP.md）。
+
+推荐流程（开发配置档案 + 开发引导）：

 ```bash
 pnpm gateway:dev
@ -229,19 +251,19 @@ OPENCLAW_PROFILE=dev openclaw tui

 如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行 CLI。

-这会执行以下操作：
+它会做这些事：

-1. **配置文件隔离**（全局 `--dev`）
+1. **配置档案隔离**（全局 `--dev`）
   - `OPENCLAW_PROFILE=dev`
   - `OPENCLAW_STATE_DIR=~/.openclaw-dev`
   - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
-   - `OPENCLAW_GATEWAY_PORT=19001`（browser/canvas 会相应偏移）
+   - `OPENCLAW_GATEWAY_PORT=19001`（浏览器/canvas 相应偏移）

 2. **开发引导**（`gateway --dev`）
-   - 如果缺失，写入最小配置（`gateway.mode=local`，绑定 local loopback）。
+   - 如果缺失，则写入最小配置（`gateway.mode=local`，绑定 loopback）。
   - 将 `agent.workspace` 设置为开发工作区。
   - 设置 `agent.skipBootstrap=true`（无 BOOTSTRAP.md）。
-   - 如果缺失，则播种工作区文件：
+   - 如果缺失，则填充工作区文件：
     `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`。
   - 默认身份：**C3‑PO**（礼仪机器人）。
   - 在开发模式中跳过渠道提供商（`OPENCLAW_SKIP_CHANNELS=1`）。
@ -253,7 +275,7 @@ pnpm gateway:dev:reset
 ```

 <Note>
-`--dev` 是一个**全局**配置文件标志，会被某些运行器吞掉。如果你需要明确写出它，请使用环境变量形式：
+`--dev` 是一个**全局**配置档案标志，会被某些运行器吞掉。如果你需要明确写出它，请使用环境变量形式：

 ```bash
 OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
@ -261,7 +283,7 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

 </Note>

-`--reset` 会清除配置、凭证、会话和开发工作区（使用 `trash`，而不是 `rm`），然后重新创建默认开发设置。
+`--reset` 会清除配置、凭证、会话和开发工作区（使用 `trash`，不是 `rm`），然后重新创建默认开发设置。

 <Tip>
 如果非开发 Gateway 网关已经在运行（launchd 或 systemd），请先停止它：
@ -274,10 +296,10 @@ openclaw gateway stop

 ## 原始流日志（OpenClaw）

-OpenClaw 可以在任何过滤/格式化之前记录**原始 assistant 流**。
-这是查看推理是作为纯文本增量到达，还是作为独立 thinking block 到达的最佳方式。
+OpenClaw 可以在任何过滤/格式化之前记录**原始助手流**。
+这是查看推理是否以纯文本 delta（或作为单独的思考块）到达的最佳方式。

-通过 CLI 启用：
+通过 CLI 启用它：

 ```bash
 pnpm gateway:watch --raw-stream
@ -300,9 +322,10 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

 `~/.openclaw/logs/raw-stream.jsonl`

-## 原始 chunk 日志（pi-mono）
+## 原始分块日志记录（pi-mono）

-为了在原始 OpenAI 兼容 chunk 被解析为 block 之前捕获它们，pi-mono 提供了单独的日志记录器：
+若要在解析为块之前捕获 **原始 OpenAI 兼容分块**，
+pi-mono 提供了一个单独的记录器：

 ```bash
 PI_RAW_STREAM=1
@ -318,13 +341,13 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

 `~/.pi-mono/logs/raw-openai-completions.jsonl`

-> 注意：这只由使用 pi-mono 的
+> 注意：这仅由使用 pi-mono 的
 > `openai-completions` 提供商的进程发出。

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

- 原始流日志可能包含完整提示词、工具输出和用户数据。
- 将日志保留在本地，并在调试后删除它们。
+- 原始流日志可能包含完整提示、工具输出和用户数据。
+- 将日志保留在本地，并在调试后删除。
 - 如果你共享日志，请先清理密钥和 PII。

 ## 相关
--- a/docs/zh-CN/plugins/manifest.md
+++ b/docs/zh-CN/plugins/manifest.md
--- a/docs/zh-CN/start/setup.md
+++ b/docs/zh-CN/start/setup.md
@ -1,72 +1,72 @@
 ---
 read_when:
-    - 设置一台新机器
-    - 你想要“最新最强”，同时又不破坏你的个人设置
-summary: OpenClaw 的高级设置与开发工作流
+    - 设置新机器
+    - 你既想要“最新 + 最佳”，又不想破坏你的个人设置
+summary: OpenClaw 的高级设置和开发工作流
 title: 设置
 x-i18n:
-    generated_at: "2026-04-24T03:43:41Z"
-    model: gpt-5.4
+    generated_at: "2026-04-29T08:48:33Z"
+    model: gpt-5.5
    provider: openai
-    source_hash: c4a965f39a14697a677c89ccadeb2b11b10c8e704e81e00619fffd5abe2ebc83
+    source_hash: f96e5e8d46e694f0dfc67eeeb34f4c49498a56e384c3a2a6266c2214afdc0870
    source_path: start/setup.md
-    workflow: 15
+    workflow: 16
 ---

 <Note>
-如果这是你第一次设置，请先阅读[入门指南](/zh-CN/start/getting-started)。
-有关新手引导的详细信息，请参阅[设置向导（CLI）](/zh-CN/start/wizard)。
+如果你是首次设置，请从[入门指南](/zh-CN/start/getting-started)开始。
+有关新手引导详情，请参阅[新手引导（CLI）](/zh-CN/start/wizard)。
 </Note>

-## TL;DR
+## 简要概览

-根据你希望更新的频率，以及你是否想自己运行 Gateway 网关，选择一种设置工作流：
+根据你想要更新的频率，以及是否想自己运行 Gateway 网关，选择一个设置流程：

- **个性化内容放在仓库之外：** 将你的配置和工作区保存在 `~/.openclaw/openclaw.json` 和 `~/.openclaw/workspace/` 中，这样仓库更新就不会影响它们。
- **稳定工作流（推荐大多数人使用）：** 安装 macOS 应用，并让它运行内置的 Gateway 网关。
- **前沿工作流（开发）：** 通过 `pnpm gateway:watch` 自行运行 Gateway 网关，然后让 macOS 应用在本地模式下连接上来。
+- **定制内容位于仓库之外：** 将你的配置和工作区保存在 `~/.openclaw/openclaw.json` 和 `~/.openclaw/workspace/` 中，这样仓库更新不会影响它们。
+- **稳定流程（推荐大多数人使用）：** 安装 macOS 应用，并让它运行内置的 Gateway 网关。
+- **前沿流程（开发）：** 通过 `pnpm gateway:watch` 自己运行 Gateway 网关，然后让 macOS 应用以 Local 模式连接。

-## 前置要求（从源码）
+## 前置条件（从源码运行）

- 推荐使用 Node 24（仍支持 Node 22 LTS，目前为 `22.14+`）
- 推荐使用 `pnpm`（或者如果你明确要使用 [Bun 工作流](/zh-CN/install/bun)，也可以用 Bun）
- Docker（可选；仅用于容器化设置/e2e——请参阅 [Docker](/zh-CN/install/docker)）
+- 推荐 Node 24（Node 22 LTS，目前为 `22.14+`，仍受支持）
+- 首选 `pnpm`（如果你有意使用 [Bun 流程](/zh-CN/install/bun)，也可以使用 Bun）
+- Docker（可选；仅用于容器化设置/e2e，请参阅 [Docker](/zh-CN/install/docker)）

-## 个性化策略（这样更新就不会伤到你）
+## 定制策略（避免更新造成影响）

-如果你想要“100% 按我定制”**并且**易于更新，请将你的自定义内容保存在：
+如果你想要“100% 按我定制”_并且_轻松更新，请将你的自定义内容保存在：

- **配置：** `~/.openclaw/openclaw.json`（JSON/近似 JSON5）
- **工作区：** `~/.openclaw/workspace`（skills、提示词、记忆；建议将其设为私有 git 仓库）
+- **配置：** `~/.openclaw/openclaw.json`（JSON/类似 JSON5）
+- **工作区：** `~/.openclaw/workspace`（skills、prompts、memories；将其设为私有 git 仓库）

-一次性初始化：
+只需引导一次：

 ```bash
 openclaw setup
 ```

-在这个仓库内，使用本地 CLI 入口：
+在此仓库内，使用本地 CLI 入口：

 ```bash
 openclaw setup
 ```

-如果你还没有全局安装，请通过 `pnpm openclaw setup` 运行（如果你使用的是 Bun 工作流，则用 `bun run openclaw setup`）。
+如果你还没有全局安装，请通过 `pnpm openclaw setup` 运行（如果你正在使用 Bun 流程，则使用 `bun run openclaw setup`）。

 ## 从此仓库运行 Gateway 网关

-执行 `pnpm build` 后，你可以直接运行打包后的 CLI：
+执行 `pnpm build` 后，可以直接运行打包后的 CLI：

 ```bash
 node openclaw.mjs gateway --port 18789 --verbose
 ```

-## 稳定工作流（先用 macOS 应用）
+## 稳定流程（macOS 应用优先）

-1. 安装并启动 **OpenClaw.app**（菜单栏应用）。
+1. 安装并启动 **OpenClaw.app**（菜单栏）。
 2. 完成新手引导/权限检查清单（TCC 提示）。
-3. 确保 Gateway 网关处于 **Local** 模式并正在运行（由应用管理）。
-4. 连接各个接口（例如：WhatsApp）：
+3. 确保 Gateway 网关为 **Local** 且正在运行（由应用管理）。
+4. 关联界面（示例：WhatsApp）：

 ```bash
 openclaw channels login
@ -82,51 +82,50 @@ openclaw health

 - 运行 `openclaw setup`，然后运行 `openclaw channels login`，再手动启动 Gateway 网关（`openclaw gateway`）。

-## 前沿工作流（在终端中运行 Gateway 网关）
+## 前沿流程（在终端中运行 Gateway 网关）

-目标：开发 TypeScript Gateway 网关，获得热重载，同时保持 macOS 应用 UI 已连接。
+目标：开发 TypeScript Gateway 网关，获得热重载，并保持 macOS 应用 UI 已连接。

-### 0）（可选）也从源码运行 macOS 应用
+### 0)（可选）也从源码运行 macOS 应用

-如果你也想让 macOS 应用使用前沿版本：
+如果你还想让 macOS 应用也使用前沿版本：

 ```bash
 ./scripts/restart-mac.sh
 ```

-### 1）启动开发版 Gateway 网关
+### 1) 启动开发 Gateway 网关

 ```bash
 pnpm install
-# 仅首次运行（或在重置本地 OpenClaw 配置/工作区之后）
+# 仅首次运行（或重置本地 OpenClaw 配置/工作区后）
 pnpm openclaw setup
 pnpm gateway:watch
 ```

-`gateway:watch` 会以 watch 模式运行 gateway，并在相关源码、
-配置以及内置插件元数据变更时重新加载。
-`pnpm openclaw setup` 是全新 checkout 时，用于初始化本地配置/工作区的一次性步骤。
-`pnpm gateway:watch` 不会重建 `dist/control-ui`，因此在 `ui/` 变更后请重新运行 `pnpm ui:build`，或在开发 Control UI 时使用 `pnpm ui:dev`。
+`gateway:watch` 会在一个具名 tmux 会话中启动或重启 Gateway 网关监听进程，并从交互式终端自动附加。非交互式 shell 会保持分离并打印 `tmux attach -t openclaw-gateway-watch-main`；使用 `OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch` 可让交互式运行保持分离，或使用 `pnpm gateway:watch:raw` 以前台监听模式运行。监听器会在相关源码、配置和内置插件元数据变更时重新加载。
+`pnpm openclaw setup` 是全新检出时一次性的本地配置/工作区初始化步骤。
+`pnpm gateway:watch` 不会重新构建 `dist/control-ui`，因此在 `ui/` 变更后请重新运行 `pnpm ui:build`，或在开发 Control UI 时使用 `pnpm ui:dev`。

-如果你明确使用的是 Bun 工作流，对应命令为：
+如果你有意使用 Bun 流程，等价命令如下：

 ```bash
 bun install
-# 仅首次运行（或在重置本地 OpenClaw 配置/工作区之后）
+# 仅首次运行（或重置本地 OpenClaw 配置/工作区后）
 bun run openclaw setup
 bun run gateway:watch
 ```

-### 2）让 macOS 应用连接到你正在运行的 Gateway 网关
+### 2) 将 macOS 应用指向你正在运行的 Gateway 网关

 在 **OpenClaw.app** 中：

 - 连接模式：**Local**
-  应用会连接到已配置端口上正在运行的 gateway。
+  应用会连接到已配置端口上正在运行的 Gateway 网关。

-### 3）验证
+### 3) 验证

- 应用内的 Gateway 网关状态应显示为 **“Using existing gateway …”**
+- 应用内 Gateway 网关状态应显示 **“正在使用现有 Gateway 网关 …”**
 - 或通过 CLI：

 ```bash
@ -135,7 +134,7 @@ openclaw health

 ### 常见陷阱

- **端口错误：** Gateway WebSocket 默认是 `ws://127.0.0.1:18789`；请确保应用和 CLI 使用同一个端口。
+- **端口错误：** Gateway 网关 WS 默认值为 `ws://127.0.0.1:18789`；保持应用和 CLI 使用同一端口。
 - **状态存储位置：**
  - 渠道/提供商状态：`~/.openclaw/credentials/`
  - 模型认证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
@ -144,42 +143,39 @@ openclaw health

 ## 凭证存储映射

-在调试认证问题或决定备份哪些内容时，可参考这里：
+在调试认证或决定备份内容时使用此映射：

 - **WhatsApp**：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- **Telegram bot token**：配置/env 或 `channels.telegram.tokenFile`（仅允许普通文件；拒绝符号链接）
- **Discord bot token**：配置/env 或 SecretRef（env/file/exec 提供商）
- **Slack tokens**：配置/env（`channels.slack.*`）
- **配对允许列表：**
+- **Telegram 机器人令牌**：配置/环境变量或 `channels.telegram.tokenFile`（仅普通文件；拒绝符号链接）
+- **Discord 机器人令牌**：配置/环境变量或 SecretRef（env/file/exec 提供商）
+- **Slack 令牌**：配置/环境变量（`channels.slack.*`）
+- **配对允许列表**：
  - `~/.openclaw/credentials/<channel>-allowFrom.json`（默认账户）
  - `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json`（非默认账户）
 - **模型认证配置文件**：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- **基于文件的 secrets 负载（可选）**：`~/.openclaw/secrets.json`
+- **文件支持的 secrets 有效载荷（可选）**：`~/.openclaw/secrets.json`
 - **旧版 OAuth 导入**：`~/.openclaw/credentials/oauth.json`
-  更多细节请参阅：[安全](/zh-CN/gateway/security#credential-storage-map)。
+  更多详情：[安全](/zh-CN/gateway/security#credential-storage-map)。

 ## 更新（不破坏你的设置）

- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 视为“你的内容”；不要把个人提示词/配置放进 `openclaw` 仓库中。
- 更新源码：`git pull` + 你所选包管理器的安装步骤（默认是 `pnpm install`；Bun 工作流使用 `bun install`）+ 继续使用对应的 `gateway:watch` 命令。
+- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 视为“你的内容”；不要把个人 prompts/配置放进 `openclaw` 仓库。
+- 更新源码：`git pull` + 你选择的包管理器安装步骤（默认 `pnpm install`；Bun 流程使用 `bun install`）+ 继续使用匹配的 `gateway:watch` 命令。

 ## Linux（systemd 用户服务）

-Linux 安装使用 systemd **用户**服务。默认情况下，systemd 会在用户
-注销/空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用
-lingering（可能会提示输入 sudo）。如果仍未启用，请运行：
+Linux 安装使用 systemd **用户**服务。默认情况下，systemd 会在注销/空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用 linger（可能会提示输入 sudo）。如果仍未启用，请运行：

 ```bash
 sudo loginctl enable-linger $USER
 ```

-对于始终在线或多用户服务器，可考虑使用**系统**服务而不是
-用户服务（这样就不需要 lingering）。有关 systemd 的说明，请参阅 [Gateway runbook](/zh-CN/gateway)。
+对于常驻或多用户服务器，请考虑使用 **system** 服务而不是用户服务（无需 linger）。systemd 说明请参阅 [Gateway 网关运行手册](/zh-CN/gateway)。

 ## 相关文档

- [Gateway runbook](/zh-CN/gateway)（标志、托管、端口）
- [Gateway 网关配置](/zh-CN/gateway/configuration)（配置 schema + 示例）
- [Discord](/zh-CN/channels/discord) 和 [Telegram](/zh-CN/channels/telegram)（回复标签 + `replyToMode` 设置）
- [OpenClaw assistant 设置](/zh-CN/start/openclaw)
- [macOS 应用](/zh-CN/platforms/macos)（gateway 生命周期）
+- [Gateway 网关运行手册](/zh-CN/gateway)（标志、监督、端口）
+- [Gateway 网关配置](/zh-CN/gateway/configuration)（配置架构 + 示例）
+- [Discord](/zh-CN/channels/discord) 和 [Telegram](/zh-CN/channels/telegram)（回复标签 + replyToMode 设置）
+- [OpenClaw 助手设置](/zh-CN/start/openclaw)
+- [macOS 应用](/zh-CN/platforms/macos)（Gateway 网关生命周期）