微信（WeChat）
将 Hermes 连接到微信（WeChat），腾讯的个人消息平台。该适配器使用腾讯的 iLink Bot API 用于个人微信账号——这不同于企业微信。消息通过长轮询投递，因此无需公共端点或 webhook。
:::info 此适配器用于个人微信账号（微信）。如果您需要企业微信，请参阅企业微信适配器。 :::
:::warning iLink 机器人身份——普通微信群可能不工作
二维码登录将 Hermes 连接到一个 iLink 机器人身份（例如 a5ace6fd482e@im.bot），而非完全可脚本化的普通个人微信账号。后果：
- iLink 机器人身份通常无法像普通联系人那样被邀请进入普通的微信群。
- iLink 通常不会将普通微信群事件（包括用于二维码登录的个人账号的
@提及）投递到网关（对于大多数机器人类型账号）。 @提及用于扫描二维码的个人微信账号不同于@提及 iLink 机器人——机器人是一个独立的身份。- 下面的
WEIXIN_GROUP_POLICY/WEIXIN_GROUP_ALLOWED_USERS设置仅当 iLink 实际为您的账号类型返回群事件时才会生效。如果不返回，无论策略如何，群消息永远不会到达 Hermes。
实际上，大多数部署只能可靠地让 iLink 机器人的私聊正常工作。如果配置后群投递不工作，限制在于 iLink 方面，而非 Hermes。每当 WEIXIN_GROUP_POLICY 设置为非 disabled 的值时，网关在启动时会记录一条 WARNING。
:::
前提条件
- 一个个人微信账号
- Python 包：
aiohttp和cryptography - 当使用
messaging附加组件安装 Hermes 时，终端二维码渲染包含在内
安装所需的依赖：
pip install aiohttp cryptography
# 可选：用于终端二维码显示
pip install hermes-agent[messaging]设置
1. 运行设置向导
连接您的微信账号最简单的方式是通过交互式设置：
hermes gateway setup按提示选择 微信。向导将：
- 从 iLink Bot API 请求二维码
- 在终端显示二维码（或提供 URL）
- 等待您使用微信手机应用扫描二维码
- 提示您在手机上确认登录
- 自动将账号凭证保存到
~/.hermes/weixin/accounts/
确认后，您会看到类似这样的消息：
微信连接成功，account_id=your-account-id
向导会存储 account_id、token 和 base_url，因此您无需手动配置。
2. 配置环境变量
初始二维码登录后，至少在 ~/.hermes/.env 中设置账号 ID：
WEIXIN_ACCOUNT_ID=your-account-id
# 可选：覆盖令牌（通常在二维码登录时自动保存）
# WEIXIN_TOKEN=your-bot-token
# 可选：限制访问
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
# 可选：恢复旧版多行分割行为
# WEIXIN_SPLIT_MULTILINE_MESSAGES=true
# 可选：定时任务/通知的家聊
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home3. 启动网关
hermes gateway适配器将恢复保存的凭证，连接到 iLink API，并开始长轮询消息。
功能
- 长轮询传输 — 无需公共端点、webhook 或 WebSocket
- 二维码登录 — 通过
hermes gateway setup扫码连接设置 - 私聊 — 可配置的访问策略；群聊取决于 iLink 是否实际为连接的身份投递群事件（对于 iLink 机器人账号通常不会——请参见上面的警告）
- 媒体支持 — 图片、视频、文件和语音消息
- AES-128-ECB 加密 CDN — 所有媒体传输的自动加密/解密
- 上下文令牌持久化 — 重启后基于磁盘的回复连续性
- Markdown 格式化 — 保留 Markdown，包括标题、表格和代码块，因此支持 Markdown 的微信客户端可以原生渲染
- 智能消息分块 — 消息在限制以下时保持为单个气泡；仅在超限时在逻辑边界拆分
- 输入指示器 — 在代理处理时在微信客户端显示”正在输入…”状态
- SSRF 保护 — 出站媒体 URL 在下载前经过验证
- 消息去重 — 5 分钟滑动窗口防止重复处理
- 带退避的自动重试 — 从临时 API 错误中恢复
配置选项
在 config.yaml 的 platforms.weixin.extra 下设置：
| 键 | 默认值 | 描述 |
|---|---|---|
account_id | — | iLink 机器人账号 ID（必填） |
token | — | iLink 机器人令牌（必填，从二维码登录自动保存） |
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（当 dm_policy=allowlist 时） |
group_allow_from | [] | 允许的群 ID（当 group_policy=allowlist 时） |
split_multiline_messages | false | 当为 true 时，将多行回复拆分为多条聊天消息（旧版行为）。当为 false 时，将多行回复保留为一条消息，除非超过长度限制。 |
访问策略
私聊策略
控制谁可以向机器人发送直接消息：
| 值 | 行为 |
|---|---|
open | 任何人都可以私聊机器人（默认） |
allowlist | 只有 allow_from 中的用户 ID 可以私聊 |
disabled | 忽略所有私聊 |
pairing | 配对模式（用于初始设置） |
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2群策略
控制当 iLink 为连接的身份投递群事件时，机器人在哪些群中响应。对于二维码登录的 iLink 机器人身份（例如 ...@im.bot），群事件通常根本不会投递，因此此策略可能无效——请参见页面顶部的 iLink 机器人限制警告。
| 值 | 行为 |
|---|---|
open | 机器人在所有群中响应（如果事件被投递） |
allowlist | 机器人仅在 group_allow_from 中列出的群 ID 中响应（如果事件被投递） |
disabled | 忽略所有群消息（默认） |
WEIXIN_GROUP_POLICY=allowlist
# 注意：这是一个逗号分隔的群聊 ID 列表，不是成员用户 ID，
# 尽管变量名包含"USERS"。配置时请记住这一点。
WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2:::note
微信的默认群策略是 disabled（不同于企业微信默认的 open）。这是有意为之的——个人微信账号可能加入许多群，而 iLink 机器人身份通常根本无法接收普通微信群消息。如果您将 WEIXIN_GROUP_POLICY 设置为非 disabled 的值，网关在启动时会记录一条 WARNING。
:::
媒体支持
入站（接收）
适配器接收来自用户的媒体附件，从微信 CDN 下载，解密，并在本地缓存以供代理处理：
| 类型 | 处理方式 |
|---|---|
| 图片 | 下载、AES 解密并缓存为 JPEG。 |
| 视频 | 下载、AES 解密并缓存为 MP4。 |
| 文件 | 下载、AES 解密并缓存。保留原始文件名。 |
| 语音 | 如果有文本转录，提取为文本。否则，下载并缓存音频（SILK 格式）。 |
引用消息： 引用（回复）消息中的媒体也会被提取，因此代理拥有用户回复的上下文。
AES-128-ECB 加密 CDN
微信媒体文件通过加密 CDN 传输。适配器透明地处理此过程：
- 入站： 使用
encrypted_query_paramURL 从 CDN 下载加密媒体，然后使用消息负载中提供的每文件密钥通过 AES-128-ECB 解密。 - 出站： 文件使用随机 AES-128-ECB 密钥在本地加密，上传到 CDN，加密引用包含在出站消息中。
- AES 密钥为 16 字节（128 位）。密钥可能以原始 base64 或十六进制编码到达——适配器处理两种格式。
- 这需要
cryptographyPython 包。
无需配置——加密和解密自动发生。
出站（发送）
| 方法 | 发送内容 |
|---|---|
send | 带 Markdown 格式的文本消息 |
send_image / send_image_file | 原生图片消息（通过 CDN 上传） |
send_document | 文件附件（通过 CDN 上传） |
send_video | 视频消息（通过 CDN 上传） |
所有出站媒体都经过加密 CDN 上传流程：
- 生成随机 AES-128 密钥
- 使用 AES-128-ECB + PKCS#7 填充加密文件
- 从 iLink API 请求上传 URL（
getuploadurl） - 将密文上传到 CDN
- 发送带有加密媒体引用的消息
上下文令牌持久化
iLink Bot API 要求对等方的每条出站消息都要回显一个 context_token。适配器维护一个基于磁盘的上下文令牌存储：
- 令牌按账号+对等方保存到
~/.hermes/weixin/accounts/<account_id>.context-tokens.json - 启动时，恢复之前保存的令牌
- 每条入站消息更新该发送者的已存储令牌
- 出站消息自动包含最新的上下文令牌
这确保了即使在网关重启后也能保持回复连续性。
Markdown 格式化
通过 iLink Bot API 连接的微信客户端可以直接渲染 Markdown，因此适配器保留 Markdown 而不是重写它：
- 标题 保留为 Markdown 标题（
#、##、…） - 表格 保留为 Markdown 表格
- 代码围栏 保留为围栏代码块
- 过多的空行 会在围栏代码块外部折叠为双换行
消息分块
消息只要在平台限制范围内就以单条聊天消息投递。只有超限的负载才会被拆分投递：
- 最大消息长度：4000 字符
- 限制以下的消息即使包含多个段落或换行也保持完整
- 超限消息在逻辑边界（段落、空行、代码围栏）处拆分
- 代码围栏尽可能保持完整（除非围栏本身超过限制，否则永不中断拆分）
- 超限的单个块回退到基础适配器的截断逻辑
- 发送多个块时，块间 0.3 秒的延迟防止微信速率限制丢��
输入指示器
适配器在微信客户端显示输入状态：
- 消息到达时，适配器通过
getconfigAPI 获取typing_ticket - 输入票据按用户缓存 10 分钟
send_typing发送开始输入信号；stop_typing发送停止输入信号- 网关在代理处理消息时自动触发输入指示器
长轮询连接
适配器使用 HTTP 长轮询（而非 WebSocket）接收消息：
工作原理
- 连接： 验证凭证并开始轮询循环
- 轮询： 调用
getupdates，超时 35 秒；服务器保持请求直到消息到达或超时到期 - 分发： 入站消息通过
asyncio.create_task并发分发 - 同步缓冲区： 持久化的同步游标（
get_updates_buf）保存到磁盘，以便适配器在重启后从正确位置恢复
重试行为
API 错误时，适配器使用简单的重试策略：
| 条件 | 行为 |
|---|---|
| 临时错误（第 1-2 次） | 2 秒后重试 |
| 重复错误（第 3 次及以上） | 退避 30 秒，然后重置计数器 |
会话过期（errcode=-14） | 暂停 10 分钟（可能需要重新登录） |
| 超时 | 立即重新轮询（正常的长轮询行为） |
去重
入站消息使用消息 ID 去重，5 分钟窗口。这可以防止在网络故障或重叠的轮询响应期间重复处理。
令牌锁定
同一时间只能有一个微信网关实例使用给定的令牌。适配器在启动时获取一个作用域锁，并在关闭时释放。如果另一个网关已经在使用相同的令牌，启动时会失败并显示一条信息性错误消息。
所有环境变量
| 变量 | 必填 | 默认值 | 描述 |
|---|---|---|---|
WEIXIN_ACCOUNT_ID | ✅ | — | iLink 机器人账号 ID（来自二维码登录） |
WEIXIN_TOKEN | ✅ | — | iLink 机器人令牌（从二维码登录自动保存） |
WEIXIN_BASE_URL | — | https://ilinkai.weixin.qq.com | iLink API 基础 URL |
WEIXIN_CDN_BASE_URL | — | https://novac2c.cdn.weixin.qq.com/c2c | 媒体传输的 CDN 基础 URL |
WEIXIN_DM_POLICY | — | open | 私聊访问策略：open、allowlist、disabled、pairing |
WEIXIN_GROUP_POLICY | — | disabled | 群访问策略：open、allowlist、disabled |
WEIXIN_ALLOWED_USERS | — | (空) | 逗号分隔的私聊白名单用户 ID |
WEIXIN_GROUP_ALLOWED_USERS | — | (空) | 逗号分隔的群聊 ID（不是成员用户 ID），用于群白名单。变量名是旧版——它期望群 ID，而非用户 ID。 |
WEIXIN_HOME_CHANNEL | — | — | 定时任务/通知输出的聊天 ID |
WEIXIN_HOME_CHANNEL_NAME | — | Home | 家聊的显示名称 |
WEIXIN_ALLOW_ALL_USERS | — | — | 网关级别标志，允许所有用户（由设置向导使用） |
故障排查
| 问题 | 解决方法 |
|---|---|
Weixin startup failed: aiohttp and cryptography are required | 安装两者：pip install aiohttp cryptography |
Weixin startup failed: WEIXIN_TOKEN is required | 运行 hermes gateway setup 完成二维码登录，或手动设置 WEIXIN_TOKEN |
Weixin startup failed: WEIXIN_ACCOUNT_ID is required | 在 .env 中设置 WEIXIN_ACCOUNT_ID 或运行 hermes gateway setup |
另一个本地 Hermes 网关正在使用此微信令牌 | 先停止另一个网关实例——每个令牌只允许一个轮询器 |
会话过期（errcode=-14） | 您的登录会话已过期。重新运行 hermes gateway setup 以扫描新二维码 |
| 设置期间二维码过期 | 二维码最多自动刷新 3 次。如果持续过期，请检查您的网络连接 |
| 机器人不回复私聊 | 检查 WEIXIN_DM_POLICY——如果设置为 allowlist，发送者必须在 WEIXIN_ALLOWED_USERS 中 |
| 机器人忽略群消息 | 群策略默认为 disabled。设置 WEIXIN_GROUP_POLICY=open 或 allowlist——但请注意，二维码登录的 iLink 机器人身份（...@im.bot）通常根本无法接收普通微信群消息。如果网关日志未显示群消息的原始入站事件，限制在于 iLink 方面，而非 Hermes。 |
| 媒体下载/上传失败 | 确保已安装 cryptography。检查到 novac2c.cdn.weixin.qq.com 的网络访问 |
阻止了不安全的 URL（SSRF 保护） | 出站媒体 URL 指向私有/内部地址。只允许公共 URL |
| 语音消息显示为文本 | 如果微信提供转录，适配器使用文本。这是预期行为 |
| 消息出现重复 | 适配器通过消息 ID 去重。如果看到重复，请检查是否有多个网关实例在运行 |
iLink POST ... HTTP 4xx/5xx | iLink 服务的 API 错误。检查您的令牌有效性和网络连通性 |
| 终端二维码不渲染 | 使用 messaging 附加组件重新安装：pip install hermes-agent[messaging]。或者，打开二维码上方打印的 URL |