chatgpt-on-wechat/channel/wechatcom_kf

微信客服（WeCom Customer Service）通道

与 channel/wechatcom/（企微自建应用）是两个独立的 CoW 通道：

• 自建应用：面向企业内部成员（员工通过企业微信 App 与机器人对话）。
• 微信客服：面向外部微信用户（普通微信用户通过链接/二维码进入对话）。

但底层都基于"企微自建应用"——本通道是通过把一个企微自建应用绑定到微信客服账号来实现 AI 接管对外咨询，详见 LinkAI 微信客服接入文档。

一、接入流程概览

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│ 1. 企业微信后台      │ →  │ 2. CoW 配置回调      │ →  │ 3. 绑定微信客服   │
│   创建一个自建应用   │    │   端口 9899          │    │   账号           │
└─────────────────────┘    └─────────────────────┘    └──────────────────┘
                                                              ↓
                                                   外部微信用户通过
                                                   链接/二维码 →
                                                   消息 → CoW Bot

重要：建议单独再创建一个企微自建应用用于微信客服，不要复用已经接入员工内部使用的那个 wechatcom_app 应用，否则两个通道会争抢同一个回调地址。

二、企业微信后台配置

1. 创建企微自建应用

进入 企业微信管理后台 → 应用管理 → 创建应用。

2. 收集字段

字段	来源	对应 CoW 配置项
企业ID（CorpId）	「我的企业」最下方	wechatcom_corp_id
Secret	进入应用详情 → 复制	wechatcom_kf_secret
Token	应用「接收消息 → 设置API接收」	wechatcom_kf_token
EncodingAESKey	应用「接收消息 → 设置API接收」	wechatcom_kf_aes_key

AgentId 在本通道不需要（消息发送走的是 cgi-bin/kf/send_msg，不依赖 agent_id）。

3. 配置回调地址 + 可信 IP

在应用「接收消息 → 设置API接收」里填：

• URL：http://<your-host>:9899/wxkf/（公网必须可达）
• Token / EncodingAESKey：与下方 config.json 一致

回到应用详情页，把服务器公网 IP 填入「企业可信IP」。

4. 绑定微信客服账号

进入 企业微信后台 → 微信客服 → 创建客服账号 → 将该账号绑定到上一步创建的企微自建应用。

绑定完成后，企业微信会给你一个客服访问链接 / 二维码，把它推给微信客户使用即可。

三、CoW 配置（config.json）

{
  "channel_type": "wechatcom_kf",

  "wechatcom_corp_id": "ww1234567890abcdef",
  "wechatcom_kf_secret": "<企微应用的 Secret>",
  "wechatcom_kf_token": "<接收消息 Token>",
  "wechatcom_kf_aes_key": "<EncodingAESKey>",
  "wechatcom_kf_port": 9899,

  "wechatcom_kf_cursor_dir": "tmp",
  "wechatcom_kf_skip_history_on_first_start": true
}

字段	说明
wechatcom_corp_id	企业 ID，可与 wechatcom_app 共用
wechatcom_kf_secret	绑定到微信客服的那个企微自建应用的 Secret（不是 wechatcomapp_secret）
wechatcom_kf_token	该应用「接收消息」配置的 Token
wechatcom_kf_aes_key	该应用「接收消息」配置的 EncodingAESKey
wechatcom_kf_port	监听端口，默认 9899（避开 wechatcomapp_port=9898）
wechatcom_kf_cursor_dir	next_cursor 持久化目录，默认 tmp/
wechatcom_kf_skip_history_on_first_start	首次启动（无 cursor）时跳过历史消息，强烈建议 true，否则会回放最近 14 天的消息把所有用户都骚扰一遍

也支持环境变量：WECHATCOM_CORP_ID / WECHATCOM_KF_SECRET / WECHATCOM_KF_TOKEN / WECHATCOM_KF_AES_KEY。

四、运行

python app.py

启动后日志里会看到：

[wechatcom_kf] WeCom customer-service channel started
[wechatcom_kf] Listening on http://0.0.0.0:9899/wxkf/

回到企微后台「设置API接收」点击保存——会触发 GET /wxkf/?...&echostr=...，CoW 通过 crypto.check_signature 校验后返回明文 echostr，验证成功。

五、与自建应用通道的运行差异

维度	自建应用 (wechatcom_app)	微信客服 (wechatcom_kf)
接收方式	回调直接 push，消息内容现成	回调只通知"有新消息"，需调 kf/sync_msg 主动拉
接收方ID	userid（成员）	external_userid（外部用户）+ open_kfid（客服身份）
发送接口	wechatpy 内置封装	直接 POST cgi-bin/kf/send_msg
端口	9898	9899
状态保存	无	必须持久化 next_cursor（本通道写本地 JSON）

六、cursor 持久化

next_cursor 是企微返回的"我上次拉到哪儿了"的书签。本通道把它存在 tmp/wechatcom_kf_cursors.json（按 open_kfid 分键），重启不会丢。

不要轻易删除该文件，否则下次启动：

• 若 wechatcom_kf_skip_history_on_first_start=true（默认）：会触发"跳过历史消息"逻辑，自动把 cursor 推进到最新位置；
• 若改为 false：会把最近 14 天的全部历史消息当成新消息回放并自动回复。

七、多客服账号

一个企业可以创建多个客服账号（多个 open_kfid）共用一个企微应用。本通道 自动按 open_kfid 维护各自的 cursor，无需为每个客服账号单独配置。

八、支持的回复类型

ReplyType	是否支持	备注
TEXT / INFO / ERROR	✅	自动按 2048 字节切片分段发送
IMAGE（本地） / IMAGE_URL（网络）	✅	大图自动压缩到 10MB 以内
VOICE	✅	转 amr 后发送，>60s 自动切片
VIDEO_URL	✅	通过临时素材接口上传
FILE	✅

九、参考文档

• LinkAI 微信客服接入文档
• 企业微信开放接口 - 微信客服 - 接收消息
• 企业微信开放接口 - 微信客服 - 发送消息