这两年AI Agent框架越来越多，OpenClaw算是其中热度比较高的一个。不过这东西部署起来真不是无脑下一步就能搞定的，我自己折腾的时候踩了不少坑，网上搜到的教程也东一块西一块，要么只讲安装不讲排错，要么一上来就让你用Docker但本地根本跑不起来。
这篇文章就把我从零开始部署OpenClaw的完整过程写下来，包括环境怎么配、哪些坑最容易踩、出了问题怎么查，争取让你照着做就能跑通。
一、部署之前先搞清楚两件事
别急着敲命令，先看看你手头的机器够不够用。
硬件方面其实门槛不算高。我拿一台老旧的4核8GB内存机器试过，跑起来没啥问题。如果你的机器只有2核4GB，也能跑，就是响应会慢一些。硬盘留个20GB以上的空间比较保险，因为模型缓存和日志文件会慢慢占地方。
系统选择上，macOS和Linux最省心，Windows用户稍微麻烦点。如果你用Windows，强烈建议走WSL2路线，原生Windows环境下装OpenClaw会遇到各种奇奇怪怪的编译错误，尤其是sharp这个图像处理库，在Windows上编译经常挂掉。
网络也得提前确认好。安装过程中要下载不少依赖包，有些源在国外，建议提前配好国内镜像源，不然等半天发现超时报错，心态容易崩。
二、环境搭建：一步一步来别跳步
Node.js版本是个大坑
OpenClaw要求Node.js版本22以上，这个卡死了很多人。你如果之前装过旧版本的Node，直接升级可能不够彻底，版本号看起来是新的但实际环境变量还有残留。
我建议用nvm来管理Node版本，这工具最大的好处是可以在多个版本之间随时切换，不会搞乱系统。
安装nvm之后执行：
text
nvm install 22 nvm use 22 nvm alias default 22 验证一下版本对不对：
text
node --version 如果输出的不是v22.x.x，那就说明环境变量还有问题，检查一下shell配置文件（~/.bashrc或者~/.zshrc）里是不是有旧的Node路径。
npm全局命令找不到的解决办法
装完OpenClaw之后，输入openclaw提示command not found，这个问题太常见了。
原因是npm全局安装的包，它的可执行文件目录没有被加到系统的PATH里。先查一下npm的全局路径在哪：
text
npm prefix -g 输出的路径后面加上/bin，就是openclaw命令所在的目录。比如输出是/home/xxx/.nvm/versions/node/v22.x.x，那完整路径就是/home/xxx/.nvm/versions/node/v22.x.x/bin。
把这个路径加到PATH里。我用的是zsh，所以编辑~/.zshrc：
text
export PATH="$(npm prefix -g)/bin:$PATH" 然后执行source ~/.zshrc让配置生效，再试一下openclaw --version，能正常显示版本号就说明搞定了。
三、正式安装OpenClaw
环境准备好之后就可以装OpenClaw了，推荐用官方提供的自动化脚本：
text
curl -sSL https://example.com/install-openclaw | bash （实际地址以官方文档为准）
这个脚本会自动检测你的Node版本、系统架构，然后补全缺失的依赖。省心不少。
如果你喜欢手动控制每一步，也可以分步来：
text
git clone https://example.com/openclaw.git cd openclaw npm install --production --production参数只装运行必需的依赖，不会装测试相关的包，能节省不少时间和空间。
装完之后运行配置向导：
text
node ./bin/onboard.js 这个向导会问你模型怎么选、API Key填什么、消息队列怎么连之类的问题，按实际情况填就行，后面随时可以改。
四、最容易踩的坑和怎么爬出来
端口冲突这件事碰到过好几次
OpenClaw默认用18789端口。如果你之前装过老版本或者有其他服务占了这个端口，启动的时候会报EADDRINUSE错误。
先看看谁占了端口。macOS/Linux用：
text
lsof -i :18789 Windows用：
text
netstat -ano | findstr 18789 找到进程ID之后把它干掉：
text
kill -9 <PID> 如果不想每次都杀进程，也可以直接改OpenClaw的默认端口：
text
openclaw config set gateway.port 18790 openclaw gateway restart Gateway启动后立马退出
这个坑特别隐蔽。执行openclaw gateway start之后，进程闪一下就没了，没有任何报错信息。
后来查到是matrix-sdk-crypto-nodejs这个原生模块没装好，二进制文件下载不完整，正常的应该有22MB左右，出问题的时候只有2.4MB。
解决办法是删掉这个模块重新安装：
text
npm rebuild @matrix-org/matrix-sdk-crypto-nodejs 或者更彻底一点，把node_modules删了重新npm install。
macOS上launchd服务注册失败
如果你用的是macOS，想设置开机自启，执行openclaw onboard --install-daemon之后发现重启了也没自动启动。
检查一下plist文件存不存在：
text
ls ~/Library/LaunchAgents/com.openclaw.gateway.plist 再看看launchd注册状态：
text
launchctl list | grep openclaw 如果PID那一列是"-"就说明没跑起来。
手动加载一下：
text
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist 还有一个常见原因是plist文件里的Node.js路径不对。用which node看一下实际路径，跟plist里写的对比一下，不一致的话手动改过来。
WSL2用户注意systemd的问题
Windows上用WSL2的朋友可能会遇到systemctl --user命令报错"No such file or directory"。
这是因为WSL2默认没开systemd。解决办法是在/etc/wsl.conf里加上：
text
[boot] systemd=true 然后回到Windows的PowerShell里执行wsl --shutdown，重启WSL2之后再试。
如果不想折腾systemd，也可以放弃自动启动，手动在~/.bashrc里加一行：
text
openclaw gateway start --detach 2>/dev/null 每次开终端的时候自动启动，虽然不如systemd优雅，但够用了。
五、API和模型配置的那些事儿
API Key找不到
报"No API key found for provider"这个错，八成是auth-profiles.json文件有问题。
这个文件的位置在~/.openclaw/agents/main/agent/auth-profiles.json。检查一下文件存不存在，格式对不对。
正确的格式长这样：
json
{ "profiles": [{ "id": "default", "type": "api-key", "provider": "openai", "apiKey": "sk-xxx" }], "default": "default" } 注意"type"字段必须存在，这是老版本的一个已知bug。
401认证失败
如果报401 Invalid Authentication，先用curl直接测一下API Key有没有效：
text
curl -s -o /dev/null -w "%{http_code}" \ https://api.openai.com/v1/models \ -H "Authorization: Bearer 你的api-key" 返回200就是有效的，401就是Key有问题或者过期了。
还有一个特殊情况：如果你在用Kimi，调用$web_search工具的时候会报401，原因是OpenClaw传了Kimi不支持的language和freshness参数。临时解决办法是在配置里把搜索Provider换成SearXNG、Brave或者Tavily。
429限流怎么处理
API调用太频繁被限流了，报429 Rate Limit Reached。
OpenClaw有个已知bug，冷却状态是按Profile级别记录的，不是按Model级别，所以一个模型触发429之后，整个Profile下的所有模型都跟着进冷却期。
临时绕过去的办法是为同一个Provider创建多个Profile，每个Profile用不同的API Key：
json
{ "profiles": [ { "id": "openai-1", "type": "api-key", "provider": "openai", "apiKey": "sk-key-1" }, { "id": "openai-2", "type": "api-key", "provider": "openai", "apiKey": "sk-key-2" } ], "default": "openai-1" } 然后启用自动failover，第一个Key被限流了自动切到第二个。
六、日常运行的维护和排查
用好doctor命令
遇到任何问题，先跑openclaw doctor。这个命令会自动检测配置问题，包括端口冲突、API Key有效性、守护进程配置，甚至能自动修复一部分问题。
加上–repair参数可以让它自动应用修复：
text
openclaw doctor --repair 看日志定位问题
日志是最直接的排查手段。实时看日志用：
text
openclaw logs --follow Gateway的行为都会在这里输出，从日志里能看出是哪一步出了问题。
注意有个坑：Gateway的日志文件是按启动日期命名的，比如openclaw-2026-03-10.log。如果你跨日运行，openclaw logs --follow默认读的是当天日期的文件，可能会看不到之前的日志。这时候需要手动去日志目录里找对应日期的文件。
内存不够怎么办
如果机器内存不大，OpenClaw跑久了可能会崩。可以限制Node.js的堆内存大小：
text
openclaw config set gateway.nodeOptions "--max-old-space-size=512" openclaw gateway restart 512就是512MB，根据你机器的实际情况调整。
用Docker的话可以直接限制内存：
text
docker run -m 2g openclaw/openclaw:latest 七、最后说几句
OpenClaw部署下来，最大的感受就是：不要跳过任何一步，不要觉得"这一步应该没问题"就略过检查。环境版本、配置文件格式、端口占用、API Key有效性，每一步都可能成为拦路虎。
如果你在部署过程中遇到了上面没写到的问题，最直接的办法还是去看官方文档和GitHub的issue区，很多坑已经被前人踩过并记录下来了。openclaw doctor这个命令也值得养成习惯，部署完跑一遍，改配置跑一遍，出问题第一件事就是跑它。
祝你部署顺利，一次过。
