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,22 +1,22 @@
 ---
 read_when:
-  - 你需要通过安全加固进行自动化服务器部署
+  - 你想要带安全加固的自动化服务器部署
  - 你需要带 VPN 访问的防火墙隔离设置
-  - 你要部署到远程 Debian/Ubuntu 服务器
-summary: 使用 Ansible、Tailscale VPN 和防火墙隔离进行自动化、安全加固的 OpenClaw 安装
+  - 你正在部署到远程 Debian/Ubuntu 服务器
+summary: 使用 Ansible、Tailscale VPN 和防火墙隔离进行自动化、加固的 OpenClaw 安装
 title: Ansible
 x-i18n:
-  generated_at: "2026-02-01T21:05:32Z"
+  generated_at: "2026-02-03T07:49:29Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 896807f344d923f09039f377c13b4bf4a824aa94eec35159fc169596a3493b29
  source_path: install/ansible.md
-  workflow: 14
+  workflow: 15
 ---

 # Ansible 安装

-将 OpenClaw 部署到生产服务器的推荐方式是使用 **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — 一个采用安全优先架构的自动化安装工具。
+将 OpenClaw 部署到生产服务器的推荐方式是通过 **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — 一个安全优先架构的自动化安装程序。

 ## 快速开始

@@ -28,36 +28,36 @@ curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/inst

 > **📦 完整指南：[github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**
 >
-> openclaw-ansible 仓库是 Ansible 部署的权威来源。本页面仅为简要概览。
+> openclaw-ansible 仓库是 Ansible 部署的权威来源。本页是快速概述。

 ## 你将获得

- 🔒 **防火墙优先的安全策略**：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
- 🔐 **Tailscale VPN**：安全的远程访问，无需公开暴露服务
+- 🔒 **防火墙优先安全**：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
+- 🔐 **Tailscale VPN**：安全远程访问，无需公开暴露服务
 - 🐳 **Docker**：隔离的沙箱容器，仅绑定 localhost
 - 🛡️ **纵深防御**：4 层安全架构
- 🚀 **一条命令部署**：几分钟内完成完整部署
- 🔧 **Systemd 集成**：开机自启并带有安全加固
+- 🚀 **一条命令设置**：几分钟内完成部署
+- 🔧 **Systemd 集成**：带加固的开机自启动

-## 前置要求
+## 要求

 - **操作系统**：Debian 11+ 或 Ubuntu 20.04+
 - **访问权限**：Root 或 sudo 权限
- **网络**：用于安装软件包的互联网连接
- **Ansible**：2.14+（快速启动脚本会自动安装）
+- **网络**：用于包安装的互联网连接
+- **Ansible**：2.14+（由快速启动脚本自动安装）

 ## 安装内容

-Ansible playbook 会安装并配置以下组件：
+Ansible playbook 安装并配置：

 1. **Tailscale**（用于安全远程访问的 mesh VPN）
-2. **UFW 防火墙**（仅开放 SSH + Tailscale 端口）
+2. **UFW 防火墙**（仅允许 SSH + Tailscale 端口）
 3. **Docker CE + Compose V2**（用于智能体沙箱）
 4. **Node.js 22.x + pnpm**（运行时依赖）
-5. **OpenClaw**（基于主机安装，非容器化）
+5. **OpenClaw**（基于主机，非容器化）
 6. **Systemd 服务**（带安全加固的自动启动）

-注意：Gateway网关 **直接运行在主机上**（不在 Docker 中），但智能体沙箱使用 Docker 进行隔离。详见 [沙箱](/gateway/sandboxing)。
+注意：Gateway 网关**直接在主机上运行**（不在 Docker 中），但智能体沙箱使用 Docker 进行隔离。详情参见[沙箱隔离](/gateway/sandboxing)。

 ## 安装后设置

@@ -71,8 +71,8 @@ sudo -i -u openclaw

 1. **新手引导向导**：配置 OpenClaw 设置
 2. **提供商登录**：连接 WhatsApp/Telegram/Discord/Signal
-3. **Gateway网关测试**：验证安装
-4. **Tailscale 设置**：连接到你的 VPN mesh 网络
+3. **Gateway 网关测试**：验证安装
+4. **Tailscale 设置**：连接到你的 VPN mesh

 ### 常用命令

@@ -83,7 +83,7 @@ sudo systemctl status openclaw
 # 查看实时日志
 sudo journalctl -u openclaw -f

-# 重启 Gateway网关
+# 重启 Gateway 网关
 sudo systemctl restart openclaw

 # 提供商登录（以 openclaw 用户运行）
@@ -95,9 +95,9 @@ openclaw channels login

 ### 4 层防御

-1. **防火墙（UFW）**：仅公开暴露 SSH (22) + Tailscale (41641/udp)
-2. **VPN（Tailscale）**：Gateway网关仅可通过 VPN mesh 网络访问
-3. **Docker 隔离**：DOCKER-USER iptables 链阻止外部端口暴露
+1. **防火墙（UFW）**：仅公开暴露 SSH（22）+ Tailscale（41641/udp）
+2. **VPN（Tailscale）**：Gateway 网关仅通过 VPN mesh 可访问
+3. **Docker 隔离**：DOCKER-USER iptables 链防止外部端口暴露
 4. **Systemd 加固**：NoNewPrivileges、PrivateTmp、非特权用户

 ### 验证
@@ -108,58 +108,58 @@ openclaw channels login
 nmap -p- YOUR_SERVER_IP
 ```

-应当仅显示**端口 22**（SSH）为开放状态。所有其他服务（Gateway网关、Docker）均已锁定。
+应该显示**仅端口 22**（SSH）开放。所有其他服务（Gateway 网关、Docker）都被锁定。

 ### Docker 可用性

-Docker 用于**智能体沙箱**（隔离的工具执行），而非运行 Gateway网关本身。Gateway网关仅绑定到 localhost，通过 Tailscale VPN 访问。
+Docker 用于**智能体沙箱**（隔离的工具执行），而不是用于运行 Gateway 网关本身。Gateway 网关仅绑定到 localhost，通过 Tailscale VPN 访问。

-沙箱配置详见 [多智能体沙箱与工具](/multi-agent-sandbox-tools)。
+沙箱配置参见[多智能体沙箱与工具](/multi-agent-sandbox-tools)。

 ## 手动安装

-如果你希望手动控制而非使用自动化：
+如果你更喜欢手动控制而非自动化：

 ```bash
-# 1. 安装前置依赖
+# 1. 安装先决条件
 sudo apt update && sudo apt install -y ansible git

 # 2. 克隆仓库
 git clone https://github.com/openclaw/openclaw-ansible.git
 cd openclaw-ansible

-# 3. 安装 Ansible 集合
+# 3. 安装 Ansible collections
 ansible-galaxy collection install -r requirements.yml

 # 4. 运行 playbook
 ./run-playbook.sh

-# 或直接运行（之后手动执行 /tmp/openclaw-setup.sh）
+# 或直接运行（然后手动执行 /tmp/openclaw-setup.sh）
 # ansible-playbook playbook.yml --ask-become-pass
 ```

 ## 更新 OpenClaw

-Ansible 安装程序将 OpenClaw 设置为手动更新。标准更新流程详见 [更新](/install/updating)。
+Ansible 安装程序设置 OpenClaw 为手动更新。标准更新流程参见[更新](/install/updating)。

-重新运行 Ansible playbook（例如配置变更时）：
+要重新运行 Ansible playbook（例如，用于配置更改）：

 ```bash
 cd openclaw-ansible
 ./run-playbook.sh
 ```

-注意：此操作是幂等的，可以安全地多次运行。
+注意：这是幂等的，可以安全地多次运行。

 ## 故障排除

 ### 防火墙阻止了我的连接

-如果你被锁定在外：
+如果你被锁定：

- 确保先通过 Tailscale VPN 访问
- SSH 访问（端口 22）始终是允许的
- Gateway网关 **仅**可通过 Tailscale 访问，这是设计如此
+- 确保你可以先通过 Tailscale VPN 访问
+- SSH 访问（端口 22）始终允许
+- Gateway 网关**仅**通过 Tailscale 访问，这是设计如此

 ### 服务无法启动

@@ -179,13 +179,13 @@ pnpm start
 ### Docker 沙箱问题

 ```bash
-# 验证 Docker 是否运行
+# 验证 Docker 正在运行
 sudo systemctl status docker

 # 检查沙箱镜像
 sudo docker images | grep openclaw-sandbox

-# 如果缺少沙箱镜像则构建
+# 如果缺失则构建沙箱镜像
 cd /opt/openclaw/openclaw
 sudo -u openclaw ./scripts/sandbox-setup.sh
 ```
@@ -201,15 +201,15 @@ openclaw channels login

 ## 高级配置

-有关详细的安全架构和故障排除：
+详细的安全架构和故障排除：

 - [安全架构](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
- [技术细节](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
+- [技术详情](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
 - [故障排除指南](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)

 ## 相关内容

 - [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — 完整部署指南
- [Docker](/install/docker) — 容器化 Gateway网关设置
- [沙箱](/gateway/sandboxing) — 智能体沙箱配置
- [多智能体沙箱与工具](/multi-agent-sandbox-tools) — 按智能体隔离
+- [Docker](/install/docker) — 容器化 Gateway 网关设置
+- [沙箱隔离](/gateway/sandboxing) — 智能体沙箱配置
+- [多智能体沙箱与工具](/multi-agent-sandbox-tools) — 每个智能体的隔离
@@ -1,45 +1,45 @@
 ---
 read_when:
  - 你想要最快的本地开发循环（bun + watch）
-  - 你遇到了 Bun 安装/补丁/生命周期脚本问题
-summary: Bun 工作流（实验性）：安装方式及与 pnpm 相比的注意事项
+  - 你遇到 Bun 安装/补丁/生命周期脚本问题
+summary: Bun 工作流（实验性）：安装及与 pnpm 相比的注意事项
 title: Bun（实验性）
 x-i18n:
-  generated_at: "2026-02-01T21:05:42Z"
+  generated_at: "2026-02-03T07:49:24Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: eb3f4c222b6bae49938d8bf53a0818fe5f5e0c0c3c1adb3e0a832ce8f785e1e3
  source_path: install/bun.md
-  workflow: 14
+  workflow: 15
 ---

 # Bun（实验性）

-目标：使用 **Bun** 运行本仓库（可选，不推荐用于 WhatsApp/Telegram），同时不偏离 pnpm 工作流。
+目标：使用 **Bun** 运行此仓库（可选，不推荐用于 WhatsApp/Telegram），同时不偏离 pnpm 工作流。

-⚠️ **不推荐用于 Gateway网关运行时**（WhatsApp/Telegram 存在 bug）。生产环境请使用 Node。
+⚠️ **不推荐用于 Gateway 网关运行时**（WhatsApp/Telegram 存在 bug）。生产环境请使用 Node。

 ## 状态

 - Bun 是一个可选的本地运行时，用于直接运行 TypeScript（`bun run …`、`bun --watch …`）。
- `pnpm` 是默认的构建工具，仍然完全受支持（部分文档工具也在使用）。
- Bun 无法使用 `pnpm-lock.yaml`，会将其忽略。
+- `pnpm` 是构建的默认工具，仍然完全支持（并被一些文档工具使用）。
+- Bun 无法使用 `pnpm-lock.yaml` 并会忽略它。

 ## 安装

-默认方式：
+默认：

 ```sh
 bun install
 ```

-注意：`bun.lock`/`bun.lockb` 已被 gitignore，因此不会造成仓库变动。如果你不想写入锁文件：
+注意：`bun.lock`/`bun.lockb` 被 gitignore，所以无论哪种方式都不会有仓库变动。如果你想*不写入锁文件*：

 ```sh
 bun install --no-save
 ```

-## 构建 / 测试（Bun）
+## 构建/测试（Bun）

 ```sh
 bun run build
@@ -48,13 +48,13 @@ bun run vitest run

 ## Bun 生命周期脚本（默认被阻止）

-Bun 可能会阻止依赖的生命周期脚本，除非显式信任（`bun pm untrusted` / `bun pm trust`）。
-对于本仓库，常见被阻止的脚本并非必需：
+除非明确信任（`bun pm untrusted` / `bun pm trust`），Bun 可能会阻止依赖的生命周期脚本。
+对于此仓库，通常被阻止的脚本不是必需的：

 - `@whiskeysockets/baileys` `preinstall`：检查 Node 主版本 >= 20（我们运行 Node 22+）。
 - `protobufjs` `postinstall`：发出关于不兼容版本方案的警告（无构建产物）。

-如果你遇到确实需要这些脚本的运行时问题，请显式信任它们：
+如果你遇到真正需要这些脚本的运行时问题，请明确信任它们：

 ```sh
 bun pm trust @whiskeysockets/baileys protobufjs
@@ -62,4 +62,4 @@ bun pm trust @whiskeysockets/baileys protobufjs

 ## 注意事项

- 部分脚本仍硬编码使用 pnpm（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请通过 pnpm 运行这些脚本。
+- 一些脚本仍然硬编码 pnpm（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请通过 pnpm 运行这些脚本。
@@ -1,16 +1,16 @@
 ---
 read_when:
-  - 你想在稳定版/测试版/开发版之间切换
+  - 你想在 stable/beta/dev 之间切换
  - 你正在标记或发布预发布版本
-summary: 稳定版、测试版和开发版渠道：语义、切换和标签管理
+summary: stable、beta 和 dev 渠道：语义、切换和标签
 title: 开发渠道
 x-i18n:
-  generated_at: "2026-02-01T21:05:54Z"
+  generated_at: "2026-02-03T10:07:21Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 2b01219b7e705044ce39838a0da7c7fa65c719809ab2f8a51e14529064af81bf
  source_path: install/development-channels.md
-  workflow: 14
+  workflow: 15
 ---

 # 开发渠道
@@ -21,13 +21,14 @@ OpenClaw 提供三个更新渠道：

 - **stable**：npm dist-tag `latest`。
 - **beta**：npm dist-tag `beta`（测试中的构建）。
- **dev**：`main` 分支的最新提交（git）。npm dist-tag：`dev`（发布时）。
+- **dev**：`main` 的移动头（git）。npm dist-tag：`dev`（发布时）。

-我们将构建发布到 **beta**，进行测试，然后**将经过验证的构建提升为 `latest`**，无需更改版本号 — dist-tag 是 npm 安装的权威来源。
+我们将构建发布到 **beta**，进行测试，然后**将经过验证的构建提升到 `latest`**，
+版本号不变——dist-tag 是 npm 安装的数据源。

 ## 切换渠道

-Git checkout 方式：
+Git checkout：

 ```bash
 openclaw update --channel stable
@@ -35,10 +36,10 @@ openclaw update --channel beta
 openclaw update --channel dev
 ```

- `stable`/`beta` 会签出最新匹配的标签（通常是同一个标签）。
- `dev` 切换到 `main` 并在上游基础上进行 rebase。
+- `stable`/`beta` 检出最新匹配的标签（通常是同一个标签）。
+- `dev` 切换到 `main` 并在上游基础上 rebase。

-npm/pnpm 全局安装方式：
+npm/pnpm 全局安装：

 ```bash
 openclaw update --channel stable
@@ -46,34 +47,35 @@ openclaw update --channel beta
 openclaw update --channel dev
 ```

-这会通过对应的 npm dist-tag（`latest`、`beta`、`dev`）进行更新。
+这会通过相应的 npm dist-tag（`latest`、`beta`、`dev`）进行更新。

-当你**显式**使用 `--channel` 切换渠道时，OpenClaw 也会同步调整安装方式：
+当你使用 `--channel` **显式**切换渠道时，OpenClaw 还会对齐安装方式：

- `dev` 确保存在 git checkout（默认 `~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），更新它，并从该 checkout 安装全局 CLI。
+- `dev` 确保有一个 git checkout（默认 `~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），
+  更新它，并从该 checkout 安装全局 CLI。
 - `stable`/`beta` 使用匹配的 dist-tag 从 npm 安装。

-提示：如果你想同时使用 stable 和 dev，可以保留两个克隆，并将 Gateway网关指向 stable 的那个。
+提示：如果你想同时使用 stable + dev，保留两个克隆并将 Gateway 网关指向 stable 那个。

-## 插件与渠道
+## 插件和渠道

-使用 `openclaw update` 切换渠道时，OpenClaw 也会同步插件来源：
+当你使用 `openclaw update` 切换渠道时，OpenClaw 还会同步插件来源：

- `dev` 优先使用 git checkout 中内置的插件。
- `stable` 和 `beta` 恢复通过 npm 安装的插件包。
+- `dev` 优先使用 git checkout 中的内置插件。
+- `stable` 和 `beta` 恢复 npm 安装的插件包。

 ## 标签最佳实践

- 为你希望 git checkout 落到的版本打标签（`vYYYY.M.D` 或 `vYYYY.M.D-<patch>`）。
+- 为你希望 git checkout 落在的发布版本打标签（`vYYYY.M.D` 或 `vYYYY.M.D-<patch>`）。
 - 保持标签不可变：永远不要移动或重用标签。
- npm dist-tag 仍然是 npm 安装的权威来源：
-  - `latest` → 稳定版
+- npm dist-tag 仍然是 npm 安装的数据源：
+  - `latest` → stable
  - `beta` → 候选构建
  - `dev` → main 快照（可选）

 ## macOS 应用可用性

-测试版和开发版构建可能**不包含** macOS 应用发布。这是正常的：
+Beta 和 dev 构建可能**不**包含 macOS 应用发布。这没问题：

 - git 标签和 npm dist-tag 仍然可以发布。
- 在发布说明或变更日志中注明"此测试版无 macOS 构建"即可。
+- 在发布说明或变更日志中注明"此 beta 无 macOS 构建"。
@@ -1,75 +1,76 @@
 ---
 read_when:
-  - 你想要容器化的 Gateway网关而非本地安装
+  - 你想要容器化的 Gateway 网关而不是本地安装
  - 你正在验证 Docker 流程
-summary: 可选的基于 Docker 的 OpenClaw 设置和新手引导
+summary: OpenClaw 的可选 Docker 设置和新手引导
 title: Docker
 x-i18n:
-  generated_at: "2026-02-01T21:07:14Z"
+  generated_at: "2026-02-03T07:51:20Z"
  model: claude-opus-4-5
  provider: pi
-  source_hash: 781dd01ca99a2101f622f03162eb1776079c3c444f54c5a054d6816ec203e2f2
+  source_hash: bd823e49b6ce76fe1136a42bf48f436b316ed1cd2f9612e3f4919f1e6b2cdee9
  source_path: install/docker.md
-  workflow: 14
+  workflow: 15
 ---

 # Docker（可选）

-Docker 是**可选的**。仅在你需要容器化 Gateway网关或验证 Docker 流程时使用。
+Docker 是**可选的**。仅当你想要容器化的 Gateway 网关或验证 Docker 流程时才使用它。

 ## Docker 适合我吗？

- **适合**：你需要一个隔离的、可随时销毁的 Gateway网关环境，或者想在无需本地安装的主机上运行 OpenClaw。
- **不适合**：你在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
- **沙箱说明**：智能体沙箱也使用 Docker，但它**不需要**完整的 Gateway网关运行在 Docker 中。详见 [沙箱](/gateway/sandboxing)。
+- **是**：你想要一个隔离的、可丢弃的 Gateway 网关环境，或在没有本地安装的主机上运行 OpenClaw。
+- **否**：你在自己的机器上运行，只想要最快的开发循环。请改用正常的安装流程。
+- **沙箱注意事项**：智能体沙箱隔离也使用 Docker，但它**不需要**完整的 Gateway 网关在 Docker 中运行。参阅[沙箱隔离](/gateway/sandboxing)。

 本指南涵盖：

- 容器化 Gateway网关（完整的 OpenClaw 运行在 Docker 中）
- 按会话的智能体沙箱（主机 Gateway网关 + Docker 隔离的智能体工具）
+- 容器化 Gateway 网关（完整的 OpenClaw 在 Docker 中）
+- 每会话智能体沙箱（主机 Gateway 网关 + Docker 隔离的智能体工具）

-沙箱详情：[沙箱](/gateway/sandboxing)
+沙箱隔离详情：[沙箱隔离](/gateway/sandboxing)

-## 前置要求
+## 要求

 - Docker Desktop（或 Docker Engine）+ Docker Compose v2
- 足够的磁盘空间用于镜像和日志
+- 足够的磁盘空间用于镜像 + 日志

-## 容器化 Gateway网关（Docker Compose）
+## 容器化 Gateway 网关（Docker Compose）

 ### 快速开始（推荐）

-在仓库根目录运行：
+从仓库根目录：

 ```bash
 ./docker-setup.sh
 ```

-该脚本会：
+此脚本：

- 构建 Gateway网关镜像
+- 构建 Gateway 网关镜像
 - 运行新手引导向导
 - 打印可选的提供商设置提示
- 通过 Docker Compose 启动 Gateway网关
- 生成 Gateway网关令牌并写入 `.env`
+- 通过 Docker Compose 启动 Gateway 网关
+- 生成 Gateway 网关令牌并写入 `.env`

 可选环境变量：

- `OPENCLAW_DOCKER_APT_PACKAGES` — 在构建期间安装额外的 apt 软件包
+- `OPENCLAW_DOCKER_APT_PACKAGES` — 在构建期间安装额外的 apt 包
 - `OPENCLAW_EXTRA_MOUNTS` — 添加额外的主机绑定挂载
- `OPENCLAW_HOME_VOLUME` — 将 `/home/node` 持久化到命名卷
+- `OPENCLAW_HOME_VOLUME` — 在命名卷中持久化 `/home/node`

 完成后：

 - 在浏览器中打开 `http://127.0.0.1:18789/`。
- 在控制界面中粘贴令牌（设置 → 令牌）。
+- 将令牌粘贴到控制 UI（设置 → token）。
+- 需要再次获取带令牌的 URL？运行 `docker compose run --rm openclaw-cli dashboard --no-open`。

-配置和工作区写入主机：
+它在主机上写入配置/工作区：

 - `~/.openclaw/`
 - `~/.openclaw/workspace`

-在 VPS 上运行？参见 [Hetzner（Docker VPS）](/platforms/hetzner)。
+在 VPS 上运行？参阅 [Hetzner（Docker VPS）](/platforms/hetzner)。

 ### 手动流程（compose）

@@ -79,9 +80,27 @@ docker compose run --rm openclaw-cli onboard
 docker compose up -d openclaw-gateway
 ```

+注意：从仓库根目录运行 `docker compose ...`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` 或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`；在其他地方运行 Compose 时包含它：
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>
+```
+
+### 控制 UI 令牌 + 配对（Docker）
+
+如果你看到"unauthorized"或"disconnected (1008): pairing required"，获取新的仪表板链接并批准浏览器设备：
+
+```bash
+docker compose run --rm openclaw-cli dashboard --no-open
+docker compose run --rm openclaw-cli devices list
+docker compose run --rm openclaw-cli devices approve <requestId>
+```
+
+更多详情：[仪表板](/web/dashboard)，[设备](/cli/devices)。
+
 ### 额外挂载（可选）

-如果你想将额外的主机目录挂载到容器中，请在运行 `docker-setup.sh` 之前设置 `OPENCLAW_EXTRA_MOUNTS`。该变量接受逗号分隔的 Docker 绑定挂载列表，并通过生成 `docker-compose.extra.yml` 将其应用到 `openclaw-gateway` 和 `openclaw-cli`。
+如果你想将额外的主机目录挂载到容器中，在运行 `docker-setup.sh` 之前设置 `OPENCLAW_EXTRA_MOUNTS`。这接受逗号分隔的 Docker 绑定挂载列表，并通过生成 `docker-compose.extra.yml` 将它们应用到 `openclaw-gateway` 和 `openclaw-cli`。

 示例：

@@ -90,15 +109,15 @@ export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/ho
 ./docker-setup.sh
 ```

-注意事项：
+注意：

- 在 macOS/Windows 上，路径必须与 Docker Desktop 共享。
- 如果修改了 `OPENCLAW_EXTRA_MOUNTS`，请重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
- `docker-compose.extra.yml` 是自动生成的。请勿手动编辑。
+- 路径必须在 macOS/Windows 上与 Docker Desktop 共享。
+- 如果你编辑 `OPENCLAW_EXTRA_MOUNTS`，重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
+- `docker-compose.extra.yml` 是生成的。不要手动编辑它。

-### 持久化整个容器 home 目录（可选）
+### 持久化整个容器 home（可选）

-如果你希望 `/home/node` 在容器重建后持久保留，请通过 `OPENCLAW_HOME_VOLUME` 设置命名卷。这会创建一个 Docker 卷并挂载到 `/home/node`，同时保留标准的配置/工作区绑定挂载。此处请使用命名卷（而非绑定路径）；绑定挂载请使用 `OPENCLAW_EXTRA_MOUNTS`。
+如果你想让 `/home/node` 在容器重建后持久化，通过 `OPENCLAW_HOME_VOLUME` 设置一个命名卷。这会创建一个 Docker 卷并将其挂载到 `/home/node`，同时保持标准的配置/工作区绑定挂载。这里使用命名卷（不是绑定路径）；对于绑定挂载，使用 `OPENCLAW_EXTRA_MOUNTS`。

 示例：

@@ -107,7 +126,7 @@ export OPENCLAW_HOME_VOLUME="openclaw_home"
 ./docker-setup.sh
 ```

-可以与额外挂载组合使用：
+你可以将其与额外挂载结合使用：

 ```bash
 export OPENCLAW_HOME_VOLUME="openclaw_home"
@@ -115,14 +134,14 @@ export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/ho
 ./docker-setup.sh
 ```

-注意事项：
+注意：

- 如果修改了 `OPENCLAW_HOME_VOLUME`，请重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
- 命名卷会一直保留，直到通过 `docker volume rm <name>` 删除。
+- 如果你更改 `OPENCLAW_HOME_VOLUME`，重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
+- 命名卷会持久化直到使用 `docker volume rm <name>` 删除。

-### 安装额外的 apt 软件包（可选）
+### 安装额外的 apt 包（可选）

-如果你需要在镜像中安装系统软件包（例如构建工具或媒体库），请在运行 `docker-setup.sh` 之前设置 `OPENCLAW_DOCKER_APT_PACKAGES`。这会在镜像构建期间安装软件包，因此即使容器被删除也会保留。
+如果你需要镜像内的系统包（例如构建工具或媒体库），在运行 `docker-setup.sh` 之前设置 `OPENCLAW_DOCKER_APT_PACKAGES`。这会在镜像构建期间安装包，因此即使容器被删除它们也会持久化。

 示例：

@@ -131,14 +150,64 @@ export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
 ./docker-setup.sh
 ```

-注意事项：
+注意：

- 该变量接受以空格分隔的 apt 软件包名称列表。
- 如果修改了 `OPENCLAW_DOCKER_APT_PACKAGES`，请重新运行 `docker-setup.sh` 以重建镜像。
+- 这接受空格分隔的 apt 包名称列表。
+- 如果你更改 `OPENCLAW_DOCKER_APT_PACKAGES`，重新运行 `docker-setup.sh` 以重建镜像。

-### 加速重建（推荐）
+### 高级用户/功能完整的容器（选择加入）

-为加速重建，请调整 Dockerfile 中的顺序以利用依赖层缓存。这样只有在锁文件变更时才会重新运行 `pnpm install`：
+默认的 Docker 镜像是**安全优先**的，以非 root 的 `node` 用户运行。这保持了较小的攻击面，但这意味着：
+
+- 运行时无法安装系统包
+- 默认没有 Homebrew
+- 没有捆绑的 Chromium/Playwright 浏览器
+
+如果你想要功能更完整的容器，使用这些选择加入选项：
+
+1. **持久化 `/home/node`** 以便浏览器下载和工具缓存能够保留：
+
+```bash
+export OPENCLAW_HOME_VOLUME="openclaw_home"
+./docker-setup.sh
+```
+
+2. **将系统依赖烘焙到镜像中**（可重复 + 持久化）：
+
+```bash
+export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
+./docker-setup.sh
+```
+
+3. **不使用 `npx` 安装 Playwright 浏览器**（避免 npm 覆盖冲突）：
+
+```bash
+docker compose run --rm openclaw-cli \
+  node /app/node_modules/playwright-core/cli.js install chromium
+```
+
+如果你需要 Playwright 安装系统依赖，使用 `OPENCLAW_DOCKER_APT_PACKAGES` 重建镜像，而不是在运行时使用 `--with-deps`。
+
+4. **持久化 Playwright 浏览器下载**：
+
+- 在 `docker-compose.yml` 中设置 `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`。
+- 确保 `/home/node` 通过 `OPENCLAW_HOME_VOLUME` 持久化，或通过 `OPENCLAW_EXTRA_MOUNTS` 挂载 `/home/node/.cache/ms-playwright`。
+
+### 权限 + EACCES
+
+镜像以 `node`（uid 1000）运行。如果你在 `/home/node/.openclaw` 上看到权限错误，确保你的主机绑定挂载由 uid 1000 拥有。
+
+示例（Linux 主机）：
+
+```bash
+sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
+```
+
+如果你选择以 root 运行以方便使用，你接受了安全权衡。
+
+### 更快的重建（推荐）
+
+要加速重建，排序你的 Dockerfile 以便依赖层被缓存。这避免了除非锁文件更改否则重新运行 `pnpm install`：

 ```dockerfile
 FROM node:22-bookworm
@@ -151,7 +220,7 @@ RUN corepack enable

 WORKDIR /app

-# 除非包元数据变更，否则缓存依赖
+# 缓存依赖，除非包元数据更改
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
 COPY ui/package.json ./ui/package.json
 COPY scripts ./scripts
@@ -170,27 +239,31 @@ CMD ["node","dist/index.js"]

 ### 渠道设置（可选）

-使用 CLI 容器配置渠道，然后根据需要重启 Gateway网关。
+使用 CLI 容器配置渠道，然后在需要时重启 Gateway 网关。

-WhatsApp（二维码）：
+WhatsApp（QR）：

 ```bash
 docker compose run --rm openclaw-cli channels login
 ```

-Telegram（机器人令牌）：
+Telegram（bot token）：

 ```bash
 docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
 ```

-Discord（机器人令牌）：
+Discord（bot token）：

 ```bash
 docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
 ```

-文档：[WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)
+文档：[WhatsApp](/channels/whatsapp)，[Telegram](/channels/telegram)，[Discord](/channels/discord)
+
+### OpenAI Codex OAuth（无头 Docker）
+
+如果你在向导中选择 OpenAI Codex OAuth，它会打开浏览器 URL 并尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调。在 Docker 或无头设置中，该回调可能显示浏览器错误。复制你到达的完整重定向 URL 并将其粘贴回向导以完成认证。

 ### 健康检查

@@ -198,70 +271,71 @@ docker compose run --rm openclaw-cli channels add --channel discord --token "<to
 docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
 ```

-### 端到端冒烟测试（Docker）
+### E2E 冒烟测试（Docker）

 ```bash
 scripts/e2e/onboard-docker.sh
 ```

-### 二维码导入冒烟测试（Docker）
+### QR 导入冒烟测试（Docker）

 ```bash
 pnpm test:docker:qr
 ```

-### 注意事项
+### 注意

- Gateway网关绑定默认设为 `lan` 以适配容器使用。
- Gateway网关容器是会话的权威来源（`~/.openclaw/agents/<agentId>/sessions/`）。
+- Gateway 网关绑定默认为 `lan` 用于容器使用。
+- Dockerfile CMD 使用 `--allow-unconfigured`；挂载的配置如果 `gateway.mode` 不是 `local` 仍会启动。覆盖 CMD 以强制执行检查。
+- Gateway 网关容器是会话的真实来源（`~/.openclaw/agents/<agentId>/sessions/`）。

-## 智能体沙箱（主机 Gateway网关 + Docker 工具）
+## 智能体沙箱（主机 Gateway 网关 + Docker 工具）

-深入了解：[沙箱](/gateway/sandboxing)
+深入了解：[沙箱隔离](/gateway/sandboxing)

-### 功能说明
+### 它做什么

-当启用 `agents.defaults.sandbox` 时，**非 main 会话**会在 Docker 容器内运行工具。Gateway网关仍在主机上运行，但工具执行是隔离的：
+当启用 `agents.defaults.sandbox` 时，**非主会话**在 Docker 容器内运行工具。Gateway 网关保持在你的主机上，但工具执行是隔离的：

- 作用域：默认为 `"agent"`（每个智能体一个容器 + 工作区）
- 作用域：`"session"` 用于按会话隔离
- 按作用域的工作区文件夹挂载到 `/workspace`
+- scope：默认为 `"agent"`（每个智能体一个容器 + 工作区）
+- scope：`"session"` 用于每会话隔离
+- 每作用域工作区文件夹挂载在 `/workspace`
 - 可选的智能体工作区访问（`agents.defaults.sandbox.workspaceAccess`）
 - 允许/拒绝工具策略（拒绝优先）
- 入站媒体会复制到活动沙箱工作区（`media/inbound/*`），以便工具可以读取（使用 `workspaceAccess: "rw"` 时，媒体会落入智能体工作区）
+- 入站媒体被复制到活动沙箱工作区（`media/inbound/*`），以便工具可以读取它（使用 `workspaceAccess: "rw"` 时，这会落在智能体工作区中）

-警告：`scope: "shared"` 会禁用跨会话隔离。所有会话共享一个容器和一个工作区。
+警告：`scope: "shared"` 禁用跨会话隔离。所有会话共享一个容器和一个工作区。

-### 按智能体的沙箱配置（多智能体）
+### 每智能体沙箱配置文件（多智能体）

-如果使用多智能体路由，每个智能体可以覆盖沙箱和工具设置：`agents.list[].sandbox` 和 `agents.list[].tools`（以及 `agents.list[].tools.sandbox.tools`）。这允许你在一个 Gateway网关中运行混合访问级别：
+如果你使用多智能体路由，每个智能体可以覆盖沙箱 + 工具设置：`agents.list[].sandbox` 和 `agents.list[].tools`（加上 `agents.list[].tools.sandbox.tools`）。这让你可以在一个 Gateway 网关中运行混合访问级别：

 - 完全访问（个人智能体）
 - 只读工具 + 只读工作区（家庭/工作智能体）
 - 无文件系统/shell 工具（公共智能体）

-示例、优先级和故障排除详见 [多智能体沙箱与工具](/multi-agent-sandbox-tools)。
+参阅[多智能体沙箱与工具](/multi-agent-sandbox-tools)了解示例、优先级和故障排除。

 ### 默认行为

 - 镜像：`openclaw-sandbox:bookworm-slim`
 - 每个智能体一个容器
 - 智能体工作区访问：`workspaceAccess: "none"`（默认）使用 `~/.openclaw/sandboxes`
-  - `"ro"` 将沙箱工作区保留在 `/workspace`，并将智能体工作区以只读方式挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）
-  - `"rw"` 将智能体工作区以读写方式挂载到 `/workspace`
- 自动清理：空闲超过 24 小时或创建超过 7 天
- 网络：默认为 `none`（需要出站访问时请显式启用）
+  - `"ro"` 保持沙箱工作区在 `/workspace` 并将智能体工作区只读挂载在 `/agent`（禁用 `write`/`edit`/`apply_patch`）
+  - `"rw"` 将智能体工作区读写挂载在 `/workspace`
+- 自动清理：空闲 > 24h 或 年龄 > 7d
+- 网络：默认为 `none`（如果需要出站则明确选择加入）
 - 默认允许：`exec`、`process`、`read`、`write`、`edit`、`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`
 - 默认拒绝：`browser`、`canvas`、`nodes`、`cron`、`discord`、`gateway`

-### 启用沙箱
+### 启用沙箱隔离

-如果你计划在 `setupCommand` 中安装软件包，请注意：
+如果你计划在 `setupCommand` 中安装包，请注意：

- 默认 `docker.network` 为 `"none"`（无出站访问）。
- `readOnlyRoot: true` 会阻止软件包安装。
+- 默认 `docker.network` 是 `"none"`（无出站）。
+- `readOnlyRoot: true` 阻止包安装。
 - `user` 必须是 root 才能运行 `apt-get`（省略 `user` 或设置 `user: "0:0"`）。
-  当 `setupCommand`（或 docker 配置）发生变更时，OpenClaw 会自动重建容器，除非容器**最近被使用过**（约 5 分钟内）。活跃容器会记录一条警告，包含确切的 `openclaw sandbox recreate ...` 命令。
+  当 `setupCommand`（或 docker 配置）更改时，OpenClaw 会自动重建容器，除非容器是**最近使用的**（在约 5 分钟内）。热容器会记录警告，包含确切的 `openclaw sandbox recreate ...` 命令。

 ```json5
 {
@@ -297,7 +371,7 @@ pnpm test:docker:qr
        },
        prune: {
          idleHours: 24, // 0 禁用空闲清理
-          maxAgeDays: 7, // 0 禁用最大时限清理
+          maxAgeDays: 7, // 0 禁用最大年龄清理
        },
      },
    },
@@ -324,12 +398,9 @@ pnpm test:docker:qr
 }
 ```

-加固选项位于 `agents.defaults.sandbox.docker` 下：
-`network`、`user`、`pidsLimit`、`memory`、`memorySwap`、`cpus`、`ulimits`、
-`seccompProfile`、`apparmorProfile`、`dns`、`extraHosts`。
+加固选项位于 `agents.defaults.sandbox.docker` 下：`network`、`user`、`pidsLimit`、`memory`、`memorySwap`、`cpus`、`ulimits`、`seccompProfile`、`apparmorProfile`、`dns`、`extraHosts`。

-多智能体：通过 `agents.list[].sandbox.{docker,browser,prune}.*` 按智能体覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`
-（当 `agents.defaults.sandbox.scope` / `agents.list[].sandbox.scope` 为 `"shared"` 时忽略）。
+多智能体：通过 `agents.list[].sandbox.{docker,browser,prune}.*` 按智能体覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当 `agents.defaults.sandbox.scope` / `agents.list[].sandbox.scope` 是 `"shared"` 时忽略）。

 ### 构建默认沙箱镜像

@@ -337,17 +408,17 @@ pnpm test:docker:qr
 scripts/sandbox-setup.sh
 ```

-这会使用 `Dockerfile.sandbox` 构建 `openclaw-sandbox:bookworm-slim`。
+这使用 `Dockerfile.sandbox` 构建 `openclaw-sandbox:bookworm-slim`。

 ### 沙箱通用镜像（可选）

-如果你需要包含常用构建工具（Node、Go、Rust 等）的沙箱镜像，请构建通用镜像：
+如果你想要一个带有常见构建工具（Node、Go、Rust 等）的沙箱镜像，构建通用镜像：

 ```bash
 scripts/sandbox-common-setup.sh
 ```

-这会构建 `openclaw-sandbox-common:bookworm-slim`。使用方法：
+这构建 `openclaw-sandbox-common:bookworm-slim`。要使用它：

 ```json5
 {
@@ -361,21 +432,21 @@ scripts/sandbox-common-setup.sh

 ### 沙箱浏览器镜像

-要在沙箱内运行浏览器工具，请构建浏览器镜像：
+要在沙箱内运行浏览器工具，构建浏览器镜像：

 ```bash
 scripts/sandbox-browser-setup.sh
 ```

-这会使用 `Dockerfile.sandbox-browser` 构建 `openclaw-sandbox-browser:bookworm-slim`。容器运行启用了 CDP 的 Chromium，并提供可选的 noVNC 观察器（通过 Xvfb 实现有头模式）。
+这使用 `Dockerfile.sandbox-browser` 构建 `openclaw-sandbox-browser:bookworm-slim`。容器运行启用 CDP 的 Chromium 和可选的 noVNC 观察器（通过 Xvfb 有头）。

-注意事项：
+注意：

- 有头模式（Xvfb）比无头模式更能减少机器人检测。
- 仍可通过设置 `agents.defaults.sandbox.browser.headless=true` 使用无头模式。
+- 有头（Xvfb）比无头减少机器人阻止。
+- 通过设置 `agents.defaults.sandbox.browser.headless=true` 仍然可以使用无头模式。
 - 不需要完整的桌面环境（GNOME）；Xvfb 提供显示。

-配置用法：
+使用配置：

 ```json5
 {
@@ -401,17 +472,17 @@ scripts/sandbox-browser-setup.sh
 }
 ```

-启用后，智能体会收到：
+启用后，智能体接收：

 - 沙箱浏览器控制 URL（用于 `browser` 工具）
- noVNC URL（如果已启用且 headless=false）
+- noVNC URL（如果启用且 headless=false）

-注意：如果你使用了工具允许列表，请添加 `browser`（并从拒绝列表中移除），否则该工具仍会被阻止。
+记住：如果你使用工具允许列表，添加 `browser`（并从拒绝中移除它）否则工具仍然被阻止。
 清理规则（`agents.defaults.sandbox.prune`）也适用于浏览器容器。

 ### 自定义沙箱镜像

-构建你自己的镜像并在配置中指向它：
+构建你自己的镜像并将配置指向它：

 ```bash
 docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
@@ -430,32 +501,32 @@ docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
 ### 工具策略（允许/拒绝）

 - `deny` 优先于 `allow`。
- 如果 `allow` 为空：所有工具（除拒绝的）均可用。
- 如果 `allow` 不为空：仅 `allow` 中的工具可用（减去拒绝的）。
+- 如果 `allow` 为空：所有工具（除了 deny）都可用。
+- 如果 `allow` 非空：只有 `allow` 中的工具可用（减去 deny）。

 ### 清理策略

-两个配置项：
+两个选项：

- `prune.idleHours`：移除超过 X 小时未使用的容器（0 = 禁用）
+- `prune.idleHours`：移除 X 小时未使用的容器（0 = 禁用）
 - `prune.maxAgeDays`：移除超过 X 天的容器（0 = 禁用）

 示例：

- 保留活跃会话但限制生命周期：
-  `idleHours: 24`，`maxAgeDays: 7`
- 从不清理：
-  `idleHours: 0`，`maxAgeDays: 0`
+- 保留繁忙会话但限制生命周期：
+  `idleHours: 24`、`maxAgeDays: 7`
+- 永不清理：
+  `idleHours: 0`、`maxAgeDays: 0`

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

 - 硬隔离仅适用于**工具**（exec/read/write/edit/apply_patch）。
- 仅限主机的工具（如 browser/camera/canvas）默认被阻止。
- 在沙箱中允许 `browser` 会**破坏隔离**（浏览器运行在主机上）。
+- 仅主机工具如 browser/camera/canvas 默认被阻止。
+- 在沙箱中允许 `browser` **会破坏隔离**（浏览器在主机上运行）。

 ## 故障排除

 - 镜像缺失：使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) 构建或设置 `agents.defaults.sandbox.docker.image`。
- 容器未运行：它会按需在每个会话中自动创建。
- 沙箱中的权限错误：将 `docker.user` 设置为与挂载工作区所有权匹配的 UID:GID（或对工作区文件夹执行 chown）。
- 找不到自定义工具：OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会加载 `/etc/profile` 并可能重置 PATH。请设置 `docker.env.PATH` 以前置你的自定义工具路径（例如 `/custom/bin:/usr/local/share/npm-global/bin`），或在 Dockerfile 中的 `/etc/profile.d/` 下添加脚本。
+- 容器未运行：它会按需为每个会话自动创建。
+- 沙箱中的权限错误：将 `docker.user` 设置为与你挂载的工作区所有权匹配的 UID:GID（或 chown 工作区文件夹）。
+- 找不到自定义工具：OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会 source `/etc/profile` 并可能重置 PATH。设置 `docker.env.PATH` 以在前面添加你的自定义工具路径（例如 `/custom/bin:/usr/local/share/npm-global/bin`），或在你的 Dockerfile 中在 `/etc/profile.d/` 下添加脚本。
@@ -2,15 +2,15 @@
 read_when:
  - 安装 OpenClaw
  - 你想从 GitHub 安装
-summary: 安装 OpenClaw（推荐安装器、全局安装或从源码安装）
+summary: 安装 OpenClaw（推荐安装器、全局安装或从源代码安装）
 title: 安装
 x-i18n:
-  generated_at: "2026-02-01T21:07:34Z"
+  generated_at: "2026-02-03T10:07:43Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
  source_path: install/index.md
-  workflow: 14
+  workflow: 15
 ---

 # 安装
@@ -23,7 +23,7 @@ x-i18n:
 curl -fsSL https://openclaw.ai/install.sh | bash
 ```

-Windows (PowerShell)：
+Windows（PowerShell）：

 ```powershell
 iwr -useb https://openclaw.ai/install.ps1 | iex
@@ -39,11 +39,11 @@ openclaw onboard --install-daemon

 - **Node >=22**
 - macOS、Linux 或通过 WSL2 的 Windows
- `pnpm` 仅在从源码构建时需要
+- `pnpm` 仅在从源代码构建时需要

-## 选择安装方式
+## 选择安装路径

-### 1) 安装器脚本（推荐）
+### 1）安装器脚本（推荐）

 通过 npm 全局安装 `openclaw` 并运行新手引导。

@@ -51,13 +51,13 @@ openclaw onboard --install-daemon
 curl -fsSL https://openclaw.ai/install.sh | bash
 ```

-安装器参数：
+安装器标志：

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

-详情：[安装器内部机制](/install/installer)。
+详情：[安装器内部原理](/install/installer)。

 非交互式（跳过新手引导）：

@@ -65,21 +65,21 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
 ```

-### 2) 全局安装（手动）
+### 2）全局安装（手动）

-如果你已安装 Node：
+如果你已经有 Node：

 ```bash
 npm install -g openclaw@latest
 ```

-如果你已全局安装 libvips（macOS 上常通过 Homebrew 安装）且 `sharp` 安装失败，请强制使用预编译二进制文件：
+如果你全局安装了 libvips（macOS 上通过 Homebrew 安装很常见）且 `sharp` 安装失败，请强制使用预构建二进制文件：

 ```bash
 SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
 ```

-如果你看到 `sharp: Please add node-gyp to your dependencies`，可以安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），或使用上述 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法跳过原生构建。
+如果你看到 `sharp: Please add node-gyp to your dependencies`，要么安装构建工具（macOS：Xcode CLT + `npm install -g node-gyp`），要么使用上面的 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 变通方法来跳过原生构建。

 或使用 pnpm：

@@ -89,7 +89,7 @@ pnpm approve-builds -g                # 批准 openclaw、node-llama-cpp、sharp
 pnpm add -g openclaw@latest           # 重新运行以执行 postinstall 脚本
 ```

-pnpm 要求显式批准带有构建脚本的软件包。首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的软件包，然后重新运行安装以执行 postinstall 脚本。
+pnpm 需要显式批准带有构建脚本的包。在首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的包，然后重新运行安装以执行 postinstall 脚本。

 然后：

@@ -97,7 +97,7 @@ pnpm 要求显式批准带有构建脚本的软件包。首次安装显示"Ignor
 openclaw onboard --install-daemon
 ```

-### 3) 从源码安装（贡献者/开发用途）
+### 3）从源代码（贡献者/开发）

 ```bash
 git clone https://github.com/openclaw/openclaw.git
@@ -108,9 +108,9 @@ pnpm build
 openclaw onboard --install-daemon
 ```

-提示：如果尚未全局安装，可通过 `pnpm openclaw ...` 运行仓库命令。
+提示：如果你还没有全局安装，请通过 `pnpm openclaw ...` 运行仓库命令。

-### 4) 其他安装选项
+### 4）其他安装选项

 - Docker：[Docker](/install/docker)
 - Nix：[Nix](/install/nix)
@@ -121,38 +121,38 @@ openclaw onboard --install-daemon

 - 运行新手引导：`openclaw onboard --install-daemon`
 - 快速检查：`openclaw doctor`
- 检查 Gateway网关健康状态：`openclaw status` + `openclaw health`
- 打开仪表盘：`openclaw dashboard`
+- 检查 Gateway 网关健康状态：`openclaw status` + `openclaw health`
+- 打开仪表板：`openclaw dashboard`

 ## 安装方式：npm vs git（安装器）

 安装器支持两种方式：

 - `npm`（默认）：`npm install -g openclaw@latest`
- `git`：从 GitHub 克隆/构建并从源码检出运行
+- `git`：从 GitHub 克隆/构建并从源代码 checkout 运行

-### CLI 参数
+### CLI 标志

 ```bash
-# 显式使用 npm
+# 显式 npm
 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

-# 从 GitHub 安装（源码检出）
+# 从 GitHub 安装（源代码 checkout）
 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
 ```

-常用参数：
+常用标志：

 - `--install-method npm|git`
 - `--git-dir <path>`（默认：`~/openclaw`）
- `--no-git-update`（使用已有检出时跳过 `git pull`）
+- `--no-git-update`（使用现有 checkout 时跳过 `git pull`）
 - `--no-prompt`（禁用提示；CI/自动化中必需）
 - `--dry-run`（打印将要执行的操作；不做任何更改）
 - `--no-onboard`（跳过新手引导）

 ### 环境变量

-等效的环境变量（适用于自动化）：
+等效的环境变量（对自动化有用）：

 - `OPENCLAW_INSTALL_METHOD=git|npm`
 - `OPENCLAW_GIT_DIR=...`
@@ -160,9 +160,9 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
 - `OPENCLAW_NO_PROMPT=1`
 - `OPENCLAW_DRY_RUN=1`
 - `OPENCLAW_NO_ONBOARD=1`
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 使用系统 libvips 编译）
+- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 针对系统 libvips 构建）

-## 故障排除：找不到 `openclaw`（PATH 问题）
+## 故障排除：找不到 `openclaw`（PATH）

 快速诊断：

@@ -173,20 +173,20 @@ npm prefix -g
 echo "$PATH"
 ```

-如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不在** `echo "$PATH"` 的输出中，说明你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。
+如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不**在 `echo "$PATH"` 的输出中，你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。

-修复：将其添加到 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
+修复：将其添加到你的 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：

 ```bash
 # macOS / Linux
 export PATH="$(npm prefix -g)/bin:$PATH"
 ```

-在 Windows 上，将 `npm prefix -g` 的输出添加到 PATH。
+在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH。

 然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。

-## 更新 / 卸载
+## 更新/卸载

 - 更新：[更新](/install/updating)
 - 迁移到新机器：[迁移](/install/migrating)
@@ -1,74 +1,74 @@
 ---
 read_when:
-  - 你正在将 OpenClaw 迁移到新的笔记本/服务器
-  - 你想保留会话、认证和渠道登录状态（WhatsApp 等）
+  - 你正在将 OpenClaw 迁移到新的笔记本电脑/服务器
+  - 你想保留会话、认证和渠道登录（WhatsApp 等）
 summary: 将 OpenClaw 安装从一台机器迁移到另一台
 title: 迁移指南
 x-i18n:
-  generated_at: "2026-02-01T21:08:21Z"
+  generated_at: "2026-02-03T07:49:55Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 604d862c4bf86e7924d09028db8cc2514ca6f1d64ebe8bb7d1e2dde57ef70caa
  source_path: install/migrating.md
-  workflow: 14
+  workflow: 15
 ---

 # 将 OpenClaw 迁移到新机器

-本指南介绍如何将 OpenClaw Gateway网关从一台机器迁移到另一台，**无需重新进行新手引导**。
+本指南将 OpenClaw Gateway 网关从一台机器迁移到另一台，**无需重新进行新手引导**。

 迁移在概念上很简单：

- 复制**状态目录**（`$OPENCLAW_STATE_DIR`，默认：`~/.openclaw/`）— 包含配置、认证、会话和渠道状态。
- 复制你的**工作区**（默认 `~/.openclaw/workspace/`）— 包含你的智能体文件（记忆、提示词等）。
+- 复制**状态目录**（`$OPENCLAW_STATE_DIR`，默认：`~/.openclaw/`）— 这包括配置、认证、会话和渠道状态。
+- 复制你的**工作区**（默认 `~/.openclaw/workspace/`）— 这包括你的智能体文件（记忆、提示等）。

-但在**配置文件**、**权限**和**不完整复制**方面有一些常见的坑。
+但在**配置文件**、**权限**和**部分复制**方面有常见的陷阱。

 ## 开始之前（你要迁移什么）

-### 1) 确认你的状态目录
+### 1）确定你的状态目录

-大多数安装使用默认路径：
+大多数安装使用默认值：

 - **状态目录：** `~/.openclaw/`

-但如果你使用了以下选项，路径可能不同：
+但如果你使用以下方式，可能会不同：

- `--profile <name>`（通常变为 `~/.openclaw-<profile>/`）
+- `--profile <name>`（通常变成 `~/.openclaw-<profile>/`）
 - `OPENCLAW_STATE_DIR=/some/path`

-如果不确定，在**旧**机器上运行：
+如果你不确定，在**旧**机器上运行：

 ```bash
 openclaw status
 ```

-在输出中查找 `OPENCLAW_STATE_DIR` / profile 的相关信息。如果你运行了多个 Gateway网关，请对每个配置文件重复操作。
+在输出中查找 `OPENCLAW_STATE_DIR` / profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。

-### 2) 确认你的工作区
+### 2）确定你的工作区

-常见默认路径：
+常见默认值：

- `~/.openclaw/workspace/`（推荐工作区）
+- `~/.openclaw/workspace/`（推荐的工作区）
 - 你创建的自定义文件夹

 你的工作区是 `MEMORY.md`、`USER.md` 和 `memory/*.md` 等文件所在的位置。

-### 3) 了解你将保留什么
+### 3）了解你将保留什么

-如果你**同时**复制状态目录和工作区，你将保留：
+如果你复制**两者**——状态目录和工作区，你将保留：

- Gateway网关配置（`openclaw.json`）
- 认证配置 / API 密钥 / OAuth 令牌
+- Gateway 网关配置（`openclaw.json`）
+- 认证配置文件 / API 密钥 / OAuth 令牌
 - 会话历史 + 智能体状态
 - 渠道状态（例如 WhatsApp 登录/会话）
 - 你的工作区文件（记忆、Skills 笔记等）

-如果你**只**复制工作区（例如通过 Git），你将**不会**保留：
+如果你**只**复制工作区（例如通过 Git），你**不会**保留：

 - 会话
- 凭据
- 渠道登录状态
+- 凭证
+- 渠道登录

 这些存储在 `$OPENCLAW_STATE_DIR` 下。

@@ -76,7 +76,7 @@ openclaw status

 ### 步骤 0 — 备份（旧机器）

-在**旧**机器上，先停止 Gateway网关以确保复制过程中文件不会变动：
+在**旧**机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：

 ```bash
 openclaw gateway stop
@@ -85,40 +85,40 @@ openclaw gateway stop
 （可选但推荐）归档状态目录和工作区：

 ```bash
-# 如果使用了配置文件或自定义路径，请调整路径
+# 如果你使用配置文件或自定义位置，请调整路径
 cd ~
 tar -czf openclaw-state.tgz .openclaw

 tar -czf openclaw-workspace.tgz .openclaw/workspace
 ```

-如果你有多个配置文件/状态目录（例如 `~/.openclaw-main`、`~/.openclaw-work`），请分别归档。
+如果你有多个配置文件/状态目录（例如 `~/.openclaw-main`、`~/.openclaw-work`），分别归档每个。

 ### 步骤 1 — 在新机器上安装 OpenClaw

-在**新**机器上安装 CLI（如有需要也安装 Node）：
+在**新**机器上，安装 CLI（如果需要还有 Node）：

 - 参见：[安装](/install)

-在此阶段，新手引导创建一个全新的 `~/.openclaw/` 是没问题的 — 你将在下一步覆盖它。
+在这个阶段，如果新手引导创建了一个新的 `~/.openclaw/` 也没关系 — 你将在下一步覆盖它。

 ### 步骤 2 — 将状态目录 + 工作区复制到新机器

-**同时**复制：
+复制**两者**：

 - `$OPENCLAW_STATE_DIR`（默认 `~/.openclaw/`）
 - 你的工作区（默认 `~/.openclaw/workspace/`）

-常用方法：
+常见方法：

- 通过 `scp` 传输压缩包并解压
+- `scp` 压缩包并解压
 - 通过 SSH 使用 `rsync -a`
- 外部存储设备
+- 外部驱动器

-复制后确保：
+复制后，确保：

- 隐藏目录已包含在内（例如 `.openclaw/`）
- 文件所有权对于运行 Gateway网关的用户是正确的
+- 包含了隐藏目录（例如 `.openclaw/`）
+- 文件所有权对于运行 Gateway 网关的用户是正确的

 ### 步骤 3 — 运行 Doctor（迁移 + 服务修复）

@@ -128,7 +128,7 @@ tar -czf openclaw-workspace.tgz .openclaw/workspace
 openclaw doctor
 ```

-Doctor 是"安全可靠"的命令。它会修复服务、应用配置迁移并警告不匹配的问题。
+Doctor 是"安全可靠"的命令。它修复服务、应用配置迁移，并警告不匹配问题。

 然后：

@@ -137,63 +137,63 @@ openclaw gateway restart
 openclaw status
 ```

-## 常见的坑（及如何避免）
+## 常见陷阱（以及如何避免）

-### 坑：配置文件 / 状态目录不匹配
+### 陷阱：配置文件/状态目录不匹配

-如果旧 Gateway网关使用了配置文件（或 `OPENCLAW_STATE_DIR`），而新 Gateway网关使用了不同的路径，你会看到以下症状：
+如果你在旧 Gateway 网关上使用了配置文件（或 `OPENCLAW_STATE_DIR`），而新 Gateway 网关使用了不同的配置，你会看到如下症状：

 - 配置更改不生效
- 渠道缺失 / 已登出
+- 渠道丢失/已登出
 - 会话历史为空

-修复：使用与迁移相同的配置文件/状态目录来运行 Gateway网关/服务，然后重新运行：
+修复：使用你迁移的**相同**配置文件/状态目录运行 Gateway 网关/服务，然后重新运行：

 ```bash
 openclaw doctor
 ```

-### 坑：只复制了 `openclaw.json`
+### 陷阱：只复制 `openclaw.json`

-`openclaw.json` 是不够的。许多提供商将状态存储在：
+`openclaw.json` 是不够的。许多提供商在以下位置存储状态：

 - `$OPENCLAW_STATE_DIR/credentials/`
 - `$OPENCLAW_STATE_DIR/agents/<agentId>/...`

 始终迁移整个 `$OPENCLAW_STATE_DIR` 文件夹。

-### 坑：权限 / 所有权
+### 陷阱：权限/所有权

-如果你以 root 身份复制或更换了用户，Gateway网关可能无法读取凭据/会话。
+如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证/会话。

-修复：确保状态目录 + 工作区的所有者是运行 Gateway网关的用户。
+修复：确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。

-### 坑：在远程/本地模式之间迁移
+### 陷阱：在远程/本地模式之间迁移

- 如果你的界面（WebUI/TUI）指向**远程** Gateway网关，则远程主机拥有会话存储 + 工作区。
- 迁移你的笔记本不会移动远程 Gateway网关的状态。
+- 如果你的 UI（WebUI/TUI）指向**远程** Gateway 网关，远程主机拥有会话存储 + 工作区。
+- 迁移你的笔记本电脑不会移动远程 Gateway 网关的状态。

-如果你处于远程模式，请迁移 **Gateway网关主机**。
+如果你处于远程模式，请迁移 **Gateway 网关主机**。

-### 坑：备份中的密钥
+### 陷阱：备份中的密钥

-`$OPENCLAW_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭据）。请将备份视为生产密钥：
+`$OPENCLAW_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：

 - 加密存储
- 避免通过不安全的渠道传输
- 如果怀疑泄露，请轮换密钥
+- 避免通过不安全的渠道共享
+- 如果怀疑泄露，轮换密钥

-## 验证清单
+## 验证检查清单

-在新机器上确认：
+在新机器上，确认：

- `openclaw status` 显示 Gateway网关正在运行
- 你的渠道仍然处于连接状态（例如 WhatsApp 无需重新配对）
- 仪表盘可以打开并显示现有会话
- 你的工作区文件（记忆、配置）已存在
+- `openclaw status` 显示 Gateway 网关正在运行
+- 你的渠道仍然连接（例如 WhatsApp 不需要重新配对）
+- 仪表板打开并显示现有会话
+- 你的工作区文件（记忆、配置）存在

 ## 相关内容

 - [Doctor](/gateway/doctor)
- [Gateway网关故障排除](/gateway/troubleshooting)
- [OpenClaw 将数据存储在哪里？](/help/faq#where-does-openclaw-store-its-data)
+- [Gateway 网关故障排除](/gateway/troubleshooting)
+- [OpenClaw 在哪里存储数据？](/help/faq#where-does-openclaw-store-its-data)
@@ -1,17 +1,17 @@
 ---
 read_when:
-  - 你想要可复现、可回滚的安装方式
+  - 你想要可复现、可回滚的安装
  - 你已经在使用 Nix/NixOS/Home Manager
-  - 你想要一切固定且声明式管理
+  - 你想要所有内容都固定并以声明式管理
 summary: 使用 Nix 声明式安装 OpenClaw
 title: Nix
 x-i18n:
-  generated_at: "2026-02-01T21:08:16Z"
+  generated_at: "2026-02-03T07:49:51Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: f1452194cfdd74613b5b3ab90b0d506eaea2d16b147497987710d6ad658312ba
  source_path: install/nix.md
-  workflow: 14
+  workflow: 15
 ---

 # Nix 安装
@@ -20,7 +20,7 @@ x-i18n:

 ## 快速开始

-将以下内容粘贴给你的 AI 智能体（Claude、Cursor 等）：
+将此粘贴给你的 AI 智能体（Claude、Cursor 等）：

 ```text
 I want to set up nix-openclaw on my Mac.
@@ -39,30 +39,29 @@ Reference the nix-openclaw README for module options.

 > **📦 完整指南：[github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)**
 >
-> nix-openclaw 仓库是 Nix 安装的权威来源。本页仅为简要概览。
+> nix-openclaw 仓库是 Nix 安装的权威来源。本页只是一个快速概述。

 ## 你将获得

- Gateway网关 + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
- 可在重启后保持运行的 Launchd 服务
- 带声明式配置的插件系统
+- Gateway 网关 + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
+- 重启后仍能运行的 Launchd 服务
+- 带有声明式配置的插件系统
 - 即时回滚：`home-manager switch --rollback`

 ---

 ## Nix 模式运行时行为

-当设置了 `OPENCLAW_NIX_MODE=1` 时（nix-openclaw 会自动设置）：
+当设置 `OPENCLAW_NIX_MODE=1` 时（nix-openclaw 会自动设置）：

-OpenClaw 支持 **Nix 模式**，使配置具有确定性并禁用自动安装流程。
+OpenClaw 支持 **Nix 模式**，使配置确定性并禁用自动安装流程。
 通过导出以下环境变量启用：

 ```bash
 OPENCLAW_NIX_MODE=1
 ```

-在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以
-通过 defaults 启用 Nix 模式：
+在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以通过 defaults 启用 Nix 模式：

 ```bash
 defaults write bot.molt.mac openclaw.nixMode -bool true
@@ -75,29 +74,26 @@ OpenClaw 从 `OPENCLAW_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存
 - `OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）
 - `OPENCLAW_CONFIG_PATH`（默认：`$OPENCLAW_STATE_DIR/openclaw.json`）

-在 Nix 下运行时，请将这些路径显式设置为 Nix 管理的位置，以便运行时状态和配置
-不会进入不可变存储。
+在 Nix 下运行时，将这些显式设置为 Nix 管理的位置，以便运行时状态和配置不会进入不可变存储。

 ### Nix 模式下的运行时行为

- 自动安装和自我变更流程被禁用
- 缺失依赖会显示 Nix 特定的修复建议
- UI 在启用时会显示只读的 Nix 模式横幅
+- 自动安装和自我修改流程被禁用
+- 缺失的依赖会显示 Nix 特定的修复消息
+- 存在时 UI 会显示只读 Nix 模式横幅

-## 打包说明（macOS）
+## 打包注意事项（macOS）

-macOS 打包流程需要一个稳定的 Info.plist 模板，位于：
+macOS 打包流程期望在以下位置有一个稳定的 Info.plist 模板：

 ```
 apps/macos/Sources/OpenClaw/Resources/Info.plist
 ```

-[`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 将此模板复制到应用包中并修补动态字段
-（bundle ID、版本/构建号、Git SHA、Sparkle 密钥）。这使得 plist 对 SwiftPM
-打包和 Nix 构建保持确定性（它们不依赖完整的 Xcode 工具链）。
+[`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 将此模板复制到应用包中并修补动态字段（bundle ID、版本/构建号、Git SHA、Sparkle 密钥）。这使 plist 对于 SwiftPM 打包和 Nix 构建保持确定性（它们不依赖完整的 Xcode 工具链）。

 ## 相关内容

 - [nix-openclaw](https://github.com/openclaw/nix-openclaw) — 完整设置指南
- [向导](/start/wizard) — 非 Nix 的 CLI 设置
+- [向导](/start/wizard) — 非 Nix CLI 设置
 - [Docker](/install/docker) — 容器化设置
@@ -1,11 +1,11 @@
 ---
 read_when:
  - 你想从机器上移除 OpenClaw
-  - 卸载后 Gateway网关服务仍在运行
+  - 卸载后 Gateway 网关服务仍在运行
 summary: 完全卸载 OpenClaw（CLI、服务、状态、工作区）
 title: 卸载
 x-i18n:
-  generated_at: "2026-02-01T21:16:21Z"
+  generated_at: "2026-02-03T07:50:10Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: 6673a755c5e1f90a807dd8ac92a774cff6d1bc97d125c75e8bf72a40e952a777
@@ -17,10 +17,10 @@ x-i18n:

 两种方式：

- **简易方式**：`openclaw` 仍已安装时使用。
- **手动移除服务**：CLI 已删除但服务仍在运行时使用。
+- 如果 `openclaw` 仍已安装，使用**简单方式**。
+- 如果 CLI 已删除但服务仍在运行，使用**手动服务移除**。

-## 简易方式（CLI 仍已安装）
+## 简单方式（CLI 仍已安装）

 推荐：使用内置卸载程序：

@@ -28,7 +28,7 @@ x-i18n:
 openclaw uninstall
 ```

-非交互模式（自动化 / npx）：
+非交互式（自动化 / npx）：

 ```bash
 openclaw uninstall --all --yes --non-interactive
@@ -37,33 +37,33 @@ npx -y openclaw uninstall --all --yes --non-interactive

 手动步骤（效果相同）：

-1. 停止 Gateway网关服务：
+1. 停止 Gateway 网关服务：

 ```bash
 openclaw gateway stop
 ```

-2. 卸载 Gateway网关服务（launchd/systemd/schtasks）：
+2. 卸载 Gateway 网关服务（launchd/systemd/schtasks）：

 ```bash
 openclaw gateway uninstall
 ```

-3. 删除状态和配置：
+3. 删除状态 + 配置：

 ```bash
 rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
 ```

-如果你将 `OPENCLAW_CONFIG_PATH` 设置为状态目录之外的自定义位置，请同时删除该文件。
+如果你将 `OPENCLAW_CONFIG_PATH` 设置为状态目录外的自定义位置，也请删除该文件。

-4. 删除工作区（可选，会移除智能体文件）：
+4. 删除你的工作区（可选，移除智能体文件）：

 ```bash
 rm -rf ~/.openclaw/workspace
 ```

-5. 移除 CLI 安装（选择你使用的方式）：
+5. 移除 CLI 安装（选择你使用的那个）：

 ```bash
 npm rm -g openclaw
@@ -79,27 +79,27 @@ rm -rf /Applications/OpenClaw.app

 注意事项：

- 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请对每个状态目录重复步骤 3（默认为 `~/.openclaw-<profile>`）。
- 在远程模式下，状态目录位于 **Gateway网关主机**上，因此也需要在那里执行步骤 1-4。
+- 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），对每个状态目录重复步骤 3（默认为 `~/.openclaw-<profile>`）。
+- 在远程模式下，状态目录位于 **Gateway 网关主机**上，因此也需要在那里运行步骤 1-4。

-## 手动移除服务（CLI 未安装）
+## 手动服务移除（CLI 未安装）

-当 Gateway网关服务持续运行但 `openclaw` 已不存在时使用此方式。
+如果 Gateway 网关服务持续运行但 `openclaw` 缺失，请使用此方法。

-### macOS (launchd)
+### macOS（launchd）

-默认标签为 `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 可能仍然存在）：
+默认标签是 `bot.molt.gateway`（或 `bot.molt.<profile>`；旧版 `com.openclaw.*` 可能仍然存在）：

 ```bash
 launchctl bootout gui/$UID/bot.molt.gateway
 rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist
 ```

-如果你使用了配置文件，请将标签和 plist 名称替换为 `bot.molt.<profile>`。如存在旧版 `com.openclaw.*` plist 文件，请一并移除。
+如果你使用了配置文件，请将标签和 plist 名称替换为 `bot.molt.<profile>`。如果存在任何旧版 `com.openclaw.*` plist，请将其移除。

 ### Linux（systemd 用户单元）

-默认单元名称为 `openclaw-gateway.service`（或 `openclaw-gateway-<profile>.service`）：
+默认单元名称是 `openclaw-gateway.service`（或 `openclaw-gateway-<profile>.service`）：

 ```bash
 systemctl --user disable --now openclaw-gateway.service
@@ -109,27 +109,27 @@ systemctl --user daemon-reload

 ### Windows（计划任务）

-默认任务名称为 `OpenClaw Gateway网关`（或 `OpenClaw Gateway网关 (<profile>)`）。
+默认任务名称是 `OpenClaw Gateway`（或 `OpenClaw Gateway (<profile>)`）。
 任务脚本位于你的状态目录下。

 ```powershell
-schtasks /Delete /F /TN "OpenClaw Gateway网关"
+schtasks /Delete /F /TN "OpenClaw Gateway"
 Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"
 ```

-如果你使用了配置文件，请删除对应的任务名称和 `~\.openclaw-<profile>\gateway.cmd`。
+如果你使用了配置文件，请删除匹配的任务名称和 `~\.openclaw-<profile>\gateway.cmd`。

-## 常规安装与源码检出
+## 普通安装 vs 源码检出

-### 常规安装（install.sh / npm / pnpm / bun）
+### 普通安装（install.sh / npm / pnpm / bun）

 如果你使用了 `https://openclaw.ai/install.sh` 或 `install.ps1`，CLI 是通过 `npm install -g openclaw@latest` 安装的。
-使用 `npm rm -g openclaw` 移除（如果你使用的是其他方式，则用 `pnpm remove -g` / `bun remove -g`）。
+使用 `npm rm -g openclaw` 移除（或 `pnpm remove -g` / `bun remove -g`，如果你是用那种方式安装的）。

 ### 源码检出（git clone）

 如果你从仓库检出运行（`git clone` + `openclaw ...` / `bun run openclaw ...`）：

-1. 在删除仓库**之前**先卸载 Gateway网关服务（使用上述简易方式或手动移除服务）。
+1. 在删除仓库**之前**卸载 Gateway 网关服务（使用上面的简单方式或手动服务移除）。
 2. 删除仓库目录。
-3. 按上述方式移除状态和工作区。
+3. 按上述方式移除状态 + 工作区。
@@ -2,52 +2,52 @@
 read_when:
  - 更新 OpenClaw
  - 更新后出现问题
-summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略
+summary: 安全更新 OpenClaw（全局安装或源码），以及回滚策略
 title: 更新
 x-i18n:
-  generated_at: "2026-02-01T21:16:51Z"
+  generated_at: "2026-02-03T07:50:25Z"
  model: claude-opus-4-5
  provider: pi
-  source_hash: 612b2519cf3e4a2c2d0f01575c3fa75ab1c88a6fed9e59477bf27395beda03c1
+  source_hash: 38cccac0839f0f22403b6508cd94ba1b401133ffc1d92d4f7640b8d04e082317
  source_path: install/updating.md
  workflow: 15
 ---

 # 更新

-OpenClaw 迭代速度很快（尚未到"1.0"）。请像对待基础设施发布一样对待更新：更新 → 运行检查 → 重启（或使用 `openclaw update`，它会自动重启）→ 验证。
+OpenClaw 发展迅速（尚未到"1.0"）。将更新视为发布基础设施：更新 → 运行检查 → 重启（或使用会重启的 `openclaw update`）→ 验证。

-## 推荐方式：重新运行网站安装程序（原地升级）
+## 推荐：重新运行网站安装程序（原地升级）

-**首选**更新路径是重新运行网站上的安装程序。它会检测现有安装、原地升级，并在需要时运行 `openclaw doctor`。
+**首选**的更新路径是重新运行网站上的安装程序。它会检测现有安装、原地升级，并在需要时运行 `openclaw doctor`。

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

-注意事项：
+说明：

- 如果不想再次运行新手引导向导，请添加 `--no-onboard`。
- 对于**源码安装**，请使用：
+- 如果你不想再次运行新手引导向导，添加 `--no-onboard`。
+- 对于**源码安装**，使用：
  ```bash
  curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
  ```
-  安装程序**仅在**仓库工作区干净时才会执行 `git pull --rebase`。
+  安装程序**仅**在仓库干净时才会执行 `git pull --rebase`。
 - 对于**全局安装**，脚本底层使用 `npm install -g openclaw@latest`。
- 兼容性说明：`openclaw` 仍可作为兼容性垫片使用。
+- 旧版说明：`clawdbot` 仍可作为兼容性垫片使用。

-## 更新前的准备
+## 更新之前

- 了解你的安装方式：**全局安装**（npm/pnpm）还是**源码安装**（git clone）。
- 了解你的 Gateway网关运行方式：**前台终端**还是**受监控服务**（launchd/systemd）。
- 备份你的自定义配置：
-  - 配置文件：`~/.openclaw/openclaw.json`
-  - 凭据：`~/.openclaw/credentials/`
+- 了解你的安装方式：**全局**（npm/pnpm）还是**源码**（git clone）。
+- 了解你的 Gateway 网关运行方式：**前台终端**还是**受管理服务**（launchd/systemd）。
+- 快照你的定制内容：
+  - 配置：`~/.openclaw/openclaw.json`
+  - 凭证：`~/.openclaw/credentials/`
  - 工作区：`~/.openclaw/workspace`

 ## 更新（全局安装）

-全局安装（任选其一）：
+全局安装（选择一个）：

 ```bash
 npm i -g openclaw@latest
@@ -57,7 +57,7 @@ npm i -g openclaw@latest
 pnpm add -g openclaw@latest
 ```

-我们**不建议**使用 Bun 作为 Gateway网关运行时（存在 WhatsApp/Telegram 相关 bug）。
+我们**不**推荐将 Bun 用于 Gateway 网关运行时（WhatsApp/Telegram 有 bug）。

 切换更新渠道（git + npm 安装）：

@@ -67,11 +67,11 @@ openclaw update --channel dev
 openclaw update --channel stable
 ```

-使用 `--tag <dist-tag|version>` 进行一次性指定标签/版本安装。
+使用 `--tag <dist-tag|version>` 进行一次性安装指定标签/版本。

-有关渠道语义和发布说明，请参阅[开发渠道](/install/development-channels)。
+渠道语义和发布说明参见[开发渠道](/install/development-channels)。

-注意：在 npm 安装中，Gateway网关启动时会记录更新提示（检查当前渠道标签）。可通过 `update.checkOnStart: false` 禁用。
+注意：在 npm 安装上，Gateway 网关在启动时会记录更新提示（检查当前渠道标签）。通过 `update.checkOnStart: false` 禁用。

 然后：

@@ -81,50 +81,50 @@ openclaw gateway restart
 openclaw health
 ```

-注意事项：
+说明：

- 如果你的 Gateway网关作为服务运行，建议使用 `openclaw gateway restart` 而非直接终止 PID。
- 如果你固定在特定版本，请参阅下方的"回滚/版本固定"。
+- 如果你的 Gateway 网关作为服务运行，`openclaw gateway restart` 优于杀死 PID。
+- 如果你固定在特定版本，参见下面的"回滚/固定"。

 ## 更新（`openclaw update`）

-对于**源码安装**（git checkout），推荐使用：
+对于**源码安装**（git checkout），首选：

 ```bash
 openclaw update
 ```

-它会执行一个相对安全的更新流程：
+它运行一个相对安全的更新流程：

- 要求工作区干净。
- 切换到所选渠道（标签或分支）。
- 从配置的上游（dev 渠道）拉取并变基。
- 安装依赖、构建、构建控制面板 UI，并运行 `openclaw doctor`。
- 默认重启 Gateway网关（使用 `--no-restart` 跳过）。
+- 需要干净的工作树。
+- 切换到选定的渠道（标签或分支）。
+- 获取并 rebase 到配置的上游（dev 渠道）。
+- 安装依赖、构建、构建控制 UI，并运行 `openclaw doctor`。
+- 默认重启 Gateway 网关（使用 `--no-restart` 跳过）。

-如果你通过 **npm/pnpm** 安装（无 git 元数据），`openclaw update` 会尝试通过你的包管理器进行更新。如果无法检测到安装方式，请改用"更新（全局安装）"。
+如果你通过 **npm/pnpm** 安装（没有 git 元数据），`openclaw update` 将尝试通过你的包管理器更新。如果无法检测到安装，请改用"更新（全局安装）"。

-## 更新（控制面板 UI / RPC）
+## 更新（控制 UI / RPC）

-控制面板 UI 提供**更新并重启**功能（RPC：`update.run`）。它会：
+控制 UI 有**更新并重启**（RPC：`update.run`）。它：

-1. 执行与 `openclaw update` 相同的源码更新流程（仅限 git checkout）。
-2. 写入重启哨兵文件及结构化报告（stdout/stderr 尾部内容）。
-3. 重启 Gateway网关并向最近活跃的会话发送报告。
+1. 运行与 `openclaw update` 相同的源码更新流程（仅限 git checkout）。
+2. 写入带有结构化报告（stdout/stderr 尾部）的重启哨兵。
+3. 重启 Gateway 网关并向最后活跃的会话 ping 报告。

-如果变基失败，Gateway网关会中止并在不应用更新的情况下重启。
+如果 rebase 失败，Gateway 网关会中止并在不应用更新的情况下重启。

-## 更新（源码安装）
+## 更新（从源码）

-从仓库检出目录：
+从仓库 checkout：

-推荐方式：
+首选：

 ```bash
 openclaw update
 ```

-手动方式（大致等效）：
+手动（大致等效）：

 ```bash
 git pull
@@ -135,32 +135,32 @@ openclaw doctor
 openclaw health
 ```

-注意事项：
+说明：

- 当你运行打包后的 `openclaw` 二进制文件（[`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)）或使用 Node 运行 `dist/` 时，`pnpm build` 很重要。
- 如果你从仓库检出运行而没有全局安装，请使用 `pnpm openclaw ...` 执行 CLI 命令。
+- 当你运行打包的 `openclaw` 二进制文件（[`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)）或使用 Node 运行 `dist/` 时，`pnpm build` 很重要。
+- 如果你从仓库 checkout 运行而没有全局安装，CLI 命令使用 `pnpm openclaw ...`。
 - 如果你直接从 TypeScript 运行（`pnpm openclaw ...`），通常不需要重新构建，但**配置迁移仍然适用** → 运行 doctor。
- 在全局安装和 git 安装之间切换很容易：安装另一种方式，然后运行 `openclaw doctor`，这样 Gateway网关服务入口点会被重写为当前安装。
+- 在全局和 git 安装之间切换很容易：安装另一种方式，然后运行 `openclaw doctor` 以便将 Gateway 网关服务入口点重写为当前安装。

-## 必须执行：`openclaw doctor`
+## 始终运行：`openclaw doctor`

-Doctor 是"安全更新"命令。它有意设计得很朴素：修复 + 迁移 + 警告。
+Doctor 是"安全更新"命令。它故意很无聊：修复 + 迁移 + 警告。

-注意：如果你使用的是**源码安装**（git checkout），`openclaw doctor` 会建议先运行 `openclaw update`。
+注意：如果你是**源码安装**（git checkout），`openclaw doctor` 会提供先运行 `openclaw update`。

-它通常执行以下操作：
+它通常做的事情：

- 迁移已弃用的配置键 / 旧版配置文件位置。
- 审核私信策略并对高风险的"开放"设置发出警告。
- 检查 Gateway网关健康状态并可建议重启。
- 检测并将旧版 Gateway网关服务（launchd/systemd；旧版 schtasks）迁移到当前的 OpenClaw 服务。
- 在 Linux 上，确保 systemd 用户 lingering（使 Gateway网关在登出后继续运行）。
+- 迁移已弃用的配置键/旧版配置文件位置。
+- 审计私信策略并对有风险的"开放"设置发出警告。
+- 检查 Gateway 网关健康状况，可以提供重启。
+- 检测并将旧版 Gateway 网关服务（launchd/systemd；旧版 schtasks）迁移到当前 OpenClaw 服务。
+- 在 Linux 上，确保 systemd 用户 lingering（这样 Gateway 网关在登出后仍能存活）。

 详情：[Doctor](/gateway/doctor)

-## 启动/停止/重启 Gateway网关
+## 启动/停止/重启 Gateway 网关

-CLI（适用于所有操作系统）：
+CLI（无论操作系统都适用）：

 ```bash
 openclaw gateway status
@@ -170,20 +170,20 @@ openclaw gateway --port 18789
 openclaw logs --follow
 ```

-如果使用服务管理：
+如果你使用受管理服务：

- macOS launchd（应用捆绑的 LaunchAgent）：`launchctl kickstart -k gui/$UID/bot.molt.gateway`（使用 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍可用）
+- macOS launchd（应用捆绑的 LaunchAgent）：`launchctl kickstart -k gui/$UID/bot.molt.gateway`（使用 `bot.molt.<profile>`；旧版 `com.openclaw.*` 仍然有效）
 - Linux systemd 用户服务：`systemctl --user restart openclaw-gateway[-<profile>].service`
 - Windows（WSL2）：`systemctl --user restart openclaw-gateway[-<profile>].service`
-  - `launchctl`/`systemctl` 仅在服务已安装时有效；否则请运行 `openclaw gateway install`。
+  - `launchctl`/`systemctl` 仅在服务已安装时有效；否则运行 `openclaw gateway install`。

-运维手册及完整服务标签：[Gateway网关运维手册](/gateway)
+运行手册 + 确切的服务标签：[Gateway 网关运行手册](/gateway)

-## 回滚/版本固定（出现问题时）
+## 回滚/固定（当出问题时）

-### 版本固定（全局安装）
+### 固定（全局安装）

-安装一个已知可用的版本（将 `<version>` 替换为上一个正常工作的版本）：
+安装已知良好的版本（将 `<version>` 替换为最后可用的版本）：

 ```bash
 npm i -g openclaw@<version>
@@ -193,25 +193,25 @@ npm i -g openclaw@<version>
 pnpm add -g openclaw@<version>
 ```

-提示：要查看当前已发布的版本，请运行 `npm view openclaw version`。
+提示：要查看当前发布的版本，运行 `npm view openclaw version`。

-然后重启并重新运行 doctor：
+然后重启 + 重新运行 doctor：

 ```bash
 openclaw doctor
 openclaw gateway restart
 ```

-### 版本固定（源码安装）按日期
+### 按日期固定（源码）

-选取某个日期的提交（示例："main 分支截至 2026-01-01 的状态"）：
+选择某个日期的提交（示例："2026-01-01 时 main 的状态"）：

 ```bash
 git fetch origin
 git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
 ```

-然后重新安装依赖并重启：
+然后重新安装依赖 + 重启：

 ```bash
 pnpm install
@@ -219,15 +219,15 @@ pnpm build
 openclaw gateway restart
 ```

-如果之后想回到最新版本：
+如果你之后想回到最新版本：

 ```bash
 git checkout main
 git pull
 ```

-## 如果你遇到困难
+## 如果你卡住了

 - 再次运行 `openclaw doctor` 并仔细阅读输出（它通常会告诉你修复方法）。
 - 查看：[故障排除](/gateway/troubleshooting)
- 在 Discord 中提问：https://discord.gg/clawd
+- 在 Discord 上提问：https://discord.gg/clawd