企业微信 (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

选择 企业微信，并输入您的 Bot ID 和 Secret。

或者在 ~/.hermes/.env 中设置环境变量：

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

# Optional: restrict access
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# Optional: home channel for cron/notifications
WECOM_HOME_CHANNEL=chat_id

3. 启动网关

hermes gateway

功能特性

WebSocket 传输 —— 持久连接，无需公网暴露
私聊与群聊支持 —— 可配置访问策略
按群组发送者白名单 —— 细粒度控制每个群组中的互动权限
媒体文件支持 —— 支持图片、文件、语音、视频的上传与下载
AES 加密媒体自动解密 —— 对接收到的附件自动解密
引用上下文保留 —— 保持回复的对话线程结构
Markdown 渲染 —— 支持富文本响应
回复模式流式输出 —— 将响应与原始消息上下文关联
自动重连机制 —— 断开后采用指数退避重连

配置选项

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

键	默认值	说明
`bot_id`	—	企业微信 AI Bot ID（必填）
`secret`	—	企业微信 AI Bot Secret（必填）
`websocket_url`	`wss://openws.work.weixin.qq.com`	WebSocket 网关地址
`dm_policy`	`open`	私聊访问策略：`open`, `allowlist`, `disabled`, `pairing`
`group_policy`	`open`	群组访问策略：`open`, `allowlist`, `disabled`
`allow_from`	`[]`	允许私聊的用户 ID 列表（当 dm_policy=allowlist 时生效）
`group_allow_from`	`[]`	允许互动的群组 ID 列表（当 group_policy=allowlist 时生效）
`groups`	`{}`	按群组的独立配置（见下文）

访问策略

私聊策略（DM Policy）

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

值	行为
`open`	任何人都可发送私聊（默认）
`allowlist`	仅允许 `allow_from` 列表中的用户发送私聊
`disabled`	忽略所有私聊消息
`pairing`	配对模式（用于初始设置）

WECOM_DM_POLICY=allowlist

群组策略（Group Policy）

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

值	行为
`open`	机器人在所有群组中响应（默认）
`allowlist`	仅在 `group_allow_from` 列表中的群组中响应
`disabled`	忽略所有群组消息

WECOM_GROUP_POLICY=allowlist

按群组发送者白名单

为实现更精细的控制，可限制特定群组内哪些用户能与机器人互动。此配置位于 config.yaml 中：

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      group_policy: "allowlist"
      group_allow_from:
        - "group_id_1"
        - "group_id_2"
      groups:
        group_id_1:
          allow_from:
            - "user_alice"
            - "user_bob"
        group_id_2:
          allow_from:
            - "user_charlie"
        "*":
          allow_from:
            - "user_admin"

工作原理：

group_policy 和 group_allow_from 控制某个群组是否被允许。
若群组通过了顶层检查，则 groups.<group_id>.allow_from 列表（如存在）会进一步限制该群组内的可互动用户。
通配符 "*" 的群组条目作为未显式列出的群组的默认规则。
白名单条目支持 * 通配符以允许所有用户，且条目不区分大小写。
条目可选地使用 wecom:user: 或 wecom:group: 前缀格式——前缀会被自动剥离。

若某群组未配置 allow_from，则只要该群组通过了顶层策略检查，其所有成员均被允许互动。

媒体支持

入站（接收）

适配器接收来自用户的媒体附件，并本地缓存以供代理处理：

类型	处理方式
图片	下载并本地缓存。支持 URL 和 base64 编码的图片。
文件	下载并缓存。文件名保留原始消息中的名称。
语音	若可用，提取语音转文字内容。
混合消息	解析企业微信的混合类型消息（文本+图片），提取所有组件。

引用消息： 被引用（回复）的消息中的媒体也会被提取，使代理能够了解用户正在回复的内容。

AES 加密媒体自动解密

企业微信会对部分入站媒体附件进行 AES-256-CBC 加密。适配器会自动处理：

当接收到的媒体项包含 aeskey 字段时，适配器会下载加密数据，并使用 AES-256-CBC（PKCS#7 填充）进行解密。
AES 密钥为 aeskey 字段的 base64 解码值（必须恰好为 32 字节）。
IV 由密钥的前 16 字节生成。
此功能需要安装 cryptography Python 包（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

分块上传： 文件通过三步协议（初始化 → 分块 → 完成）以 512 KB 为单位上传。适配器自动处理此过程。

自动降级： 当媒体超过原生类型大小限制但仍在绝对 20 MB 限制内时，将自动以通用文件形式发送：

图片 > 10 MB → 作为文件发送
视频 > 10 MB → 作为文件发送
语音 > 2 MB → 作为文件发送
非 AMR 音频 → 作为文件发送（企业微信仅支持 AMR 作为原生语音）

超过 20 MB 限制的文件将被拒绝，并向聊天发送提示信息。

回复模式流式响应

当机器人通过企业微信回调收到消息时，适配器会记住原始请求 ID。如果在请求上下文仍有效时发送响应，适配器将使用企业微信的回复模式（aibot_respond_msg）配合流式传输，将响应直接关联到原始消息。这在企业微信客户端中提供更自然的对话体验。

若原始请求上下文已过期或不可用，适配器将回退至通过 aibot_send_msg 主动发送消息。

回复模式也适用于媒体：上传的媒体可作为对原始消息的回复发送。

连接与重连

适配器维护与企业微信网关 wss://openws.work.weixin.qq.com 的持久 WebSocket 连接。

连接生命周期

连接：打开 WebSocket 连接，并发送包含 bot_id 和 secret 的 aibot_subscribe 认证帧。
心跳：每 30 秒发送一次应用层 ping 帧以保持连接活跃。
监听：持续读取入站帧并触发消息回调。

重连行为

连接丢失后，适配器采用指数退避策略重连：

尝试次数	延迟时间
第 1 次	2 秒
第 2 次	5 秒
第 3 次	10 秒
第 4 次	30 秒
第 5 次及以上	60 秒

每次成功重连后，退避计数器重置为零。所有待处理的请求未来对象在断开时将被标记为失败，防止调用方无限等待。

消息去重机制入站消息通过消息 ID 进行去重，使用 5 分钟的时间窗口和最多 1000 条记录的缓存。这可防止在重新连接或网络波动期间出现消息重复处理。

所有环境变量

变量	必填	默认值	说明
`WECOM_BOT_ID`	✅	—	企业微信 AI 机器人 ID
`WECOM_SECRET`	✅	—	企业微信 AI 机器人密钥
`WECOM_ALLOWED_USERS`	—	(空)	以逗号分隔的网关级允许列表用户 ID
`WECOM_HOME_CHANNEL`	—	—	用于定时任务/通知输出的聊天 ID
`WECOM_WEBSOCKET_URL`	—	`wss://openws.work.weixin.qq.com`	WebSocket 网关地址
`WECOM_DM_POLICY`	—	`open`	私聊访问策略
`WECOM_GROUP_POLICY`	—	`open`	群组访问策略

故障排除

问题	解决方法
`WECOM_BOT_ID and WECOM_SECRET are required`	设置两个环境变量，或在设置向导中配置
`WeCom startup failed: aiohttp not installed`	安装 aiohttp：`pip install aiohttp`
`WeCom startup failed: httpx not installed`	安装 httpx：`pip install httpx`
`invalid secret (errcode=40013)`	验证密钥是否与机器人的凭证完全匹配
`Timed out waiting for subscribe acknowledgement`	检查与 `openws.work.weixin.qq.com` 的网络连通性
机器人在群组中无响应	检查 `group_policy` 设置，并确保群组 ID 在 `group_allow_from` 列表中
机器人忽略群组中的某些用户	检查 `groups` 配置部分中的各群组 `allow_from` 白名单
媒体解密失败	安装 `cryptography`：`pip install cryptography`
`cryptography is required for WeCom media decryption`	入站媒体为 AES 加密。请安装：`pip install cryptography`
语音消息以文件形式发送	企业微信仅原生支持 AMR 格式语音。其他格式将自动降级为文件形式发送。
`File too large` 错误	企业微信对所有文件上传有 20 MB 的绝对限制。请压缩或拆分文件。
图片以文件形式发送	图片大小超过 10 MB 时超出原生图片限制，将自动降级为文件附件。
`Timeout sending message to WeCom`	WebSocket 可能已断开连接。检查日志中的重连信息。
`WeCom websocket closed during authentication`	网络问题或凭证错误。请验证 bot_id 和 secret 是否正确。

前置条件​

配置步骤​

1. 创建 AI Bot​

2. 配置 Hermes​

3. 启动网关​

功能特性​

配置选项​

访问策略​

私聊策略（DM Policy）​

群组策略（Group Policy）​

按群组发送者白名单​

媒体支持​

入站（接收）​

AES 加密媒体自动解密​

出站（发送）​

回复模式流式响应​

连接与重连​

连接生命周期​

重连行为​

消息去重机制入站消息通过消息 ID 进行去重，使用 5 分钟的时间窗口和最多 1000 条记录的缓存。这可防止在重新连接或网络波动期间出现消息重复处理。​

所有环境变量​

故障排除​