02. 安装部署指南
课程信息
⠀
-
作者：老金
-
GitHub：https://github.com/KimYx0207
-
公众号：老金带你玩AI
-
X（Twitter）：老金带你玩AI
-
个人博客：https://aiking.dev
-
难度等级：🟢 入门
-
阅读时间：20 分钟
-
前置知识：会用命令行（终端）
⠀
本篇你将学会： 在 macOS/Linux/Windows 上安装 OpenClaw，配置运行环境，完成首次启动
⠀
小白速通： 直接跳到"快速安装"章节（第 3 节），跟着复制粘贴命令就行。遇到问题看第 12-13 节的故障排查
⠀
概述
⠀
我写安装部署时最看重可复现：你能照着装好，也要知道以后升级时从哪里回头查。
⠀
2026-09-14 当前基线（v2026.9.4）：升级链路这几版改动最多，有两条要在升级前先看。一是从 2026.8.2 升上来、机器上又没有 service manager 的，先手动跑一次 openclaw update --no-restart（v2026.9.1 起才支持无 service 环境继续升级，旧版会直接拒绝）。二是 v2026.9.4 只有在数据库结构未变、旧包仍兼容且配置校验通过时，才会自动恢复旧包、配置和服务；数据库迁移、无法确认兼容性或激活后的人工配置修改都可能阻止回滚。迁移后要退回旧版，仍然需要已验证的升级前备份和匹配的 OpenClaw 版本，详见官方回滚与恢复说明。其余改进：v2026.9.1 起 openclaw update 补强升级后 Doctor 失败时的 npm candidate 回滚，保留配置和 secret 引用，提供 triage 排障入口，并等插件就绪后再重启；v2026.9.3 起核心和插件改动会先在隔离的 candidate 状态里预演再激活；v2026.9.2 起自动升级会保住当前设置、已启用技能和默认 agent 归属。新装路径也变了：v2026.9.1 起全新安装（含 npx openclaw@latest）走快速通道，自动探测本机已有的 Claude Code / Codex 登录态和 API key，在线验证后直接开 web dashboard，完整向导保留为 Custom setup。另外 v2026.8.2 起 Linux 有了桌面端（x86-64 的 .deb / AppImage）；v2026.9.4 新增 OPENCLAW_CONFIG_READONLY=1，可让 OpenClaw 不再改写由部署方托管的配置。当前 latest 为 2026.9.4，extended-stable 为 2026.6.35（核查日：2026-09-14）。
⠀
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
24.x 至少 24.16.0，或 26.1.0 及以上
26.x（至少 26.1.0）
运行时环境；25.x 和 26.0.x 不符合当前要求
npm（Node Package Manager，Node.js 的包管理器）
随所选 Node.js 安装
使用随 Node.js 附带的版本
包管理器
Git
2.30+
最新版
克隆仓库、本地构建、版本管理
Python
3.10+（可选）
3.12
部分 Agent 工具依赖
Docker
24.0+（可选）
最新版
容器化部署
⠀
检查当前环境是否满足要求：
⠀
# 检查 Node.js 版本
node --version
# 确认版本：v26.1.0 及以上；沿用 24.x 时至少为 v24.16.0
# 检查 npm 版本
npm --version
# 应能输出版本号；无需为了示例单独降级 npm
# 检查 Git 版本
git --version
2. Node.js 环境安装
⠀
本章按 OpenClaw v2026.9.4 安装：新环境推荐 Node.js 26.x，至少 26.1.0；已有 24.x 环境可以沿用，但必须达到 24.16.0。Node 22、25.x 和 26.0.x 都不符合这个版本的要求。
⠀
这个范围来自官方快速开始和v2026.9.4 的 engines.node：>=24.16.0 <25 || >=26.1.0（核查日：2026-09-14）。先运行 node --version；符合要求就跳过安装，不要反复安装几套 Node。
⠀
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 26
nvm install 26
nvm use 26
# 设为默认版本
nvm alias default 26
# 验证
node --version # 确认 v26.x.x，且不低于 v26.1.0
⠀
Windows：
⠀
Windows 用户使用 nvm-windows：
⠀
-
从 nvm-windows releases 下载最新安装包
-
运行安装程序
-
打开新的命令行窗口：
⠀
nvm install 26
nvm use 26
node --version
⠀
2.2 使用官方安装包
⠀
从 Node.js 官网 选择 26.x 安装包（至少 26.1.0）。如果选择 24.x LTS，确认补丁版本不低于 24.16.0；不要只看“LTS”标签就跳过版本检查。
⠀
-
macOS：下载 .pkg 文件，双击安装
-
Windows：下载 .msi 文件，双击安装
-
Linux：使用 NodeSource 仓库
⠀
# Ubuntu/Debian - 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs
# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_26.x | sudo bash -
sudo yum install -y nodejs
# Arch Linux
sudo pacman -S nodejs npm
⠀
2.3 使用 Homebrew（macOS）
⠀
brew install node
node --version
⠀
核查时 Homebrew 的 node 包为 26.x。安装后仍要检查完整版本；如果终端调用到旧版本，用 which node 查路径，再选择本节的一种管理方式。
⠀
2.4 安装方式对比
⠀
方式
优点
缺点
适用场景
nvm
多版本管理、不需要 sudo
需要额外安装
开发环境（推荐）
官方安装包
简单直接
升级麻烦、可能需要 sudo
新手、单版本需求
Homebrew
macOS 生态集成好
仅限 macOS
macOS 用户
NodeSource
系统包管理器集成
版本更新可能滞后
服务器部署
3. 安装 OpenClaw CLI
⠀
旧版本说明：v2026.6.8 时的 Node 22.19+ 兼容说明只适用于当时的版本，不能用于安装本章当前的 v2026.9.4。当前运行时要求见第 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 全局安装（推荐）
⠀
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（具体模型以当前目录为准）
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（最简单）
⠀
# 安装 Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Node.js；核查时 Homebrew 的 node 包为 26.x
brew install node
node --version # 确认符合第 2 节的版本范围
# 安装 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 26
nvm install 26
nvm use 26
nvm alias default 26
# 安装 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 26（NodeSource 方式）
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt install -y nodejs
# 验证
node --version # 确认 v26.x.x，且不低于 v26.1.0
npm --version # 使用随 Node.js 安装的版本
# 安装 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 26
curl -fsSL https://rpm.nodesource.com/setup_26.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 26
nvm use 26
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：
⠀
# 安装 WSL2（管理员 PowerShell）
wsl --install
⠀
按提示重启电脑，打开 Ubuntu 终端，再运行下面的 Bash 命令。Windows 与 WSL 各有自己的 Node 环境，要在 Ubuntu 内检查版本。
⠀
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt install -y nodejs
node --version # 确认 v26.x.x，且不低于 v26.1.0
npm install -g openclaw@latest
openclaw onboard --install-daemon
⠀
7.2 原生 Windows 安装
⠀
如果不想用 WSL2，也可以原生安装：
⠀
-
从 Node.js 官网 下载 26.x Windows 安装包（至少 26.1.0）
-
运行安装程序，勾选 "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
# 重新打开终端，或加载你的 shell 配置后再执行
source ~/.bashrc # zsh 用户改为 source ~/.zshrc
nvm install 26
nvm use 26
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 版本不兼容
⠀
症状：安装提示 EBADENGINE / engine incompatible，或启动时提示 Node 版本不符合要求。完整报错会随安装方式变化。
⠀
v2026.9.4 要求 >=24.16.0 <25 || >=26.1.0。比较完整版本号；25.x 虽然大于 24，也不在支持范围内。
⠀
# 检查当前版本
node --version
# 使用 nvm 升级
nvm install 26
nvm use 26
node --version
# 或者使用 NodeSource 升级
curl -fsSL https://deb.nodesource.com/setup_26.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 19789 # 不要用 18790-18899，那一段是 Bridge / Browser Control / Canvas / CDP 端口池（见 09 章端口表）
⠀
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
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 课堂节奏
⠀
第 1 段：确认 Node 和 shell。
第 2 段：安装 OpenClaw CLI。
第 3 段：运行 onboard。
第 4 段：启动 Gateway。
第 5 段：运行 doctor。
第 6 段：发第一条消息。
第 7 段：才开始接平台。
⠀
如果有人在第 2 段卡住，不要让全班等。让他继续听后续概念，课后按安装问题排查。OpenClaw 是长期运行工具，不需要所有人同一分钟完成同一个命令。
⠀
15.3 三类故障分流
⠀
A 类：可以继续
- CLI 已安装。
- Gateway 能启动。
- doctor 只有非阻塞提醒。
B 类：需要旁路协助
- onboard 失败。
- API Key 或模型不通。
- 端口冲突。
C 类：先不要继续写配置
- 不确定当前账号和 token。
- 使用生产服务器但安全边界没确认。
- Docker volume 或配置目录可能覆盖已有数据。
⠀
对 A 类：
⠀
继续快速开始。
平台接入可以晚一点做。
⠀
对 B 类：
⠀
记录命令、错误、系统和配置路径。
不要反复重装。
⠀
对 C 类：
⠀
停止写入配置。
先备份或确认环境归属。
⠀
16. 安装后第一条可用链路
⠀
安装完成不等于系统可用。最小可用链路是：
⠀
openclaw --version
↓
openclaw onboard --install-daemon
↓
openclaw gateway --port 18789 --verbose
↓
openclaw doctor
↓
openclaw agent --message "ping"
⠀
每一步失败时的含义不同。
⠀
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 是长驻服务，升级前要保护配置和数据。
⠀
升级前：
⠀
# 备份配置目录
cp -R ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)
# 记录当前版本
openclaw --version
# 记录当前配置
openclaw config get
⠀
升级后：
⠀
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、源码各适合谁
⠀
官方安装脚本：
适合个人和普通用户，最快跑通。
npm / pnpm 全局安装：
适合熟悉 Node 生态的人，方便版本控制和排查 PATH。
Docker：
适合服务器长期运行，便于隔离、备份、重启和反向代理。
源码构建：
适合贡献代码、调试 OpenClaw 本身、开发插件或修改内部逻辑。
⠀
选择建议：
⠀
第一次学习：
脚本或 npm。
团队服务器：
Docker。
开发 OpenClaw：
源码构建。
Windows 用户：
优先 WSL2，除非你明确知道原生 Windows 下的 shell、路径和依赖差异。
⠀
安装方式不是信仰问题，而是维护问题。你以后要怎么升级、备份、看日志、重启，就应该反过来决定今天怎么安装。
⠀
19. 安装前环境画像：先知道自己在哪
⠀
很多安装问题不是 OpenClaw 特有问题，而是 Node、shell、PATH、代理、权限、Windows/WSL2 差异带来的。正式安装前，先写一份环境画像。
⠀
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 命令不存在
⠀
npm prefix -g
command -v openclaw
echo $PATH
⠀
macOS / Linux 的全局命令一般位于 npm prefix -g 输出目录下的 bin；原生 Windows 则检查该输出目录本身是否在 Path 中。新版 npm 已移除 npm bin -g，不要用它排查。使用 nvm 时，确认当前 shell 已加载 nvm：
⠀
command -v nvm
node --version
⠀
20.2 npm 权限错误
⠀
不要第一反应 sudo npm install -g。优先使用 nvm 重新管理 Node：
⠀
nvm install 26
nvm use 26
npm install -g openclaw
⠀
如果你已经用 sudo 装过，可能需要检查全局目录 owner：
⠀
npm prefix -g
ls -la "$(npm prefix -g)"
⠀
20.3 配置写坏了
⠀
OpenClaw 配置是 JSON5，支持注释和尾逗号，但仍然可能因为括号、引号、路径写错导致启动失败。先备份再改：
⠀
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d%H%M%S)
openclaw doctor
⠀
如果改完 Gateway 起不来，把备份复制回来：
⠀
cp ~/.openclaw/openclaw.json.bak.YYYYMMDDHHMMSS ~/.openclaw/openclaw.json
⠀
20.4 Gateway 起不来
⠀
按顺序查：
⠀
# 端口
lsof -i :18789 || ss -tlnp | grep 18789
# 配置
openclaw doctor
# 前台日志
openclaw gateway --port 18789 --verbose
⠀
如果端口被占用，先不要杀进程。确认占用者是不是另一个 OpenClaw：
⠀
ps aux | grep openclaw
⠀
如果是旧 Gateway，正常停止或换端口；如果是未知进程，再决定是否处理。
⠀
21. 换机器迁移：安装和数据分开处理
⠀
换电脑时不要把“重新安装 OpenClaw”和“迁移旧数据”混成一步。先在新机器装干净，再迁移必要数据。
⠀
第一步，新机器安装 CLI：
⠀
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version
openclaw doctor
⠀
第二步，旧机器导出核心数据：
⠀
tar -czf openclaw-user-data.tar.gz \
~/.openclaw/openclaw.json \
~/.openclaw/workspace/MEMORY.md \
~/.openclaw/workspace/USER.md \
~/.openclaw/workspace/memory
⠀
第三步，新机器恢复：
⠀
tar -xzf openclaw-user-data.tar.gz -C ~/
openclaw memory index
openclaw doctor
⠀
谨慎迁移这些：
⠀
auth-profiles.json
credentials/
sessions/
channel login state
⠀
这些文件可能包含平台凭证、会话历史、设备绑定。新机器上更稳的方式通常是重新登录消息平台和 provider，而不是直接复制所有认证状态。
⠀
迁移后做三件事：
⠀
openclaw --version
openclaw models status
openclaw channels status
⠀
然后发送一条测试消息。能本地聊，不代表消息平台也恢复了；消息平台通常还需要重新扫码、重新设置 webhook，或者更新平台后台的回调地址。
⠀
22. 团队安装模板：减少“每个人都不一样”
⠀
如果你要带团队或课程学员一起安装，建议给大家一个统一模板，而不是让每个人自由选择。
⠀
推荐组合：
⠀
macOS:
nvm + Node 26（至少 26.1.0）+ npm global + OpenClaw onboard
Linux:
nvm 或 NodeSource + npm global + OpenClaw onboard
Windows:
WSL2 Ubuntu + nvm + Node 26（至少 26.1.0）+ npm global
服务器：
Docker Compose + .env + volume + 反向代理
⠀
统一模板的好处：
⠀
-
报错更容易互相对照。
-
PATH、Node 版本、权限问题更少。
-
教程截图和命令更容易一致。
-
后续升级和卸载更容易讲清楚。
⠀
可以发给团队一段标准安装命令：
⠀
# 1. 检查 Node
node --version
# 2. 仅在版本不满足 >=24.16.0 <25 或 >=26.1.0 时安装
nvm install 26
nvm use 26
# 3. 安装 OpenClaw
npm install -g openclaw
# 4. 初始化
openclaw onboard --install-daemon
# 5. 诊断
openclaw doctor
⠀
让每个人把结果贴到同一份安装记录：
⠀
| Name | OS | Node | OpenClaw | Install Method | Status | Error |
|---|---|---|---|---|---|---|
| 姓名 | 实际系统 | node --version 的完整输出 | openclaw --version 的输出 | 安装方式 | 实际结果 | 原始报错 |
⠀
团队安装的重点不是"每个人都立刻成功"，而是失败时能快速归类。
⠀
23. 安装后的文件地图
⠀
装完 OpenClaw 后，你至少要知道哪些文件不能乱删。
⠀
常见位置：
⠀
~/.openclaw/
├── openclaw.json # 主配置
├── logs/ # 日志
├── workspace/ # 默认 Agent 工作空间
│ ├── SOUL.md
│ ├── USER.md
│ ├── MEMORY.md
│ └── memory/
├── agents/ # Agent 状态
├── credentials/ # 平台凭证或登录状态
└── auth-profiles.json # 认证资料
⠀
第一次安装完成后，建议运行：
⠀
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。迁移时要把“程序”和“数据”分开。
⠀
第一步，在旧环境记录：
⠀
openclaw --version
openclaw config get agents.defaults.model
openclaw channels status
⠀
第二步，备份数据：
⠀
tar -czf openclaw-local-data.tar.gz ~/.openclaw
⠀
如果你只想迁移核心配置和记忆，而不迁移凭证：
⠀
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 服务器先启动空实例：
⠀
docker compose up -d
docker compose ps
⠀
第四步，把数据恢复到 volume 或 bind mount。Docker volume / bind mount 的完整写法放在 09-Docker部署指南，安装篇这里只强调迁移原则：新的容器必须挂载同一个持久化数据目录，否则配置、记忆和会话不会自动出现。
⠀
恢复：
⠀
mkdir -p /opt/openclaw/data/openclaw
tar -xzf openclaw-core-data.tar.gz -C /opt/openclaw/data/openclaw --strip-components=2
⠀
第五步，重新配置平台凭证。消息平台 token、扫码登录、Webhook 地址通常和机器有关，迁移后要重新确认。
⠀
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 文件系统中：
⠀
/home/<user>/project
~/.openclaw
⠀
不要长期放在：
⠀
/mnt/c/Users/<user>/...
⠀
原因：
⠀
- 文件权限表现不同。
- 大量小文件读写更慢。
- 某些工具对 Windows 路径处理不一致。
⠀
26.2 shell 边界
⠀
在 WSL2 Ubuntu 里安装，就在 WSL2 里运行：
⠀
openclaw --version
openclaw gateway --port 18789
⠀
不要一会儿在 PowerShell 里装，一会儿在 WSL2 里跑。两个环境的 Node、npm、PATH、home 目录都不同。
⠀
26.3 浏览器访问
⠀
如果 Gateway 在 WSL2 里监听 127.0.0.1:18789，Windows 浏览器通常可以访问：
⠀
http://localhost:18789
⠀
如果打不开，先在 WSL2 里测：
⠀
curl -i http://127.0.0.1:18789/health
⠀
WSL2 内部能访问，Windows 浏览器不能访问，问题在 Windows/WSL 网络转发；WSL2 内部也不能访问，问题在 Gateway 或端口。
⠀
26.4 代理和 npm registry
⠀
中国网络环境下，npm 或 provider API 可能不稳定。先区分：
⠀
npm 安装慢：
是包下载问题。
模型 API 超时：
是 provider 网络问题。
Webhook 不通：
是外部平台访问你 Gateway 的问题。
⠀
不要用一个代理设置解决所有问题。安装、模型、Webhook 是三条不同链路。
⠀
27. 安装完成后的安全起步
⠀
刚安装完就应该做几个基础安全动作，不用等到生产部署。
⠀
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
⠀
如果已经产生日志：
⠀
chmod 750 ~/.openclaw/logs 2>/dev/null || true
chmod 640 ~/.openclaw/logs/*.log 2>/dev/null || true
⠀
确认配置里没有明文 Key：
⠀
rg -n "sk-|token|password|secret|AKIA" ~/.openclaw
⠀
如果你为了测试把 Key 写进了配置，尽快改成环境变量：
⠀
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
⠀
安装章节看起来和安全无关，但安装时形成的习惯会一直延续到生产。把 token 放环境变量、知道配置位置、知道如何备份，是最早应该养成的习惯。
⠀
28. 企业网络和代理环境
⠀
在公司网络、校园网或国内网络环境里，安装失败不一定是 OpenClaw 问题。常见卡点有三类：
⠀
npm registry：
包下载慢或失败。
GitHub：
源码、release、脚本下载失败。
模型 provider：
安装成功，但模型 API 超时。
⠀
先分别测试：
⠀
npm ping
git ls-remote https://github.com/openclaw/openclaw.git HEAD
curl -I https://api.openai.com
⠀
如果 npm 慢，可以临时切 registry：
⠀
npm config get registry
npm config set registry https://registry.npmmirror.com
npm install -g openclaw
npm config set registry https://registry.npmjs.org
⠀
如果公司要求代理：
⠀
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 里传入：
⠀
environment:
- HTTP_PROXY=http://host.docker.internal:7890
- HTTPS_PROXY=http://host.docker.internal:7890
extra_hosts:
- "host.docker.internal:host-gateway"
⠀
企业网络还有一种情况：外部平台 webhook 无法访问内网机器。这时不要硬开公网端口。优先使用：
⠀
- WebChat / CLI 做本地测试。
- SSH 隧道。
- Tailscale / VPN。
- 平台支持的 polling 或 socket 模式。
- 正式反向代理和 TLS。
⠀
网络问题要分层排查：安装包下载、模型 API、消息平台回调是三条不同路径。
⠀
29. 多版本共存和试验环境
⠀
如果你要试 beta/dev 通道，建议不要直接在主环境上试。可以用不同的 OPENCLAW_HOME 创建隔离环境。
⠀
export OPENCLAW_HOME=~/.openclaw-dev
openclaw onboard
openclaw gateway --port 28789 --verbose
⠀
这样主环境仍然在：
⠀
~/.openclaw
⠀
试验环境在：
⠀
~/.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 安全、网络安全