Docs: update zh-CN translations and pipeline

What: - update zh-CN glossary, TM, and translator prompt - regenerate zh-CN docs and apply targeted fixes - add zh-CN AGENTS pipeline guidance Why: - address terminology/spacing feedback from #6995 Tests: - pnpm build && pnpm check && pnpm test
2026-06-28 17:01:53 +03:00 · 2026-02-03 13:23:00 -08:00
parent 9f03791aa9
commit a3ec2d0734
228 changed files with 10651 additions and 10475 deletions
@@ -1,12 +1,12 @@
 ---
 read_when:
  - 配对或重新连接 Android 节点
-  - 调试 Android Gateway网关发现或认证问题
+  - 调试 Android Gateway 网关发现或认证
  - 验证跨客户端的聊天历史一致性
-summary: Android 应用（节点）：连接运维手册 + Canvas/聊天/相机
+summary: Android 应用（节点）：连接操作手册 + Canvas/Chat/Camera
 title: Android 应用
 x-i18n:
-  generated_at: "2026-02-01T21:19:33Z"
+  generated_at: "2026-02-03T07:51:34Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 9cd02f12065ce2bc483379c9afd7537489d9076094f4a412cf9f21ccc47f0e38
@@ -18,32 +18,32 @@ x-i18n:

 ## 支持概览

- 角色：伴侣节点应用（Android 不托管 Gateway网关）。
- 需要 Gateway网关：是（在 macOS、Linux 或通过 WSL2 的 Windows 上运行）。
+- 角色：配套节点应用（Android 不托管 Gateway 网关）。
+- 需要 Gateway 网关：是（在 macOS、Linux 或通过 WSL2 的 Windows 上运行）。
 - 安装：[入门指南](/start/getting-started) + [配对](/gateway/pairing)。
- Gateway网关：[运维手册](/gateway) + [配置](/gateway/configuration)。
-  - 协议：[Gateway网关协议](/gateway/protocol)（节点 + 控制平面）。
+- Gateway 网关：[操作手册](/gateway) + [配置](/gateway/configuration)。
+  - 协议：[Gateway 网关协议](/gateway/protocol)（节点 + 控制平面）。

 ## 系统控制

-系统控制（launchd/systemd）在 Gateway网关主机上。参见 [Gateway网关](/gateway)。
+系统控制（launchd/systemd）位于 Gateway 网关主机上。参见 [Gateway 网关](/gateway)。

-## 连接运维手册
+## 连接操作手册

-Android 节点应用 ⇄（mDNS/NSD + WebSocket）⇄ **Gateway网关**
+Android 节点应用 ⇄（mDNS/NSD + WebSocket）⇄ **Gateway 网关**

-Android 直接连接到 Gateway网关 WebSocket（默认 `ws://<host>:18789`）并使用 Gateway网关管理的配对。
+Android 直接连接到 Gateway 网关 WebSocket（默认 `ws://<host>:18789`）并使用 Gateway 网关拥有的配对。

-### 前提条件
+### 前置条件

- 你可以在"主"机器上运行 Gateway网关。
- Android 设备/模拟器可以访问 Gateway网关 WebSocket：
-  - 同一局域网且支持 mDNS/NSD，**或**
-  - 同一 Tailscale tailnet，使用 Wide-Area Bonjour / 单播 DNS-SD（见下文），**或**
-  - 手动指定 Gateway网关主机/端口（备用方案）
- 你可以在 Gateway网关机器上（或通过 SSH）运行 CLI（`openclaw`）。
+- 你可以在"主"机器上运行 Gateway 网关。
+- Android 设备/模拟器可以访问 Gateway 网关 WebSocket：
+  - 使用 mDNS/NSD 的同一局域网，**或**
+  - 使用 Wide-Area Bonjour / unicast DNS-SD 的同一 Tailscale tailnet（见下文），**或**
+  - 手动 Gateway 网关主机/端口（回退方案）
+- 你可以在 Gateway 网关机器上运行 CLI（`openclaw`）（或通过 SSH）。

-### 1）启动 Gateway网关
+### 1）启动 Gateway 网关

 ```bash
 openclaw gateway --port 18789 --verbose
@@ -53,14 +53,14 @@ openclaw gateway --port 18789 --verbose

 - `listening on ws://0.0.0.0:18789`

-对于仅 tailnet 的设置（推荐用于 Vienna ⇄ London），将 Gateway网关绑定到 tailnet IP：
+对于仅 tailnet 设置（推荐用于维也纳 ⇄ 伦敦），将 Gateway 网关绑定到 tailnet IP：

- 在 Gateway网关主机的 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。
- 重启 Gateway网关 / macOS 菜单栏应用。
+- 在 Gateway 网关主机的 `~/.openclaw/openclaw.json` 中设置 `gateway.bind: "tailnet"`。
+- 重启 Gateway 网关 / macOS 菜单栏应用。

 ### 2）验证发现（可选）

-在 Gateway网关机器上：
+从 Gateway 网关机器：

 ```bash
 dns-sd -B _openclaw-gw._tcp local.
@@ -68,12 +68,12 @@ dns-sd -B _openclaw-gw._tcp local.

 更多调试说明：[Bonjour](/gateway/bonjour)。

-#### Tailnet（Vienna ⇄ London）通过单播 DNS-SD 发现
+#### 通过 unicast DNS-SD 的 Tailnet（维也纳 ⇄ 伦敦）发现

-Android NSD/mDNS 发现无法跨网络工作。如果你的 Android 节点和 Gateway网关在不同网络上但通过 Tailscale 连接，请改用 Wide-Area Bonjour / 单播 DNS-SD：
+Android NSD/mDNS 发现无法跨网络。如果你的 Android 节点和 Gateway 网关在不同网络但通过 Tailscale 连接，请改用 Wide-Area Bonjour / unicast DNS-SD：

-1. 在 Gateway网关主机上设置 DNS-SD 区域（示例 `openclaw.internal.`）并发布 `_openclaw-gw._tcp` 记录。
-2. 配置 Tailscale split DNS，将你选择的域名指向该 DNS 服务器。
+1. 在 Gateway 网关主机上设置 DNS-SD 区域（示例 `openclaw.internal.`）并发布 `_openclaw-gw._tcp` 记录。
+2. 配置 Tailscale split DNS，将你选择的域指向该 DNS 服务器。

 详情和示例 CoreDNS 配置：[Bonjour](/gateway/bonjour)。

@@ -81,26 +81,26 @@ Android NSD/mDNS 发现无法跨网络工作。如果你的 Android 节点和 Ga

 在 Android 应用中：

- 应用通过**前台服务**（持久通知）保持 Gateway网关连接活跃。
+- 应用通过**前台服务**（持久通知）保持 Gateway 网关连接活动。
 - 打开**设置**。
- 在**已发现的 Gateway网关** 下，选择你的 Gateway网关并点击**连接**。
- 如果 mDNS 被阻止，使用**高级 → 手动 Gateway网关**（主机 + 端口）并点击**连接（手动）**。
+- 在**发现的 Gateway 网关**下，选择你的 Gateway 网关并点击**连接**。
+- 如果 mDNS 被阻止，使用**高级 → 手动 Gateway 网关**（主机 + 端口）并**连接（手动）**。

-首次成功配对后，Android 会在启动时自动重连：
+首次成功配对后，Android 在启动时自动重连：

- 手动端点（如已启用），否则
- 上次发现的 Gateway网关（尽力而为）。
+- 手动端点（如果启用），否则
+- 上次发现的 Gateway 网关（尽力而为）。

-### 4）审批配对（CLI）
+### 4）批准配对（CLI）

-在 Gateway网关机器上：
+在 Gateway 网关机器上：

 ```bash
 openclaw nodes pending
 openclaw nodes approve <requestId>
 ```

-配对详情：[Gateway网关配对](/gateway/pairing)。
+配对详情：[Gateway 网关配对](/gateway/pairing)。

 ### 5）验证节点已连接

@@ -108,48 +108,48 @@ openclaw nodes approve <requestId>
  ```bash
  openclaw nodes status
  ```
- 通过 Gateway网关：
+- 通过 Gateway 网关：
  ```bash
  openclaw gateway call node.list --params "{}"
  ```

-### 6）聊天 + 历史记录
+### 6）聊天 + 历史

-Android 节点的聊天界面使用 Gateway网关的**主会话键**（`main`），因此历史记录和回复与 WebChat 及其他客户端共享：
+Android 节点的 Chat 面板使用 Gateway 网关的**主会话键**（`main`），因此历史和回复与 WebChat 和其他客户端共享：

- 历史记录：`chat.history`
+- 历史：`chat.history`
 - 发送：`chat.send`
 - 推送更新（尽力而为）：`chat.subscribe` → `event:"chat"`

-### 7）Canvas + 相机
+### 7）Canvas + 摄像头

-#### Gateway网关 Canvas 主机（推荐用于 Web 内容）
+#### Gateway 网关 Canvas 主机（推荐用于 web 内容）

-如果你希望节点显示智能体可以在磁盘上编辑的真实 HTML/CSS/JS，请将节点指向 Gateway网关 canvas 主机。
+如果你想让节点显示智能体可以在磁盘上编辑的真实 HTML/CSS/JS，请将节点指向 Gateway 网关 canvas 主机。

 注意：节点使用 `canvasHost.port`（默认 `18793`）上的独立 canvas 主机。

-1. 在 Gateway网关主机上创建 `~/.openclaw/workspace/canvas/index.html`。
+1. 在 Gateway 网关主机上创建 `~/.openclaw/workspace/canvas/index.html`。

-2. 将节点导航到该地址（局域网）：
+2. 将节点导航到它（局域网）：

 ```bash
 openclaw nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__openclaw__/canvas/"}'
 ```

-Tailnet（可选）：如果两台设备都在 Tailscale 上，使用 MagicDNS 名称或 tailnet IP 替代 `.local`，例如 `http://<gateway-magicdns>:18793/__openclaw__/canvas/`。
+Tailnet（可选）：如果两个设备都在 Tailscale 上，使用 MagicDNS 名称或 tailnet IP 而不是 `.local`，例如 `http://<gateway-magicdns>:18793/__openclaw__/canvas/`。

-该服务器会向 HTML 注入实时重载客户端，并在文件变更时重新加载。
+此服务器将实时重载客户端注入 HTML 并在文件更改时重新加载。
 A2UI 主机位于 `http://<gateway-host>:18793/__openclaw__/a2ui/`。

 Canvas 命令（仅前台）：

 - `canvas.eval`、`canvas.snapshot`、`canvas.navigate`（使用 `{"url":""}` 或 `{"url":"/"}` 返回默认脚手架）。`canvas.snapshot` 返回 `{ format, base64 }`（默认 `format="jpeg"`）。
- A2UI：`canvas.a2ui.push`、`canvas.a2ui.reset`（`canvas.a2ui.pushJSONL` 旧版别名）
+- A2UI：`canvas.a2ui.push`、`canvas.a2ui.reset`（`canvas.a2ui.pushJSONL` 遗留别名）

-相机命令（仅前台；需权限）：
+摄像头命令（仅前台；权限限制）：

 - `camera.snap`（jpg）
 - `camera.clip`（mp4）

-参见[相机节点](/nodes/camera)了解参数和 CLI 辅助工具。
+参见 [Camera 节点](/nodes/camera) 了解参数和 CLI 助手。
@@ -2,10 +2,10 @@
 read_when:
  - 在 DigitalOcean 上设置 OpenClaw
  - 寻找便宜的 VPS 托管来运行 OpenClaw
-summary: 在 DigitalOcean 上运行 OpenClaw（简单的付费 VPS 方案）
+summary: 在 DigitalOcean 上运行 OpenClaw（简单的付费 VPS 选项）
 title: DigitalOcean
 x-i18n:
-  generated_at: "2026-02-01T21:20:02Z"
+  generated_at: "2026-02-03T07:51:55Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: d60559b8751da37413e5364e83c88254b476b2283386a0b07b2ca6b4e16157fc
@@ -17,25 +17,25 @@ x-i18n:

 ## 目标

-在 DigitalOcean 上运行持久化的 OpenClaw Gateway网关，费用为**每月 $6**（预留定价为每月 $4）。
+以 **$6/月**（或使用预留定价 $4/月）在 DigitalOcean 上运行持久的 OpenClaw Gateway 网关。

-如果你想要每月 $0 的方案且不介意 ARM + 特定提供商的设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。
+如果你想要 $0/月的选项且不介意 ARM + 特定提供商的设置，请参阅 [Oracle Cloud 指南](/platforms/oracle)。

-## 费用对比（2026）
+## 成本比较（2026）

-| 提供商       | 方案            | 规格                  | 月费        | 备注                       |
-| ------------ | --------------- | --------------------- | ----------- | -------------------------- |
-| Oracle Cloud | Always Free ARM | 最高 4 OCPU, 24GB RAM | $0          | ARM，容量有限 / 注册较繁琐 |
-| Hetzner      | CX22            | 2 vCPU, 4GB RAM       | €3.79 (~$4) | 最便宜的付费方案           |
-| DigitalOcean | Basic           | 1 vCPU, 1GB RAM       | $6          | 界面简洁，文档完善         |
-| Vultr        | Cloud Compute   | 1 vCPU, 1GB RAM       | $6          | 节点位置多                 |
-| Linode       | Nanode          | 1 vCPU, 1GB RAM       | $5          | 现为 Akamai 旗下           |
+| 提供商       | 方案            | 配置                  | 价格/月     | 备注                     |
+| ------------ | --------------- | --------------------- | ----------- | ------------------------ |
+| Oracle Cloud | Always Free ARM | 最高 4 OCPU、24GB RAM | $0          | ARM，容量有限 / 注册有坑 |
+| Hetzner      | CX22            | 2 vCPU、4GB RAM       | €3.79 (~$4) | 最便宜的付费选项         |
+| DigitalOcean | Basic           | 1 vCPU、1GB RAM       | $6          | 界面简单，文档完善       |
+| Vultr        | Cloud Compute   | 1 vCPU、1GB RAM       | $6          | 多地区可选               |
+| Linode       | Nanode          | 1 vCPU、1GB RAM       | $5          | 现为 Akamai 旗下         |

 **选择提供商：**

- DigitalOcean：最简单的用户体验 + 可预期的设置流程（本指南）
+- DigitalOcean：最简单的用户体验 + 可预测的设置（本指南）
 - Hetzner：性价比高（参见 [Hetzner 指南](/platforms/hetzner)）
- Oracle Cloud：可以每月 $0，但配置较繁琐且仅支持 ARM（参见 [Oracle 指南](/platforms/oracle)）
+- Oracle Cloud：可以 $0/月，但更麻烦且仅限 ARM（参见 [Oracle 指南](/platforms/oracle)）

 ---

@@ -45,42 +45,42 @@ x-i18n:
 - SSH 密钥对（或愿意使用密码认证）
 - 约 20 分钟

-## 1）创建 Droplet
+## 1) 创建 Droplet

 1. 登录 [DigitalOcean](https://cloud.digitalocean.com/)
 2. 点击 **Create → Droplets**
 3. 选择：
-   - **区域：** 离你（或你的用户）最近的
-   - **镜像：** Ubuntu 24.04 LTS
-   - **规格：** Basic → Regular → **$6/月**（1 vCPU, 1GB RAM, 25GB SSD）
-   - **认证：** SSH 密钥（推荐）或密码
+   - **Region：** 离你（或你的用户）最近的地区
+   - **Image：** Ubuntu 24.04 LTS
+   - **Size：** Basic → Regular → **$6/mo**（1 vCPU、1GB RAM、25GB SSD）
+   - **Authentication：** SSH 密钥（推荐）或密码
 4. 点击 **Create Droplet**
 5. 记下 IP 地址

-## 2）通过 SSH 连接
+## 2) 通过 SSH 连接

 ```bash
 ssh root@YOUR_DROPLET_IP
 ```

-## 3）安装 OpenClaw
+## 3) 安装 OpenClaw

 ```bash
-# 更新系统
+# Update system
 apt update && apt upgrade -y

-# 安装 Node.js 22
+# Install Node.js 22
 curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
 apt install -y nodejs

-# 安装 OpenClaw
+# Install OpenClaw
 curl -fsSL https://openclaw.ai/install.sh | bash

-# 验证
+# Verify
 openclaw --version
 ```

-## 4）运行新手引导
+## 4) 运行新手引导

 ```bash
 openclaw onboard --install-daemon
@@ -90,43 +90,43 @@ openclaw onboard --install-daemon

 - 模型认证（API 密钥或 OAuth）
 - 渠道设置（Telegram、WhatsApp、Discord 等）
- Gateway网关令牌（自动生成）
+- Gateway 网关令牌（自动生成）
 - 守护进程安装（systemd）

-## 5）验证 Gateway网关
+## 5) 验证 Gateway 网关

 ```bash
-# 检查状态
+# Check status
 openclaw status

-# 检查服务
+# Check service
 systemctl --user status openclaw-gateway.service

-# 查看日志
+# View logs
 journalctl --user -u openclaw-gateway.service -f
 ```

-## 6）访问控制面板
+## 6) 访问控制面板

-Gateway网关默认绑定到 local loopback。要访问控制面板 UI：
+Gateway 网关默认绑定到 loopback。要访问控制界面：

-**方案 A：SSH 隧道（推荐）**
+**选项 A：SSH 隧道（推荐）**

 ```bash
-# 从你的本地机器
+# From your local machine
 ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP

-# 然后打开：http://localhost:18789
+# Then open: http://localhost:18789
 ```

-**方案 B：Tailscale Serve（HTTPS，仅 local loopback）**
+**选项 B：Tailscale Serve（HTTPS，仅 loopback）**

 ```bash
-# 在 Droplet 上
+# On the droplet
 curl -fsSL https://tailscale.com/install.sh | sh
 tailscale up

-# 配置 Gateway网关使用 Tailscale Serve
+# Configure Gateway to use Tailscale Serve
 openclaw config set gateway.tailscale.mode serve
 openclaw gateway restart
 ```
@@ -135,10 +135,10 @@ openclaw gateway restart

 注意事项：

- Serve 保持 Gateway网关仅绑定 local loopback，并通过 Tailscale 身份头进行认证。
- 如需使用令牌/密码认证，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。
+- Serve 保持 Gateway 网关仅 loopback 并通过 Tailscale 身份头进行认证。
+- 要改为需要令牌/密码，请设置 `gateway.auth.allowTailscale: false` 或使用 `gateway.auth.mode: "password"`。

-**方案 C：Tailnet 绑定（不使用 Serve）**
+**选项 C：Tailnet 绑定（不使用 Serve）**

 ```bash
 openclaw config set gateway.bind tailnet
@@ -147,7 +147,7 @@ openclaw gateway restart

 打开：`http://<tailscale-ip>:18789`（需要令牌）。

-## 7）连接你的渠道
+## 7) 连接你的渠道

 ### Telegram

@@ -160,18 +160,18 @@ openclaw pairing approve telegram <CODE>

 ```bash
 openclaw channels login whatsapp
-# 扫描二维码
+# Scan QR code
 ```

-其他提供商请参阅[渠道](/channels)。
+参见[渠道](/channels)了解其他提供商。

 ---

-## 1GB RAM 的优化建议
+## 1GB RAM 的优化

-$6 的 Droplet 只有 1GB RAM。为保持运行流畅：
+$6 的 droplet 只有 1GB RAM。为了保持运行流畅：

-### 添加交换空间（推荐）
+### 添加 swap（推荐）

 ```bash
 fallocate -l 2G /swapfile
@@ -183,9 +183,9 @@ echo '/swapfile none swap sw 0 0' >> /etc/fstab

 ### 使用更轻量的模型

-如果遇到内存不足（OOM），可以考虑：
+如果遇到 OOM，考虑：

- 使用基于 API 的模型（Claude、GPT）而非本地模型
+- 使用基于 API 的模型（Claude、GPT）而不是本地模型
 - 将 `agents.defaults.model.primary` 设置为更小的模型

 ### 监控内存
@@ -201,10 +201,10 @@ htop

 所有状态存储在：

- `~/.openclaw/` — 配置、凭据、会话数据
+- `~/.openclaw/` — 配置、凭证、会话数据
 - `~/.openclaw/workspace/` — 工作区（SOUL.md、记忆等）

-这些内容在重启后不会丢失。定期备份：
+这些在重启后保留。定期备份：

 ```bash
 tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace
@@ -214,27 +214,27 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace

 ## Oracle Cloud 免费替代方案

-Oracle Cloud 提供 **Always Free** ARM 实例，性能远超此处任何付费方案——每月 $0。
+Oracle Cloud 提供 **Always Free** ARM 实例，比这里任何付费选项都强大得多 — 每月 $0。

-| 你将获得       | 规格             |
+| 你将获得       | 配置             |
 | -------------- | ---------------- |
-| **4 OCPU**     | ARM Ampere A1    |
+| **4 OCPUs**    | ARM Ampere A1    |
 | **24GB RAM**   | 绰绰有余         |
 | **200GB 存储** | 块存储卷         |
-| **永久免费**   | 不会扣信用卡费用 |
+| **永久免费**   | 不收取信用卡费用 |

 **注意事项：**

- 注册过程可能较繁琐（失败时请重试）
- ARM 架构——大多数工具可正常工作，但部分二进制文件需要 ARM 构建版本
+- 注册可能有点麻烦（失败了就重试）
+- ARM 架构 — 大多数东西都能工作，但有些二进制文件需要 ARM 构建

-完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。注册技巧和注册流程故障排除请参阅此[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。
+完整设置指南请参阅 [Oracle Cloud](/platforms/oracle)。关于注册技巧和注册流程故障排除，请参阅此[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。

 ---

 ## 故障排除

-### Gateway网关无法启动
+### Gateway 网关无法启动

 ```bash
 openclaw gateway status
@@ -242,7 +242,7 @@ openclaw doctor --non-interactive
 journalctl -u openclaw --no-pager -n 50
 ```

-### 端口已被占用
+### 端口已被使用

 ```bash
 lsof -i :18789
@@ -252,18 +252,18 @@ kill <PID>
 ### 内存不足

 ```bash
-# 检查内存
+# Check memory
 free -h

-# 添加更多交换空间
-# 或升级到 $12/月的 Droplet（2GB RAM）
+# Add more swap
+# Or upgrade to $12/mo droplet (2GB RAM)
 ```

 ---

 ## 另请参阅

- [Hetzner 指南](/platforms/hetzner) — 更便宜，性能更强
+- [Hetzner 指南](/platforms/hetzner) — 更便宜、更强大
 - [Docker 安装](/install/docker) — 容器化设置
 - [Tailscale](/gateway/tailscale) — 安全远程访问
 - [配置](/gateway/configuration) — 完整配置参考
@@ -1,40 +1,40 @@
 ---
 read_when:
-  - 你想要一个便宜的常驻 Linux 主机来运行 Gateway网关
-  - 你想在不自行运维 VPS 的情况下远程访问控制面板 UI
-summary: 在 exe.dev 上运行 OpenClaw Gateway网关（虚拟机 + HTTPS 代理）以实现远程访问
+  - 你想要一个便宜的常驻 Linux 主机来运行 Gateway 网关
+  - 你想要远程控制 UI 访问而无需运行自己的 VPS
+summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问
 title: exe.dev
 x-i18n:
-  generated_at: "2026-02-01T21:20:17Z"
+  generated_at: "2026-02-03T07:51:36Z"
  model: claude-opus-4-5
  provider: pi
-  source_hash: d4697efb0ff219f6222a932e89572182d311b267c393297b052c1296a6936eda
+  source_hash: 8d57ee7dd6029f0b778465c147092b824a0f1b0680af13032aaf116ff3d4d671
  source_path: platforms/exe-dev.md
  workflow: 15
 ---

 # exe.dev

-目标：在 exe.dev 虚拟机上运行 OpenClaw Gateway网关，通过以下地址从你的笔记本访问：`https://<vm-name>.exe.xyz`
+目标：OpenClaw Gateway 网关运行在 exe.dev VM 上，可从你的笔记本电脑通过以下地址访问：`https://<vm-name>.exe.xyz`

-本页假设使用 exe.dev 的默认 **exeuntu** 镜像。如果你选择了其他发行版，请相应调整软件包。
+本页假设使用 exe.dev 的默认 **exeuntu** 镜像。如果你选择了不同的发行版，请相应地映射软件包。

 ## 新手快速路径

 1. [https://exe.new/openclaw](https://exe.new/openclaw)
-2. 根据需要填入你的认证密钥/令牌
-3. 点击虚拟机旁边的"Agent"，然后等待...
+2. 根据需要填写你的认证密钥/令牌
+3. 点击 VM 旁边的"Agent"，然后等待...
 4. ???
 5. 完成

 ## 你需要什么

 - exe.dev 账户
- 通过 `ssh exe.dev` 访问 [exe.dev](https://exe.dev) 虚拟机（可选）
+- `ssh exe.dev` 访问 [exe.dev](https://exe.dev) 虚拟机（可选）

 ## 使用 Shelley 自动安装

-Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以通过我们的提示词即时安装 OpenClaw。使用的提示词如下：
+Shelley，[exe.dev](https://exe.dev) 的智能体，可以使用我们的提示立即安装 OpenClaw。使用的提示如下：

 ```
 Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw device approve <request id>". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
@@ -42,7 +42,7 @@ Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-inter

 ## 手动安装

-## 1）创建虚拟机
+## 1) 创建 VM

 从你的设备：

@@ -56,16 +56,16 @@ ssh exe.dev new
 ssh <vm-name>.exe.xyz
 ```

-提示：保持此虚拟机为**有状态**。OpenClaw 将状态存储在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下。
+提示：保持此 VM **有状态**。OpenClaw 在 `~/.openclaw/` 和 `~/.openclaw/workspace/` 下存储状态。

-## 2）安装前置依赖（在虚拟机上）
+## 2) 安装先决条件（在 VM 上）

 ```bash
 sudo apt-get update
 sudo apt-get install -y git curl jq ca-certificates openssl
 ```

-## 3）安装 OpenClaw
+## 3) 安装 OpenClaw

 运行 OpenClaw 安装脚本：

@@ -73,7 +73,7 @@ sudo apt-get install -y git curl jq ca-certificates openssl
 curl -fsSL https://openclaw.ai/install.sh | bash
 ```

-## 4）配置 nginx 将 OpenClaw 代理到端口 8000
+## 4) 设置 nginx 将 OpenClaw 代理到端口 8000

 编辑 `/etc/nginx/sites-enabled/default`：

@@ -107,13 +107,13 @@ server {
 }
 ```

-## 5）访问 OpenClaw 并授予权限
+## 5) 访问 OpenClaw 并授予权限

-访问 `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL`。使用 `openclaw devices list` 和 `openclaw device approve` 审批设备。如果不确定，可以从浏览器使用 Shelley！
+访问 `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL`（参阅新手引导中的控制 UI 输出）。使用 `openclaw devices list` 和 `openclaw devices approve <requestId>` 批准设备。如有疑问，从浏览器使用 Shelley！

 ## 远程访问

-远程访问由 [exe.dev](https://exe.dev) 的认证机制处理。默认情况下，端口 8000 的 HTTP 流量会被转发到 `https://<vm-name>.exe.xyz`，并通过邮箱认证。
+远程访问由 [exe.dev](https://exe.dev) 的认证处理。默认情况下，来自端口 8000 的 HTTP 流量通过电子邮件认证转发到 `https://<vm-name>.exe.xyz`。

 ## 更新

@@ -2,7 +2,7 @@
 description: Deploy OpenClaw on Fly.io
 title: Fly.io
 x-i18n:
-  generated_at: "2026-02-01T21:21:15Z"
+  generated_at: "2026-02-03T07:52:55Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: a00bae43e416112eb269126445c51492a30abe9e136d89e161fc4193314a876f
@@ -12,46 +12,46 @@ x-i18n:

 # Fly.io 部署

-**目标：** 在 [Fly.io](https://fly.io) 机器上运行 OpenClaw Gateway网关，配备持久化存储、自动 HTTPS 和 Discord/渠道访问。
+**目标：** OpenClaw Gateway 网关运行在 [Fly.io](https://fly.io) 机器上，具有持久存储、自动 HTTPS 和 Discord/渠道访问。

 ## 你需要什么

 - 已安装 [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/)
- Fly.io 账户（免费套餐即可）
+- Fly.io 账户（免费套餐可用）
 - 模型认证：Anthropic API 密钥（或其他提供商密钥）
- 渠道凭据：Discord 机器人令牌、Telegram 令牌等
+- 渠道凭证：Discord bot token、Telegram token 等

-## 新手快速路径
+## 初学者快速路径

 1. 克隆仓库 → 自定义 `fly.toml`
 2. 创建应用 + 卷 → 设置密钥
 3. 使用 `fly deploy` 部署
-4. 通过 SSH 创建配置或使用控制面板 UI
+4. SSH 进入创建配置或使用 Control UI

 ## 1）创建 Fly 应用

 ```bash
-# 克隆仓库
+# Clone the repo
 git clone https://github.com/openclaw/openclaw.git
 cd openclaw

-# 创建新的 Fly 应用（选择你自己的名称）
+# Create a new Fly app (pick your own name)
 fly apps create my-openclaw

-# 创建持久化卷（1GB 通常足够）
+# Create a persistent volume (1GB is usually enough)
 fly volumes create openclaw_data --size 1 --region iad
 ```

-**提示：** 选择离你最近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。
+**提示：** 选择离你近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。

 ## 2）配置 fly.toml

 编辑 `fly.toml` 以匹配你的应用名称和需求。

-**安全提示：** 默认配置会暴露公共 URL。如需无公网 IP 的加固部署，请参阅[私有部署](#私有部署加固)或使用 `fly.private.toml`。
+**安全注意事项：** 默认配置暴露公共 URL。对于没有公共 IP 的加固部署，参见[私有部署](#私有部署加固)或使用 `fly.private.toml`。

 ```toml
-app = "my-openclaw"  # 你的应用名称
+app = "my-openclaw"  # Your app name
 primary_region = "iad"

 [build]
@@ -87,34 +87,34 @@ primary_region = "iad"

 | 设置                           | 原因                                                                      |
 | ------------------------------ | ------------------------------------------------------------------------- |
-| `--bind lan`                   | 绑定到 `0.0.0.0`，使 Fly 的代理能够访问 Gateway网关                       |
-| `--allow-unconfigured`         | 无需配置文件即可启动（之后再创建）                                        |
-| `internal_port = 3000`         | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）匹配，用于 Fly 健康检查 |
+| `--bind lan`                   | 绑定到 `0.0.0.0` 以便 Fly 的代理可以访问 Gateway 网关                     |
+| `--allow-unconfigured`         | 无需配置文件启动（你稍后会创建一个）                                      |
+| `internal_port = 3000`         | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）匹配以进行 Fly 健康检查 |
 | `memory = "2048mb"`            | 512MB 太小；推荐 2GB                                                      |
-| `OPENCLAW_STATE_DIR = "/data"` | 将状态持久化到卷上                                                        |
+| `OPENCLAW_STATE_DIR = "/data"` | 在卷上持久化状态                                                          |

 ## 3）设置密钥

 ```bash
-# 必需：Gateway网关令牌（用于非 local loopback 绑定）
+# Required: Gateway token (for non-loopback binding)
 fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

-# 模型提供商 API 密钥
+# Model provider API keys
 fly secrets set ANTHROPIC_API_KEY=sk-ant-...

-# 可选：其他提供商
+# Optional: Other providers
 fly secrets set OPENAI_API_KEY=sk-...
 fly secrets set GOOGLE_API_KEY=...

-# 渠道令牌
+# Channel tokens
 fly secrets set DISCORD_BOT_TOKEN=MTQ...
 ```

 **注意事项：**

- 非 local loopback 绑定（`--bind lan`）出于安全需要 `OPENCLAW_GATEWAY_TOKEN`。
- 请像对待密码一样对待这些令牌。
- **所有 API 密钥和令牌优先使用环境变量而非配置文件**。这样可以避免密钥出现在 `openclaw.json` 中，防止意外暴露或被记录到日志。
+- 非 loopback 绑定（`--bind lan`）出于安全需要 `OPENCLAW_GATEWAY_TOKEN`。
+- 像对待密码一样对待这些 token。
+- **优先使用环境变量而不是配置文件**来存储所有 API 密钥和 token。这可以避免密钥出现在 `openclaw.json` 中，防止意外暴露或记录。

 ## 4）部署

@@ -122,7 +122,7 @@ fly secrets set DISCORD_BOT_TOKEN=MTQ...
 fly deploy
 ```

-首次部署会构建 Docker 镜像（约 2-3 分钟）。后续部署会更快。
+首次部署构建 Docker 镜像（约 2-3 分钟）。后续部署更快。

 部署后验证：

@@ -140,7 +140,7 @@ fly logs

 ## 5）创建配置文件

-通过 SSH 连接到机器以创建正式配置：
+SSH 进入机器创建正确的配置：

 ```bash
 fly ssh console
@@ -202,25 +202,25 @@ cat > /data/openclaw.json << 'EOF'
 EOF
 ```

-**注意：** 当 `OPENCLAW_STATE_DIR=/data` 时，配置路径为 `/data/openclaw.json`。
+**注意：** 使用 `OPENCLAW_STATE_DIR=/data` 时，配置路径是 `/data/openclaw.json`。

-**注意：** Discord 令牌可以来自：
+**注意：** Discord token 可以来自：

 - 环境变量：`DISCORD_BOT_TOKEN`（推荐用于密钥）
 - 配置文件：`channels.discord.token`

-如果使用环境变量，无需在配置中添加令牌。Gateway网关会自动读取 `DISCORD_BOT_TOKEN`。
+如果使用环境变量，无需将 token 添加到配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。

-重启以应用配置：
+重启以应用：

 ```bash
 exit
 fly machine restart <machine-id>
 ```

-## 6）访问 Gateway网关
+## 6）访问 Gateway 网关

-### 控制面板 UI
+### Control UI

 在浏览器中打开：

@@ -230,13 +230,13 @@ fly open

 或访问 `https://my-openclaw.fly.dev/`

-粘贴你的 Gateway网关令牌（即 `OPENCLAW_GATEWAY_TOKEN` 的值）进行认证。
+粘贴你的 Gateway 网关 token（来自 `OPENCLAW_GATEWAY_TOKEN` 的那个）进行认证。

 ### 日志

 ```bash
-fly logs              # 实时日志
-fly logs --no-tail    # 最近的日志
+fly logs              # Live logs
+fly logs --no-tail    # Recent logs
 ```

 ### SSH 控制台
@@ -249,19 +249,19 @@ fly ssh console

 ### "App is not listening on expected address"

-Gateway网关绑定到了 `127.0.0.1` 而不是 `0.0.0.0`。
+Gateway 网关绑定到 `127.0.0.1` 而不是 `0.0.0.0`。

-**修复：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。
+**修复：** 在 `fly.toml` 中的进程命令添加 `--bind lan`。

 ### 健康检查失败 / 连接被拒绝

-Fly 无法通过配置的端口访问 Gateway网关。
+Fly 无法在配置的端口上访问 Gateway 网关。

-**修复：** 确保 `internal_port` 与 Gateway网关端口匹配（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。
+**修复：** 确保 `internal_port` 与 Gateway 网关端口匹配（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。

-### 内存不足（OOM）/ 内存问题
+### OOM / 内存问题

-容器持续重启或被终止。迹象：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration` 或无声重启。
+容器持续重启或被终止。迹象：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration` 或静默重启。

 **修复：** 在 `fly.toml` 中增加内存：

@@ -278,11 +278,11 @@ fly machine update <machine-id> --vm-memory 2048 -y

 **注意：** 512MB 太小。1GB 可能可以工作但在负载或详细日志记录下可能 OOM。**推荐 2GB。**

-### Gateway网关锁文件问题
+### Gateway 网关锁问题

-Gateway网关拒绝启动并报"already running"错误。
+Gateway 网关拒绝启动并显示"already running"错误。

-这发生在容器重启但 PID 锁文件在卷上持久保留时。
+这发生在容器重启但 PID 锁文件在卷上持久存在时。

 **修复：** 删除锁文件：

@@ -291,11 +291,11 @@ fly ssh console --command "rm -f /data/gateway.*.lock"
 fly machine restart <machine-id>
 ```

-锁文件位于 `/data/gateway.*.lock`（不在子目录中）。
+锁文件在 `/data/gateway.*.lock`（不在子目录中）。

 ### 配置未被读取

-如果使用 `--allow-unconfigured`，Gateway网关会创建一个最小配置。你在 `/data/openclaw.json` 的自定义配置应在重启后被读取。
+如果使用 `--allow-unconfigured`，Gateway 网关会创建最小配置。你在 `/data/openclaw.json` 的自定义配置应该在重启时被读取。

 验证配置是否存在：

@@ -308,15 +308,15 @@ fly ssh console --command "cat /data/openclaw.json"
 `fly ssh console -C` 命令不支持 shell 重定向。要写入配置文件：

 ```bash
-# 使用 echo + tee（从本地管道到远程）
+# Use echo + tee (pipe from local to remote)
 echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

-# 或使用 sftp
+# Or use sftp
 fly sftp shell
 > put /local/path/config.json /data/openclaw.json
 ```

-**注意：** 如果文件已存在，`fly sftp` 可能会失败。请先删除：
+**注意：** 如果文件已存在，`fly sftp` 可能会失败。先删除：

 ```bash
 fly ssh console --command "rm /data/openclaw.json"
@@ -324,82 +324,82 @@ fly ssh console --command "rm /data/openclaw.json"

 ### 状态未持久化

-如果重启后凭据或会话丢失，说明状态目录写入了容器文件系统。
+如果重启后丢失凭证或会话，状态目录正在写入容器文件系统。

 **修复：** 确保 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data` 并重新部署。

 ## 更新

 ```bash
-# 拉取最新更改
+# Pull latest changes
 git pull

-# 重新部署
+# Redeploy
 fly deploy

-# 检查健康状态
+# Check health
 fly status
 fly logs
 ```

 ### 更新机器命令

-如果需要在不完全重新部署的情况下更改启动命令：
+如果你需要更改启动命令而无需完全重新部署：

 ```bash
-# 获取机器 ID
+# Get machine ID
 fly machines list

-# 更新命令
+# Update command
 fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y

-# 或同时增加内存
+# Or with memory increase
 fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y
 ```

-**注意：** `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你做了手动更改，请在部署后重新应用。
+**注意：** `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你进行了手动更改，请在部署后重新应用它们。

 ## 私有部署（加固）

-默认情况下，Fly 分配公网 IP，使你的 Gateway网关可通过 `https://your-app.fly.dev` 访问。这很方便，但意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。
+默认情况下，Fly 分配公共 IP，使你的 Gateway 网关可通过 `https://your-app.fly.dev` 访问。这很方便，但意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。

-如需**无公网暴露**的加固部署，请使用私有模板。
+对于**无公共暴露**的加固部署，使用私有模板。

 ### 何时使用私有部署

- 你只进行**出站**调用/消息（无入站 webhook）
- 你使用 **ngrok 或 Tailscale** 隧道处理 webhook 回调
- 你通过 **SSH、代理或 WireGuard** 访问 Gateway网关而非浏览器
- 你希望部署**对互联网扫描器不可见**
+- 你只进行**出站**调用/消息（无入站 webhooks）
+- 你使用 **ngrok 或 Tailscale** 隧道处理任何 webhook 回调
+- 你通过 **SSH、代理或 WireGuard** 而不是浏览器访问 Gateway 网关
+- 你希望部署**对互联网扫描器隐藏**

 ### 设置

-使用 `fly.private.toml` 代替标准配置：
+使用 `fly.private.toml` 替代标准配置：

 ```bash
-# 使用私有配置部署
+# Deploy with private config
 fly deploy -c fly.private.toml
 ```

 或转换现有部署：

 ```bash
-# 列出当前 IP
+# List current IPs
 fly ips list -a my-openclaw

-# 释放公网 IP
+# Release public IPs
 fly ips release <public-ipv4> -a my-openclaw
 fly ips release <public-ipv6> -a my-openclaw

-# 切换到私有配置，使未来的部署不再分配公网 IP
-# （移除 [http_service] 或使用私有模板部署）
+# Switch to private config so future deploys don't re-allocate public IPs
+# (remove [http_service] or deploy with the private template)
 fly deploy -c fly.private.toml

-# 分配仅私有的 IPv6
+# Allocate private-only IPv6
 fly ips allocate-v6 --private -a my-openclaw
 ```

-之后，`fly ips list` 应该只显示 `private` 类型的 IP：
+此后，`fly ips list` 应该只显示 `private` 类型的 IP：

 ```
 VERSION  IP                   TYPE             REGION
@@ -408,42 +408,42 @@ v6       fdaa:x:x:x:x::x      private          global

 ### 访问私有部署

-由于没有公网 URL，请使用以下方法之一：
+由于没有公共 URL，使用以下方法之一：

-**方案 1：本地代理（最简单）**
+**选项 1：本地代理（最简单）**

 ```bash
-# 将本地端口 3000 转发到应用
+# Forward local port 3000 to the app
 fly proxy 3000:3000 -a my-openclaw

-# 然后在浏览器中打开 http://localhost:3000
+# Then open http://localhost:3000 in browser
 ```

-**方案 2：WireGuard VPN**
+**选项 2：WireGuard VPN**

 ```bash
-# 创建 WireGuard 配置（一次性）
+# Create WireGuard config (one-time)
 fly wireguard create

-# 导入到 WireGuard 客户端，然后通过内部 IPv6 访问
-# 示例：http://[fdaa:x:x:x:x::x]:3000
+# Import to WireGuard client, then access via internal IPv6
+# Example: http://[fdaa:x:x:x:x::x]:3000
 ```

-**方案 3：仅 SSH**
+**选项 3：仅 SSH**

 ```bash
 fly ssh console -a my-openclaw
 ```

-### 私有部署中的 Webhook
+### 私有部署的 Webhooks

-如果你需要 webhook 回调（Twilio、Telnyx 等）但不想公网暴露：
+如果你需要 webhook 回调（Twilio、Telnyx 等）而不暴露公共：

 1. **ngrok 隧道** - 在容器内或作为 sidecar 运行 ngrok
 2. **Tailscale Funnel** - 通过 Tailscale 暴露特定路径
-3. **仅出站** - 某些提供商（Twilio）在无 webhook 的情况下也能正常进行出站呼叫
+3. **仅出站** - 某些提供商（Twilio）对于出站呼叫无需 webhooks 也能正常工作

-使用 ngrok 的语音通话配置示例：
+使用 ngrok 的示例语音通话配置：

 ```json
 {
@@ -461,30 +461,30 @@ fly ssh console -a my-openclaw
 }
 ```

-ngrok 隧道在容器内运行，提供公共 webhook URL 而不暴露 Fly 应用本身。
+ngrok 隧道在容器内运行并提供公共 webhook URL，而不暴露 Fly 应用本身。

 ### 安全优势

-| 方面             | 公网     | 私有     |
-| ---------------- | -------- | -------- |
-| 互联网扫描器     | 可被发现 | 隐藏     |
-| 直接攻击         | 可能     | 被阻止   |
-| 控制面板 UI 访问 | 浏览器   | 代理/VPN |
-| Webhook 投递     | 直接     | 通过隧道 |
+| 方面            | 公共   | 私有     |
+| --------------- | ------ | -------- |
+| 互联网扫描器    | 可发现 | 隐藏     |
+| 直接攻击        | 可能   | 被阻止   |
+| Control UI 访问 | 浏览器 | 代理/VPN |
+| Webhook 投递    | 直接   | 通过隧道 |

 ## 注意事项

 - Fly.io 使用 **x86 架构**（非 ARM）
 - Dockerfile 兼容两种架构
- WhatsApp/Telegram 新手引导请使用 `fly ssh console`
- 持久化数据存储在 `/data` 卷上
- Signal 需要 Java + signal-cli；请使用自定义镜像并保持内存在 2GB+ 以上。
+- 对于 WhatsApp/Telegram 新手引导，使用 `fly ssh console`
+- 持久数据位于 `/data` 卷上
+- Signal 需要 Java + signal-cli；使用自定义镜像并保持内存在 2GB+。

-## 费用
+## 成本

 使用推荐配置（`shared-cpu-2x`，2GB RAM）：

- 每月约 $10-15，取决于使用量
- 免费套餐包含一定额度
+- 根据使用情况约 $10-15/月
+- 免费套餐包含一些配额

 详情参见 [Fly.io 定价](https://fly.io/docs/about/pricing/)。
@@ -1,12 +1,12 @@
 ---
 read_when:
-  - 你希望在 GCP 上全天候运行 OpenClaw
-  - 你希望在自己的虚拟机上运行生产级、始终在线的 Gateway网关
-  - 你希望完全掌控持久化、二进制文件和重启行为
-summary: 在 GCP Compute Engine 虚拟机上全天候运行 OpenClaw Gateway网关（Docker），并实现持久化状态存储
+  - 你想在 GCP 上 24/7 运行 OpenClaw
+  - 你想要在自己的 VM 上运行生产级、常驻的 Gateway 网关
+  - 你想完全控制持久化、二进制文件和重启行为
+summary: 在 GCP Compute Engine VM（Docker）上 24/7 运行 OpenClaw Gateway 网关并持久化状态
 title: GCP
 x-i18n:
-  generated_at: "2026-02-01T21:33:10Z"
+  generated_at: "2026-02-03T07:52:50Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: abb236dd421505d307bb3869340c9a0c940de095b93af9ad1f130cc08a9deadb
@@ -14,31 +14,31 @@ x-i18n:
  workflow: 15
 ---

-# 在 GCP Compute Engine 上运行 OpenClaw（Docker，生产环境 VPS 指南）
+# 在 GCP Compute Engine 上运行 OpenClaw（Docker，生产 VPS 指南）

 ## 目标

-使用 Docker 在 GCP Compute Engine 虚拟机上运行持久化的 OpenClaw Gateway网关，实现持久状态存储、内置二进制文件和安全的重启行为。
+使用 Docker 在 GCP Compute Engine VM 上运行持久化的 OpenClaw Gateway 网关，具有持久状态、内置二进制文件和安全的重启行为。

-如果你想"以每月约 $5-12 的成本全天候运行 OpenClaw"，这是在 Google Cloud 上的可靠方案。
-价格因机器类型和区域而异；选择适合你工作负载的最小虚拟机，如果遇到 OOM 再进行扩容。
+如果你想要"OpenClaw 24/7 大约 $5-12/月"，这是在 Google Cloud 上的可靠设置。
+价格因机器类型和区域而异；选择适合你工作负载的最小 VM，如果遇到 OOM 则扩容。

-## 我们要做什么（简单说明）？
+## 我们在做什么（简单说明）？

 - 创建 GCP 项目并启用计费
- 创建 Compute Engine 虚拟机
+- 创建 Compute Engine VM
 - 安装 Docker（隔离的应用运行时）
- 在 Docker 中启动 OpenClaw Gateway网关
- 将 `~/.openclaw` + `~/.openclaw/workspace` 持久化到宿主机（重启/重建后数据不丢失）
- 通过 SSH 隧道从笔记本电脑访问控制界面
+- 在 Docker 中启动 OpenClaw Gateway 网关
+- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（重启/重建后仍保留）
+- 通过 SSH 隧道从你的笔记本电脑访问控制 UI

-Gateway网关可通过以下方式访问：
+Gateway 网关可以通过以下方式访问：

- 从笔记本电脑进行 SSH 端口转发
- 如果你自行管理防火墙和令牌，可直接暴露端口
+- 从你的笔记本电脑进行 SSH 端口转发
+- 如果你自己管理防火墙和令牌，可以直接暴露端口

 本指南使用 GCP Compute Engine 上的 Debian。
-Ubuntu 同样适用；请相应地映射软件包。
+Ubuntu 也可以；请相应地映射软件包。
 有关通用 Docker 流程，请参阅 [Docker](/install/docker)。

 ---
@@ -46,33 +46,33 @@ Ubuntu 同样适用；请相应地映射软件包。
 ## 快速路径（有经验的运维人员）

 1. 创建 GCP 项目 + 启用 Compute Engine API
-2. 创建 Compute Engine 虚拟机（e2-small，Debian 12，20GB）
-3. SSH 连接到虚拟机
+2. 创建 Compute Engine VM（e2-small，Debian 12，20GB）
+3. SSH 进入 VM
 4. 安装 Docker
 5. 克隆 OpenClaw 仓库
-6. 创建持久化宿主机目录
+6. 创建持久化主机目录
 7. 配置 `.env` 和 `docker-compose.yml`
-8. 内置所需二进制文件，构建并启动
+8. 内置所需二进制文件、构建并启动

 ---

-## 前提条件
+## 你需要什么

- GCP 账户（e2-micro 可享受免费层级）
+- GCP 账户（e2-micro 符合免费层条件）
 - 已安装 gcloud CLI（或使用 Cloud Console）
- 笔记本电脑可进行 SSH 访问
- 基本的 SSH 操作和复制/粘贴能力
+- 从你的笔记本电脑 SSH 访问
+- 对 SSH + 复制/粘贴有基本了解
 - 约 20-30 分钟
 - Docker 和 Docker Compose
- 模型认证凭据
- 可选的提供商凭据
-  - WhatsApp 二维码
-  - Telegram 机器人令牌
+- 模型认证凭证
+- 可选的提供商凭证
+  - WhatsApp QR
+  - Telegram bot token
  - Gmail OAuth

 ---

-## 1）安装 gcloud CLI（或使用 Console）
+## 1) 安装 gcloud CLI（或使用 Console）

 **选项 A：gcloud CLI**（推荐用于自动化）

@@ -87,16 +87,16 @@ gcloud auth login

 **选项 B：Cloud Console**

-所有步骤均可通过 https://console.cloud.google.com 的 Web 界面完成
+所有步骤都可以通过 https://console.cloud.google.com 的 Web UI 完成

 ---

-## 2）创建 GCP 项目
+## 2) 创建 GCP 项目

 **CLI：**

 ```bash
-gcloud projects create my-openclaw-project --name="OpenClaw Gateway网关"
+gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
 gcloud config set project my-openclaw-project
 ```

@@ -110,21 +110,21 @@ gcloud services enable compute.googleapis.com

 **Console：**

-1. 前往 IAM & Admin > Create Project
+1. 转到 IAM & Admin > Create Project
 2. 命名并创建
 3. 为项目启用计费
-4. 导航至 APIs & Services > Enable APIs > 搜索 "Compute Engine API" > 启用
+4. 导航到 APIs & Services > Enable APIs > 搜索 "Compute Engine API" > Enable

 ---

-## 3）创建虚拟机
+## 3) 创建 VM

 **机器类型：**

-| 类型     | 规格                     | 费用           | 备注             |
-| -------- | ------------------------ | -------------- | ---------------- |
-| e2-small | 2 vCPU，2GB 内存         | 约 $12/月      | 推荐             |
-| e2-micro | 2 vCPU（共享），1GB 内存 | 可享受免费层级 | 高负载下可能 OOM |
+| 类型     | 配置                    | 成本       | 说明           |
+| -------- | ----------------------- | ---------- | -------------- |
+| e2-small | 2 vCPU，2GB RAM         | ~$12/月    | 推荐           |
+| e2-micro | 2 vCPU（共享），1GB RAM | 符合免费层 | 负载下可能 OOM |

 **CLI：**

@@ -139,16 +139,16 @@ gcloud compute instances create openclaw-gateway \

 **Console：**

-1. 前往 Compute Engine > VM instances > Create instance
-2. 名称：`openclaw-gateway`
-3. 区域：`us-central1`，可用区：`us-central1-a`
-4. 机器类型：`e2-small`
-5. 启动磁盘：Debian 12，20GB
-6. 创建
+1. 转到 Compute Engine > VM instances > Create instance
+2. Name：`openclaw-gateway`
+3. Region：`us-central1`，Zone：`us-central1-a`
+4. Machine type：`e2-small`
+5. Boot disk：Debian 12，20GB
+6. Create

 ---

-## 4）SSH 连接到虚拟机
+## 4) SSH 进入 VM

 **CLI：**

@@ -158,13 +158,13 @@ gcloud compute ssh openclaw-gateway --zone=us-central1-a

 **Console：**

-在 Compute Engine 控制面板中点击虚拟机旁边的 "SSH" 按钮。
+在 Compute Engine 仪表板中点击 VM 旁边的"SSH"按钮。

-注意：虚拟机创建后，SSH 密钥传播可能需要 1-2 分钟。如果连接被拒绝，请等待后重试。
+注意：VM 创建后 SSH 密钥传播可能需要 1-2 分钟。如果连接被拒绝，请等待并重试。

 ---

-## 5）安装 Docker（在虚拟机上）
+## 5) 安装 Docker（在 VM 上）

 ```bash
 sudo apt-get update
@@ -173,13 +173,13 @@ curl -fsSL https://get.docker.com | sudo sh
 sudo usermod -aG docker $USER
 ```

-注销并重新登录以使用户组变更生效：
+注销并重新登录以使组更改生效：

 ```bash
 exit
 ```

-然后重新 SSH 连接：
+然后重新 SSH 登录：

 ```bash
 gcloud compute ssh openclaw-gateway --zone=us-central1-a
@@ -194,21 +194,21 @@ docker compose version

 ---

-## 6）克隆 OpenClaw 仓库
+## 6) 克隆 OpenClaw 仓库

 ```bash
 git clone https://github.com/openclaw/openclaw.git
 cd openclaw
 ```

-本指南假设你将构建自定义镜像以确保二进制文件的持久化。
+本指南假设你将构建自定义镜像以保证二进制文件持久化。

 ---

-## 7）创建持久化宿主机目录
+## 7) 创建持久化主机目录

-Docker 容器是临时性的。
-所有长期状态必须存储在宿主机上。
+Docker 容器是临时的。
+所有长期状态必须存在于主机上。

 ```bash
 mkdir -p ~/.openclaw
@@ -217,7 +217,7 @@ mkdir -p ~/.openclaw/workspace

 ---

-## 8）配置环境变量
+## 8) 配置环境变量

 在仓库根目录创建 `.env`。

@@ -240,11 +240,11 @@ XDG_CONFIG_HOME=/home/node/.openclaw
 openssl rand -hex 32
 ```

-**请勿提交此文件。**
+**不要提交此文件。**

 ---

-## 9）Docker Compose 配置
+## 9) Docker Compose 配置

 创建或更新 `docker-compose.yml`。

@@ -270,12 +270,12 @@ services:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
-      # 推荐：在虚拟机上保持 Gateway网关仅监听 local loopback；通过 SSH 隧道访问。
-      # 如需公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
+      # 推荐：在 VM 上保持 Gateway 网关仅绑定 loopback；通过 SSH 隧道访问。
+      # 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

-      # 可选：仅当你对此虚拟机运行 iOS/Android 节点并需要 Canvas 主机时使用。
-      # 如果公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
+      # 可选：仅当你针对此 VM 运行 iOS/Android 节点并需要 Canvas 主机时。
+      # 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
      # - "18793:18793"
    command:
      [
@@ -291,26 +291,26 @@ services:

 ---

-## 10）将所需二进制文件内置到镜像中（关键步骤）
+## 10) 将所需二进制文件内置到镜像中（关键）

 在运行中的容器内安装二进制文件是一个陷阱。
-运行时安装的任何内容在重启后都会丢失。
+任何在运行时安装的内容在重启后都会丢失。

 所有 Skills 所需的外部二进制文件必须在镜像构建时安装。

-以下示例仅展示三个常见的二进制文件：
+以下示例仅显示三个常见的二进制文件：

 - `gog` 用于 Gmail 访问
 - `goplaces` 用于 Google Places
 - `wacli` 用于 WhatsApp

-这些只是示例，并非完整列表。
-你可以使用相同的模式安装所需的任意数量的二进制文件。
+这些是示例，不是完整列表。
+你可以使用相同的模式安装任意数量的二进制文件。

-如果之后添加了依赖其他二进制文件的新 Skills，你必须：
+如果你以后添加依赖额外二进制文件的新 Skills，你必须：

 1. 更新 Dockerfile
-2. 重新构建镜像
+2. 重建镜像
 3. 重启容器

 **示例 Dockerfile**
@@ -332,7 +332,7 @@ RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplac
 RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

-# 使用相同模式在下方添加更多二进制文件
+# 使用相同的模式在下面添加更多二进制文件

 WORKDIR /app
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
@@ -354,7 +354,7 @@ CMD ["node","dist/index.js"]

 ---

-## 11）构建并启动
+## 11) 构建并启动

 ```bash
 docker compose build
@@ -379,13 +379,13 @@ docker compose exec openclaw-gateway which wacli

 ---

-## 12）验证 Gateway网关
+## 12) 验证 Gateway 网关

 ```bash
 docker compose logs -f openclaw-gateway
 ```

-成功标志：
+成功：

 ```
 [gateway] listening on ws://0.0.0.0:18789
@@ -393,9 +393,9 @@ docker compose logs -f openclaw-gateway

 ---

-## 13）从笔记本电脑访问
+## 13) 从你的笔记本电脑访问

-创建 SSH 隧道以转发 Gateway网关端口：
+创建 SSH 隧道以转发 Gateway 网关端口：

 ```bash
 gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
@@ -405,33 +405,33 @@ gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:1

 `http://127.0.0.1:18789/`

-粘贴你的 Gateway网关令牌。
+粘贴你的 Gateway 网关令牌。

 ---

-## 持久化存储位置（数据来源）
+## 什么持久化在哪里（真实来源）

-OpenClaw 在 Docker 中运行，但 Docker 并非数据来源。
-所有长期状态必须在重启、重建和重启动后仍然存在。
+OpenClaw 在 Docker 中运行，但 Docker 不是真实来源。
+所有长期状态必须在重启、重建和重启后仍然存在。

-| 组件            | 位置                              | 持久化机制      | 备注                        |
-| --------------- | --------------------------------- | --------------- | --------------------------- |
-| Gateway网关配置 | `/home/node/.openclaw/`           | 宿主机卷挂载    | 包含 `openclaw.json`、令牌  |
-| 模型认证配置    | `/home/node/.openclaw/`           | 宿主机卷挂载    | OAuth 令牌、API 密钥        |
-| Skills配置      | `/home/node/.openclaw/skills/`    | 宿主机卷挂载    | Skills 级别状态             |
-| 智能体工作区    | `/home/node/.openclaw/workspace/` | 宿主机卷挂载    | 代码和智能体产物            |
-| WhatsApp 会话   | `/home/node/.openclaw/`           | 宿主机卷挂载    | 保留二维码登录              |
-| Gmail 密钥环    | `/home/node/.openclaw/`           | 宿主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
-| 外部二进制文件  | `/usr/local/bin/`                 | Docker 镜像     | 必须在构建时内置            |
-| Node 运行时     | 容器文件系统                      | Docker 镜像     | 每次镜像构建时重建          |
-| 操作系统软件包  | 容器文件系统                      | Docker 镜像     | 请勿在运行时安装            |
-| Docker 容器     | 临时性                            | 可重启          | 可安全销毁                  |
+| 组件             | 位置                              | 持久化机制    | 说明                        |
+| ---------------- | --------------------------------- | ------------- | --------------------------- |
+| Gateway 网关配置 | `/home/node/.openclaw/`           | 主机卷挂载    | 包括 `openclaw.json`、令牌  |
+| 模型认证配置文件 | `/home/node/.openclaw/`           | 主机卷挂载    | OAuth 令牌、API 密钥        |
+| Skill 配置       | `/home/node/.openclaw/skills/`    | 主机卷挂载    | Skill 级别状态              |
+| 智能体工作区     | `/home/node/.openclaw/workspace/` | 主机卷挂载    | 代码和智能体产物            |
+| WhatsApp 会话    | `/home/node/.openclaw/`           | 主机卷挂载    | 保留 QR 登录                |
+| Gmail 密钥环     | `/home/node/.openclaw/`           | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
+| 外部二进制文件   | `/usr/local/bin/`                 | Docker 镜像   | 必须在构建时内置            |
+| Node 运行时      | 容器文件系统                      | Docker 镜像   | 每次镜像构建时重建          |
+| OS 包            | 容器文件系统                      | Docker 镜像   | 不要在运行时安装            |
+| Docker 容器      | 临时                              | 可重启        | 可以安全销毁                |

 ---

 ## 更新

-在虚拟机上更新 OpenClaw：
+在 VM 上更新 OpenClaw：

 ```bash
 cd ~/openclaw
@@ -446,11 +446,11 @@ docker compose up -d

 **SSH 连接被拒绝**

-虚拟机创建后，SSH 密钥传播可能需要 1-2 分钟。请等待后重试。
+VM 创建后 SSH 密钥传播可能需要 1-2 分钟。等待并重试。

 **OS Login 问题**

-检查你的 OS Login 配置：
+检查你的 OS Login 配置文件：

 ```bash
 gcloud compute os-login describe-profile
@@ -458,12 +458,12 @@ gcloud compute os-login describe-profile

 确保你的账户具有所需的 IAM 权限（Compute OS Login 或 Compute OS Admin Login）。

-**内存不足 (OOM)**
+**内存不足（OOM）**

-如果使用 e2-micro 并遇到 OOM，请升级到 e2-small 或 e2-medium：
+如果使用 e2-micro 并遇到 OOM，升级到 e2-small 或 e2-medium：

 ```bash
-# 先停止虚拟机
+# 首先停止 VM
 gcloud compute instances stop openclaw-gateway --zone=us-central1-a

 # 更改机器类型
@@ -471,7 +471,7 @@ gcloud compute instances set-machine-type openclaw-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small

-# 启动虚拟机
+# 启动 VM
 gcloud compute instances start openclaw-gateway --zone=us-central1-a
 ```

@@ -479,9 +479,9 @@ gcloud compute instances start openclaw-gateway --zone=us-central1-a

 ## 服务账户（安全最佳实践）

-个人使用时，默认用户账户即可。
+对于个人使用，你的默认用户账户就可以。

-对于自动化或 CI/CD 流水线，请创建具有最小权限的专用服务账户：
+对于自动化或 CI/CD 管道，创建具有最小权限的专用服务账户：

 1. 创建服务账户：

@@ -490,21 +490,21 @@ gcloud compute instances start openclaw-gateway --zone=us-central1-a
     --display-name="OpenClaw Deployment"
   ```

-2. 授予 Compute Instance Admin 角色（或更精细的自定义角色）：
+2. 授予 Compute Instance Admin 角色（或更窄的自定义角色）：
   ```bash
   gcloud projects add-iam-policy-binding my-openclaw-project \
     --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
     --role="roles/compute.instanceAdmin.v1"
   ```

-避免在自动化中使用 Owner 角色。请遵循最小权限原则。
+避免为自动化使用 Owner 角色。使用最小权限原则。

-有关 IAM 角色详情，请参阅 https://cloud.google.com/iam/docs/understanding-roles。
+参阅 https://cloud.google.com/iam/docs/understanding-roles 了解 IAM 角色详情。

 ---

-## 后续步骤
+## 下一步

 - 设置消息渠道：[渠道](/channels)
 - 将本地设备配对为节点：[节点](/nodes)
- 配置 Gateway网关：[Gateway网关配置](/gateway/configuration)
+- 配置 Gateway 网关：[Gateway 网关配置](/gateway/configuration)
@@ -1,13 +1,13 @@
 ---
 read_when:
-  - 你希望 OpenClaw 在云端 VPS（而非笔记本电脑）上全天候运行
-  - 你需要在自己的 VPS 上部署一个生产级、始终在线的 Gateway网关
-  - 你希望完全掌控持久化、二进制文件和重启行为
-  - 你正在 Hetzner 或类似提供商上通过 Docker 运行 OpenClaw
-summary: 在廉价的 Hetzner VPS 上通过 Docker 全天候运行 OpenClaw Gateway网关，支持持久化状态和内置二进制文件
+  - 你想让 OpenClaw 在云 VPS 上 24/7 运行（而不是你的笔记本电脑）
+  - 你想在自己的 VPS 上运行生产级、永久在线的 Gateway 网关
+  - 你想完全控制持久化、二进制文件和重启行为
+  - 你在 Hetzner 或类似提供商上用 Docker 运行 OpenClaw
+summary: 在廉价的 Hetzner VPS（Docker）上 24/7 运行 OpenClaw Gateway 网关，带持久状态和内置二进制文件
 title: Hetzner
 x-i18n:
-  generated_at: "2026-02-01T21:32:45Z"
+  generated_at: "2026-02-03T07:52:17Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 84d9f24f1a803aa15faa52a05f25fe557ec3e2c2f48a00c701d49764bd3bc21a
@@ -15,65 +15,65 @@ x-i18n:
  workflow: 15
 ---

-# 在 Hetzner 上部署 OpenClaw（Docker 生产环境 VPS 指南）
+# 在 Hetzner 上运行 OpenClaw（Docker，生产 VPS 指南）

 ## 目标

-使用 Docker 在 Hetzner VPS 上运行持久化的 OpenClaw Gateway网关，支持持久化状态、内置二进制文件和安全的重启行为。
+使用 Docker 在 Hetzner VPS 上运行持久的 OpenClaw Gateway 网关，带持久状态、内置二进制文件和安全的重启行为。

-如果你想要"每月约 $5 实现 OpenClaw 全天候运行"，这是最简单可靠的方案。
-Hetzner 定价会变动；选择最小的 Debian/Ubuntu VPS，如果遇到内存不足（OOM）再扩容。
+如果你想要"约 $5 实现 OpenClaw 24/7"，这是最简单可靠的设置。
+Hetzner 定价会变化；选择最小的 Debian/Ubuntu VPS，如果遇到 OOM 再扩容。

-## 我们要做什么（简单说明）？
+## 我们在做什么（简单说明）？

- 租一台小型 Linux 服务器（Hetzner VPS）
+- 租用一台小型 Linux 服务器（Hetzner VPS）
 - 安装 Docker（隔离的应用运行时）
- 在 Docker 中启动 OpenClaw Gateway网关
- 将 `~/.openclaw` + `~/.openclaw/workspace` 持久化到宿主机（重启/重建后数据不丢失）
- 通过 SSH 隧道从笔记本电脑访问控制界面
+- 在 Docker 中启动 OpenClaw Gateway 网关
+- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（重启/重建后保留）
+- 通过 SSH 隧道从你的笔记本电脑访问控制 UI

-Gateway网关可通过以下方式访问：
+Gateway 网关可以通过以下方式访问：

- 从笔记本电脑进行 SSH 端口转发
- 如果你自行管理防火墙和令牌，也可以直接暴露端口
+- 从你的笔记本电脑进行 SSH 端口转发
+- 如果你自己管理防火墙和令牌，可以直接暴露端口

-本指南假设 Hetzner 上使用 Ubuntu 或 Debian。
-如果你使用其他 Linux VPS，请对应调整软件包。
-通用 Docker 流程请参阅 [Docker](/install/docker)。
+本指南假设在 Hetzner 上使用 Ubuntu 或 Debian。
+如果你使用其他 Linux VPS，请相应地映射软件包。
+通用 Docker 流程请参见 [Docker](/install/docker)。

 ---

 ## 快速路径（有经验的运维人员）

-1. 创建 Hetzner VPS
+1. 配置 Hetzner VPS
 2. 安装 Docker
 3. 克隆 OpenClaw 仓库
-4. 创建持久化宿主机目录
+4. 创建持久化主机目录
 5. 配置 `.env` 和 `docker-compose.yml`
-6. 将所需二进制文件内置到镜像中
+6. 将所需二进制文件烘焙到镜像中
 7. `docker compose up -d`
-8. 验证持久化和 Gateway网关访问
+8. 验证持久化和 Gateway 网关访问

 ---

-## 准备工作
+## 你需要什么

- 拥有 root 权限的 Hetzner VPS
- 从笔记本电脑可通过 SSH 访问
- 基本熟悉 SSH + 复制/粘贴操作
- 约 20 分钟时间
+- 具有 root 访问权限的 Hetzner VPS
+- 从你的笔记本电脑进行 SSH 访问
+- 基本熟悉 SSH + 复制/粘贴
+- 约 20 分钟
 - Docker 和 Docker Compose
- 模型认证凭据
- 可选的提供商凭据
+- 模型认证凭证
+- 可选的提供商凭证
  - WhatsApp 二维码
  - Telegram 机器人令牌
  - Gmail OAuth

 ---

-## 1) 创建 VPS
+## 1) 配置 VPS

-在 Hetzner 创建一台 Ubuntu 或 Debian VPS。
+在 Hetzner 中创建一个 Ubuntu 或 Debian VPS。

 以 root 身份连接：

@@ -110,14 +110,14 @@ git clone https://github.com/openclaw/openclaw.git
 cd openclaw
 ```

-本指南假设你将构建自定义镜像以确保二进制文件的持久化。
+本指南假设你将构建自定义镜像以保证二进制文件持久化。

 ---

-## 4) 创建持久化宿主机目录
+## 4) 创建持久化主机目录

-Docker 容器是临时性的。
-所有长期状态必须存放在宿主机上。
+Docker 容器是临时的。
+所有长期状态必须存储在主机上。

 ```bash
 mkdir -p /root/.openclaw
@@ -132,7 +132,7 @@ chown -R 1000:1000 /root/.openclaw/workspace

 ## 5) 配置环境变量

-在仓库根目录创建 `.env` 文件。
+在仓库根目录创建 `.env`。

 ```bash
 OPENCLAW_IMAGE=openclaw:latest
@@ -153,7 +153,7 @@ XDG_CONFIG_HOME=/home/node/.openclaw
 openssl rand -hex 32
 ```

-**请勿将此文件提交到版本控制。**
+**不要提交此文件。**

 ---

@@ -183,12 +183,12 @@ services:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
-      # 推荐：在 VPS 上仅绑定 local loopback；通过 SSH 隧道访问。
-      # 如需公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
+      # 推荐：在 VPS 上保持 Gateway 网关仅限 loopback；通过 SSH 隧道访问。
+      # 要公开暴露，移除 `127.0.0.1:` 前缀并相应配置防火墙。
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

-      # 可选：仅在你需要将 iOS/Android 节点连接到此 VPS 且需要 Canvas 主机时使用。
-      # 如果公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
+      # 可选：仅当你对此 VPS 运行 iOS/Android 节点并需要 Canvas 主机时。
+      # 如果你公开暴露此端口，请阅读 /gateway/security 并相应配置防火墙。
      # - "18793:18793"
    command:
      [
@@ -204,23 +204,23 @@ services:

 ---

-## 7) 将所需二进制文件内置到镜像中（关键步骤）
+## 7) 将所需二进制文件烘焙到镜像中（关键）

 在运行中的容器内安装二进制文件是一个陷阱。
-任何在运行时安装的内容都会在重启后丢失。
+任何在运行时安装的东西都会在重启时丢失。

-Skills 所需的所有外部二进制文件必须在镜像构建时安装。
+所有 skills 所需的外部二进制文件必须在镜像构建时安装。

-以下示例仅展示三个常见的二进制文件：
+以下示例仅展示三个常见二进制文件：

 - `gog` 用于 Gmail 访问
 - `goplaces` 用于 Google Places
 - `wacli` 用于 WhatsApp

-这些只是示例，并非完整列表。
+这些是示例，不是完整列表。
 你可以使用相同的模式安装任意数量的二进制文件。

-如果你后续添加了依赖额外二进制文件的新 Skills，你必须：
+如果你以后添加依赖额外二进制文件的新 skills，你必须：

 1. 更新 Dockerfile
 2. 重新构建镜像
@@ -245,7 +245,7 @@ RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplac
 RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

-# 在下方使用相同模式添加更多二进制文件
+# 使用相同模式在下方添加更多二进制文件

 WORKDIR /app
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
@@ -292,19 +292,19 @@ docker compose exec openclaw-gateway which wacli

 ---

-## 9) 验证 Gateway网关
+## 9) 验证 Gateway 网关

 ```bash
 docker compose logs -f openclaw-gateway
 ```

-成功标志：
+成功：

 ```
 [gateway] listening on ws://0.0.0.0:18789
 ```

-从笔记本电脑执行：
+从你的笔记本电脑：

 ```bash
 ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
@@ -314,24 +314,24 @@ ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

 `http://127.0.0.1:18789/`

-粘贴你的 Gateway网关令牌。
+粘贴你的 Gateway 网关令牌。

 ---

-## 持久化位置说明（数据源）
+## 持久化位置（事实来源）

-OpenClaw 在 Docker 中运行，但 Docker 不是数据源。
-所有长期状态必须能在重启、重建和重启后保留。
+OpenClaw 在 Docker 中运行，但 Docker 不是事实来源。
+所有长期状态必须在重启、重建和重启后保留。

-| 组件            | 位置                              | 持久化机制      | 备注                        |
-| --------------- | --------------------------------- | --------------- | --------------------------- |
-| Gateway网关配置 | `/home/node/.openclaw/`           | 宿主机卷挂载    | 包含 `openclaw.json`、令牌  |
-| 模型认证配置    | `/home/node/.openclaw/`           | 宿主机卷挂载    | OAuth 令牌、API 密钥        |
-| Skills配置      | `/home/node/.openclaw/skills/`    | 宿主机卷挂载    | Skills 级别状态             |
-| 智能体工作区    | `/home/node/.openclaw/workspace/` | 宿主机卷挂载    | 代码和智能体产物            |
-| WhatsApp 会话   | `/home/node/.openclaw/`           | 宿主机卷挂载    | 保留二维码登录状态          |
-| Gmail 密钥环    | `/home/node/.openclaw/`           | 宿主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
-| 外部二进制文件  | `/usr/local/bin/`                 | Docker 镜像     | 必须在构建时内置            |
-| Node 运行时     | 容器文件系统                      | Docker 镜像     | 每次构建镜像时重建          |
-| 操作系统软件包  | 容器文件系统                      | Docker 镜像     | 不要在运行时安装            |
-| Docker 容器     | 临时性                            | 可重启          | 可安全销毁                  |
+| 组件             | 位置                              | 持久化机制    | 说明                        |
+| ---------------- | --------------------------------- | ------------- | --------------------------- |
+| Gateway 网关配置 | `/home/node/.openclaw/`           | 主机卷挂载    | 包括 `openclaw.json`、令牌  |
+| 模型认证配置文件 | `/home/node/.openclaw/`           | 主机卷挂载    | OAuth 令牌、API 密钥        |
+| Skill 配置       | `/home/node/.openclaw/skills/`    | 主机卷挂载    | Skill 级别状态              |
+| 智能体工作区     | `/home/node/.openclaw/workspace/` | 主机卷挂载    | 代码和智能体产物            |
+| WhatsApp 会话    | `/home/node/.openclaw/`           | 主机卷挂载    | 保留二维码登录              |
+| Gmail 密钥环     | `/home/node/.openclaw/`           | 主机卷 + 密码 | 需要 `GOG_KEYRING_PASSWORD` |
+| 外部二进制文件   | `/usr/local/bin/`                 | Docker 镜像   | 必须在构建时烘焙            |
+| Node 运行时      | 容器文件系统                      | Docker 镜像   | 每次镜像构建时重建          |
+| 操作系统包       | 容器文件系统                      | Docker 镜像   | 不要在运行时安装            |
+| Docker 容器      | 临时的                            | 可重启        | 可以安全销毁                |
@@ -1,11 +1,11 @@
 ---
 read_when:
-  - 查找操作系统支持或安装路径
-  - 决定在哪里运行 Gateway网关
-summary: 平台支持概览（Gateway网关 + 配套应用）
+  - 查找操作系统支持或安装路径时
+  - 决定在哪里运行 Gateway 网关时
+summary: 平台支持概述（Gateway 网关 + 配套应用）
 title: 平台
 x-i18n:
-  generated_at: "2026-02-01T21:32:17Z"
+  generated_at: "2026-02-03T07:52:07Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 254852a5ed1996982a52eed4a72659477609e08d340c625d24ef6d99c21eece6
@@ -15,12 +15,12 @@ x-i18n:

 # 平台

-OpenClaw 核心使用 TypeScript 编写。**推荐使用 Node 作为运行时**。
-不建议在 Gateway网关上使用 Bun（存在 WhatsApp/Telegram 相关的 bug）。
+OpenClaw 核心使用 TypeScript 编写。**Node 是推荐的运行时**。
+不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。

-配套应用支持 macOS（菜单栏应用）和移动节点（iOS/Android）。Windows 和
-Linux 的配套应用已在规划中，但 Gateway网关目前已完全支持。
-Windows 的原生配套应用同样在规划中；推荐通过 WSL2 使用 Gateway网关。
+配套应用适用于 macOS（菜单栏应用）和移动节点（iOS/Android）。Windows 和
+Linux 配套应用已在计划中，但 Gateway 网关目前已完全支持。
+Windows 原生配套应用也在计划中；推荐通过 WSL2 使用 Gateway 网关。

 ## 选择你的操作系统

@@ -30,29 +30,29 @@ Windows 的原生配套应用同样在规划中；推荐通过 WSL2 使用 Gatew
 - Windows：[Windows](/platforms/windows)
 - Linux：[Linux](/platforms/linux)

-## VPS 与托管
+## VPS 和托管

 - VPS 中心：[VPS 托管](/vps)
 - Fly.io：[Fly.io](/platforms/fly)
- Hetzner (Docker)：[Hetzner](/platforms/hetzner)
- GCP (Compute Engine)：[GCP](/platforms/gcp)
- exe.dev (VM + HTTPS 代理)：[exe.dev](/platforms/exe-dev)
+- Hetzner（Docker）：[Hetzner](/platforms/hetzner)
+- GCP（Compute Engine）：[GCP](/platforms/gcp)
+- exe.dev（VM + HTTPS 代理）：[exe.dev](/platforms/exe-dev)

 ## 常用链接

- 安装指南：[快速开始](/start/getting-started)
- Gateway网关运维手册：[Gateway网关](/gateway)
- Gateway网关配置：[配置](/gateway/configuration)
+- 安装指南：[入门指南](/start/getting-started)
+- Gateway 网关运行手册：[Gateway 网关](/gateway)
+- Gateway 网关配置：[配置](/gateway/configuration)
 - 服务状态：`openclaw gateway status`

-## Gateway网关服务安装（CLI）
+## Gateway 网关服务安装（CLI）

-使用以下任一方式（均受支持）：
+使用以下任一方式（均支持）：

 - 向导（推荐）：`openclaw onboard --install-daemon`
 - 直接安装：`openclaw gateway install`
- 配置流程：`openclaw configure` → 选择 **Gateway网关 service**
- 修复/迁移：`openclaw doctor`（会提示安装或修复服务）
+- 配置流程：`openclaw configure` → 选择 **Gateway service**
+- 修复/迁移：`openclaw doctor`（提供安装或修复服务）

 服务目标取决于操作系统：

@@ -2,11 +2,11 @@
 read_when:
  - 配对或重新连接 iOS 节点
  - 从源码运行 iOS 应用
-  - 调试 Gateway网关发现或画布命令
-summary: iOS 节点应用：连接 Gateway网关、配对、画布及故障排除
+  - 调试 Gateway 网关发现或 canvas 命令
+summary: iOS 节点应用：连接到 Gateway 网关、配对、canvas 和故障排除
 title: iOS 应用
 x-i18n:
-  generated_at: "2026-02-01T21:32:23Z"
+  generated_at: "2026-02-03T07:52:17Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 692eebdc82e4bb8dc221bcbabf6a344a861a839fc377f1aeeb6eecaa4917a232
@@ -18,31 +18,31 @@ x-i18n:

 可用性：内部预览。iOS 应用尚未公开分发。

-## 功能说明
+## 功能

- 通过 WebSocket 连接到 Gateway网关（局域网或 tailnet）。
- 暴露节点能力：画布、屏幕快照、摄像头捕获、位置、对话模式、语音唤醒。
- 接收 `node.invoke` 命令并上报节点状态事件。
+- 通过 WebSocket（LAN 或 tailnet）连接到 Gateway 网关。
+- 暴露节点能力：Canvas、屏幕快照、相机捕获、位置、对话模式、语音唤醒。
+- 接收 `node.invoke` 命令并报告节点状态事件。

 ## 要求

- Gateway网关运行在另一台设备上（macOS、Linux 或通过 WSL2 的 Windows）。
+- Gateway 网关运行在另一台设备上（macOS、Linux 或通过 WSL2 的 Windows）。
 - 网络路径：
-  - 通过 Bonjour 的同一局域网，**或**
-  - 通过单播 DNS-SD 的 Tailnet（示例域名：`openclaw.internal.`），**或**
-  - 手动输入主机/端口（备用方案）。
+  - 通过 Bonjour 的同一 LAN，**或**
+  - 通过单播 DNS-SD 的 Tailnet（示例域：`openclaw.internal.`），**或**
+  - 手动主机/端口（备选）。

 ## 快速开始（配对 + 连接）

-1. 启动 Gateway网关：
+1. 启动 Gateway 网关：

 ```bash
 openclaw gateway --port 18789
 ```

-2. 在 iOS 应用中，打开设置并选择已发现的 Gateway网关（或启用手动主机并输入主机/端口）。
+2. 在 iOS 应用中，打开设置并选择一个已发现的 Gateway 网关（或启用手动主机并输入主机/端口）。

-3. 在 Gateway网关主机上批准配对请求：
+3. 在 Gateway 网关主机上批准配对请求：

 ```bash
 openclaw nodes pending
@@ -58,22 +58,22 @@ openclaw gateway call node.list --params "{}"

 ## 发现路径

-### Bonjour（局域网）
+### Bonjour（LAN）

-Gateway网关在 `local.` 上广播 `_openclaw-gw._tcp`。iOS 应用会自动列出这些服务。
+Gateway 网关在 `local.` 上广播 `_openclaw-gw._tcp`。iOS 应用会自动列出这些。

 ### Tailnet（跨网络）

-如果 mDNS 被阻止，请使用单播 DNS-SD 区域（选择一个域名；示例：`openclaw.internal.`）和 Tailscale 分割 DNS。
-参阅 [Bonjour](/gateway/bonjour) 了解 CoreDNS 配置示例。
+如果 mDNS 被阻止，使用单播 DNS-SD 区域（选择一个域；示例：`openclaw.internal.`）和 Tailscale 分割 DNS。
+参见 [Bonjour](/gateway/bonjour) 了解 CoreDNS 示例。

 ### 手动主机/端口

-在设置中，启用**手动主机**并输入 Gateway网关主机 + 端口（默认 `18789`）。
+在设置中，启用**手动主机**并输入 Gateway 网关主机 + 端口（默认 `18789`）。

-## 画布 + A2UI
+## Canvas + A2UI

-iOS 节点渲染一个 WKWebView 画布。使用 `node.invoke` 来驱动它：
+iOS 节点渲染一个 WKWebView canvas。使用 `node.invoke` 来驱动它：

 ```bash
 openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18793/__openclaw__/canvas/"}'
@@ -81,11 +81,11 @@ openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"ur

 注意事项：

- Gateway网关画布主机提供 `/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/` 服务。
- iOS 节点在连接时如果画布主机 URL 已广播，会自动导航到 A2UI。
- 使用 `canvas.navigate` 和 `{"url":""}` 返回内置脚手架页面。
+- Gateway 网关 canvas 主机服务于 `/__openclaw__/canvas/` 和 `/__openclaw__/a2ui/`。
+- 当广播了 canvas 主机 URL 时，iOS 节点在连接时自动导航到 A2UI。
+- 使用 `canvas.navigate` 和 `{"url":""}` 返回内置脚手架。

-### 画布执行 / 快照
+### Canvas eval / snapshot

 ```bash
 openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
@@ -97,18 +97,18 @@ openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"ma

 ## 语音唤醒 + 对话模式

- 语音唤醒和对话模式可在设置中配置。
- iOS 可能会挂起后台音频；当应用不在前台时，请将语音功能视为尽力而为。
+- 语音唤醒和对话模式在设置中可用。
+- iOS 可能会暂停后台音频；当应用不活跃时，将语音功能视为尽力而为。

 ## 常见错误

- `NODE_BACKGROUND_UNAVAILABLE`：将 iOS 应用切换到前台（画布/摄像头/屏幕命令需要前台运行）。
- `A2UI_HOST_NOT_CONFIGURED`：Gateway网关未广播画布主机 URL；请检查 [Gateway网关配置](/gateway/configuration) 中的 `canvasHost`。
- 配对提示始终未出现：运行 `openclaw nodes pending` 并手动批准。
- 重新安装后重连失败：钥匙串中的配对令牌已被清除；请重新配对节点。
+- `NODE_BACKGROUND_UNAVAILABLE`：将 iOS 应用带到前台（canvas/相机/屏幕命令需要它）。
+- `A2UI_HOST_NOT_CONFIGURED`：Gateway 网关未广播 canvas 主机 URL；检查 [Gateway 网关配置](/gateway/configuration) 中的 `canvasHost`。
+- 配对提示从未出现：运行 `openclaw nodes pending` 并手动批准。
+- 重新安装后重连失败：钥匙串配对令牌已被清除；重新配对节点。

 ## 相关文档

 - [配对](/gateway/pairing)
- [发现](/gateway/discovery)
+- [设备发现](/gateway/discovery)
 - [Bonjour](/gateway/bonjour)
@@ -1,11 +1,11 @@
 ---
 read_when:
-  - 查找 Linux 伴侣应用状态
-  - 规划平台覆盖范围或贡献
-summary: Linux 支持 + 伴侣应用状态
+  - 查找 Linux 配套应用状态时
+  - 规划平台覆盖或贡献时
+summary: Linux 支持 + 配套应用状态
 title: Linux 应用
 x-i18n:
-  generated_at: "2026-02-01T21:32:18Z"
+  generated_at: "2026-02-03T07:52:18Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: a9bbbcecf2fd522a2f5ac8f3b9068febbc43658465bfb9276bff6c3e946789d2
@@ -15,10 +15,10 @@ x-i18n:

 # Linux 应用

-Gateway网关在 Linux 上完全受支持。**推荐使用 Node 作为运行时**。
-不建议将 Bun 用于 Gateway网关（WhatsApp/Telegram 存在 bug）。
+Gateway 网关在 Linux 上完全支持。**Node 是推荐的运行时**。
+不推荐 Bun 用于 Gateway 网关（WhatsApp/Telegram 存在 bug）。

-原生 Linux 伴侣应用已在计划中。如果你想帮助构建，欢迎贡献。
+原生 Linux 配套应用已在计划中。如果你想帮助构建，欢迎贡献。

 ## 新手快速路径（VPS）

@@ -32,16 +32,16 @@ Gateway网关在 Linux 上完全受支持。**推荐使用 Node 作为运行时*

 ## 安装

- [快速开始](/start/getting-started)
+- [入门指南](/start/getting-started)
 - [安装与更新](/install/updating)
 - 可选流程：[Bun（实验性）](/install/bun)、[Nix](/install/nix)、[Docker](/install/docker)

-## Gateway网关
+## Gateway 网关

- [Gateway网关运维手册](/gateway)
+- [Gateway 网关运行手册](/gateway)
 - [配置](/gateway/configuration)

-## Gateway网关服务安装（CLI）
+## Gateway 网关服务安装（CLI）

 使用以下任一方式：

@@ -61,7 +61,7 @@ openclaw gateway install
 openclaw configure
 ```

-出现提示时选择 **Gateway网关服务**。
+出现提示时选择 **Gateway service**。

 修复/迁移：

@@ -71,15 +71,17 @@ openclaw doctor

 ## 系统控制（systemd 用户单元）

-OpenClaw 默认安装 systemd **用户**服务。对于共享或常驻服务器，请使用**系统**服务。完整的单元示例和指南请参阅 [Gateway网关运维手册](/gateway)。
+OpenClaw 默认安装 systemd **用户**服务。对于共享或常驻服务器使用**系统**
+服务。完整的单元示例和指南
+在 [Gateway 网关运行手册](/gateway) 中。

-最小化设置：
+最小设置：

 创建 `~/.config/systemd/user/openclaw-gateway[-<profile>].service`：

 ```
 [Unit]
-Description=OpenClaw Gateway网关 (profile: <profile>, v<version>)
+Description=OpenClaw Gateway (profile: <profile>, v<version>)
 After=network-online.target
 Wants=network-online.target

@@ -92,7 +94,7 @@ RestartSec=5
 WantedBy=default.target
 ```

-启用服务：
+启用它：

 ```
 systemctl --user enable --now openclaw-gateway[-<profile>].service
@@ -1,12 +1,12 @@
 ---
 read_when:
  - 打包 OpenClaw.app
-  - 调试 macOS gateway launchd 服务
-  - 为 macOS 安装 gateway CLI
-summary: macOS 上的 Gateway网关运行时（外部 launchd 服务）
-title: macOS 上的 Gateway网关
+  - 调试 macOS Gateway 网关 launchd 服务
+  - 为 macOS 安装 Gateway 网关 CLI
+summary: macOS 上的 Gateway 网关运行时（外部 launchd 服务）
+title: macOS 上的 Gateway 网关
 x-i18n:
-  generated_at: "2026-02-01T21:32:27Z"
+  generated_at: "2026-02-03T07:52:30Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 4a3e963d13060b123538005439213e786e76127b370a6c834d85a369e4626fe5
@@ -14,51 +14,49 @@ x-i18n:
  workflow: 15
 ---

-# macOS 上的 Gateway网关（外部 launchd）
+# macOS 上的 Gateway 网关（外部 launchd）

-OpenClaw.app 不再捆绑 Node/Bun 或 Gateway网关运行时。macOS 应用
-要求**外部**安装 `openclaw` CLI，不会将 Gateway网关作为子进程启动，而是管理一个
-按用户配置的 launchd 服务来保持 Gateway网关运行（如果本地已有 Gateway网关在运行，则会连接到现有实例）。
+OpenClaw.app 不再捆绑 Node/Bun 或 Gateway 网关运行时。macOS 应用期望有一个**外部**的 `openclaw` CLI 安装，不会将 Gateway 网关作为子进程启动，而是管理一个每用户的 launchd 服务来保持 Gateway 网关运行（或者如果已有本地 Gateway 网关正在运行，则连接到现有的）。

 ## 安装 CLI（本地模式必需）

-Mac 上需要 Node 22+，然后全局安装 `openclaw`：
+你需要在 Mac 上安装 Node 22+，然后全局安装 `openclaw`：

 ```bash
 npm install -g openclaw@<version>
 ```

-macOS 应用的 **Install CLI** 按钮通过 npm/pnpm 执行相同的安装流程（不建议使用 bun 作为 Gateway网关运行时）。
+macOS 应用的**安装 CLI**按钮通过 npm/pnpm 运行相同的流程（不推荐使用 bun 作为 Gateway 网关运行时）。

-## Launchd（Gateway网关作为 LaunchAgent）
+## Launchd（Gateway 网关作为 LaunchAgent）

 标签：

 - `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 可能仍然存在）

-Plist 位置（按用户）：
+Plist 位置（每用户）：

 - `~/Library/LaunchAgents/bot.molt.gateway.plist`
  （或 `~/Library/LaunchAgents/bot.molt.<profile>.plist`）

 管理者：

- macOS 应用在本地模式下负责 LaunchAgent 的安装/更新。
+- macOS 应用在本地模式下拥有 LaunchAgent 的安装/更新权限。
 - CLI 也可以安装它：`openclaw gateway install`。

 行为：

- "OpenClaw Active" 启用/禁用 LaunchAgent。
- 退出应用**不会**停止 Gateway网关（launchd 会保持其运行）。
- 如果配置端口上已有 Gateway网关在运行，应用会连接到该实例，而不是启动新的。
+- "OpenClaw Active"启用/禁用 LaunchAgent。
+- 应用退出**不会**停止 Gateway 网关（launchd 保持其存活）。
+- 如果 Gateway 网关已经在配置的端口上运行，应用会连接到它而不是启动新的。

 日志：

- launchd 标准输出/错误：`/tmp/openclaw/openclaw-gateway.log`
+- launchd stdout/err：`/tmp/openclaw/openclaw-gateway.log`

 ## 版本兼容性

-macOS 应用会将 Gateway网关版本与自身版本进行比对。如果不兼容，请更新全局 CLI 以匹配应用版本。
+macOS 应用会检查 Gateway 网关版本与其自身版本是否匹配。如果不兼容，请更新全局 CLI 以匹配应用版本。

 ## 冒烟测试

@@ -2,11 +2,11 @@
 read_when:
  - 实现 macOS Canvas 面板
  - 为可视化工作区添加智能体控制
-  - 调试 WKWebView canvas 加载问题
-summary: 智能体控制的 Canvas 面板，通过 WKWebView + 自定义 URL scheme 嵌入
+  - 调试 WKWebView canvas 加载
+summary: 通过 WKWebView + 自定义 URL 方案嵌入的智能体控制 Canvas 面板
 title: Canvas
 x-i18n:
-  generated_at: "2026-02-01T21:32:34Z"
+  generated_at: "2026-02-03T07:52:39Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: e39caa21542e839d9f59ad0bf7ecefb379225ed7e8f00cd59131d188f193bec6
@@ -16,15 +16,15 @@ x-i18n:

 # Canvas（macOS 应用）

-macOS 应用使用 `WKWebView` 嵌入了一个智能体控制的 **Canvas 面板**。它是一个轻量级的可视化工作区，用于 HTML/CSS/JS、A2UI 以及小型交互式 UI 界面。
+macOS 应用使用 `WKWebView` 嵌入一个智能体控制的 **Canvas 面板**。它是一个用于 HTML/CSS/JS、A2UI 和小型交互式界面的轻量级可视化工作区。

-## Canvas 的存储位置
+## Canvas 存储位置

-Canvas 状态存储在 Application Support 目录下：
+Canvas 状态存储在 Application Support 下：

 - `~/Library/Application Support/OpenClaw/canvas/<session>/...`

-Canvas 面板通过**自定义 URL scheme** 提供这些文件：
+Canvas 面板通过**自定义 URL 方案**提供这些文件：

 - `openclaw-canvas://<session>/<path>`

@@ -34,20 +34,20 @@ Canvas 面板通过**自定义 URL scheme** 提供这些文件：
 - `openclaw-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
 - `openclaw-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`

-如果根目录下不存在 `index.html`，应用会显示一个**内置脚手架页面**。
+如果根目录下没有 `index.html`，应用会显示一个**内置脚手架页面**。

 ## 面板行为

 - 无边框、可调整大小的面板，锚定在菜单栏（或鼠标光标）附近。
- 按会话记忆大小/位置。
- 本地 canvas 文件变更时自动重新加载。
- 同一时间只显示一个 Canvas 面板（根据需要切换会话）。
+- 记住每个会话的大小/位置。
+- 当本地 canvas 文件更改时自动重新加载。
+- 一次只显示一个 Canvas 面板（根据需要切换会话）。

-可以在设置 → **允许 Canvas** 中禁用 Canvas。禁用后，canvas 节点命令返回 `CANVAS_DISABLED`。
+可以从设置 → **允许 Canvas** 禁用 Canvas。禁用时，canvas 节点命令返回 `CANVAS_DISABLED`。

 ## 智能体 API 接口

-Canvas 通过 **Gateway网关 WebSocket** 暴露，因此智能体可以：
+Canvas 通过 **Gateway 网关 WebSocket** 暴露，因此智能体可以：

 - 显示/隐藏面板
 - 导航到路径或 URL
@@ -66,11 +66,12 @@ openclaw nodes canvas snapshot --node <id>
 注意事项：

 - `canvas.navigate` 接受**本地 canvas 路径**、`http(s)` URL 和 `file://` URL。
- 如果传入 `"/"`，Canvas 会显示本地脚手架或 `index.html`。
+- 如果传递 `"/"`，Canvas 会显示本地脚手架或 `index.html`。

 ## Canvas 中的 A2UI

-A2UI 由 Gateway网关 canvas 主机托管，并在 Canvas 面板内渲染。当 Gateway网关广播 Canvas 主机时，macOS 应用在首次打开时会自动导航到 A2UI 主机页面。
+A2UI 由 Gateway 网关 canvas 主机托管并在 Canvas 面板内渲染。
+当 Gateway 网关广播 Canvas 主机时，macOS 应用在首次打开时自动导航到 A2UI 主机页面。

 默认 A2UI 主机 URL：

@@ -80,14 +81,14 @@ http://<gateway-host>:18793/__openclaw__/a2ui/

 ### A2UI 命令（v0.8）

-Canvas 当前接受 **A2UI v0.8** 服务端→客户端消息：
+Canvas 目前接受 **A2UI v0.8** 服务器→客户端消息：

 - `beginRendering`
 - `surfaceUpdate`
 - `dataModelUpdate`
 - `deleteSurface`

-不支持 `createSurface`（v0.9）。
+`createSurface`（v0.9）不受支持。

 CLI 示例：

@@ -100,7 +101,7 @@ EOFA2
 openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
 ```

-快速冒烟测试：
+快速测试：

 ```bash
 openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
@@ -122,6 +123,6 @@ window.location.href = "openclaw://agent?message=Review%20this%20design";

 ## 安全注意事项

- Canvas scheme 阻止目录遍历；文件必须位于会话根目录下。
- 本地 Canvas 内容使用自定义 scheme（无需 local loopback 服务器）。
- 仅在显式导航时才允许外部 `http(s)` URL。
+- Canvas 方案阻止目录遍历；文件必须位于会话根目录下。
+- 本地 Canvas 内容使用自定义方案（不需要 loopback 服务器）。
+- 仅在显式导航时允许外部 `http(s)` URL。
@@ -1,10 +1,10 @@
 ---
 read_when:
-  - 将 Mac 应用与 Gateway网关生命周期集成
-summary: macOS 上的 Gateway网关生命周期（launchd）
-title: Gateway网关生命周期
+  - 将 mac 应用与 Gateway 网关生命周期集成时
+summary: macOS 上的 Gateway 网关生命周期（launchd）
+title: Gateway 网关生命周期
 x-i18n:
-  generated_at: "2026-02-01T21:32:36Z"
+  generated_at: "2026-02-03T07:52:31Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 9b910f574b723bc194ac663a5168e48d95f55cb468ce34c595d8ca60d3463c6a
@@ -12,17 +12,23 @@ x-i18n:
  workflow: 15
 ---

-# macOS 上的 Gateway网关生命周期
+# macOS 上的 Gateway 网关生命周期

-macOS 应用默认**通过 launchd 管理 Gateway网关**，不会将 Gateway网关作为子进程启动。它首先尝试连接到已在配置端口上运行的 Gateway网关；如果无法连接，则通过外部 `openclaw` CLI（无内嵌运行时）启用 launchd 服务。这为你提供了可靠的登录自启动和崩溃后自动重启。
+macOS 应用**默认通过 launchd 管理 Gateway 网关**，不会将
+Gateway 网关作为子进程生成。它首先尝试连接到配置端口上已运行的
+Gateway 网关；如果无法访问，它会通过外部 `openclaw` CLI（无嵌入式运行时）启用 launchd
+服务。这为你提供了可靠的登录时自动启动和崩溃后重启。

-子进程模式（由应用直接启动 Gateway网关）**目前未使用**。如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway网关。
+子进程模式（由应用直接生成 Gateway 网关）**目前未使用**。
+如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway 网关。

 ## 默认行为（launchd）

- 应用安装一个标签为 `bot.molt.gateway` 的用户级 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；兼容旧版 `com.openclaw.*`）。
- 当启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway网关。
- 日志写入 launchd Gateway网关日志路径（可在调试设置中查看）。
+- 应用安装标记为 `bot.molt.gateway` 的按用户 LaunchAgent
+  （使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；支持旧版 `com.openclaw.*`）。
+- 当启用本地模式时，应用确保 LaunchAgent 已加载，并
+  在需要时启动 Gateway 网关。
+- 日志写入 launchd Gateway 网关日志路径（在调试设置中可见）。

 常用命令：

@@ -31,15 +37,15 @@ launchctl kickstart -k gui/$UID/bot.molt.gateway
 launchctl bootout gui/$UID/bot.molt.gateway
 ```

-运行命名配置文件时，请将标签替换为 `bot.molt.<profile>`。
+运行命名配置文件时，将标签替换为 `bot.molt.<profile>`。

 ## 未签名的开发构建

-`scripts/restart-mac.sh --no-sign` 用于在没有签名密钥时进行快速本地构建。为防止 launchd 指向未签名的中继二进制文件，它会：
+`scripts/restart-mac.sh --no-sign` 用于在没有签名密钥时的快速本地构建。为了防止 launchd 指向未签名的中继二进制文件，它：

 - 写入 `~/.openclaw/disable-launchagent`。

-已签名的 `scripts/restart-mac.sh` 运行会在检测到该标记文件时清除此覆盖。手动重置方法：
+已签名运行的 `scripts/restart-mac.sh` 会在标记存在时清除此覆盖。要手动重置：

 ```bash
 rm ~/.openclaw/disable-launchagent
@@ -47,16 +53,21 @@ rm ~/.openclaw/disable-launchagent

 ## 仅连接模式

-要强制 macOS 应用**永不安装或管理 launchd**，请使用 `--attach-only`（或 `--no-launchd`）启动。这会设置 `~/.openclaw/disable-launchagent`，使应用仅连接到已运行的 Gateway网关。你也可以在调试设置中切换相同的行为。
+要强制 macOS 应用**永不安装或管理 launchd**，请使用
+`--attach-only`（或 `--no-launchd`）启动它。这会设置 `~/.openclaw/disable-launchagent`，
+因此应用只会连接到已运行的 Gateway 网关。你可以在调试设置中切换相同的
+行为。

 ## 远程模式

-远程模式不会启动本地 Gateway网关。应用使用 SSH 隧道连接到远程主机，并通过该隧道进行通信。
+远程模式永远不会启动本地 Gateway 网关。应用使用到
+远程主机的 SSH 隧道并通过该隧道连接。

-## 为何优先选择 launchd
+## 为什么我们更喜欢 launchd

 - 登录时自动启动。
- 内置重启/KeepAlive 语义。
- 可预测的日志和进程监管。
+- 内置的重启/KeepAlive 语义。
+- 可预测的日志和监管。

-如果将来再次需要真正的子进程模式，应将其作为独立的、明确的开发专用模式进行文档记录。
+如果将来再次需要真正的子进程模式，它应该被记录为
+单独的、明确的仅开发模式。
@@ -1,10 +1,10 @@
 ---
 read_when:
  - 设置 macOS 开发环境
-summary: 面向 OpenClaw macOS 应用开发者的设置指南
-title: macOS 开发环境设置
+summary: 为在 OpenClaw macOS 应用上工作的开发者提供的设置指南
+title: macOS 开发设置
 x-i18n:
-  generated_at: "2026-02-01T21:32:41Z"
+  generated_at: "2026-02-03T07:52:36Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 4ea67701bd58b7512f945fce58d79e1b3d990fbf45183323a1e3ab9688827623
@@ -14,18 +14,18 @@ x-i18n:

 # macOS 开发者设置

-本指南介绍从源代码构建和运行 OpenClaw macOS 应用的必要步骤。
+本指南涵盖从源代码构建和运行 OpenClaw macOS 应用程序的必要步骤。

-## 前提条件
+## 前置条件

-在构建应用之前，请确保已安装以下内容：
+在构建应用之前，确保你已安装以下内容：

 1.  **Xcode 26.2+**：Swift 开发所需。
-2.  **Node.js 22+ & pnpm**：Gateway网关、CLI 和打包脚本所需。
+2.  **Node.js 22+ & pnpm**：Gateway 网关、CLI 和打包脚本所需。

 ## 1. 安装依赖

-安装项目的全部依赖：
+安装项目范围的依赖：

 ```bash
 pnpm install
@@ -33,30 +33,30 @@ pnpm install

 ## 2. 构建和打包应用

-要构建 macOS 应用并将其打包为 `dist/OpenClaw.app`，请运行：
+要构建 macOS 应用并将其打包到 `dist/OpenClaw.app`，运行：

 ```bash
 ./scripts/package-mac-app.sh
 ```

-如果你没有 Apple Developer ID 证书，脚本将自动使用**临时签名**（`-`）。
+如果你没有 Apple Developer ID 证书，脚本将自动使用 **ad-hoc 签名**（`-`）。

-有关开发运行模式、签名选项和 Team ID 故障排除，请参阅 macOS 应用 README：
+有关开发运行模式、签名标志和 Team ID 故障排除，请参阅 macOS 应用 README：
 https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

-> **注意**：临时签名的应用可能会触发安全提示。如果应用立即崩溃并显示 "Abort trap 6"，请参阅[故障排除](#troubleshooting)部分。
+> **注意**：Ad-hoc 签名的应用可能会触发安全提示。如果应用立即崩溃并显示"Abort trap 6"，请参阅[故障排除](#troubleshooting)部分。

 ## 3. 安装 CLI

-macOS 应用需要全局安装 `openclaw` CLI 来管理后台任务。
+macOS 应用期望全局安装 `openclaw` CLI 来管理后台任务。

-**安装方式（推荐）：**
+**安装方法（推荐）：**

 1.  打开 OpenClaw 应用。
-2.  进入 **General** 设置选项卡。
+2.  转到 **General** 设置标签页。
 3.  点击 **"Install CLI"**。

-或者手动安装：
+或者，手动安装：

 ```bash
 npm install -g openclaw@<version>
@@ -66,11 +66,11 @@ npm install -g openclaw@<version>

 ### 构建失败：工具链或 SDK 不匹配

-macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链。
+macOS 应用构建期望最新的 macOS SDK 和 Swift 6.2 工具链。

 **系统依赖（必需）：**

- **软件更新中可用的最新 macOS 版本**（Xcode 26.2 SDK 要求）
+- **软件更新中可用的最新 macOS 版本**（Xcode 26.2 SDK 所需）
 - **Xcode 26.2**（Swift 6.2 工具链）

 **检查：**
@@ -80,30 +80,30 @@ xcodebuild -version
 xcrun swift --version
 ```

-如果版本不匹配，请更新 macOS/Xcode 并重新运行构建。
+如果版本不匹配，更新 macOS/Xcode 并重新运行构建。

-### 授权时应用崩溃
+### 授予权限时应用崩溃

 如果在尝试允许**语音识别**或**麦克风**访问时应用崩溃，可能是由于 TCC 缓存损坏或签名不匹配。

-**修复方法：**
+**修复：**

 1. 重置 TCC 权限：
   ```bash
   tccutil reset All bot.molt.mac.debug
   ```
-2. 如果仍然无效，在 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中临时更改 `BUNDLE_ID`，以强制 macOS 使用"全新状态"。
+2. 如果这不起作用，在 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中临时更改 `BUNDLE_ID` 以强制 macOS 从"全新状态"开始。

-### Gateway网关持续显示"Starting..."
+### Gateway 网关无限期"Starting..."

-如果 Gateway网关状态一直停留在"Starting..."，请检查是否有僵尸进程占用了端口：
+如果 Gateway 网关状态一直停留在"Starting..."，检查是否有僵尸进程占用端口：

 ```bash
 openclaw gateway status
 openclaw gateway stop

-# 如果你没有使用 LaunchAgent（开发模式/手动运行），查找监听进程：
+# 如果你没有使用 LaunchAgent（开发模式/手动运行），找到监听器：
 lsof -nP -iTCP:18789 -sTCP:LISTEN
 ```

-如果是手动运行的进程占用了端口，请停止该进程（Ctrl+C）。作为最后手段，终止上面找到的 PID。
+如果手动运行占用了端口，停止该进程（Ctrl+C）。作为最后手段，杀死你找到的 PID。
@@ -1,10 +1,10 @@
 ---
 read_when:
  - 调试 Mac 应用健康指示器
-summary: macOS 应用如何报告 Gateway网关/Baileys 健康状态
+summary: macOS 应用如何报告 Gateway 网关/Baileys 健康状态
 title: 健康检查
 x-i18n:
-  generated_at: "2026-02-01T21:32:43Z"
+  generated_at: "2026-02-03T07:52:40Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 0560e96501ddf53a499f8960cfcf11c2622fcb9056bfd1bcc57876e955cab03d
@@ -14,28 +14,28 @@ x-i18n:

 # macOS 上的健康检查

-如何从菜单栏应用查看已关联渠道的健康状态。
+如何从菜单栏应用查看关联渠道是否健康。

 ## 菜单栏

 - 状态圆点现在反映 Baileys 健康状态：
-  - 绿色：已关联 + socket 近期已打开。
-  - 橙色：正在连接/重试中。
+  - 绿色：已关联 + socket 最近已打开。
+  - 橙色：正在连接/重试。
  - 红色：已登出或探测失败。
- 次要行显示 "linked · auth 12m" 或显示失败原因。
- "运行健康检查" 菜单项可触发按需探测。
+- 第二行显示"linked · auth 12m"或显示失败原因。
+- "Run Health Check"菜单项触发按需探测。

 ## 设置

- 通用选项卡新增健康卡片，显示：已关联认证时长、会话存储路径/数量、上次检查时间、上次错误/状态码，以及"运行健康检查"/"显示日志"按钮。
- 使用缓存快照，使 UI 即时加载，离线时优雅降级。
- **渠道选项卡**展示渠道状态 + WhatsApp/Telegram 的控制项（登录二维码、登出、探测、上次断连/错误）。
+- 通用选项卡新增健康卡片，显示：关联认证时间、会话存储路径/数量、上次检查时间、上次错误/状态码，以及运行健康检查/显示日志按钮。
+- 使用缓存快照，因此 UI 立即加载，离线时优雅降级。
+- **渠道选项卡**显示渠道状态 + WhatsApp/Telegram 的控制（登录二维码、登出、探测、上次断开/错误）。

 ## 探测工作原理

- 应用每约 60 秒以及按需通过 `ShellExecutor` 运行 `openclaw health --json`。探测会加载凭据并报告状态，不会发送消息。
- 分别缓存上次成功的快照和上次错误，以避免闪烁；显示各自的时间戳。
+- 应用每约 60 秒和按需时通过 `ShellExecutor` 运行 `openclaw health --json`。探测加载凭证并报告状态，不发送消息。
+- 分别缓存上次成功的快照和上次错误以避免闪烁；显示每个的时间戳。

-## 不确定时
+## 有疑问时

- 你仍然可以使用 [Gateway网关健康检查](/gateway/health) 中的 CLI 流程（`openclaw status`、`openclaw status --deep`、`openclaw health --json`），并跟踪 `/tmp/openclaw/openclaw-*.log` 中的 `web-heartbeat` / `web-reconnect`。
+- 你仍然可以使用 [Gateway 网关健康](/gateway/health) 中的 CLI 流程（`openclaw status`、`openclaw status --deep`、`openclaw health --json`），并在 `/tmp/openclaw/openclaw-*.log` 中跟踪 `web-heartbeat` / `web-reconnect`。
@@ -1,10 +1,10 @@
 ---
 read_when:
-  - 设置或调试远程 Mac 控制
-summary: macOS 应用通过 SSH 远程控制 OpenClaw Gateway网关的流程
+  - 设置或调试远程 mac 控制时
+summary: macOS 应用通过 SSH 控制远程 OpenClaw Gateway 网关的流程
 title: 远程控制
 x-i18n:
-  generated_at: "2026-02-01T21:33:20Z"
+  generated_at: "2026-02-03T07:52:53Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 61b43707250d5515fd0f85f092bdde24598f14904398ff3fca3736bcc48d72f8
@@ -14,77 +14,77 @@ x-i18n:

 # 远程 OpenClaw（macOS ⇄ 远程主机）

-此流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw Gateway网关的完整远程控制器。这是应用的 **Remote over SSH**（远程运行）功能。所有功能——健康检查、语音唤醒转发和 Web Chat——都复用 _设置 → 通用_ 中相同的远程 SSH 配置。
+此流程让 macOS 应用作为运行在另一台主机（桌面/服务器）上的 OpenClaw Gateway 网关的完整远程控制。这是应用的 **Remote over SSH**（远程运行）功能。所有功能——健康检查、语音唤醒转发和 Web Chat——都重用来自 _Settings → General_ 的相同远程 SSH 配置。

 ## 模式

- **本地（此 Mac）**：所有内容在笔记本电脑上运行，无需 SSH。
- **Remote over SSH（默认）**：OpenClaw 命令在远程主机上执行。Mac 应用使用 `-o BatchMode` 加上你选择的身份/密钥打开 SSH 连接，并进行本地端口转发。
- **Remote direct (ws/wss)**：无 SSH 隧道。Mac 应用直接连接到 Gateway网关 URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。
+- **Local (this Mac)**：一切都在笔记本电脑上运行。不涉及 SSH。
+- **Remote over SSH（默认）**：OpenClaw 命令在远程主机上执行。mac 应用使用 `-o BatchMode` 加上你选择的身份/密钥打开 SSH 连接，并进行本地端口转发。
+- **Remote direct (ws/wss)**：无 SSH 隧道。mac 应用直接连接到 Gateway 网关 URL（例如，通过 Tailscale Serve 或公共 HTTPS 反向代理）。

-## 远程传输方式
+## 远程传输

 远程模式支持两种传输方式：

- **SSH 隧道**（默认）：使用 `ssh -N -L ...` 将 Gateway网关端口转发到 localhost。由于隧道是 local loopback 的，Gateway网关会将节点 IP 识别为 `127.0.0.1`。
- **Direct (ws/wss)**：直接连接到 Gateway网关 URL。Gateway网关会看到真实的客户端 IP。
+- **SSH 隧道**（默认）：使用 `ssh -N -L ...` 将 Gateway 网关端口转发到 localhost。Gateway 网关会将节点的 IP 视为 `127.0.0.1`，因为隧道是 loopback。
+- **Direct (ws/wss)**：直接连接到 Gateway 网关 URL。Gateway 网关看到真实的客户端 IP。

-## 远程主机的前提条件
+## 远程主机上的先决条件

 1. 安装 Node + pnpm 并构建/安装 OpenClaw CLI（`pnpm install && pnpm build && pnpm link --global`）。
-2. 确保 `openclaw` 在非交互式 shell 的 PATH 中（如有需要，创建符号链接到 `/usr/local/bin` 或 `/opt/homebrew/bin`）。
-3. 开启 SSH 密钥认证。我们建议使用 **Tailscale** IP 以实现局域网外的稳定可达性。
+2. 确保 `openclaw` 在非交互式 shell 的 PATH 中（如需要，请符号链接到 `/usr/local/bin` 或 `/opt/homebrew/bin`）。
+3. 使用密钥认证打开 SSH。我们推荐使用 **Tailscale** IP 以实现离开局域网时的稳定可达性。

 ## macOS 应用设置

-1. 打开 _设置 → 通用_。
+1. 打开 _Settings → General_。
 2. 在 **OpenClaw runs** 下，选择 **Remote over SSH** 并设置：
-   - **传输方式**：**SSH 隧道** 或 **Direct (ws/wss)**。
-   - **SSH 目标**：`user@host`（可选 `:port`）。
-     - 如果 Gateway网关在同一局域网中并通过 Bonjour 广播，可从发现列表中选择以自动填充此字段。
-   - **Gateway网关 URL**（仅 Direct 模式）：`wss://gateway.example.ts.net`（或局域网使用 `ws://...`）。
-   - **身份文件**（高级）：密钥路径。
-   - **项目根目录**（高级）：用于命令执行的远程代码仓库路径。
-   - **CLI 路径**（高级）：可选的 `openclaw` 可执行入口/二进制文件路径（广播时自动填充）。
-3. 点击 **测试远程连接**。成功表示远程 `openclaw status --json` 正常运行。失败通常意味着 PATH/CLI 问题；exit 127 表示远程未找到 CLI。
-4. 健康检查和 Web Chat 现在会自动通过此 SSH 隧道运行。
+   - **Transport**：**SSH tunnel** 或 **Direct (ws/wss)**。
+   - **SSH target**：`user@host`（可选 `:port`）。
+     - 如果 Gateway 网关在同一局域网上并广播 Bonjour，从发现列表中选择它以自动填充此字段。
+   - **Gateway URL**（仅 Direct）：`wss://gateway.example.ts.net`（或本地/局域网使用 `ws://...`）。
+   - **Identity file**（高级）：你的密钥路径。
+   - **Project root**（高级）：用于命令的远程 checkout 路径。
+   - **CLI path**（高级）：可运行的 `openclaw` 入口点/二进制文件的可选路径（广播时自动填充）。
+3. 点击 **Test remote**。成功表示远程 `openclaw status --json` 正确运行。失败通常意味着 PATH/CLI 问题；退出码 127 表示远程找不到 CLI。
+4. 健康检查和 Web Chat 现在将自动通过此 SSH 隧道运行。

 ## Web Chat

- **SSH 隧道**：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway网关。
- **Direct (ws/wss)**：Web Chat 直接连接到配置的 Gateway网关 URL。
+- **SSH 隧道**：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway 网关。
+- **Direct (ws/wss)**：Web Chat 直接连接到配置的 Gateway 网关 URL。
 - 不再有单独的 WebChat HTTP 服务器。

 ## 权限

- 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行新手引导以一次性授予权限。
- 节点通过 `node.list` / `node.describe` 广播其权限状态，以便智能体了解可用功能。
+- 远程主机需要与本地相同的 TCC 批准（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行新手引导以一次性授予它们。
+- 节点通过 `node.list` / `node.describe` 广播其权限状态，以便智能体知道哪些可用。

 ## 安全注意事项

- 建议在远程主机上绑定 local loopback，并通过 SSH 或 Tailscale 连接。
- 如果将 Gateway网关绑定到非 local loopback 接口，请要求令牌/密码认证。
- 参阅 [安全](/gateway/security) 和 [Tailscale](/gateway/tailscale)。
+- 优先在远程主机上使用 loopback 绑定，并通过 SSH 或 Tailscale 连接。
+- 如果你将 Gateway 网关绑定到非 loopback 接口，请要求令牌/密码认证。
+- 参见[安全](/gateway/security)和 [Tailscale](/gateway/tailscale)。

 ## WhatsApp 登录流程（远程）

- 在**远程主机**上运行 `openclaw channels login --verbose`。用手机上的 WhatsApp 扫描二维码。
- 如果认证过期，在该主机上重新运行登录。健康检查会显示链接问题。
+- **在远程主机上**运行 `openclaw channels login --verbose`。用手机上的 WhatsApp 扫描二维码。
+- 如果认证过期，在该主机上重新运行登录。健康检查会显示关联问题。

 ## 故障排除

- **exit 127 / not found**：`openclaw` 不在非登录 shell 的 PATH 中。将其添加到 `/etc/paths`、你的 shell rc 文件中，或创建符号链接到 `/usr/local/bin`/`/opt/homebrew/bin`。
- **健康探测失败**：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（`openclaw status --json`）。
- **Web Chat 卡住**：确认 Gateway网关在远程主机上正在运行，且转发端口与 Gateway网关 WS 端口匹配；界面需要健康的 WS 连接。
- **节点 IP 显示 127.0.0.1**：使用 SSH 隧道时这是预期行为。如果你希望 Gateway网关看到真实客户端 IP，请将**传输方式**切换为 **Direct (ws/wss)**。
- **语音唤醒**：触发短语在远程模式下会自动转发；无需单独的转发器。
+- **exit 127 / not found**：`openclaw` 不在非登录 shell 的 PATH 中。将其添加到 `/etc/paths`、你的 shell rc，或符号链接到 `/usr/local/bin`/`/opt/homebrew/bin`。
+- **Health probe failed**：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（`openclaw status --json`）。
+- **Web Chat 卡住**：确认 Gateway 网关正在远程主机上运行，转发的端口与 Gateway 网关 WS 端口匹配；UI 需要健康的 WS 连接。
+- **节点 IP 显示 127.0.0.1**：使用 SSH 隧道时是预期的。如果你想让 Gateway 网关看到真实的客户端 IP，请将 **Transport** 切换到 **Direct (ws/wss)**。
+- **Voice Wake**：触发短语在远程模式下自动转发；不需要单独的转发器。

 ## 通知声音

-通过 `openclaw` 和 `node.invoke` 在脚本中为每个通知选择声音，例如：
+通过带有 `openclaw` 和 `node.invoke` 的脚本为每个通知选择声音，例如：

 ```bash
 openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
 ```

-应用中不再有全局"默认声音"开关；调用方按请求选择声音（或不使用声音）。
+应用中不再有全局"默认声音"开关；调用者为每个请求选择声音（或无声音）。
@@ -2,10 +2,10 @@
 read_when:
  - 更新 macOS Skills 设置 UI
  - 更改 Skills 门控或安装行为
-summary: macOS Skills 设置 UI 及 Gateway网关支持的状态
+summary: macOS Skills 设置 UI 和基于 Gateway 网关的状态
 title: Skills
 x-i18n:
-  generated_at: "2026-02-01T21:33:07Z"
+  generated_at: "2026-02-03T10:08:09Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: ecd5286bbe49eed89319686c4f7d6da55ef7b0d3952656ba98ef5e769f3fbf79
@@ -15,26 +15,26 @@ x-i18n:

 # Skills（macOS）

-macOS 应用通过 Gateway网关展示 OpenClaw Skills；不会在本地解析 Skills。
+macOS 应用通过 Gateway 网关展示 OpenClaw Skills；它不会在本地解析 Skills。

 ## 数据来源

- `skills.status`（Gateway网关）返回所有 Skills 及其资格和缺失的依赖项
-  （包括内置 Skills 的白名单限制）。
- 依赖项来源于每个 `SKILL.md` 中的 `metadata.openclaw.requires`。
+- `skills.status`（Gateway 网关）返回所有 Skills 以及资格和缺失的要求
+  （包括内置 Skills 的允许列表阻止情况）。
+- 要求来源于每个 `SKILL.md` 中的 `metadata.openclaw.requires`。

 ## 安装操作

 - `metadata.openclaw.install` 定义安装选项（brew/node/go/uv）。
- 应用调用 `skills.install` 在 Gateway网关主机上运行安装程序。
- 当提供多个安装程序时，Gateway网关仅展示一个首选安装程序
-  （优先使用 brew，否则使用 `skills.install` 中的 node 管理器，默认为 npm）。
+- 应用调用 `skills.install` 在 Gateway 网关主机上运行安装器。
+- 当提供多个安装器时，Gateway 网关仅展示一个首选安装器
+  （如果可用则使用 brew，否则使用来自 `skills.install` 的 node 管理器，默认 npm）。

 ## 环境变量/API 密钥

 - 应用将密钥存储在 `~/.openclaw/openclaw.json` 的 `skills.entries.<skillKey>` 下。
- `skills.update` 可修改 `enabled`、`apiKey` 和 `env`。
+- `skills.update` 更新 `enabled`、`apiKey` 和 `env`。

 ## 远程模式

- 安装和配置更新在 Gateway网关主机上执行（而非本地 Mac）。
+- 安装 + 配置更新发生在 Gateway 网关主机上（不是本地 Mac）。
@@ -1,10 +1,10 @@
 ---
 read_when:
-  - 正在开发语音唤醒或按键通话相关功能
+  - 开发语音唤醒或按键通话路径
 summary: Mac 应用中的语音唤醒和按键通话模式及路由详情
 title: 语音唤醒
 x-i18n:
-  generated_at: "2026-02-01T21:33:32Z"
+  generated_at: "2026-02-03T10:08:23Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: f6440bb89f349ba5c1c9aacffe95e568681beb9899ca736dedfe2f4a366cb5e4
@@ -16,59 +16,59 @@ x-i18n:

 ## 模式

- **唤醒词模式**（默认）：常驻语音识别器等待触发词（`swabbleTriggerWords`）。匹配后开始采集，显示叠加层并展示部分文本，静默后自动发送。
- **按键通话（长按右 Option 键）**：长按右 Option 键立即开始采集——无需触发词。长按期间显示叠加层；松开后完成采集并在短暂延迟后转发，以便你调整文本。
+- **唤醒词模式**（默认）：常驻语音识别器等待触发词（`swabbleTriggerWords`）。匹配时开始捕获，显示带有部分文本的悬浮窗，并在静默后自动发送。
+- **按键通话（按住右 Option 键）**：按住右 Option 键立即开始捕获——无需触发词。按住时显示悬浮窗；松开后延迟片刻再最终转发，以便你可以调整文本。

 ## 运行时行为（唤醒词）

 - 语音识别器位于 `VoiceWakeRuntime` 中。
- 仅当唤醒词和下一个词之间存在**有意义的停顿**（约 0.55 秒间隔）时才会触发。叠加层/提示音可以在停顿时启动，甚至在命令开始之前。
- 静默窗口：语音持续时为 2.0 秒，仅听到触发词时为 5.0 秒。
- 硬停止：120 秒，防止会话失控。
- 会话间去抖：350 毫秒。
- 叠加层通过 `VoiceWakeOverlayController` 驱动，具有已确认/临时着色。
- 发送后，识别器干净重启以监听下一个触发词。
+- 仅当唤醒词和下一个词之间有**明显停顿**（约 0.55 秒间隔）时才触发。悬浮窗/提示音可以在命令开始前的停顿时就启动。
+- 静默窗口：语音流畅时为 2.0 秒，如果只听到触发词则为 5.0 秒。
+- 硬性停止：120 秒，防止会话失控。
+- 会话间去抖动：350 毫秒。
+- 悬浮窗通过 `VoiceWakeOverlayController` 驱动，带有已提交/临时状态的颜色区分。
+- 发送后，识别器干净地重启以监听下一个触发词。

 ## 生命周期不变量

- 如果语音唤醒已启用且权限已授予，唤醒词识别器应保持监听状态（显式按键通话采集期间除外）。
- 叠加层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。
+- 如果启用了语音唤醒且权限已授予，唤醒词识别器应该处于监听状态（除非正在进行显式的按键通话捕获）。
+- 悬浮窗可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。

-## 叠加层卡住故障模式（历史问题）
+## 悬浮窗卡住的故障模式（之前的问题）

-此前，如果叠加层卡在可见状态并且你手动关闭它，语音唤醒可能表现为"无响应"，因为运行时的重启尝试会被叠加层可见性阻塞，且不会调度后续重启。
+之前，如果悬浮窗卡在可见状态且你手动关闭它，语音唤醒可能会显得"失效"，因为运行时的重启尝试可能被悬浮窗可见性阻止，且没有安排后续重启。

 加固措施：

- 唤醒运行时重启不再被叠加层可见性阻塞。
- 叠加层关闭完成后通过 `VoiceSessionCoordinator` 触发 `VoiceWakeRuntime.refresh(...)`，因此手动点击 X 关闭始终会恢复监听。
+- 唤醒运行时重启不再被悬浮窗可见性阻止。
+- 悬浮窗关闭完成时通过 `VoiceSessionCoordinator` 触发 `VoiceWakeRuntime.refresh(...)`，因此手动点击 X 关闭总是会恢复监听。

-## 按键通话详情
+## 按键通话细节

- 热键检测使用全局 `.flagsChanged` 监视器检测**右 Option 键**（`keyCode 61` + `.option`）。我们仅观察事件（不拦截）。
- 采集管道位于 `VoicePushToTalk` 中：立即启动语音识别，将部分结果流式传输到叠加层，松开时调用 `VoiceWakeForwarder`。
- 按键通话开始时，我们暂停唤醒词运行时以避免音频输入冲突；松开后自动重启。
- 权限：需要麦克风 + 语音识别权限；查看事件需要辅助功能/输入监控授权。
- 外接键盘：某些键盘可能无法按预期暴露右 Option 键——如果用户反馈未响应，请提供备用快捷键。
+- 热键检测使用全局 `.flagsChanged` 监视器检测**右 Option 键**（`keyCode 61` + `.option`）。我们只观察事件（不拦截）。
+- 捕获管道位于 `VoicePushToTalk` 中：立即启动语音识别，将部分结果流式传输到悬浮窗，并在松开时调用 `VoiceWakeForwarder`。
+- 按键通话开始时，我们暂停唤醒词运行时以避免音频采集冲突；松开后自动重启。
+- 权限：需要麦克风 + 语音识别权限；查看事件需要辅助功能/输入监控批准。
+- 外接键盘：某些键盘可能无法按预期暴露右 Option 键——如果用户报告未响应，提供备用快捷键。

 ## 面向用户的设置

 - **语音唤醒**开关：启用唤醒词运行时。
- **长按 Cmd+Fn 说话**：启用按键通话监视器。在 macOS < 26 上禁用。
- 语言和麦克风选择器、实时电平指示器、触发词表格、测试器（仅本地；不进行转发）。
- 麦克风选择器在设备断开时保留上次选择，显示断开提示，并在设备恢复前临时回退到系统默认设备。
- **声音**：触发检测和发送时播放提示音；默认使用 macOS "Glass" 系统声音。你可以为每个事件选择任何 `NSSound` 可加载的文件（如 MP3/WAV/AIFF），或选择**无声音**。
+- **按住 Cmd+Fn 说话**：启用按键通话监视器。在 macOS < 26 上禁用。
+- 语言和麦克风选择器、实时电平指示器、触发词表、测试器（仅本地；不转发）。
+- 麦克风选择器在设备断开时保留上次选择，显示断开提示，并临时回退到系统默认设备直到设备恢复。
+- **声音**：触发检测和发送时的提示音；默认为 macOS"Glass"系统声音。你可以为每个事件选择任何 `NSSound` 可加载的文件（例如 MP3/WAV/AIFF）或选择**无声音**。

 ## 转发行为

- 启用语音唤醒后，转录文本将转发到活跃的 Gateway网关/智能体（与 Mac 应用其他部分使用的本地/远程模式相同）。
- 回复将发送到**最近使用的主要提供商**（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，错误会被记录，且运行仍可通过 WebChat/会话日志查看。
+- 启用语音唤醒时，转录文本被转发到活动的 Gateway 网关/智能体（与 Mac 应用其他部分使用相同的本地/远程模式）。
+- 回复被投递到**上次使用的主提供商**（WhatsApp/Telegram/Discord/WebChat）。如果投递失败，错误会被记录，运行记录仍可通过 WebChat/会话日志查看。

-## 转发载荷
+## 转发负载

- `VoiceWakeForwarder.prefixedTranscript(_:)` 在发送前添加机器提示前缀。唤醒词和按键通话路径共用此逻辑。
+- `VoiceWakeForwarder.prefixedTranscript(_:)` 在发送前添加机器提示前缀。唤醒词和按键通话路径共享此方法。

 ## 快速验证

- 开启按键通话，长按 Cmd+Fn，说话，松开：叠加层应显示部分结果然后发送。
- 长按期间，菜单栏耳朵图标应保持放大状态（使用 `triggerVoiceEars(ttl:nil)`）；松开后恢复。
+- 开启按键通话，按住 Cmd+Fn，说话，松开：悬浮窗应显示部分结果然后发送。
+- 按住时，菜单栏耳朵图标应保持放大状态（使用 `triggerVoiceEars(ttl:nil)`）；松开后恢复。
@@ -1,10 +1,10 @@
 ---
 read_when:
-  - 调试 Mac WebChat 视图或 local loopback 端口
-summary: Mac 应用如何嵌入 Gateway网关 WebChat 以及如何调试
+  - 调试 macOS WebChat 视图或 loopback 端口
+summary: macOS 应用如何嵌入 Gateway 网关 WebChat 以及如何调试
 title: WebChat
 x-i18n:
-  generated_at: "2026-02-01T21:33:23Z"
+  generated_at: "2026-02-03T07:52:46Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 04ff448758e530098e2004625f33e42fc3dbe31137cd3beec2d55590e507de08
@@ -14,12 +14,12 @@ x-i18n:

 # WebChat（macOS 应用）

-macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接到 Gateway网关，默认使用所选智能体的**主会话**（通过会话切换器可访问其他会话）。
+macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接到 Gateway 网关，默认使用所选智能体的**主会话**（带有会话切换器用于其他会话）。

- **本地模式**：直接连接到本地 Gateway网关 WebSocket。
- **远程模式**：通过 SSH 转发 Gateway网关控制端口，并使用该隧道作为数据平面。
+- **本地模式**：直接连接到本地 Gateway 网关 WebSocket。
+- **远程模式**：通过 SSH 转发 Gateway 网关控制端口，并使用该隧道作为数据平面。

-## 启动与调试
+## 启动和调试

 - 手动：Lobster 菜单 → "Open Chat"。
 - 测试时自动打开：
@@ -30,14 +30,14 @@ macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接

 ## 工作原理

- 数据平面：Gateway网关 WS 方法 `chat.history`、`chat.send`、`chat.abort`、`chat.inject` 以及事件 `chat`、`agent`、`presence`、`tick`、`health`。
- 会话：默认使用主会话（`main`，或作用域为全局时使用 `global`）。UI 可在会话之间切换。
- 新手引导使用专用会话，以将首次运行设置与其他内容分开。
+- 数据平面：Gateway 网关 WS 方法 `chat.history`、`chat.send`、`chat.abort`、`chat.inject` 和事件 `chat`、`agent`、`presence`、`tick`、`health`。
+- 会话：默认为主会话（`main`，或当范围为全局时为 `global`）。UI 可以在会话之间切换。
+- 新手引导使用专用会话，以将首次运行设置分开。

 ## 安全面

- 远程模式仅通过 SSH 转发 Gateway网关 WebSocket 控制端口。
+- 远程模式仅通过 SSH 转发 Gateway 网关 WebSocket 控制端口。

 ## 已知限制

- UI 针对聊天会话进行了优化（不是完整的浏览器沙箱）。
+- UI 针对聊天会话优化（不是完整的浏览器沙箱）。
@@ -1,10 +1,10 @@
 ---
 read_when:
-  - 编辑 IPC 协议或菜单栏应用 IPC
-summary: OpenClaw 应用、gateway 节点传输和 PeekabooBridge 的 macOS IPC 架构
+  - 编辑 IPC 合约或菜单栏应用 IPC
+summary: OpenClaw 应用的 macOS IPC 架构、Gateway 网关节点传输和 PeekabooBridge
 title: macOS IPC
 x-i18n:
-  generated_at: "2026-02-01T21:33:31Z"
+  generated_at: "2026-02-03T07:52:57Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: d0211c334a4a59b71afb29dd7b024778172e529fa618985632d3d11d795ced92
@@ -14,31 +14,31 @@ x-i18n:

 # OpenClaw macOS IPC 架构

-**当前模型：** 本地 Unix 套接字将**节点宿主服务**连接到 **macOS 应用**，用于执行审批和 `system.run`。存在一个 `openclaw-mac` 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway网关 WebSocket 和 `node.invoke` 传递。UI 自动化使用 PeekabooBridge。
+**当前模型：** 一个本地 Unix 套接字将**节点主机服务**连接到 **macOS 应用**，用于 exec 审批 + `system.run`。存在一个 `openclaw-mac` 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway 网关 WebSocket 和 `node.invoke` 流转。UI 自动化使用 PeekabooBridge。

 ## 目标

- 单个 GUI 应用实例负责所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
- 精简的自动化接口：Gateway网关 + 节点命令，加上用于 UI 自动化的 PeekabooBridge。
- 可预测的权限：始终使用相同的已签名 bundle ID，由 launchd 启动，确保 TCC 授权持久有效。
+- 单个 GUI 应用实例拥有所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
+- 小型自动化接口：Gateway 网关 + 节点命令，加上用于 UI 自动化的 PeekabooBridge。
+- 可预测的权限：始终是同一个签名的 bundle ID，由 launchd 启动，因此 TCC 授权保持有效。

 ## 工作原理

-### Gateway网关 + 节点传输
+### Gateway 网关 + 节点传输

- 应用运行 Gateway网关（本地模式）并作为节点连接到它。
+- 应用运行 Gateway 网关（本地模式）并作为节点连接到它。
 - 智能体操作通过 `node.invoke` 执行（例如 `system.run`、`system.notify`、`canvas.*`）。

 ### 节点服务 + 应用 IPC

- 无界面的节点宿主服务通过 WebSocket 连接到 Gateway网关。
+- 一个无头节点主机服务连接到 Gateway 网关 WebSocket。
 - `system.run` 请求通过本地 Unix 套接字转发到 macOS 应用。
- 应用在 UI 上下文中执行操作，必要时提示用户确认，并返回输出。
+- 应用在 UI 上下文中执行 exec，必要时提示，并返回输出。

-架构图（SCI）：
+图示（SCI）：

 ```
-Agent -> Gateway网关 -> Node Service (WS)
+Agent -> Gateway -> Node Service (WS)
                      |  IPC (UDS + token + HMAC + TTL)
                      v
                  Mac App (UI + TCC + system.run)
@@ -46,23 +46,23 @@ Agent -> Gateway网关 -> Node Service (WS)

 ### PeekabooBridge（UI 自动化）

- UI 自动化使用名为 `bridge.sock` 的独立 UNIX 套接字和 PeekabooBridge JSON 协议。
- 宿主优先级顺序（客户端侧）：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行。
- 安全性：bridge 宿主要求允许的 TeamID；仅 DEBUG 模式下的同 UID 回退机制受 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（Peekaboo 约定）保护。
- 详见：[PeekabooBridge 用法](/platforms/mac/peekaboo)。
+- UI 自动化使用名为 `bridge.sock` 的单独 UNIX 套接字和 PeekabooBridge JSON 协议。
+- 主机优先顺序（客户端侧）：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行。
+- 安全性：桥接主机需要允许的 TeamID；仅 DEBUG 的同 UID 逃逸通道由 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` 保护（Peekaboo 约定）。
+- 参见：[PeekabooBridge 用法](/platforms/mac/peekaboo)了解详情。

 ## 操作流程

- 重启/重新构建：`SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh`
+- 重启/重建：`SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh`
  - 终止现有实例
  - Swift 构建 + 打包
  - 写入/引导/启动 LaunchAgent
- 单实例：如果另一个具有相同 bundle ID 的实例正在运行，应用会提前退出。
+- 单实例：如果具有相同 bundle ID 的另一个实例正在运行，应用会提前退出。

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

- 优先要求所有特权接口进行 TeamID 匹配。
- PeekabooBridge：`PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（仅 DEBUG 模式）可允许同 UID 调用方用于本地开发。
- 所有通信仅限本地；不暴露网络套接字。
- TCC 提示仅来自 GUI 应用 bundle；跨重新构建时保持已签名的 bundle ID 稳定。
- IPC 加固：套接字模式 `0600`、令牌、对端 UID 检查、HMAC 质询/响应、短 TTL。
+- 优先要求所有特权接口的 TeamID 匹配。
+- PeekabooBridge：`PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（仅 DEBUG）可能允许同 UID 调用者用于本地开发。
+- 所有通信仅保持本地；不暴露网络套接字。
+- TCC 提示仅源自 GUI 应用包；在重建时保持签名的 bundle ID 稳定。
+- IPC 加固：套接字模式 `0600`、令牌、对等 UID 检查、HMAC 质询/响应、短 TTL。
@@ -1,13 +1,13 @@
 ---
 read_when:
-  - 你希望将 OpenClaw 与主 macOS 环境隔离运行
-  - 你需要在沙盒中集成 iMessage（BlueBubbles）
-  - 你需要一个可重置、可克隆的 macOS 环境
-  - 你想比较本地与托管 macOS 虚拟机方案
-summary: 在沙盒化的 macOS 虚拟机（本地或托管）中运行 OpenClaw，适用于需要隔离环境或 iMessage 的场景
+  - 你想让 OpenClaw 与你的主 macOS 环境隔离
+  - 你想在沙箱中集成 iMessage（BlueBubbles）
+  - 你想要一个可重置、可克隆的 macOS 环境
+  - 你想比较本地与托管 macOS VM 选项
+summary: 在沙箱隔离的 macOS VM（本地或托管）中运行 OpenClaw，当你需要隔离或 iMessage 时
 title: macOS 虚拟机
 x-i18n:
-  generated_at: "2026-02-01T21:33:51Z"
+  generated_at: "2026-02-03T07:53:09Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 4d1c85a5e4945f9f0796038cd5960edecb71ec4dffb6f9686be50adb75180716
@@ -15,37 +15,37 @@ x-i18n:
  workflow: 15
 ---

-# 在 macOS 虚拟机上运行 OpenClaw（沙盒化）
+# 在 macOS 虚拟机上运行 OpenClaw（沙箱隔离）

 ## 推荐默认方案（大多数用户）

- **小型 Linux VPS**，用于始终在线的 Gateway网关，成本低廉。参阅 [VPS 托管](/vps)。
- **专用硬件**（Mac mini 或 Linux 主机），如果你需要完全控制和**住宅 IP** 以进行浏览器自动化。许多网站会屏蔽数据中心 IP，因此本地浏览通常效果更好。
- **混合方案：** 将 Gateway网关部署在廉价 VPS 上，需要浏览器/UI 自动化时将你的 Mac 作为**节点**连接。参阅 [节点](/nodes) 和 [Gateway网关远程控制](/gateway/remote)。
+- **小型 Linux VPS** 用于永久在线的 Gateway 网关，成本低。参见 [VPS 托管](/vps)。
+- **专用硬件**（Mac mini 或 Linux 机器）如果你想要完全控制和**住宅 IP** 用于浏览器自动化。许多网站会屏蔽数据中心 IP，所以本地浏览通常效果更好。
+- **混合方案：** 将 Gateway 网关保持在廉价 VPS 上，当你需要浏览器/UI 自动化时，将你的 Mac 作为**节点**连接。参见[节点](/nodes)和 [Gateway 网关远程](/gateway/remote)。

-当你特别需要 macOS 专有功能（iMessage/BlueBubbles）或希望与日常使用的 Mac 严格隔离时，请使用 macOS 虚拟机。
+当你特别需要 macOS 独有功能（iMessage/BlueBubbles）或想要与日常 Mac 严格隔离时，使用 macOS VM。

-## macOS 虚拟机方案
+## macOS VM 选项

-### 在 Apple Silicon Mac 上运行本地虚拟机（Lume）
+### 在你的 Apple Silicon Mac 上运行本地 VM（Lume）

-使用 [Lume](https://cua.ai/docs/lume) 在现有的 Apple Silicon Mac 上以沙盒化的 macOS 虚拟机运行 OpenClaw。
+使用 [Lume](https://cua.ai/docs/lume) 在你现有的 Apple Silicon Mac 上的沙箱 macOS VM 中运行 OpenClaw。

-这将为你提供：
+这为你提供：

- 隔离的完整 macOS 环境（宿主机保持干净）
- 通过 BlueBubbles 支持 iMessage（Linux/Windows 上无法实现）
- 通过克隆虚拟机即时重置
- 无需额外硬件或云端费用
+- 隔离的完整 macOS 环境（你的主机保持干净）
+- 通过 BlueBubbles 支持 iMessage（在 Linux/Windows 上不可能）
+- 通过克隆 VM 即时重置
+- 无需额外硬件或云成本

-### 托管 Mac 提供商（云端）
+### 托管 Mac 提供商（云）

-如果你需要云端的 macOS，托管 Mac 提供商也可以：
+如果你想要云端的 macOS，托管 Mac 提供商也可以：

 - [MacStadium](https://www.macstadium.com/)（托管 Mac）
- 其他托管 Mac 供应商同样适用；按照其虚拟机 + SSH 文档操作
+- 其他托管 Mac 供应商也可以；按照他们的 VM + SSH 文档操作

-获得 macOS 虚拟机的 SSH 访问权限后，继续下方步骤 6。
+一旦你有了 macOS VM 的 SSH 访问权限，继续下面的步骤 6。

 ---

@@ -53,18 +53,18 @@ x-i18n:

 1. 安装 Lume
 2. `lume create openclaw --os macos --ipsw latest`
-3. 完成设置助理，启用远程登录（SSH）
+3. 完成设置助手，启用远程登录（SSH）
 4. `lume run openclaw --no-display`
-5. SSH 登录，安装 OpenClaw，配置渠道
+5. SSH 进入，安装 OpenClaw，配置渠道
 6. 完成

 ---

-## 准备工作（Lume）
+## 你需要什么（Lume）

 - Apple Silicon Mac（M1/M2/M3/M4）
- 宿主机运行 macOS Sequoia 或更高版本
- 每个虚拟机约 60 GB 可用磁盘空间
+- 主机上安装 macOS Sequoia 或更高版本
+- 每个 VM 约 60 GB 可用磁盘空间
 - 约 20 分钟

 ---
@@ -87,28 +87,28 @@ echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
 lume --version
 ```

-文档：[Lume 安装指南](https://cua.ai/docs/lume/guide/getting-started/installation)
+文档：[Lume 安装](https://cua.ai/docs/lume/guide/getting-started/installation)

 ---

-## 2) 创建 macOS 虚拟机
+## 2) 创建 macOS VM

 ```bash
 lume create openclaw --os macos --ipsw latest
 ```

-这将下载 macOS 并创建虚拟机。VNC 窗口会自动打开。
+这会下载 macOS 并创建 VM。VNC 窗口会自动打开。

-注意：下载时间取决于你的网络连接速度。
+注意：下载可能需要一段时间，取决于你的网络连接。

 ---

-## 3) 完成设置助理
+## 3) 完成设置助手

 在 VNC 窗口中：

 1. 选择语言和地区
-2. 跳过 Apple ID（如果以后需要 iMessage 则登录）
+2. 跳过 Apple ID（或者如果你以后想要 iMessage 就登录）
 3. 创建用户账户（记住用户名和密码）
 4. 跳过所有可选功能

@@ -119,29 +119,29 @@ lume create openclaw --os macos --ipsw latest

 ---

-## 4) 获取虚拟机的 IP 地址
+## 4) 获取 VM 的 IP 地址

 ```bash
 lume get openclaw
 ```

-查找 IP 地址（通常为 `192.168.64.x`）。
+查找 IP 地址（通常是 `192.168.64.x`）。

 ---

-## 5) SSH 登录虚拟机
+## 5) SSH 进入 VM

 ```bash
 ssh youruser@192.168.64.X
 ```

-将 `youruser` 替换为你创建的账户，IP 替换为你的虚拟机 IP。
+将 `youruser` 替换为你创建的账户，IP 替换为你 VM 的 IP。

 ---

 ## 6) 安装 OpenClaw

-在虚拟机内：
+在 VM 内：

 ```bash
 npm install -g openclaw@latest
@@ -184,16 +184,16 @@ openclaw channels login

 ---

-## 8) 无界面运行虚拟机
+## 8) 无头运行 VM

-停止虚拟机并以无显示模式重启：
+停止 VM 并在无显示器模式下重启：

 ```bash
 lume stop openclaw
 lume run openclaw --no-display
 ```

-虚拟机将在后台运行。OpenClaw 的守护进程会保持 Gateway网关运行。
+VM 在后台运行。OpenClaw 的守护进程保持 Gateway 网关运行。

 检查状态：

@@ -203,16 +203,16 @@ ssh youruser@192.168.64.X "openclaw status"

 ---

-## 附加功能：iMessage 集成
+## 额外：iMessage 集成

 这是在 macOS 上运行的杀手级功能。使用 [BlueBubbles](https://bluebubbles.app) 将 iMessage 添加到 OpenClaw。

-在虚拟机内：
+在 VM 内：

 1. 从 bluebubbles.app 下载 BlueBubbles
-2. 使用你的 Apple ID 登录
+2. 用你的 Apple ID 登录
 3. 启用 Web API 并设置密码
-4. 将 BlueBubbles webhook 指向你的 Gateway网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）
+4. 将 BlueBubbles webhooks 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`）

 添加到你的 OpenClaw 配置：

@@ -228,7 +228,7 @@ ssh youruser@192.168.64.X "openclaw status"
 }
 ```

-重启 Gateway网关。现在你的智能体可以收发 iMessage 了。
+重启 Gateway 网关。现在你的智能体可以发送和接收 iMessage 了。

 完整设置详情：[BlueBubbles 渠道](/channels/bluebubbles)

@@ -236,7 +236,7 @@ ssh youruser@192.168.64.X "openclaw status"

 ## 保存黄金镜像

-在进一步自定义之前，快照保存你的干净状态：
+在进一步自定义之前，快照你的干净状态：

 ```bash
 lume stop openclaw
@@ -253,26 +253,26 @@ lume run openclaw --no-display

 ---

-## 全天候运行
+## 24/7 运行

-通过以下方式保持虚拟机运行：
+通过以下方式保持 VM 运行：

- 保持 Mac 接通电源
+- 保持你的 Mac 插电
 - 在系统设置 → 节能中禁用睡眠
- 如有需要使用 `caffeinate`
+- 如需要使用 `caffeinate`

-如需真正的始终在线，请考虑专用 Mac mini 或小型 VPS。参阅 [VPS 托管](/vps)。
+对于真正的永久在线，考虑专用 Mac mini 或小型 VPS。参见 [VPS 托管](/vps)。

 ---

 ## 故障排除

-| 问题                    | 解决方案                                                        |
-| ----------------------- | --------------------------------------------------------------- |
-| 无法 SSH 登录虚拟机     | 检查虚拟机系统设置中是否已启用"远程登录"                        |
-| 虚拟机 IP 未显示        | 等待虚拟机完全启动，再次运行 `lume get openclaw`                |
-| Lume 命令未找到         | 将 `~/.local/bin` 添加到你的 PATH                               |
-| WhatsApp 二维码无法扫描 | 确保运行 `openclaw channels login` 时登录的是虚拟机（非宿主机） |
+| 问题                    | 解决方案                                                         |
+| ----------------------- | ---------------------------------------------------------------- |
+| 无法 SSH 进入 VM        | 检查 VM 的系统设置中是否启用了"远程登录"                         |
+| VM IP 未显示            | 等待 VM 完全启动，再次运行 `lume get openclaw`                   |
+| 找不到 Lume 命令        | 将 `~/.local/bin` 添加到你的 PATH                                |
+| WhatsApp 二维码扫描失败 | 确保运行 `openclaw channels login` 时你是登录到 VM（而不是主机） |

 ---

@@ -280,9 +280,9 @@ lume run openclaw --no-display

 - [VPS 托管](/vps)
 - [节点](/nodes)
- [Gateway网关远程控制](/gateway/remote)
+- [Gateway 网关远程](/gateway/remote)
 - [BlueBubbles 渠道](/channels/bluebubbles)
 - [Lume 快速入门](https://cua.ai/docs/lume/guide/getting-started/quickstart)
 - [Lume CLI 参考](https://cua.ai/docs/lume/reference/cli-reference)
- [无人值守虚拟机设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
- [Docker 沙盒化](/install/docker)（替代隔离方案）
+- [无人值守 VM 设置](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup)（高级）
+- [Docker 沙箱隔离](/install/docker)（替代隔离方案）
@@ -1,11 +1,11 @@
 ---
 read_when:
  - 实现 macOS 应用功能
-  - 更改 macOS 上的 Gateway网关生命周期或节点桥接
-summary: OpenClaw macOS 伴侣应用（菜单栏 + Gateway网关代理）
+  - 在 macOS 上更改 Gateway 网关生命周期或节点桥接
+summary: OpenClaw macOS 配套应用（菜单栏 + Gateway 网关代理）
 title: macOS 应用
 x-i18n:
-  generated_at: "2026-02-01T21:33:53Z"
+  generated_at: "2026-02-03T07:53:14Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: a5b1c02e5905e4cbc6c0688149cdb50a5bf7653e641947143e169ad948d1f057
@@ -13,69 +13,68 @@ x-i18n:
  workflow: 15
 ---

-# OpenClaw macOS 伴侣应用（菜单栏 + Gateway网关代理）
+# OpenClaw macOS 配套应用（菜单栏 + Gateway 网关代理）

-macOS 应用是 OpenClaw 的**菜单栏伴侣**。它拥有权限，在本地管理/连接 Gateway网关（launchd 或手动），并将 macOS 能力作为节点暴露给智能体。
+macOS 应用是 OpenClaw 的**菜单栏配套应用**。它拥有权限，在本地管理/附加到 Gateway 网关（launchd 或手动），并作为节点向智能体暴露 macOS 功能。

-## 功能说明
+## 功能

- 在菜单栏显示原生通知和状态。
+- 在菜单栏中显示原生通知和状态。
 - 拥有 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）。
- 运行或连接到 Gateway网关（本地或远程）。
- 暴露 macOS 专有工具（画布、摄像头、屏幕录制、`system.run`）。
- 在**远程**模式下启动本地节点宿主服务（launchd），在**本地**模式下停止它。
- 可选托管 **PeekabooBridge** 用于 UI 自动化。
- 根据请求通过 npm/pnpm 安装全局 CLI（`openclaw`）（不建议将 bun 用于 Gateway网关运行时）。
+- 运行或连接到 Gateway 网关（本地或远程）。
+- 暴露 macOS 专用工具（Canvas、相机、屏幕录制、`system.run`）。
+- 在**远程**模式下启动本地节点主机服务（launchd），在**本地**模式下停止它。
+- 可选地托管 **PeekabooBridge** 用于 UI 自动化。
+- 根据请求通过 npm/pnpm 安装全局 CLI（`openclaw`）（不建议使用 bun 作为 Gateway 网关运行时）。

-## 本地模式与远程模式
+## 本地 vs 远程模式

- **本地**（默认）：如果存在正在运行的本地 Gateway网关，应用会连接到它；否则通过 `openclaw gateway install` 启用 launchd 服务。
- **远程**：应用通过 SSH/Tailscale 连接到 Gateway网关，不会启动本地进程。
-  应用会启动本地**节点宿主服务**，以便远程 Gateway网关可以访问这台 Mac。
-  应用不会将 Gateway网关作为子进程启动。
+- **本地**（默认）：如果存在运行中的本地 Gateway 网关，应用附加到它；否则通过 `openclaw gateway install` 启用 launchd 服务。
+- **远程**：应用通过 SSH/Tailscale 连接到 Gateway 网关，从不启动本地进程。
+  应用启动本地**节点主机服务**，以便远程 Gateway 网关可以访问此 Mac。
+  应用不会将 Gateway 网关作为子进程生成。

 ## Launchd 控制

-应用管理一个标签为 `bot.molt.gateway` 的用户级 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍会被卸载）。
+应用管理一个标记为 `bot.molt.gateway` 的每用户 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍会卸载）。

 ```bash
 launchctl kickstart -k gui/$UID/bot.molt.gateway
 launchctl bootout gui/$UID/bot.molt.gateway
 ```

-运行命名配置文件时，请将标签替换为 `bot.molt.<profile>`。
+运行命名配置文件时，将标签替换为 `bot.molt.<profile>`。

-如果 LaunchAgent 未安装，可从应用中启用或运行 `openclaw gateway install`。
+如果 LaunchAgent 未安装，从应用中启用它或运行 `openclaw gateway install`。

-## 节点能力（Mac）
+## 节点功能（mac）

 macOS 应用将自身呈现为一个节点。常用命令：

- 画布：`canvas.present`、`canvas.navigate`、`canvas.eval`、`canvas.snapshot`、`canvas.a2ui.*`
- 摄像头：`camera.snap`、`camera.clip`
+- Canvas：`canvas.present`、`canvas.navigate`、`canvas.eval`、`canvas.snapshot`、`canvas.a2ui.*`
+- 相机：`camera.snap`、`camera.clip`
 - 屏幕：`screen.record`
 - 系统：`system.run`、`system.notify`

-节点上报 `permissions` 映射表，以便智能体判断哪些操作被允许。
+节点报告一个 `permissions` 映射，以便智能体可以决定什么是允许的。

 节点服务 + 应用 IPC：

- 当无头节点宿主服务运行时（远程模式），它通过 WS 作为节点连接到 Gateway网关。
- `system.run` 在 macOS 应用（UI/TCC 上下文）中通过本地 Unix 套接字执行；提示和输出保留在应用内。
+- 当无头节点主机服务运行时（远程模式），它作为节点连接到 Gateway 网关 WS。
+- `system.run` 在 macOS 应用中执行（UI/TCC 上下文）通过本地 Unix 套接字；提示 + 输出保留在应用内。

-示意图（SCI）：
+图示（SCI）：

 ```
-Gateway网关 -> Node Service (WS)
+Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)
 ```

-## 执行审批（system.run）
+## Exec 审批（system.run）

-`system.run` 由 macOS 应用中的**执行审批**控制（设置 → 执行审批）。
-安全策略 + 询问方式 + 允许列表存储在 Mac 本地：
+`system.run` 由 macOS 应用中的 **Exec 审批**控制（设置 → Exec approvals）。安全 + 询问 + 允许列表本地存储在 Mac 上：

 ```
 ~/.openclaw/exec-approvals.json
@@ -103,16 +102,16 @@ Gateway网关 -> Node Service (WS)
 注意事项：

 - `allowlist` 条目是解析后二进制路径的 glob 模式。
- 在提示中选择"始终允许"会将该命令添加到允许列表中。
- `system.run` 环境变量覆盖会先过滤（移除 `PATH`、`DYLD_*`、`LD_*`、`NODE_OPTIONS`、`PYTHON*`、`PERL*`、`RUBYOPT`），然后与应用的环境变量合并。
+- 在提示中选择"Always Allow"会将该命令添加到允许列表。
+- `system.run` 环境覆盖会被过滤（删除 `PATH`、`DYLD_*`、`LD_*`、`NODE_OPTIONS`、`PYTHON*`、`PERL*`、`RUBYOPT`），然后与应用的环境合并。

 ## 深度链接

-应用注册 `openclaw://` URL 方案用于本地操作。
+应用为本地操作注册 `openclaw://` URL 方案。

 ### `openclaw://agent`

-触发 Gateway网关 `agent` 请求。
+触发 Gateway 网关 `agent` 请求。

 ```bash
 open 'openclaw://agent?message=Hello%20from%20deep%20link'
@@ -120,34 +119,34 @@ open 'openclaw://agent?message=Hello%20from%20deep%20link'

 查询参数：

- `message`（必填）
+- `message`（必需）
 - `sessionKey`（可选）
 - `thinking`（可选）
 - `deliver` / `to` / `channel`（可选）
 - `timeoutSeconds`（可选）
- `key`（可选，无人值守模式密钥）
+- `key`（可选无人值守模式密钥）

-安全性：
+安全：

- 不带 `key` 时，应用会提示确认。
- 带有有效 `key` 时，运行为无人值守模式（用于个人自动化）。
+- 没有 `key` 时，应用会提示确认。
+- 有有效的 `key` 时，运行是无人值守的（用于个人自动化）。

 ## 新手引导流程（典型）

 1. 安装并启动 **OpenClaw.app**。
 2. 完成权限清单（TCC 提示）。
-3. 确保**本地**模式已激活且 Gateway网关正在运行。
-4. 如需终端访问，安装 CLI。
+3. 确保**本地**模式处于活动状态且 Gateway 网关正在运行。
+4. 如果你想要终端访问，安装 CLI。

-## 构建与开发工作流（原生）
+## 构建和开发工作流程（原生）

 - `cd apps/macos && swift build`
 - `swift run OpenClaw`（或 Xcode）
 - 打包应用：`scripts/package-mac-app.sh`

-## 调试 Gateway网关连接（macOS CLI）
+## 调试 Gateway 网关连接（macOS CLI）

-使用调试 CLI 来执行与 macOS 应用相同的 Gateway网关 WebSocket 握手和发现逻辑，无需启动应用。
+使用调试 CLI 来执行与 macOS 应用使用的相同的 Gateway 网关 WebSocket 握手和发现逻辑，而无需启动应用。

 ```bash
 cd apps/macos
@@ -155,40 +154,40 @@ swift run openclaw-mac connect --json
 swift run openclaw-mac discover --timeout 3000 --json
 ```

-连接选项：
+Connect 选项：

 - `--url <ws://host:port>`：覆盖配置
- `--mode <local|remote>`：从配置中解析（默认：配置值或 local）
- `--probe`：强制执行新的健康探测
+- `--mode <local|remote>`：从配置解析（默认：配置或 local）
+- `--probe`：强制进行新的健康探测
 - `--timeout <ms>`：请求超时（默认：`15000`）
- `--json`：结构化输出，便于对比
+- `--json`：用于比较的结构化输出

-发现选项：
+Discovery 选项：

- `--include-local`：包含会被过滤为"本地"的 Gateway网关
- `--timeout <ms>`：总发现窗口时间（默认：`2000`）
- `--json`：结构化输出，便于对比
+- `--include-local`：包含会被过滤为"本地"的 Gateway 网关
+- `--timeout <ms>`：总体发现窗口（默认：`2000`）
+- `--json`：用于比较的结构化输出

-提示：与 `openclaw gateway discover --json` 对比，查看 macOS 应用的发现管道（NWBrowser + tailnet DNS-SD 回退）是否与 Node CLI 基于 `dns-sd` 的发现有差异。
+提示：与 `openclaw gateway discover --json` 比较，查看 macOS 应用的发现管道（NWBrowser + tailnet DNS-SD 回退）是否与 Node CLI 基于 `dns-sd` 的发现不同。

-## 远程连接机制（SSH 隧道）
+## 远程连接管道（SSH 隧道）

-当 macOS 应用在**远程**模式下运行时，它会打开 SSH 隧道，使本地 UI 组件可以像访问 localhost 一样与远程 Gateway网关通信。
+当 macOS 应用在**远程**模式下运行时，它会打开一个 SSH 隧道，以便本地 UI 组件可以像在 localhost 上一样与远程 Gateway 网关通信。

-### 控制隧道（Gateway网关 WebSocket 端口）
+### 控制隧道（Gateway 网关 WebSocket 端口）

- **用途：** 健康检查、状态、Web Chat、配置及其他控制平面调用。
- **本地端口：** Gateway网关端口（默认 `18789`），始终稳定。
- **远程端口：** 远程主机上的相同 Gateway网关端口。
- **行为：** 不使用随机本地端口；应用复用现有的健康隧道，或在需要时重启。
- **SSH 形式：** `ssh -N -L <local>:127.0.0.1:<remote>`，带 BatchMode + ExitOnForwardFailure + keepalive 选项。
- **IP 上报：** SSH 隧道使用 local loopback，因此 Gateway网关看到的节点 IP 为 `127.0.0.1`。如果需要显示真实客户端 IP，请使用 **Direct (ws/wss)** 传输方式（参阅 [macOS 远程访问](/platforms/mac/remote)）。
+- **目的：**健康检查、状态、Web Chat、配置和其他控制平面调用。
+- **本地端口：**Gateway 网关端口（默认 `18789`），始终稳定。
+- **远程端口：**远程主机上的相同 Gateway 网关端口。
+- **行为：**无随机本地端口；应用复用现有的健康隧道或在需要时重启它。
+- **SSH 形式：**`ssh -N -L <local>:127.0.0.1:<remote>`，带有 BatchMode + ExitOnForwardFailure + keepalive 选项。
+- **IP 报告：**SSH 隧道使用 loopback，因此 Gateway 网关将看到节点 IP 为 `127.0.0.1`。如果你想要显示真实的客户端 IP，请使用 **Direct (ws/wss)** 传输（参见 [macOS 远程访问](/platforms/mac/remote)）。

-有关设置步骤，请参阅 [macOS 远程访问](/platforms/mac/remote)。有关协议详情，请参阅 [Gateway网关协议](/gateway/protocol)。
+有关设置步骤，请参阅 [macOS 远程访问](/platforms/mac/remote)。有关协议详情，请参阅 [Gateway 网关协议](/gateway/protocol)。

 ## 相关文档

- [Gateway网关运行手册](/gateway)
- [Gateway网关（macOS）](/platforms/mac/bundled-gateway)
+- [Gateway 网关运维手册](/gateway)
+- [Gateway 网关（macOS）](/platforms/mac/bundled-gateway)
 - [macOS 权限](/platforms/mac/permissions)
- [画布](/platforms/mac/canvas)
+- [Canvas](/platforms/mac/canvas)
@@ -1,12 +1,12 @@
 ---
 read_when:
-  - 在 Oracle Cloud 上部署 OpenClaw
-  - 寻找低成本 VPS 托管方案来运行 OpenClaw
-  - 希望在小型服务器上全天候运行 OpenClaw
-summary: 在 Oracle Cloud（Always Free ARM）上运行 OpenClaw
+  - 在 Oracle Cloud 上设置 OpenClaw
+  - 寻找 OpenClaw 的低成本 VPS 托管
+  - 想要在小型服务器上 24/7 运行 OpenClaw
+summary: 在 Oracle Cloud 上运行 OpenClaw（Always Free ARM）
 title: Oracle Cloud
 x-i18n:
-  generated_at: "2026-02-01T21:34:35Z"
+  generated_at: "2026-02-03T07:53:25Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: d3cc337b40ea512b5756ac15ec4341fecad417ede75f717fea3035678c7c6697
@@ -14,56 +14,56 @@ x-i18n:
  workflow: 15
 ---

-# 在 Oracle Cloud (OCI) 上运行 OpenClaw
+# 在 Oracle Cloud（OCI）上运行 OpenClaw

 ## 目标

-在 Oracle Cloud 的 **Always Free** ARM 层级上运行持久化的 OpenClaw Gateway网关。
+在 Oracle Cloud 的 **Always Free** ARM 层上运行持久化的 OpenClaw Gateway 网关。

-Oracle 的免费层级非常适合运行 OpenClaw（特别是如果你已有 OCI 账户），但也存在一些权衡：
+Oracle 的免费层非常适合 OpenClaw（特别是如果你已经有 OCI 账户），但有一些权衡：

- ARM 架构（大多数东西都能运行，但某些二进制文件可能仅支持 x86）
- 容量和注册流程可能不太稳定
+- ARM 架构（大多数东西都能工作，但某些二进制文件可能仅支持 x86）
+- 容量和注册可能比较麻烦

-## 费用对比（2026）
+## 成本比较（2026）

-| 提供商       | 方案            | 配置                  | 月费用 | 备注               |
-| ------------ | --------------- | --------------------- | ------ | ------------------ |
-| Oracle Cloud | Always Free ARM | 最高 4 OCPU, 24GB RAM | $0     | ARM，容量有限      |
-| Hetzner      | CX22            | 2 vCPU, 4GB RAM       | ~ $4   | 最便宜的付费选项   |
-| DigitalOcean | Basic           | 1 vCPU, 1GB RAM       | $6     | 界面简洁，文档完善 |
-| Vultr        | Cloud Compute   | 1 vCPU, 1GB RAM       | $6     | 机房节点多         |
-| Linode       | Nanode          | 1 vCPU, 1GB RAM       | $5     | 现为 Akamai 旗下   |
+| 提供商       | 方案            | 配置                  | 价格/月 | 说明                 |
+| ------------ | --------------- | --------------------- | ------- | -------------------- |
+| Oracle Cloud | Always Free ARM | 最多 4 OCPU，24GB RAM | $0      | ARM，容量有限        |
+| Hetzner      | CX22            | 2 vCPU，4GB RAM       | ~ $4    | 最便宜的付费选项     |
+| DigitalOcean | Basic           | 1 vCPU，1GB RAM       | $6      | 易用的 UI，文档完善  |
+| Vultr        | Cloud Compute   | 1 vCPU，1GB RAM       | $6      | 多个地区             |
+| Linode       | Nanode          | 1 vCPU，1GB RAM       | $5      | 现为 Akamai 的一部分 |

 ---

-## 前提条件
+## 先决条件

- Oracle Cloud 账户（[注册](https://www.oracle.com/cloud/free/)）— 如果遇到问题请参阅[社区注册指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)
- Tailscale 账户（在 [tailscale.com](https://tailscale.com) 免费注册）
+- Oracle Cloud 账户（[注册](https://www.oracle.com/cloud/free/)）——如果遇到问题请参阅[社区注册指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)
+- Tailscale 账户（在 [tailscale.com](https://tailscale.com) 免费）
 - 约 30 分钟

 ## 1) 创建 OCI 实例

-1. 登录 [Oracle Cloud 控制台](https://cloud.oracle.com/)
-2. 导航至 **Compute → Instances → Create Instance**
+1. 登录 [Oracle Cloud Console](https://cloud.oracle.com/)
+2. 导航到 **Compute → Instances → Create Instance**
 3. 配置：
   - **Name:** `openclaw`
   - **Image:** Ubuntu 24.04 (aarch64)
-   - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
-   - **OCPUs:** 2（最高 4）
-   - **Memory:** 12 GB（最高 24 GB）
-   - **Boot volume:** 50 GB（免费额度最高 200 GB）
+   - **Shape:** `VM.Standard.A1.Flex`（Ampere ARM）
+   - **OCPUs:** 2（或最多 4）
+   - **Memory:** 12 GB（或最多 24 GB）
+   - **Boot volume:** 50 GB（最多 200 GB 免费）
   - **SSH key:** 添加你的公钥
 4. 点击 **Create**
-5. 记下公共 IP 地址
+5. 记录公网 IP 地址

-**提示：** 如果实例创建失败并提示 "Out of capacity"，请尝试其他可用性域或稍后重试。免费层级容量有限。
+**提示：** 如果实例创建失败并显示"Out of capacity"，尝试不同的可用性域或稍后重试。免费层容量有限。

 ## 2) 连接并更新

 ```bash
-# 通过公共 IP 连接
+# 通过公网 IP 连接
 ssh ubuntu@YOUR_PUBLIC_IP

 # 更新系统
@@ -71,7 +71,7 @@ sudo apt update && sudo apt upgrade -y
 sudo apt install -y build-essential
 ```

-**注意：** ARM 架构下编译某些依赖需要 `build-essential`。
+**注意：** `build-essential` 是某些依赖项 ARM 编译所必需的。

 ## 3) 配置用户和主机名

@@ -93,7 +93,7 @@ curl -fsSL https://tailscale.com/install.sh | sh
 sudo tailscale up --ssh --hostname=openclaw
 ```

-这将启用 Tailscale SSH，让你可以从 tailnet 上的任何设备通过 `ssh openclaw` 连接，无需公共 IP。
+这会启用 Tailscale SSH，所以你可以从 tailnet 上的任何设备通过 `ssh openclaw` 连接——不需要公网 IP。

 验证：

@@ -110,19 +110,19 @@ curl -fsSL https://openclaw.ai/install.sh | bash
 source ~/.bashrc
 ```

-当提示 "How do you want to hatch your bot?" 时，选择 **"Do this later"**。
+当提示"How do you want to hatch your bot?"时，选择 **"Do this later"**。

-> 注意：如果遇到 ARM 原生构建问题，请先安装系统包（例如 `sudo apt install -y build-essential`），再考虑使用 Homebrew。
+> 注意：如果你遇到 ARM 原生构建问题，在使用 Homebrew 之前先从系统包开始（例如 `sudo apt install -y build-essential`）。

-## 6) 配置 Gateway网关（local loopback 绑定 + 令牌认证）并启用 Tailscale Serve
+## 6) 配置 Gateway 网关（loopback + 令牌认证）并启用 Tailscale Serve

-默认使用令牌认证。这种方式可预测，且无需在控制 UI 中设置任何"不安全认证"标志。
+使用令牌认证作为默认值。它是可预测的，避免需要任何"不安全认证"的控制 UI 标志。

 ```bash
-# 将 Gateway网关限制在虚拟机本地
+# 在 VM 上保持 Gateway 网关私有
 openclaw config set gateway.bind loopback

-# 为 Gateway网关 + 控制 UI 启用认证
+# 要求 Gateway 网关 + 控制 UI 的认证
 openclaw config set gateway.auth.mode token
 openclaw doctor --generate-gateway-token

@@ -149,69 +149,69 @@ tailscale serve status
 curl http://localhost:18789
 ```

-## 8) 锁定 VCN 安全规则
+## 8) 锁定 VCN 安全

-一切正常运行后，锁定 VCN 以阻止除 Tailscale 外的所有流量。OCI 的虚拟云网络在网络边缘充当防火墙——流量在到达实例之前就被拦截。
+现在一切正常工作了，锁定 VCN 以阻止除 Tailscale 之外的所有流量。OCI 的虚拟云网络充当网络边缘的防火墙——流量在到达你的实例之前就被阻止。

-1. 在 OCI 控制台中进入 **Networking → Virtual Cloud Networks**
+1. 在 OCI Console 中转到 **Networking → Virtual Cloud Networks**
 2. 点击你的 VCN → **Security Lists** → Default Security List
-3. **删除**所有入站规则，仅保留：
+3. **移除**除以下之外的所有入站规则：
   - `0.0.0.0/0 UDP 41641`（Tailscale）
-4. 保留默认出站规则（允许所有出站流量）
+4. 保留默认出站规则（允许所有出站）

-这将在网络边缘阻止 22 端口 SSH、HTTP、HTTPS 及其他所有流量。从此以后，你只能通过 Tailscale 连接。
+这会在网络边缘阻止端口 22 上的 SSH、HTTP、HTTPS 和其他所有内容。从现在开始，你只能通过 Tailscale 连接。

 ---

 ## 访问控制 UI

-从 Tailscale 网络上的任意设备访问：
+从你 Tailscale 网络上的任何设备：

 ```
 https://openclaw.<tailnet-name>.ts.net/
 ```

-将 `<tailnet-name>` 替换为你的 tailnet 名称（可在 `tailscale status` 中查看）。
+将 `<tailnet-name>` 替换为你的 tailnet 名称（在 `tailscale status` 中可见）。

-无需 SSH 隧道。Tailscale 提供：
+不需要 SSH 隧道。Tailscale 提供：

 - HTTPS 加密（自动证书）
- 通过 Tailscale 身份进行认证
- 从 tailnet 上的任何设备访问（笔记本电脑、手机等）
+- 通过 Tailscale 身份认证
+- 从 tailnet 上的任何设备（笔记本电脑、手机等）访问

 ---

-## 安全性：VCN + Tailscale（推荐基线）
+## 安全：VCN + Tailscale（推荐基线）

-锁定 VCN（仅开放 UDP 41641）并将 Gateway网关绑定到 local loopback 后，你将获得强大的纵深防御：公共流量在网络边缘被阻止，管理访问通过 tailnet 进行。
+通过锁定 VCN（仅开放 UDP 41641）并将 Gateway 网关绑定到 loopback，你获得了强大的纵深防御：公共流量在网络边缘被阻止，管理访问通过你的 tailnet 进行。

-这种配置通常不再*需要*额外的主机防火墙规则来阻止全网 SSH 暴力破解——但你仍应保持操作系统更新、运行 `openclaw security audit`，并确认没有意外监听公共接口。
+此设置通常消除了纯粹为了阻止互联网范围的 SSH 暴力破解而需要额外的基于主机的防火墙规则的*需求*——但你仍应保持操作系统更新，运行 `openclaw security audit`，并验证你没有意外地在公共接口上监听。

-### 已受保护的内容
+### 已经受保护的内容

-| 传统步骤        | 是否需要？ | 原因                                               |
-| --------------- | ---------- | -------------------------------------------------- |
-| UFW 防火墙      | 否         | VCN 在流量到达实例之前就已拦截                     |
-| fail2ban        | 否         | VCN 阻止了 22 端口，不存在暴力破解                 |
-| sshd 加固       | 否         | Tailscale SSH 不使用 sshd                          |
-| 禁用 root 登录  | 否         | Tailscale 使用 Tailscale 身份认证，而非系统用户    |
-| 仅密钥 SSH 认证 | 否         | Tailscale 通过 tailnet 进行认证                    |
-| IPv6 加固       | 通常不需要 | 取决于你的 VCN/子网设置；请验证实际分配/暴露的内容 |
+| 传统步骤        | 是否需要？ | 原因                                             |
+| --------------- | ---------- | ------------------------------------------------ |
+| UFW 防火墙      | 否         | VCN 在流量到达实例之前就阻止了                   |
+| fail2ban        | 否         | 如果端口 22 在 VCN 被阻止则无暴力破解            |
+| sshd 加固       | 否         | Tailscale SSH 不使用 sshd                        |
+| 禁用 root 登录  | 否         | Tailscale 使用 Tailscale 身份，而不是系统用户    |
+| 仅 SSH 密钥认证 | 否         | Tailscale 通过你的 tailnet 认证                  |
+| IPv6 加固       | 通常不需要 | 取决于你的 VCN/子网设置；验证实际分配/暴露的内容 |

-### 仍然建议执行
+### 仍然推荐

- **凭据权限：** `chmod 700 ~/.openclaw`
+- **凭证权限：** `chmod 700 ~/.openclaw`
 - **安全审计：** `openclaw security audit`
- **系统更新：** 定期运行 `sudo apt update && sudo apt upgrade`
- **监控 Tailscale：** 在 [Tailscale 管理控制台](https://login.tailscale.com/admin) 中检查设备
+- **系统更新：** 定期 `sudo apt update && sudo apt upgrade`
+- **监控 Tailscale：** 在 [Tailscale 管理控制台](https://login.tailscale.com/admin) 中查看设备

-### 验证安全状态
+### 验证安全态势

 ```bash
 # 确认没有公共端口在监听
 sudo ss -tlnp | grep -v '127.0.0.1\|::1'

-# 验证 Tailscale SSH 是否激活
+# 验证 Tailscale SSH 处于活动状态
 tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active"

 # 可选：完全禁用 sshd
@@ -220,12 +220,12 @@ sudo systemctl disable --now ssh

 ---

-## 备选方案：SSH 隧道
+## 备用方案：SSH 隧道

-如果 Tailscale Serve 无法正常工作，可使用 SSH 隧道：
+如果 Tailscale Serve 不工作，使用 SSH 隧道：

 ```bash
-# 从本地机器（通过 Tailscale）
+# 从你的本地机器（通过 Tailscale）
 ssh -L 18789:127.0.0.1:18789 ubuntu@openclaw
 ```

@@ -237,11 +237,11 @@ ssh -L 18789:127.0.0.1:18789 ubuntu@openclaw

 ### 实例创建失败（"Out of capacity"）

-免费层级 ARM 实例非常热门。请尝试：
+免费层 ARM 实例很受欢迎。尝试：

- 切换不同的可用性域
- 在非高峰时段重试（清晨）
- 选择配置时使用 "Always Free" 筛选器
+- 不同的可用性域
+- 在非高峰时段（清晨）重试
+- 选择 shape 时使用"Always Free"过滤器

 ### Tailscale 无法连接

@@ -253,7 +253,7 @@ sudo tailscale status
 sudo tailscale up --ssh --hostname=openclaw --reset
 ```

-### Gateway网关无法启动
+### Gateway 网关无法启动

 ```bash
 openclaw gateway status
@@ -264,33 +264,33 @@ journalctl --user -u openclaw-gateway -n 50
 ### 无法访问控制 UI

 ```bash
-# 验证 Tailscale Serve 是否在运行
+# 验证 Tailscale Serve 正在运行
 tailscale serve status

-# 检查 Gateway网关是否在监听
+# 检查 Gateway 网关是否在监听
 curl http://localhost:18789

-# 需要时重启
+# 如需要则重启
 systemctl --user restart openclaw-gateway
 ```

 ### ARM 二进制文件问题

-某些工具可能没有 ARM 构建版本。检查：
+某些工具可能没有 ARM 构建。检查：

 ```bash
-uname -m  # 应显示 aarch64
+uname -m  # 应该显示 aarch64
 ```

-大多数 npm 包都能正常工作。对于二进制文件，请查找 `linux-arm64` 或 `aarch64` 版本。
+大多数 npm 包工作正常。对于二进制文件，寻找 `linux-arm64` 或 `aarch64` 版本。

 ---

 ## 持久化

-所有状态保存在：
+所有状态存储在：

- `~/.openclaw/` — 配置、凭据、会话数据
+- `~/.openclaw/` — 配置、凭证、会话数据
 - `~/.openclaw/workspace/` — 工作区（SOUL.md、记忆、产物）

 定期备份：
@@ -303,8 +303,8 @@ tar -czvf openclaw-backup.tar.gz ~/.openclaw ~/.openclaw/workspace

 ## 另请参阅

- [Gateway网关远程访问](/gateway/remote) — 其他远程访问模式
- [Tailscale 集成](/gateway/tailscale) — 完整 Tailscale 文档
- [Gateway网关配置](/gateway/configuration) — 所有配置选项
- [DigitalOcean 指南](/platforms/digitalocean) — 付费但注册更简单的选择
+- [Gateway 网关远程访问](/gateway/remote) — 其他远程访问模式
+- [Tailscale 集成](/gateway/tailscale) — 完整的 Tailscale 文档
+- [Gateway 网关配置](/gateway/configuration) — 所有配置选项
+- [DigitalOcean 指南](/platforms/digitalocean) — 如果你想要付费 + 更容易注册
 - [Hetzner 指南](/platforms/hetzner) — 基于 Docker 的替代方案
@@ -1,12 +1,12 @@
 ---
 read_when:
-  - 在 Raspberry Pi 上设置 OpenClaw
-  - 在 ARM 设备上运行 OpenClaw
-  - 搭建低成本的全天候个人 AI
-summary: 在 Raspberry Pi 上运行 OpenClaw（低成本自托管方案）
+  - 在 Raspberry Pi 上设置 OpenClaw 时
+  - 在 ARM 设备上运行 OpenClaw 时
+  - 构建低成本常驻个人 AI 时
+summary: 在 Raspberry Pi 上运行 OpenClaw（低成本自托管设置）
 title: Raspberry Pi
 x-i18n:
-  generated_at: "2026-02-01T21:34:34Z"
+  generated_at: "2026-02-03T07:53:30Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 6741eaf0115a4fa0efd6599a99e0526a20ceb30eda1d9b04cba9dd5dec84bee2
@@ -18,39 +18,39 @@ x-i18n:

 ## 目标

-在 Raspberry Pi 上运行一个持久的、全天候在线的 OpenClaw Gateway网关，**一次性费用约 $35-80**（无月费）。
+在 Raspberry Pi 上运行持久、常驻的 OpenClaw Gateway 网关，**一次性成本约 $35-80**（无月费）。

-适用场景：
+适用于：

 - 24/7 个人 AI 助手
- 家庭自动化中枢
+- 家庭自动化中心
 - 低功耗、随时可用的 Telegram/WhatsApp 机器人

 ## 硬件要求

-| Pi 型号         | 内存    | 可用？  | 备注                           |
-| --------------- | ------- | ------- | ------------------------------ |
-| **Pi 5**        | 4GB/8GB | ✅ 最佳 | 速度最快，推荐                 |
-| **Pi 4**        | 4GB     | ✅ 良好 | 大多数用户的最佳性价比         |
-| **Pi 4**        | 2GB     | ✅ 可用 | 可运行，需添加交换空间         |
-| **Pi 4**        | 1GB     | ⚠️ 紧张 | 需交换空间和最小化配置才可运行 |
-| **Pi 3B+**      | 1GB     | ⚠️ 缓慢 | 可运行但较卡顿                 |
-| **Pi Zero 2 W** | 512MB   | ❌      | 不推荐                         |
+| Pi 型号         | 内存    | 是否可用？ | 说明                       |
+| --------------- | ------- | ---------- | -------------------------- |
+| **Pi 5**        | 4GB/8GB | ✅ 最佳    | 最快，推荐                 |
+| **Pi 4**        | 4GB     | ✅ 良好    | 大多数用户的最佳选择       |
+| **Pi 4**        | 2GB     | ✅ 可以    | 可用，添加交换空间         |
+| **Pi 4**        | 1GB     | ⚠️ 紧张    | 使用交换空间可行，最小配置 |
+| **Pi 3B+**      | 1GB     | ⚠️ 慢      | 可用但较慢                 |
+| **Pi Zero 2 W** | 512MB   | ❌         | 不推荐                     |

-**最低配置：** 1GB 内存，1 核，500MB 磁盘空间
-**推荐配置：** 2GB+ 内存，64 位系统，16GB+ SD 卡（或 USB SSD）
+**最低配置：** 1GB 内存，1 核，500MB 磁盘  
+**推荐：** 2GB+ 内存，64 位系统，16GB+ SD 卡（或 USB SSD）

 ## 你需要准备

- Raspberry Pi 4 或 5（推荐 2GB+ 内存）
+- Raspberry Pi 4 或 5（推荐 2GB+）
 - MicroSD 卡（16GB+）或 USB SSD（性能更好）
- 电源适配器（推荐官方 Pi 电源）
+- 电源（推荐官方 Pi 电源）
 - 网络连接（以太网或 WiFi）
- 约 30 分钟时间
+- 约 30 分钟

 ## 1) 刷写系统

-使用 **Raspberry Pi OS Lite (64-bit)** — 无桌面的无头服务器无需桌面环境。
+使用 **Raspberry Pi OS Lite (64-bit)** — 无头服务器不需要桌面。

 1. 下载 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
 2. 选择系统：**Raspberry Pi OS Lite (64-bit)**
@@ -59,7 +59,7 @@ x-i18n:
   - 启用 SSH
   - 设置用户名/密码
   - 配置 WiFi（如果不使用以太网）
-4. 刷写到 SD 卡 / USB 驱动器
+4. 刷写到你的 SD 卡 / USB 驱动器
 5. 插入并启动 Pi

 ## 2) 通过 SSH 连接
@@ -79,11 +79,11 @@ sudo apt update && sudo apt upgrade -y
 # 安装必要软件包
 sudo apt install -y git curl build-essential

-# 设置时区（对定时任务/提醒很重要）
-sudo timedatectl set-timezone America/Chicago  # 改为你的时区
+# 设置时区（对 cron/提醒很重要）
+sudo timedatectl set-timezone America/Chicago  # 改成你的时区
 ```

-## 4) 安装 Node.js 22 (ARM64)
+## 4) 安装 Node.js 22（ARM64）

 ```bash
 # 通过 NodeSource 安装 Node.js
@@ -95,9 +95,9 @@ node --version  # 应显示 v22.x.x
 npm --version
 ```

-## 5) 添加交换空间（2GB 及以下内存必做）
+## 5) 添加交换空间（2GB 或更少内存时很重要）

-交换空间可防止内存不足导致的崩溃：
+交换空间可防止内存不足崩溃：

 ```bash
 # 创建 2GB 交换文件
@@ -106,23 +106,23 @@ sudo chmod 600 /swapfile
 sudo mkswap /swapfile
 sudo swapon /swapfile

-# 设为永久生效
+# 永久生效
 echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

-# 针对低内存优化（降低 swappiness）
+# 优化低内存（降低 swappiness）
 echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
 sudo sysctl -p
 ```

 ## 6) 安装 OpenClaw

-### 方案 A：标准安装（推荐）
+### 选项 A：标准安装（推荐）

 ```bash
 curl -fsSL https://openclaw.ai/install.sh | bash
 ```

-### 方案 B：可修改安装（适合折腾）
+### 选项 B：可修改安装（用于调试）

 ```bash
 git clone https://github.com/openclaw/openclaw.git
@@ -142,8 +142,8 @@ openclaw onboard --install-daemon

 按照向导操作：

-1. **Gateway网关模式：** 本地
-2. **认证：** 推荐使用 API 密钥（OAuth 在无头 Pi 上可能不太稳定）
+1. **Gateway 网关模式：** Local
+2. **认证：** 推荐 API 密钥（OAuth 在无头 Pi 上可能不稳定）
 3. **渠道：** Telegram 最容易上手
 4. **守护进程：** 是（systemd）

@@ -160,19 +160,19 @@ sudo systemctl status openclaw
 journalctl -u openclaw -f
 ```

-## 9) 访问仪表盘
+## 9) 访问仪表板

-由于 Pi 是无头模式，使用 SSH 隧道：
+由于 Pi 是无头的，使用 SSH 隧道：

 ```bash
-# 从你的笔记本/台式机
+# 从你的笔记本电脑/台式机
 ssh -L 18789:localhost:18789 user@gateway-host

 # 然后在浏览器中打开
 open http://localhost:18789
 ```

-或使用 Tailscale 实现全天候访问：
+或使用 Tailscale 实现常驻访问：

 ```bash
 # 在 Pi 上
@@ -188,24 +188,24 @@ sudo systemctl restart openclaw

 ## 性能优化

-### 使用 USB SSD（显著提升）
+### 使用 USB SSD（巨大改进）

-SD 卡速度慢且易损耗。USB SSD 能大幅提升性能：
+SD 卡速度慢且会磨损。USB SSD 可大幅提升性能：

 ```bash
 # 检查是否从 USB 启动
 lsblk
 ```

-设置方法请参阅 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。
+设置请参见 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。

-### 减少内存占用
+### 减少内存使用

 ```bash
 # 禁用 GPU 内存分配（无头模式）
 echo 'gpu_mem=16' | sudo tee -a /boot/config.txt

-# 如不需要蓝牙则禁用
+# 如不需要则禁用蓝牙
 sudo systemctl disable bluetooth
 ```

@@ -228,32 +228,32 @@ htop

 ### 二进制兼容性

-大多数 OpenClaw 功能在 ARM64 上正常工作，但部分外部二进制文件可能需要 ARM 构建版本：
+大多数 OpenClaw 功能在 ARM64 上可用，但某些外部二进制文件可能需要 ARM 构建：

-| 工具               | ARM64 状态 | 备注                                |
+| 工具               | ARM64 状态 | 说明                                |
 | ------------------ | ---------- | ----------------------------------- |
 | Node.js            | ✅         | 运行良好                            |
 | WhatsApp (Baileys) | ✅         | 纯 JS，无问题                       |
 | Telegram           | ✅         | 纯 JS，无问题                       |
-| gog (Gmail CLI)    | ⚠️         | 请检查是否有 ARM 版本               |
+| gog (Gmail CLI)    | ⚠️         | 检查是否有 ARM 版本                 |
 | Chromium (browser) | ✅         | `sudo apt install chromium-browser` |

-如果某个 Skills 运行失败，请检查其二进制文件是否有 ARM 构建版本。大多数 Go/Rust 工具有；部分没有。
+如果某个 skill 失败，检查其二进制文件是否有 ARM 构建。许多 Go/Rust 工具有；有些没有。

 ### 32 位 vs 64 位

-**务必使用 64 位系统。** Node.js 和许多现代工具都需要 64 位。检查方法：
+**始终使用 64 位系统。** Node.js 和许多现代工具需要它。使用以下命令检查：

 ```bash
 uname -m
-# 应显示：aarch64（64 位）而非 armv7l（32 位）
+# 应显示：aarch64（64 位）而不是 armv7l（32 位）
 ```

 ---

-## 推荐模型配置
+## 推荐的模型设置

-由于 Pi 只是 Gateway网关（模型在云端运行），请使用基于 API 的模型：
+由于 Pi 只是 Gateway 网关（模型在云端运行），使用基于 API 的模型：

 ```json
 {
@@ -268,19 +268,19 @@ uname -m
 }
 ```

-**不要尝试在 Pi 上运行本地大语言模型** — 即使是小模型也太慢。让 Claude/GPT 来完成繁重的工作。
+**不要尝试在 Pi 上运行本地 LLM** — 即使是小模型也太慢了。让 Claude/GPT 来做繁重的工作。

 ---

-## 开机自启动
+## 开机自启

-新手引导向导会自动设置，但可以验证一下：
+新手引导向导会设置这个，但要验证：

 ```bash
 # 检查服务是否已启用
 sudo systemctl is-enabled openclaw

-# 如未启用则启用
+# 如果没有则启用
 sudo systemctl enable openclaw

 # 开机启动
@@ -291,19 +291,19 @@ sudo systemctl start openclaw

 ## 故障排除

-### 内存不足 (OOM)
+### 内存不足（OOM）

 ```bash
 # 检查内存
 free -h

-# 添加更多交换空间（参见步骤 5）
+# 添加更多交换空间（见步骤 5）
 # 或减少 Pi 上运行的服务
 ```

-### 性能缓慢
+### 性能慢

- 使用 USB SSD 替代 SD 卡
+- 使用 USB SSD 代替 SD 卡
 - 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon`
 - 检查 CPU 降频：`vcgencmd get_throttled`（应返回 `0x0`）

@@ -313,7 +313,7 @@ free -h
 # 检查日志
 journalctl -u openclaw --no-pager -n 100

-# 常见修复方法：重新构建
+# 常见修复：重新构建
 cd ~/openclaw  # 如果使用可修改安装
 npm run build
 sudo systemctl restart openclaw
@@ -321,13 +321,13 @@ sudo systemctl restart openclaw

 ### ARM 二进制问题

-如果某个 Skills 报错 "exec format error"：
+如果某个 skill 失败并显示"exec format error"：

-1. 检查该二进制文件是否有 ARM64 构建版本
-2. 尝试从源码编译
+1. 检查该二进制文件是否有 ARM64 构建
+2. 尝试从源代码构建
 3. 或使用支持 ARM 的 Docker 容器

-### WiFi 断连
+### WiFi 断开

 对于使用 WiFi 的无头 Pi：

@@ -335,7 +335,7 @@ sudo systemctl restart openclaw
 # 禁用 WiFi 电源管理
 sudo iwconfig wlan0 power off

-# 设为永久生效
+# 永久生效
 echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
 ```

@@ -343,7 +343,7 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces

 ## 成本对比

-| 方案           | 一次性费用 | 月费     | 备注               |
+| 设置           | 一次性成本 | 月费     | 说明               |
 | -------------- | ---------- | -------- | ------------------ |
 | **Pi 4 (2GB)** | ~$45       | $0       | + 电费（约 $5/年） |
 | **Pi 4 (4GB)** | ~$55       | $0       | 推荐               |
@@ -352,14 +352,14 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
 | DigitalOcean   | $0         | $6/月    | $72/年             |
 | Hetzner        | $0         | €3.79/月 | 约 $50/年          |

-**回本周期：** 与云 VPS 相比，Pi 约 6-12 个月即可回本。
+**回本期：** 与云 VPS 相比，Pi 约 6-12 个月内回本。

 ---

 ## 另请参阅

 - [Linux 指南](/platforms/linux) — 通用 Linux 设置
- [DigitalOcean 指南](/platforms/digitalocean) — 云端替代方案
+- [DigitalOcean 指南](/platforms/digitalocean) — 云替代方案
 - [Hetzner 指南](/platforms/hetzner) — Docker 设置
 - [Tailscale](/gateway/tailscale) — 远程访问
- [节点](/nodes) — 将你的笔记本/手机与 Pi Gateway网关配对
+- [节点](/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对
@@ -1,11 +1,11 @@
 ---
 read_when:
  - 在 Windows 上安装 OpenClaw
-  - 了解 Windows 伴侣应用的状态
-summary: Windows (WSL2) 支持 + 伴侣应用状态
+  - 查找 Windows 配套应用状态
+summary: Windows（WSL2）支持 + 配套应用状态
 title: Windows (WSL2)
 x-i18n:
-  generated_at: "2026-02-01T21:34:13Z"
+  generated_at: "2026-02-03T07:53:19Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: c93d2263b4e5b60cb6fbe9adcb1a0ca95b70cd6feb6e63cfc4459cb18b229da0
@@ -15,22 +15,22 @@ x-i18n:

 # Windows (WSL2)

-推荐**通过 WSL2** 在 Windows 上使用 OpenClaw（建议使用 Ubuntu）。CLI + Gateway网关在 Linux 内运行，这样可以保持运行时一致性，并使工具链兼容性更好（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生 Windows 可能会更麻烦。WSL2 为你提供完整的 Linux 体验——一条命令即可安装：`wsl --install`。
+Windows 上的 OpenClaw 推荐**通过 WSL2**（推荐 Ubuntu）。CLI + Gateway 网关在 Linux 内运行，这保持了运行时的一致性并使工具兼容性大大提高（Node/Bun/pnpm、Linux 二进制文件、Skills）。原生 Windows 可能更棘手。WSL2 给你完整的 Linux 体验——一条命令安装：`wsl --install`。

-原生 Windows 伴侣应用已在计划中。
+原生 Windows 配套应用已在计划中。

 ## 安装（WSL2）

- [快速开始](/start/getting-started)（在 WSL 内使用）
- [安装与更新](/install/updating)
+- [入门指南](/start/getting-started)（在 WSL 内使用）
+- [安装和更新](/install/updating)
 - 官方 WSL2 指南（Microsoft）：https://learn.microsoft.com/windows/wsl/install

-## Gateway网关
+## Gateway 网关

- [Gateway网关运行手册](/gateway)
+- [Gateway 网关操作手册](/gateway)
 - [配置](/gateway/configuration)

-## Gateway网关服务安装（CLI）
+## Gateway 网关服务安装（CLI）

 在 WSL2 内：

@@ -50,7 +50,7 @@ openclaw gateway install
 openclaw configure
 ```

-出现提示时选择 **Gateway网关服务**。
+出现提示时选择 **Gateway service**。

 修复/迁移：

@@ -58,9 +58,9 @@ openclaw configure
 openclaw doctor
 ```

-## 进阶：通过局域网暴露 WSL 服务（portproxy）
+## 高级：通过 LAN 暴露 WSL 服务（portproxy）

-WSL 拥有自己的虚拟网络。如果另一台机器需要访问 **WSL 内部** 运行的服务（SSH、本地 TTS 服务器或 Gateway网关），你必须将 Windows 端口转发到当前 WSL IP。WSL IP 在重启后会改变，因此你可能需要刷新转发规则。
+WSL 有自己的虚拟网络。如果另一台机器需要访问**在 WSL 内**运行的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须将 Windows 端口转发到当前的 WSL IP。WSL IP 在重启后会改变，因此你可能需要刷新转发规则。

 示例（以**管理员身份**运行 PowerShell）：

@@ -76,14 +76,14 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor
  connectaddress=$WslIp connectport=$TargetPort
 ```

-通过 Windows 防火墙放行端口（一次性操作）：
+允许端口通过 Windows 防火墙（一次性）：

 ```powershell
 New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
  -Protocol TCP -LocalPort $ListenPort -Action Allow
 ```

-WSL 重启后刷新 portproxy：
+在 WSL 重启后刷新 portproxy：

 ```powershell
 netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
@@ -93,27 +93,27 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.

 注意事项：

- 从另一台机器通过 SSH 连接时，目标是 **Windows 主机 IP**（例如：`ssh user@windows-host -p 2222`）。
- 远程节点必须指向一个**可达的** Gateway网关 URL（而非 `127.0.0.1`）；使用 `openclaw status --all` 来确认。
- 使用 `listenaddress=0.0.0.0` 进行局域网访问；`127.0.0.1` 仅限本地访问。
- 如果你希望自动执行，可以注册一个计划任务，在登录时运行刷新步骤。
+- 从另一台机器 SSH 目标是 **Windows 主机 IP**（示例：`ssh user@windows-host -p 2222`）。
+- 远程节点必须指向**可访问的** Gateway 网关 URL（不是 `127.0.0.1`）；使用 `openclaw status --all` 确认。
+- 使用 `listenaddress=0.0.0.0` 进行 LAN 访问；`127.0.0.1` 仅保持本地访问。
+- 如果你想自动化，注册一个计划任务在登录时运行刷新步骤。

-## 分步 WSL2 安装指南
+## WSL2 分步安装

-### 1) 安装 WSL2 + Ubuntu
+### 1）安装 WSL2 + Ubuntu

 打开 PowerShell（管理员）：

 ```powershell
 wsl --install
-# 或明确选择一个发行版：
+# Or pick a distro explicitly:
 wsl --list --online
 wsl --install -d Ubuntu-24.04
 ```

-如果 Windows 提示，请重启。
+如果 Windows 要求则重启。

-### 2) 启用 systemd（Gateway网关安装所需）
+### 2）启用 systemd（Gateway 网关安装所需）

 在你的 WSL 终端中：

@@ -124,7 +124,7 @@ systemd=true
 EOF
 ```

-然后在 PowerShell 中：
+然后从 PowerShell：

 ```powershell
 wsl --shutdown
@@ -136,21 +136,21 @@ wsl --shutdown
 systemctl --user status
 ```

-### 3) 安装 OpenClaw（在 WSL 内）
+### 3）安装 OpenClaw（在 WSL 内）

-在 WSL 内按照 Linux 快速开始流程操作：
+在 WSL 内按照 Linux 入门指南流程：

 ```bash
 git clone https://github.com/openclaw/openclaw.git
 cd openclaw
 pnpm install
-pnpm ui:build # 首次运行时自动安装 UI 依赖
+pnpm ui:build # auto-installs UI deps on first run
 pnpm build
 openclaw onboard
 ```

-完整指南：[快速开始](/start/getting-started)
+完整指南：[入门指南](/start/getting-started)

-## Windows 伴侣应用
+## Windows 配套应用

-我们目前还没有 Windows 伴侣应用。如果你希望推动此功能的实现，欢迎贡献代码。
+我们还没有 Windows 配套应用。如果你想让它实现，欢迎贡献。