02. 安装部署指南

难度：入门 | ⏱️ 阅读时间：20 分钟 | 前置知识：会用命令行（终端）

本篇你将学会： 在 macOS/Linux/Windows 上安装 OpenClaw，配置运行环境，完成首次启动

小白速通： 直接跳到"快速安装"章节（第 3 节），跟着复制粘贴命令就行。遇到问题看第 12-13 节的故障排查

概述

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

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

1. 安装运行环境（Node.js 22+）
2. 安装 OpenClaw CLI
3. 运行引导向导（openclaw onboard）

下面我们从系统要求开始，一步步来。

1. 系统要求

1.1 硬件要求

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

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

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

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

1.2 操作系统要求

1.3 软件依赖

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

# 检查 Node.js 版本
node --version
# 期望输出：v22.x.x 或更高

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

# 检查 Git 版本
git --version

2. Node.js 环境安装

OpenClaw 需要 Node.js 22 或更高版本。如果你已经有了，跳过这一节。

2.1 使用 nvm 安装（推荐）

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

macOS / Linux：

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

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

# 安装 Node.js 22
nvm install 22

# 设为默认版本
nvm alias default 22

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

Windows：

Windows 用户使用 nvm-windows：

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

nvm install 22
nvm use 22
node --version

2.2 使用官方安装包

直接从 Node.js 官网 下载 LTS 版本安装包：

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

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

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

# Arch Linux
sudo pacman -S nodejs npm

2.3 使用 Homebrew（macOS）

brew install node@22

2.4 安装方式对比

3. 安装 OpenClaw CLI

3.1 npm 全局安装（推荐）

npm install -g openclaw@latest

# 验证安装
openclaw --version

3.2 使用 yarn

yarn global add openclaw
openclaw --version

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

pnpm add -g openclaw
openclaw --version

3.4 使用 npx（免安装体验）

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

npx openclaw --version
npx openclaw onboard --install-daemon

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

3.5 安装方式对比

4. 引导向导（openclaw onboard）

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

openclaw onboard --install-daemon

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

4.1 选择 AI 模型提供商

? 选择你的 AI 模型提供商:
  ❯ OpenAI (GPT-5.2, GPT-5.2-mini)
    Anthropic (Claude Sonnet 4.6, Claude Haiku 4.5)
    Google (Gemini 2.0 Flash, Gemini 1.5 Pro)
    本地模型 (Ollama)
    自定义 API (OpenAI 兼容)

4.2 配置 API Key

? 输入你的 OpenAI API Key: sk-proj-xxxxxxxxxxxxx
✓ API Key 验证成功！
✓ 可用模型: gpt-5.2, 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（最简单）

# 安装 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

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

# 安装 Node.js 22
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。如果遇到原生模块编译问题：

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

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

6. Linux 安装完整流程

6.1 Ubuntu / Debian

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

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

# 安装 Node.js 22（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

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

# 安装 Node.js 22
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

# 安装 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：

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 全局目录

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

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

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

7. Windows 安装完整流程

7.1 WSL2 安装（强烈推荐）

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

# 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 官网 下载 Windows 安装包
2. 运行安装程序，勾选 "Automatically install the necessary tools"
3. 打开新的 PowerShell 或 CMD：

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

7.3 WSL2 vs 原生安装对比

8. Docker 快速安装

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

# 一行命令启动
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：

# 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:

docker-compose up -d

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

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

9. 从源码编译安装

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

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

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

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

# 链接到全局
pnpm link --global

# 验证
openclaw --version

开发模式运行：

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

# 运行测试
pnpm test

# 运行 lint
pnpm lint

10. 升级和版本管理

10.1 升级到最新版

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

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

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

# 验证新版本
openclaw --version

10.2 版本通道说明

# 查看当前通道
openclaw --version

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

10.3 版本锁定

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

# 安装指定版本
npm install -g openclaw@1.2.3

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

10.4 回滚到旧版本

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

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

10.5 升级注意事项

升级前建议：

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

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

11. 多环境部署

11.1 开发环境

// ~/.openclaw/openclaw.json
{
  environment: "development",
  gateway: {
    port: 18789,
    debug: true,
    logLevel: "debug",
  },
  agent: {
    model: "openai/gpt-5.2-mini",  // 开发用便宜模型
  },
}

11.2 测试环境

{
  environment: "staging",
  gateway: {
    port: 18789,
    debug: false,
    logLevel: "info",
  },
  agent: {
    model: "openai/gpt-5.2",
  },
}

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

11.3 生产环境

{
  environment: "production",
  gateway: {
    port: 18789,
    debug: false,
    logLevel: "warn",
    rateLimit: {
      enabled: true,
      maxRequests: 100,
      windowMs: 60000,
    },
  },
  agent: {
    model: "openai/gpt-5.2",
  },
  security: {
    gatewayToken: "${OPENCLAW_GATEWAY_TOKEN}",
    controlUI: {
      enabled: true,
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
    },
  },
}

11.4 使用环境变量切换

# 开发环境
OPENCLAW_ENV=development openclaw gateway

# 生产环境
OPENCLAW_ENV=production openclaw gateway

12. 安装验证和健康检查

12.1 基本验证

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

# 检查配置
openclaw config get

# 检查 Gateway 状态
openclaw status

# 运行诊断工具
openclaw doctor

12.2 启动 Gateway 并验证

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

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

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

12.3 API 连通性测试

# 检查模型状态
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

# 方案一：使用 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

# 使用淘宝镜像
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 or higher

# 检查当前版本
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

# 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

# 查看占用端口的进程
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

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

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

# 检查模型状态
openclaw models list

13.7 WSL2 网络问题

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

# 检查 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

# npm 卸载
npm uninstall -g openclaw

# yarn 卸载
yarn global remove openclaw

# pnpm 卸载
pnpm remove -g openclaw

14.2 清理配置和数据

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

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

14.3 Docker 卸载

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

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

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

下一步

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