02. 安装部署指南

课程信息

⠀

作者：老金
GitHub：https://github.com/KimYx0207
公众号：老金带你玩AI
X（Twitter）：老金带你玩AI
个人博客：https://aiking.dev
难度等级：🟢 入门
阅读时间：20 分钟
前置知识：会用命令行（终端）

⠀

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

⠀

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

⠀

概述

⠀

这篇指南覆盖 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），硬件要求会大幅提升：

⠀

模型规模

最低内存

1.2 操作系统要求

⠀

操作系统

支持版本

备注

macOS

12 (Monterey) 及以上

Intel 和 Apple Silicon 均支持

Ubuntu/Debian

20.04 LTS 及以上

1.3 软件依赖

⠀

软件

最低版本

推荐版本

用途

Node.js

22.19+ 兼容

24.x

运行时环境

npm（Node Package Manager，Node.js 的包管理器）

10.0.0

10.x（随 Node.js 附带）

包管理器

Git

2.30+

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：

⠀

# 安装 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 下载最新安装包
运行安装程序
打开新的命令行窗口：

⠀

nvm install 24
nvm use 24
node --version

⠀

2.2 使用官方安装包

⠀

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

⠀

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

⠀

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

⠀

brew install node@24

⠀

2.4 安装方式对比

⠀

方式

优点

缺点

适用场景

nvm

多版本管理、不需要 sudo

需要额外安装

开发环境（推荐）

官方安装包

简单直接

升级麻烦、可能需要 sudo

新手、单版本需求

Homebrew

macOS 生态集成好

仅限 macOS

macOS 用户

NodeSource

系统包管理器集成

版本更新可能滞后

服务器部署

3. 安装 OpenClaw CLI

⠀

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

⠀

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

⠀

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 启动路径有缓存和延迟加载优化，升级后启动变快是正常现象；启动失败时看 openclaw doctor、Gateway 日志和 v2026.5.27 release verification。
Docker runtime workspace templates、Alpine 安装、Windows Scheduled Tasks 和稳定 channel 选择在 v2026.5.26 / v2026.5.27 有加固；生产部署不要跳过发布包 integrity / shrinkwrap 校验。

⠀

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 安装方式对比

⠀

方式

命令

优点

缺点

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 后，运行引导向导完成初始配置：

⠀

openclaw onboard --install-daemon

⠀

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

⠀

4.1 选择 AI 模型提供商

⠀

? 选择你的 AI 模型提供商:
  ❯ DeepSeek (V4 Flash — 引导默认, V4 Pro)
    OpenAI (GPT-5.4, GPT-5.2-mini)
    Anthropic (Claude Opus 4.6, Claude Sonnet 4.6)
    Google (Gemini 3.1 Pro, Gemini 2.5 Flash)
    本地模型 (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（最简单）

⠀

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

⠀

# 确保 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 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

⠀

# 安装必要工具
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

⠀

# 安装 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，也可以原生安装：

⠀

从 Node.js 官网下载 Windows 安装包
运行安装程序，勾选 "Automatically install the necessary tools"
打开新的 PowerShell 或 CMD：

⠀

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 是最简单的方式：

⠀

# 一行命令启动
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 仓库克隆并编译安装

⠀

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

⠀

# 克隆仓库
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 版本通道说明

⠀

通道

说明

npm dist-tag

stable

标签发布（vYYYY.M.D）

latest

beta

预发布（vYYYY.M.D-beta.N）

beta

dev

main 分支头

dev

⠀

# 查看当前通道
openclaw --version

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

⠀

10.3 版本锁定

⠀

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

⠀

# 安装指定版本（OpenClaw 使用日期版本号 vYYYY.M.D）
npm install -g [email protected]

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

⠀

10.4 回滚到旧版本

⠀

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

# 安装旧版本
npm install -g [email protected]

⠀

10.5 升级注意事项

⠀

升级前建议：

⠀

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

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

⠀

11. 多环境部署

⠀

11.1 开发环境

⠀

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

⠀

11.2 测试环境

⠀

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

⠀

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

⠀

11.3 生产环境

⠀

{
  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 使用不同配置文件

⠀

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

12. 安装验证和健康检查

⠀

12.1 基本验证

⠀

# 检查 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 并验证

⠀

# 启动 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 连通性测试

⠀

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

下一步

⠀

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

⠀

下一步

文档

说明

快速体验

03-快速开始指南

5 分钟上手

配置模型

04-模型配置指南

详细的模型配置

接入平台

05-消息平台接入指南

连接 Telegram、WhatsApp 等

Docker 部署

09-Docker部署指南

生产环境容器化部署

安全配置

10-安全配置指南

API Key 安全、网络安全