WeCom 回调(自建应用)
将 Kopi Agent 通过回调/webhook 模型接入 WeCom(企业微信),作为自建企业应用使用。
Kopi Agent 支持两种 WeCom 集成模式:
- WeCom Bot — 机器人模式,通过 WebSocket 连接。设置更简单,可在群聊中使用。
- WeCom Callback(本页)— 自建应用,接收加密 XML 回调。在用户的 WeCom 侧边栏中显示为独立应用。支持多企业路由。
另请参阅:WeCom Bot(机器人模式集成)。
运行
kopi gateway setup并选择 WeCom Callback,即可获得交互式引导。
工作原理
- 在 WeCom 管理后台注册一个自建应用
- WeCom 将加密 XML 推送到你的 HTTP 回调端点
- Kopi Agent 解密消息,并将其排入 agent 队列
- 立即返回确认(静默处理 — 不向用户显示任何内容)
- agent 处理请求(通常需要 3–30 分钟)
- 通过 WeCom
message/sendAPI 主动下发回复
前提条件
- 一个拥有管理权限的 WeCom 企业账号
aiohttp和httpxPython 包(默认安装已包含)- 一个可公开访问的服务器用于回调 URL(或使用 ngrok 之类的隧道)
配置步骤
1. 在 WeCom 中创建自建应用
- 前往 WeCom 管理后台 → 应用管理 → 创建应用
- 记下你的 Corp ID(显示在管理后台顶部)
- 在应用设置中创建 Corp Secret
- 从应用概览页面记下 Agent ID
- 在 接收消息 下配置回调 URL:
- URL:
http://YOUR_PUBLIC_IP:8645/wecom/callback - Token:生成一个随机 token(WeCom 会提供一个)
- EncodingAESKey:生成一个密钥(WeCom 会提供一个)
- URL:
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 密钥(必填) |
host | 0.0.0.0 | HTTP 回调服务器的绑定地址 |
port | 8645 | HTTP 回调服务器的端口 |
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/callback | URL 验证握手(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。请确认:
- 你的反向代理 / 隧道已将
/wecom/callback转发到网关端口。 - 管理后台中的 URL 是 HTTPS(WeCom 会拒绝普通 HTTP)。
- 从你的网络外部访问
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 之类的隧道。