

网上讲怎么装 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，所以恢复了。

**处理策略（按优先级排序）：**

1.  让对方先发一条消息（最快，但不适合无人值守场景）
2.  在定时任务开始前，先安排一条"健康检查"消息发给对方，触发 token 刷新（推荐）
3.  缩短定时任务的间隔，不要让 token 长时间空置
4.  实在要无人值守推送，考虑走文件消息或网页链接作为正文，简短推送


原则：不是"多重试几次"，而是"先解决 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 的通解）：微信只做入口，正文不走微信。** 状态、摘要、提醒走文字，详细内容走文件、网页链接或知识库。这个原则比任何技术参数调优都有效。


----
**六、维护建议**

装好之后这几件事值得做：

1.  **持续更新**。iLink 协议和两边的实现都在迭代，有些 ret=-2 的处理缺陷是小版本修复的
2.  **私聊开、群聊关**。群聊是风控重灾区，没有特殊需求就别开
3.  **白名单收口**。限制只有指定联系人才能触发 Agent
4.  **单 token 只跑一个实例**。多个实例抢 token 的坑，踩过就知道多难排查
5.  **日志养成定期看的习惯**。很多故障早期在日志里有预兆


----
**总结：装好之后的排障顺序**

第一步：gateway 在线吗？不在就重启，而不是重新扫码

第二步：日志里的报错码是什么？errcode=-14 是会话过期，ret=-2 需要判断是真限流还是 stale token

第三步：长文本/文件发不出去？先确认 4000 上限和 cryptography/CDN

第四步：定时任务推送失败？先让人发一条消息进来刷新 token

第五步：所有问题都指向同一个方向——**微信只适合做短消息入口和告警通道**，正文和详情交给文件、链接、知识库。

市面上不缺安装教程，但装好之后怎么把坑一个个填平，才是决定你能不能长期用下去的 key。这五个方向踩透了，微信 Bot 就能从"凑合用"变成"稳着跑"。

![仙踪问道under_副本.png](https://developer.qcloudimg.com/http-save/yehe-7525015/5c4df6400ef33045a8edf033e4a13784.png)

网上讲怎么装 Hermes、怎么装 OpenClaw、怎么扫码的教程一搜一大堆，几步就搞定。但真正的问题从来不在安装这一步。

AI Agent 接入微信 Bot 排坑实战手册：装好只是开始，稳跑才是本事

AI Agent 接入微信 Bot 安装只是第一步，稳定运行才是关键。本文不讲安装，只讲装好之后最常见的五大故障——断链、ret=-2真假限流、定时推送失败、多实例冲突、长消息被切碎——以及从 gateway 进程到日志报错码的完整排查顺序，帮你避开 90% 的坑。

人工智能

客户端

开发工具

安装微信机器人后常见故障排查指南：电脑睡眠后微信无响应？先检查gateway进程状态，而非盲目重扫码。ret=-2错误不一定是真限流，可能是会话令牌失效，需对方发消息刷新。定时推送失败因token过期，建议前置健康检查消息。避免多实例抢占同一token，长内容优先用文件/链接传输。掌握五大核心场景排障逻辑，让微信机器人从凑合用到稳定跑。

OpenClaw

Agent

CDN免费试用


2026年中大促 | AI 领航 智绘未来

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

安装微信机器人后常见故障排查指南：电脑睡眠后微信无响应？先检查gateway进程状态，而非盲目重扫码。ret=-2错误不一定是真限流，可能是会话令牌失效，需对方发消息刷新。定时推送失败因token过期，建议前置健康检查消息。避免多实例抢占同一token，长内容优先用文件/链接传输。掌握五大核心场景排障逻辑，让微信机器人...

AI Agent 接入微信 Bot 排坑实战手册：装好只是开始，稳跑才是本事-腾讯云开发者社区-腾讯云

AI Agent 接入微信 Bot 排坑实战手册：装好只是开始，稳跑才是本事

AI Agent 接入微信 Bot 排坑实战手册：装好只是开始，稳跑才是本事

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐