🎖️ 任务奖励 — 学完你能做到
一次性跑通安装，不再卡在环境配置阶段
📖 本章目标：避开安装阶段最常见的 8 个坑，一次跑通
1.1 Node.js 版本要求（最常见坑 #1）
❌ 踩坑
安装后运行 openclaw 报语法错误，如：
SyntaxError: Unexpected token '?'看起来像 bug，实际是 Node 版本太低。OpenClaw 需要 Node.js ≥ 22，但报错信息完全不提版本。
✅ 解决
用 nvm 管理版本：
nvm install 22 && nvm use 22 && nvm alias default 22
node -v # 应显示 v22.x.x1.2 Windows：必须用 WSL2
⚠️ 警告
OpenClaw 不支持 Windows 原生环境。在 PowerShell / CMD 直接安装 100% 失败。必须使用 WSL2（Ubuntu 22.04+）。
WSL2 三大常见问题
| 问题 | 原因 | 解决 |
|---|---|---|
EACCES 权限错误 | npm global 目录在 Windows 分区 | 把 npm global 目录改到 Linux 原生路径 |
openclaw 命令找不到 | PATH 没包含 npm global bin | source ~/.bashrc 或在 .bashrc 里加 export PATH |
| 文件操作极慢 | 跨 Windows/Linux 文件系统 | 把整个工作目录移到 Linux 原生路径 ~/ |
WSL2 一次性修复 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
openclaw --version1.3 macOS Apple Silicon（M1/M2/M3）
❌ 踩坑
安装时报错：
sharp: Installation error: ... pre-built binaries原因：sharp 图像处理库的预编译二进制不兼容 ARM 架构。
✅ 解决
安装前设置环境变量：
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw1.4 Docker 部署要求
资源要求
| 资源 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | 1 vCPU | 2 vCPU+ |
| RAM | 2 GB | 4 GB+ |
| 磁盘 | 5 GB | 20 GB+（日志 + 记忆文件） |
❌ 踩坑
Docker bind mount 权限问题：容器内以 root 运行，宿主机文件夹是普通用户所有，写入时报 EACCES。
✅ 解决
在 docker-compose.yml 里加 user: "1000:1000"（或宿主机实际 UID/GID），或用命名卷替代 bind mount。
1.5 Gateway 端口冲突
❌ 踩坑
Gateway 启动失败，报 EADDRINUSE。默认端口 18789 被其他进程占用。
✅ 解决
# 查找占用端口的进程
lsof -i :18789
# 或在 openclaw.json 改端口
# "gateway": { "port": 18790 }1.6 国内网络：npm 安装超时
# 切换到国内镜像
npm config set registry https://registry.npmmirror.com
npm install -g openclaw
# 如果 GitHub 资源也超时
export OPENCLAW_CDN=https://openclaw-cn.oss-cn-hangzhou.aliyuncs.com1.7 第一次启动流程（BOOTSTRAP）
❌ 踩坑
很多用户第一条消息直接发了真实任务，agent 优先处理任务跳过了 bootstrap，导致 agent 跑了一周没有任何身份认知——没名字、没性格，行为像个通用助手。
✅ 正确流程
| 步骤 | 操作 |
|---|---|
| 1 | 安装完成，确认 openclaw status 显示 Gateway running |
| 2 | 第一条消息必须是 bootstrap：发送 「Hey, let's get you set up. Read BOOTSTRAP.md and walk me through it.」 |
| 3 | 立刻填写 IDENTITY.md（5 分钟内）——名字、性格、说话方式 |
| 4 | bootstrap 完成后删除 BOOTSTRAP.md |
1.8 安装后快速验证
openclaw --version # 确认版本 ≥ 最新
openclaw status --all # 全局状态
openclaw gateway status # Gateway 是否运行
openclaw doctor # 自动诊断常见配置问题
openclaw doctor --fix # 自动修复可修复的问题