02 · 安装部署指南

⚠️ OpenClaw 迭代很快：界面、版本、命令和模型能力可能随版本变化。遇到与页面描述不一致时，以你当前看到的界面和官方文档（docs.openclaw.ai）为准，不要在未确认的情况下执行高权限或不可逆操作。

概述

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

这篇指南覆盖 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：

从 nvm-windows releases 下载最新安装包
运行安装程序
打开新的命令行窗口：

powershell

nvm install 24
nvm use 24
node --version

2.2 使用官方安装包

直接从 Node.js 官网下载 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.1 安装基线：官方 README 当前写法是 Node 24 recommended，Node 22.19+ supported。新装优先走 openclaw onboard，升级和回滚按 release channel 选择 stable / beta / dev；教程里的固定版本号只用于复现问题，不建议长期锁死。v2026.6.5-beta.x 是预发布线，不作为本教程默认稳定基线。

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

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 和 session 绑定在 v2026.6.1 后恢复更稳；启动失败时先看 openclaw doctor、Gateway 日志、release verification 和插件/Skill Workshop 状态。
Docker、release/diagnostics、插件索引和 bounded logs 在 v2026.6.1 继续加固；生产部署不要跳过发布包 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，也可以原生安装：

从 Node.js 官网下载 Windows 安装包
运行安装程序，勾选 "Automatically install the necessary tools"
打开新的 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部署指南，包含生产环境配置、多服务编排、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 升级注意事项

升级前建议：

备份配置文件：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
查看 Changelog：了解新版本的破坏性变更
升级：openclaw update --channel stable
验证：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 开始前收集信息

# 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 链路仍未完整跑通。

安装课作业：

# 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

升级复盘：

# 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

记录成这样：

# 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

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

| 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

把关键路径记下来：

# 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部署指南，安装篇这里只强调迁移原则：新的容器必须挂载同一个持久化数据目录，否则配置、记忆和会话不会自动出现。

恢复：

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. 安装问题复盘：把一次失败变成文档资产

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

# 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 中的安装和运行。记录下来：

# 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

记录：

# 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-快速开始指南	5 分钟上手
配置模型	04-模型配置指南	详细的模型配置
接入平台	05-消息平台接入指南	连接 Telegram、WhatsApp 等
Docker 部署	09-Docker部署指南	生产环境容器化部署
安全配置	10-安全配置指南	API Key 安全、网络安全

02 · 安装部署指南 ​

概述 ​

1. 系统要求 ​

1.1 硬件要求 ​

1.2 操作系统要求 ​

1.3 软件依赖 ​

2. Node.js 环境安装 ​

2.1 使用 nvm 安装（推荐） ​

2.2 使用官方安装包 ​

2.3 使用 Homebrew（macOS） ​

2.4 安装方式对比 ​

3. 安装 OpenClaw CLI ​

3.1 npm 全局安装（推荐） ​

3.2 使用 yarn ​

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

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

3.5 安装方式对比 ​

4. 引导向导（openclaw onboard） ​

4.1 选择 AI 模型提供商 ​

4.2 配置 API Key ​

4.3 选择消息平台 ​

4.4 配置 Gateway ​

4.5 完成配置 ​

5. macOS 安装完整流程 ​

5.1 使用 Homebrew（最简单） ​

5.2 使用 nvm ​

5.3 Apple Silicon 注意事项 ​

6. Linux 安装完整流程 ​

6.1 Ubuntu / Debian ​

6.2 CentOS / RHEL ​

6.3 Arch Linux ​

6.4 权限问题处理 ​

7. Windows 安装完整流程 ​

7.1 WSL2 安装（强烈推荐） ​

7.2 原生 Windows 安装 ​

7.3 WSL2 vs 原生安装对比 ​

8. Docker 快速安装 ​

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

10. 升级和版本管理 ​

10.1 升级到最新版 ​

10.2 版本通道说明 ​

10.3 版本锁定 ​

10.4 回滚到旧版本 ​

10.5 升级注意事项 ​

11. 多环境部署 ​

11.1 开发环境 ​

11.2 测试环境 ​

11.3 生产环境 ​

11.4 使用不同配置文件 ​

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

12.1 基本验证 ​

12.2 启动 Gateway 并验证 ​

12.3 API 连通性测试 ​

12.4 Control UI 访问 ​

13. 常见安装问题排查 ​

13.1 权限问题 ​

13.2 网络问题 ​

13.3 Node.js 版本过低 ​

13.4 原生模块编译失败 ​

13.5 端口被占用 ​

13.6 API Key 无效 ​

13.7 WSL2 网络问题 ​

14. 卸载 ​

14.1 卸载 CLI ​

14.2 清理配置和数据 ​

14.3 Docker 卸载 ​

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

15.1 开始前收集信息 ​

15.2 课堂节奏 ​

15.3 三类故障分流 ​

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

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

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

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

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

20.1 命令不存在 ​

20.2 npm 权限错误 ​

20.3 配置写坏了 ​

20.4 Gateway 起不来 ​

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

02 · 安装部署指南

概述

1. 系统要求

1.1 硬件要求

1.2 操作系统要求

1.3 软件依赖

2. Node.js 环境安装

2.1 使用 nvm 安装（推荐）

2.2 使用官方安装包

2.3 使用 Homebrew（macOS）

2.4 安装方式对比

3. 安装 OpenClaw CLI

3.1 npm 全局安装（推荐）

3.2 使用 yarn

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

3.4 使用 npx（免安装体验）

3.5 安装方式对比

4. 引导向导（openclaw onboard）

4.1 选择 AI 模型提供商

4.2 配置 API Key

4.3 选择消息平台

4.4 配置 Gateway

4.5 完成配置

5. macOS 安装完整流程

5.1 使用 Homebrew（最简单）

5.2 使用 nvm

5.3 Apple Silicon 注意事项

6. Linux 安装完整流程

6.1 Ubuntu / Debian

6.2 CentOS / RHEL

6.3 Arch Linux

6.4 权限问题处理

7. Windows 安装完整流程

7.1 WSL2 安装（强烈推荐）

7.2 原生 Windows 安装

7.3 WSL2 vs 原生安装对比

8. Docker 快速安装

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

10. 升级和版本管理

10.1 升级到最新版

10.2 版本通道说明

10.3 版本锁定

10.4 回滚到旧版本

10.5 升级注意事项

11. 多环境部署

11.1 开发环境

11.2 测试环境

11.3 生产环境

11.4 使用不同配置文件

12. 安装验证和健康检查

12.1 基本验证

12.2 启动 Gateway 并验证

12.3 API 连通性测试

12.4 Control UI 访问

13. 常见安装问题排查

13.1 权限问题

13.2 网络问题

13.3 Node.js 版本过低

13.4 原生模块编译失败

13.5 端口被占用

13.6 API Key 无效

13.7 WSL2 网络问题

14. 卸载

14.1 卸载 CLI

14.2 清理配置和数据

14.3 Docker 卸载

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

15.1 开始前收集信息

15.2 课堂节奏

15.3 三类故障分流

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

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

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

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

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

20.1 命令不存在

20.2 npm 权限错误

20.3 配置写坏了

20.4 Gateway 起不来

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