企业微信回调模式——自建应用 | Easy Understand Hermes Agent

这篇教程将教你如何把 Hermes Agent 接入企业微信，让它以“自建应用”的身份出现在你的企业微信侧边栏里，像一位真正的同事一样接收任务并回复结果。

两种接入方式，先分清

Hermes 支持两种企业微信接入方式，就像“加群聊天”和“正式入职”的区别：

企业微信机器人（Bot）：通过 WebSocket 连接，配置简单，适合群聊场景。
企业微信回调（Callback，即本文）：以自建应用的形式存在，用户在企业微信侧边栏里能直接看到它，支持多公司路由。

运行 hermes gateway setup 并选择 WeCom Callback 可进行引导式配置。

它是怎么工作的？

想象一下，你给这位“同事”发了一条消息：

企业微信把加密的消息推送到你的服务器（回调 URL）
Hermes 解密消息，交给 AI 智能体处理
服务器立即回复“收到”（用户端无感知）
智能体开始思考（通常需要 3–30 分钟）
处理完成后，通过企业微信 API 主动把结果发给你

准备工作

一个企业微信管理员账号
一台公网可达的服务器（或用 ngrok 等内网穿透工具）
Python 包 aiohttp 和 httpx（默认安装已包含）

第 1 步：在企业微信后台创建自建应用

登录企业微信管理后台 → 应用管理 → 创建应用
记下页面顶部的 企业 ID（Corp ID）
在应用设置里创建 企业密钥（Corp Secret）
在应用概览页找到 Agent ID
在“接收消息”模块配置回调 URL：
- URL：http://你的公网IP:8645/wecom/callback
- Token：随机生成一个（后台会提供）
- EncodingAESKey：生成一个密钥（后台会提供）

第 2 步：配置环境变量

在 .env 文件中添加以下内容：

WECOM_CALLBACK_CORP_ID=你的企业ID
WECOM_CALLBACK_CORP_SECRET=你的企业密钥
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=你的回调Token
WECOM_CALLBACK_ENCODING_AES_KEY=你的43位AES密钥

# 可选配置
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

第 3 步：启动网关

hermes gateway

（若已注册系统服务，可用 hermes gateway start）

启动后，适配器会开启一个 HTTP 服务器。企业微信会先通过 GET 请求验证 URL，之后通过 POST 推送消息。

多应用路由（进阶）

如果公司有多个部门、多个自建应用，可以在 config.yaml 中配置 apps 列表：

platforms:
  wecom_callback:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8645
      apps:
        - name: "dept-a"
          corp_id: "ww_corp_a"
          corp_secret: "secret-a"
          agent_id: "1000002"
          token: "token-a"
          encoding_aes_key: "key-a-43-chars..."

系统会按 corp_id:user_id 区分用户，确保消息路由到正确的应用。

访问控制

# 只允许指定用户使用
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi

# 或允许所有用户
WECOM_CALLBACK_ALLOW_ALL_USERS=true

常见问题

签名验证失败？ 检查 Token 和 EncodingAESKey 是否从后台完整复制，注意 .env 中 = 两侧不要有空格。

回调 URL 无法访问？ 确认反向代理或隧道已正确转发 /wecom/callback 路径，且 URL 为 HTTPS（企业微信拒绝 HTTP）。

端口无法访问？ 查看日志确认监听地址。如果绑定在 127.0.0.1，需要用 Cloudflare Tunnel 或 nginx 做反向代理。

小总结

通过回调模式接入企业微信，相当于给企业配备了一位 7×24 小时在线的 AI 同事。虽然它目前只支持文本输入、回复有延迟（3–30 分钟），但作为异步任务处理工具已经足够强大。

下篇预告：我们将介绍如何配置企业微信机器人的 WebSocket 接入方式，让你在群聊里也能随时召唤 AI 助手！