1. 微信 Bot 断连到底断在哪从「装好」到「稳跑」的排查地图微信 Bot 断连这件事最坑的地方在于它不是一个错误而是一类症状。你看到的现象可能都是「微信不回消息了」但背后的根因完全不同有时候是 gateway 进程悄悄死了有时候是长轮询断链没恢复有时候是会话上下文令牌过期还有时候是同一个 token 被两个实例抢着用。如果你上来就重新扫码大概率是在做无用功——因为 90% 的断连根本不是登录态失效。我先把排查地图给你画清楚。AI Agent 接入微信 Bot不管是 Hermes、OpenClaw 还是直接走 iLink 协议之后消息链路大致是这样的Agent 进程 → gateway 网关 → iLink 长轮询通道 → 微信客户端。断连可能发生在任何一层而每一层的表现和修法都不一样。从连接保活角度看长轮询通道对网络切换极其敏感。笔记本合盖休眠、WiFi 切到有线、甚至系统进入低功耗模式都可能让长轮询连接静默断开而进程本身还活着日志里也不一定有明显报错。这时候你需要的不是重新登录而是让 gateway 具备断线重连能力或者干脆重启 gateway。从会话续期角度看iLink 协议用 context_token 来标识一段会话上下文。这个 token 有生命周期长时间不互动就会失效。失效之后你主动发消息服务端返回的可能是 ret-2看起来像限流其实是 stale token。这个坑我在实际排查里见过太多次很多人一看到 ret-2 就开始降频、加延迟结果完全没用。从消息重试角度看长文本被切成多段、分段发送时多个任务同时往同一个聊天窗口推送会触发真正的限流。这时候重试策略如果没做好幂等还会导致消息重复。所以重试不是越多越好而是要先判断错误类型再决定要不要重试。这篇手册的目标很明确让你从「能装好」走到「能稳跑」。我会给出可复制的连接配置模板、断连复现验证步骤以及怎么把 endpoint 和鉴权参数统一改到 TaoToken 管理减少因为 key 散落各处导致的排查困难。适合已经装好 Hermes 或 OpenClaw、但被断连问题反复折磨的人。2. 把 endpoint 和鉴权收口到 TaoToken减少一类断连根因在讲具体排查之前先解决一个容易被忽略的问题鉴权参数散落。很多人的微信 Bot 断连追到最后发现是某个配置文件里的 API Key 过期了或者 endpoint 写错了但因为配置分散在好几个地方排查时根本想不到去看。我的做法是把所有 AI 能力的 endpoint 和鉴权统一收口到 TaoToken 管理。TaoToken 是一个 API 聚合平台你可以把它理解成「一个 Base URL 一个 Key 走天下」的入口。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。为什么这对微信 Bot 稳定性有帮助因为当你的 Agent 需要调用模型能力时如果 endpoint 和 key 是统一管理的那么一旦出现鉴权类错误比如 401你能立刻定位到是 key 的问题而不是在「网络问题 / 进程问题 / 模型问题」之间反复横跳。断连排查最怕的就是变量太多收口鉴权就是减少变量。具体操作上你需要拿到一个 API Key。进入控制台创建 key 的入口在这里https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。创建之后把 key 填到你的 Agent 配置里Base URL 统一写成 https://taotoken.net/api 。如果你用的是 Claude Code 这类编码 AgentTaoToken 也提供了对应的接入方式文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Claude Code 的接入可以参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。这里要强调一个原则微信 Bot 的稳定性问题很多时候不是微信本身的问题而是整个链路里某个环节的配置漂移了。把 endpoint 和 key 收口等于给排查建立了一个稳定的基准点。后面遇到任何断连你都可以先确认「鉴权这一层是好的」然后专心排查连接保活和会话续期。另外如果你需要长期跑编码类或 Agent 类任务可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。对于需要验证模型对话效果的场景可以用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。3. 可复制的连接配置模板Hermes 与 OpenClaw 的 gateway 参数这一节给你可以直接抄的配置。不管你是 Hermes 还是 OpenClaw核心思路都是把 gateway 的连接参数、重连策略、鉴权信息写清楚避免用默认值硬扛。先看 Hermes 的配置。Hermes 的 gateway 配置一般在~/.hermes/config.toml或项目目录下的config.toml。下面是一个可复制的模板重点在[gateway]和[llm]两段# ~/.hermes/config.toml [gateway] # iLink 长轮询超时单位秒。太短会频繁重连太长断链后恢复慢 poll_timeout 45 # 断线重连间隔单位秒 reconnect_interval 5 # 最大重连次数超过后进程退出交给外部守护进程拉起 max_reconnect 20 # 心跳间隔用于检测长轮询是否还活着 heartbeat_interval 30 [session] # context_token 缓存时间单位秒。超过这个时间没互动主动发消息前先刷新 context_token_ttl 3600 # 是否在定时任务前自动触发健康检查消息 pre_task_health_check true [llm] # 统一走 TaoToken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 # 请求超时避免模型调用卡死导致 gateway 假死 request_timeout 60再看 OpenClaw 的配置。OpenClaw 一般用~/.openclaw/config.json或环境变量。下面是一个 JSON 模板{ gateway: { pollTimeout: 45, reconnectInterval: 5, maxReconnect: 20, heartbeatInterval: 30, singleInstanceLock: true }, session: { contextTokenTtl: 3600, preTaskHealthCheck: true }, llm: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, requestTimeout: 60 } }几个参数值得单独解释。singleInstanceLock这个开关非常重要它保证同一时间只有一个 gateway 实例使用同一个 Weixin token。前面说的「同一账号忽好忽坏」很多时候就是多个实例在抢 token。Hermes 没有这个显式开关但它的日志会提示 token 被占用你需要手动确保只跑一个实例。context_token_ttl和pre_task_health_check是解决定时任务推送失败的关键。把 TTL 设成 3600 秒意味着超过一小时没互动Agent 就知道 token 可能失效了。pre_task_health_check打开后定时任务执行前会先发一条健康检查消息触发 token 刷新。如果你用的是 Cline MCP 或 Codex 这类工具配置里同样要写全三件套Base URL、Key、Model ID。以 Codex 的auth.json为例{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }Cline MCP 的配置类似在 MCP server 的 settings 里填{ mcpServers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: claude-sonnet-4-20250514 } } }配置写完先别急着跑。用hermes gateway status或openclaw gateway status确认配置被正确加载。如果状态里显示的 base_url 还是旧的说明配置文件路径不对或者环境变量覆盖了配置文件。4. 断连复现与验证用最小步骤确认修好了配置改完怎么验证真的稳了我给你一套可复现的验证步骤按顺序做每一步都有明确的预期结果。第一步验证 gateway 进程和长轮询。启动 gateway 后观察日志# Hermes hermes gateway start tail -f ~/.hermes/logs/gateway.log # OpenClaw openclaw gateway start openclaw gateway log --tail 50预期看到类似polling started、heartbeat ok的日志。如果看到reconnect attempt反复出现说明长轮询不稳定检查网络或调大poll_timeout。第二步验证会话续期。手动给 Bot 发一条消息然后等超过context_token_ttl的时间测试时可以临时改成 60 秒再主动发一条消息。如果配置正确pre_task_health_check会先触发一条健康检查然后正常回复。如果直接报 ret-2说明 token 刷新逻辑没生效。第三步验证单实例锁。故意启动两个 gateway 实例# 第一个实例 hermes gateway start # 第二个实例应该被拒绝或提示 token 占用 hermes gateway start预期第二个实例启动失败日志提示Another local Hermes gateway is already using this Weixin token。OpenClaw 开了singleInstanceLock后第二个实例应该直接退出。第四步验证长消息处理。发一条超过 4000 字符的消息观察是否被正确切分或转成文件。如果消息发不出去检查cryptography库# Hermes pip install aiohttp cryptography # OpenClaw openclaw plugins install --force第五步验证定时任务推送。配置一个每分钟执行一次的 cron 任务让它主动推送一条消息。观察是否成功。如果失败看日志里是 ret-2 还是其他错误。如果是 ret-2先让对方发一条消息进来刷新 token再重试。这套验证做完你对整个链路的稳定性就有底了。实测下来大部分断连问题都能在这五步里定位到。5. 常见报错对照排查401、local proxy failed、reading choices、OAuth这一节把最常见的报错和对应处理列清楚。你遇到问题时直接对照查。401 Unauthorized。这是鉴权失败通常意味着 API Key 无效或过期。先确认 TaoToken 的 key 还在有效期内然后检查配置文件里的api_key有没有写错。如果你用的是环境变量确认环境变量真的被加载了。401 不会导致微信 Bot 断连但会导致 Agent 无法回复表现上像断连。local proxy failed。这个报错通常出现在网络层意思是本地代理连接失败。注意这里说的是你本机网络配置的问题不是让你去用什么特殊网络工具。检查你的系统代理设置确认 gateway 进程能正常访问外网。如果是公司网络环境确认防火墙没有拦截长轮询端口。reading choices 相关报错。这个一般出现在模型返回格式解析阶段比如error reading choices from response。说明模型 API 返回的结构和 Agent 预期的不一致。先确认 Base URL 写的是https://taotoken.net/api然后确认 Model ID 拼写正确。如果 Model ID 写错有些服务会返回一个非标准结构导致解析失败。OAuth 相关报错。如果你用的是 Claude Code 或类似需要 OAuth 的工具可能会遇到 token 刷新失败。检查 OAuth 配置里的回调地址和 key 是否匹配。Claude Code 的接入文档在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 里面有完整的配置步骤。errcode-14。这是 iLink 协议的会话过期错误登录态丢了。处理方式是重跑扫码流程。注意只有这个错误才需要重新扫码其他断连不要上来就扫码。ret-2。前面详细讲过需要区分是 stale context_token 还是真限流。判断方法长时间没互动后第一次主动发消息就报 ret-2大概率是 token 失效连续高频发送后报 ret-2大概率是真限流。Another local Hermes gateway is already using this Weixin token。同一个 token 被多个实例占用。干掉多余的 gateway 进程确保同一时间只有一个实例在跑。插件连接断开 / 网关反复重启。ClawBot 插件异常或版本不兼容。用openclaw plugins install --force重装插件。没有明显报错只是无响应。长轮询断链睡眠或网络切换后未恢复。重启 gateway 即可。把这张对照表存下来下次遇到报错先查表能省很多时间。6. 让 Bot 从「凑合用」到「稳着跑」维护清单与收口建议最后给你一份维护清单。装好只是开始稳跑才是本事而稳跑靠的是日常维护习惯。第一持续更新。iLink 协议和 Hermes、OpenClaw 的实现都在迭代有些 ret-2 的处理缺陷是小版本修复的。定期更新能避免踩已知的坑。第二私聊开、群聊关。群聊是风控重灾区没有特殊需求就别开。如果一定要开用白名单收口限制只有指定联系人才能触发 Agent。第三单 token 只跑一个实例。多个实例抢 token 的坑踩过就知道多难排查。用singleInstanceLock或手动确保只跑一个 gateway。第四养成看日志的习惯。很多故障早期在日志里有预兆比如反复的 reconnect attempt、偶尔的 ret-2。定期看日志能在问题变大之前处理掉。第五微信只做入口正文不走微信。状态、摘要、提醒走文字详细内容走文件、网页链接或知识库。这个原则比任何技术参数调优都有效。微信文本上限 4000 字符Markdown 和表格显示效果差长内容天然不适合走微信。第六把 endpoint 和鉴权收口到 TaoToken。统一管理 Base URL 和 Key减少配置漂移导致的排查困难。需要创建 key 就去 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 需要查文档就去 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。排障和接入相关的问题优先看 API Keys 和接入文档需要验证模型对话效果用模型对话入口长期跑编码或 Agent 任务考虑 Coding Plan。把这几件事做到位你的微信 Bot 就能从「凑合用」变成「稳着跑」。