Skip to main content

微信 (WeChat)

将 Hermes 与 微信（腾讯的个人消息平台）连接。该适配器使用腾讯的 iLink Bot API 来支持个人微信账号 —— 这与企业微信（WeCom）不同。消息通过长轮询方式传递，因此无需公开端点或 Webhook。

info

此适配器仅适用于 个人微信账号（微信）。如需企业/公司级微信，请参阅 企业微信适配器。

前提条件​

  • 一个个人微信账号
  • Python 包：aiohttp 和 cryptography
  • 可选包：qrcode（用于设置过程中在终端中渲染二维码）

安装所需依赖项：

pip install aiohttp cryptography
# Optional: for terminal QR code display
pip install qrcode

设置​

1. 运行设置向导​

最简便的连接微信账号方式是通过交互式设置向导：

hermes gateway setup

提示时选择 微信。向导将执行以下操作：

  1. 向 iLink Bot API 请求二维码
  2. 在终端中显示二维码（或提供 URL）
  3. 等待您使用微信手机 App 扫描二维码
  4. 提示您在手机上确认登录
  5. 自动将账户凭据保存至 ~/.hermes/weixin/accounts/

确认后，您会看到类似如下信息：

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

向导会自动保存 account_id、token 和 base_url，无需手动配置。

2. 配置环境变量​

首次扫码登录后，至少需在 ~/.hermes/.env 中设置账号 ID：

WEIXIN_ACCOUNT_ID=your-account-id

# Optional: override the token (normally auto-saved from QR login)
# WEIXIN_TOKEN=your-bot-token

# Optional: restrict access
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# Optional: home channel for cron/notifications
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home

3. 启动网关​

hermes gateway

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

功能特性​

  • 长轮询传输 —— 无需公开端点、Webhook 或 WebSocket
  • 二维码登录 —— 通过 hermes gateway setup 扫码连接设置
  • 私聊与群组消息 —— 可配置访问策略
  • 媒体支持 —— 图片、视频、文件和语音消息
  • AES-128-ECB 加密 CDN —— 所有媒体传输自动加密/解密
  • 上下文令牌持久化 —— 磁盘存储回复连续性，支持重启后继续
  • Markdown 格式化 —— 标题、表格和代码块会重新格式化以适应微信阅读
  • 智能消息分块 —— 长消息按逻辑边界（段落、代码块）自动拆分
  • 输入状态指示 —— 代理处理时在微信客户端显示“正在输入…”状态
  • SSRF 防护 —— 下载前验证出站媒体 URL
  • 消息去重 —— 5分钟滑动窗口防止重复处理
  • 自动重试带退避机制 —— 可从临时 API 错误中恢复

配置选项​

在 config.yaml 中的 platforms.weixin.extra 下设置以下参数：

键默认值描述
account_id—iLink Bot 账号 ID（必需）
token—iLink Bot Token（必需，由扫码登录自动保存）
base_urlhttps://ilinkai.weixin.qq.comiLink API 基础地址
cdn_base_urlhttps://novac2c.cdn.weixin.qq.com/c2c媒体传输所用 CDN 基础地址
dm_policyopen私聊访问策略：open、allowlist、disabled、pairing
group_policydisabled群组访问策略：open、allowlist、disabled
allow_from[]允许私聊的用户 ID 列表（当 dm_policy=allowlist 时）
group_allow_from[]允许响应的群组 ID 列表（当 group_policy=allowlist 时）

访问策略​

私聊策略​

控制谁可以向机器人发送私聊消息：

值行为
open任何人都可发送私聊（默认）
allowlist仅 allow_from 中列出的用户 ID 可发送
disabled忽略所有私聊消息
pairing配对模式（用于初始设置）
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

群组策略​

控制机器人在哪些群组中响应：

值行为
open机器人在所有群组中响应
allowlist仅在 group_allow_from 列出的群组 ID 中响应
disabled忽略所有群组消息（默认）
WEIXIN_GROUP_POLICY=allowlist
WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2
note

个人微信账号的默认群组策略为 disabled（不同于企业微信默认为 open）。这是有意为之的设计，因为个人微信账号可能加入大量群组。

媒体支持​

入站（接收）​

适配器接收来自用户的媒体附件，从微信 CDN 下载，解密并本地缓存以供代理处理：

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

引用消息：被引用（回复）的消息中的媒体也会被提取，使代理能获取用户回复的上下文。

AES-128-ECB 加密 CDN​

微信媒体文件通过加密 CDN 传输。适配器透明处理此过程：

  • 入站：使用 encrypted_query_param URL 从 CDN 下载加密媒体，然后使用消息负载中提供的每文件密钥，通过 AES-128-ECB 解密。
  • 出站：文件在本地使用随机 AES-128-ECB 密钥加密，上传至 CDN，加密引用包含在出站消息中。
  • AES 密钥长度为 16 字节（128 位）。密钥可能以原始 base64 或十六进制编码形式到达 —— 适配器可自动处理两种格式。
  • 此功能需要 cryptography Python 包。

无需额外配置 —— 加密与解密均自动完成。

出站（发送）​

方法发送内容
send带 Markdown 格式的文本消息
send_image / send_image_file原生图片消息（通过 CDN 上传）
send_document文件附件（通过 CDN 上传）
send_video视频消息（通过 CDN 上传）

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

  1. 生成随机 AES-128 密钥
  2. 使用 AES-128-ECB + PKCS#7 填充加密文件
  3. 向 iLink API 请求上传 URL（getuploadurl）
  4. 将密文上传至 CDN
  5. 发送包含加密媒体引用的消息

上下文令牌持久化​

iLink Bot API 要求每个目标对话必须回传一个 context_token。适配器维护基于磁盘的上下文令牌存储：

  • 每个账号+对话方的令牌保存至 ~/.hermes/weixin/accounts/<account_id>.context-tokens.json
  • 启动时恢复之前保存的令牌
  • 每条入站消息更新对应发送者的存储令牌
  • 出站消息自动包含最新的上下文令牌

这确保了即使网关重启，也能保持回复连续性。

Markdown 格式化​

微信个人聊天不原生支持完整 Markdown。适配器会重新格式化内容以提升可读性：

  • 标题 (# Title) → 转换为 【Title】（一级）或 **Title**（二级及以上）
  • 表格 → 重写为带标签的键值列表（例如 - Column: Value）
  • 代码块 → 保持原样（微信对代码块渲染效果良好）
  • 过多空行 → 合并为双换行

消息分块​

长消息会智能拆分以适配聊天发送：

  • 最大消息长度：4000 个字符
  • 拆分点优先选择段落边界和空行
  • 代码块保持完整（不会中途拆分）
  • 缩进的续行（重格式化表格/列表中的子项）与父项保持在一起
  • 超大单个区块则退回到基础适配器的截断逻辑

输入状态指示​

适配器会在微信客户端中显示“正在输入…”状态：1. 当消息到达时，适配器通过 getconfig API 获取一个 typing_ticket
2. 输入状态（typing）票据按用户缓存 10 分钟
3. send_typing 发送输入开始信号；stop_typing 发送输入结束信号
4. 网关在代理处理消息期间会自动触发输入指示器

长轮询连接​

适配器使用 HTTP 长轮询（非 WebSocket）接收消息：

工作原理​

  1. 连接：验证凭证并启动轮询循环
  2. 轮询：调用 getupdates，设置 35 秒超时；服务器将保持请求打开，直到有消息到达或超时
  3. 分发：入站消息通过 asyncio.create_task 并发分发
  4. 同步缓冲：持久化的同步游标（get_updates_buf）保存至磁盘，确保适配器重启后能从正确位置恢复

重试行为​

遇到 API 错误时，适配器采用简单重试策略：

条件行为
临时错误（第1–2次）2秒后重试
重复错误（第3次及以上）退避30秒，然后重置计数器
会话过期（errcode=-14）暂停10分钟（可能需要重新登录）
超时立即重新轮询（正常长轮询行为）

去重机制​

入站消息基于消息 ID 进行去重，窗口为 5 分钟。这可防止网络波动或重叠轮询响应导致的重复处理。

Token 锁机制​

同一 token 只允许一个 Weixin 网关实例使用。适配器在启动时获取作用域锁，并在关闭时释放。若已有其他网关使用相同 token，启动将失败，并提示明确错误信息。

所有环境变量​

变量必填默认值说明
WEIXIN_ACCOUNT_ID✅—iLink Bot 账号 ID（来自扫码登录）
WEIXIN_TOKEN✅—iLink Bot Token（扫码登录后自动保存）
WEIXIN_BASE_URL—https://ilinkai.weixin.qq.comiLink 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 列表
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
Another local Hermes gateway is already using this Weixin token先停止另一个网关实例——每个 token 只允许一个轮询器
会话已过期（errcode=-14）登录会话已失效。请重新运行 hermes gateway setup 扫描新二维码
设置过程中二维码过期二维码最多自动刷新 3 次。若持续过期，请检查网络连接
机器人不回复私聊消息检查 WEIXIN_DM_POLICY — 若设为 allowlist，发送者必须在 WEIXIN_ALLOWED_USERS 内
机器人忽略群组消息群组策略默认为 disabled。请设置 WEIXIN_GROUP_POLICY=open 或 allowlist
媒体下载/上传失败确保安装了 cryptography。检查对 novac2c.cdn.weixin.qq.com 的网络访问权限
Blocked unsafe URL (SSRF protection)出站媒体 URL 指向私有/内部地址。仅允许公开 URL
语音消息显示为文字若微信提供转录文本，适配器将使用该文本。此为预期行为
消息出现重复适配器基于消息 ID 去重。若仍见重复，请检查是否运行了多个网关实例
iLink POST ... HTTP 4xx/5xxiLink 服务返回 API 错误。请检查 token 有效性及网络连通性
终端二维码无法渲染安装 qrcode：pip install qrcode。或直接打开二维码上方打印的 URL