企业微信回调模式——自建应用

嘿，朋友们！今天咱们来聊聊怎么把 Hermes 接到企业微信上。别被“回调模式”这四个字吓到，其实现在的新玩法已经简单到连公网 IP 都不用准备了——全靠 WebSocket 长连接，妥妥的“内网友好型”选手。

先搞清楚：这版和以前有啥不一样？

老版本的回调模式需要你有个公网地址，还得配一堆回调 URL、Token、EncodingAESKey……想想就头大。现在好了，官方直接推荐走 AI Bot WebSocket 网关，双向实时通信，不需要任何公网端点。你只需要在企业微信后台创建一个 AI Bot，拿到 Bot ID 和 Secret，完事儿。

准备工作

一个企业微信组织账号
在管理后台创建一个 AI Bot（应用 → 创建应用 → AI Bot）
记下 Bot 的 ID 和 Secret（这俩是命根子，Secret 千万别泄露，谁拿到谁就能冒充你的机器人）
Python 环境装好 aiohttp 和 httpx

第一步：创建 AI Bot（推荐扫码大法）

打开终端，跑一条命令：

hermes gateway setup

选择 WeCom，然后终端会弹出一个二维码，掏出手机企业微信扫一下，Hermes 会自动帮你创建好应用、配好权限、存好凭证。整个过程丝滑得像德芙。

如果扫码方式不可用，也别慌，向导会退回手动输入模式：去管理后台复制 Bot ID 和 Secret，再回来粘贴就行。

第二步：配置 Hermes

同样推荐交互式配置：

hermes gateway setup

跟着向导走，它会带你搞定凭证、访问控制（白名单/配对模式/完全开放）、还有通知用的 home channel。

如果你喜欢手动改文件，那就编辑 ~/.hermes/.env：

WECOM_BOT_ID=你的-bot-id
WECOM_SECRET=你的-secret

# 可选：限制谁能私聊机器人
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# 可选：cron/通知的默认会话
WECOM_HOME_CHANNEL=chat_id

第三步：启动网关

hermes gateway

搞定！就这么简单。

这版有啥亮点？

原生流式输出：机器人回复的时候，企业微信会先显示“正在输入”的泡泡，然后一个字一个字蹦出来，体验跟 ChatGPT 官方客户端一模一样。工具调用的进度也会折叠在同一个泡泡里。默认开启，想关掉的话在 config.yaml 里把 display.platforms.wecom.streaming 设为 false
媒体全能：图片、文件、语音、视频都能收发，而且企业微信的加密媒体会自动解密，不用你操心
引用上下文：回复会保留引用关系，群聊里不会乱套
自动重连：断线了会指数退避重连，稳如老狗

访问控制：精细到群

除了全局的 DM 策略（open / allowlist / disabled / pairing）和群策略（open / allowlist / disabled），新版还支持每个群单独设置发言白名单。比如：

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"
        "*":
          allow_from:
            - "user_admin"

逻辑是：先看顶层 group_policy 和 group_allow_from 判断这个群能不能用，如果通过了，再看 groups.<群ID>.allow_from 决定群里谁能说话。"*" 是通配符，给所有群兜底。

一个小彩蛋

如果你遇到超长回复被截断的问题，可以试试开启 stream_keepalive_enabled: true，它会定时发送心跳帧，刷新企业微信大约 6 分钟的回复窗口，让长任务也能完整输出。

好了，今天的教程就到这里。企业微信接入 Hermes 现在就是这么轻松，快去试试吧！有问题欢迎在评论区留言～