📚

OpenClaw WIKI

最接地气的中文指南

🔧 故障排查

遇到问题别慌，按这个指南一步步排查

🩺 诊断流程

遇到问题时，按这个顺序排查：

1

检查 Gateway 状态

openclaw gateway status
✅ 预期: 应该显示 running 和端口信息
🛠️ 修复: 如果没运行: openclaw gateway --port 18789
2

运行 Doctor 诊断

openclaw doctor
✅ 预期: 查看是否有错误或警告
🛠️ 修复: 根据 doctor 提示修复问题
3

检查日志

openclaw logs --follow
✅ 预期: 查看最近的错误信息
🛠️ 修复: 根据错误信息针对性修复
4

测试基础连接

curl http://localhost:18789/health
✅ 预期: 应该返回健康状态
🛠️ 修复: 检查端口和防火墙
5

检查配置

openclaw config validate
✅ 预期: 验证配置文件语法
🛠️ 修复: 根据错误修复 ~/.openclaw/openclaw.json

❌ 常见错误代码

ECONNREFUSED 连接被拒绝

🔍 可能原因：

  • • Gateway 没有运行
  • • 端口配置错误
  • • 防火墙阻止

✅ 解决方案：

  • • 检查 Gateway 状态: openclaw gateway status
  • • 确认端口正确: netstat -tlnp | grep 18789
  • • 检查防火墙规则
401 Unauthorized 认证失败

🔍 可能原因：

  • • Token 错误
  • • Token 过期
  • • 未配置认证

✅ 解决方案：

  • • 检查 ~/.openclaw/openclaw.json 中的 token
  • • 重新生成 token
  • • 确认请求头中包含正确的 Authorization
NODE_NOT_FOUND 节点未找到

🔍 可能原因：

  • • iOS/Android App 未连接
  • • 配对未完成
  • • 节点已离线

✅ 解决方案：

  • • 检查手机 App 是否运行
  • • 查看待配对请求: openclaw nodes pending
  • • 重新配对设备
CANVAS_DISABLED Canvas 被禁用

🔍 可能原因：

  • • macOS App 中关闭了 Canvas
  • • 配置中禁用了 Canvas

✅ 解决方案：

  • • macOS App Settings → Allow Canvas → 开启
  • • 检查配置中的 canvas.enabled
RATE_LIMITED API 请求被限流

🔍 可能原因：

  • • Anthropic/OpenAI 限流
  • • 短时间内请求太多

✅ 解决方案：

  • • 等待几分钟后重试
  • • 检查 API 用量限制
  • • 考虑升级 API 套餐

📱 频道问题

WhatsApp

二维码扫描后无反应

原因：手机网络问题, WhatsApp 版本过旧

解决：检查手机网络，更新 WhatsApp 到最新版

频繁掉线

原因：手机锁屏, WhatsApp Web 会话过期

解决：保持手机解锁，定期重新扫码

消息发不出去

原因：被 WhatsApp 风控, 账号异常

解决：减少发送频率，避免被标记为 spam

Telegram

Bot 不回复

原因：Webhook 配置错误, Token 失效

解决：检查 Token，确认 Bot 有消息接收权限

群组里不工作

原因：Bot 不是管理员, 隐私设置阻止

解决：将 Bot 设为群组管理员，关闭隐私模式

Discord

Slash 命令不显示

原因：命令未注册, 权限不足

解决：重新邀请 Bot，添加 applications.commands 权限

无法发送消息

原因：Bot 没有 SEND_MESSAGES 权限

解决：在 Discord Developer Portal 配置权限

📊 日志级别说明

ERROR 严重错误，需要立即处理

示例：ECONNREFUSED, 认证失败, 崩溃

WARN 警告，可能影响功能

示例：重试, 降级, 配置建议

INFO 正常信息，记录运行状态

示例：启动, 连接, 消息处理

DEBUG 调试信息，开发使用

示例：详细请求, 内部状态

⚡ 快速修复

Gateway 启动失败

1 检查端口是否被占用: lsof -ti:18789 | xargs kill -9
2 检查配置文件语法: cat ~/.openclaw/openclaw.json | jq
3 重置配置: openclaw reset --config
4 清除缓存: rm -rf ~/.openclaw/cache

收不到消息

1 检查频道状态: openclaw channels status
2 重新登录频道: openclaw channels login <channel>
3 检查白名单: openclaw config get channels.telegram.allowFrom
4 查看配对状态: openclaw pairing list

AI 不回复

1 检查 API Key: openclaw config get agents.defaults.model.apiKey
2 测试模型: openclaw agent --message 'test'
3 查看模型状态: openclaw models status
4 检查余额: 登录 Anthropic/OpenAI 控制台

性能缓慢

1 清理旧会话: openclaw sessions prune
2 检查内存使用: openclaw system memory
3 重启 Gateway: openclaw gateway restart
4 升级硬件: 增加 RAM 或使用 SSD

❓ 常见问题

Q: 如何开启调试日志？

A: 运行命令时加 --verbose 参数，或设置环境变量 OPENCLAW_LOG_LEVEL=debug

Q: Gateway 占用了太多内存怎么办？

A: 运行 openclaw sessions prune 清理旧会话，或降低 sessions.maxHistory 配置

Q: 如何备份我的配置？

A: cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)

Q: 更新后配置丢失了？

A: 检查是否使用了正确的配置文件路径，或使用 openclaw config import 恢复备份

Q: API 调用太慢怎么办？

A: 考虑更换更快的模型（如 Claude Sonnet 替代 Opus），或使用模型缓存

🆘 还是解决不了？

💬

Discord 社区

实时问答，大佬在线
🐛

GitHub Issues

提交 Bug 报告
📚

官方文档

最权威的技术文档
←

上一章

🐳 部署与运维

下一章

CLI 速查表 ⌨️

→