常见问题与避坑

Q: Node.js 版本要求是什么？

OpenClaw 2026 版要求 Node.js ≥ 22.0.0，推荐使用 LTS 版本（22.x）。使用 node -v 查看当前版本。

升级方法：

• Windows：使用 nvm-windows，运行 nvm install 22
• macOS：brew install node@22 或使用 nvm
• Linux：curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

Q: npm install 报错 EACCES 权限不足

Windows 用户以管理员身份运行终端。macOS/Linux 用户避免使用 sudo npm install，改为修改 npm 目录权限：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Q: 端口 3000 / 18789 被占用

查找占用端口的进程并终止：

# Windows
netstat -ano | findstr :18789
taskkill /PID <PID> /F

# macOS / Linux
lsof -i :18789
kill -9 <PID>

或在配置中修改端口：openclaw config set port 18790

Q: 飞书机器人配置后收不到消息

排查步骤：

1. 确认使用的是长连接模式（不要配置回调地址）
2. 检查 App ID 和 App Secret 是否正确（无多余空格）
3. 在飞书开放平台 → 事件订阅中查看推送日志
4. 确认已开启"机器人"能力，并已发布版本
5. 查看 OpenClaw 日志：openclaw logs | grep feishu

Q: 企业微信无法接收消息

排查步骤：

1. 确认回调 URL 可从公网访问：curl http://你的公网IP:18789/wecom
2. 检查 Token 和 EncodingAESKey 是否与企业微信后台一致
3. 确认防火墙已放行 18789 端口
4. 如果使用 ngrok，确认隧道正在运行

Q: QQ 机器人被封怎么办？

• 建议使用小号创建机器人，避免主号风险
• 控制消息发送频率，不要发送广告或敏感内容
• 遵守 QQ 开放平台的使用规范
• 单个 QQ 号最多创建 5 个机器人

Q: 技能安装失败

常见原因和解决方案：

• 网络问题：切换镜像源 openclaw config set registry https://registry.clawhub.cn
• 依赖缺失：运行 openclaw skills install --verbose 查看详细错误
• 版本不兼容：检查技能要求的 OpenClaw 最低版本

Q: 技能权限不足

某些技能需要额外权限（如文件系统访问、网络请求）。在管理后台 → 技能管理中检查并授予所需权限。

Q: 启动后访问 18789 端口无法打开 WebUI

排查步骤：

1. 检查防火墙是否放行 18789 端口（阿里云需在安全组配置）
2. 确认服务正在运行：openclaw status
3. 本地测试：curl http://localhost:18789
4. 如果本地正常但外网不通，检查云服务商的安全组/防火墙规则

Q: 内存不足导致崩溃

解决方案：

• 升级服务器配置（推荐至少 2核4GB）
• 添加 Swap 分区（参考阿里云部署教程）
• 限制 Node.js 内存：export NODE_OPTIONS="--max-old-space-size=1024"
• 减少同时启用的技能数量

Q: 域名解析错误

确认 DNS A 记录已正确指向服务器公网 IP，等待 DNS 生效（通常 5-30 分钟）。使用 ping your-domain.com 验证解析是否正确。