第 2/7 章

🚀 第2章：安装部署（可执行 + 防踩坑）

2.1 这一章的目的

很多"AI教程"在安装部署这里最容易出问题：表面上写了几条命令，实际一执行就报错。对企业读者来说，这一章不是"看看就懂"，而是必须做到命令拷贝就能执行：

  • 员工照着做能装上；
  • 技术人员知道为什么这样装；
  • 老板看完知道哪种部署方式最适合公司。
这一章的目标不是"显得专业"，而是"让你真正装成功"。

2.2 先做选择：你到底该用哪种部署方式

方式适合谁优点不足
本地 npm 安装开发者 / 技术人员安装直接、便于调试对环境要求高
Windows + WSL2Windows 用户兼容性最好首次配置略麻烦
Docker 部署企业 / 服务器场景环境稳定、便于迁移需要懂一点容器
云端一键部署新手 / 非技术管理者最快见效灵活性不如自建
建议：个人学习先用本地安装；企业试点优先 Docker 或云端一键部署。

2.3 安装前必须满足的环境要求

项目要求说明
Node.js22 或以上版本太低会直接报错
包管理器npm / pnpm / bun新手建议 npm
操作系统Windows / macOS / LinuxWindows 推荐 WSL2
网络可访问模型 API否则模型无法工作

2.4 Windows 用户：推荐 WSL2 安装

为什么不推荐直接在 Windows 原生环境安装？因为 OpenClaw 的很多能力天然更适合 Unix 风格环境，比如路径、权限、脚本执行、后台服务管理等。

步骤 1：安装 WSL2

wsl --install

执行后重启电脑，打开 Ubuntu 终端。

步骤 2：安装 nvm 与 Node 22

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --version

步骤 3：安装 OpenClaw

npm install -g openclaw@latest

步骤 4：初始化并安装守护进程

openclaw onboard --install-daemon

步骤 5：运行诊断检查

openclaw doctor
如果看到 Node 版本正常、依赖正常、Gateway 正常，说明安装基本成功。
常见坑：没有把 Node 切到 22；没有在 Ubuntu 终端里执行；把命令复制到了 PowerShell 里。

2.5 macOS 安装（最适合个人长期使用）

如果你是 Mac 用户，本地安装通常体验很好，尤其适合个人学习与长期运行。

步骤 1：安装 Xcode 命令行工具

xcode-select --install

步骤 2：确认 Node 版本

node --version

如果低于 22，建议先升级。

步骤 3：安装 OpenClaw

npm install -g openclaw@latest

步骤 4：初始化

openclaw onboard --install-daemon

步骤 5：诊断

openclaw doctor
Mac 用户如果后续想接 iMessage 或 Apple Notes，macOS 场景会更有优势。

2.6 Linux 安装（服务器最常见）

Linux 是企业服务器部署最常见的环境。建议用 nvm 管理 Node 版本，避免系统包版本过旧。

步骤 1：安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

步骤 2：安装 Node 22

nvm install 22
nvm use 22
node --version

步骤 3：安装 OpenClaw

npm install -g openclaw@latest

步骤 4：初始化并安装后台服务

openclaw onboard --install-daemon

步骤 5：验证 systemd 用户服务

systemctl --user status openclaw-gateway

2.7 Docker 部署（企业试点首选）

如果你想让环境更稳定、迁移更方便，Docker 是企业里最值得优先考虑的部署方式之一。

步骤 1：获取源码

git clone https://github.com/openclaw/openclaw.git
cd openclaw

步骤 2：启动容器

docker-compose up -d

步骤 3：查看状态

docker-compose ps
docker-compose logs -f openclaw

关键挂载（必须做）

volumes:
  - ~/.openclaw:/root/.openclaw
  - ~/openclaw/workspace:/workspace

为什么一定要挂载？因为：

  • ~/.openclaw 存运行状态、会话数据；
  • workspace 存配置、技能、工作文件；
  • 如果不挂载，容器重启后很多数据会丢失。

2.8 云端一键部署（最适合新手和老板试点）

如果老板想先快速看到效果，而不是先折腾环境，那么云端一键部署会更合适。

平台适合对象特点
阿里云国内企业新手社区资源多、镜像成熟
腾讯云企微 / QQ 生态用户对国内 IM 生态友好
飞书OpenClaw飞书用户飞书整合体验好
Kimi-Claw入门新手云端一键安装
Qclaw想快速体验的新手改装型OpenClaw,本地要安装客户端
WorkBuddy想快速体验的新手改装型OpenClaw,本地要安装客户端
企业可以先用云端快速验证价值，再决定是否自建或私有化。

2.9 安装完成后，第一件事不是用，而是检查

很多人装完马上就想接渠道、跑任务，但最正确的做法是：先确认环境真的正常。

推荐检查命令

openclaw doctor

这个命令通常会检查：

  • Node 版本是否符合要求；
  • 必要依赖是否安装完整；
  • Gateway 是否正常；
  • 模型 API 是否可用；
  • 后台服务状态是否正常。

2.10 安装后必须做的三件事

  1. 配置 Gateway 认证：不要让未认证实例暴露；
  2. 先接一个最简单的渠道：比如 Telegram 或飞书；
  3. 先跑一个最简单的案例：比如自动写日报。

2.11 最常见的安装报错与解决方案

问题典型报错原因解决方法
Node 版本不对Node.js version 20.x is not supported版本低于 22用 nvm 安装并切换到 22
权限问题Permission denied全局安装目录权限不足调整 npm 前缀或使用正确权限
认证配置缺失auth.mode must be setGateway 未配置认证模式配置 token 或 password
端口占用EADDRINUSE: 18789端口已被占用换端口或结束占用进程
数据库打不开SQLITE_CANTOPEN目录权限或挂载问题检查目录权限与 Docker 挂载

查看端口占用

lsof -i :18789

结束占用进程

kill -9 <PID>

2.12 企业部署最推荐的实践

如果你是企业，不建议所有员工自己在电脑上乱装。更建议用以下方式：

  • 试点期：找一台测试服务器，用 Docker 部署；
  • 接入期：先接一个渠道（飞书或企业微信）；
  • 稳定后：再考虑扩展模型、技能、权限和更多部门。
企业最优路径不是"最快装完"，而是"最稳上线"。

2.13 本章总结

👉 Windows 用户优先 WSL2
👉 企业试点优先 Docker 或云端一键部署
👉 安装成功不代表可用，必须跑 openclaw doctor
👉 真正的防踩坑，不是会装命令，而是先选对部署方式