4.0 KiB
4.0 KiB
OpenClaw 故障排查指南
🚨 常见问题
1. Gateway 无法启动
症状:
Error: Invalid config at /root/.openclaw/openclaw.json
- <root>: Unrecognized key: "xxx"
原因: 配置格式错误
解决方案:
# 检查配置
openclaw doctor
# 修复配置
openclaw doctor --fix
# 查看详细错误
openclaw logs --follow
2. Telegram 消息发送失败
症状:
fetch failed
Network request for 'sendMessage' failed!
原因:
- 代理未配置
- 网络连接问题
- Bot Token 错误
解决方案:
# 检查Telegram状态
openclaw status | grep telegram
# 检查代理配置
echo $https_proxy
echo $http_proxy
# 重启Gateway
openclaw gateway restart
# SSH远程测试
sshpass -p 'password' ssh root@host "openclaw message send --target tg:123 --message 'test'"
3. 模型调用失败
症状:
Error: Model not found
anthropic/claude-opus-4-5 is not available
原因: 模型配置错误或未配置
解决方案:
# 检查模型配置
openclaw config get models.providers
# 验证配置文件
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 设置正确的默认模型
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"
4. WebSocket 连接失败
症状:
gateway connect failed: unauthorized: token mismatch
原因: Gateway Token 不匹配
解决方案:
# 检查本地token
openclaw config get gateway.auth.token
# 修改远程Gateway token
ssh user@host "openclaw config set gateway.auth.token 'new-token'"
# 或直接编辑配置文件
ssh user@host "nano ~/.openclaw/openclaw.json"
5. 内存管理器不可用
症状:
Memory: enabled (plugin memory-core) · unavailable
原因: OpenAI API 不可用（中国网络环境）
解决方案:
- 停用内存管理器
- 使用本地 embedding 服务
- 定期导出记忆到文件
🔍 诊断命令
系统状态
# 基本状态
openclaw status
# 详细状态
openclaw status --deep
# 所有会话
openclaw status --all
日志查看
# 实时日志
openclaw logs --follow
# 最近日志
openclaw logs --since 1h
# 过滤错误
openclaw logs | grep -i error
配置检查
# 获取完整配置
openclaw config get
# 获取特定配置
openclaw config get agents.defaults.model
# 验证配置
openclaw doctor
🛠️ 修复流程
标准修复流程
-
停止Gateway
openclaw gateway stop -
备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup -
修复配置
openclaw doctor --fix -
重启Gateway
openclaw gateway restart -
验证状态
openclaw status
强制重启
# 杀死进程
pkill -9 openclaw
# 清理锁文件
rm -f ~/.openclaw/*.lock
# 重启服务
systemctl --user restart openclaw-gateway.service
📋 错误代码
| 代码 | 说明 | 解决方案 |
|---|---|---|
| E001 | 配置无效 | 运行 openclaw doctor --fix |
| E002 | Token不匹配 | 检查 gateway.auth.token |
| E003 | 模型不可用 | 检查模型配置 |
| E004 | 网络错误 | 检查代理和网络连接 |
| E005 | 通道未配置 | 配置通道设置 |
🌐 网络问题
代理配置
# 检查代理
curl -I https://github.com --proxy http://192.168.0.66:7890
# 测试API
curl -I https://api.deepseek.com --proxy http://192.168.0.66:7890
SSH 隧道
# 创建隧道
ssh -L 18789:localhost:18789 user@remote-host
# 保持隧道
ssh -N -L 18789:localhost:18789 user@remote-host &
📞 获取帮助
官方资源
- 文档: https://docs.openclaw.ai
- GitHub: https://github.com/openclaw/openclaw
- FAQ: https://docs.openclaw.ai/faq
调试模式
# 启用详细日志
openclaw gateway --verbose
# 跟踪特定模块
openclaw logs --follow | grep telegram
最后更新: 2026-02-03 21:35 GMT+8 维护者: 青龙 🐉