github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-28 10:08:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: add zh-CN translations

Browse Source
This commit is contained in:
Josh Palmer
2026-02-01 22:47:44 +01:00
parent e70984745b
commit 149dc7c4e7
298 changed files with 53861 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

215
docs/zh-CN/install/ansible.md Normal file
View File

@@ -0,0 +1,215 @@
---
read_when:
- 你需要通过安全加固进行自动化服务器部署
- 你需要带 VPN 访问的防火墙隔离设置
- 你要部署到远程 Debian/Ubuntu 服务器
summary: 使用 Ansible、Tailscale VPN 和防火墙隔离进行自动化、安全加固的 OpenClaw 安装
title: Ansible
x-i18n:
generated_at: "2026-02-01T21:05:32Z"
model: claude-opus-4-5
provider: pi
source_hash: 896807f344d923f09039f377c13b4bf4a824aa94eec35159fc169596a3493b29
source_path: install/ansible.md
workflow: 14
---
# Ansible 安装
将 OpenClaw 部署到生产服务器的推荐方式是使用 **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** — 一个采用安全优先架构的自动化安装工具。
## 快速开始
一条命令安装：
```bash
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
```
> **📦 完整指南：[github.com/openclaw/openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**
>
> openclaw-ansible 仓库是 Ansible 部署的权威来源。本页面仅为简要概览。
## 你将获得
- 🔒 **防火墙优先的安全策略**：UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
- 🔐 **Tailscale VPN**：安全的远程访问，无需公开暴露服务
- 🐳 **Docker**：隔离的沙箱容器，仅绑定 localhost
- 🛡️ **纵深防御**：4 层安全架构
- 🚀 **一条命令部署**：几分钟内完成完整部署
- 🔧 **Systemd 集成**：开机自启并带有安全加固
## 前置要求
- **操作系统**：Debian 11+ 或 Ubuntu 20.04+
- **访问权限**：Root 或 sudo 权限
- **网络**：用于安装软件包的互联网连接
- **Ansible**：2.14+（快速启动脚本会自动安装）
## 安装内容
Ansible playbook 会安装并配置以下组件：
1. **Tailscale**（用于安全远程访问的 mesh VPN）
2. **UFW 防火墙**（仅开放 SSH + Tailscale 端口）
3. **Docker CE + Compose V2**（用于智能体沙箱）
4. **Node.js 22.x + pnpm**（运行时依赖）
5. **OpenClaw**（基于主机安装，非容器化）
6. **Systemd 服务**（带安全加固的自动启动）
注意：Gateway **直接运行在主机上**（不在 Docker 中），但智能体沙箱使用 Docker 进行隔离。详见 [沙箱](/gateway/sandboxing)。
## 安装后设置
安装完成后，切换到 openclaw 用户：
```bash
sudo -i -u openclaw
```
安装后脚本将引导你完成：
1. **上手引导向导**：配置 OpenClaw 设置
2. **提供商登录**：连接 WhatsApp/Telegram/Discord/Signal
3. **Gateway 测试**：验证安装
4. **Tailscale 设置**：连接到你的 VPN mesh 网络
### 常用命令
```bash
# 检查服务状态
sudo systemctl status openclaw
# 查看实时日志
sudo journalctl -u openclaw -f
# 重启 Gateway
sudo systemctl restart openclaw
# 提供商登录（以 openclaw 用户运行）
sudo -i -u openclaw
openclaw channels login
```
## 安全架构
### 4 层防御
1. **防火墙（UFW）**：仅公开暴露 SSH (22) + Tailscale (41641/udp)
2. **VPN（Tailscale）**：Gateway 仅可通过 VPN mesh 网络访问
3. **Docker 隔离**：DOCKER-USER iptables 链阻止外部端口暴露
4. **Systemd 加固**：NoNewPrivileges、PrivateTmp、非特权用户
### 验证
测试外部攻击面：
```bash
nmap -p- YOUR_SERVER_IP
```
应当仅显示**端口 22**（SSH）为开放状态。所有其他服务（Gateway、Docker）均已锁定。
### Docker 可用性
Docker 用于**智能体沙箱**（隔离的工具执行），而非运行 Gateway 本身。Gateway 仅绑定到 localhost，通过 Tailscale VPN 访问。
沙箱配置详见 [多智能体沙箱与工具](/multi-agent-sandbox-tools)。
## 手动安装
如果你希望手动控制而非使用自动化：
```bash
# 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 集合
ansible-galaxy collection install -r requirements.yml
# 4. 运行 playbook
./run-playbook.sh
# 或直接运行（之后手动执行 /tmp/openclaw-setup.sh）
# ansible-playbook playbook.yml --ask-become-pass
```
## 更新 OpenClaw
Ansible 安装程序将 OpenClaw 设置为手动更新。标准更新流程详见 [更新](/install/updating)。
重新运行 Ansible playbook（例如配置变更时）：
```bash
cd openclaw-ansible
./run-playbook.sh
```
注意：此操作是幂等的，可以安全地多次运行。
## 故障排除
### 防火墙阻止了我的连接
如果你被锁定在外：
- 确保先通过 Tailscale VPN 访问
- SSH 访问（端口 22）始终是允许的
- Gateway **仅**可通过 Tailscale 访问，这是设计如此
### 服务无法启动
```bash
# 检查日志
sudo journalctl -u openclaw -n 100
# 验证权限
sudo ls -la /opt/openclaw
# 测试手动启动
sudo -i -u openclaw
cd ~/openclaw
pnpm start
```
### Docker 沙箱问题
```bash
# 验证 Docker 是否运行
sudo systemctl status docker
# 检查沙箱镜像
sudo docker images | grep openclaw-sandbox
# 如果缺少沙箱镜像则构建
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh
```
### 提供商登录失败
确保你以 `openclaw` 用户运行：
```bash
sudo -i -u openclaw
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/troubleshooting.md)
## 相关内容
- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — 完整部署指南
- [Docker](/install/docker) — 容器化 Gateway 设置
- [沙箱](/gateway/sandboxing) — 智能体沙箱配置
- [多智能体沙箱与工具](/multi-agent-sandbox-tools) — 按智能体隔离

65
docs/zh-CN/install/bun.md Normal file
View File

@@ -0,0 +1,65 @@
---
read_when:
- 你想要最快的本地开发循环（bun + watch）
- 你遇到了 Bun 安装/补丁/生命周期脚本问题
summary: Bun 工作流（实验性）：安装方式及与 pnpm 相比的注意事项
title: Bun（实验性）
x-i18n:
generated_at: "2026-02-01T21:05:42Z"
model: claude-opus-4-5
provider: pi
source_hash: eb3f4c222b6bae49938d8bf53a0818fe5f5e0c0c3c1adb3e0a832ce8f785e1e3
source_path: install/bun.md
workflow: 14
---
# Bun（实验性）
目标：使用 **Bun** 运行本仓库（可选，不推荐用于 WhatsApp/Telegram），同时不偏离 pnpm 工作流。
⚠️ **不推荐用于 Gateway 运行时**（WhatsApp/Telegram 存在 bug）。生产环境请使用 Node。
## 状态
- Bun 是一个可选的本地运行时，用于直接运行 TypeScript（`bun run …`、`bun --watch …`）。
- `pnpm` 是默认的构建工具，仍然完全受支持（部分文档工具也在使用）。
- Bun 无法使用 `pnpm-lock.yaml`，会将其忽略。
## 安装
默认方式：
```sh
bun install
```
注意：`bun.lock`/`bun.lockb` 已被 gitignore，因此不会造成仓库变动。如果你不想写入锁文件：
```sh
bun install --no-save
```
## 构建 / 测试（Bun）
```sh
bun run build
bun run vitest run
```
## Bun 生命周期脚本（默认被阻止）
Bun 可能会阻止依赖的生命周期脚本，除非显式信任（`bun pm untrusted` / `bun pm trust`）。
对于本仓库，常见被阻止的脚本并非必需：
- `@whiskeysockets/baileys` `preinstall`：检查 Node 主版本 >= 20（我们运行 Node 22+）。
- `protobufjs` `postinstall`：发出关于不兼容版本方案的警告（无构建产物）。
如果你遇到确实需要这些脚本的运行时问题，请显式信任它们：
```sh
bun pm trust @whiskeysockets/baileys protobufjs
```
## 注意事项
- 部分脚本仍硬编码使用 pnpm（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请通过 pnpm 运行这些脚本。

79
docs/zh-CN/install/development-channels.md Normal file
View File

@@ -0,0 +1,79 @@
---
read_when:
- 你想在稳定版/测试版/开发版之间切换
- 你正在标记或发布预发布版本
summary: 稳定版、测试版和开发版渠道：语义、切换和标签管理
title: 开发渠道
x-i18n:
generated_at: "2026-02-01T21:05:54Z"
model: claude-opus-4-5
provider: pi
source_hash: 2b01219b7e705044ce39838a0da7c7fa65c719809ab2f8a51e14529064af81bf
source_path: install/development-channels.md
workflow: 14
---
# 开发渠道
最后更新：2026-01-21
OpenClaw 提供三个更新渠道：
- **stable**：npm dist-tag `latest`。
- **beta**：npm dist-tag `beta`（测试中的构建）。
- **dev**：`main` 分支的最新提交（git）。npm dist-tag：`dev`（发布时）。
我们将构建发布到 **beta**，进行测试，然后**将经过验证的构建提升为 `latest`**，无需更改版本号 — dist-tag 是 npm 安装的权威来源。
## 切换渠道
Git checkout 方式：
```bash
openclaw update --channel stable
openclaw update --channel beta
openclaw update --channel dev
```
- `stable`/`beta` 会签出最新匹配的标签（通常是同一个标签）。
- `dev` 切换到 `main` 并在上游基础上进行 rebase。
npm/pnpm 全局安装方式：
```bash
openclaw update --channel stable
openclaw update --channel beta
openclaw update --channel dev
```
这会通过对应的 npm dist-tag（`latest`、`beta`、`dev`）进行更新。
当你**显式**使用 `--channel` 切换渠道时，OpenClaw 也会同步调整安装方式：
- `dev` 确保存在 git checkout（默认 `~/openclaw`，可通过 `OPENCLAW_GIT_DIR` 覆盖），更新它，并从该 checkout 安装全局 CLI。
- `stable`/`beta` 使用匹配的 dist-tag 从 npm 安装。
提示：如果你想同时使用 stable 和 dev，可以保留两个克隆，并将 Gateway 指向 stable 的那个。
## 插件与渠道
使用 `openclaw update` 切换渠道时，OpenClaw 也会同步插件来源：
- `dev` 优先使用 git checkout 中内置的插件。
- `stable` 和 `beta` 恢复通过 npm 安装的插件包。
## 标签最佳实践
- 为你希望 git checkout 落到的版本打标签（`vYYYY.M.D` 或 `vYYYY.M.D-<patch>`）。
- 保持标签不可变：永远不要移动或重用标签。
- npm dist-tag 仍然是 npm 安装的权威来源：
- `latest` → 稳定版
- `beta` → 候选构建
- `dev` → main 快照（可选）
## macOS 应用可用性
测试版和开发版构建可能**不包含** macOS 应用发布。这是正常的：
- git 标签和 npm dist-tag 仍然可以发布。
- 在发布说明或变更日志中注明"此测试版无 macOS 构建"即可。

461
docs/zh-CN/install/docker.md Normal file
View File

@@ -0,0 +1,461 @@
---
read_when:
- 你想要容器化的 Gateway 而非本地安装
- 你正在验证 Docker 流程
summary: 可选的基于 Docker 的 OpenClaw 设置和上手引导
title: Docker
x-i18n:
generated_at: "2026-02-01T21:07:14Z"
model: claude-opus-4-5
provider: pi
source_hash: 781dd01ca99a2101f622f03162eb1776079c3c444f54c5a054d6816ec203e2f2
source_path: install/docker.md
workflow: 14
---
# Docker（可选）
Docker 是**可选的**。仅在你需要容器化 Gateway 或验证 Docker 流程时使用。
## Docker 适合我吗？
- **适合**：你需要一个隔离的、可随时销毁的 Gateway 环境，或者想在无需本地安装的主机上运行 OpenClaw。
- **不适合**：你在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
- **沙箱说明**：智能体沙箱也使用 Docker，但它**不需要**完整的 Gateway 运行在 Docker 中。详见 [沙箱](/gateway/sandboxing)。
本指南涵盖：
- 容器化 Gateway（完整的 OpenClaw 运行在 Docker 中）
- 按会话的智能体沙箱（主机 Gateway + Docker 隔离的智能体工具）
沙箱详情：[沙箱](/gateway/sandboxing)
## 前置要求
- Docker Desktop（或 Docker Engine）+ Docker Compose v2
- 足够的磁盘空间用于镜像和日志
## 容器化 Gateway（Docker Compose）
### 快速开始（推荐）
在仓库根目录运行：
```bash
./docker-setup.sh
```
该脚本会：
- 构建 Gateway 镜像
- 运行上手引导向导
- 打印可选的提供商设置提示
- 通过 Docker Compose 启动 Gateway
- 生成 Gateway 令牌并写入 `.env`
可选环境变量：
- `OPENCLAW_DOCKER_APT_PACKAGES` — 在构建期间安装额外的 apt 软件包
- `OPENCLAW_EXTRA_MOUNTS` — 添加额外的主机绑定挂载
- `OPENCLAW_HOME_VOLUME` — 将 `/home/node` 持久化到命名卷
完成后：
- 在浏览器中打开 `http://127.0.0.1:18789/`。
- 在控制界面中粘贴令牌（设置 → 令牌）。
配置和工作区写入主机：
- `~/.openclaw/`
- `~/.openclaw/workspace`
在 VPS 上运行？参见 [Hetzner（Docker VPS）](/platforms/hetzner)。
### 手动流程（compose）
```bash
docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway
```
### 额外挂载（可选）
如果你想将额外的主机目录挂载到容器中，请在运行 `docker-setup.sh` 之前设置 `OPENCLAW_EXTRA_MOUNTS`。该变量接受逗号分隔的 Docker 绑定挂载列表，并通过生成 `docker-compose.extra.yml` 将其应用到 `openclaw-gateway` 和 `openclaw-cli`。
示例：
```bash
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh
```
注意事项：
- 在 macOS/Windows 上，路径必须与 Docker Desktop 共享。
- 如果修改了 `OPENCLAW_EXTRA_MOUNTS`，请重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
- `docker-compose.extra.yml` 是自动生成的。请勿手动编辑。
### 持久化整个容器 home 目录（可选）
如果你希望 `/home/node` 在容器重建后持久保留，请通过 `OPENCLAW_HOME_VOLUME` 设置命名卷。这会创建一个 Docker 卷并挂载到 `/home/node`，同时保留标准的配置/工作区绑定挂载。此处请使用命名卷（而非绑定路径）；绑定挂载请使用 `OPENCLAW_EXTRA_MOUNTS`。
示例：
```bash
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
```
可以与额外挂载组合使用：
```bash
export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh
```
注意事项：
- 如果修改了 `OPENCLAW_HOME_VOLUME`，请重新运行 `docker-setup.sh` 以重新生成额外的 compose 文件。
- 命名卷会一直保留，直到通过 `docker volume rm <name>` 删除。
### 安装额外的 apt 软件包（可选）
如果你需要在镜像中安装系统软件包（例如构建工具或媒体库），请在运行 `docker-setup.sh` 之前设置 `OPENCLAW_DOCKER_APT_PACKAGES`。这会在镜像构建期间安装软件包，因此即使容器被删除也会保留。
示例：
```bash
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh
```
注意事项：
- 该变量接受以空格分隔的 apt 软件包名称列表。
- 如果修改了 `OPENCLAW_DOCKER_APT_PACKAGES`，请重新运行 `docker-setup.sh` 以重建镜像。
### 加速重建（推荐）
为加速重建，请调整 Dockerfile 中的顺序以利用依赖层缓存。这样只有在锁文件变更时才会重新运行 `pnpm install`：
```dockerfile
FROM node:22-bookworm
# 安装 Bun（构建脚本需要）
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
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
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]
```
### 渠道设置（可选）
使用 CLI 容器配置渠道，然后根据需要重启 Gateway。
WhatsApp（二维码）：
```bash
docker compose run --rm openclaw-cli channels login
```
Telegram（机器人令牌）：
```bash
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
```
Discord（机器人令牌）：
```bash
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
```
文档：[WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)
### 健康检查
```bash
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
```
### 端到端冒烟测试（Docker）
```bash
scripts/e2e/onboard-docker.sh
```
### 二维码导入冒烟测试（Docker）
```bash
pnpm test:docker:qr
```
### 注意事项
- Gateway 绑定默认设为 `lan` 以适配容器使用。
- Gateway 容器是会话的权威来源（`~/.openclaw/agents/<agentId>/sessions/`）。
## 智能体沙箱（主机 Gateway + Docker 工具）
深入了解：[沙箱](/gateway/sandboxing)
### 功能说明
当启用 `agents.defaults.sandbox` 时，**非 main 会话**会在 Docker 容器内运行工具。Gateway 仍在主机上运行，但工具执行是隔离的：
- 作用域：默认为 `"agent"`（每个智能体一个容器 + 工作区）
- 作用域：`"session"` 用于按会话隔离
- 按作用域的工作区文件夹挂载到 `/workspace`
- 可选的智能体工作区访问（`agents.defaults.sandbox.workspaceAccess`）
- 允许/拒绝工具策略（拒绝优先）
- 入站媒体会复制到活动沙箱工作区（`media/inbound/*`），以便工具可以读取（使用 `workspaceAccess: "rw"` 时，媒体会落入智能体工作区）
警告：`scope: "shared"` 会禁用跨会话隔离。所有会话共享一个容器和一个工作区。
### 按智能体的沙箱配置（多智能体）
如果使用多智能体路由，每个智能体可以覆盖沙箱和工具设置：`agents.list[].sandbox` 和 `agents.list[].tools`（以及 `agents.list[].tools.sandbox.tools`）。这允许你在一个 Gateway 中运行混合访问级别：
- 完全访问（个人智能体）
- 只读工具 + 只读工作区（家庭/工作智能体）
- 无文件系统/shell 工具（公共智能体）
示例、优先级和故障排除详见 [多智能体沙箱与工具](/multi-agent-sandbox-tools)。
### 默认行为
- 镜像：`openclaw-sandbox:bookworm-slim`
- 每个智能体一个容器
- 智能体工作区访问：`workspaceAccess: "none"`（默认）使用 `~/.openclaw/sandboxes`
- `"ro"` 将沙箱工作区保留在 `/workspace`，并将智能体工作区以只读方式挂载到 `/agent`（禁用 `write`/`edit`/`apply_patch`）
- `"rw"` 将智能体工作区以读写方式挂载到 `/workspace`
- 自动清理：空闲超过 24 小时或创建超过 7 天
- 网络：默认为 `none`（需要出站访问时请显式启用）
- 默认允许：`exec`、`process`、`read`、`write`、`edit`、`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`
- 默认拒绝：`browser`、`canvas`、`nodes`、`cron`、`discord`、`gateway`
### 启用沙箱
如果你计划在 `setupCommand` 中安装软件包，请注意：
- 默认 `docker.network` 为 `"none"`（无出站访问）。
- `readOnlyRoot: true` 会阻止软件包安装。
- `user` 必须是 root 才能运行 `apt-get`（省略 `user` 或设置 `user: "0:0"`）。
当 `setupCommand`（或 docker 配置）发生变更时，OpenClaw 会自动重建容器，除非容器**最近被使用过**（约 5 分钟内）。活跃容器会记录一条警告，包含确切的 `openclaw sandbox recreate ...` 命令。
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared（默认为 agent）
workspaceAccess: "none", // none | ro | rw
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "openclaw-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000",
capDrop: ["ALL"],
env: { LANG: "C.UTF-8" },
setupCommand: "apt-get update && apt-get install -y git curl jq",
pidsLimit: 256,
memory: "1g",
memorySwap: "2g",
cpus: 1,
ulimits: {
nofile: { soft: 1024, hard: 2048 },
nproc: 256,
},
seccompProfile: "/path/to/seccomp.json",
apparmorProfile: "openclaw-sandbox",
dns: ["1.1.1.1", "8.8.8.8"],
extraHosts: ["internal.service:10.0.0.5"],
},
prune: {
idleHours: 24, // 0 禁用空闲清理
maxAgeDays: 7, // 0 禁用最大时限清理
},
},
},
},
tools: {
sandbox: {
tools: {
allow: [
"exec",
"process",
"read",
"write",
"edit",
"sessions_list",
"sessions_history",
"sessions_send",
"sessions_spawn",
"session_status",
],
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
},
},
},
}
```
加固选项位于 `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"` 时忽略）。
### 构建默认沙箱镜像
```bash
scripts/sandbox-setup.sh
```
这会使用 `Dockerfile.sandbox` 构建 `openclaw-sandbox:bookworm-slim`。
### 沙箱通用镜像（可选）
如果你需要包含常用构建工具（Node、Go、Rust 等）的沙箱镜像，请构建通用镜像：
```bash
scripts/sandbox-common-setup.sh
```
这会构建 `openclaw-sandbox-common:bookworm-slim`。使用方法：
```json5
{
agents: {
defaults: {
sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
},
},
}
```
### 沙箱浏览器镜像
要在沙箱内运行浏览器工具，请构建浏览器镜像：
```bash
scripts/sandbox-browser-setup.sh
```
这会使用 `Dockerfile.sandbox-browser` 构建 `openclaw-sandbox-browser:bookworm-slim`。容器运行启用了 CDP 的 Chromium，并提供可选的 noVNC 观察器（通过 Xvfb 实现有头模式）。
注意事项：
- 有头模式（Xvfb）比无头模式更能减少机器人检测。
- 仍可通过设置 `agents.defaults.sandbox.browser.headless=true` 使用无头模式。
- 不需要完整的桌面环境（GNOME）；Xvfb 提供显示。
配置用法：
```json5
{
agents: {
defaults: {
sandbox: {
browser: { enabled: true },
},
},
},
}
```
自定义浏览器镜像：
```json5
{
agents: {
defaults: {
sandbox: { browser: { image: "my-openclaw-browser" } },
},
},
}
```
启用后，智能体会收到：
- 沙箱浏览器控制 URL（用于 `browser` 工具）
- noVNC URL（如果已启用且 headless=false）
注意：如果你使用了工具允许列表，请添加 `browser`（并从拒绝列表中移除），否则该工具仍会被阻止。
清理规则（`agents.defaults.sandbox.prune`）也适用于浏览器容器。
### 自定义沙箱镜像
构建你自己的镜像并在配置中指向它：
```bash
docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
```
```json5
{
agents: {
defaults: {
sandbox: { docker: { image: "my-openclaw-sbx" } },
},
},
}
```
### 工具策略（允许/拒绝）
- `deny` 优先于 `allow`。
- 如果 `allow` 为空：所有工具（除拒绝的）均可用。
- 如果 `allow` 不为空：仅 `allow` 中的工具可用（减去拒绝的）。
### 清理策略
两个配置项：
- `prune.idleHours`：移除超过 X 小时未使用的容器（0 = 禁用）
- `prune.maxAgeDays`：移除超过 X 天的容器（0 = 禁用）
示例：
- 保留活跃会话但限制生命周期：
`idleHours: 24`，`maxAgeDays: 7`
- 从不清理：
`idleHours: 0`，`maxAgeDays: 0`
### 安全说明
- 硬隔离仅适用于**工具**（exec/read/write/edit/apply_patch）。
- 仅限主机的工具（如 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/` 下添加脚本。

193
docs/zh-CN/install/index.md Normal file
View File

@@ -0,0 +1,193 @@
---
read_when:
- 安装 OpenClaw
- 你想从 GitHub 安装
summary: 安装 OpenClaw（推荐安装器、全局安装或从源码安装）
title: 安装
x-i18n:
generated_at: "2026-02-01T21:07:34Z"
model: claude-opus-4-5
provider: pi
source_hash: b26f48c116c26c163ee0090fb4c3e29622951bd427ecaeccba7641d97cfdf17a
source_path: install/index.md
workflow: 14
---
# 安装
除非有特殊原因，否则请使用安装器。它会设置 CLI 并运行上手引导。
## 快速安装（推荐）
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
Windows (PowerShell)：
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
下一步（如果你跳过了上手引导）：
```bash
openclaw onboard --install-daemon
```
## 系统要求
- **Node >=22**
- macOS、Linux 或通过 WSL2 的 Windows
- `pnpm` 仅在从源码构建时需要
## 选择安装方式
### 1) 安装器脚本（推荐）
通过 npm 全局安装 `openclaw` 并运行上手引导。
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
安装器参数：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
```
详情：[安装器内部机制](/install/installer)。
非交互式（跳过上手引导）：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
### 2) 全局安装（手动）
如果你已安装 Node：
```bash
npm install -g openclaw@latest
```
如果你已全局安装 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` 变通方法跳过原生构建。
或使用 pnpm：
```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g # 批准 openclaw、node-llama-cpp、sharp 等
pnpm add -g openclaw@latest # 重新运行以执行 postinstall 脚本
```
pnpm 要求显式批准带有构建脚本的软件包。首次安装显示"Ignored build scripts"警告后，运行 `pnpm approve-builds -g` 并选择列出的软件包，然后重新运行安装以执行 postinstall 脚本。
然后：
```bash
openclaw onboard --install-daemon
```
### 3) 从源码安装（贡献者/开发用途）
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon
```
提示：如果尚未全局安装，可通过 `pnpm openclaw ...` 运行仓库命令。
### 4) 其他安装选项
- Docker：[Docker](/install/docker)
- Nix：[Nix](/install/nix)
- Ansible：[Ansible](/install/ansible)
- Bun（仅 CLI）：[Bun](/install/bun)
## 安装后
- 运行上手引导：`openclaw onboard --install-daemon`
- 快速检查：`openclaw doctor`
- 检查 Gateway 健康状态：`openclaw status` + `openclaw health`
- 打开仪表盘：`openclaw dashboard`
## 安装方式：npm vs git（安装器）
安装器支持两种方式：
- `npm`（默认）：`npm install -g openclaw@latest`
- `git`：从 GitHub 克隆/构建并从源码检出运行
### CLI 参数
```bash
# 显式使用 npm
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
# 从 GitHub 安装（源码检出）
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-prompt`（禁用提示；CI/自动化中必需）
- `--dry-run`（打印将要执行的操作；不做任何更改）
- `--no-onboard`（跳过上手引导）
### 环境变量
等效的环境变量（适用于自动化）：
- `OPENCLAW_INSTALL_METHOD=git|npm`
- `OPENCLAW_GIT_DIR=...`
- `OPENCLAW_GIT_UPDATE=0|1`
- `OPENCLAW_NO_PROMPT=1`
- `OPENCLAW_DRY_RUN=1`
- `OPENCLAW_NO_ONBOARD=1`
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1`（默认：`1`；避免 `sharp` 使用系统 libvips 编译）
## 故障排除：找不到 `openclaw`（PATH 问题）
快速诊断：
```bash
node -v
npm -v
npm prefix -g
echo "$PATH"
```
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不在** `echo "$PATH"` 的输出中，说明你的 shell 无法找到全局 npm 二进制文件（包括 `openclaw`）。
修复：将其添加到 shell 启动文件（zsh：`~/.zshrc`，bash：`~/.bashrc`）：
```bash
# macOS / Linux
export PATH="$(npm prefix -g)/bin:$PATH"
```
在 Windows 上，将 `npm prefix -g` 的输出添加到 PATH。
然后打开新终端（或在 zsh 中执行 `rehash` / 在 bash 中执行 `hash -r`）。
## 更新 / 卸载
- 更新：[更新](/install/updating)
- 迁移到新机器：[迁移](/install/migrating)
- 卸载：[卸载](/install/uninstall)

128
docs/zh-CN/install/installer.md Normal file
View File

@@ -0,0 +1,128 @@
---
read_when:
- 你想了解 `openclaw.ai/install.sh` 的工作机制
- 你想自动化安装（CI / 无头环境）
- 你想从 GitHub 检出安装
summary: 安装器脚本的工作原理（install.sh + install-cli.sh）、参数和自动化
title: 安装器内部机制
x-i18n:
generated_at: "2026-02-01T21:07:55Z"
model: claude-opus-4-5
provider: pi
source_hash: 9e0a19ecb5da0a395030e1ccf0d4bedf16b83946b3432c5399d448fe5d298391
source_path: install/installer.md
workflow: 14
---
# 安装器内部机制
OpenClaw 提供两个安装器脚本（托管在 `openclaw.ai`）：
- `https://openclaw.ai/install.sh` — "推荐"安装器（默认全局 npm 安装；也可从 GitHub 检出安装）
- `https://openclaw.ai/install-cli.sh` — 无需 root 权限的 CLI 安装器（安装到带有独立 Node 的前缀目录）
- `https://openclaw.ai/install.ps1` — Windows PowerShell 安装器（默认 npm；可选 git 安装）
查看当前参数/行为，运行：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
```
Windows (PowerShell) 帮助：
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
```
如果安装器完成但在新终端中找不到 `openclaw`，通常是 Node/npm PATH 问题。参见：[安装](/install#nodejs--npm-path-sanity)。
## install.sh（推荐）
功能概述：
- 检测操作系统（macOS / Linux / WSL）。
- 确保 Node.js **22+**（macOS 通过 Homebrew；Linux 通过 NodeSource）。
- 选择安装方式：
- `npm`（默认）：`npm install -g openclaw@latest`
- `git`：克隆/构建源码检出并安装包装脚本
- 在 Linux 上：必要时将 npm 前缀切换到 `~/.npm-global`，以避免全局 npm 权限错误。
- 如果是升级现有安装：运行 `openclaw doctor --non-interactive`（尽力执行）。
- 对于 git 安装：安装/更新后运行 `openclaw doctor --non-interactive`（尽力执行）。
- 通过默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 来缓解 `sharp` 原生安装问题（避免使用系统 libvips 编译）。
如果你*希望* `sharp` 链接到全局安装的 libvips（或你正在调试），请设置：
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
```
### 可发现性 / "git 安装"提示
如果你在**已有的 OpenClaw 源码检出目录中**运行安装器（通过 `package.json` + `pnpm-workspace.yaml` 检测），它会提示：
- 更新并使用此检出（`git`）
- 或迁移到全局 npm 安装（`npm`）
在非交互式上下文中（无 TTY / `--no-prompt`），你必须传入 `--install-method git|npm`（或设置 `OPENCLAW_INSTALL_METHOD`），否则脚本将以退出码 `2` 退出。
### 为什么需要 Git
`--install-method git` 路径（克隆 / 拉取）需要 Git。
对于 `npm` 安装，Git *通常*不是必需的，但某些环境仍然需要它（例如通过 git URL 获取软件包或依赖时）。安装器目前会确保 Git 存在，以避免在全新发行版上出现 `spawn git ENOENT` 错误。
### 为什么在全新 Linux 上 npm 会报 `EACCES`
在某些 Linux 设置中（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局前缀指向 root 拥有的位置。此时 `npm install -g ...` 会报 `EACCES` / `mkdir` 权限错误。
`install.sh` 通过将前缀切换到以下位置来缓解此问题：
- `~/.npm-global`（并在存在时将其添加到 `~/.bashrc` / `~/.zshrc` 的 `PATH` 中）
## install-cli.sh（无需 root 权限的 CLI 安装器）
此脚本将 `openclaw` 安装到前缀目录（默认：`~/.openclaw`），同时在该前缀下安装专用的 Node 运行时，因此可以在不想改动系统 Node/npm 的机器上使用。
帮助：
```bash
curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
```
## install.ps1（Windows PowerShell）
功能概述：
- 确保 Node.js **22+**（winget/Chocolatey/Scoop 或手动安装）。
- 选择安装方式：
- `npm`（默认）：`npm install -g openclaw@latest`
- `git`：克隆/构建源码检出并安装包装脚本
- 在升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力执行）。
示例：
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
```
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
```
环境变量：
- `OPENCLAW_INSTALL_METHOD=git|npm`
- `OPENCLAW_GIT_DIR=...`
Git 要求：
如果你选择 `-InstallMethod git` 但未安装 Git，安装器会打印 Git for Windows 的链接（`https://git-scm.com/download/win`）并退出。
常见 Windows 问题：
- **npm error spawn git / ENOENT**：安装 Git for Windows 并重新打开 PowerShell，然后重新运行安装器。
- **"openclaw" 不是可识别的命令**：你的 npm 全局 bin 文件夹不在 PATH 中。大多数系统使用 `%AppData%\\npm`。你也可以运行 `npm config get prefix` 并将 `\\bin` 添加到 PATH，然后重新打开 PowerShell。

199
docs/zh-CN/install/migrating.md Normal file
View File

@@ -0,0 +1,199 @@
---
read_when:
- 你正在将 OpenClaw 迁移到新的笔记本/服务器
- 你想保留会话、认证和渠道登录状态（WhatsApp 等）
summary: 将 OpenClaw 安装从一台机器迁移到另一台
title: 迁移指南
x-i18n:
generated_at: "2026-02-01T21:08:21Z"
model: claude-opus-4-5
provider: pi
source_hash: 604d862c4bf86e7924d09028db8cc2514ca6f1d64ebe8bb7d1e2dde57ef70caa
source_path: install/migrating.md
workflow: 14
---
# 将 OpenClaw 迁移到新机器
本指南介绍如何将 OpenClaw Gateway 从一台机器迁移到另一台，**无需重新进行上手引导**。
迁移在概念上很简单：
- 复制**状态目录**（`$OPENCLAW_STATE_DIR`，默认：`~/.openclaw/`）— 包含配置、认证、会话和渠道状态。
- 复制你的**工作区**（默认 `~/.openclaw/workspace/`）— 包含你的智能体文件（记忆、提示词等）。
但在**配置文件**、**权限**和**不完整复制**方面有一些常见的坑。
## 开始之前（你要迁移什么）
### 1) 确认你的状态目录
大多数安装使用默认路径：
- **状态目录：** `~/.openclaw/`
但如果你使用了以下选项，路径可能不同：
- `--profile <name>`（通常变为 `~/.openclaw-<profile>/`）
- `OPENCLAW_STATE_DIR=/some/path`
如果不确定，在**旧**机器上运行：
```bash
openclaw status
```
在输出中查找 `OPENCLAW_STATE_DIR` / profile 的相关信息。如果你运行了多个 Gateway，请对每个配置文件重复操作。
### 2) 确认你的工作区
常见默认路径：
- `~/.openclaw/workspace/`（推荐工作区）
- 你创建的自定义文件夹
你的工作区是 `MEMORY.md`、`USER.md` 和 `memory/*.md` 等文件所在的位置。
### 3) 了解你将保留什么
如果你**同时**复制状态目录和工作区，你将保留：
- Gateway 配置（`openclaw.json`）
- 认证配置 / API 密钥 / OAuth 令牌
- 会话历史 + 智能体状态
- 渠道状态（例如 WhatsApp 登录/会话）
- 你的工作区文件（记忆、技能笔记等）
如果你**只**复制工作区（例如通过 Git），你将**不会**保留：
- 会话
- 凭据
- 渠道登录状态
这些存储在 `$OPENCLAW_STATE_DIR` 下。
## 迁移步骤（推荐）
### 步骤 0 — 备份（旧机器）
在**旧**机器上，先停止 Gateway 以确保复制过程中文件不会变动：
```bash
openclaw gateway stop
```
（可选但推荐）归档状态目录和工作区：
```bash
# 如果使用了配置文件或自定义路径，请调整路径
cd ~
tar -czf openclaw-state.tgz .openclaw
tar -czf openclaw-workspace.tgz .openclaw/workspace
```
如果你有多个配置文件/状态目录（例如 `~/.openclaw-main`、`~/.openclaw-work`），请分别归档。
### 步骤 1 — 在新机器上安装 OpenClaw
在**新**机器上安装 CLI（如有需要也安装 Node）：
- 参见：[安装](/install)
在此阶段，上手引导创建一个全新的 `~/.openclaw/` 是没问题的 — 你将在下一步覆盖它。
### 步骤 2 — 将状态目录 + 工作区复制到新机器
**同时**复制：
- `$OPENCLAW_STATE_DIR`（默认 `~/.openclaw/`）
- 你的工作区（默认 `~/.openclaw/workspace/`）
常用方法：
- 通过 `scp` 传输压缩包并解压
- 通过 SSH 使用 `rsync -a`
- 外部存储设备
复制后确保：
- 隐藏目录已包含在内（例如 `.openclaw/`）
- 文件所有权对于运行 Gateway 的用户是正确的
### 步骤 3 — 运行 Doctor（迁移 + 服务修复）
在**新**机器上：
```bash
openclaw doctor
```
Doctor 是"安全可靠"的命令。它会修复服务、应用配置迁移并警告不匹配的问题。
然后：
```bash
openclaw gateway restart
openclaw status
```
## 常见的坑（及如何避免）
### 坑：配置文件 / 状态目录不匹配
如果旧 Gateway 使用了配置文件（或 `OPENCLAW_STATE_DIR`），而新 Gateway 使用了不同的路径，你会看到以下症状：
- 配置更改不生效
- 渠道缺失 / 已登出
- 会话历史为空
修复：使用与迁移相同的配置文件/状态目录来运行 Gateway/服务，然后重新运行：
```bash
openclaw doctor
```
### 坑：只复制了 `openclaw.json`
`openclaw.json` 是不够的。许多提供商将状态存储在：
- `$OPENCLAW_STATE_DIR/credentials/`
- `$OPENCLAW_STATE_DIR/agents/<agentId>/...`
始终迁移整个 `$OPENCLAW_STATE_DIR` 文件夹。
### 坑：权限 / 所有权
如果你以 root 身份复制或更换了用户，Gateway 可能无法读取凭据/会话。
修复：确保状态目录 + 工作区的所有者是运行 Gateway 的用户。
### 坑：在远程/本地模式之间迁移
- 如果你的界面（WebUI/TUI）指向**远程** Gateway，则远程主机拥有会话存储 + 工作区。
- 迁移你的笔记本不会移动远程 Gateway 的状态。
如果你处于远程模式，请迁移 **Gateway 主机**。
### 坑：备份中的密钥
`$OPENCLAW_STATE_DIR` 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭据）。请将备份视为生产密钥：
- 加密存储
- 避免通过不安全的渠道传输
- 如果怀疑泄露，请轮换密钥
## 验证清单
在新机器上确认：
- `openclaw status` 显示 Gateway 正在运行
- 你的渠道仍然处于连接状态（例如 WhatsApp 无需重新配对）
- 仪表盘可以打开并显示现有会话
- 你的工作区文件（记忆、配置）已存在
## 相关内容
- [Doctor](/gateway/doctor)
- [Gateway 故障排除](/gateway/troubleshooting)
- [OpenClaw 将数据存储在哪里？](/help/faq#where-does-openclaw-store-its-data)

103
docs/zh-CN/install/nix.md Normal file
View File

@@ -0,0 +1,103 @@
---
read_when:
- 你想要可复现、可回滚的安装方式
- 你已经在使用 Nix/NixOS/Home Manager
- 你想要一切固定且声明式管理
summary: 使用 Nix 声明式安装 OpenClaw
title: Nix
x-i18n:
generated_at: "2026-02-01T21:08:16Z"
model: claude-opus-4-5
provider: pi
source_hash: f1452194cfdd74613b5b3ab90b0d506eaea2d16b147497987710d6ad658312ba
source_path: install/nix.md
workflow: 14
---
# Nix 安装
使用 Nix 运行 OpenClaw 的推荐方式是通过 **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — 一个开箱即用的 Home Manager 模块。
## 快速开始
将以下内容粘贴给你的 AI 智能体（Claude、Cursor 等）：
```text
I want to set up nix-openclaw on my Mac.
Repository: github:openclaw/nix-openclaw
What I need you to do:
1. Check if Determinate Nix is installed (if not, install it)
2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
5. Fill in the template placeholders and run home-manager switch
6. Verify: launchd running, bot responds to messages
Reference the nix-openclaw README for module options.
```
> **📦 完整指南：[github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)**
>
> nix-openclaw 仓库是 Nix 安装的权威来源。本页仅为简要概览。
## 你将获得
- Gateway + macOS 应用 + 工具（whisper、spotify、cameras）— 全部固定版本
- 可在重启后保持运行的 Launchd 服务
- 带声明式配置的插件系统
- 即时回滚：`home-manager switch --rollback`
---
## Nix 模式运行时行为
当设置了 `OPENCLAW_NIX_MODE=1` 时（nix-openclaw 会自动设置）：
OpenClaw 支持 **Nix 模式**，使配置具有确定性并禁用自动安装流程。
通过导出以下环境变量启用：
```bash
OPENCLAW_NIX_MODE=1
```
在 macOS 上，GUI 应用不会自动继承 shell 环境变量。你也可以
通过 defaults 启用 Nix 模式：
```bash
defaults write bot.molt.mac openclaw.nixMode -bool true
```
### 配置 + 状态路径
OpenClaw 从 `OPENCLAW_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存储在 `OPENCLAW_STATE_DIR` 中。
- `OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）
- `OPENCLAW_CONFIG_PATH`（默认：`$OPENCLAW_STATE_DIR/openclaw.json`）
在 Nix 下运行时，请将这些路径显式设置为 Nix 管理的位置，以便运行时状态和配置
不会进入不可变存储。
### Nix 模式下的运行时行为
- 自动安装和自我变更流程被禁用
- 缺失依赖会显示 Nix 特定的修复建议
- UI 在启用时会显示只读的 Nix 模式横幅
## 打包说明（macOS）
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 工具链）。
## 相关内容
- [nix-openclaw](https://github.com/openclaw/nix-openclaw) — 完整设置指南
- [向导](/start/wizard) — 非 Nix 的 CLI 设置
- [Docker](/install/docker) — 容器化设置

85
docs/zh-CN/install/node.md Normal file
View File

@@ -0,0 +1,85 @@
---
read_when:
- 你已安装 OpenClaw 但 `openclaw` 提示"command not found"
- 你正在新机器上配置 Node.js/npm
- npm install -g ... 因权限或 PATH 问题失败
summary: Node.js + npm 安装完整性检查：版本、PATH 及全局安装
title: Node.js + npm（PATH 安装完整性检查）
x-i18n:
generated_at: "2026-02-01T21:16:20Z"
model: claude-opus-4-5
provider: pi
source_hash: 9f6d83be362e3e148ddf07d47e57c51679c22687263d3b5131cccbef2e37c598
source_path: install/node.md
workflow: 15
---
# Node.js + npm（PATH 安装完整性检查）
OpenClaw 的运行时基线要求为 **Node 22+**。
如果你能运行 `npm install -g openclaw@latest`，但之后看到 `openclaw: command not found`，这几乎总是 **PATH** 问题：npm 存放全局二进制文件的目录不在你 shell 的 PATH 中。
## 快速诊断
运行：
```bash
node -v
npm -v
npm prefix -g
echo "$PATH"
```
如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**未出现**在 `echo "$PATH"` 的输出中，你的 shell 就无法找到全局 npm 二进制文件（包括 `openclaw`）。
## 修复：将 npm 的全局 bin 目录添加到 PATH
1. 查找你的全局 npm 前缀：
```bash
npm prefix -g
```
2. 将全局 npm bin 目录添加到你的 shell 启动文件中：
- zsh：`~/.zshrc`
- bash：`~/.bashrc`
示例（将路径替换为你的 `npm prefix -g` 输出）：
```bash
# macOS / Linux
export PATH="/path/from/npm/prefix/bin:$PATH"
```
然后打开一个**新终端**（或在 zsh 中运行 `rehash` / 在 bash 中运行 `hash -r`）。
在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。
## 修复：避免 `sudo npm install -g` / 权限错误（Linux）
如果 `npm install -g ...` 因 `EACCES` 失败，请将 npm 的全局前缀切换到用户可写的目录：
```bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
```
将 `export PATH=...` 这一行持久化到你的 shell 启动文件中。
## 推荐的 Node 安装方式
如果 Node/npm 的安装方式满足以下条件，你将遇到最少的问题：
- 保持 Node 更新（22+）
- 使全局 npm bin 目录稳定且在新 shell 中位于 PATH 中
常见选择：
- macOS：Homebrew（`brew install node`）或版本管理器
- Linux：你偏好的版本管理器，或提供 Node 22+ 的发行版支持的安装方式
- Windows：官方 Node 安装程序、`winget` 或 Windows Node 版本管理器
如果你使用版本管理器（nvm/fnm/asdf 等），请确保它在你日常使用的 shell（zsh 或 bash）中已初始化，这样它设置的 PATH 在你运行安装程序时才会生效。

135
docs/zh-CN/install/uninstall.md Normal file
View File

@@ -0,0 +1,135 @@
---
read_when:
- 您想从机器上移除 OpenClaw
- 卸载后 Gateway 服务仍在运行
summary: 完全卸载 OpenClaw（CLI、服务、状态、工作区）
title: 卸载
x-i18n:
generated_at: "2026-02-01T21:16:21Z"
model: claude-opus-4-5
provider: pi
source_hash: 6673a755c5e1f90a807dd8ac92a774cff6d1bc97d125c75e8bf72a40e952a777
source_path: install/uninstall.md
workflow: 15
---
# 卸载
两种方式：
- **简易方式**：`openclaw` 仍已安装时使用。
- **手动移除服务**：CLI 已删除但服务仍在运行时使用。
## 简易方式（CLI 仍已安装）
推荐：使用内置卸载程序：
```bash
openclaw uninstall
```
非交互模式（自动化 / npx）：
```bash
openclaw uninstall --all --yes --non-interactive
npx -y openclaw uninstall --all --yes --non-interactive
```
手动步骤（效果相同）：
1. 停止 Gateway 服务：
```bash
openclaw gateway stop
```
2. 卸载 Gateway 服务（launchd/systemd/schtasks）：
```bash
openclaw gateway uninstall
```
3. 删除状态和配置：
```bash
rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
```
如果您将 `OPENCLAW_CONFIG_PATH` 设置为状态目录之外的自定义位置，请同时删除该文件。
4. 删除工作区（可选，会移除智能体文件）：
```bash
rm -rf ~/.openclaw/workspace
```
5. 移除 CLI 安装（选择您使用的方式）：
```bash
npm rm -g openclaw
pnpm remove -g openclaw
bun remove -g openclaw
```
6. 如果您安装了 macOS 应用：
```bash
rm -rf /Applications/OpenClaw.app
```
注意事项：
- 如果您使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请对每个状态目录重复步骤 3（默认为 `~/.openclaw-<profile>`）。
- 在远程模式下，状态目录位于 **Gateway 主机**上，因此也需要在那里执行步骤 1-4。
## 手动移除服务（CLI 未安装）
当 Gateway 服务持续运行但 `openclaw` 已不存在时使用此方式。
### macOS (launchd)
默认标签为 `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 文件，请一并移除。
### Linux（systemd 用户单元）
默认单元名称为 `openclaw-gateway.service`（或 `openclaw-gateway-<profile>.service`）：
```bash
systemctl --user disable --now openclaw-gateway.service
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload
```
### Windows（计划任务）
默认任务名称为 `OpenClaw Gateway`（或 `OpenClaw Gateway (<profile>)`）。
任务脚本位于您的状态目录下。
```powershell
schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"
```
如果您使用了配置文件，请删除对应的任务名称和 `~\.openclaw-<profile>\gateway.cmd`。
## 常规安装与源码检出
### 常规安装（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`）。
### 源码检出（git clone）
如果您从仓库检出运行（`git clone` + `openclaw ...` / `bun run openclaw ...`）：
1. 在删除仓库**之前**先卸载 Gateway 服务（使用上述简易方式或手动移除服务）。
2. 删除仓库目录。
3. 按上述方式移除状态和工作区。

233
docs/zh-CN/install/updating.md Normal file
View File

@@ -0,0 +1,233 @@
---
read_when:
- 更新 OpenClaw
- 更新后出现问题
summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略
title: 更新
x-i18n:
generated_at: "2026-02-01T21:16:51Z"
model: claude-opus-4-5
provider: pi
source_hash: 612b2519cf3e4a2c2d0f01575c3fa75ab1c88a6fed9e59477bf27395beda03c1
source_path: install/updating.md
workflow: 15
---
# 更新
OpenClaw 迭代速度很快（尚未到"1.0"）。请像对待基础设施发布一样对待更新：更新 → 运行检查 → 重启（或使用 `openclaw update`，它会自动重启）→ 验证。
## 推荐方式：重新运行网站安装程序（原地升级）
**首选**更新路径是重新运行网站上的安装程序。它会检测现有安装、原地升级，并在需要时运行 `openclaw doctor`。
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
注意事项：
- 如果不想再次运行上手引导向导，请添加 `--no-onboard`。
- 对于**源码安装**，请使用：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
```
安装程序**仅在**仓库工作区干净时才会执行 `git pull --rebase`。
- 对于**全局安装**，脚本底层使用 `npm install -g openclaw@latest`。
- 兼容性说明：`openclaw` 仍可作为兼容性垫片使用。
## 更新前的准备
- 了解你的安装方式：**全局安装**（npm/pnpm）还是**源码安装**（git clone）。
- 了解你的 Gateway 运行方式：**前台终端**还是**受监控服务**（launchd/systemd）。
- 备份你的自定义配置：
- 配置文件：`~/.openclaw/openclaw.json`
- 凭据：`~/.openclaw/credentials/`
- 工作区：`~/.openclaw/workspace`
## 更新（全局安装）
全局安装（任选其一）：
```bash
npm i -g openclaw@latest
```
```bash
pnpm add -g openclaw@latest
```
我们**不建议**使用 Bun 作为 Gateway 运行时（存在 WhatsApp/Telegram 相关 bug）。
切换更新渠道（git + npm 安装）：
```bash
openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable
```
使用 `--tag <dist-tag|version>` 进行一次性指定标签/版本安装。
有关渠道语义和发布说明，请参阅[开发渠道](/install/development-channels)。
注意：在 npm 安装中，Gateway 启动时会记录更新提示（检查当前渠道标签）。可通过 `update.checkOnStart: false` 禁用。
然后：
```bash
openclaw doctor
openclaw gateway restart
openclaw health
```
注意事项：
- 如果你的 Gateway 作为服务运行，建议使用 `openclaw gateway restart` 而非直接终止 PID。
- 如果你固定在特定版本，请参阅下方的"回滚/版本固定"。
## 更新（`openclaw update`）
对于**源码安装**（git checkout），推荐使用：
```bash
openclaw update
```
它会执行一个相对安全的更新流程：
- 要求工作区干净。
- 切换到所选渠道（标签或分支）。
- 从配置的上游（dev 渠道）拉取并变基。
- 安装依赖、构建、构建控制面板 UI，并运行 `openclaw doctor`。
- 默认重启 Gateway（使用 `--no-restart` 跳过）。
如果你通过 **npm/pnpm** 安装（无 git 元数据），`openclaw update` 会尝试通过你的包管理器进行更新。如果无法检测到安装方式，请改用"更新（全局安装）"。
## 更新（控制面板 UI / RPC）
控制面板 UI 提供**更新并重启**功能（RPC：`update.run`）。它会：
1. 执行与 `openclaw update` 相同的源码更新流程（仅限 git checkout）。
2. 写入重启哨兵文件及结构化报告（stdout/stderr 尾部内容）。
3. 重启 Gateway 并向最近活跃的会话发送报告。
如果变基失败，Gateway 会中止并在不应用更新的情况下重启。
## 更新（源码安装）
从仓库检出目录：
推荐方式：
```bash
openclaw update
```
手动方式（大致等效）：
```bash
git pull
pnpm install
pnpm build
pnpm ui:build # 首次运行时自动安装 UI 依赖
openclaw doctor
openclaw health
```
注意事项：
- 当你运行打包后的 `openclaw` 二进制文件（[`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)）或使用 Node 运行 `dist/` 时，`pnpm build` 很重要。
- 如果你从仓库检出运行而没有全局安装，请使用 `pnpm openclaw ...` 执行 CLI 命令。
- 如果你直接从 TypeScript 运行（`pnpm openclaw ...`），通常不需要重新构建，但**配置迁移仍然适用** → 运行 doctor。
- 在全局安装和 git 安装之间切换很容易：安装另一种方式，然后运行 `openclaw doctor`，这样 Gateway 服务入口点会被重写为当前安装。
## 必须执行：`openclaw doctor`
Doctor 是"安全更新"命令。它有意设计得很朴素：修复 + 迁移 + 警告。
注意：如果你使用的是**源码安装**（git checkout），`openclaw doctor` 会建议先运行 `openclaw update`。
它通常执行以下操作：
- 迁移已弃用的配置键 / 旧版配置文件位置。
- 审核私信策略并对高风险的"开放"设置发出警告。
- 检查 Gateway 健康状态并可建议重启。
- 检测并将旧版 Gateway 服务（launchd/systemd；旧版 schtasks）迁移到当前的 OpenClaw 服务。
- 在 Linux 上，确保 systemd 用户 lingering（使 Gateway 在登出后继续运行）。
详情：[Doctor](/gateway/doctor)
## 启动/停止/重启 Gateway
CLI（适用于所有操作系统）：
```bash
openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow
```
如果使用服务管理：
- 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`。
运维手册及完整服务标签：[Gateway 运维手册](/gateway)
## 回滚/版本固定（出现问题时）
### 版本固定（全局安装）
安装一个已知可用的版本（将 `<version>` 替换为上一个正常工作的版本）：
```bash
npm i -g openclaw@<version>
```
```bash
pnpm add -g openclaw@<version>
```
提示：要查看当前已发布的版本，请运行 `npm view openclaw version`。
然后重启并重新运行 doctor：
```bash
openclaw doctor
openclaw gateway restart
```
### 版本固定（源码安装）按日期
选取某个日期的提交（示例："main 分支截至 2026-01-01 的状态"）：
```bash
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
```
然后重新安装依赖并重启：
```bash
pnpm install
pnpm build
openclaw gateway restart
```
如果之后想回到最新版本：
```bash
git checkout main
git pull
```
## 如果你遇到困难
- 再次运行 `openclaw doctor` 并仔细阅读输出（它通常会告诉你修复方法）。
- 查看：[故障排除](/gateway/troubleshooting)
- 在 Discord 中提问：https://discord.gg/clawd