@wecom/wecom-openclaw-plugin 2026.3.30 → 2026.3.31-beta.0

package/README.md

@@ -19,7 +19,7 @@
 
 **WeCom channel plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.
 
-> A bot plugin powered by WeCom AI Bot WebSocket persistent connections. Supports direct messages & group chats, streaming replies, and proactive messaging.
+> A channel plugin powered by WeCom. Supports **Bot mode** (WebSocket long-polling) and **Agent mode** (HTTP webhook with XML encrypted callbacks). Direct messages, group chats, streaming replies, and proactive messaging.
 
 ---
 
@@ -28,13 +28,15 @@
 
 ## ✨ Features
 
-- 🔗 WebSocket persistent connection for stable communication
+- 🔗 **Dual-mode**: Bot (WebSocket) and Agent (HTTP webhook) can run independently or together
 - 💬 Supports both direct messages (DM) and group chat
 - 📤 Proactive messaging to specific users or groups
 - 🖼️ Receives and processes image and file messages with automatic downloading
-- ⏳ Streaming replies with "thinking" placeholder messages
+- ⏳ Streaming replies with "thinking" placeholder messages (Bot mode)
+- 🔐 Agent mode: AES-256-CBC encrypted XML callbacks with SHA1 signature verification
 - 📝 Markdown formatting support for replies
 - 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)
+- 👥 Multi-account support: run multiple WeCom accounts with independent bot/agent configs
 - ⚡ Auto heartbeat keep-alive and reconnection (up to 100 reconnect attempts)
 - 🧙 Interactive CLI setup wizard
 
@@ -89,7 +91,16 @@ openclaw config set channels.wecom.enabled true
 openclaw gateway restart
 ```
 
-### Configuration Reference
+### Mode Overview
+
+The plugin supports two connection modes that can be used independently or together:
+
+| Mode | Connection | Message Format | Use Case |
+|------|-----------|---------------|----------|
+| **Bot** (智能体) | WebSocket long-polling | JSON | Quick setup, streaming replies |
+| **Agent** (自建应用) | HTTP webhook callbacks | XML | Enterprise apps, API-driven messaging |
+
+### Bot Mode Configuration
 
 | Config Path | Description | Options | Default |
 |---|---|---|---|
@@ -103,6 +114,141 @@ openclaw gateway restart
 | `channels.wecom.groupAllowFrom` | Group allowlist (group IDs) | — | `[]` |
 | `channels.wecom.sendThinkingMessage` | Send "thinking" placeholder | `true` / `false` | `true` |
 
+### Agent Mode Configuration
+
+Agent mode uses HTTP webhook callbacks with XML encrypted messages. You need to configure the callback URL in the WeCom admin console under "API Receive" settings.
+
+#### Prerequisites
+
+1. Create a self-built app in [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#apps)
+2. In the app settings, go to "API Receive" (API接收) and configure:
+   - **URL**: `https://<your-gateway-host>/plugins/wecom/agent` (or `/plugins/wecom/agent/<accountId>` for multi-account)
+   - **Token**: auto-generated or custom
+   - **EncodingAESKey**: auto-generated or custom
+3. Note down the **CorpID**, **CorpSecret**, **Token**, and **EncodingAESKey**
+
+#### Quick Setup
+
+```shell
+openclaw config set channels.wecom.agent.corpId <YOUR_CORP_ID>
+openclaw config set channels.wecom.agent.corpSecret <YOUR_CORP_SECRET>
+openclaw config set channels.wecom.agent.agentId <YOUR_AGENT_ID>
+openclaw config set channels.wecom.agent.token <YOUR_CALLBACK_TOKEN>
+openclaw config set channels.wecom.agent.encodingAESKey <YOUR_ENCODING_AES_KEY>
+openclaw config set channels.wecom.enabled true
+openclaw gateway restart
+```
+
+#### JSON Configuration
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "agent": {
+        "corpId": "ww1234567890abcdef",
+        "corpSecret": "your-corp-secret",
+        "agentId": 1000002,
+        "token": "your-callback-token",
+        "encodingAESKey": "your-encoding-aes-key-43-chars"
+      }
+    }
+  }
+}
+```
+
+#### Agent Config Reference
+
+| Config Path | Description | Required |
+|---|---|---|
+| `channels.wecom.agent.corpId` | Enterprise Corp ID | Yes |
+| `channels.wecom.agent.corpSecret` | App secret | Yes |
+| `channels.wecom.agent.agentId` | App agent ID | No (needed for proactive messaging) |
+| `channels.wecom.agent.token` | Callback verification token | Yes |
+| `channels.wecom.agent.encodingAESKey` | Callback encryption key (43 chars) | Yes |
+
+#### Webhook Paths
+
+| Path | Description |
+|---|---|
+| `/plugins/wecom/agent` | Recommended path (single account) |
+| `/plugins/wecom/agent/<accountId>` | Multi-account path |
+| `/wecom/agent` | Legacy compatible path |
+
+### Outbound Delivery (Bot WS → Agent HTTP Fallback)
+
+The plugin uses a **Bot-first, Agent-fallback** strategy for outbound message delivery:
+
+1. **Bot WebSocket available** → send via WS (supports markdown, streaming)
+2. **Bot WS unavailable** → automatically fallback to **Agent HTTP API** (`cgi-bin/message/send`)
+
+This means:
+- **Agent-only accounts** (no Bot configured) can still send proactive messages, cron deliveries, and broadcasts
+- **Target formats** like `party:1`, `tag:Ops`, `user:zhangsan` are fully supported in both paths
+- No manual switching needed — the plugin handles fallback transparently
+
+### Using Both Modes Together
+
+Bot and Agent can run simultaneously on the same account. Bot handles WebSocket streaming; Agent handles HTTP webhook callbacks with API-driven replies.
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "botId": "your-bot-id",
+      "secret": "your-bot-secret",
+      "agent": {
+        "corpId": "ww1234567890abcdef",
+        "corpSecret": "your-corp-secret",
+        "agentId": 1000002,
+        "token": "your-callback-token",
+        "encodingAESKey": "your-encoding-aes-key-43-chars"
+      }
+    }
+  }
+}
+```
+
+### Multi-Account Configuration
+
+Use `accounts` to configure multiple WeCom accounts, each with optional bot and/or agent sub-configs:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "accounts": {
+        "main": {
+          "bot": {
+            "botId": "bot-id-1",
+            "secret": "secret-1"
+          },
+          "agent": {
+            "corpId": "ww1234567890abcdef",
+            "corpSecret": "secret-a",
+            "agentId": 1000002,
+            "token": "token-a",
+            "encodingAESKey": "aes-key-a"
+          }
+        },
+        "support": {
+          "agent": {
+            "corpId": "ww1234567890abcdef",
+            "corpSecret": "secret-b",
+            "agentId": 1000003,
+            "token": "token-b",
+            "encodingAESKey": "aes-key-b"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ---
 
 ## 🔒 Access Control
@@ -198,6 +344,107 @@ In addition to the group allowlist, you can restrict which members within a grou
 
 ---
 
+## ⏰ Cronjob (Scheduled Tasks)
+
+The plugin supports scheduled message delivery via OpenClaw's built-in Cron service. Cron jobs run through the **Agent outbound** channel, so Agent mode must be configured.
+
+### Target Formats
+
+The `delivery.to` field supports the following target formats:
+
+| Format | Target | Example |
+|--------|--------|---------|
+| `party:<id>` | Department (all members) | `party:1` (root dept = all employees) |
+| `dept:<id>` | Department (alias) | `dept:5` |
+| `tag:<id>` | Tag group | `tag:Ops` |
+| `user:<id>` | Specific user | `user:zhangsan` |
+| `group:<id>` | External group chat | `group:wr123abc` |
+| `chat:<id>` | Group chat (alias) | `chat:wc456def` |
+| Pure number | Auto-detected as department | `1` → `party:1` |
+| `wr...` / `wc...` | Auto-detected as group chat | `wr123` → `chatid` |
+| Other string | Auto-detected as user | `zhangsan` → `touser` |
+
+### Method 1: CLI (Recommended — takes effect immediately)
+
+```shell
+openclaw cron add \
+  --name "daily-report" \
+  --agent main \
+  --cron "0 9 * * 1-5" \
+  --message "Good morning! Here is your daily briefing." \
+  --deliver \
+  --delivery-channel wecom \
+  --delivery-to "party:1"
+```
+
+Common CLI commands:
+
+```shell
+openclaw cron list              # List all cron jobs
+openclaw cron enable <id>       # Enable a job
+openclaw cron disable <id>      # Disable a job
+openclaw cron remove <id>       # Remove a job
+openclaw cron run <id>          # Manually trigger a job
+```
+
+### Method 2: Edit `jobs.json` (requires gateway restart)
+
+File path: `~/.openclaw/cron/jobs.json`
+
+```json
+{
+  "version": 1,
+  "jobs": [
+    {
+      "id": "daily-report",
+      "name": "Daily Report",
+      "agentId": "main",
+      "enabled": true,
+      "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "Asia/Shanghai" },
+      "sessionTarget": "isolated",
+      "wakeMode": "now",
+      "payload": {
+        "kind": "agentTurn",
+        "message": "Generate today's briefing and send it.",
+        "deliver": true,
+        "channel": "wecom",
+        "to": "party:1"
+      },
+      "delivery": {
+        "mode": "announce",
+        "channel": "wecom",
+        "to": "party:1",
+        "accountId": "main"
+      },
+      "state": {}
+    }
+  ]
+}
+```
+
+After editing, restart the gateway:
+
+```shell
+openclaw gateway restart
+```
+
+### Method 3: Create via chat (takes effect immediately)
+
+You can ask the AI agent directly in a WeCom conversation:
+
+> "Create a scheduled task: send a daily briefing to the entire company at 9am every weekday"
+
+The agent will call the Cron API to create the job — no restart needed.
+
+### Notes
+
+- Cron jobs use the **Agent outbound** path — Agent mode (`corpId` / `corpSecret` / `agentId`) must be configured.
+- The server IP must be in the WeCom trusted IP allowlist, or configure `egressProxyUrl` for a fixed egress proxy.
+- Jobs created via CLI or chat API take effect immediately. Manual edits to `jobs.json` require `openclaw gateway restart`.
+- For multi-account setups, set `delivery.accountId` to the target account (e.g. `"main"`, `"support"`).
+
+---
+
 ## 📦 Update
 
 ```shell

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
-
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 declare const plugin: {
     id: string;
     name: string;
@@ -7,5 +6,4 @@ declare const plugin: {
     configSchema: Record<string, unknown>;
     register(api: OpenClawPluginApi): void;
 };
-
-export { plugin as default };
+export default plugin;

package/dist/index.js

@@ -0,0 +1,113 @@
+import { emptyPluginConfigSchema } from "./src/openclaw-compat.js";
+import { wecomPlugin } from "./src/channel.js";
+import { createWeComMcpTool } from "./src/mcp/index.js";
+import { setWeComRuntime } from "./src/runtime.js";
+import { CHANNEL_ID, WEBHOOK_PATHS } from "./src/const.js";
+import { handleWecomAgentWebhookRequest } from "./src/agent/webhook.js";
+import { handleWecomWebhookRequest } from "./src/webhook/index.js";
+// ============================================================================
+// 需要自动注入 tools.alsoAllow 的工具名列表
+// ============================================================================
+const REQUIRED_ALSO_ALLOW_TOOLS = ["wecom_mcp"];
+/**
+ * 确保 tools.alsoAllow 中包含插件所需的工具名。
+ *
+ * 逻辑：
+ *  1. 读取当前配置
+ *  2. 检查 tools.alsoAllow 中是否已包含所需工具
+ *  3. 如有缺失，合并写入配置文件
+ *
+ * 幂等操作——重复调用不会产生副作用。
+ * 若 tools.allow 已显式设置（与 alsoAllow 互斥），则跳过注入并打印提示。
+ */
+async function ensureToolsAlsoAllow(api) {
+    try {
+        const cfg = api.runtime.config.loadConfig();
+        const tools = cfg.tools ?? {};
+        // 如果用户显式配置了 tools.allow（全量白名单），则 alsoAllow 与之互斥，
+        // 此时不应自动追加 alsoAllow，避免产生校验冲突
+        if (tools.allow && tools.allow.length > 0) {
+            const missing = REQUIRED_ALSO_ALLOW_TOOLS.filter((t) => !tools.allow.includes(t));
+            if (missing.length > 0) {
+                console.warn(`[wecom] tools.allow 已显式设置，无法自动注入 alsoAllow。` +
+                    `请手动将 ${JSON.stringify(missing)} 加入 tools.allow。`);
+            }
+            return;
+        }
+        const existing = tools.alsoAllow ?? [];
+        const missing = REQUIRED_ALSO_ALLOW_TOOLS.filter((t) => !existing.includes(t));
+        if (missing.length === 0) {
+            // 所有工具已在白名单中，无需操作
+            return;
+        }
+        const merged = [...existing, ...missing];
+        const nextConfig = {
+            ...cfg,
+            tools: {
+                ...tools,
+                alsoAllow: merged,
+            },
+        };
+        await api.runtime.config.writeConfigFile(nextConfig);
+        console.log(`[wecom] 已自动将 ${JSON.stringify(missing)} 加入 tools.alsoAllow`);
+    }
+    catch (err) {
+        // 配置写入失败不应阻断 Gateway 启动
+        console.error(`[wecom] 自动注入 tools.alsoAllow 失败:`, err instanceof Error ? err.message : String(err));
+    }
+}
+const plugin = {
+    id: "wecom-openclaw-plugin",
+    name: "企业微信",
+    description: "企业微信 OpenClaw 插件",
+    configSchema: emptyPluginConfigSchema(),
+    register(api) {
+        setWeComRuntime(api.runtime);
+        api.registerChannel({ plugin: wecomPlugin });
+        // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
+        api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
+        // 注册 Agent 模式 HTTP 路由（prefix match 覆盖带 accountId 的子路径）
+        api.registerHttpRoute({
+            path: WEBHOOK_PATHS.AGENT_PLUGIN,
+            handler: handleWecomAgentWebhookRequest,
+            auth: "plugin",
+            match: "prefix",
+        });
+        api.registerHttpRoute({
+            path: WEBHOOK_PATHS.AGENT,
+            handler: handleWecomAgentWebhookRequest,
+            auth: "plugin",
+            match: "prefix",
+        });
+        // ── 注册 bot Webhook HTTP 路由 ────────────────────────────────────────
+        // 前缀匹配模式，同时覆盖 /plugins/wecom 和 /wecom 路径
+        const webhookRoutes = [WEBHOOK_PATHS.BOT_PLUGIN, WEBHOOK_PATHS.BOT_ALT, WEBHOOK_PATHS.BOT];
+        for (const routePath of webhookRoutes) {
+            api.registerHttpRoute({
+                path: routePath,
+                handler: handleWecomWebhookRequest,
+                auth: "plugin",
+                match: "prefix",
+            });
+        }
+        // ── Gateway 启动时自动确保 tools.alsoAllow 包含 wecom_mcp ──────────
+        // 在 gateway_start 阶段检测并写入，保证插件安装/更新后首次启动即生效
+        // api.on("gateway_start", async () => {
+        //   await ensureToolsAlsoAllow(api);
+        // });
+        // 注入媒体发送指令和文件大小限制提示词（仅对企业微信 channel 生效）
+        api.on("before_prompt_build", (_event, ctx) => {
+            // 只在企业微信 channel 的会话中注入，避免影响其他 channel 插件
+            if (ctx?.channelId !== CHANNEL_ID) {
+                return;
+            }
+            return {
+                appendSystemContext: [
+                    "重要：涉及发送图片/视频/语音/文件给用户时，请务必使用 `MEDIA:` 指令。详见  wecom-send-media 这个 skill（技能）。",
+                    "重要：当需要向用户发送结构化卡片消息（如通知、投票、按钮选择等）时，请在回复中直接输出 JSON 代码块（```json ... ```），其中 card_type 字段标明卡片类型。详见 wecom-send-template-card 技能。"
+                ].join("\n"),
+            };
+        });
+    },
+};
+export default plugin;

package/dist/src/accounts.d.ts

@@ -0,0 +1,57 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { WeComConfig, WeComAccountConfig, ResolvedWeComAccount } from "./utils.js";
+/**
+ * 企业微信多账号配置结构（扩展 WeComConfig）
+ */
+export interface WeComMultiAccountConfig extends WeComConfig {
+    /** 默认账号 ID */
+    defaultAccount?: string;
+    /** 多账号配置 */
+    accounts?: Record<string, WeComAccountConfig>;
+}
+/**
+ * 判断是否为多账号模式（即配置中存在 accounts 字段）。
+ * 用于区分单账号/多账号模式的分支判断，替代 `accountId === DEFAULT_ACCOUNT_ID` 的不可靠判断。
+ */
+export declare function hasMultiAccounts(cfg: OpenClawConfig): boolean;
+/**
+ * 列出所有企业微信账号 ID。
+ * 如果没有 accounts 字段，返回 [DEFAULT_ACCOUNT_ID] 以向后兼容。
+ */
+export declare function listWeComAccountIds(cfg: OpenClawConfig): string[];
+/**
+ * 解析默认账号 ID。
+ *
+ * 优先级：
+ * 1. 显式设置的 defaultAccount
+ * 2. 包含 DEFAULT_ACCOUNT_ID 的账号列表
+ * 3. 字母序第一个账号
+ */
+export declare function resolveDefaultWeComAccountId(cfg: OpenClawConfig): string;
+/**
+ * 解析单个企业微信账号的完整配置。
+ *
+ * 支持：
+ * - 显式指定 accountId → 使用该 accountId
+ * - 未指定 → 使用默认账号
+ * - 单账号模式（无 accounts 字段） → 直接读取顶层配置
+ */
+export declare function resolveWeComAccountMulti(params: {
+    cfg: OpenClawConfig;
+    accountId?: string | null;
+}): ResolvedWeComAccount;
+/**
+ * 列出所有已启用且已配置凭据的账号。
+ */
+export declare function listEnabledWeComAccounts(cfg: OpenClawConfig): ResolvedWeComAccount[];
+/**
+ * 写入企业微信账户配置（自动区分单账号/多账号模式）。
+ *
+ * - 单账号模式（无 accounts 字段）：写入顶层 channels.wecom
+ * - 多账号模式：写入 channels.wecom.accounts[accountId]
+ *
+ * @param cfg  当前全局配置
+ * @param updates  要写入的部分配置字段
+ * @param accountId  目标账号 ID（默认写入默认账号）
+ */
+export declare function setWeComAccountMulti(cfg: OpenClawConfig, updates: Partial<WeComConfig>, accountId?: string): OpenClawConfig;