@messi1030/wechat-customer-service-plugin

v2026.9.48

Published

15 days ago

OpenClaw WeChat Customer Service (微信客服) channel plugin

0High
0Medium
0Low

messi1030

wechat openclaw customer-service wechat-customer-service-plugin

微信客服插件

OpenClaw 微信客服（WeChat Customer Service）渠道集成插件

项目介绍

微信客服插件为 OpenClaw 与微信企业客服平台提供无缝集成。本插件支持消息接收、发送以及多账号管理，让您轻松构建微信客服机器人。

核心功能

✅ 消息处理: 支持文本、图片、语音、视频、文件等多种消息类型的收发
✅ 多账号支持: 同时管理多个微信客服账号
✅ 灵活安全策略: 支持白名单、配对和开放三种访问模式
✅ 双模式接收: 支持 Webhook 推送和消息轮询两种接收方式
✅ 媒体管理: 自动处理媒体文件上传下载，智能检测文件类型
✅ 流量控制: 内置速率限制器，防止 API 调用超限
✅ 文本分片: 超长消息自动分片发送
✅ 令牌管理: Access Token 自动刷新和缓存
✅ 消息去重: 防止重复处理同一消息

技术架构

本插件采用六层架构设计，职责清晰，易于维护和扩展：

┌─────────────────────────────────────────────────────────────┐
│                    Channel Adapter Layer                     │
│                   (channel.ts - 渠道适配层)                   │
│  • 统一的 OpenClaw Channel Plugin 接口实现                    │
│  • 生命周期管理、配置解析、安全策略                            │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Gateway Layer                             │
│                   (gateway/ - 网关层)                         │
│  • 账号网关生命周期管理                                        │
│  • Webhook/轮询器启动和监控                                   │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌──────────────────────────┬──────────────────────────────────┐
│   Inbound Layer          │   Outbound Layer                 │
│   (inbound/ - 入站层)     │   (outbound/ - 出站层)            │
│  • Webhook 消息接收       │  • 消息发送                       │
│  • 消息轮询器             │  • 文本分片                       │
│  • 消息解析               │  • 速率限制                       │
│  • 事件处理               │                                  │
└──────────────────────────┴──────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    API Client Layer                          │
│                   (api/ - API 客户端层)                       │
│  • 微信客服 API 封装                                          │
│  • HTTP 请求管理                                             │
│  • 错误处理和重试                                             │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌──────────────────────────┬──────────────────────────────────┐
│   Auth Layer             │   Media Layer                    │
│   (auth/ - 认证层)        │   (media/ - 媒体层)               │
│  • Token 管理             │  • 媒体文件下载                   │
│  • 签名验证               │  • 文件类型检测                   │
│                          │  • 大小验证                       │
└──────────────────────────┴──────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Foundation Layer                          │
│              (config/, security/, types/ - 基础层)            │
│  • 配置管理和合并                                             │
│  • 安全策略 (DM Policy)                                      │
│  • 类型定义和常量                                             │
└─────────────────────────────────────────────────────────────┘

架构说明

渠道适配层 (Channel Adapter): 实现 OpenClaw 插件标准接口，是插件的入口点
网关层 (Gateway): 管理账号级别的网关生命周期，协调 Webhook 和轮询器
入站层 (Inbound): 处理来自微信的消息，包括 Webhook 接收和轮询
出站层 (Outbound): 处理发送到微信的消息，包括文本分片和速率控制
API 客户端层 (API Client): 封装微信客服 API 调用
认证层 (Auth) & 媒体层 (Media): 提供认证和媒体处理服务
基础层 (Foundation): 提供配置、安全策略和类型定义等基础设施

快速开始

前置条件

Node.js >= 18
OpenClaw >= 2026.3.28
企业微信账号
已开通微信客服功能

安装

npm install @wechat/wechat-customer-service-plugin

基础配置

在 OpenClaw 配置文件中添加：

{
  "channels": {
    "wechat-kf": {
      "enabled": true,
      "corpId": "ww1234567890abcdef",
      "corpSecret": "你的客服Secret",
      "dmPolicy": "allowlist",
      "allowFrom": ["external_user_id_1", "external_user_id_2"]
    }
  }
}

启动机器人

openclaw start

安装部署

方式一：通过 npm 安装

# 安装插件
npm install @wechat/wechat-customer-service-plugin

# 配置 OpenClaw
# 编辑配置文件（通常是 openclaw.config.json）

方式二：从源码构建

# 克隆仓库
git clone https://github.com/yourusername/wechat-customer-service-plugin.git
cd wechat-customer-service-plugin

# 安装依赖
npm install

# 构建
npm run build

# 链接到 OpenClaw
npm link

配置指南

单账号配置（推荐新手）

适用于只有一个微信客服账号的场景：

{
  "channels": {
    "wechat-kf": {
      "enabled": true,
      "corpId": "ww1234567890abcdef",
      "corpSecret": "你的客服Secret",
      "name": "客服机器人",
      "dmPolicy": "allowlist",
      "allowFrom": ["*"],
      "pollInterval": 5000,
      "messageLimit": 1000,
      "webhookToken": "your-webhook-token",
      "webhookAesKey": "your-43-character-aes-key-1234567890123"
    }
  }
}

多账号配置（企业级）

适用于需要管理多个微信客服账号的场景：

{
  "channels": {
    "wechat-kf": {
      "defaultAccount": "support",
      "dmPolicy": "allowlist",
      "pollInterval": 5000,
      "accounts": {
        "support": {
          "enabled": true,
          "name": "客服支持",
          "corpId": "ww1111111111111111",
          "corpSecret": "secret-support",
          "allowFrom": ["*"],
          "webhookToken": "token-support",
          "webhookAesKey": "aes-key-support-12345678901234567890123"
        },
        "sales": {
          "enabled": true,
          "name": "销售团队",
          "corpId": "ww2222222222222222",
          "corpSecret": "secret-sales",
          "dmPolicy": "pairing",
          "allowFrom": ["user_a", "user_b", "user_c"],
          "pollInterval": 10000
        },
        "vip": {
          "enabled": false,
          "name": "VIP 客服",
          "corpId": "ww3333333333333333",
          "corpSecret": "secret-vip",
          "dmPolicy": "allowlist",
          "allowFrom": ["vip_user_1", "vip_user_2"]
        }
      }
    }
  }
}

配置项详解

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | enabled | boolean | true | 是否启用该账号 | | corpId | string | - | 必填。企业 ID，在企业微信管理后台获取 | | corpSecret | string | - | 必填。客服 Secret，在客服应用配置中获取 | | name | string | "default" | 账号显示名称，便于识别 | | dmPolicy | string | "allowlist" | 私信策略：allowlist（白名单）、pairing（配对）、open（开放） | | allowFrom | string[] | [] | 允许的外部用户 ID 列表。使用 ["*"] 表示允许所有用户 | | webhookToken | string | - | Webhook 验证 Token | | webhookAesKey | string | - | 消息加密密钥（43 位字符） | | pollInterval | number | 5000 | 消息轮询间隔（毫秒），最小 1000 | | messageLimit | number | 1000 | 单次拉取消息数量（1-1000） | | openKfId | string | - | 指定客服账号 ID（可选） | | defaultAccount | string | - | 多账号模式下的默认账号 ID | | accounts | object | - | 多账号配置对象 |

安全策略说明

1. 白名单模式 (`dmPolicy: "allowlist"`)

最安全的模式，只有 allowFrom 列表中的用户可以与机器人交互。

{
  "dmPolicy": "allowlist",
  "allowFrom": ["external_user_1", "external_user_2"]
}

适用场景：

内部测试
特定客户服务
高安全性要求

2. 配对模式 (`dmPolicy: "pairing"`)

用户首次发送消息时需要管理员手动批准才能继续对话。

{
  "dmPolicy": "pairing"
}

适用场景：

需要审核用户身份
控制服务范围
防止垃圾消息

3. 开放模式 (`dmPolicy: "open"`)

所有用户都可以直接与机器人对话，无需审核。

{
  "dmPolicy": "open",
  "allowFrom": ["*"]
}

适用场景：

公开服务
营销活动
客户咨询

⚠️ 安全提示：开放模式下建议配合其他安全措施（如消息频率限制、内容审核等）。

Webhook 配置步骤

Webhook 模式可以实现实时消息推送，响应速度更快，推荐使用。

第一步：在插件中配置 Webhook 凭证

{
  "channels": {
    "wechat-kf": {
      "corpId": "ww1234567890abcdef",
      "corpSecret": "your-secret",
      "webhookToken": "your-webhook-token",
      "webhookAesKey": "your-43-character-aes-key-1234567890123"
    }
  }
}

webhookToken: 自定义字符串，用于验证请求来源
webhookAesKey: 43 位字符的 AES 密钥，用于消息加解密

第二步：在企业微信后台设置 Webhook URL

登录企业微信管理后台
进入 应用管理 → 客服 → API 配置
设置回调 URL：https://your-domain.com/plugins/wechat-kf
填入与插件配置相同的 Token 和 EncodingAESKey
点击保存并验证

第三步：验证连接

插件会自动响应微信的验证请求。查看日志确认：

[wechat-kf:default] Webhook configured, listening on your-webhook-token
[wechat-kf:default] Webhook verification successful

注意事项

确保服务器 URL 可公网访问
使用 HTTPS 协议（微信要求）
检查防火墙和安全组规则
Token 和 AESKey 必须完全一致

Webhook + 轮询双保险

可以同时启用 Webhook 和轮询，互为备份：

{
  "webhookToken": "token",
  "webhookAesKey": "key",
  "pollInterval": 5000  // 轮询作为备份
}

使用示例

发送消息

插件会自动处理 OpenClaw 机器人的回复消息，无需手动调用。支持：

文本消息：自动分片（最大 2048 字符/片）
图片消息：自动上传并发送
文件消息：支持多种格式
语音/视频：自动处理媒体文件

接收消息

插件支持两种接收模式：

1. Webhook 模式（实时推送）

{
  "webhookToken": "your-token",
  "webhookAesKey": "your-aes-key"
}

优点：实时性强，资源占用少缺点：需要公网访问

2. 轮询模式（主动拉取）

{
  "pollInterval": 5000,
  "messageLimit": 1000
}

优点：无需公网 IP，配置简单缺点：有延迟，资源占用稍高

处理多媒体消息

插件自动处理各种媒体类型：

// 接收图片消息
// 插件自动下载并保存到本地

// 发送图片消息
// 插件自动上传并发送 media_id

媒体文件大小限制：

图片：最大 2MB
语音：最大 2MB
视频：最大 10MB
文件：最大 20MB

常见问题

1. 机器人收不到消息

可能原因：

账号未启用（enabled: false）
corpId 或 corpSecret 配置错误
用户不在 allowFrom 白名单中
轮询间隔设置过长

解决方案：

{
  "enabled": true,
  "corpId": "检查是否正确",
  "corpSecret": "检查是否正确",
  "allowFrom": ["*"],  // 先用 * 测试
  "pollInterval": 5000
}

查看日志：

openclaw logs --channel wechat-kf

2. 认证失败

错误码对照表：

| 错误码 | 说明 | 解决方案 | |--------|------|---------| | 40001 | 无效的 corpSecret | 检查 corpSecret 是否正确 | | 40013 | 无效的 corpId | 检查 corpId 是否正确 | | 42001 | Token 已过期 | 插件会自动刷新，无需处理 | | -1 | 系统繁忙 | 稍后重试 |

3. Webhook 不工作

检查清单：

[ ] Webhook URL 可公网访问
[ ] 使用 HTTPS 协议
[ ] webhookToken 和 webhookAesKey 与企业微信后台设置一致
[ ] 防火墙已开放相应端口
[ ] SSL 证书有效

调试方法：

# 测试 URL 可访问性
curl -I https://your-domain.com/plugins/wechat-kf

# 查看详细日志
openclaw logs --level debug --channel wechat-kf

4. 消息发送失败

常见原因：

文件超过大小限制
媒体格式不支持
达到速率限制
网络超时

解决方案：

{
  "pollInterval": 5000,  // 降低请求频率
  "messageLimit": 500    // 减少单次拉取量
}

5. 多账号切换问题

指定账号发送：

// OpenClaw 会根据消息来源自动选择账号
// 也可以手动指定 defaultAccount

账号优先级：

消息来源账号
defaultAccount 配置
第一个启用的账号

6. 性能优化建议

大流量场景：

{
  "pollInterval": 3000,      // 缩短轮询间隔
  "messageLimit": 1000,      // 最大拉取量
  "enableMessageDedup": true // 启用消息去重
}

低流量场景：

{
  "pollInterval": 10000,  // 延长轮询间隔
  "messageLimit": 100     // 减少单次拉取
}

开发指南

项目结构

wechat-customer-service-plugin/
├── src/
│   ├── api/                    # API 客户端
│   │   ├── client.ts           # HTTP 客户端
│   │   ├── message.ts          # 消息 API
│   │   ├── media.ts            # 媒体 API
│   │   └── types.ts            # API 类型定义
│   ├── auth/                   # 认证模块
│   │   ├── token-manager.ts    # Token 管理
│   │   └── signature.ts        # 签名验证
│   ├── config/                 # 配置管理
│   │   ├── schema.ts           # 配置 Schema
│   │   ├── accounts.ts         # 账号解析
│   │   └── merge.ts            # 配置合并
│   ├── gateway/                # 网关模块
│   │   ├── lifecycle.ts        # 生命周期管理
│   │   └── monitor.ts          # 状态监控
│   ├── inbound/                # 消息接收
│   │   ├── webhook-handler.ts  # Webhook 处理
│   │   ├── poller.ts           # 消息轮询
│   │   ├── message-parser.ts   # 消息解析
│   │   └── event-handler.ts    # 事件处理
│   ├── outbound/               # 消息发送
│   │   ├── message-sender.ts   # 消息发送器
│   │   ├── chunker.ts          # 文本分片
│   │   └── rate-limiter.ts     # 速率限制
│   ├── media/                  # 媒体处理
│   │   ├── downloader.ts       # 文件下载
│   │   ├── type-detector.ts    # 类型检测
│   │   ├── size-validator.ts   # 大小验证
│   │   └── local-resolver.ts   # 本地路径解析
│   ├── security/               # 安全模块
│   │   └── dm-policy.ts        # DM 策略
│   ├── types/                  # 类型定义
│   │   └── config.ts           # 配置类型
│   ├── const.ts                # 常量定义
│   ├── runtime.ts              # 运行时状态
│   └── channel.ts              # 渠道适配器（入口）
├── docs/                       # 文档
│   ├── API.md                  # API 文档
│   ├── CONFIGURATION.md        # 配置文档
│   └── DEVELOPMENT.md          # 开发文档
├── dist/                       # 编译输出
├── package.json                # 项目配置
├── tsconfig.json               # TypeScript 配置
└── README.md                   # 项目说明

本地开发

# 克隆项目
git clone https://github.com/yourusername/wechat-customer-service-plugin.git
cd wechat-customer-service-plugin

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 清理
npm run clean

调试技巧

启用调试日志

# 设置环境变量
export DEBUG=wechat-kf:*

# 或在配置文件中设置
{
  "logging": {
    "level": "debug"
  }
}

测试消息接收

# 使用 curl 模拟 Webhook 请求
curl -X POST https://your-domain.com/plugins/wechat-kf \
  -H "Content-Type: application/json" \
  -d '{"MsgType":"text","Content":"测试消息"}'

查看 Token 状态

// 在代码中添加日志
import { runtime } from './runtime.js';
console.log(runtime.getToken('corpId'));

贡献指南

我们欢迎各种形式的贡献！

如何贡献

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

代码规范

使用 TypeScript 编写代码
遵循项目现有代码风格
添加必要的注释和文档
确保所有测试通过

提交消息规范

类型: 简短描述

详细描述（可选）

关联 Issue（可选）

类型包括：

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构代码
test: 测试相关
chore: 构建/工具链相关

报告问题

发现 bug？请创建 Issue 并包含：

问题描述
复现步骤
期望行为
实际行为
环境信息（Node 版本、OS 等）
错误日志

路线图

已完成 ✅

[x] 基础消息收发
[x] 多账号支持
[x] Webhook 集成
[x] 消息轮询
[x] 媒体文件处理
[x] Token 自动管理
[x] 安全策略

计划中 🚧

[ ] 消息模板支持
[ ] 客服会话管理
[ ] 统计分析功能
[ ] 自动回复规则
[ ] 客服分配策略
[ ] WebSocket 长连接

未来展望 💡

[ ] 智能客服路由
[ ] 多语言支持
[ ] 性能监控面板
[ ] 可视化配置界面

许可证

本项目采用 MIT 许可证。

致谢

感谢所有为本项目做出贡献的开发者！

用 ❤️ 为 OpenClaw 打造

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

微信客服插件

项目介绍

核心功能

技术架构

架构说明

快速开始

前置条件

安装

基础配置

启动机器人

安装部署

方式一：通过 npm 安装

方式二：从源码构建

配置指南

单账号配置（推荐新手）

多账号配置（企业级）

配置项详解

安全策略说明

1. 白名单模式 (dmPolicy: "allowlist")

2. 配对模式 (dmPolicy: "pairing")

3. 开放模式 (dmPolicy: "open")

Webhook 配置步骤

第一步：在插件中配置 Webhook 凭证

第二步：在企业微信后台设置 Webhook URL

第三步：验证连接

注意事项

Webhook + 轮询双保险

使用示例

发送消息

接收消息

1. Webhook 模式（实时推送）

2. 轮询模式（主动拉取）

处理多媒体消息

常见问题

1. 机器人收不到消息

2. 认证失败

3. Webhook 不工作

4. 消息发送失败

5. 多账号切换问题

6. 性能优化建议

开发指南

项目结构

本地开发

调试技巧

启用调试日志

测试消息接收

查看 Token 状态

贡献指南

如何贡献

代码规范

提交消息规范

报告问题

路线图

已完成 ✅

计划中 🚧

未来展望 💡

许可证

相关链接

致谢

1. 白名单模式 (`dmPolicy: "allowlist"`)

2. 配对模式 (`dmPolicy: "pairing"`)

3. 开放模式 (`dmPolicy: "open"`)