跳到主要内容

WeCom 回调(自建应用)

将 Kopi Agent 通过回调/webhook 模型接入 WeCom(企业微信),作为自建企业应用使用。

WeCom Bot 与 WeCom Callback 的区别

Kopi Agent 支持两种 WeCom 集成模式:

  • WeCom Bot — 机器人模式,通过 WebSocket 连接。设置更简单,可在群聊中使用。
  • WeCom Callback(本页)— 自建应用,接收加密 XML 回调。在用户的 WeCom 侧边栏中显示为独立应用。支持多企业路由。

另请参阅:WeCom Bot(机器人模式集成)。

运行 kopi gateway setup 并选择 WeCom Callback,即可获得交互式引导。

工作原理​

  1. 在 WeCom 管理后台注册一个自建应用
  2. WeCom 将加密 XML 推送到你的 HTTP 回调端点
  3. Kopi Agent 解密消息,并将其排入 agent 队列
  4. 立即返回确认(静默处理 — 不向用户显示任何内容)
  5. agent 处理请求(通常需要 3–30 分钟)
  6. 通过 WeCom message/send API 主动下发回复

前提条件​

  • 一个拥有管理权限的 WeCom 企业账号
  • aiohttp 和 httpx Python 包(默认安装已包含)
  • 一个可公开访问的服务器用于回调 URL(或使用 ngrok 之类的隧道)

配置步骤​

1. 在 WeCom 中创建自建应用​

  1. 前往 WeCom 管理后台 → 应用管理 → 创建应用
  2. 记下你的 Corp ID(显示在管理后台顶部)
  3. 在应用设置中创建 Corp Secret
  4. 从应用概览页面记下 Agent ID
  5. 在 接收消息 下配置回调 URL:
    • URL:http://YOUR_PUBLIC_IP:8645/wecom/callback
    • Token:生成一个随机 token(WeCom 会提供一个)
    • EncodingAESKey:生成一个密钥(WeCom 会提供一个)

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

# Optional
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. 启动网关​

kopi gateway

(仅在 kopi gateway install 已注册 systemd/launchd 服务后才使用 kopi gateway start。)

回调适配器会在配置的端口上启动一个 HTTP 服务器。WeCom 会先通过 GET 请求验证回调 URL,然后开始通过 POST 发送消息。

配置参考​

在 config.yaml 的 platforms.wecom_callback.extra 下进行如下设置,或使用环境变量:

设置项默认值说明
corp_id—WeCom 企业 Corp ID(必填)
corp_secret—自建应用的 Corp secret(必填)
agent_id—自建应用的 Agent ID(必填)
token—回调验证 token(必填)
encoding_aes_key—用于回调加密的 43 字符 AES 密钥(必填)
host0.0.0.0HTTP 回调服务器的绑定地址
port8645HTTP 回调服务器的端口
path/wecom/callback回调端点的 URL 路径

多应用路由​

对于运行多个自建应用的企业(例如不同部门或子公司),请在 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 进行隔离,以防止跨企业冲突。当用户发送消息时,适配器会记录该用户所属的应用(企业),并通过对应应用的 access token 路由回复。

访问控制​

限制哪些用户可以与该应用交互:

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

端点​

适配器暴露以下端点:

方法路径用途
GET/wecom/callbackURL 验证握手(WeCom 在配置过程中发送此请求)
POST/wecom/callback加密消息回调(WeCom 将用户消息发送到这里)
GET/health健康检查 — 返回 {"status": "ok"}

加密​

所有回调负载均使用 EncodingAESKey 通过 AES-CBC 加密。适配器负责:

  • 入站:解密 XML 负载,验证 SHA1 签名
  • 出站:回复通过主动 API 发送(不是加密的回调响应)

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

限制​

  • 不支持流式输出 — 回复会在 agent 完成后以完整消息形式送达
  • 不支持输入状态指示 — 回调模型不支持"正在输入"状态
  • 仅支持文本 — 目前输入仅支持文本消息;图片/文件/语音输入尚未实现。agent 可通过 WeCom 平台提示了解出站媒体能力(图片、文档、视频、语音)。
  • 响应延迟 — agent 会话需要 3–30 分钟;用户会在处理完成后看到回复

故障排查​

签名校验失败。 WeCom 会对你在管理后台注册的 Token 为每个请求签名。Kopi Agent 中配置的 token 与管理后台期望的 token 不一致是最常见的原因。请重新从管理后台复制 Token 和 EncodingAESKey — 它们很容易被截断。~/.kopi/.env 值中 = 周围的空白字符也会导致签名校验失败。修复后,重启 kopi gateway run。

回调 URL 不可达 / 验证步骤失败。 WeCom 会访问你注册的公网 URL。请确认:

  1. 你的反向代理 / 隧道已将 /wecom/callback 转发到网关端口。
  2. 管理后台中的 URL 是 HTTPS(WeCom 会拒绝普通 HTTP)。
  3. 从你的网络外部访问 curl -i https://<your-domain>/wecom/callback 能返回结果而不是超时(没有查询参数时返回 4xx 也没问题 — 这只说明监听器可达)。

端口不可达 / 监听器未绑定。 查看 kopi gateway run 日志了解绑定的 host/port。如果适配器绑定到 127.0.0.1,你必须在其前面加上反向代理或隧道 — WeCom 的服务器 无法访问 loopback。在 config.yaml 中设置 extra.host: 0.0.0.0(如果直接对外暴露,还需 allowed_source_cidrs),或者保留 loopback 并使用 Cloudflare Tunnel / nginx 之类的隧道。