微信接入失败时,应依次执行:一、运行hermes gateway setup选weixin扫码登录并自动保存凭证;二、若失败则手动编辑~/.hermes/.env填入weixin_account_id和weixin_token;三、执行hermes gateway启动长轮询服务;四、按需配置weixin_dm_policy与weixin_group_policy策略;五、排查ilink api连通性、python版本、依赖及微信客户端限制。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您尝试将 Hermes Agent 接入个人微信作为消息通道,但无法完成登录或收发消息,则可能是由于凭证未正确获取、依赖缺失或环境策略限制。以下是解决此问题的步骤:
一、运行微信配置向导
该方法通过交互式流程自动拉取二维码、完成扫码登录并持久化保存账号凭证,适用于绝大多数用户,避免手动编辑配置文件出错。
1、确保已安装 Hermes 核心程序及必要依赖:执行 sudo apt update && sudo apt install -y python3-qrcode python3-pil(Linux 系统)或 pip install qrcode aiohttp cryptography(其他系统)。
2、在终端中运行配置命令:hermes gateway setup。
3、使用方向键选择「Weixin」,按回车确认。
4、终端将生成并显示微信登录二维码(或提供可访问的 URL 链接)。
5、使用手机微信扫描该二维码,在手机端点击「登录」完成授权。
6、成功后,终端输出类似 微信连接成功,account_id=your-account-id 的提示,并自动将凭证写入 ~/.hermes/weixin/accounts/ 目录。
二、手动配置微信参数
当向导因网络或权限问题失败时,可跳过扫码环节,直接通过环境变量注入已知有效凭证,适用于 CI/CD 或容器化部署场景。
1、确认已拥有有效的 WEIXIN_ACCOUNT_ID 和 WEIXIN_TOKEN(例如来自其他已成功运行的实例或调试日志)。
2、编辑环境配置文件:nano ~/.hermes/.env。
3、添加或修改以下行(注意不加空格、无引号):
WEIXIN_ACCOUNT_ID=your-account-id
WEIXIN_TOKEN=your-bot-token
4、按 Ctrl+O 保存,Ctrl+X 退出编辑器。
5、如需控制消息接收范围,补充以下策略项(可选):
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
WEIXIN_GROUP_POLICY=disabled
三、启动微信网关服务
该步骤触发 Hermes 加载已配置的微信凭证,建立与 iLink Bot API 的长轮询连接,开始实时监听和响应微信消息。
1、确保当前用户对 ~/.hermes/weixin/accounts/ 目录具有读取权限。
微信聊天分析助手 v2.1.0 — 完全本地运行的隐私保护工具。 分析聊天记录,推断 MBTI 与大五人格,检测情感趋势,生成可视化报告。 支持 jieba 精准分词、否定识别、反讽检测、风险预警。 内置 RAG 检索增强预测和多智能体博弈模拟,完全本地化、零数据外传。 可选 MiroFish 群体智能引擎增强对话预测。
2、在终端中执行启动命令:hermes gateway。
3、观察终端输出,确认出现类似 [Weixin] Adapter initialized, polling for messages... 的日志行。
4、此时可在微信中向已登录账号发送任意文本,验证是否收到回复。
四、验证私聊与群聊策略生效
微信通道默认禁用群消息响应,且私聊策略影响谁可发起对话;手动调整策略参数后需重启网关才能生效。
1、检查当前策略配置是否存在于 ~/.hermes/.env 中,例如:
WEIXIN_DM_POLICY=open
WEIXIN_GROUP_POLICY=disabled
2、若需启用指定群组响应,将 WEIXIN_GROUP_POLICY 改为 allowlist,并设置 WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2。
3、修改完成后,先终止正在运行的 hermes gateway 进程(按 Ctrl+C)。
4、重新执行 hermes gateway 启动服务。
5、向白名单中的群组发送测试消息,确认响应被正常处理。
五、排查常见连接失败原因
当启动后无任何消息日志或持续报错时,应逐项检查底层依赖与网络连通性,而非重复运行向导。
1、验证 iLink Bot API 可达性:执行 curl -I https://api.ilink.bot,确认返回 HTTP 200 状态码。
2、检查 Python 版本是否满足要求:运行 python3 --version,确保为 3.9 或更高版本。
3、确认 ~/.hermes/weixin/accounts/ 下存在非空 JSON 文件,且内容包含 account_id 与 refresh_token 字段。
4、若终端报错 ModuleNotFoundError: No module named 'qrcode',说明依赖未全局安装,需补全:pip install qrcode[pil]。
5、若扫码后手机端无反应或提示“该网页可能存在安全风险”,请确认微信版本为最新,并关闭手机端“隐私保护”中的“限制应用后台活动”选项。










