微信配置

通过微信适配器，Hermes Agent 可以连接你的个人微信账户。适配器使用腾讯 iLink Bot API，通过长轮询传输消息 — 无需公网端点或 Webhook。

iLink Bot 身份限制

QR 登录连接的是 iLink Bot 身份（如 [email protected]），而非完全可编程的普通个人微信账户。后果：

iLink Bot 身份通常无法像普通联系人那样被邀请进入普通微信群
iLink 通常不会为大多数 Bot 类型账户传送普通微信群事件
@提及用于扫码登录的个人微信号不等于 @提及 iLink Bot — Bot 是独立身份
WEIXIN_GROUP_POLICY / WEIXIN_GROUP_ALLOWED_USERS 设置仅在 iLink 实际返回群事件时才生效

前置条件

一个个人微信账户
Python 包：aiohttp 和 cryptography
终端 QR 码渲染（安装 hermes-agent[messaging] 时包含）

pip install aiohttp cryptography
# 可选：终端 QR 码显示
pip install hermes-agent[messaging]

设置步骤

1. 运行设置向导

连接微信最简单的方式是通过交互式设置：

hermes gateway setup

选择 Weixin，向导会：

从 iLink Bot API 请求 QR 码
在终端显示 QR 码（或提供 URL）
等待你用微信手机 App 扫码
提示你在手机上确认登录
自动将账户凭据保存到 ~/.hermes/weixin/accounts/

确认后你会看到：

微信连接成功，account_id=your-account-id

2. 配置环境变量

初始 QR 登录后，至少需要在 ~/.hermes/.env 中设置账户 ID：

WEIXIN_ACCOUNT_ID=your-account-id

# 可选：覆盖 token（通常自动保存自 QR 登录）
# WEIXIN_TOKEN=your-bot-token

# 可选：限制访问
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# 可选：主频道（用于定时任务/通知）
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home

3. 启动网关

hermes gateway

适配器将恢复已保存的凭据，连接到 iLink API，并开始长轮询消息。

功能特性

长轮询传输 — 无需公网端点、Webhook 或 WebSocket
QR 码登录 — 通过 hermes gateway setup 扫码即连
私信 — 可配置访问策略；群组消息取决于 iLink 是否传送群事件
媒体支持 — 图片、视频、文件和语音消息
AES-128-ECB 加密 CDN — 自动加密/解密所有媒体传输
上下文 Token 持久化 — 磁盘支持的跨重启回复连续性
Markdown 格式 — 保留 Markdown 格式（标题、表格、代码块）
智能消息分块 — 不超限时保持单条消息，超大内容按逻辑边界拆分
输入指示 — Agent 处理时显示”正在输入…”状态
SSRF 防护 — 出站媒体 URL 下载前验证
消息去重 — 5 分钟滑动窗口防止重复处理
自动重试 — 从临时 API 错误中恢复

配置选项

在 config.yaml 的 platforms.weixin.extra 下设置：

键	默认值	说明
`account_id`	—	iLink Bot 账户 ID（必填）
`token`	—	iLink Bot Token（必填，QR 登录自动保存）
`base_url`	`https://ilinkai.weixin.qq.com`	iLink API 基础 URL
`cdn_base_url`	`https://novac2c.cdn.weixin.qq.com/c2c`	CDN 基础 URL
`dm_policy`	`open`	私信策略：open/allowlist/disabled/pairing
`group_policy`	`disabled`	群组策略：open/allowlist/disabled
`allow_from`	[]	私信白名单用户 ID
`group_allow_from`	[]	群组白名单 ID
`split_multiline_messages`	false	是否将多行回复拆分为多条消息

访问策略

私信策略

值	行为
`open`	任何人都可以私信 Bot（默认）
`allowlist`	仅白名单中的用户 ID 可私信
`disabled`	忽略所有私信
`pairing`	配对模式（用于初始设置）

WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

群组策略

值	行为
`open`	Bot 在所有群组中响应（如果事件被投递）
`allowlist`	仅在白名单群组 ID 中响应
`disabled`	忽略所有群组消息（默认）

WEIXIN_GROUP_POLICY=allowlist
WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2

媒体处理

接收（入站）

适配器接收用户发送的媒体附件，从微信 CDN 下载、解密并缓存到本地供 Agent 处理：

类型	处理方式
图片	下载、AES 解密、缓存为 JPEG
视频	下载、AES 解密、缓存为 MP4
文件	下载、AES 解密、缓存，保留原始文件名
语音	如有文字转录则提取文本，否则下载 SILK 格式音频缓存

发送（出站）

所有出站媒体通过加密 CDN 上传流程：

生成随机 AES-128 密钥
用 AES-128-ECB + PKCS#7 填充加密文件
从 iLink API 获取上传 URL
上传密文到 CDN
发送包含加密媒体引用的消息

常见问题排查

问题	解决方法
启动失败：需要 aiohttp 和 cryptography	安装：`pip install aiohttp cryptography`
启动失败：需要 WEIXIN_TOKEN	运行 `hermes gateway setup` 完成 QR 登录
启动失败：需要 WEIXIN_ACCOUNT_ID	在 `.env` 中设置或运行 `hermes gateway setup`
另一个本地网关已在使用此 Token	先停止另一个网关实例 — 每个 Token 只允许一个轮询器
会话过期 (errcode=-14)	登录会话已过期，重新运行 `hermes gateway setup` 扫码
QR 码设置中过期	QR 自动刷新最多 3 次，反复过期请检查网络
Bot 不回复私信	检查 `WEIXIN_DM_POLICY` — 如设为 allowlist，发送者必须在白名单中
Bot 忽略群组消息	群组策略默认为 disabled。设置 `WEIXIN_GROUP_POLICY=open` — 但注意 iLink Bot 身份通常无法接收普通微信群消息
媒体下载/上传失败	确保 cryptography 已安装，检查到 `novac2c.cdn.weixin.qq.com` 的网络
终端 QR 码不显示	安装消息组件：`pip install hermes-agent[messaging]`，或打开 QR 上方打印的 URL