WeCom（企业微信）设置
将 Hermes 连接到 企业微信（企业微信），腾讯的企业消息平台。适配器使用企业微信的 AI Bot WebSocket 网关进行实时双向通信 — 无需公共端点或 webhook。
前置要求
- 企业微信组织账户
- 在企业微信管理后台创建的 AI Bot
- 来自机器人凭证页面的 Bot ID 和 Secret
- Python 包：
aiohttp和httpx
设置
1. 创建 AI Bot
- 登录 企业微信管理后台
- 导航到 应用 → 创建应用 → AI Bot
- 配置机器人名称和描述
- 从凭证页面复制 Bot ID 和 Secret
2. 配置 Hermes
运行交互式设置：
hermes gateway setup
选择 WeCom 并输入你的 Bot ID 和 Secret。
或在 ~/.hermes/.env 中设置环境变量：
WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret
# 可选：限制访问
WECOM_ALLOWED_USERS=user_id_1,user_id_2
# 可选：用于 cron/通知的主频道
WECOM_HOME_CHANNEL=chat_id
3. 启动网关
hermes gateway
功能
- WebSocket 传输 — 持久连接，无需公共端点
- DM 和群组消息 — 可配置的访问策略
- 每群发件人白名单 — 对每个群中可交互用户的细粒度控制
- 媒体支持 — 图片、文件、语音、视频上传和下载
- AES 加密媒体 — 入站附件自动解密
- 引用上下文 — 保留回复线程
- Markdown 渲染 — 富文本响应
- 回复模式流式响应 — 将响应关联到入站消息上下文
- 自动重连 — 连接断开时指数退避
访问策略
DM 策略
控制谁可以向机器人发送直接消息：
| 值 | 行为 |
|---|---|
open | 任何人都可以 DM 机器人（默认） |
allowlist | 只有 allow_from 中的用户 ID 可以 DM |
disabled | 所有 DM 都被忽略 |
pairing | 配对模式（用于初始设置） |
群组策略
控制机器人在哪些群组中响应：
| 值 | 行为 |
|---|---|
open | 机器人在所有群组中响应（默认） |
allowlist | 机器人仅在 group_allow_from 中列出的群组 ID 中响应 |
disabled | 所有群组消息都被忽略 |
媒体支持
入站（接收）
适配器接收用户的媒体附件并将其本地缓存以供 agent 处理：
| 类型 | 处理方式 |
|---|---|
| 图片 | 下载并本地缓存。支持基于 URL 和 base64 编码的图片。 |
| 文件 | 下载并缓存。保留原始消息中的文件名。 |
| 语音 | 如果可用，提取语音消息文本转录。 |
| 混合消息 | 解析企业微信混合类型消息（文本 + 图片）并提取所有组件。 |
AES 加密媒体解密
企业微信使用 AES-256-CBC 加密某些入站媒体附件。适配器自动处理：
- 当入站媒体项目包含
aeskey字段时，适配器下载加密字节并使用 PKCS#7 填充的 AES-256-CBC 解密 - AES 密钥是
aeskey字段的 base64 解码值（必须恰好 32 字节） - IV 源自密钥的前 16 字节
- 这需要
cryptographyPython 包（pip install cryptography）
无需配置 — 当接收到加密媒体时解密自动进行。
出站（发送）
| 方法 | 发送内容 | 大小限制 |
|---|---|---|
send | Markdown 文本消息 | 4000 字符 |
send_image / send_image_file | 原生图片消息 | 10 MB |
send_document | 文件附件 | 20 MB |
send_voice | 语音消息（仅支持 AMR 格式原生语音） | 2 MB |
send_video | 视频消息 | 10 MB |
连接与重连
适配器维护到企业微信网关 wss://openws.work.weixin.qq.com 的持久 WebSocket 连接。
重连行为
连接丢失时，适配器使用指数退避重连：
| 尝试 | 延迟 |
|---|---|
| 第 1 次重试 | 2 秒 |
| 第 2 次重试 | 5 秒 |
| 第 3 次重试 | 10 秒 |
| 第 4 次重试 | 30 秒 |
| 第 5 次+ 重试 | 60 秒 |
每次成功重连后，退避计数器重置为零。所有待处理请求 futures 在断开连接时失败，以免调用者无限期挂起。
所有环境变量
| 变量 | 必填 | 默认值 | 描述 |
|---|---|---|---|
WECOM_BOT_ID | ✅ | — | 企业微信 AI Bot ID |
WECOM_SECRET | ✅ | — | 企业微信 AI Bot Secret |
WECOM_ALLOWED_USERS | — | (空) | 网关级白名单的逗号分隔用户 ID |
WECOM_HOME_CHANNEL | — | — | 用于 cron/通知输出的聊天 ID |
WECOM_WEBSOCKET_URL | — | wss://openws.work.weixin.qq.com | WebSocket 网关 URL |
WECOM_DM_POLICY | — | open | DM 访问策略 |
WECOM_GROUP_POLICY | — | open | 群组访问策略 |
故障排除
| 问题 | 修复 |
|---|---|
WECOM_BOT_ID 和 WECOM_SECRET 是必需的 | 设置两个环境变量或在设置向导中配置 |
WeCom 启动失败：aiohttp 未安装 | 安装 aiohttp：pip install aiohttp |
WeCom 启动失败：httpx 未安装 | 安装 httpx：pip install httpx |
无效 secret (errcode=40013) | 验证 secret 与你的机器人凭证匹配 |
等待订阅确认超时 | 检查到 openws.work.weixin.qq.com 的网络连接 |
| 机器人在群组中不响应 | 检查 group_policy 设置并确保群组 ID 在 group_allow_from 中 |
| 媒体解密失败 | 安装 cryptography：pip install cryptography |
| 语音消息作为文件发送 | 企业微信仅原生语音支持 AMR 格式。其他格式自动降级为文件。 |
文件太大 错误 | 企业微信对所有文件上传有 20 MB 绝对限制。压缩或分割文件。 |