# OpenClaw 故障排查指南

## 快速诊断命令

```bash
# 首选诊断流程
openclaw status                    # 基本状态
openclaw status --all             # 完整诊断（可分享）
openclaw status --deep            # 深度检测
openclaw doctor                   # 健康检查
openclaw logs --follow            # 实时日志
```

## 常见问题

### Gateway 无法启动

**症状**:
```
Error: Invalid config
Gateway start blocked: set gateway.mode=local
```

**原因**: 配置不完整或模式错误

**解决方案**:
```bash
# 运行向导配置
openclaw configure

# 或直接设置
openclaw config set gateway.mode local

# 允许无配置启动（临时）
openclaw gateway --allow-unconfigured
```

### Token 不匹配

**症状**:
```
gateway connect failed: unauthorized: token mismatch
```

**解决方案**:
```bash
# 检查本地 Token
openclaw config get gateway.auth.token

# 同步 Token 到远程主机
ssh user@host "openclaw config set gateway.auth.token 'your-token'"
```

### Telegram 消息发送失败

**症状**:
```
fetch failed
Network request for 'sendMessage' failed!
```

**排查步骤**:
```bash
# 1. 检查 Telegram 状态
openclaw status | grep telegram

# 2. 检查代理配置
echo $https_proxy
echo $http_proxy

# 3. 重启 Gateway
openclaw gateway restart

# 4. 检查 Bot Token
openclaw config get channels.telegram.botToken
```

### 模型调用失败

**症状**:
```
Error: Model not found
anthropic/claude-opus-4 is not available
```

**排查步骤**:
```bash
# 1. 检查模型配置
openclaw config get models.providers

# 2. 验证配置文件
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# 3. 设置正确模型
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

# 4. 检查认证
openclaw models status
```

### 端口被占用 (18789)

**症状**:
```
Error: Port 18789 already in use
```

**排查步骤**:
```bash
# 1. 检查端口占用
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 2. 查看 Gateway 状态
openclaw gateway status

# 3. 停止现有 Gateway
openclaw gateway stop

# 4. 或使用其他端口
openclaw config set gateway.port 18790
openclaw gateway restart
```

### 消息不触发响应

**排查步骤**:
```bash
# 1. 检查发送者是否在允许列表
openclaw status | grep AllowFrom

# 2. 群聊检查是否需要 @
openclaw logs --follow | grep blocked

# 3. 检查配对状态
openclaw pairing list telegram
```

### WhatsApp 连接问题

**排查步骤**:
```bash
# 1. 检查状态
openclaw status
openclaw status --deep

# 2. 查看连接日志
openclaw logs --follow | grep -i "connection\|disconnect"

# 3. 重新登录
openclaw channels logout whatsapp
openclaw channels login whatsapp --verbose

# 4. 检查凭证
ls -la ~/.openclaw/credentials/whatsapp/
```

### 媒体发送失败

**排查步骤**:
```bash
# 1. 验证文件存在
ls -la /path/to/file.jpg

# 2. 检查文件大小限制
# 图片: max 6MB
# 音频/视频: max 16MB
# 文档: max 100MB

# 3. 检查日志
openclaw logs | grep -i media
```

### 内存使用过高

**原因**: 对话历史保留过多

**解决方案**:
```bash
# 设置会话历史限制
openclaw config set session.historyLimit 100

# 或定期重启 Gateway
openclaw gateway restart
```

## macOS 特定问题

### App 崩溃（权限提示）

```bash
# 重置 TCC 缓存
tccutil reset All bot.molt.mac.debug
```

### Gateway 卡在 "Starting..."

```bash
# 1. 停止 supervisor
openclaw gateway stop
launchctl bootout gui/$UID/bot.molt.gateway

# 2. 检查端口
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 3. 强制停止
kill -TERM <PID>
kill -9 <PID>
```

## Linux 特定问题

### 浏览器无法启动（Chrome）

```bash
# 安装 Chrome
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

# 配置路径
openclaw config set browser.executablePath "/usr/bin/google-chrome-stable"
```

## 服务相关问题

### 服务已安装但未运行

```bash
# 检查服务状态
openclaw gateway status

# 查看服务日志
journalctl --user -u openclaw-gateway.service -n 200 --no-pager

# 查看最近错误
openclaw logs | grep -i error
```

### 服务环境变量问题

```bash
# Gateway 服务使用最小 PATH
# 手动设置环境变量
export https_proxy=http://192.168.0.66:7890
export http_proxy=http://192.168.0.66:7890

# 或在配置中设置
openclaw config set env.vars.HTTPS_PROXY "http://192.168.0.66:7890"
```

## 诊断命令速查

| 命令 | 用途 |
|------|------|
| `openclaw status` | 基本状态 |
| `openclaw status --all` | 完整诊断 |
| `openclaw status --deep` | 深度检测 |
| `openclaw doctor` | 健康检查 |
| `openclaw doctor --fix` | 自动修复 |
| `openclaw logs --follow` | 实时日志 |
| `openclaw logs --since 1h` | 最近 1 小时日志 |
| `openclaw gateway status` | 服务状态 |
| `openclaw gateway probe` | Gateway 探测 |
| `openclaw channels status` | 通道状态 |
| `openclaw models status` | 模型状态 |

## 日志位置

| 类型 | 位置 |
|------|------|
| Gateway 日志 | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` |
| 服务日志 | `journalctl --user -u openclaw-gateway.service` |
| 媒体缓存 | `$OPENCLAW_STATE_DIR/media/` |
| 凭证 | `$OPENCLAW_STATE_DIR/credentials/` |

## 恢复出厂设置

⚠️ **此操作会删除所有会话和配置**

```bash
openclaw gateway stop
trash ~/.openclaw
openclaw channels login  # 重新配对
openclaw gateway restart
```

## 获取帮助

1. 检查日志: `openclaw logs --follow`
2. 搜索 GitHub Issues
3. 提供以下信息:
   - OpenClaw 版本
   - 相关日志片段
   - 复现步骤
   - 配置（脱敏后）

---

*最后更新: 2026-02-04*