跳到主要内容

WeCom Callback（自建应用）设置

使用回调/webhook 模型将 Hermes 连接到企业微信作为自建企业应用。

WeCom Bot vs WeCom Callback

Hermes 支持两种 WeCom 集成模式：

  • WeCom Bot — 机器人样式，通过 WebSocket 连接。设置更简单，适用于群聊。
  • WeCom Callback（本页）— 自建应用，接收加密 XML 回调。在用户的企业微信侧边栏显示为一类应用。支持多企业路由。

工作原理​

  1. 你在企业微信管理后台注册一个自建应用
  2. 企业微信将加密 XML 推送到你的 HTTP 回调端点
  3. Hermes 解密消息，将其排队给 agent
  4. 立即确认（静默 — 不向用户显示任何内容）
  5. Agent 处理请求（通常 3–30 分钟）
  6. 回复通过企业微信 message/send API 主动投递

前置要求​

  • 具有管理员访问权限的企业微信企业账户
  • aiohttp 和 httpx Python 包（默认安装中已包含）
  • 用于回调 URL 的公开可访问服务器（或 ngrok 等隧道）

设置​

1. 在企业微信中创建自建应用​

  1. 进入 企业微信管理后台 → 应用 → 创建应用
  2. 记录你的 Corp ID（在管理后台顶部显示）
  3. 在应用设置中，创建一个 Corp Secret
  4. 从应用的概述页面记录 Agent ID
  5. 在 接收消息 下，配置回调 URL：
    • URL：http://YOUR_PUBLIC_IP:8645/wecom/callback
    • Token：生成一个随机 token（企业微信提供一个）
    • EncodingAESKey：生成一个密钥（企业微信提供一个）

2. 配置环境变量​

添加到你的 .env 文件：

WECOM_CALLBACK_CORP_ID=your-corp-id
WECOM_CALLBACK_CORP_SECRET=your-corp-secret
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key

# 可选
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. 启动网关​

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..."
        - name: "dept-b"
          corp_id: "ww_corp_b"
          corp_secret: "secret-b"
          agent_id: "1000003"
          token: "token-b"
          encoding_aes_key: "key-b-43-chars..."

用户通过 corp_id:user_id 限定以防止跨企业冲突。当用户发送消息时，适配器记录他们属于哪个应用（企业）并通过正确的应用访问 token 路由回复。

访问控制​

限制可以与应用交互的用户：

# 白名单特定用户
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# 或允许所有用户
WECOM_CALLBACK_ALLOW_ALL_USERS=true

端点​

适配器暴露：

| 方法 | 路径 | 用途 | |--------|------|---------|---------| | GET | /wecom/callback | URL 验证握手（设置期间企业微信发送） | | POST | /wecom/callback | 加密消息回调（企业微信在此发送用户消息） | | GET | /health | 健康检查 — 返回 {"status": "ok"} |

加密​

所有回调负载使用 EncodingAESKey 进行 AES-CBC 加密。适配器处理：

  • 入站：解密 XML 负载，验证 SHA1 签名
  • 出站：回复通过主动 API 发送（不加密回调响应）

加密实现与腾讯官方 WXBizMsgCrypt SDK 兼容。

限制​

  • 无流式传输 — 回复在 agent 完成后作为完整消息到达
  • 无打字指示器 — 回调模型不支持打字状态
  • 仅文本 — 目前支持文本消息作为输入；图片/文件/语音输入尚未实现
  • 响应延迟 — agent 会话需要 3–30 分钟；用户看到回复时处理完成