好奇心花园🪴

搜索

SearchSearch

最近的笔记

企业微信（WeCom）

2026年5月24日12分钟阅读

企业微信（WeCom）

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

前提条件

  • 一个企业微信组织账号
  • 在企业微信管理后台创建的 AI 机器人
  • 机器人凭证页面的 Bot ID 和 Secret
  • Python 包：aiohttp 和 httpx

设置

第一步：创建 AI 机器人

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

hermes gateway setup

选择 企业微信 并使用企业微信手机应用扫描二维码。Hermes 将自动创建一个具有正确权限的机器人应用并保存凭证。

设置向导将：

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

备选：手动设置

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

  1. 登录企业微信管理后台
  2. 导航至 应用管理 → 创建应用 → AI 机器人
  3. 配置机器人名称和描述
  4. 从凭证页面复制 Bot ID 和 Secret
  5. 运行 hermes gateway setup，选择 企业微信，按提示输入凭证

:::warning 保持 Bot Secret 私密。任何人拥有它都可以冒充您的机器人。 :::

第二步：配置 Hermes

方式 A：交互式设置（推荐）

hermes gateway setup

选择 企业微信 并按照提示操作。向导将引导您完成：

  • 机器人凭证（通过扫描二维码或手动输入）
  • 访问控制设置（白名单、配对模式或开放访问）
  • 通知家聊

方式 B：手动配置

将以下内容添加到 ~/.hermes/.env：

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret
 
# 可选：限制访问
WECOM_ALLOWED_USERS=user_id_1,user_id_2
 
# 可选：定时任务/通知的家聊
WECOM_HOME_CHANNEL=chat_id

第三步：启动网关

hermes gateway

功能

  • WebSocket 传输 — 持久连接，无需公共端点
  • 私聊和群聊 — 可配置的访问策略
  • 按群发送者白名单 — 细粒度控制谁可以在每个群中交互
  • 媒体支持 — 图片、文件、语音、视频上传和下载
  • AES 加密媒体 — 入站附件的自动解密
  • 引用上下文 — 保留回复线程
  • Markdown 渲染 — 富文本响应
  • 回复模式流式 — 将响应与入站消息上下文关联
  • 自动重连 — 连接断开时指数退避

配置选项

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

键默认值描述
bot_id—企业微信 AI 机器人 ID（必填）
secret—企业微信 AI 机器人 Secret（必填）
websocket_urlwss://openws.work.weixin.qq.comWebSocket 网关 URL
dm_policyopen私聊访问：open、allowlist、disabled、pairing
group_policyopen群访问：open、allowlist、disabled
allow_from[]允许私聊的用户 ID（当 dm_policy=allowlist 时）
group_allow_from[]允许的群 ID（当 group_policy=allowlist 时）
groups{}按群配置（见下文）

访问策略

私聊策略

控制谁可以向机器人发送直接消息：

值行为
open任何人都可以私聊机器人（默认）
allowlist只有 allow_from 中的用户 ID 可以私聊
disabled忽略所有私聊
pairing配对模式（用于初始设置）
WECOM_DM_POLICY=allowlist

群策略

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

值行为
open机器人在所有群中响应（默认）
allowlist机器人仅在 group_allow_from 中列出的群 ID 中响应
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"

工作原理：

  1. group_policy 和 group_allow_from 控制群是否被允许。
  2. 如果群通过顶层检查，groups.<group_id>.allow_from 列表（如果存在）进一步限制该群内哪些发送者可以与机器人交互。
  3. 通配符 "*" 群条目作为未显式列出的群的默认值。
  4. 白名单条目支持 * 通配符以允许所有用户，且条目不区分大小写。
  5. 条目可以选择使用 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）。

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

出站（发送）

方法发送内容大小限制
sendMarkdown 文本消息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 连接。

连接生命周期

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

重连行为

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

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

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

去重

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

所有环境变量

变量必填默认值描述
WECOM_BOT_ID✅—企业微信 AI 机器人 ID
WECOM_SECRET✅—企业微信 AI 机器人 Secret
WECOM_ALLOWED_USERS—(空)逗号分隔的网关级别白名单用户 ID
WECOM_HOME_CHANNEL——定时任务/通知输出的聊天 ID
WECOM_WEBSOCKET_URL—wss://openws.work.weixin.qq.comWebSocket 网关 URL
WECOM_DM_POLICY—open私聊访问策略
WECOM_GROUP_POLICY—open群访问策略

故障排查

问题解决方法
需要 WECOM_BOT_ID 和 WECOM_SECRET设置两个环境变量或在设置向导中配置
WeCom startup failed: aiohttp not installed安装 aiohttp：pip install aiohttp
WeCom startup failed: httpx not installed安装 httpx：pip install httpx
invalid secret (errcode=40013)确认 secret 与您的机器人凭证匹配
等待订阅确认超时检查到 openws.work.weixin.qq.com 的网络连通性
机器人在群中不回复检查 group_policy 设置，确保群 ID 在 group_allow_from 中
机器人忽略群中的某些用户检查 groups 配置部分中按群的 allow_from 列表
媒体解密失败安装 cryptography：pip install cryptography
WeCom 媒体解密需要 cryptography入站媒体为 AES 加密。安装：pip install cryptography
语音消息作为文件发送企业微信仅支持 AMR 格式的原生语音。其他格式自动降级为文件。
文件过大 错误企业微信对所有文件上传有 20 MB 的绝对限制。压缩或拆分文件。
图片作为文件发送图片 > 10 MB 超出原生图片限制，会自动降级为文件附件。
向企业微信发送消息超时WebSocket 可能已断开。检查日志中的重连消息。
企业微信 WebSocket 在认证期间关闭网络问题或凭证错误。验证 bot_id 和 secret。

关系图谱

反向链接