# wecom_callback "机器人没回复" 诊断流程

当用户反馈企微机器人发消息后没有回复时，按以下顺序排查，每一步都有明确的检查命令和判断标准。

## 第1步：确认隧道可用

```bash
# 检查隧道连接状态（应看到 2-4 条 "Registered tunnel connection"）
sudo journalctl -u cloudflared-tunnel --no-pager -n 10 | grep "Registered tunnel"

# 测试已知可用的 hostname
curl -s -o /dev/null -w "%{http_code}" https://rss.gdcjgk.net/ --connect-timeout 5
```

- **无 Registered 日志** → 隧道未连接，看 journalctl 中的错误（QUIC timeout / HTTP/2 timeout）
- **rss 返回非 200** → 隧道断连，重启 `sudo systemctl restart cloudflared-tunnel`
- **rss 返回 200 但 callback hostname 返回 403** → DNS CNAME 未添加或隧道 ingress 未配置该 hostname

## 第2步：确认企微 API 可达

```bash
# 测试获取 token（errmsg 应为 "ok"）
curl -s "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=<corpid>&corpsecret=<secret>" --connect-timeout 5
```

- **返回 errcode=0, errmsg="ok"** → API 正常
- **超时 (timeout)** → 服务器无法访问 qyapi.weixin.qq.com，检查 DNS/网络
- **errcode != 0** → corpsecret 可能过期或被修改，去企微后台检查

## 第3步：确认回调端口在监听

```bash
ss -tlnp | grep 8645
```

- **有 LISTEN** → 端口正常
- **无输出** → Hermes gateway 未运行或 wecom_callback 未启用，检查 `hermes gateway status`

## 第4步：查看 gateway 日志

```bash
# 查看最近的 wecom_callback 活动
grep "wecom_callback" ~/.hermes/logs/gateway.log | tail -10

# 查看最近的错误
grep -i "error\|failed" ~/.hermes/logs/gateway.log | tail -10
```

**关键日志解读：**

| 日志 | 含义 |
|------|------|
| `inbound message: platform=wecom_callback user=... msg='...'` | 消息已到达 Hermes |
| `response ready: platform=wecom_callback ... time=N.Ns` | 回复已生成 |
| `Sending response (N chars) to ...` | 回复已发送到企微 API |
| `Token refreshed for app 'smartbot' ... expires in 7200s` | Token 正常刷新 |
| **无任何 wecom_callback 日志** | 消息未到达 → 隧道/回调配置问题 |
| `errcode=853000` | wecom WebSocket 平台密钥无效（通常是 `wecom` 平台噪声，不影响 callback） |

## 第5步：区分 wecom 平台噪声与真实问题

注意：`error 853000` 来源于 `gateway.platforms.wecom`（WebSocket 模式），不是 `wecom_callback`（URL 回调模式）。

如果 config.yaml 中 `wecom.enabled: false` 但日志仍在刷 853000 重连：
- 这是 **噪声**，不影响 wecom_callback 的正常工作
- 两个 platform 是独立的

## 第6步：确认 cloudflared service 配置

```bash
cat /etc/systemd/system/cloudflared-tunnel.service | grep ExecStart
```

确保包含 `--protocol http2`，否则隧道重启后会因 QUIC 被墙而等待 1-2 分钟才恢复：

```
ExecStart=/usr/local/bin/cloudflared tunnel --no-autoupdate --protocol http2 --config /home/agentuser/.cloudflared/config.yml run
```

修改后：
```bash
sudo systemctl daemon-reload
sudo systemctl restart cloudflared-tunnel
```

## 快速一览

| 检查项 | 命令 | 正常结果 |
|--------|------|---------|
| 隧道连接 | `journalctl -u cloudflared-tunnel --no-pager \| grep "Registered"` | 2-4条 protocol=http2 |
| 外网可达 | `curl -s -o /dev/null -w "%{http_code}" https://rss.gdcjgk.net/` | 200 |
| 企微 API | `curl -s "https://qyapi.weixin.qq.com/cgi-bin/gettoken?..."` | errcode=0 |
| 端口监听 | `ss -tlnp \| grep 8645` | LISTEN |
| 消息到达 | `grep "inbound.*wecom_callback" ~/.hermes/logs/gateway.log \| tail -3` | 有最新消息 |
| Token 有效 | `grep "Token refreshed" ~/.hermes/logs/gateway.log \| tail -1` | expires in 7200s |