O
OpenClaw

故障排查

本文汇总了 OpenClaw 使用中的常见问题及解决方法。

安装问题

npm install 失败

# 问题：权限错误
EACCES: permission denied

# 解决：使用 npx 临时运行
npx openclaw gateway start

# 或使用 volta/nvm 管理 Node 版本

Node.js 版本过低

# 问题：需要 Node.js 22+
Error: Requires Node.js >= 22.0.0

# 解决：升级 Node.js
# macOS
brew upgrade node

# 或使用 nvm
nvm install 22
nvm use 22

启动问题

Gateway 无法启动

  • 检查端口是否被占用：lsof -i :18789
  • 检查 API 密钥是否设置：echo $ANTHROPIC_API_KEY
  • 查看详细错误日志：openclaw gateway start --verbose

端口被占用

# 查看占用进程
lsof -i :18789

# 修改配置文件使用其他端口
# ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 18790
  }
}

AI 响应问题

AI 不响应消息

  • 检查 API 密钥余额是否充足
  • 检查 allowFrom 是否包含你的账号
  • 检查是否在群组中需要 @提及
  • 查看 Gateway 日志中的错误信息

API 请求失败

# 问题：401 Unauthorized
# 解决：检查 API 密钥是否正确
export ANTHROPIC_API_KEY="your-correct-key"

# 问题：429 Rate Limit
# 解决：降低请求频率，或升级 API 计划

频道连接问题

WhatsApp 二维码不显示

  • 确保终端支持图像显示（iTerm2、Terminal.app）
  • 使用 ASCII 模式：配置 "qrTerminal": true
  • 检查网络连接

Telegram Bot 无响应

  • 先私聊 Bot 发送 /start
  • 检查 botToken 是否正确
  • 检查是否设置了 webhook 但没有配置服务器

Discord Bot 离线

  • 检查 botToken 是否正确
  • 确认开启了 MESSAGE CONTENT INTENT
  • 检查 Bot 是否已被邀请进服务器

查看日志

日志文件位置：

# 实时查看日志
tail -f ~/.openclaw/logs/gateway.log

# 查看最后 100 行
tail -n 100 ~/.openclaw/logs/gateway.log

# 带过滤查看
grep "ERROR" ~/.openclaw/logs/gateway.log

获取帮助

如果以上方法无法解决问题：