微信接入无响应？Hermes Agent 网关配置排错指南

当微信接入Hermes Agent后出现消息发送无响应的“静默失败”，往往并非单一原因所致，而是网关连接中断、模型未就绪、会话令牌失效、网络访问受阻或路由规则误配等多重环节协同失守的结果；本文直击五大关键排查维度——从验证网关活跃状态与iLink长连接是否建立，到确认大模型API配置正确性、检查wechat_session.json有效性、测试ilink.bot域名可达性，再到审查config.yaml中微信路由是否被意外禁用或覆盖，提供一套清晰、可执行、逐层递进的排错路径，助你快速定位并击穿看似神秘的“零响应”黑盒。

如果您已完成 Hermes Agent 的微信接入配置，但消息发送后无任何响应，则可能是由于网关未正确连接微信 iLink 服务、模型未就绪或会话令牌失效所致。以下是解决此问题的步骤：

一、验证微信网关是否已成功启动并保持活跃

微信接入依赖 Hermes Gateway 持续运行并与 iLink Bot API 建立长连接；若网关进程意外退出或未启动，将导致所有消息静默丢弃。

1、执行命令查看网关当前状态：hermes gateway status

2、若输出显示 inactive 或无任何进程信息，说明网关未运行。

3、手动启动网关：hermes gateway start

4、立即检查日志确认连接建立：hermes gateway logs --tail 50

5、在日志中查找包含 "ilink connected" 或 "wechat session established" 的行，确认连接成功。

二、检查模型配置是否生效且可调用

微信消息需经 LLM 处理后生成回复；若模型未正确加载或 API Key 无效，网关将跳过推理直接丢弃请求，不报错亦无响应。

1、运行交互式模型检查命令：hermes model test

2、观察输出是否返回有效文本（如“Hello”或模型标识），而非 "Model not recognized" 或空响应。

3、若测试失败，重新执行模型配置：hermes model，确保 Base URL 为 https://dashscope.aliyuncs.com/compatible-mode/v1，API Key 格式为 sk-xxxxxxxxxxxxxxxxxxxxxxxx，默认模型选择 qwen-turbo。

4、配置完成后，强制重载模型设置：hermes setup

三、确认微信会话令牌未过期或损坏

Hermes 在首次扫码登录后会持久化一个会话令牌至 ~/.hermes/wechat_session.json；该文件损坏、权限异常或被误删将导致后续无法鉴权，消息被 iLink 服务拒绝但不反馈错误。

1、检查会话文件是否存在且可读：ls -l ~/.hermes/wechat_session.json

2、若文件不存在或大小为 0，说明登录状态已丢失，需重新扫码绑定。

3、执行微信重配置命令：hermes gateway setup

4、在向导中再次选择 WeChat (ilink / ClawBot)，并完成手机端扫码与确认。

5、成功后，验证新会话文件内容是否含非空 "access_token" 和 "expires_in" 字段。

四、排查网络层对 iLink API 的访问限制

iLink Bot API 服务域名 https://ilink.bot 及其 CDN 资源可能被本地防火墙、代理或 DNS 污染阻断，导致网关无法建立初始握手，表现为日志中持续出现连接超时或 TLS 握手失败。

1、在终端中直接测试 iLink 域名连通性：curl -I -v https://ilink.bot --connect-timeout 5

2、若返回 Failed to connect 或卡在 TLS 阶段，说明网络不通。

3、切换 DNS 尝试（如使用阿里 DNS）：echo "nameserver 223.5.5.5" | sudo tee /etc/resolv.conf

4、关闭系统代理或临时禁用企业级防火墙软件（如 360、火绒）。

5、再次运行 hermes gateway logs --tail 30，确认新日志中出现 "ilink handshake success"。

五、检查微信消息路由规则是否被覆盖或禁用

Hermes 默认启用全消息路由，但若用户手动修改了 ~/.hermes/config.yaml 中的 gateway.wechat.rules 或启用了技能守卫（skills_guard），可能导致消息被静默拦截。

1、打开配置文件：nano ~/.hermes/config.yaml

2、定位到 gateway: 下的 wechat: 区块。

3、确认其中未设置 rules: [] 或 enabled: false。

4、若存在 skills_guard: 配置，临时注释整段并保存文件。

5、重启网关使配置生效：hermes gateway restart

到这里，我们也就讲完了《微信接入无响应？Hermes Agent 网关配置排错指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Hermes Agent,HermesAgent的知识点！