hermes教程-WeCom (企业微信)

将 Hermes 连接到 WeCom（企业微信），腾讯的企业级消息平台。该适配器使用 WeCom 的 AI Bot WebSocket 网关进行实时双向通信——无需公共端点或 webhook。

另请参阅：WeCom 回调 了解入站 webhook 设置。

前提条件

• 一个 WeCom 企业账号
• 在 WeCom 管理后台创建的 AI Bot
• 从 Bot 凭证页面获取的 Bot ID 和 Secret
• Python 包：aiohttp 和 httpx

设置

步骤 1：创建 AI Bot

推荐：扫码创建（一条命令）

hermes gateway setup

选择 WeCom，然后用你的 WeCom 手机应用扫描二维码。Hermes 将自动创建一个具有正确权限的 Bot 应用并保存凭证。

设置向导将：

1. 在终端中显示二维码
2. 等待你用 WeCom 手机应用扫描
3. 自动获取 Bot ID 和 Secret
4. 引导你完成访问控制配置

备选：手动设置

如果扫码创建不可用，向导将回退到手动输入：

1. 登录 WeCom 管理后台
2. 导航到 应用 → 创建应用 → AI Bot
3. 配置 Bot 名称和描述
4. 从凭证页面复制 Bot ID 和 Secret
5. 运行 hermes gateway setup，选择 WeCom，并在提示时输入凭证

警告

请保密 Bot Secret。任何拥有它的人都可以冒充你的 Bot。

步骤 2：配置 Hermes

选项 A：交互式设置（推荐）

hermes gateway setup

选择 WeCom 并按照提示操作。向导将引导你完成：

• Bot 凭证（通过二维码扫描或手动输入）
• 访问控制设置（白名单、配对模式或开放访问）
• 用于通知的主频道

选项 B：手动配置

将以下内容添加到 ~/.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 传输 — 持久连接，无需公共端点
• 私聊和群聊消息 — 可配置的访问策略
• 按群组设置发送者白名单 — 精细控制每个群组中谁可以与 Bot 交互
• 媒体支持 — 图片、文件、语音、视频的上传和下载
• AES 加密媒体 — 自动解密入站附件
• 引用上下文 — 保留回复的线程关系
• Markdown 渲染 — 富文本响应
• 回复关联 — 响应与入站消息上下文关联
• 自动重连 — 连接断开时指数退避

注意 — 流式传输和输入指示

WeCom 适配器将每个响应作为一条完整的消息发送——它不会逐 token 流式传输响应，也不会显示输入指示。“回复关联”（见下文）仅将响应与入站请求关联；并非实时流式传输。

配置选项

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

访问策略

私聊策略

控制谁可以向 Bot 发送私聊消息：

WECOM_DM_POLICY=allowlist

群组策略

控制 Bot 在哪些群组中响应：

WECOM_GROUP_POLICY=allowlist

按群组设置发送者白名单

为了实现精细控制，你可以限制特定群组中哪些用户允许与 Bot 交互。在 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"

工作原理：

1. group_policy 和 group_allow_from 控制群组是否被允许。
2. 如果群组通过了顶层检查，groups.<group_id>.allow_from 列表（如果存在）将进一步限制该群组中哪些发送者可以与 Bot 交互。
3. 通配符 "*" 群组条目作为未显式列出的群组的默认设置。
4. 白名单条目支持 * 通配符以允许所有用户，且条目不区分大小写。
5. 条目可以选择使用 wecom:user: 或 wecom:group: 前缀格式——前缀会被自动去除。

如果某个群组未配置 allow_from，则该群组中的所有用户都被允许（假设群组本身通过了顶层策略检查）。

媒体支持

入站（接收）

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

引用消息： 也会提取被引用（回复）消息中的媒体，以便代理了解用户正在回复的上下文。

AES 加密媒体解密

WeCom 使用 AES-256-CBC 加密某些入站媒体附件。适配器自动处理此过程：

• 当入站媒体项包含 aeskey 字段时，适配器下载加密字节并使用 AES-256-CBC 和 PKCS#7 填充进行解密。
• AES 密钥是 aeskey 字段的 base64 解码值（必须恰好为 32 字节）。
• IV 由密钥的前 16 个字节派生。
• 这需要 cryptography Python 包（pip install cryptography）。

无需配置——当接收到加密媒体时，解密会自动进行。

出站（发送）

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

自动降级： 当媒体超过原生类型的尺寸限制但低于绝对 20 MB 文件限制时，会自动作为通用文件附件发送：

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

超过绝对 20 MB 限制的文件将被拒绝，并向聊天发送一条信息性消息。

回复模式响应

当 Bot 通过 WeCom 回调收到消息时，适配器会记住入站请求 ID。如果在请求上下文仍然有效时发送响应，适配器会使用 WeCom 的回复模式（aibot_respond_msg）将响应直接关联到入站消息。这为 WeCom 客户端提供了更自然的对话体验。

完整响应作为单条消息发送——适配器不会增量流式传输 token。如果入站请求上下文已过期或不可用，适配器会回退到通过 aibot_send_msg 主动发送消息。

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

连接与重连

适配器通过 wss://openws.work.weixin.qq.com 与 WeCom 网关保持持久 WebSocket 连接。

连接生命周期

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

重连行为

连接丢失时，适配器使用指数退避进行重连：

每次成功重连后，退避计数器重置为零。所有待处理的请求 future 会在断开连接时失败，以免调用者无限挂起。

去重

入站消息使用消息 ID 进行去重，窗口为 5 分钟，最大缓存 1000 条。这可以防止在重连或网络波动期间重复处理消息。

所有环境变量

故障排除