# 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*
*维护者: 青龙 🐉*