# QQ Bot 平台排查指南

## "No messaging platforms enabled" 排查

### 1. 确认配置

```bash
grep -A5 "platform_toolsets:" ~/.hermes/config.yaml
grep -E "QQ_APP_ID|QQ_CLIENT_SECRET|QQ_ALLOW_ALL_USERS" ~/.hermes/.env
```

### 2. 确认平台代码存在

```bash
ls /opt/hermes-venv/lib/python3.*/site-packages/gateway/platforms/qqbot/
```

### 3. 启动方式

```bash
# 方式1（推荐，跟老服务器一致）
/opt/hermes-venv/bin/python -m hermes_cli.main gateway run --replace

# 方式2
/opt/hermes-venv/bin/hermes gateway run
```

### 4. 日志检查

```bash
cat /tmp/hermes-gateway.log
grep -i "qqbot\|websocket\|platform" /tmp/hermes-gateway.log
```

### 5. 注意事项

- WebSocket code=4009 Session timed out 是正常心跳重连，不影响使用
- gateway 重启可能导致 SSH 断开（exit 255），重连即可
- QQ bot 是内置的，不需要 pip install hermes-qqbot（这个包不存在）
- pilk/STT 语音解码警告不影响文字消息

## ⚠️ 关键：sessions.json 必须搬迁

**症状**：配置全部正确，QQ bot 代码也存在，但 gateway 启动后 "No messaging platforms enabled"

**原因**：QQ bot 的连接 session 信息存储在 `~/.hermes/sessions/sessions.json` 中。这个文件记录了 QQ WebSocket 的 session token。如果新服务器没有这个文件，QQ bot 就无法建立连接。

**解决**：必须把老服务器的 `~/.hermes/sessions/` 目录完整拷贝到新服务器：

```bash
# 从老服务器传到新服务器
sshpass -p '新服务器密码' scp -o StrictHostKeyChecking=no \
  /root/.hermes/sessions/sessions.json \
  root@新IP:/root/.hermes/sessions/sessions.json

# 或者整个 sessions 目录（推荐，包含所有 session 文件）
rsync -avz --timeout=60 -e "sshpass -p '密码' ssh -o StrictHostKeyChecking=no" \
  /root/.hermes/sessions/ root@新IP:/root/.hermes/sessions/
```

**注意**：sessions 目录可能很大（几百MB的 session JSON 文件），传输需要时间。可以只传 `sessions.json` 文件（最小必需）。

## ⚠️ 关键：SOUL.md 必须搬迁

**症状**：新服务器 Hermes 能聊天，但回复是 "我是 OWL/ZOO 公司开发的 AI 助手"，不是用户的自定义人格（如"星璇"）

**原因**：`~/.hermes/SOUL.md` 定义了 AI 助手的身份、性格、语言习惯。不拷过去就用默认人格。

**解决**：
```bash
scp /root/.hermes/SOUL.md root@新IP:/root/.hermes/SOUL.md
```

## ⚠️ 关键：.state.db 必须搬迁

**症状**：新服务器 Hermes 不认识用户，没有记忆

**原因**：用户记忆（MEMORY、USER PROFILE）存储在 `~/.hermes/state.db` SQLite 数据库中

**解决**：
```bash
sshpass -p '密码' scp -o StrictHostKeyChecking=no \
  /root/.hermes/state.db \
  /root/.hermes/state.db-wal \
  /root/.hermes/state.db-shm \
  root@新IP:/root/.hermes/
```

## 搬迁后 QQ bot 仍不连接的终极排查

如果以上文件都搬过去了，QQ bot 还是不连接：

1. **检查 QQ session 是否过期**：老服务器的 session 可能已经过期（WebSocket code=4009 反复超时）。这种情况下需要重新配对 QQ bot。

2. **检查 QQ_APP_ID 和 QQ_CLIENT_SECRET 是否正确**：确认 `.env` 中的值跟老服务器一致。

3. **检查网络连通性**：新服务器可能网络环境不同，测试：
   ```bash
   curl -s https://api.qq.com 2>&1 | head -5
   ```

4. **尝试重新生成 session**：删除 `~/.hermes/sessions/sessions.json`，重启 gateway，让它重新建立连接。

5. **检查 gateway 版本差异**：老服务器可能是从源码安装的特定版本，新服务器是 pip 安装的版本。版本差异可能导致 QQ bot 行为不同。用 `hermes --version` 对比两台服务器的版本。