# 02. 安装部署指南

> **课程信息**
>
> - **作者**：老金
> - **GitHub**：https://github.com/KimYx0207
> - **公众号**：老金带你玩AI
> - **X（Twitter）**：老金带你玩AI
> - **个人博客**：https://aiking.dev
> - **难度等级**：🟢 入门
> - **阅读时间**：20 分钟
> - **前置知识**：会用命令行（终端）
>
> **本篇你将学会：** 在 macOS/Linux/Windows 上安装 OpenClaw，配置运行环境，完成首次启动
>
> **小白速通：** 直接跳到"快速安装"章节（第 3 节），跟着复制粘贴命令就行。遇到问题看第 12-13 节的故障排查

## 概述

老金我写安装部署时最看重可复现：你能照着装好，也要知道以后升级时从哪里回头查。

> **2026-06-18 稳定基线**：本章按 OpenClaw v2026.6.8 更新。日常升级优先使用 `openclaw update`，需要预演时用 dry-run / json / status，遇到安装损坏再用 repair；`repair` 负责 doctor --fix、插件同步、缺失 payload 修复和 registry 刷新，不等于重新安装 core，也不会替你重启 Gateway。

这篇指南覆盖 OpenClaw 在所有主流平台上的安装、配置、升级和故障排查。不管你是 macOS 用户、Linux 服务器管理员还是 Windows 开发者，都能找到适合自己的安装方式。

安装 OpenClaw 的核心流程就三步：

```
1. 官方推荐：运行安装脚本（必要时自动安装 Node）
2. 或者手动安装 OpenClaw CLI（npm / pnpm / bun）
3. 运行引导向导（openclaw onboard）
```

---

## 1. 系统要求


### 1.1 硬件要求

| 项目 | 最低要求 | 推荐配置 | 说明 |
|------|---------|---------|------|
| CPU | 1 核 | 2 核+ | Gateway 守护进程常驻运行 |
| 内存 | 512 MB | 2 GB+ | 多平台连接时内存消耗线性增长 |
| 磁盘 | 500 MB 可用空间 | 2 GB+ | 包含 node_modules 和日志文件 |
| 网络 | 能访问 AI 模型 API | 稳定的宽带连接 | WebSocket 长连接需要稳定网络 |

> **名词解释**：Gateway（OpenClaw 的核心服务进程）以守护进程（daemon，在后台持续运行的服务）方式运行，负责管理所有消息平台连接和 Agent 调度。

说明：OpenClaw 本身很轻量，主要资源消耗来自 Gateway 守护进程和消息平台连接。如果你同时连接多个平台（WhatsApp + Telegram + Discord），建议至少 2 GB 内存。

如果使用本地模型（Ollama），硬件要求会大幅提升：

| 模型规模 | 最低内存 | 推荐 GPU | 推荐磁盘空间 |
|---------|---------|---------|-------------|
| 7B 参数 | 8 GB RAM | 6 GB VRAM | 10 GB |
| 13B 参数 | 16 GB RAM | 12 GB VRAM | 20 GB |
| 70B 参数 | 64 GB RAM | 24 GB+ VRAM | 50 GB |

> **提示**：如果你只用云端 API（OpenAI、Anthropic、Google），不需要 GPU，一台普通的云服务器就够了。

### 1.2 操作系统要求

| 操作系统 | 支持版本 | 备注 |
|---------|---------|------|
| macOS | 12 (Monterey) 及以上 | Intel 和 Apple Silicon 均支持 |
| Ubuntu/Debian | 20.04 LTS 及以上 | 推荐 22.04 LTS |
| CentOS/RHEL | 8 及以上 | 需要 EPEL 仓库 |
| Arch Linux | Rolling Release | 社区维护 AUR 包 |
| Windows | 10 (1903+) / 11 | 强烈推荐通过 WSL2 安装 |
| Alpine Linux | 3.18+ | Docker 镜像常用基础系统 |

### 1.3 软件依赖

| 软件 | 最低版本 | 推荐版本 | 用途 |
|------|---------|---------|------|
| Node.js | 22.19+ 兼容 | 24.x | 运行时环境 |
| npm（Node Package Manager，Node.js 的包管理器） | 10.0.0 | 10.x（随 Node.js 附带） | 包管理器 |
| Git | 2.30+ | 最新版 | 克隆仓库、本地构建、版本管理 |
| Python | 3.10+（可选） | 3.12 | 部分 Agent 工具依赖 |
| Docker | 24.0+（可选） | 最新版 | 容器化部署 |

检查当前环境是否满足要求：

```bash
# 检查 Node.js 版本
node --version
# 期望输出：v24.x.x（或至少 v22.19+）

# 检查 npm 版本
npm --version
# 期望输出：10.x.x 或更高

# 检查 Git 版本
git --version
```

---

## 2. Node.js 环境安装

OpenClaw 当前的官方口径是：**Node.js 24.x 推荐，22.19+ 兼容**。如果你已经满足这个基线，可以跳过这一节。

> 💡 **阅读提示**：下面部分命令示例仍保留 `Node 22` 写法，因为它仍然在兼容范围内；如果你是新装环境，直接把示例里的 `22` 换成 `24` 会更符合当前官方推荐。

> **Termux / 移动 Linux 提示**：v2026.5.22 之后，Termux 场景会更稳地回退到可写 home 目录。不要把 OpenClaw 配置放到系统只读目录；先确认 `node --version`、`npm --version` 和 `echo $HOME` 都指向当前用户环境。

### 2.1 使用 nvm 安装（推荐）

nvm（Node Version Manager）是管理 Node.js 版本的最佳方式，可以在多个版本之间自由切换。

**macOS / Linux：**

```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js 24
nvm install 24

# 设为默认版本
nvm alias default 24

# 验证
node --version  # v24.x.x
```

**Windows：**

Windows 用户使用 nvm-windows：

1. 从 [nvm-windows releases](https://github.com/coreybutler/nvm-windows/releases) 下载最新安装包
2. 运行安装程序
3. 打开新的命令行窗口：

```powershell
nvm install 24
nvm use 24
node --version
```

### 2.2 使用官方安装包

直接从 [Node.js 官网](https://nodejs.org/) 下载 LTS 版本安装包：

- macOS：下载 `.pkg` 文件，双击安装
- Windows：下载 `.msi` 文件，双击安装
- Linux：使用 NodeSource 仓库

```bash
# Ubuntu/Debian - 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

# Arch Linux
sudo pacman -S nodejs npm
```

### 2.3 使用 Homebrew（macOS）

```bash
brew install node@24
```

### 2.4 安装方式对比

| 方式 | 优点 | 缺点 | 适用场景 |
|------|------|------|---------|
| nvm | 多版本管理、不需要 sudo | 需要额外安装 | 开发环境（推荐） |
| 官方安装包 | 简单直接 | 升级麻烦、可能需要 sudo | 新手、单版本需求 |
| Homebrew | macOS 生态集成好 | 仅限 macOS | macOS 用户 |
| NodeSource | 系统包管理器集成 | 版本更新可能滞后 | 服务器部署 |

---

## 3. 安装 OpenClaw CLI


> **v2026.6.8 安装基线**：官方 README 当前写法是 Node 24 recommended，Node 22.19+ supported。新装优先走 `openclaw onboard`，升级和回滚按 release channel 选择 stable / beta / dev；教程里的固定版本号只用于复现问题，不建议长期锁死。v2026.6.8-beta.2 是预发布线，不作为本教程默认稳定基线。

这一轮还会影响排障口径：

- Pi packages 更新到 0.75.1，遇到内部运行时错误时先确认安装包版本。
- Bundled Codex harness 已随 v2026.5.26 对齐到 Codex CLI 0.134.0，Codex code mode 问题不要只查外部 Codex CLI，也要看 OpenClaw app-server 与 auth profile。
- macOS app 内嵌 Peekaboo Bridge 更新到 3.2.1，UI 自动化权限问题先重新授权 Accessibility / Screen Recording。
- Gateway、CLI-backed runtimes、agent run recovery 和 session 绑定在 v2026.6.8 后恢复更稳；启动失败时先看 `openclaw doctor`、Gateway 日志、release verification 和插件/Skill Workshop 状态。
- Docker、release/diagnostics、插件索引、bounded logs 和 latest tag parsing 在 v2026.6.8 继续加固；生产部署不要跳过发布包 integrity / shrinkwrap 校验。

### 3.1 npm 全局安装（推荐）

```bash
npm install -g openclaw@latest

# 验证安装
openclaw --version
```

### 3.2 使用 yarn

```bash
yarn global add openclaw
openclaw --version
```

### 3.3 使用 pnpm（高性能的 npm 替代品）

```bash
pnpm add -g openclaw
openclaw --version
```

### 3.4 使用 npx（免安装体验）

如果你只是想试试，不想全局安装：

```bash
npx openclaw --version
npx openclaw onboard --install-daemon
```

> **注意**：npx 每次运行都会检查最新版本，适合体验，不适合生产环境。

### 3.5 安装方式对比

| 方式 | 命令 | 优点 | 缺点 |
|------|------|------|------|
| npm | `npm i -g openclaw@latest` | 最通用、文档最多 | 全局安装可能需要权限 |
| yarn | `yarn global add openclaw` | 速度快、缓存好 | 需要额外安装 yarn |
| pnpm | `pnpm add -g openclaw` | 磁盘占用小 | 需要额外安装 pnpm |
| npx | `npx openclaw` | 免安装 | 每次启动慢 |

---

## 4. 引导向导（openclaw onboard）

安装完 CLI 后，运行引导向导完成初始配置：

```bash
openclaw onboard --install-daemon
```

向导会引导你完成以下步骤：

### 4.1 选择 AI 模型提供商

```
? 选择你的 AI 模型提供商:
  ❯ DeepSeek（具体模型以当前目录为准）
    OpenAI（具体模型以当前目录为准）
    Anthropic（具体模型以当前目录为准）
    Google / Vertex（具体模型以当前目录为准）
    本地模型 (Ollama)
    自定义 API (OpenAI 兼容)
```

### 4.2 配置 API Key

```
? 输入你的 OpenAI API Key: sk-proj-xxxxxxxxxxxxx
✓ API Key 验证成功！
✓ 可用模型: gpt-5.4, gpt-5.2-mini
```

### 4.3 选择消息平台

```
? 你想连接哪些消息平台？（可多选）
  ❯ ◉ Telegram
    ◉ WhatsApp
    ◯ Discord
    ◯ Slack
    ◯ 微信（企业微信）
    ◯ 飞书
    ◯ Web Chat（内置网页界面）
```

### 4.4 配置 Gateway

```
? Gateway 监听端口: (18789)
? 启用 Control UI 控制面板？ (Y/n)
? Control UI 访问密码: ********
```

### 4.5 完成配置

```
✓ 配置文件已生成: ~/.openclaw/openclaw.json
✓ Gateway 守护进程已安装（launchd/systemd user service）
✓ Gateway 已启动: http://localhost:18789

OpenClaw 安装完成！

下一步：
  openclaw gateway          启动 Gateway
  openclaw channels list    查看频道
  openclaw models list      查看可用模型
```

> **提示**：引导向导生成的配置文件在 `~/.openclaw/openclaw.json`（JSON5 格式），你可以随时手动编辑。

---

## 5. macOS 安装完整流程

### 5.1 使用 Homebrew（最简单）

```bash
# 安装 Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node@22

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行引导向导
openclaw onboard --install-daemon
```

### 5.2 使用 nvm

```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc

# 安装 Node.js 24
nvm install 22
nvm alias default 22

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行引导向导
openclaw onboard --install-daemon
```

### 5.3 Apple Silicon 注意事项

M1/M2/M3/M4 芯片的 Mac 完全支持，不需要 Rosetta。如果遇到原生模块编译问题：

```bash
# 确保 Xcode Command Line Tools 已安装
xcode-select --install

# 如果 node-gyp 编译失败
brew install python-setuptools
```

---

## 6. Linux 安装完整流程

### 6.1 Ubuntu / Debian

```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装必要工具
sudo apt install -y curl git build-essential

# 安装 Node.js 24（NodeSource 方式）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 验证
node --version  # v22.x.x
npm --version   # 10.x.x

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行引导向导
openclaw onboard --install-daemon
```

### 6.2 CentOS / RHEL

```bash
# 安装必要工具
sudo yum groupinstall -y "Development Tools"
sudo yum install -y curl git

# 安装 Node.js 24
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行引导向导
openclaw onboard --install-daemon
```

### 6.3 Arch Linux

```bash
# 安装 Node.js
sudo pacman -S nodejs npm

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行引导向导
openclaw onboard --install-daemon
```

### 6.4 权限问题处理

Linux 上全局安装 npm 包可能遇到权限问题。推荐方案：

**方案一：使用 nvm（推荐）**

nvm 安装的 Node.js 在用户目录下，不需要 sudo：

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
npm install -g openclaw@latest  # 不需要 sudo
```

**方案二：修改 npm 全局目录**

```bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest  # 不需要 sudo
```

**方案三：修改目录权限（不推荐）**

```bash
sudo chown -R $(whoami) /usr/lib/node_modules
npm install -g openclaw@latest
```

---

## 7. Windows 安装完整流程

### 7.1 WSL2 安装（强烈推荐）

Windows 上运行 OpenClaw 最稳定的方式是通过 WSL2：

```powershell
# 1. 安装 WSL2（管理员 PowerShell）
wsl --install

# 2. 重启电脑后，打开 Ubuntu 终端

# 3. 在 WSL2 Ubuntu 中安装
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

### 7.2 原生 Windows 安装

如果不想用 WSL2，也可以原生安装：

1. 从 [Node.js 官网](https://nodejs.org/) 下载 Windows 安装包
2. 运行安装程序，勾选 "Automatically install the necessary tools"
3. 打开新的 PowerShell 或 CMD：

```powershell
node --version
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

> **v2026.5.22 默认 Shell 提示**：Windows 教程不要只写“打开终端”。先明确当前默认 Shell 是 WSL2 Ubuntu bash、PowerShell 还是 CMD，再执行安装和 `openclaw onboard`。如果项目后续需要运行脚本、Docker 或浏览器工具，也把默认 Shell 写进团队安装记录，避免同一条命令在 WSL2 与原生 Windows 下表现不同。

### 7.3 WSL2 vs 原生安装对比

| 特性 | WSL2 | 原生 Windows |
|------|------|-------------|
| 稳定性 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 性能 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 兼容性 | 完全兼容 Linux 生态 | 部分原生模块可能有问题 |
| 文件系统 | Linux 文件系统 | NTFS |
| 网络 | 需要端口转发 | 直接访问 |
| 推荐度 | ✅ 强烈推荐 | ⚠️ 可用但可能遇到问题 |

---

## 8. Docker 快速安装

如果你只想快速体验，Docker 是最简单的方式：

```bash
# 一行命令启动
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v openclaw-data:/data \
  -e OPENAI_API_KEY=sk-proj-your-key \
  openclaw/openclaw:latest

# 查看状态
docker logs openclaw

# 访问 Control UI
# http://localhost:18789
```

使用 docker-compose：

```yaml
# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
    volumes:
      - openclaw-data:/data
      - ./openclaw.json:/app/openclaw.json
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    restart: unless-stopped

volumes:
  openclaw-data:
```

```bash
docker-compose up -d
```

> **详细的 Docker 部署指南**请参考 [09-Docker部署指南](./09-Docker部署指南.md)，包含生产环境配置、多服务编排、SSL/TLS、备份恢复等内容。

---

> ⏭️ **小白可跳过** — 这部分面向高级用户，新手用默认配置就够了

## 9. 从 Git 仓库克隆并编译安装

适合需要自定义修改或参与开发的用户：

```bash
# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖（推荐使用 pnpm）
pnpm install

# 编译 UI 和主项目
pnpm ui:build && pnpm build

# 链接到全局
pnpm link --global

# 验证
openclaw --version
```

开发模式运行：

```bash
# 监听文件变化，自动重新编译
pnpm gateway:watch

# 运行测试
pnpm test

# 运行 lint
pnpm lint
```

---

## 10. 升级和版本管理

### 10.1 升级到最新版

```bash
# 使用内置升级命令（推荐）
openclaw update --channel stable

# 升级到 beta 通道
openclaw update --channel beta

# 升级到 dev 通道（main 分支头）
openclaw update --channel dev

# 验证新版本
openclaw --version
```

### 10.2 版本通道说明

| 通道 | 说明 | npm dist-tag |
|------|------|-------------|
| stable | 标签发布（vYYYY.M.D） | `latest` |
| beta | 预发布（vYYYY.M.D-beta.N） | `beta` |
| dev | main 分支头 | `dev` |

```bash
# 查看当前通道
openclaw --version

# 也可以通过 npm 安装指定通道
npm install -g openclaw@latest   # stable
npm install -g openclaw@beta     # beta
npm install -g openclaw@dev      # dev
```

### 10.3 版本锁定

如果你需要锁定特定版本（比如生产环境）：

```bash
# 安装指定版本（OpenClaw 使用日期版本号 vYYYY.M.D）
npm install -g openclaw@2026.2.24

# 查看当前安装的版本
openclaw --version
```

### 10.4 回滚到旧版本

```bash
# 卸载当前版本
npm uninstall -g openclaw

# 安装旧版本
npm install -g openclaw@2026.2.20
```

### 10.5 升级注意事项

升级前建议：

1. **备份配置文件**：`cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak`
2. **查看 Changelog**：了解新版本的破坏性变更
3. **升级**：`openclaw update --channel stable`
4. **验证**：`openclaw status`

---

> ⏭️ **小白可跳过** — 这部分面向高级用户，新手用默认配置就够了

## 11. 多环境部署

### 11.1 开发环境

```json5
// ~/.openclaw/openclaw.json（开发环境示例）
{
  gateway: {
    port: 18789,
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.2-mini",  // 开发用便宜模型
    },
  },
  logging: {
    level: "debug",
  },
}
```

### 11.2 测试环境

```json5
{
  gateway: {
    port: 18789,
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.4",
    },
  },
  logging: {
    level: "info",
  },
}
```

> ⏭️ **小白可跳过** — 这部分面向高级用户，新手用默认配置就够了

### 11.3 生产环境

```json5
{
  gateway: {
    port: 18789,
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.4",
    },
  },
  logging: {
    level: "warn",
  },
}
```

> **注意：** `environment`、`debug`、`logLevel`（在 gateway 下）、`rateLimit`、`security` 等字段并非 OpenClaw 配置模式中的真实字段。Gateway 认证通过 `gateway.auth.token` 配置，日志级别通过顶层 `logging` 配置。

### 11.4 使用不同配置文件

```bash
# 可以通过命令行参数指定配置文件
openclaw gateway --config ~/.openclaw/openclaw-dev.json
openclaw gateway --config ~/.openclaw/openclaw-prod.json
```

---

## 12. 安装验证和健康检查


### 12.1 基本验证

```bash
# 检查 CLI 是否正常
openclaw --version
openclaw --help

# 检查配置
openclaw config get

# 检查 Gateway 状态
openclaw status

# 运行诊断工具
openclaw doctor
```

> **v2026.5.22 首次运行行为**：如果直接执行裸命令 `openclaw`，且本机还没有 authored config，新版会进入 classic onboarding。教程仍推荐显式运行 `openclaw onboard --install-daemon`，因为它更清楚地表达“配置 + 安装后台服务”两个动作。

### 12.2 启动 Gateway 并验证

```bash
# 启动 Gateway
openclaw gateway --port 18789 --verbose

# 检查 Gateway 是否在运行（另一个终端）
openclaw status

# 期望输出：
# Gateway Status: running
# Port: 18789
# Uptime: 5 seconds
# Connected Channels: 0
# Active Agents: 1
```

v2026.5.22 对 Gateway ready 路径做了缓存和延迟加载优化：未用到的 handler tree、插件 metadata、channel catalog、ACPX runtime 不应阻塞首次 ready。排障时先区分三种状态：

| 状态 | 说明 | 处理方式 |
|---|---|---|
| CLI 可用但 Gateway 未 ready | 配置或后台服务还没启动完 | 看 `openclaw gateway --verbose` |
| Gateway ready 但插件未 ready | 可选插件仍在懒加载 | 看插件日志，不要直接判定安装失败 |
| Gateway ready 抖动 | restart trace 或依赖服务异常 | 先跑 `openclaw doctor`，再看 Gateway 日志 |

### 12.3 API 连通性测试

```bash
# 检查模型状态
openclaw models list

# 健康检查
openclaw health
```

### 12.4 Control UI 访问

Gateway 启动后，Control UI 通过 Gateway WebSocket 提供，访问 `http://localhost:18789`，你应该能看到：

- Gateway 运行状态
- 已连接的消息平台列表
- Agent 列表和状态
- 消息统计和日志

---

> 💡 **遇到问题？** 直接来这里找答案，大部分安装问题都能在这里解决

## 13. 常见安装问题排查

### 13.1 权限问题

**症状**：`EACCES: permission denied`

```bash
# 方案一：使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
npm install -g openclaw@latest

# 方案二：修改 npm 目录权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

### 13.2 网络问题

**症状**：`npm ERR! network timeout`

```bash
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest

# 或者使用代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm install -g openclaw@latest

# 安装完成后恢复
npm config delete proxy
npm config delete https-proxy
npm config set registry https://registry.npmjs.org
```

### 13.3 Node.js 版本过低

**症状**：`Error: OpenClaw requires Node.js 22.19 or higher`

```bash
# 检查当前版本
node --version

# 使用 nvm 升级
nvm install 22
nvm use 22

# 或者使用 NodeSource 升级
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
```

### 13.4 原生模块编译失败

**症状**：`node-gyp rebuild failed`

```bash
# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install -y build-essential python3

# CentOS/RHEL
sudo yum groupinstall -y "Development Tools"
sudo yum install -y python3
```

### 13.5 端口被占用

**症状**：`Error: listen EADDRINUSE: address already in use :::18789`

```bash
# 查看占用端口的进程
lsof -i :18789  # macOS/Linux
netstat -ano | findstr :18789  # Windows

# 杀掉占用进程
kill -9 <PID>

# 或者修改 OpenClaw 端口
openclaw config set gateway.port 18790
```

### 13.6 API Key 无效

**症状**：`Error: Invalid API key`

```bash
# 检查 API Key 是否正确设置
openclaw config get

# 重新设置
openclaw config set model.apiKey sk-proj-your-new-key

# 检查模型状态
openclaw models list
```

### 13.7 WSL2 网络问题

**症状**：WSL2 中无法访问外部网络

```bash
# 检查 DNS 配置
cat /etc/resolv.conf

# 如果 DNS 有问题，手动设置
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

# 检查网络连通性
ping google.com
curl -I https://registry.npmjs.org
```

---

## 14. 卸载

### 14.1 卸载 CLI

```bash
# npm 卸载
npm uninstall -g openclaw

# yarn 卸载
yarn global remove openclaw

# pnpm 卸载
pnpm remove -g openclaw
```

### 14.2 清理配置和数据

```bash
# 删除配置目录
rm -rf ~/.openclaw

# 删除日志文件
rm -rf ~/.openclaw/logs
```

### 14.3 Docker 卸载

```bash
# 停止并删除容器
docker stop openclaw && docker rm openclaw

# 删除数据卷（注意：这会删除所有数据）
docker volume rm openclaw-data

# 删除镜像
docker rmi openclaw/openclaw:latest
```

---

## 15. 安装现场 Runbook：多人一起安装时怎么排队

如果你要带团队安装 OpenClaw，不要让所有人同时冲到消息平台接入。先统一环境，再跑 Gateway，再测模型，最后才接平台。

### 15.1 开始前收集信息

```md
# OpenClaw Install Sheet

## Machine

- OS:
- Shell:
- Node:
- npm / pnpm / yarn:
- Docker:

## Install Method

- install script:
- npm global:
- Docker:
- source build:

## Config

- config path:
- gateway port:
- model provider:
- first channel:

## Status

- onboard:
- gateway:
- doctor:
- first message:
```

这张表的价值不是好看，而是排障时能快速知道每个人卡在哪一层。

### 15.2 课堂节奏

```text
第 1 段：确认 Node 和 shell。
第 2 段：安装 OpenClaw CLI。
第 3 段：运行 onboard。
第 4 段：启动 Gateway。
第 5 段：运行 doctor。
第 6 段：发第一条消息。
第 7 段：才开始接平台。
```

如果有人在第 2 段卡住，不要让全班等。让他继续听后续概念，课后按安装问题排查。OpenClaw 是长期运行工具，不需要所有人同一分钟完成同一个命令。

### 15.3 三类故障分流

```text
A 类：可以继续
- CLI 已安装。
- Gateway 能启动。
- doctor 只有非阻塞提醒。

B 类：需要旁路协助
- onboard 失败。
- API Key 或模型不通。
- 端口冲突。

C 类：先不要继续写配置
- 不确定当前账号和 token。
- 使用生产服务器但安全边界没确认。
- Docker volume 或配置目录可能覆盖已有数据。
```

对 A 类：

```text
继续快速开始。
平台接入可以晚一点做。
```

对 B 类：

```text
记录命令、错误、系统和配置路径。
不要反复重装。
```

对 C 类：

```text
停止写入配置。
先备份或确认环境归属。
```

## 16. 安装后第一条可用链路

安装完成不等于系统可用。最小可用链路是：

```text
openclaw --version
  ↓
openclaw onboard --install-daemon
  ↓
openclaw gateway --port 18789 --verbose
  ↓
openclaw doctor
  ↓
openclaw agent --message "ping"
```

每一步失败时的含义不同。

```text
version 失败：
CLI 没装好，或 PATH 不对。

onboard 失败：
配置生成、模型凭据或 daemon 安装出错。

gateway 失败：
端口、配置文件、权限或运行环境问题。

doctor 失败：
可能是模型、channel、配置或系统依赖问题。

agent ping 失败：
Agent / model / gateway 链路仍未完整跑通。
```

安装课作业：

```md
# First Working Chain

## Commands

- openclaw --version:
- openclaw onboard:
- openclaw gateway:
- openclaw doctor:
- first message:

## First Error

...

## Fixed By

...

## Next Risk

...
```

这份作业能把安装经验留下来。下次换机器、换同事、换服务器时，不需要从头猜。

## 17. 升级前后怎么保护配置

OpenClaw 是长驻服务，升级前要保护配置和数据。

升级前：

```bash
# 备份配置目录
cp -R ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)

# 记录当前版本
openclaw --version

# 记录当前配置
openclaw config get
```

升级后：

```bash
openclaw --version
openclaw doctor
openclaw gateway --port 18789 --verbose
```

升级复盘：

```md
# OpenClaw Upgrade Note

## Before

Version:
Install method:
Config backup:

## Upgrade

Command:
Channel:

## After

Doctor:
Gateway:
First message:

## Issues

...

## Rollback

...
```

不要把升级当成“跑一个命令”。只要你的 OpenClaw 接了消息平台、记忆和团队配置，升级就是一次小型运维动作。

## 18. 安装方式选择：脚本、npm、Docker、源码各适合谁

```text
官方安装脚本：
适合个人和普通用户，最快跑通。

npm / pnpm 全局安装：
适合熟悉 Node 生态的人，方便版本控制和排查 PATH。

Docker：
适合服务器长期运行，便于隔离、备份、重启和反向代理。

源码构建：
适合贡献代码、调试 OpenClaw 本身、开发插件或修改内部逻辑。
```

选择建议：

```text
第一次学习：
脚本或 npm。

团队服务器：
Docker。

开发 OpenClaw：
源码构建。

Windows 用户：
优先 WSL2，除非你明确知道原生 Windows 下的 shell、路径和依赖差异。
```

安装方式不是信仰问题，而是维护问题。你以后要怎么升级、备份、看日志、重启，就应该反过来决定今天怎么安装。

## 19. 安装前环境画像：先知道自己在哪

很多安装问题不是 OpenClaw 特有问题，而是 Node、shell、PATH、代理、权限、Windows/WSL2 差异带来的。正式安装前，先写一份环境画像。

```bash
uname -a
node --version
npm --version
git --version
echo $SHELL
which node
which npm
```

记录成这样：

```md
# OpenClaw Install Profile

## Machine

- OS:
- Shell:
- CPU:
- RAM:

## Runtime

- Node:
- npm:
- Git:
- Install method:

## Network

- Region:
- Proxy:
- npm registry:

## Permission

- npm global path:
- current user:
- using sudo:
```

这份记录能帮你快速判断问题类型：

| 现象 | 可能原因 |
|---|---|
| `openclaw` 找不到 | npm 全局 bin 不在 PATH |
| `node` 版本太低 | 系统自带 Node 覆盖 nvm |
| 安装卡住 | npm registry、代理、网络 |
| 原生模块编译失败 | Python、make、Xcode/Build Tools 缺失 |
| WSL2 能装，Windows 原生失败 | 路径、shell、权限和原生依赖差异 |

安装前多花 3 分钟，后面少猜半小时。

## 20. 失败恢复：不要反复重装

安装失败时，最容易做错的是连续运行不同安装命令：脚本跑一半失败，再 npm，全局权限失败又 sudo，再换 pnpm。这样会把问题叠在一起。

更稳的恢复顺序：

### 20.1 命令不存在

```bash
npm bin -g
npm prefix -g
echo $PATH
```

如果全局 bin 不在 PATH，把它加入 shell 配置。使用 nvm 时，确认当前 shell 已加载 nvm：

```bash
command -v nvm
node --version
```

### 20.2 npm 权限错误

不要第一反应 `sudo npm install -g`。优先使用 nvm 重新管理 Node：

```bash
nvm install 24
nvm use 24
npm install -g openclaw
```

如果你已经用 sudo 装过，可能需要检查全局目录 owner：

```bash
npm prefix -g
ls -la "$(npm prefix -g)"
```

### 20.3 配置写坏了

OpenClaw 配置是 JSON5，支持注释和尾逗号，但仍然可能因为括号、引号、路径写错导致启动失败。先备份再改：

```bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d%H%M%S)
openclaw doctor
```

如果改完 Gateway 起不来，把备份复制回来：

```bash
cp ~/.openclaw/openclaw.json.bak.YYYYMMDDHHMMSS ~/.openclaw/openclaw.json
```

### 20.4 Gateway 起不来

按顺序查：

```bash
# 端口
lsof -i :18789 || ss -tlnp | grep 18789

# 配置
openclaw doctor

# 前台日志
openclaw gateway --port 18789 --verbose
```

如果端口被占用，先不要杀进程。确认占用者是不是另一个 OpenClaw：

```bash
ps aux | grep openclaw
```

如果是旧 Gateway，正常停止或换端口；如果是未知进程，再决定是否处理。

## 21. 换机器迁移：安装和数据分开处理

换电脑时不要把“重新安装 OpenClaw”和“迁移旧数据”混成一步。先在新机器装干净，再迁移必要数据。

第一步，新机器安装 CLI：

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

第二步，旧机器导出核心数据：

```bash
tar -czf openclaw-user-data.tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/workspace/MEMORY.md \
  ~/.openclaw/workspace/USER.md \
  ~/.openclaw/workspace/memory
```

第三步，新机器恢复：

```bash
tar -xzf openclaw-user-data.tar.gz -C ~/
openclaw memory index
openclaw doctor
```

谨慎迁移这些：

```text
auth-profiles.json
credentials/
sessions/
channel login state
```

这些文件可能包含平台凭证、会话历史、设备绑定。新机器上更稳的方式通常是重新登录消息平台和 provider，而不是直接复制所有认证状态。

迁移后做三件事：

```bash
openclaw --version
openclaw models status
openclaw channels status
```

然后发送一条测试消息。能本地聊，不代表消息平台也恢复了；消息平台通常还需要重新扫码、重新设置 webhook，或者更新平台后台的回调地址。

## 22. 团队安装模板：减少“每个人都不一样”

如果你要带团队或课程学员一起安装，建议给大家一个统一模板，而不是让每个人自由选择。

推荐组合：

```text
macOS:
nvm + Node 24 + npm global + OpenClaw onboard

Linux:
nvm 或 NodeSource + npm global + OpenClaw onboard

Windows:
WSL2 Ubuntu + nvm + Node 24 + npm global

服务器：
Docker Compose + .env + volume + 反向代理
```

统一模板的好处：

- 报错更容易互相对照。
- PATH、Node 版本、权限问题更少。
- 教程截图和命令更容易一致。
- 后续升级和卸载更容易讲清楚。

可以发给团队一段标准安装命令：

```bash
# 1. 检查 Node
node --version

# 2. 如果 Node 不是 22.19+ 或 24.x，先用 nvm 安装
nvm install 24
nvm use 24

# 3. 安装 OpenClaw
npm install -g openclaw

# 4. 初始化
openclaw onboard --install-daemon

# 5. 诊断
openclaw doctor
```

让每个人把结果贴到同一份安装记录：

```md
| Name | OS | Node | OpenClaw | Install Method | Status | Error |
|---|---|---|---|---|---|---|
| Kim | WSL2 Ubuntu | v24.x | v2026.x | npm | ok | - |
```

团队安装的重点不是"每个人都立刻成功"，而是失败时能快速归类。

## 23. 安装后的文件地图

装完 OpenClaw 后，你至少要知道哪些文件不能乱删。

常见位置：

```text
~/.openclaw/
├── openclaw.json          # 主配置
├── logs/                  # 日志
├── workspace/             # 默认 Agent 工作空间
│   ├── SOUL.md
│   ├── USER.md
│   ├── MEMORY.md
│   └── memory/
├── agents/                # Agent 状态
├── credentials/           # 平台凭证或登录状态
└── auth-profiles.json     # 认证资料
```

第一次安装完成后，建议运行：

```bash
ls -la ~/.openclaw
find ~/.openclaw -maxdepth 2 -type f | sort
```

把关键路径记下来：

```md
# OpenClaw Local Map

## Config

~/.openclaw/openclaw.json

## Logs

~/.openclaw/logs/

## Default Workspace

~/.openclaw/workspace/

## Memory

~/.openclaw/workspace/MEMORY.md
~/.openclaw/workspace/USER.md
~/.openclaw/workspace/memory/

## Credentials

~/.openclaw/credentials/
~/.openclaw/auth-profiles.json
```

这张地图对卸载、迁移、备份都很重要。尤其是 `credentials` 和 `auth-profiles.json`，里面可能包含平台登录状态，不要随意上传、截图或发给别人。

## 24. 安装方式切换：从 npm 迁到 Docker

很多人先用 npm 在本地跑通，后面想迁到服务器或 Docker。迁移时要把“程序”和“数据”分开。

第一步，在旧环境记录：

```bash
openclaw --version
openclaw config get agents.defaults.model
openclaw channels status
```

第二步，备份数据：

```bash
tar -czf openclaw-local-data.tar.gz ~/.openclaw
```

如果你只想迁移核心配置和记忆，而不迁移凭证：

```bash
tar -czf openclaw-core-data.tar.gz \
  ~/.openclaw/openclaw.json \
  ~/.openclaw/workspace/SOUL.md \
  ~/.openclaw/workspace/USER.md \
  ~/.openclaw/workspace/MEMORY.md \
  ~/.openclaw/workspace/memory
```

第三步，在 Docker 服务器先启动空实例：

```bash
docker compose up -d
docker compose ps
```

第四步，把数据恢复到 volume 或 bind mount。Docker volume / bind mount 的完整写法放在 [09-Docker部署指南](./09-Docker部署指南.md)，安装篇这里只强调迁移原则：新的容器必须挂载同一个持久化数据目录，否则配置、记忆和会话不会自动出现。

恢复：

```bash
mkdir -p /opt/openclaw/data/openclaw
tar -xzf openclaw-core-data.tar.gz -C /opt/openclaw/data/openclaw --strip-components=2
```

第五步，重新配置平台凭证。消息平台 token、扫码登录、Webhook 地址通常和机器有关，迁移后要重新确认。

```bash
docker compose exec openclaw-gateway openclaw doctor
docker compose exec openclaw-gateway openclaw channels status
```

不要直接假设旧机器的所有认证状态在 Docker 中都能继续工作。先恢复配置和记忆，再重新连接平台，是更稳的迁移方式。

## 25. 安装问题复盘：把一次失败变成文档资产

如果你在安装时踩坑，建议顺手写一条复盘。格式可以很短：

```md
# Install Issue Note

## Symptom

`openclaw` command not found.

## Environment

- OS:
- Node:
- npm:
- Install method:

## Cause

npm global bin path was not in PATH.

## Fix

Added npm global bin to shell profile and restarted terminal.

## Next Time

Run `npm prefix -g` and `echo $PATH` before reinstalling.
```

这类复盘会直接帮助下一位读者。安装教程最有价值的部分，往往不是顺利路径，而是失败后怎么恢复。

## 26. Windows / WSL2 特别说明

Windows 用户最容易卡在三个地方：路径、shell、网络。推荐优先使用 WSL2，是因为 OpenClaw 的很多命令、脚本、依赖和 Linux/macOS 更接近。

### 26.1 路径边界

在 WSL2 里，尽量把 OpenClaw 工作目录放在 Linux 文件系统中：

```text
/home/<user>/project
~/.openclaw
```

不要长期放在：

```text
/mnt/c/Users/<user>/...
```

原因：

```text
- 文件权限表现不同。
- 大量小文件读写更慢。
- 某些工具对 Windows 路径处理不一致。
```

### 26.2 shell 边界

在 WSL2 Ubuntu 里安装，就在 WSL2 里运行：

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

不要一会儿在 PowerShell 里装，一会儿在 WSL2 里跑。两个环境的 Node、npm、PATH、home 目录都不同。

### 26.3 浏览器访问

如果 Gateway 在 WSL2 里监听 `127.0.0.1:18789`，Windows 浏览器通常可以访问：

```text
http://localhost:18789
```

如果打不开，先在 WSL2 里测：

```bash
curl -i http://127.0.0.1:18789/health
```

WSL2 内部能访问，Windows 浏览器不能访问，问题在 Windows/WSL 网络转发；WSL2 内部也不能访问，问题在 Gateway 或端口。

### 26.4 代理和 npm registry

中国网络环境下，npm 或 provider API 可能不稳定。先区分：

```text
npm 安装慢：
是包下载问题。

模型 API 超时：
是 provider 网络问题。

Webhook 不通：
是外部平台访问你 Gateway 的问题。
```

不要用一个代理设置解决所有问题。安装、模型、Webhook 是三条不同链路。

## 27. 安装完成后的安全起步

刚安装完就应该做几个基础安全动作，不用等到生产部署。

```bash
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
```

如果已经产生日志：

```bash
chmod 750 ~/.openclaw/logs 2>/dev/null || true
chmod 640 ~/.openclaw/logs/*.log 2>/dev/null || true
```

确认配置里没有明文 Key：

```bash
rg -n "sk-|token|password|secret|AKIA" ~/.openclaw
```

如果你为了测试把 Key 写进了配置，尽快改成环境变量：

```bash
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
```

安装章节看起来和安全无关，但安装时形成的习惯会一直延续到生产。把 token 放环境变量、知道配置位置、知道如何备份，是最早应该养成的习惯。

## 28. 企业网络和代理环境

在公司网络、校园网或国内网络环境里，安装失败不一定是 OpenClaw 问题。常见卡点有三类：

```text
npm registry：
包下载慢或失败。

GitHub：
源码、release、脚本下载失败。

模型 provider：
安装成功，但模型 API 超时。
```

先分别测试：

```bash
npm ping
git ls-remote https://github.com/openclaw/openclaw.git HEAD
curl -I https://api.openai.com
```

如果 npm 慢，可以临时切 registry：

```bash
npm config get registry
npm config set registry https://registry.npmmirror.com
npm install -g openclaw
npm config set registry https://registry.npmjs.org
```

如果公司要求代理：

```bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
```

注意：代理变量会影响当前 shell 中的安装和运行。记录下来：

```md
# Network Note

## npm registry

...

## proxy

HTTP_PROXY:
HTTPS_PROXY:

## model provider reachable

...
```

如果 OpenClaw 在 Docker 里运行，宿主机有代理不代表容器有代理。需要在 compose 里传入：

```yaml
environment:
  - HTTP_PROXY=http://host.docker.internal:7890
  - HTTPS_PROXY=http://host.docker.internal:7890
extra_hosts:
  - "host.docker.internal:host-gateway"
```

企业网络还有一种情况：外部平台 webhook 无法访问内网机器。这时不要硬开公网端口。优先使用：

```text
- WebChat / CLI 做本地测试。
- SSH 隧道。
- Tailscale / VPN。
- 平台支持的 polling 或 socket 模式。
- 正式反向代理和 TLS。
```

网络问题要分层排查：安装包下载、模型 API、消息平台回调是三条不同路径。

## 29. 多版本共存和试验环境

如果你要试 beta/dev 通道，建议不要直接在主环境上试。可以用不同的 `OPENCLAW_HOME` 创建隔离环境。

```bash
export OPENCLAW_HOME=~/.openclaw-dev
openclaw onboard
openclaw gateway --port 28789 --verbose
```

这样主环境仍然在：

```text
~/.openclaw
```

试验环境在：

```text
~/.openclaw-dev
```

记录：

```md
# OpenClaw Dev Environment

## Home

~/.openclaw-dev

## Port

28789

## Purpose

Test beta/dev channel before upgrading main environment.

## Do not copy

- production credentials
- real channel tokens
- private memory
```

试验环境里不要放真实 token，也不要连接正式消息平台。它只用来试版本、试插件、试配置。

如果试验通过，再回到主环境升级。这样即使 beta/dev 有问题，也不会影响你的日常入口和记忆。

---

## 下一步

安装完成后，建议按以下顺序继续：

| 下一步 | 文档 | 说明 |
|--------|------|------|
| 快速体验 | [03-快速开始指南](./03-快速开始指南.md) | 5 分钟上手 |
| 配置模型 | [04-模型配置指南](./04-模型配置指南.md) | 详细的模型配置 |
| 接入平台 | [05-消息平台接入指南](./05-消息平台接入指南.md) | 连接 Telegram、WhatsApp 等 |
| Docker 部署 | [09-Docker部署指南](./09-Docker部署指南.md) | 生产环境容器化部署 |
| 安全配置 | [10-安全配置指南](./10-安全配置指南.md) | API Key 安全、网络安全 |