Enterprise WeCom (WeChat Work) integration plugin for OpenClaw - receives and sends messages with AI agent support
npm install @william.qian/simple-wecom企业微信（WeCom）插件，支持接收和发送消息，包含完整的 AI agent 集成和媒体文件透传。
- ✅ 接收企业微信加密消息（文本、图片等）
- ✅ 调用 OpenClaw AI agent 处理消息
- ✅ 发送文本消息到企业微信
- ✅ 发送图片/文件（从沙箱透传）
- ✅ 自动处理 access_token 缓存
- ✅ URL 验证（企业微信首次配置）
接收文件： ✅ 插件支持接收用户发送的图片、文件等媒体内容。
发送文件： ⚠️ 插件本身不支持直接发送文件。企业微信对临时素材有限制，直接上传的文件用户可能无法访问。
推荐方案：
- 使用 S3 兼容的存储服务（如 US3、阿里云 OSS、AWS S3）
- 配置相应的 OpenClaw skill（如 us3-uploader）
- AI agent 生成文件后，自动上传到云存储并返回下载链接
示例配置：
``json`
{
"skills": {
"us3-uploader": {
"enabled": true,
"config": {
"bucket": "your-bucket",
"region": "cn-bj",
"accessKey": "your-access-key",
"secretKey": "your-secret-key"
}
}
}
}
详见 SANDBOX_MEDIA.md 了解媒体文件处理方案。
插件已包含在 OpenClaw 的 workspace 中，无需额外安装。
#### 2.1 获取企业微信配置信息
在企业微信管理后台获取以下配置信息：
步骤 1：获取企业 ID (corpid)
1. 登录 企业微信管理后台
2. 进入 我的企业 > 企业信息
3. 复制 企业ID（格式如：ww1234567890abcdef）
步骤 2：创建应用并获取配置
1. 进入 应用管理 > 应用 > 创建应用
2. 填写应用名称和描述，创建应用
3. 进入应用详情页面，记录以下信息：
- AgentId：应用的 ID（如：1000002）
- Secret：应用密钥（点击 "查看" 获取）
步骤 3：配置接收消息
1. 在应用详情页，进入 接收消息 设置
2. 点击 设置API接收
3. 自定义 Token 和 EncodingAESKey（或随机生成）
- Token：随机字符串，用于验证请求来源（如：mytoken123）abcdefghijklmnopqrstuvwxyz1234567890ABC
- EncodingAESKey：43位字符，用于消息加解密（如：）
#### 2.2 配置插件
方式 1：使用配置文件（推荐）
在 ~/.openclaw/openclaw.json 中添加配置：
`json`
{
"plugins": {
"entries": {
"simple-wecom": {
"enabled": true,
"config": {
"token": "mytoken123",
"encodingAESKey": "abcdefghijklmnopqrstuvwxyz1234567890ABC",
"corpid": "ww1234567890abcdef",
"corpSecret": "your_app_secret_here",
"agentId": 1000002
}
}
}
}
}
方式 2：使用环境变量
`bash`
export WECOM_TOKEN="mytoken123"
export WECOM_ENCODING_AES_KEY="abcdefghijklmnopqrstuvwxyz1234567890ABC"
export WECOM_CORPID="ww1234567890abcdef"
export WECOM_CORP_SECRET="your_app_secret_here"
export WECOM_AGENT_ID="1000002"
#### 配置项说明
| 配置项 | 说明 | 获取位置 | 示例 |
|--------|------|----------|------|
| token | 自定义 Token，用于验证 URL | 应用管理 > 接收消息 > 设置 API 接收 | mytoken123 |encodingAESKey
| | 43位加密密钥 | 应用管理 > 接收消息 > 设置 API 接收 | abcdefghijklmnopqrstuvwxyz1234567890ABC |corpid
| | 企业 ID | 我的企业 > 企业信息 | ww1234567890abcdef |corpSecret
| | 应用密钥 | 应用管理 > 应用详情 > Secret | your_app_secret_here |agentId
| | 应用 AgentId | 应用管理 > 应用详情 | 1000002 |
注意事项：
- 配置文件优先级高于环境变量
- token 和 encodingAESKey 必须与企业微信后台配置一致corpSecret
- 具有敏感权限，请妥善保管
- 推荐使用配置文件方式，便于管理多个应用
在企业微信管理后台：
1. 进入 应用管理 > 选择你的应用
2. 进入 接收消息 设置
3. 配置回调 URL：
`
http://your-server:18789/simple-wecom/message
或使用 Tailscale/ngrok 等内网穿透：
https://your-domain.com/simple-wecom/message
4. 设置 Token 和 EncodingAESKey（与配置文件一致）
5. 点击 保存 完成配置
`bash`
pnpm gateway
插件会自动加载，监听 /simple-wecom/message 路径。
用户在企业微信中发送消息：
`
你好，请帮我生成一张图表
插件会：
1. 接收并解密消息
2. 调用 OpenClaw AI agent 处理
3. AI 生成回复（可能包含文本和图片）
4. 自动发送回复到企业微信
AI agent 在沙箱中生成图片后，会返回路径：
`
media/inbound/chart.png
插件会自动：
1. 使用 loadWebMedia() 读取文件media_id
2. 上传到企业微信获取
3. 发送图片消息给用户
`
extensions/simple-wecom/
├── index.ts # 主插件文件（消息接收+发送）
├── send.ts # 发送模块（已集成到 index.ts）
├── examples.ts # 使用示例
├── SANDBOX_MEDIA.md # 沙箱媒体透传方案文档
├── package.json
└── README.md # 本文件
`
企业微信 → Gateway HTTP → 解密 → AI Agent → 生成回复 → 上传媒体 → 企业微信
1. 消息接收（handleSimpleWecomMessage）
- GET 请求：URL 验证
- POST 请求：接收加密消息
2. 消息处理（handleWeComTextMessage）api.runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher()
- 调用
- 处理 AI agent 返回的回复
3. 消息发送（sendWeComMessage）uploadMedia
- 上传媒体文件（）
- 发送文本消息
- 发送图片/文件消息
沙箱路径处理：
`typescript
// AI 返回相对路径
"media/inbound/chart.png"
// 转换为绝对路径
"~/.openclaw/workspace/media/inbound/chart.png"
// 使用 loadWebMedia 读取
const media = await loadWebMedia(absolutePath);
// 上传到企业微信
const mediaId = await uploadMedia(media.buffer, 'image', ...);
`
支持的路径格式：
- 相对路径：media/inbound/file.jpg
- 绝对路径：
- file:// URL：
- HTTP URL：
`bash启动 Gateway 查看日志
pnpm gateway
$3
使用企业微信管理后台的 测试消息 功能：
1. 进入应用管理 > 接收消息
2. 点击 测试消息
3. 发送测试文本
查看日志输出：
=== [simple-wecom] Received Encrypted Message ===
Headers: ...
Query: ...
XML Body: ...=== [simple-wecom] Decrypted Message ===
...
=== [simple-wecom] Parsed Message ===
{
"ToUserName": "...",
"FromUserName": "...",
"MsgType": "text",
"Content": "你好"
}
$3
#### 方式 1：使用测试脚本
项目提供了测试脚本
，可以快速测试发送功能：设置环境变量：
`bash
export WECOM_CORPID="ww1234567890abcdef"
export WECOM_CORP_SECRET="your_app_secret_here"
export WECOM_AGENT_ID="1000002"
export WECOM_TEST_USER="user@company.com" # 接收测试消息的用户账号
`运行测试：
bash
测试文本消息
npm test测试图片消息（提供图片路径）
npm test /path/to/image.jpg
`测试脚本会执行：
1. 验证所有必需的配置是否已设置
2. 发送测试文本消息
3. 发送测试图片消息（如果提供了路径）
预期输出：
🚀 WeCom Plugin Test Suite
==================================================
CorpID: ww1234567890abcdef
AgentID: 1000002
Test User: user@company.com
==================================================
📝 Testing text message...
✅ Text message sent successfully🖼️ Testing image message...
✅ Image message sent successfully
✨ Test completed!
#### 方式 2：使用自定义脚本
可以参考测试脚本创建自己的发送逻辑。
常见问题
$3
原因： 配置未正确设置或格式错误。
解决：
1. 检查
配置文件：
`bash
cat ~/.openclaw/openclaw.json
`
2. 确认配置项格式正确（注意 是数字类型）
3. 重启 Gateway 使配置生效：
`bash
# Ctrl+C 停止，然后重新启动
pnpm gateway
`
4. 查看启动日志，确认配置已加载：
[simple-wecom] WECOM_TOKEN: SET
[simple-wecom] WECOM_CORPID: SET
...
$3
原因： Token 配置不正确或签名验证失败。
解决：
1. 检查
中的 token 是否与企业微信后台一致
2. 查看日志确认签名验证过程
3. 确保 Gateway 正常运行且可访问$3
原因： 回调 URL 无法访问或配置错误。
解决：
1. 确认 Gateway 正在运行：
pnpm gateway
2. 测试回调 URL 是否可访问：
bash
curl http://localhost:18789/simple-wecom/message
`
3. 如果使用内网穿透，检查穿透服务是否正常$3
原因： 文件路径错误或权限问题。
解决：
1. 检查文件是否存在：
bash
ls -la ~/.openclaw/workspace/media/inbound/
`
2. 查看日志中的路径转换：
[wecom] Sending media to user123
3. 确认 能读取文件$3
原因： CorpSecret 错误或企业微信限制。
解决：
1. 检查
corpSecret 是否正确
2. 确认应用有 "发送消息" 权限
3. 查看日志中的错误信息$3
$3
如需支持多个企业微信应用，可以：
1. 为每个应用创建独立的插件实例
2. 使用不同的回调路径（如
/simple-wecom/app1, /simple-wecom/app2）$3
修改
handleWeComTextMessage 函数，添加自定义逻辑：`typescript
// 检测特定命令
if (rawBody.startsWith('/help')) {
// 发送帮助信息
await sendWeComMessage({
toUser: senderId,
agentId,
corpId,
corpSecret,
text: "使用帮助：...",
});
return;
}// 其他自定义处理...
`$3
当前版本支持单聊，如需支持群聊：
1. 解析
字段（判断是群聊还是单聊）
2. 调整 toUser` 为群 ID- SANDBOX_MEDIA.md - 沙箱媒体透传详细方案
- examples.ts - 代码示例
- OpenClaw Documentation
- 企业微信 API 文档
如有问题，请：
1. 查看 SANDBOX_MEDIA.md 中的调试技巧
2. 检查 Gateway 日志输出
3. 提交 Issue 到 OpenClaw 仓库
ISC