网上讲怎么装 Hermes、怎么装 OpenClaw、怎么扫码的教程一搜一大堆，几步就搞定。但真正的问题从来不在安装这一步。
装好之后，才是踩坑的开始：今天会话断了，明天消息发不出去，后天定时任务推送失败，大后天报了个 ret=-2 不知道是真限流还是假限流。日志里一堆看不懂的错误码，网上搜一圈也没人能说清楚到底该先干啥。
这篇文章不讲怎么装，只讲装好之后遇到最常见的故障，到底怎么排查、怎么处理。基于两条主流路线——Hermes Agent 和 OpenClaw（都走腾讯 iLink Bot 协议）——把共性问题和各自特有问题统一覆盖。
一、最常见：电脑睡一觉，微信就不理你了
现象：前一天还好好的，早上打开电脑发现微信不回消息了。
排查顺序（别上来就重新扫码）：
第一步，查 gateway 进程还活着没有：
Hermes：ps aux | grep hermes 或 hermes gateway status
OpenClaw：ps aux | grep openclaw 或 openclaw gateway status
第二步，看日志里有没有关键报错：
Hermes 日志一般在 ~/.hermes/logs/gateway.log，搜 errcode 和 errmsg
OpenClaw：openclaw gateway log --tail 50
第三步，根据报错类型决定下一步：
| 日志特征 | 原因 | 处理 |
|---|---|---|
| errcode=-14 | session 过期，登录态丢了 | 重跑扫码流程 |
| "Another local Hermes gateway is already using this Weixin token" | 同一个 token 被多个实例占用 | 干掉多余的 gateway 进程 |
| 插件连接断开 / 网关反复重启 | ClawBot 插件异常或版本不兼容 | openclaw plugins install --force 重装 |
| 没有明显报错，只是无响应 | 长轮询断链，睡眠/网络切换后未恢复 | 重启 gateway |
常见误区： 好多人看到微信不回，第一反应是重新扫码。但 90% 的情况不是 token 失效，要么是进程死了，要么是网络波动导致长轮询断了。重启 gateway 就行，不需要重新扫码。
二、最误导：ret=-2 不一定是真限流
现象：消息发不出去，日志里出现 ret=-2 或提示 "rate limited"。
大多数人的第一反应：降频、延迟、减少消息数量——但其实未必有效。
这里有一个非常关键的设计细节：iLink 协议里，stale context_token（过期的会话上下文令牌）和真正的限流，报错都是 ret=-2。光看错误码你根本分不出来。
怎么快速判断：
如果你发现：
- 长时间没跟这个联系人互动（几小时或以上）
- 第一次主动发消息就报 ret=-2
- 但对方给你发一条消息之后，你就能正常回复了
那 90% 是 context_token 失效，不是真限流。 解决方式是让对方先发一条消息进来刷新 token，而不是改你的重试策略。
真限流通常长这样：
- 连续高频发送多条消息后出现 ret=-2
- 长消息被切成多段，分段发送时触发
- 多个任务同时往同一个聊天窗口推送
两种情况的处理完全不同：
| 场景 | 处理方式 |
|---|---|
| context_token 失效 | 让对方发一条消息进来刷新 |
| 真限流 | 降频、合并消息、缩短输出 |
把这两者搞混，是微信 Bot 排障里最常见的弯路。
三、最头疼：定时任务推送失败，但手动对话正常
现象：cron 脚本、定时报告、自动通知推不过去，但你在对话框里手动发一条消息一切正常。
原因已经很清楚：主动推送靠的是缓存下来的 context_token，长时间无互动后 token 失效。 手动发消息让 Agent 重新拿到了有效 token，所以恢复了。
处理策略（按优先级排序）：
- 让对方先发一条消息（最快，但不适合无人值守场景）
- 在定时任务开始前，先安排一条"健康检查"消息发给对方，触发 token 刷新（推荐）
- 缩短定时任务的间隔，不要让 token 长时间空置
- 实在要无人值守推送，考虑走文件消息或网页链接作为正文，简短推送
原则：不是"多重试几次"，而是"先解决 token 刷新问题"。
四、最隐蔽：同一账号忽好忽坏
现象：今天好明天坏，这个房间通那个房间不通。
第一条排查项：有没有多个实例在抢同一个 Weixin token？
典型场景：
- 本机跑了一个 gateway，Docker 里又跑了一个
- 公司电脑和家里电脑都配了同一个账号
- 同时跑了 Hermes 和 OpenClaw 用了同一个 token
Hermes 会有明确的日志提示 "Another local Hermes gateway is already using this Weixin token"。OpenClaw 的表现没那么明显，可能只是网关反复重启或消息随机丢失。
处理方式：同一时间只运行一个 gateway 实例使用同一个 Weixin token。
五、最具体：长消息/长文件发不出去
| 问题 | 原因 | 处理 |
|---|---|---|
| 长文本被切成好几段 | 微信文本上限 4000 字符 | 只发摘要，正文放文件或链接 |
| Markdown/代码/表格很难看 | 微信不支持原生 Markdown | 自动转纯文本，复杂内容当附件发 |
| 文件/图片发不出去 | 缺 cryptography 库或 CDN不通 | Hermes: pip install aiohttp cryptography；OpenClaw: 检查插件依赖是否完整 |
| 视频/语音没有反应 | 格式或大小限制 | 转成常见格式（mp4/mp3），压缩至合理大小 |
推荐策略（微信 Bot 的通解）：微信只做入口，正文不走微信。 状态、摘要、提醒走文字，详细内容走文件、网页链接或知识库。这个原则比任何技术参数调优都有效。
六、维护建议
装好之后这几件事值得做：
- 持续更新。iLink 协议和两边的实现都在迭代，有些 ret=-2 的处理缺陷是小版本修复的
- 私聊开、群聊关。群聊是风控重灾区，没有特殊需求就别开
- 白名单收口。限制只有指定联系人才能触发 Agent
- 单 token 只跑一个实例。多个实例抢 token 的坑，踩过就知道多难排查
- 日志养成定期看的习惯。很多故障早期在日志里有预兆
总结：装好之后的排障顺序
第一步：gateway 在线吗？不在就重启，而不是重新扫码
第二步：日志里的报错码是什么？errcode=-14 是会话过期，ret=-2 需要判断是真限流还是 stale token
第三步：长文本/文件发不出去？先确认 4000 上限和 cryptography/CDN
第四步：定时任务推送失败？先让人发一条消息进来刷新 token
第五步：所有问题都指向同一个方向——微信只适合做短消息入口和告警通道，正文和详情交给文件、链接、知识库。
市面上不缺安装教程，但装好之后怎么把坑一个个填平，才是决定你能不能长期用下去的 key。这五个方向踩透了，微信 Bot 就能从"凑合用"变成"稳着跑"。