企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。

为什么这对微信 Bot 稳定性有帮助？因为当你的 Agent 需要调用模型能力时，如果 endpoint 和 key 是统一管理的，那么一旦出现鉴权类错误（比如 401），你能立刻定位到是 key 的问题，而不是在「网络问题 / 进程问题 / 模型问题」之间反复横跳。断连排查最怕的就是变量太多，收口鉴权就是减少变量。

具体操作上，你需要拿到一个 API Key。进入控制台创建 key 的入口在这里：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。创建之后，把 key 填到你的 Agent 配置里，Base URL 统一写成 https://taotoken.net/api 。

如果你用的是 Claude Code 这类编码 Agent，TaoToken 也提供了对应的接入方式，文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。Claude Code 的接入可以参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

这里要强调一个原则：微信 Bot 的稳定性问题，很多时候不是微信本身的问题，而是整个链路里某个环节的配置漂移了。把 endpoint 和 key 收口，等于给排查建立了一个稳定的基准点。后面遇到任何断连，你都可以先确认「鉴权这一层是好的」，然后专心排查连接保活和会话续期。

另外，如果你需要长期跑编码类或 Agent 类任务，可以考虑 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。对于需要验证模型对话效果的场景，可以用模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，里面有完整的配置步骤。

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，需要查文档就去 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。

排障和接入相关的问题，优先看 API Keys 和接入文档；需要验证模型对话效果，用模型对话入口；长期跑编码或 Agent 任务，考虑 Coding Plan。把这几件事做到位，你的微信 Bot 就能从「凑合用」变成「稳着跑」。