@marshulll/openclaw-wecom 0.1.4

package/README.en.md

@@ -0,0 +1,98 @@
+# OpenClaw WeCom Plugin (Dual Mode)
+
+English | [中文](README.zh.md)
+
+OpenClaw WeCom plugin supporting **Bot API mode** and **Internal App mode** with multi-account, media, and group chat.
+
+> `docs/TECHNICAL.md` is the source of truth. Read it before development.
+
+## Features
+- Dual mode: Bot API (JSON callback + stream) / App (XML callback + ACK + proactive send)
+- Multi-account: `channels.wecom.accounts`
+- Message types: text / image / voice / video / file (send & receive)
+- Commands: `/help`, `/status`, `/clear`
+- Stability: signature verification, AES decrypt, token cache, rate limit & retries
+- Group chat: uses `appchat/send` when `chatId` is present
+
+## Install
+### npm
+```bash
+openclaw plugins install @marshulll/openclaw-wecom
+openclaw plugins enable openclaw-wecom
+openclaw gateway restart
+```
+
+### Local path
+```bash
+openclaw plugins install --link /path/to/openclaw-wecom
+openclaw plugins enable wecom
+openclaw gateway restart
+```
+
+## Configuration
+Write config to `~/.openclaw/openclaw.json`.  
+Recommended: use main config only; env vars are fallback.
+
+Minimal example: `docs/wecom.config.example.json`  
+Full example: `docs/wecom.config.full.example.json`  
+Install guide: `docs/INSTALL.md`
+
+### Minimal config
+```json5
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "mode": "both",
+      "webhookPath": "/wecom",
+      "token": "BOT_TOKEN",
+      "encodingAESKey": "BOT_AES",
+      "receiveId": "BOT_ID",
+      "corpId": "CORP_ID",
+      "corpSecret": "CORP_SECRET",
+      "agentId": 1000001,
+      "callbackToken": "CALLBACK_TOKEN",
+      "callbackAesKey": "CALLBACK_AES"
+    }
+  }
+}
+```
+
+### Key notes
+- Bot mode `receiveId`: recommended to set **Bot ID (aibotid)** for strict crypto validation
+- App mode decryption uses **CorpID** (`corpId`)
+
+## Webhook setup (WeCom Admin)
+### Bot mode
+- URL: `https://your-domain/wecom`
+- Token: custom string
+- EncodingAESKey: generated in admin
+- Bot ID (aibotid): map to `receiveId`
+
+### App mode
+- URL: `https://your-domain/wecom`
+- Token / EncodingAESKey: map to `callbackToken` / `callbackAesKey`
+- CorpID / AgentID / Secret: map to `corpId` / `agentId` / `corpSecret`
+
+> HTTPS is required. Restart OpenClaw gateway after enabling the plugin.
+
+## Modes
+- `mode: "bot"`: Bot API only
+- `mode: "app"`: App only
+- `mode: "both"`: both modes (default)
+
+## Media handling
+- App mode: downloads inbound media to local temp dir (`media.tempDir`)
+- Bot mode media bridge: if reply payload includes `mediaUrl + mediaType`,
+  and App credentials are present, media will be uploaded and sent
+
+## Troubleshooting
+- Callback verification failed: check Token / AESKey / URL
+- No reply: ensure plugin enabled and gateway restarted
+- Media too large: adjust `media.maxBytes` or send smaller files
+- invalid access_token: verify `corpId/corpSecret/agentId`
+
+## Docs
+- Dev doc: `docs/TECHNICAL.md`
+- Install: `docs/INSTALL.md`
+- Examples: `docs/wecom.config.example.json` / `docs/wecom.config.full.example.json`

package/README.md

@@ -0,0 +1,98 @@
+# OpenClaw 企业微信插件（双模式）
+
+中文 | [English](README.en.md)
+
+OpenClaw WeCom 插件，支持 **智能机器人 API 模式** 与 **自建应用模式**（双模式），并支持多账户、媒体消息与群聊。
+
+> 以 `docs/TECHNICAL.md` 为准；开发前请先阅读。
+
+## 功能概览
+- 双模式：Bot API（JSON 回调 + stream）/ App（XML 回调 + ACK + 主动发送）
+- 多账户：`channels.wecom.accounts`
+- 消息类型：文本 / 图片 / 语音 / 视频 / 文件（收发均支持）
+- 机器人命令：`/help`、`/status`、`/clear`
+- 稳定性：签名校验、AES 解密、token 缓存、限流与重试
+- 群聊：自动识别 `chatId` 并使用 `appchat/send`
+
+## 安装
+### npm 安装
+```bash
+openclaw plugins install @marshulll/openclaw-wecom
+openclaw plugins enable openclaw-wecom
+openclaw gateway restart
+```
+
+### 本地路径加载
+```bash
+openclaw plugins install --link /path/to/openclaw-wecom
+openclaw plugins enable wecom
+openclaw gateway restart
+```
+
+## 配置
+主配置写入：`~/.openclaw/openclaw.json`  
+推荐仅使用主配置；环境变量仅作为兜底。
+
+最小示例：`docs/wecom.config.example.json`  
+全量示例：`docs/wecom.config.full.example.json`  
+安装与配置说明：`docs/INSTALL.md`
+
+### 最小配置示例
+```json5
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "mode": "both",
+      "webhookPath": "/wecom",
+      "token": "BOT_TOKEN",
+      "encodingAESKey": "BOT_AES",
+      "receiveId": "BOT_ID",
+      "corpId": "CORP_ID",
+      "corpSecret": "CORP_SECRET",
+      "agentId": 1000001,
+      "callbackToken": "CALLBACK_TOKEN",
+      "callbackAesKey": "CALLBACK_AES"
+    }
+  }
+}
+```
+
+### 关键字段说明
+- Bot 模式 `receiveId`：建议填写 **Bot ID（aibotid）**，用于回调加解密校验
+- App 模式回调解密使用 **CorpID**（`corpId`）
+
+## 回调配置（企业微信后台）
+### Bot 模式
+- URL：`https://你的域名/wecom`
+- Token：自定义
+- EncodingAESKey：后台生成
+- Bot ID（aibotid）：填写到 `receiveId`
+
+### App 模式
+- URL：`https://你的域名/wecom`
+- Token / EncodingAESKey：后台生成，对应 `callbackToken` / `callbackAesKey`
+- CorpID / AgentID / Secret：分别对应 `corpId` / `agentId` / `corpSecret`
+
+> 两种模式都要求公网 HTTPS；配置完成后请重启 OpenClaw gateway。
+
+## 模式说明
+- `mode: "bot"`：只启用智能机器人 API 模式
+- `mode: "app"`：只启用自建应用模式
+- `mode: "both"`：同时启用两种模式（默认）
+
+## 媒体处理说明
+- App 模式：收到媒体会下载到本地临时目录（可配置 `media.tempDir`）
+- Bot 模式媒体桥接：当 reply payload 含 `mediaUrl + mediaType` 时，
+  若已配置 App 凭据，会自动上传并发送媒体
+
+## 常见问题
+- 回调验证失败：检查 Token / AESKey / URL 是否一致
+- 没有回复：确认已启用插件并重启 gateway
+- 媒体过大：调整 `media.maxBytes` 或发送更小文件
+- invalid access_token：检查 `corpId/corpSecret/agentId`
+
+## 资料入口
+- 开发文档：`docs/TECHNICAL.md`
+- 安装配置：`docs/INSTALL.md`
+- 配置示例：`docs/wecom.config.example.json` / `docs/wecom.config.full.example.json`

package/README.zh.md

@@ -0,0 +1,98 @@
+# OpenClaw 企业微信插件（双模式）
+
+中文 | [English](README.en.md)
+
+OpenClaw WeCom 插件，支持 **智能机器人 API 模式** 与 **自建应用模式**（双模式），并支持多账户、媒体消息与群聊。
+
+> 以 `docs/TECHNICAL.md` 为准；开发前请先阅读。
+
+## 功能概览
+- 双模式：Bot API（JSON 回调 + stream）/ App（XML 回调 + ACK + 主动发送）
+- 多账户：`channels.wecom.accounts`
+- 消息类型：文本 / 图片 / 语音 / 视频 / 文件（收发均支持）
+- 机器人命令：`/help`、`/status`、`/clear`
+- 稳定性：签名校验、AES 解密、token 缓存、限流与重试
+- 群聊：自动识别 `chatId` 并使用 `appchat/send`
+
+## 安装
+### npm 安装
+```bash
+openclaw plugins install @marshulll/openclaw-wecom
+openclaw plugins enable openclaw-wecom
+openclaw gateway restart
+```
+
+### 本地路径加载
+```bash
+openclaw plugins install --link /path/to/openclaw-wecom
+openclaw plugins enable wecom
+openclaw gateway restart
+```
+
+## 配置
+主配置写入：`~/.openclaw/openclaw.json`  
+推荐仅使用主配置；环境变量仅作为兜底。
+
+最小示例：`docs/wecom.config.example.json`  
+全量示例：`docs/wecom.config.full.example.json`  
+安装与配置说明：`docs/INSTALL.md`
+
+### 最小配置示例
+```json5
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "mode": "both",
+      "webhookPath": "/wecom",
+      "token": "BOT_TOKEN",
+      "encodingAESKey": "BOT_AES",
+      "receiveId": "BOT_ID",
+      "corpId": "CORP_ID",
+      "corpSecret": "CORP_SECRET",
+      "agentId": 1000001,
+      "callbackToken": "CALLBACK_TOKEN",
+      "callbackAesKey": "CALLBACK_AES"
+    }
+  }
+}
+```
+
+### 关键字段说明
+- Bot 模式 `receiveId`：建议填写 **Bot ID（aibotid）**，用于回调加解密校验
+- App 模式回调解密使用 **CorpID**（`corpId`）
+
+## 回调配置（企业微信后台）
+### Bot 模式
+- URL：`https://你的域名/wecom`
+- Token：自定义
+- EncodingAESKey：后台生成
+- Bot ID（aibotid）：填写到 `receiveId`
+
+### App 模式
+- URL：`https://你的域名/wecom`
+- Token / EncodingAESKey：后台生成，对应 `callbackToken` / `callbackAesKey`
+- CorpID / AgentID / Secret：分别对应 `corpId` / `agentId` / `corpSecret`
+
+> 两种模式都要求公网 HTTPS；配置完成后请重启 OpenClaw gateway。
+
+## 模式说明
+- `mode: "bot"`：只启用智能机器人 API 模式
+- `mode: "app"`：只启用自建应用模式
+- `mode: "both"`：同时启用两种模式（默认）
+
+## 媒体处理说明
+- App 模式：收到媒体会下载到本地临时目录（可配置 `media.tempDir`）
+- Bot 模式媒体桥接：当 reply payload 含 `mediaUrl + mediaType` 时，
+  若已配置 App 凭据，会自动上传并发送媒体
+
+## 常见问题
+- 回调验证失败：检查 Token / AESKey / URL 是否一致
+- 没有回复：确认已启用插件并重启 gateway
+- 媒体过大：调整 `media.maxBytes` 或发送更小文件
+- invalid access_token：检查 `corpId/corpSecret/agentId`
+
+## 资料入口
+- 开发文档：`docs/TECHNICAL.md`
+- 安装配置：`docs/INSTALL.md`
+- 配置示例：`docs/wecom.config.example.json` / `docs/wecom.config.full.example.json`

package/docs/INSTALL.md

@@ -0,0 +1,103 @@
+# OpenClaw WeCom 插件安装与配置
+
+## 安装
+
+### 方式一：npm 安装
+```bash
+openclaw plugins install @marshulll/openclaw-wecom
+openclaw plugins enable openclaw-wecom
+openclaw gateway restart
+```
+
+### 方式二：本地路径加载
+```bash
+openclaw plugins install --link /path/to/openclaw-wecom
+openclaw plugins enable wecom
+openclaw gateway restart
+```
+
+## 配置
+
+将配置写入 OpenClaw 配置文件（通常在 `~/.openclaw/openclaw.json`）：
+
+- 配置模板（最小）：`docs/wecom.config.example.json`
+- 配置模板（全量）：`docs/wecom.config.full.example.json`
+
+> 推荐仅使用 `~/.openclaw/openclaw.json` 作为主配置来源；`env.vars` 与系统环境变量仅作为兜底。
+
+最小示例（单账户）：
+```json5
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "mode": "both",
+      "webhookPath": "/wecom",
+
+      "token": "BOT_TOKEN",
+      "encodingAESKey": "BOT_AES",
+      "receiveId": "BOT_ID",
+
+      "corpId": "CORP_ID",
+      "corpSecret": "CORP_SECRET",
+      "agentId": 1000001,
+      "callbackToken": "CALLBACK_TOKEN",
+      "callbackAesKey": "CALLBACK_AES"
+    }
+  }
+}
+```
+
+## 环境变量示例（可选）
+
+如果你更希望用环境变量，也可以写在 `~/.openclaw/openclaw.json` 的 `env.vars` 中（优先级低于 `channels.wecom` 配置）：
+
+```json5
+{
+  "env": {
+    "vars": {
+      "WECOM_TOKEN": "BOT_TOKEN",
+      "WECOM_ENCODING_AES_KEY": "BOT_AES",
+      "WECOM_RECEIVE_ID": "BOT_ID",
+      "WECOM_CORP_ID": "CORP_ID",
+      "WECOM_CORP_SECRET": "CORP_SECRET",
+      "WECOM_AGENT_ID": "1000001",
+      "WECOM_CALLBACK_TOKEN": "CALLBACK_TOKEN",
+      "WECOM_CALLBACK_AES_KEY": "CALLBACK_AES",
+      "WECOM_WEBHOOK_PATH": "/wecom"
+    }
+  }
+}
+```
+
+多账户示例（ACCOUNT 为大写）：
+
+```json5
+{
+  "env": {
+    "vars": {
+      "WECOM_SALES_TOKEN": "BOT_TOKEN",
+      "WECOM_SALES_ENCODING_AES_KEY": "BOT_AES",
+      "WECOM_SALES_RECEIVE_ID": "BOT_ID",
+      "WECOM_SALES_CORP_ID": "CORP_ID",
+      "WECOM_SALES_CORP_SECRET": "CORP_SECRET",
+      "WECOM_SALES_AGENT_ID": "1000002",
+      "WECOM_SALES_CALLBACK_TOKEN": "CALLBACK_TOKEN",
+      "WECOM_SALES_CALLBACK_AES_KEY": "CALLBACK_AES",
+      "WECOM_SALES_WEBHOOK_PATH": "/wecom/sales"
+    }
+  }
+}
+```
+
+### 字段说明
+- Bot 模式 `receiveId`：建议填写 **Bot ID（aibotid）**，用于回调加解密校验；不填也可通过，但会降低校验严格性。
+- App 模式回调解密使用 **CorpID**（即 `corpId`），与 Bot 模式的 `receiveId` 无关。
+
+## Webhook 验证
+- Bot 模式与 App 模式都要求公网 HTTPS。
+- 在企业微信后台配置回调 URL。
+
+## 常见问题
+- 回调验证失败：检查 Token / AESKey / URL 是否一致
+- 没有回复：检查 OpenClaw 是否已启用插件并重启 gateway

package/docs/wecom.config.example.json

@@ -0,0 +1,19 @@
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "mode": "both",
+      "webhookPath": "/wecom",
+
+      "token": "BOT_TOKEN",
+      "encodingAESKey": "BOT_AES",
+      "receiveId": "BOT_ID",
+
+      "corpId": "CORP_ID",
+      "corpSecret": "CORP_SECRET",
+      "agentId": 1000001,
+      "callbackToken": "CALLBACK_TOKEN",
+      "callbackAesKey": "CALLBACK_AES"
+    }
+  }
+}

package/docs/wecom.config.full.example.json

@@ -0,0 +1,55 @@
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "mode": "both",
+      "webhookPath": "/wecom",
+
+      "token": "BOT_TOKEN",
+      "encodingAESKey": "BOT_AES",
+      "receiveId": "BOT_ID",
+
+      "corpId": "CORP_ID",
+      "corpSecret": "CORP_SECRET",
+      "agentId": 1000001,
+      "callbackToken": "CALLBACK_TOKEN",
+      "callbackAesKey": "CALLBACK_AES",
+
+      "media": {
+        "tempDir": "/tmp/openclaw-wecom",
+        "retentionHours": 72,
+        "cleanupOnStart": true,
+        "maxBytes": 10485760
+      },
+      "botMediaBridge": true,
+
+      "dm": {
+        "policy": "pairing",
+        "allowFrom": []
+      },
+
+      "defaultAccount": "default",
+      "accounts": {
+        "default": {
+          "mode": "both",
+          "webhookPath": "/wecom",
+          "token": "BOT_TOKEN",
+          "encodingAESKey": "BOT_AES",
+          "receiveId": "BOT_ID",
+          "corpId": "CORP_ID",
+          "corpSecret": "CORP_SECRET",
+          "agentId": 1000001,
+          "callbackToken": "CALLBACK_TOKEN",
+          "callbackAesKey": "CALLBACK_AES",
+          "media": {
+            "tempDir": "/tmp/openclaw-wecom",
+            "retentionHours": 72,
+            "cleanupOnStart": true,
+            "maxBytes": 10485760
+          },
+          "botMediaBridge": true
+        }
+      }
+    }
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "openclaw-wecom",
+  "channels": ["wecom"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@marshulll/openclaw-wecom",
+  "version": "0.1.4",
+  "type": "module",
+  "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
+  "author": "OpenClaw",
+  "main": "wecom/index.ts",
+  "openclaw": {
+    "extensions": [
+      "./wecom/index.ts"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "WeCom",
+      "selectionLabel": "WeCom (plugin)",
+      "detailLabel": "WeCom",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom",
+      "blurb": "Enterprise WeCom: bot API + internal app (dual mode).",
+      "aliases": [
+        "wechatwork",
+        "wework",
+        "qywx",
+        "企微",
+        "企业微信"
+      ],
+      "order": 85
+    },
+    "install": {
+      "npmSpec": "@marshulll/openclaw-wecom",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.25"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^4.3.6",
+    "zod": "^3.23.8"
+  },
+  "keywords": [
+    "openclaw",
+    "wecom",
+    "wechat-work",
+    "channel",
+    "plugin"
+  ],
+  "license": "ISC",
+  "files": [
+    "wecom/**",
+    "docs/INSTALL.md",
+    "docs/wecom.config.example.json",
+    "docs/wecom.config.full.example.json",
+    "openclaw.plugin.json",
+    "README.md",
+    "README.zh.md",
+    "README.en.md"
+  ]
+}

package/wecom/index.ts

@@ -0,0 +1,23 @@
+/**
+ * WeCom dual-mode plugin (bot API + internal app)
+ */
+import type { ClawdbotPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+import { handleWecomWebhookRequest } from "./src/monitor.js";
+import { setWecomRuntime } from "./src/runtime.js";
+import { wecomPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "openclaw-wecom",
+  name: "OpenClaw WeCom",
+  description: "OpenClaw WeCom channel plugin (bot API + internal app)",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setWecomRuntime(api.runtime);
+    api.registerChannel({ plugin: wecomPlugin });
+    api.registerHttpHandler(handleWecomWebhookRequest);
+  },
+};
+
+export default plugin;

package/wecom/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "openclaw-wecom",
+  "channels": ["wecom"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/wecom/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@marshulll/openclaw-wecom",
+  "version": "0.1.4",
+  "type": "module",
+  "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
+  "author": "OpenClaw",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "WeCom",
+      "selectionLabel": "WeCom (plugin)",
+      "detailLabel": "WeCom",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom",
+      "blurb": "Enterprise WeCom: bot API + internal app (dual mode).",
+      "aliases": [
+        "wechatwork",
+        "wework",
+        "qywx",
+        "企微",
+        "企业微信"
+      ],
+      "order": 85
+    },
+    "install": {
+      "npmSpec": "@marshulll/openclaw-wecom",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.25"
+  },
+  "keywords": [
+    "openclaw",
+    "wecom",
+    "wechat-work",
+    "channel",
+    "plugin"
+  ],
+  "license": "ISC"
+}