Hermes Agent 接入个人微信（WeChat）完整指南

前言

Hermes Agent 是一个开源 AI 代理框架，支持通过网关（Gateway）接入 20+ 消息平台，包括个人微信。本文将详细介绍从零开始将 Hermes 连接到你的微信账号的全流程，亲测可用。

本文基于 Hermes Agent 官方 v2.x 版本编写。官方文档：https://hermes-agent.nousresearch.com/docs

一、前置条件

在开始前，请确保满足以下条件：

条件	说明
一个个人微信账号	用于扫码登录
Hermes Agent 已安装	确保 `hermes` 命令可用
Python 依赖	`aiohttp`、`cryptography`、`qrcode`

检查并安装依赖：

sh
pip install aiohttp cryptography qrcode

二、配置步骤

2.1 运行配置向导

Hermes 提供了交互式配置向导，一键完成微信接入：

sh
hermes gateway setup

在菜单中选择 Weixin / WeChat（找到对应序号输入）。

向导会自动完成以下步骤：

向腾讯 iLink Bot API 请求二维码
在终端显示二维码（并提供 URL 备用）
等待你用手机微信扫码
提示在手机上确认登录
自动保存账号凭据

扫码确认后，你会看到类似输出：


微信连接成功，account_id=xxxxxx@im.bot

什么是 iLink Bot？ 微信适配器使用的是腾讯官方的 iLink Bot API，扫码后创建一个 bot 身份。这个身份以 @im.bot 结尾，不是你的个人微信号本身。

2.2 验证凭据

登录成功后，凭据会自动保存在以下位置：

sh
ls ~/.hermes/weixin/accounts/
# 输出示例: c21e7890e3ae@im.bot.json

查看凭据内容：

json
{
  "token": "...",
  "base_url": "https://ilinkai.weixin.qq.com",
  "user_id": "...@im.wechat",
  "saved_at": "2026-07-18T05:58:27Z"
}

同时 ~/.hermes/.env 中会自动写入环境变量：

sh
WEIXIN_ACCOUNT_ID=c21e7890e3ae@im.bot
WEIXIN_TOKEN=...
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com

三、启动网关

3.1 启动

确保微信配置就绪后，启动 Hermes 网关：

sh
hermes gateway run

网关启动后会自动长轮询微信消息。正常情况下日志会显示：


[gateway] ready
[Weixin] Connected

3.2 验活

用手机微信给 bot 发一条消息。如果配置正确，Hermes 会收到消息并回复。

首次消息会触发配对流程——Hermes 会返回一个配对码，需要在终端批准：

sh
hermes pairing approve weixin <PAIRING_CODE>

批准后，你的微信账号就与 Hermes 绑定了，后续消息自动响应。

四、额外配置

4.1 设置 Home Channel

Home Channel 是 Hermes 发送定时任务结果、跨平台消息的默认聊天窗口。在微信中回复：


/sethome

或直接在 .env 中配置：

sh
WEIXIN_HOME_CHANNEL=your_user_id@im.wechat
WEIXIN_HOME_CHANNEL_NAME=Home

4.2 访问策略

你可以控制谁可以向 bot 发消息：

sh
# 只允许指定用户
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

策略	说明
`open`	任何人可发私信（默认）
`allowlist`	仅白名单用户
`disabled`	关闭私信
`pairing`	配对模式

五、功能特性

支持的功能

功能	说明
私信聊天	✅ 支持
群聊	⚠️ 有限制（见下方）
图片消息	✅ 支持收发
视频消息	✅ 支持收发
文件消息	✅ 支持收发
语音消息	✅ 支持（有文字转录则提取）
Markdown 回复	✅ 自动格式化
输入状态提示	✅ 显示"正在输入…"

架构特点

长轮询传输：无需公网 IP 或 webhook
AES-128-ECB 加密 CDN：所有媒体传输自动加解密
消息去重：5 分钟滑动窗口
自动重试与退避：从瞬时错误恢复

六、注意事项与限制

⚠️ iLink Bot 身份限制

扫码登录后连接的是 iLink bot 身份（xxx@im.bot），而非你的个人微信号。这意味着：

不能加入普通微信群：bot 身份无法像普通联系人一样被邀请进群
群消息基本不可用：iLink 通常不向 bot 推送群事件
@ 提及自己 vs @ 提及 bot：在群里 @ 你自己的微信号 ≠ @ bot
私信（DM）是主要使用方式：私信功能完全正常

其他限制

需要电脑保持 Hermes gateway 运行
依赖 iLink API 的可用性
媒体文件有大小限制（受 CDN 限制）

七、常见问题

Q: 扫码后提示"已过期"怎么办？

重新运行 hermes gateway setup 重新扫码。

Q: 收不到微信消息？

确保 gateway 正在运行，检查日志：

sh
grep weixin ~/.hermes/logs/gateway.log | tail -20

Q: 想要连接多个微信账号？

重复运行 hermes gateway setup 并选择 Weixin，或者查看官方文档的 multi-account 配置。

Q: 和 OpenClaw 的微信方案有什么区别？

Hermes 使用的是腾讯官方的 iLink Bot API，而 OpenClaw 使用相同的底层协议但需额外安装插件。Hermes 原生内置支持，开箱即用。

八、总结

Hermes Agent 接入微信的整体流程非常简洁：

装依赖 → 2. 运行 hermes gateway setup 扫码 → 3. 启动 gateway → 4. 配对批准 → 完成

整个过程只需几分钟，无需公网服务器、无需 webhook、无需额外插件。Hermes 的原生支持让微信集成变得轻松高效。

目录