装OpenClaw的人里大概有一半会在某个环节卡住。有的是端口冲突有的是Key配不对有的是Node版本不够。这些问题单独拿出来都不难但如果你是第一次接触可能不知道从哪下手。这篇把所有常见问题集中在一起按报错信息分类方便你快速定位。OpenClaw最新版本一键部署包下载地址https://top.wokk.cn/Q1启动报端口被占用错误Error: listen EADDRINUSE: address already in use :::3456解决# 查看谁占了端口 Windows: netstat -ano | findstr 3456 macOS: lsof -i :3456 方案A关掉占用进程 Windows: taskkill /F /PID xxx macOS: kill -9 xxx 方案B改端口config.yaml gateway: port: 3780 方案CHyper-V保留端口导致 netsh interface ipv4 show excludedportrange protocoltcp 如果3456在保留范围内用方案BQ2启动报Node版本不兼容错误The engine node is incompatible. Expected ^18.0.0升级Node.js到18推荐用nvmnvm install 18 nvm use 18Q3API Key无效错误Authentication failed: invalid API key检查清单□ .env在 ~/.qclaw/ 下 □ 文件名是 .env不是 .env.txt □ Key前后无多余空格 □ Key完整未截断 □ 变量名拼写正确ZHIPU_API_KEY □ Key未过期Q4npm install超时npm config set registry https://registry.npmmirror.com npm cache clean --force npm installQ5浏览器白屏CtrlShiftDelete 清除缓存 或用无痕模式打开 http://localhost:3456Q6Docker重启后数据丢失# 加-v卷映射 docker run -d -p 3456:3456 -v ~/.qclaw:/root/.qclaw nicepkg/openclawQ7macOS无法验证开发者系统偏好设置→安全性与隐私→点仍要打开 或终端xattr -cr /Applications/OpenClaw.appQ8Windows终端乱码用PowerShell代替cmd即可Q9Agent回复超慢□ 检查网络能否访问LLM API □ API余额是否充足 □ maxTokens是否过大 □ 是否用了重模型换GLM-4-Flash试试Q10Skill安装失败openclaw skill clean openclaw skill install xxx以上覆盖了90%的常见故障。遇到其他问题建议去GitHub Issues搜索。
