将 Hermes Agent 接入微信
直接在微信里和你的 Hermes Agent 对话。扫描二维码即可连接，支持私信和群聊，所有接入平台共享同一个 AI 上下文。
你能做什么
Hermes Agent 微信网关将本地 Agent 连接到微信——在微信聊天界面里直接使用技能、记忆和所有平台功能。
在微信里直接聊
Hermes Agent 运行在你的机器上，微信只是接口——在任何登录了微信的设备上都能发送消息。
语音和多媒体支持
发送语音、图片、视频或文件，Hermes 会自动接收处理，在条件允许时对语音进行转写。
支持群聊
将 Bot 加入微信群，控制哪些群组可以触发回复。群聊默认关闭，一行配置即可开启。
跨平台共享上下文
Hermes Agent 在所有接入平台之间共享对话记忆。在 Telegram 开始的任务，可以在微信里继续——同一个会话、同一个模型、同一份记忆。
开始之前
运行配置向导前，请确认以下条件已满足。
- ✓Hermes 已安装并正常运行→ /install
- ✓已配置 LLM API→ /models
- ✓拥有微信个人账号（非企业微信）
- ✓依赖已安装：
pip install aiohttp cryptography
配置步骤
安装依赖
aiohttp 和 cryptography aiohttp 和 cryptography 是必须安装的依赖，缺少它们时网关会直接报错并拒绝启动。
qrcode 是可选依赖——如果没有安装，配置向导会打印出一个链接供浏览器扫描。
扫码登录
出现提示后选择 Weixin，向导将：
- 向 iLink Bot API 请求二维码
- 在终端显示二维码（或打印链接供浏览器扫描）
- 等待你用微信 App 扫码
- 等待手机端确认登录
- 自动将凭据保存至 ~/.hermes/weixin/accounts/
确认后你会看到：
account_id、token 和 base_url 均已自动保存，无需手动复制任何内容。
启动网关
适配器会恢复已保存的凭据，连接 iLink API 并开始轮询消息。你应该看到：
打开微信，找到扫码后出现的对话，发一条消息——Bot 会回复一个配对码。
授权访问
默认的私信策略是配对模式。第一次向 Bot 发消息时，它不会直接回复内容，而是返回一个配对码：
在运行 Hermes 的机器上，执行以下命令完成授权：
Bot 会确认授权成功，之后所有消息都会正常回复。每个微信账号只需授权一次。
验证配置
发送以下消息，确认各层功能正常：
| 发送的消息 | 预期结果 |
|---|---|
Hello | Agent 以文字回复 |
| 一条语音消息 | Agent 转写并回复 |
/model | 显示当前模型 |
/skill arxiv | 加载 arxiv 技能 |
如果发送 Hello 没有回复，请确认已完成上方的授权步骤。
微信与 Telegram 的关键区别
微信的配置体验与 Telegram 有一处重要差异。
与 Telegram 不同——Telegram 可以通过 BotFather 创建独立的机器人账号，拥有独立的用户名和对话界面——微信以你的个人账号作为 Bot 入口，每个接入的微信账号只有一个消息入口。
这意味着，想和你的 Hermes Agent 对话的人需要直接给你发微信，或者在你开启了网关的群里发消息。没有单独的「@机器人」可以分享——分享的是你的微信号。
对于多用户场景，私信策略（open / pairing / allowlist）决定了谁可以无需手动审批直接使用 Agent。
常见问题
扫描前二维码一直过期怎么办？
二维码最多自动刷新 3 次。反复过期的常见原因：
- 网络较慢或不稳定——iLink API 在刷新间隔内超时
- 微信扫一扫打开较慢——建议提前打开扫一扫，再运行 setup
如果 3 次都过期，退出后重新运行 hermes gateway setup。
Bot 收到消息但没有任何回复？
原因 A — 配对未完成
如果私信策略是 pairing（默认），Bot 在授权前不会正常回复。检查是否有待审批的配对码：
如果列表中有待审批项，执行授权命令后 Bot 即可正常回复。
原因 B — 模型未配置或 API Key 已过期
微信已将消息传递给 Hermes，但因为 LLM 不可用，Hermes 无法生成回复。这类失败完全静默——微信侧不会显示任何报错。请检查 API 提供商后台确认额度和 Key 状态。
原因 C — 网关未运行
网关需要持续运行才能接收消息。如果终端已关闭，重新运行 hermes gateway 即可。
Bot 忽略群聊消息？
群聊默认关闭。在 ~/.hermes/config.yaml 中添加以下配置并重启网关即可开启：
保存配置后重启网关。
语音消息没有被转写？
Hermes 需要配置语音识别提供商。默认本地方案使用 faster-whisper：
也可以在 ~/.hermes/.env 中配置云端提供商：
什么是 Hermes Agent 微信网关？
Hermes Agent 网关是连接本地 Hermes Agent 与消息平台的进程，支持微信、Telegram、Discord、Slack 和 Signal。微信接入通过 iLink Bot API 进行二维码认证，并长轮询接收消息。
完成配置后运行 hermes gateway 即可启动。网关默认不是后台服务，需要保持终端进程运行，也可以配置为开机自启。
微信会话过一段时间断开？
通过 iLink API 的微信会话偶尔需要重新认证。发生时，重新运行 hermes gateway setup 并扫码即可刷新凭据。
为减少断线，请在稳定网络下运行网关，避免使用频繁切换 IP 的 VPN，否则可能触发微信的安全检测。
高级配置
面向进阶用户的可选配置项。
群聊 @ 触发控制
开启群聊回复后，Hermes 默认响应它能看到的所有消息。如果只想响应 @ 提及或特定前缀触发的消息：
私信访问策略
控制谁可以向你的 Hermes Agent 发私信。在 ~/.hermes/.env 中设置 WEIXIN_DM_POLICY：
多账号支持
Weixin 适配器支持同时接入多个微信账号，每个账号的凭据独立保存在 ~/.hermes/weixin/accounts/ 下。再次运行 hermes gateway setup 即可添加第二个账号。
所有账号共享同一个 Agent 和模型。回复会路由回收到原始消息的那个账号。
跨平台上下文
Hermes 默认在所有接入平台之间维护统一的对话历史。如果你同时运行了 Telegram 网关，微信和 Telegram 的对话会共享同一个会话和记忆。
如需将各平台的会话隔离，在配置中设置 session_scope: platform 即可。
本指南介绍了 Hermes Agent 微信接入方式。同一个网关还支持 Telegram、Discord、Slack 和 Signal。完整配置参考和企业微信支持，请查阅官方文档。