常见问题

安装问题

Node.js 版本不满足要求

现象：Error: Requires Node.js >= 22

解决：

# 检查当前版本
node --version

# 升级到 Node.js 22
nvm install 22 && nvm use 22

---

npm 全局安装权限报错

现象：EACCES: permission denied

解决：

# 方案一：修复 npm 目录权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 方案二：使用 sudo（不推荐）
sudo npm install -g openclaw

---

启动问题

端口被占用

现象：Error: EADDRINUSE: address already in use :::3000

解决：

# 找出占用进程
lsof -i :3000

# 更换端口
openclaw config set gateway.port 3001

---

配置文件损坏

现象：启动时报 JSON 解析错误

解决：

# 备份损坏的配置
mv ~/.openclaw/config.json ~/.openclaw/config.json.bak

# 重新运行向导
openclaw wizard

---

频道问题

Telegram Bot 无响应

检查步骤：

1. 确认 Bot Token 正确：在 @BotFather 重新获取
2. 检查频道状态：openclaw channels list
3. 查看错误日志：openclaw logs --filter telegram

---

WhatsApp 二维码过期

WhatsApp 使用二维码配对，二维码有效期约 60 秒。

# 重新生成二维码
openclaw channels reconnect whatsapp

扫码后需在手机上确认授权。

---

AI 连接问题

API Key 无效

现象：AuthenticationError: Invalid API key

解决：

# 更新 API Key
openclaw config set ai.apiKey "sk-ant-..."

# 测试连接
openclaw ping

---

响应超时

现象：等待很久后报 Timeout 错误

解决：

• 检查网络连接，确认能访问 AI 提供商接口
• 如使用代理转发（如 XaAPI），确认 baseURL 配置正确：

  openclaw config set ai.baseURL "https://xaapi.ai"

• 适当增大超时时间：

  openclaw config set ai.timeout 60000

---

获取帮助

• GitHub Issues — 提交 Bug 或功能请求
• 官方文档 — 完整参考文档