词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"WeCom（企业微信）"
WeCom（企业微信）
前提条件
aiohttp 和 httpx设置
第一步：创建 AI Bot
推荐方式：扫码创建（一条命令）
1.
2.
3.
4.
备选方式：手动设置
1.
2.
3.
4.
5.
hermes gateway setup，选择 WeCom，并在提示时输入凭据警告
第二步：配置 Hermes
方式 A：交互式设置（推荐）
方式 B：手动配置
~/.hermes/.env：第三步：启动网关
功能特性
配置选项
config.yaml 的 platforms.wecom.extra 下设置以下选项：| 键 | 默认值 | 描述 |
|---|---|---|
bot_id | — | WeCom AI Bot ID（必填） |
secret | — | WeCom AI Bot Secret（必填） |
websocket_url | wss://openws.work.weixin.qq.com | WebSocket 网关 URL |
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 | {} | 按群组配置（见下文） |
访问策略
私聊策略
| 值 | 行为 |
|---|---|
open | 任何人均可私聊机器人（默认） |
allowlist | 仅 allow_from 中的用户 ID 可私聊 |
disabled | 所有私聊均被忽略 |
pairing | 配对模式（用于初始设置） |
群组策略
| 值 | 行为 |
|---|---|
open | 机器人在所有群组中响应（默认） |
allowlist | 机器人仅在 group_allow_from 中列出的群组 ID 中响应 |
disabled | 所有群组消息均被忽略 |
按群组的发送者白名单
config.yaml 中配置：1.
group_policy 和 group_allow_from 控制决定某个群组是否被允许。2.
groups.<group_id>.allow_from 列表（如果存在）将进一步限制该群组内哪些发送者可以与机器人交互。3.
"*" 群组条目作为未明确列出的群组的默认配置。4.
* 通配符以允许所有用户，且条目不区分大小写。5.
wecom:user: 或 wecom:group: 前缀格式——前缀会被自动去除。allow_from，则该群组中的所有用户均被允许（前提是该群组本身通过了顶层策略检查）。媒体支持
入站（接收）
| 类型 | 处理方式 |
|---|---|
| 图片 | 下载并在本地缓存。支持基于 URL 和 base64 编码的图片。 |
| 文件 | 下载并缓存。文件名从原始消息中保留。 |
| 语音 | 如果可用，提取语音消息的文字转录。 |
| 混合消息 | WeCom 混合类型消息（文本 + 图片）会被解析并提取所有组件。 |
AES 加密媒体解密
aeskey 字段时，适配器下载加密字节并使用带 PKCS#7 填充的 AES-256-CBC 进行解密。aeskey 字段的 base64 解码值（必须恰好为 32 字节）。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 |
回复模式流式响应
aibot_respond_msg）配合流式传输，将响应直接与入站消息关联。这在 WeCom 客户端中提供了更自然的对话体验。aibot_send_msg 主动发送消息。连接与重连
wss://openws.work.weixin.qq.com 维护与 WeCom 网关的持久 WebSocket 连接。连接生命周期
1.
aibot_subscribe 认证帧。2.
3.
重连行为
| 尝试次数 | 延迟 |
|---|---|
| 第 1 次重试 | 2 秒 |
| 第 2 次重试 | 5 秒 |
| 第 3 次重试 | 10 秒 |
| 第 4 次重试 | 30 秒 |
| 第 5 次及以后 | 60 秒 |
去重
所有环境变量
| 变量 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|
WECOM_BOT_ID | ✅ | — | WeCom AI Bot ID |
WECOM_SECRET | ✅ | — | WeCom AI Bot Secret |
WECOM_ALLOWED_USERS | — | （空） | 网关级白名单的逗号分隔用户 ID |
WECOM_HOME_CHANNEL | — | — | 定时任务/通知输出的聊天 ID |
WECOM_WEBSOCKET_URL | — | wss://openws.work.weixin.qq.com | WebSocket 网关 URL |
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) | 验证 secret 是否与机器人凭据匹配 |
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 |
| 语音消息作为文件发送 | WeCom 原生语音仅支持 AMR 格式，其他格式会自动降级为文件。 |
File too large 错误 | WeCom 对所有文件 上传有 20 MB 的绝对限制。请压缩或拆分文件。 |
| 图片作为文件发送 | 图片 > 10 MB 超过原生图片限制，会自动降级为文件附件。 |
Timeout sending message to WeCom | WebSocket 可能已断开。检查日志中的重连消息。 |
WeCom websocket closed during authentication | 网络问题或凭据不正确。验证 bot_id 和 secret。 |