Simple WeCom Plugin

企业微信（WeCom）插件，支持接收和发送消息，包含完整的 AI agent 集成和媒体文件透传。

功能特性

• ✅ 接收企业微信加密消息（文本、图片等）
• ✅ 调用 OpenClaw AI agent 处理消息
• ✅ 发送文本消息到企业微信
• ✅ 发送图片/文件（从沙箱透传）
• ✅ 自动处理 access_token 缓存
• ✅ URL 验证（企业微信首次配置）

⚠️ 重要说明

文件接收与发送

接收文件： ✅ 插件支持接收用户发送的图片、文件等媒体内容。

发送文件： ⚠️ 插件本身不支持直接发送文件。企业微信对临时素材有限制，直接上传的文件用户可能无法访问。

推荐方案：

• 使用 S3 兼容的存储服务（如 US3、阿里云 OSS、AWS S3）
• 配置相应的 OpenClaw skill（如 us3-uploader）
• AI agent 生成文件后，自动上传到云存储并返回下载链接

示例配置：

{
  "skills": {
    "us3-uploader": {
      "enabled": true,
      "config": {
        "bucket": "your-bucket",
        "region": "cn-bj",
        "accessKey": "your-access-key",
        "secretKey": "your-secret-key"
      }
    }
  }
}

详见 SANDBOX_MEDIA.md 了解媒体文件处理方案。

快速开始

1. 安装依赖

插件已包含在 OpenClaw 的 workspace 中，无需额外安装。

2. 配置企业微信

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）
   • EncodingAESKey：43位字符，用于消息加解密（如：abcdefghijklmnopqrstuvwxyz1234567890ABC）

2.2 配置插件

方式 1：使用配置文件（推荐）

在 ~/.openclaw/openclaw.json 中添加配置：

{
  "plugins": {
    "entries": {
      "simple-wecom": {
        "enabled": true,
        "config": {
          "token": "mytoken123",
          "encodingAESKey": "abcdefghijklmnopqrstuvwxyz1234567890ABC",
          "corpid": "ww1234567890abcdef",
          "corpSecret": "your_app_secret_here",
          "agentId": 1000002
        }
      }
    }
  }
}

方式 2：使用环境变量

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 具有敏感权限，请妥善保管
• 推荐使用配置文件方式，便于管理多个应用

3. 配置企业微信接收消息

在企业微信管理后台：

1. 进入 应用管理 > 选择你的应用

2. 进入 接收消息 设置

3. 配置回调 URL：

   http://your-server:18789/simple-wecom/message

   或使用 Tailscale/ngrok 等内网穿透：

   https://your-domain.com/simple-wecom/message

4. 设置 Token 和 EncodingAESKey（与配置文件一致）

5. 点击 保存 完成配置

4. 启动 OpenClaw Gateway

pnpm gateway

插件会自动加载，监听 /simple-wecom/message 路径。

使用示例

接收消息

用户在企业微信中发送消息：

你好，请帮我生成一张图表

插件会：

1. 接收并解密消息
2. 调用 OpenClaw AI agent 处理
3. AI 生成回复（可能包含文本和图片）
4. 自动发送回复到企业微信

发送媒体文件

AI agent 在沙箱中生成图片后，会返回路径：

media/inbound/chart.png

插件会自动：

1. 使用 loadWebMedia() 读取文件
2. 上传到企业微信获取 media_id
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）
   • 发送文本消息
   • 发送图片/文件消息

媒体透传

沙箱路径处理：

// 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
• 绝对路径：~/.openclaw/workspace/media/inbound/file.jpg
• file:// URL：file://~/.openclaw/workspace/media/inbound/file.jpg
• HTTP URL：http://example.com/image.jpg

详见 SANDBOX_MEDIA.md

调试

查看日志

# 启动 Gateway 查看日志
pnpm gateway

# 查看插件加载状态
[simple-wecom] WECOM_TOKEN: SET
[simple-wecom] WECOM_ENCODING_AES_KEY: SET
[simple-wecom] WECOM_CORPID: SET
[simple-wecom] WECOM_CORP_SECRET: SET
[simple-wecom] WECOM_AGENT_ID: SET
[simple-wecom] simple-wecom plugin registered: listening at /simple-wecom/message

测试消息接收

使用企业微信管理后台的 测试消息 功能：

1. 进入应用管理 > 接收消息
2. 点击 测试消息
3. 发送测试文本

查看日志输出：

=== [simple-wecom] Received Encrypted Message ===
Headers: ...
Query: ...
XML Body: ...

=== [simple-wecom] Decrypted Message ===
<xml>...</xml>

=== [simple-wecom] Parsed Message ===
{
  "ToUserName": "...",
  "FromUserName": "...",
  "MsgType": "text",
  "Content": "你好"
}

测试发送消息

方式 1：使用测试脚本

项目提供了测试脚本 test.ts，可以快速测试发送功能：

设置环境变量：

export WECOM_CORPID="ww1234567890abcdef"
export WECOM_CORP_SECRET="your_app_secret_here"
export WECOM_AGENT_ID="1000002"
export WECOM_TEST_USER="[email protected]"  # 接收测试消息的用户账号

运行测试：

# 测试文本消息
npm test

# 测试图片消息（提供图片路径）
npm test /path/to/image.jpg

测试脚本会执行：

1. 验证所有必需的配置是否已设置
2. 发送测试文本消息
3. 发送测试图片消息（如果提供了路径）

预期输出：

🚀 WeCom Plugin Test Suite
==================================================
CorpID: ww1234567890abcdef
AgentID: 1000002
Test User: [email protected]
==================================================
📝 Testing text message...
✅ Text message sent successfully

🖼️  Testing image message...
✅ Image message sent successfully

✨ Test completed!

方式 2：使用自定义脚本

可以参考测试脚本创建自己的发送逻辑。

常见问题

Q1: 配置项缺失或未生效

原因： 配置未正确设置或格式错误。

解决：

1. 检查 ~/.openclaw/openclaw.json 配置文件：

   cat ~/.openclaw/openclaw.json

2. 确认配置项格式正确（注意 agentId 是数字类型）
3. 重启 Gateway 使配置生效：

   # Ctrl+C 停止，然后重新启动
   pnpm gateway

4. 查看启动日志，确认配置已加载：

   [simple-wecom] WECOM_TOKEN: SET
   [simple-wecom] WECOM_CORPID: SET
   ...

Q2: 企业微信返回 "Token 验证失败"

原因： Token 配置不正确或签名验证失败。

解决：

1. 检查 openclaw.json 中的 token 是否与企业微信后台一致
2. 查看日志确认签名验证过程
3. 确保 Gateway 正常运行且可访问

Q2: 收不到消息

原因： 回调 URL 无法访问或配置错误。

解决：

1. 确认 Gateway 正在运行：pnpm gateway
2. 测试回调 URL 是否可访问：

   curl http://localhost:18789/simple-wecom/message

3. 如果使用内网穿透，检查穿透服务是否正常

Q3: 收不到消息

原因： 文件路径错误或权限问题。

解决：

1. 检查文件是否存在：

   ls -la ~/.openclaw/workspace/media/inbound/

2. 查看日志中的路径转换：

   [wecom] Sending media to user123

3. 确认 loadWebMedia() 能读取文件

Q4: 图片发送失败

原因： CorpSecret 错误或企业微信限制。

解决：

1. 检查 corpSecret 是否正确
2. 确认应用有 "发送消息" 权限
3. 查看日志中的错误信息

Q5: access_token 过期

多账号支持

如需支持多个企业微信应用，可以：

1. 为每个应用创建独立的插件实例
2. 使用不同的回调路径（如 /simple-wecom/app1, /simple-wecom/app2）

自定义消息处理

修改 handleWeComTextMessage 函数，添加自定义逻辑：

// 检测特定命令
if (rawBody.startsWith('/help')) {
  // 发送帮助信息
  await sendWeComMessage({
    toUser: senderId,
    agentId,
    corpId,
    corpSecret,
    text: "使用帮助：...",
  });
  return;
}

// 其他自定义处理...

群聊支持

当前版本支持单聊，如需支持群聊：

1. 解析 ChatType 字段（判断是群聊还是单聊）
2. 调整 toUser 为群 ID
3. 处理 @提及 逻辑

相关文档

• SANDBOX_MEDIA.md - 沙箱媒体透传详细方案
• examples.ts - 代码示例
• OpenClaw Documentation
• 企业微信 API 文档

技术支持

如有问题，请：

1. 查看 SANDBOX_MEDIA.md 中的调试技巧
2. 检查 Gateway 日志输出
3. 提交 Issue 到 OpenClaw 仓库

许可证

ISC