@x.ken/wecom

v1.0.2

Published

2 days ago

Clawdbot WeCom (企业微信) integration plugin

0High
0Medium
0Low

x.ken

Clawdbot WeCom Plugin

企业微信（WeCom）集成插件，支持通过企业微信与 AI 进行对话。

功能特性

✅ 企业微信消息接收：支持加密消息解密和多种消息类型（文本、图片、语音、视频、位置、链接）
✅ 企业微信消息发送：通过企业微信官方 API 发送消息
✅ Access Token 管理：自动缓存和刷新 Access Token
✅ 多账号管理：支持配置多个独立账号

快速开始

1. 安装配置

在 ~/.clawdbot/clawdbot.json 中添加：

{
  "plugins": {
    "enabled": ["wecom"]
  },

  "channels": {
    "wecom": {
      "enabled": true,

      // 企业微信应用配置
      "corpid": "ww1234567890abcdef",        // 企业ID
      "corpsecret": "your-corp-secret",      // 应用Secret
      "agentid": 1000002,                    // 应用AgentId
      "token": "your-token",                 // 消息验证Token
      "encodingAESKey": "your-encoding-aes-key", // 消息加密密钥

      // 自定义系统提示词（可选）
      "systemPrompt": "你是一个专业的AI助手"
    }
  }
}

如何获取配置参数：

登录企业微信管理后台
进入"应用管理" → 选择或创建应用
在应用详情页获取：
- AgentId：应用ID
- Secret：点击"查看Secret"获取
在"接收消息"设置中获取：
- Token：点击"随机获取"
- EncodingAESKey：点击"随机获取"
在"我的企业"中查看 企业ID (CorpID)

2. 启动 Gateway

clawdbot gateway run --port 18789

3. 配置企业微信应用

在企业微信管理后台，配置应用回调 URL：

http://your-gateway-host:18789/wecom/message

企业微信会发送 GET 请求验证 URL，插件会自动处理验证流程。

4. 测试接收消息

在企业微信应用中发送消息，Gateway 会自动接收、解密并转发给 Clawdbot 进行 AI 对话。

架构设计

消息接收流程（企业微信 → Clawdbot）

企业微信用户发送消息
    ↓ POST /wecom/message（加密 XML）
Gateway（接收）
    ↓ 验证签名
    ↓ 解密消息
    ↓ 解析 XML
    ↓ 转换为内部格式
Clawdbot Agent（AI 处理）
    ↓ 生成回复
Gateway（发送回复）
    ↓ 调用企业微信 API
企业微信用户接收回复

消息发送流程（Clawdbot → 企业微信）

Clawdbot Agent（生成回复）
    ↓
Gateway（发送）
    ↓
企业微信官方 API（发送）
    ↓
企业微信用户接收

API 端点

GET /wecom/message

企业微信 URL 验证端点（首次配置时使用）

查询参数：

msg_signature: 消息签名
timestamp: 时间戳
nonce: 随机数
echostr: 加密的验证字符串

插件会自动验证签名、解密并返回明文 echostr。

POST /wecom/message

接收企业微信加密消息

Content-Type: text/xml 或 application/xml

查询参数：

msg_signature: 消息签名
timestamp: 时间戳
nonce: 随机数

请求体（XML）：

<xml>
  <ToUserName><![CDATA[corpid]]></ToUserName>
  <Encrypt><![CDATA[加密的消息内容]]></Encrypt>
</xml>

支持的消息类型：

文本消息：直接处理文本内容
图片消息：提取图片 URL 并发送给 Clawdbot
语音消息：显示语音信息（格式、MediaId）
视频消息：显示视频信息（MediaId）
位置消息：格式化位置信息（坐标、标签）
链接消息：提取标题、描述、URL

响应：返回 success 文本（企业微信要求）

GET /wecom/messages?email=xxx

轮询获取待发送的消息（异步模式）

响应格式：

{
  "messages": [
    {
      "text": "回复内容",
      "mediaUrl": "https://..."
    }
  ]
}

配置参数

企业微信官方 API 配置

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | corpid | string | 是 | 企业微信 Corp ID | | corpsecret | string | 是 | 企业微信应用 Secret | | agentid | number | 是 | 企业微信应用 Agent ID | | token | string | 是 | 企业微信应用 Token（用于消息验证）| | encodingAESKey | string | 是 | 消息加密密钥（43位字符）|

如何获取：

登录企业微信管理后台
进入"应用管理" → 选择或创建应用
在应用详情页获取 AgentId 和 Secret
在"接收消息"设置中获取 Token 和 EncodingAESKey
在"我的企业"中查看 企业ID (CorpID)

配置命令：

clawdbot config set channels.wecom.corpid "ww1234567890abcdef"
clawdbot config set channels.wecom.corpsecret "your-corp-secret"
clawdbot config set channels.wecom.agentid 1000002
clawdbot config set channels.wecom.token "your-token"
clawdbot config set channels.wecom.encodingAESKey "your-encoding-aes-key"

可选配置

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | systemPrompt | string | 否 | 自定义系统提示词片段 |

文件结构

clawdbot-wechat-plugin/
├── src/
│   ├── channel.ts          # 渠道插件定义
│   ├── client.ts           # 消息发送客户端
│   ├── config-schema.ts    # 配置 Schema
│   ├── gateway.ts          # Gateway HTTP 路由
│   ├── multipart.ts        # Multipart 解析器
│   ├── runtime.ts          # 运行时管理
│   ├── crypto.ts           # 加密/解密工具
│   ├── message-parser.ts    # 消息解析
│   ├── official-api.ts     # 企业微信官方 API
│   └── access-token.ts     # Access Token 管理
├── index.ts                # 插件入口
├── package.json
├── clawdbot.plugin.json
└── README.md               # 本文档

开发

构建

cd clawdbot-wechat-plugin
pnpm install
pnpm build

故障排查

企业微信发送失败

症状：日志显示 "企业微信 API 调用失败"

解决方法：

检查查 corpid、corpsecret 和 agentid 是否正确
确认收件人 UserID 在企业微信系统中存在
检查消息内容长度（最多 2048 字节）
验证 API 配额是否已用完

消息验证失败

症状：企业微信配置回调 URL 时验证失败