接收企业微信客服消息，转发到 OpenClaw Gateway，实现外部微信用户与 AI Agent 的对话。
- 🔐 消息加解密：支持企业微信安全模式，自动处理消息加解密和签名验证
- 🤖 AI Agent 集成：无缝对接 OpenClaw Gateway，支持多 Agent 配置
- 👋 自动欢迎消息：新用户首次对话时自动发送欢迎词
- 🔄 消息去重：防止重复消息处理
- ⚙️ 灵活配置：支持 JSON 配置文件和环境变量
- 📊 详细日志：完整的消息流转日志，便于调试
- 🚀 生产就绪：支持 PM2、Docker 部署
- 🔢 多实例支持：同一服务器可运行多个独立实例，服务不同业务
- Node.js >= 20.0.0
- 企业微信账号（已开通微信客服功能）
- OpenClaw Gateway 实例
git clone https://github.com/YOUR_USERNAME/wecom-kf-bridge.git
cd wecom-kf-bridgenpm install复制配置模板：
cp config.conf.example config.conf编辑 config.conf，填入你的配置：
{
"wecom": {
"corpId": "你的企业ID",
"kfSecret": "你的客服Secret",
"token": "你的Token",
"encodingAESKey": "你的EncodingAESKey"
},
"openclaw": {
"gatewayUrl": "http://localhost:18789",
"gatewayToken": "你的Gateway Token",
"agentId": "service"
},
"server": {
"port": 3000
},
"welcome": {
"enabled": true,
"message": "您好呀，欢迎使用我们的服务！",
"clearInterval": 86400000
}
}详细配置说明请查看 CONFIG.md
# 开发模式
npm run dev
# 生产模式
npm start- 登录 企业微信管理后台
- 导航：应用管理 → 微信客服 → 开通
- 微信客服 → 客服账号 → 添加账号
- 填写客服名称和头像
- 记录生成的
open_kfid
- 微信客服 → 接入配置 → 接收消息
- 填写配置：
- URL:
http://your-domain:3000/wecom-kf/webhook - Token: 随机生成 16 位字符串
- EncodingAESKey: 随机生成 43 位字符串
- 消息加解密方式: 安全模式
- URL:
- 点击保存，完成 URL 验证
| 配置项 | 获取位置 |
|---|---|
| CorpID | 我的企业 → 企业信息 → 企业ID |
| Secret | 应用管理 → 微信客服 → 查看 Secret |
| Token | 接收消息配置页面 |
| EncodingAESKey | 接收消息配置页面 |
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────┐
│ 微信用户 │────▶│ 企业微信客服 │────▶│ 本服务 │────▶│ OpenClaw │
│ │ │ │ │ (Bridge) │ │ Gateway │
└─────────────┘ └──────────────┘ └─────────────┘ └──────────┘
│ │
│ ▼
│ ┌──────────┐
│ │ AI Agent │
│ └──────────┘
│ │
▼ │
┌─────────────┐ │
│ 消息处理 │◀───────────┘
│ - 解密 │
│ - 去重 │
│ - 欢迎消息 │
└─────────────┘
config.conf文件（推荐）- 环境变量
- 默认值
corpId: 企业ID（必填）kfSecret: 客服Secret（必填）token: 消息加解密Token（必填）encodingAESKey: 消息加解密AESKey（必填）
gatewayUrl: Gateway地址（默认:http://localhost:18789）gatewayToken: Gateway访问令牌（必填）agentId: Agent ID（默认:servers）
enabled: 是否启用欢迎消息（默认:true）message: 欢迎消息内容clearInterval: 清理间隔，毫秒（默认: 86400000，即24小时）
完整配置说明请查看 CONFIG.md
# 安装 PM2
npm install -g pm2
# 启动服务
pm2 start server.js --name wecom-kf-bridge
# 保存配置
pm2 save
# 设置开机自启
pm2 startup如果需要在同一服务器上运行多个客服实例（服务不同业务），请查看 多实例部署指南。
快速部署第二个实例：
# 使用自动化脚本
./deploy-instance.sh 2
# 或手动部署，详见 DEPLOYMENT_GUIDE.md每个实例独立运行，使用不同的：
- 端口（3000, 3001, 3002...）
- 配置文件
- PM2进程名
- Agent ID
- 欢迎消息
# 构建镜像
docker build -t wecom-kf-bridge .
# 运行容器
docker run -d \
--name wecom-kf-bridge \
-p 3000:3000 \
-v $(pwd)/config.conf:/app/config.conf \
wecom-kf-bridgedocker-compose up -d项目包含一个命令行工具 kf-manager.js，用于管理企业微信客服账号。
- 📝 列出所有客服账号
- 🖼️ 更新客服头像
- ✏️ 更新客服名字
- 🔄 同时更新头像和名字
# 列出所有客服
node kf-manager.js list
# 更新头像
node kf-manager.js update-avatar "客服达达" /path/to/avatar.jpg
# 更新名字
node kf-manager.js update-name "客服达达" "客服小晓"
# 同时更新
node kf-manager.js update "客服达达" "客服小晓" /path/to/avatar.jpg详细使用说明请查看 客服管理工具指南
GET /health响应：
{
"status": "ok",
"timestamp": "2026-03-12T00:00:00.000Z"
}POST /wecom-kf/webhook企业微信会自动调用此接口推送消息。
# PM2 日志
pm2 logs wecom-kf-bridge
# 实时日志
pm2 logs wecom-kf-bridge --lines 100# 测试健康检查
curl http://localhost:3000/health
# 测试公网访问
curl http://your-domain:3000/healthwecom-kf-bridge/
├── server.js # 主服务文件
├── wecom-crypto.js # 加解密模块
├── config.conf # 配置文件（不提交）
├── config.conf.example # 配置模板
├── package.json # 依赖配置
├── CONFIG.md # 配置说明文档
├── README.md # 项目说明
├── Dockerfile # Docker 配置
├── docker-compose.yml # Docker Compose 配置
└── .gitignore # Git 忽略规则
npm test- 公网可访问: 服务器必须有公网 IP 或域名，企业微信才能推送消息
- 端口开放: 确保配置的端口（默认3000）已开放
- HTTPS: 生产环境建议使用 HTTPS（可通过 Nginx 反向代理实现）
- Token 安全: 不要将
config.conf提交到 Git 仓库 - 消息去重: 企业微信可能重复推送消息，服务已内置去重机制
- AccessToken 缓存: AccessToken 会自动缓存，避免频繁请求
欢迎提交 Issue 和 Pull Request！
如有问题，请提交 Issue