前两篇写了 Hermes Agent 的安装和飞书配置这篇说说怎么接微信。说实话接入个人微信这件事踩坑是大概率事件。微信本身封闭第三方接入方案多多少少都有点灰色地带。Hermes Agent 用的是腾讯官方的 iLink Bot API理论上是最稳的方案但配置过程还是有一些需要注意的地方。重要说明这是个人微信接入不是企业微信。个人微信的 API 限制比较多稳定性也不能跟企业微信比。如果你要的是企业微信请看 WeCom 适配器官方有单独的文档。前提条件Hermes Agent 已安装一个个人微信账号Python 包aiohttp和cryptographypipinstallaiohttp cryptography pipinstallqrcode# 可选用于终端显示二维码工作原理Hermes 通过腾讯的iLink Bot API接入微信用的是长轮询long-polling方式不需要公网地址或 WebSocket。流程大概是手机微信扫码授权Gateway 通过 iLink API 轮询拉取消息处理后通过同一 API 发送回复Step 1: 运行设置向导最简单的方式是用交互式向导hermes gateway setup选「Weixin」向导会请求 iLink Bot API 的二维码在终端显示二维码或提供 URL用微信手机版扫码在手机上确认登录自动保存凭证到~/.hermes/weixin/accounts/扫码成功后显示微信连接成功account_idyour-account-idStep 2: 手动配置如需向导会自动保存凭证但如果需要手动设置编辑~/.hermes/.envWEIXIN_ACCOUNT_IDyour-account-idWEIXIN_TOKENyour-bot-token# 通常向导已自动保存# 可选访问控制WEIXIN_DM_POLICYopen# 私聊策略open/allowlist/disabledWEIXIN_ALLOWED_USERSuser_id_1# 白名单用户WEIXIN_GROUP_POLICYdisabled# 群策略默认禁用避免在所有群里响应WEIXIN_GROUP_ALLOWED_USERSgroup_id_1# 可选首页频道收到 cron 通知的地方WEIXIN_HOME_CHANNELchat_idWEIXIN_HOME_CHANNEL_NAMEHomeStep 3: 启动 Gatewayhermes gateway适配器会恢复保存的凭证连接 iLink API开始长轮询拉取消息。访问控制策略私聊策略WEIXIN_DM_POLICYopen# 任何人可以私聊默认WEIXIN_DM_POLICYallowlist# 只有白名单用户可以私聊WEIXIN_DM_POLICYdisabled# 完全忽略私聊群策略WEIXIN_GROUP_POLICYopen# 所有群都响应WEIXIN_GROUP_POLICYallowlist# 只响应白名单群WEIXIN_GROUP_POLICYdisabled# 忽略所有群消息默认⚠️ 默认禁用群策略因为个人微信可能加了很多群避免刷屏。核心功能接入后支持✅ 长轮询传输不需要公网地址✅ 二维码扫码登录✅ 私聊和群聊✅ 图片、视频、文件、语音消息✅ AES-128-ECB 加密的 CDN 传输✅ 消息上下文记忆跨重启持久化✅ Markdown 格式化会自动转换✅ 智能消息分片长消息自动拆分✅ 打字状态提示✅ SSRF 保护媒体处理接收图片下载后 AES 解密缓存为 JPEG视频下载后 AES 解密缓存为 MP4文件下载后 AES 解密保留原始文件名语音如果有文本 transcription 就用文本否则缓存 SILK 格式音频发送通过加密 CDN 上传生成本地 AES-128 密钥用密钥加密文件上传到微信 CDN发送加密后的媒体引用这些都是自动处理的不需要手动配置。消息格式化微信个人版对 Markdown 支持有限适配器会自动转换# 标题→【标题】## 标题→**标题**表格 → 转换为键值列表代码块 → 保持原样微信渲染还行常见问题Q: Weixin startup failed: aiohttp and cryptography are requiredA: 安装依赖pip install aiohttp cryptographyQ: Weixin startup failed: WEIXIN_TOKEN is requiredA: 重新运行hermes gateway setup完成扫码登录或手动设置WEIXIN_TOKENQ: Another local Hermes gateway is already using this Weixin tokenA: 先停掉另一个 Gateway 实例一个 token 只能被一个实例使用Q: Session expired (errcode-14)A: 登录会话过期重新运行hermes gateway setup扫码Q: QR code expired during setupA: 二维码会自动刷新最多 3 次。如果持续过期检查网络连接Q: Bot doesn’t respond to DMsA: 检查WEIXIN_DM_POLICY如果是allowlist发送者必须在WEIXIN_ALLOWED_USERS里Q: Bot ignores group messagesA: 默认群策略是disabled。设置WEIXIN_GROUP_POLICYopen或allowlistQ: Media download/upload failsA: 确保cryptography已安装。检查网络能否访问novac2c.cdn.weixin.qq.comQ: 终端二维码不显示A: 安装 qrcodepip install qrcode。或者使用向导输出的 URL 在浏览器扫码技术细节长轮询机制每次请求 35 秒超时服务器hold住请求直到有消息或超时入站消息通过 asyncio 并发分发重试策略瞬时错误等2秒重试连续错误等30秒Token 持久化context_token 会保存到~/.hermes/weixin/accounts/.context-tokens.json确保重启后对话连贯。去重5 分钟滑动窗口去重避免网络抖动导致重复处理。写在最后用了一段时间微信通道的稳定性比预期好。但说实话个人微信的 API 限制是硬伤比如不能主动发消息给陌生人、容易被封等。如果你要做正经的客服/助手场景企业微信WeCom方案会更合适。个人微信接入更多是尝鲜或者个人使用。另外提醒微信对第三方接入一直不太友好且用且珍惜。遵守平台规则不要发垃圾消息。系列文章Hermes Agent 安装部署60秒入门这个可成长的AI助手Hermes Agent 配置飞书通道让机器人跑在 Lark 上配置微信通道本文