mirror of
https://github.com/zhayujie/chatgpt-on-wechat.git
synced 2026-06-02 00:57:41 +08:00
6e04ea8240
Rename the WeCom customer-service channel and give it its own corp_id
field so users no longer have to share `wechatcom_corp_id` with the
self-built WeCom app channel.
Renames (channel-side):
- channel type / const: wechatcom_kf -> wechat_kf
- package dir: channel/wechatcom_kf/ -> channel/wechat_kf/
- python files / classes: WechatComKf* -> WechatKf*
- config keys: wechatcom_kf_{secret,token,aes_key,port} ->
wechat_kf_{secret,token,aes_key,port}; new wechat_kf_corp_id
- env vars: WECHATCOM_KF_* -> WECHAT_KF_*; new WECHAT_KF_CORP_ID
- log prefix / cursor file: [wechatcom_kf] -> [wechat_kf]
- web console CHANNEL_DEFS key + startup log line
Renames (docs):
- docs/channels/wecom-kf.mdx -> docs/channels/wechat-kf.mdx (zh/en/ja)
- update docs.json sidebar entries and all field names inside the docs
In addition, the Web Console "微信客服" entry now exposes its own
Corp ID field instead of reusing the wechatcom_app one, and includes
the screenshot of the visual config in the channel guide.
Web Console onboarding section is added (Tabs: Web Console / config
file) and the local URL `http://127.0.0.1:9899/` parenthetical is
dropped for consistency with other channel docs.
Co-authored-by: Cursor <cursoragent@cursor.com>
131 lines
5.7 KiB
Plaintext
131 lines
5.7 KiB
Plaintext
---
|
||
title: 微信客服
|
||
description: 将 CowAgent 接入微信客服（WeCom Customer Service）
|
||
---
|
||
|
||
通过把企业微信自建应用绑定到「微信客服」账号，CowAgent 可以接管来自外部微信用户的客服咨询，并可在小程序、公众号、视频号及视频号小店等场景中通过链接或二维码触达微信用户。
|
||
|
||
<Note>
|
||
微信客服只能使用 Docker 部署或服务器 Python 部署，需要公网可达的回调地址，不支持本地运行模式。
|
||
</Note>
|
||
|
||
## 一、准备
|
||
|
||
需要的资源：
|
||
|
||
1. 一台服务器（有公网 IP）
|
||
2. 注册并已认证的企业微信
|
||
3. 已开通「微信客服」能力
|
||
|
||
<Note>
|
||
建议**单独再创建一个企微自建应用**用于微信客服，不要复用已有的 `wechatcom_app` 应用，否则两个通道会争抢同一个回调地址。
|
||
</Note>
|
||
|
||
## 二、创建企业微信自建应用
|
||
|
||
1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，点击 **应用管理 → 创建应用**：
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
|
||
|
||
2. 点击 **我的企业**，在最下方获取 **企业ID**（后续填写到 `wechat_kf_corp_id`）：
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png" width="600"/>
|
||
|
||
3. 进入上一步创建的应用，点击 Secret 旁的「**查看**」，Secret 会推送到管理员手机端的企业微信里查看：
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png" width="600"/>
|
||
|
||
4. 进入应用 **接收消息 → 设置API接收**，点击右侧「**随机获取**」生成 **Token** 和 **EncodingAESKey** 并保存：
|
||
|
||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg" width="600"/>
|
||
|
||
<Note>
|
||
此时保存 API 接收配置会失败，因为程序还未启动，等项目运行后再回来保存。
|
||
</Note>
|
||
|
||
## 三、配置和运行
|
||
|
||
填入上一步收集到的 4 个字段（Corp ID / Secret / Token / EncodingAESKey）：
|
||
|
||
<Tabs>
|
||
<Tab title="Web 控制台">
|
||
启动 Cow 项目后打开 Web 控制台，选择 **通道** 菜单，点击 **接入通道**，选择 **微信客服**，依次填入 Corp ID / Secret / Token / AES Key（端口默认 9888，可改），点击接入即可。
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/cow-weixinkefu-web-control.png" width="800"/>
|
||
</Tab>
|
||
<Tab title="配置文件">
|
||
在 `config.json` 中添加以下配置（各参数与企业微信后台的对应关系见上方截图）：
|
||
|
||
```json
|
||
{
|
||
"channel_type": "wechat_kf",
|
||
"wechat_kf_corp_id": "YOUR_CORP_ID",
|
||
"wechat_kf_secret": "YOUR_SECRET",
|
||
"wechat_kf_token": "YOUR_TOKEN",
|
||
"wechat_kf_aes_key": "YOUR_AES_KEY",
|
||
"wechat_kf_port": 9888
|
||
}
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
| --- | --- |
|
||
| `wechat_kf_corp_id` | 企业 ID |
|
||
| `wechat_kf_secret` | 绑定到微信客服的那个企微自建应用的 Secret |
|
||
| `wechat_kf_token` | API 接收配置中的 Token |
|
||
| `wechat_kf_aes_key` | API 接收配置中的 EncodingAESKey |
|
||
| `wechat_kf_port` | 监听端口，默认 9888 |
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
接入完成后启动程序（Web 控制台方式会自动重启），日志中出现 `Listening on http://0.0.0.0:9888/wxkf/` 表示运行成功，需要将该端口对外开放（如在云服务器安全组中放行）。
|
||
|
||
接着回到企业微信「接收消息 → 设置API接收」，将回调 URL 填为 `http://<your-host>:9888/wxkf/`，点击保存。保存成功后还需将服务器 IP 添加到 **企业可信IP** 中，否则无法收发消息：
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/wechat-com_config.png" width="600"/>
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
|
||
|
||
<Warning>
|
||
如遇到 URL 配置回调不通过或配置失败：
|
||
1. 确保服务器防火墙关闭且安全组放行监听端口（默认 9888）
|
||
2. 仔细检查 Token、Secret、EncodingAESKey 等参数配置是否一致，URL 格式是否正确
|
||
3. 认证企业微信需要配置与主体一致的备案域名
|
||
</Warning>
|
||
|
||
## 四、绑定微信客服账号
|
||
|
||
进入企业微信管理后台 **微信客服** 页面，创建客服账号并与上一步的企微自建应用绑定：
|
||
|
||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg" width="600"/>
|
||
|
||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step2.jpg" width="600"/>
|
||
|
||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg" width="600"/>
|
||
|
||
绑定完成后，进入 **微信客服 → 微信客服账号详情**，在「**接入链接**」一栏：
|
||
|
||
- 点击「**复制链接**」可获得形如 `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be` 的访问链接
|
||
- 点击「**生成二维码**」可获得对应的二维码
|
||
|
||
把链接或二维码推给微信客户使用即可：
|
||
|
||
<img src="https://cdn.link-ai.tech/doc/wechat-customer-service_use.png" width="600"/>
|
||
|
||
## 五、使用
|
||
|
||
微信用户通过链接或二维码进入客服对话后，即可与 AI 进行多轮对话，支持文本、图片、语音等消息：
|
||
|
||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg" width="900"/>
|
||
|
||
除此之外，基于微信生态官方能力，还可将微信客服应用在公众号、小程序、视频号及视频号小店等场景，详情可查看企业微信管理后台 [微信客服 → 接入场景](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) 的相关说明：
|
||
|
||
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png" width="800"/>
|
||
|
||
## 常见问题
|
||
|
||
需要确保已安装以下依赖：
|
||
|
||
```bash
|
||
pip install websocket-client pycryptodome
|
||
```
|