装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 方案C：Hyper-V保留端口导致 netsh interface ipv4 show excludedportrange protocol=tcp 如果3456在保留范围内，用方案B

Q2：启动报"Node版本不兼容"

错误：The engine "node" is incompatible. Expected ^18.0.0

升级Node.js到18+，推荐用nvm：

nvm install 18 nvm use 18

Q3：API Key无效

错误：Authentication failed: invalid API key

检查清单：

□ .env在 ~/.qclaw/ 下 □ 文件名是 .env（不是 .env.txt） □ Key前后无多余空格 □ Key完整未截断 □ 变量名拼写正确（ZHIPU_API_KEY） □ Key未过期

Q4：npm install超时

npm config set registry https://registry.npmmirror.com npm cache clean --force npm install

Q5：浏览器白屏

Ctrl+Shift+Delete 清除缓存 或用无痕模式打开 http://localhost:3456

Q6：Docker重启后数据丢失

# 加-v卷映射 docker run -d -p 3456:3456 -v ~/.qclaw:/root/.qclaw nicepkg/openclaw

Q7：macOS"无法验证开发者"

系统偏好设置→安全性与隐私→点"仍要打开" 或终端：xattr -cr /Applications/OpenClaw.app

Q8：Windows终端乱码

用PowerShell代替cmd即可

Q9：Agent回复超慢

□ 检查网络能否访问LLM API □ API余额是否充足 □ maxTokens是否过大 □ 是否用了重模型（换GLM-4-Flash试试）

Q10：Skill安装失败

openclaw skill clean openclaw skill install xxx

以上覆盖了90%的常见故障。遇到其他问题建议去GitHub Issues搜索。