微信AI Agent排坑指南：从装好到稳跑
市面上讲怎么装 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 |
多数人容易踩的坑：一看到微信没反应，第一反应就是重新扫码。但现实是，超过九成的情况不是 token 失效，要么是进程挂了，要么是网络波动导致长轮询断了。遇到这种情况，先重启 gateway，不需要重新扫。
二、最误导：ret=-2 不一定是真限流
消息发不出去，日志里出现 ret=-2 或提示 "rate limited"。大多数人的第一反应是降频、延迟、减少消息数量——但这么做未必管用。
这里有一个很关键的设计细节：在 iLink 协议里，过期的会话上下文令牌（stale context_token）和真正的限流，报的都是 ret=-2。光看错误码，根本没有办法区分。
怎么快速判断？
如果你遇到以下情况：
- 已经好几个小时没跟这个联系人互动过
- 第一次主动发消息就报 ret=-2
- 但对方给你发一条消息之后，你就能正常回复了
那九成是 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。
第五步：所有问题都指向同一个方向——微信只适合做短消息入口和告警通道，正文和详情交给文件、链接、知识库。
市面上不缺安装教程，但装好之后怎么把坑一个个填平，才是决定你能不能长期用下去的关键。这五个方向踩透了，微信 Bot 就能从"凑合用"变成"稳着跑"。
