夜雨聆风但说实话，安装这玩意儿，坑是真多。
我自己折腾了十几次，云服务器、本地、虚拟机全试过，踩过的坑能写一本教程。今天把安装报错TOP5一次性整理出来，看完至少能省3天踩坑时间。
安装报错 TOP5
坑1：npm error code 128（出现频率最高）
症状长这样：
npm error code 128npm error An unknown git error occurredcommand git ls-remote ssh://git@github.com/...Permission denied (publickey)原因：GitHub访问不稳定，或者权限出问题。Windows最多见，Mac也会遇到。
解决方法（按顺序试）：
1️⃣ 国内用户先切换npm镜像
npm config set registry https://registry.npmmirror.com这一步能解决80%的问题。
2️⃣ 切换到稳定的网络节点后再执行
3️⃣ 多试几次，有时候是偶发性问题
4️⃣ Windows用户检查环境变量：系统变量Path里要有C:\Program Files\nodejs，没有就手动加一下。
坑2：Node.js版本不对（排第二）
症状：安装完各种奇怪报错，比如"command not found"、部分功能用不了。
原因：OpenClaw需要Node.js ≥ v22，但你的版本太低。
解决方法：
1️⃣ 先检查版本：node -v
2️⃣ 用nvm管理版本（强烈推荐，Mac/Linux用户）：
nvm install 22nvm use 223️⃣ Windows用户直接去 nodejs.org 下载LTS版本，安装前先卸载旧版。
4️⃣ 安装完再查一下版本，确认是22以上。
坑3：API Key配置报错（403/429/500）
403报错：
原因：模型不支持当前地域，或者账号没权限 注意：海外模型（如OpenAI）不能用于国内服务器 解决：换用国产模型（DeepSeek/Kimi/智谱），国内服务器用国内模型
429/500报错：
原因：API余额不足，或者Key配置有误 解决：登录模型后台检查余额，确认API Key没输错
坑4：权限问题 EACCES（Mac/Linux用户常见）
症状：安装时报EACCES: permission denied
解决方法：
1️⃣ 加sudo（Mac/Linux通用）：
sudo npm install -g openclaw@latest2️⃣ 配置npm全局目录：
mkdir ~/.npm-globalnpm config set prefix '~/.npm-global'echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrcsource ~/.bashrc坑5：安装后启动失败（Mac用户反馈多）
解决方法：
1️⃣ 用nohup后台运行：
nohup openclaw gateway start &2️⃣ 配置systemd服务开机自启（Linux/Mac通用）：配置service文件然后enable
各系统安装要点
Windows用户
用PowerShell安装： iwr -useb https://openclaw.ai/install.ps1 | iex安装完检查Node.js环境变量有没有配好 - 关键
：国内用户大概率GitHub访问不稳定，切换网络节点再执行
Mac用户
用Homebrew安装Node.js： brew install node用官方安装脚本： curl -fsSL https://openclaw.ai/install.sh | bash建议加sudo： sudo npm install -g openclaw@latest
Linux用户
同样用官方安装脚本： curl -fsSL https://openclaw.ai/install.sh | bash注意pnpm依赖问题，遇到就单独处理 配置systemd服务，开机自启
预防胜于治疗：安装前检查清单
☐ Node.js版本 ≥ 22（ node -v检查）☐ npm版本是最新的（ npm install -g npm@latest）☐ Git已安装且配置好 ☐ 网络稳定（国内建议切换网络节点） ☐ 有管理员/root权限 ☐ API Key准备好（选DeepSeek/Kimi/智谱等国产模型）
写在最后
安装这事，"先跑通再变强"比"追求完美配置"重要得多。
我之前就是反复安装卸载十几次，总觉得配置不够完美，结果一篇文章都没写出来。后来想通了——先跑起来，功能用起来，遇到问题再解决。
AI不会让你失业，但会用OpenClaw的人会让你失业。
— 工具就在那里，就看你用不用了。—
