250 lines
4.0 KiB
Markdown
250 lines
4.0 KiB
Markdown
# OpenClaw 故障排查指南
|
|
|
|
## 🚨 常见问题
|
|
|
|
### 1. Gateway 无法启动
|
|
|
|
**症状**:
|
|
```
|
|
Error: Invalid config at /root/.openclaw/openclaw.json
|
|
- <root>: Unrecognized key: "xxx"
|
|
```
|
|
|
|
**原因**: 配置格式错误
|
|
|
|
**解决方案**:
|
|
```bash
|
|
# 检查配置
|
|
openclaw doctor
|
|
|
|
# 修复配置
|
|
openclaw doctor --fix
|
|
|
|
# 查看详细错误
|
|
openclaw logs --follow
|
|
```
|
|
|
|
### 2. Telegram 消息发送失败
|
|
|
|
**症状**:
|
|
```
|
|
fetch failed
|
|
Network request for 'sendMessage' failed!
|
|
```
|
|
|
|
**原因**:
|
|
- 代理未配置
|
|
- 网络连接问题
|
|
- Bot Token 错误
|
|
|
|
**解决方案**:
|
|
```bash
|
|
# 检查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
|
|
```
|
|
|
|
**原因**: 模型配置错误或未配置
|
|
|
|
**解决方案**:
|
|
```bash
|
|
# 检查模型配置
|
|
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 不匹配
|
|
|
|
**解决方案**:
|
|
```bash
|
|
# 检查本地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 服务
|
|
- 定期导出记忆到文件
|
|
|
|
## 🔍 诊断命令
|
|
|
|
### 系统状态
|
|
|
|
```bash
|
|
# 基本状态
|
|
openclaw status
|
|
|
|
# 详细状态
|
|
openclaw status --deep
|
|
|
|
# 所有会话
|
|
openclaw status --all
|
|
```
|
|
|
|
### 日志查看
|
|
|
|
```bash
|
|
# 实时日志
|
|
openclaw logs --follow
|
|
|
|
# 最近日志
|
|
openclaw logs --since 1h
|
|
|
|
# 过滤错误
|
|
openclaw logs | grep -i error
|
|
```
|
|
|
|
### 配置检查
|
|
|
|
```bash
|
|
# 获取完整配置
|
|
openclaw config get
|
|
|
|
# 获取特定配置
|
|
openclaw config get agents.defaults.model
|
|
|
|
# 验证配置
|
|
openclaw doctor
|
|
```
|
|
|
|
## 🛠️ 修复流程
|
|
|
|
### 标准修复流程
|
|
|
|
1. **停止Gateway**
|
|
```bash
|
|
openclaw gateway stop
|
|
```
|
|
|
|
2. **备份配置**
|
|
```bash
|
|
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
|
|
```
|
|
|
|
3. **修复配置**
|
|
```bash
|
|
openclaw doctor --fix
|
|
```
|
|
|
|
4. **重启Gateway**
|
|
```bash
|
|
openclaw gateway restart
|
|
```
|
|
|
|
5. **验证状态**
|
|
```bash
|
|
openclaw status
|
|
```
|
|
|
|
### 强制重启
|
|
|
|
```bash
|
|
# 杀死进程
|
|
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 | 通道未配置 | 配置通道设置 |
|
|
|
|
## 🌐 网络问题
|
|
|
|
### 代理配置
|
|
|
|
```bash
|
|
# 检查代理
|
|
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 隧道
|
|
|
|
```bash
|
|
# 创建隧道
|
|
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
|
|
|
|
### 调试模式
|
|
|
|
```bash
|
|
# 启用详细日志
|
|
openclaw gateway --verbose
|
|
|
|
# 跟踪特定模块
|
|
openclaw logs --follow | grep telegram
|
|
```
|
|
|
|
---
|
|
|
|
*最后更新: 2026-02-03 21:35 GMT+8*
|
|
*维护者: 青龙 🐉*
|