每日备份 2026-06-10 12:57:13

doc/TROUBLESHOOTING.md

@@ -0,0 +1,249 @@
+# 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*
+*维护者: 青龙 🐉*