装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搜索。