@mocrane/wecom 2026.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xl370869-art
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/clawdbot.plugin.json

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

package/index.ts

@@ -0,0 +1,28 @@
+import type { OpenClawPluginApi } 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: "wecom",
+  name: "WeCom",
+  description: "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  /**
+   * **register (注册插件)**
+   * 
+   * OpenClaw 插件入口点。
+   * 1. 注入 Runtime 环境 (api.runtime)。
+   * 2. 注册 WeCom 渠道插件 (ChannelPlugin)。
+   * 3. 注册 Webhook HTTP 处理器 (handleWecomWebhookRequest)。
+   */
+  register(api: OpenClawPluginApi) {
+    setWecomRuntime(api.runtime);
+    api.registerChannel({ plugin: wecomPlugin });
+    api.registerHttpHandler(handleWecomWebhookRequest);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@mocrane/wecom",
+  "version": "2026.2.5",
+  "type": "module",
+  "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "clawdbot.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "WeCom",
+      "selectionLabel": "WeCom (plugin)",
+      "detailLabel": "WeCom Bot",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom",
+      "blurb": "Enterprise WeCom intelligent bot (API mode) via encrypted webhooks + passive replies.",
+      "aliases": [
+        "wechatwork",
+        "wework",
+        "qywx",
+        "企微",
+        "企业微信"
+      ],
+      "order": 85
+    },
+    "install": {
+      "npmSpec": "@mocrane/wecom",
+      "localPath": "extensions/wecom",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "fast-xml-parser": "5.3.4",
+    "undici": "^7.20.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.26"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "typescript": "^5.9.3"
+  },
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "WeCom",
+      "selectionLabel": "WeCom (plugin)",
+      "detailLabel": "WeCom Bot",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom",
+      "blurb": "Enterprise WeCom intelligent bot (API mode) via encrypted webhooks + passive replies.",
+      "aliases": [
+        "wechatwork",
+        "wework",
+        "qywx",
+        "企微",
+        "企业微信"
+      ],
+      "order": 85
+    },
+    "install": {
+      "npmSpec": "@mocrane/wecom",
+      "localPath": "extensions/wecom",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,72 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
+
+import type { ResolvedWecomAccount, WecomAccountConfig, WecomConfig } from "./types.js";
+
+function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
+  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listWecomAccountIds(cfg: OpenClawConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultWecomAccountId(cfg: OpenClawConfig): string {
+  const wecomConfig = cfg.channels?.wecom as WecomConfig | undefined;
+  if (wecomConfig?.defaultAccount?.trim()) return wecomConfig.defaultAccount.trim();
+  const ids = listWecomAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): WecomAccountConfig | undefined {
+  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as WecomAccountConfig | undefined;
+}
+
+function mergeWecomAccountConfig(cfg: OpenClawConfig, accountId: string): WecomAccountConfig {
+  const raw = (cfg.channels?.wecom ?? {}) as WecomConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account };
+}
+
+export function resolveWecomAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedWecomAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = (params.cfg.channels?.wecom as WecomConfig | undefined)?.enabled !== false;
+  const merged = mergeWecomAccountConfig(params.cfg, accountId);
+  const enabled = baseEnabled && merged.enabled !== false;
+
+  const token = merged.token?.trim() || undefined;
+  const encodingAESKey = merged.encodingAESKey?.trim() || undefined;
+  const receiveId = merged.receiveId?.trim() ?? "";
+  const configured = Boolean(token && encodingAESKey);
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
+    configured,
+    token,
+    encodingAESKey,
+    receiveId,
+    config: merged,
+  };
+}
+
+export function listEnabledWecomAccounts(cfg: OpenClawConfig): ResolvedWecomAccount[] {
+  return listWecomAccountIds(cfg)
+    .map((accountId) => resolveWecomAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/src/agent/api-client.ts

@@ -0,0 +1,336 @@
+/**
+ * WeCom Agent API 客户端
+ * 管理 AccessToken 缓存和 API 调用
+ */
+
+import crypto from "node:crypto";
+import { API_ENDPOINTS, LIMITS } from "../types/constants.js";
+import type { ResolvedAgentAccount } from "../types/index.js";
+import { readResponseBodyAsBuffer, wecomFetch } from "../http.js";
+import { resolveWecomEgressProxyUrlFromNetwork } from "../config/index.js";
+
+/**
+ * **TokenCache (AccessToken 缓存结构)**
+ * 
+ * 用于缓存企业微信 API 调用所需的 AccessToken。
+ * @property token 缓存的 Token 字符串
+ * @property expiresAt 过期时间戳 (ms)
+ * @property refreshPromise 当前正在进行的刷新 Promise (防止并发刷新)
+ */
+type TokenCache = {
+    token: string;
+    expiresAt: number;
+    refreshPromise: Promise<string> | null;
+};
+
+const tokenCaches = new Map<string, TokenCache>();
+
+/**
+ * **getAccessToken (获取 AccessToken)**
+ * 
+ * 获取企业微信 API 调用所需的 AccessToken。
+ * 具备自动缓存和过期刷新机制。
+ * 
+ * @param agent Agent 账号信息
+ * @returns 有效的 AccessToken
+ */
+export async function getAccessToken(agent: ResolvedAgentAccount): Promise<string> {
+    const cacheKey = `${agent.corpId}:${agent.agentId}`;
+    let cache = tokenCaches.get(cacheKey);
+
+    if (!cache) {
+        cache = { token: "", expiresAt: 0, refreshPromise: null };
+        tokenCaches.set(cacheKey, cache);
+    }
+
+    const now = Date.now();
+    if (cache.token && cache.expiresAt > now + LIMITS.TOKEN_REFRESH_BUFFER_MS) {
+        return cache.token;
+    }
+
+    // 防止并发刷新
+    if (cache.refreshPromise) {
+        return cache.refreshPromise;
+    }
+
+    cache.refreshPromise = (async () => {
+        try {
+            const url = `${API_ENDPOINTS.GET_TOKEN}?corpid=${encodeURIComponent(agent.corpId)}&corpsecret=${encodeURIComponent(agent.corpSecret)}`;
+            const res = await wecomFetch(url, undefined, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+            const json = await res.json() as { access_token?: string; expires_in?: number; errcode?: number; errmsg?: string };
+
+            if (!json?.access_token) {
+                throw new Error(`gettoken failed: ${json?.errcode} ${json?.errmsg}`);
+            }
+
+            cache!.token = json.access_token;
+            cache!.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+            return cache!.token;
+        } finally {
+            cache!.refreshPromise = null;
+        }
+    })();
+
+    return cache.refreshPromise;
+}
+
+/**
+ * **sendText (发送文本消息)**
+ * 
+ * 调用 `message/send` (Agent) 或 `appchat/send` (群聊) 发送文本。
+ * 
+ * @param params.agent 发送方 Agent
+ * @param params.toUser 接收用户 ID (单聊可选，可与 toParty/toTag 同时使用)
+ * @param params.toParty 接收部门 ID (单聊可选)
+ * @param params.toTag 接收标签 ID (单聊可选)
+ * @param params.chatId 接收群 ID (群聊模式必填，互斥)
+ * @param params.text 消息内容
+ */
+export async function sendText(params: {
+    agent: ResolvedAgentAccount;
+    toUser?: string;
+    toParty?: string;
+    toTag?: string;
+    chatId?: string;
+    text: string;
+}): Promise<void> {
+    const { agent, toUser, toParty, toTag, chatId, text } = params;
+    const token = await getAccessToken(agent);
+
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+
+    const body = useChat
+        ? { chatid: chatId, msgtype: "text", text: { content: text } }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: "text",
+            agentid: agent.agentId,
+            text: { content: text }
+        };
+
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = await res.json() as {
+        errcode?: number;
+        errmsg?: string;
+        invaliduser?: string;
+        invalidparty?: string;
+        invalidtag?: string;
+    };
+
+    if (json?.errcode !== 0) {
+        throw new Error(`send failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : ""
+        ].filter(Boolean).join(", ");
+        throw new Error(`send partial failure: ${details}`);
+    }
+}
+
+/**
+ * **uploadMedia (上传媒体文件)**
+ * 
+ * 上传临时素材到企业微信。
+ * 素材有效期为 3 天。
+ * 
+ * @param params.type 媒体类型 (image, voice, video, file)
+ * @param params.buffer 文件二进制数据
+ * @param params.filename 文件名 (需包含正确扩展名)
+ * @returns 媒体 ID (media_id)
+ */
+export async function uploadMedia(params: {
+    agent: ResolvedAgentAccount;
+    type: "image" | "voice" | "video" | "file";
+    buffer: Buffer;
+    filename: string;
+}): Promise<string> {
+    const { agent, type, buffer, filename } = params;
+    const token = await getAccessToken(agent);
+    // 添加 debug=1 参数获取更多错误信息
+    const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
+
+    // DEBUG: 输出上传信息
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${filename}, size=${buffer.length} bytes`);
+
+    // 手动构造 multipart/form-data 请求体
+    // 企业微信要求包含 filename 和 filelength
+    const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+
+    // 根据文件类型设置 Content-Type
+    const contentTypeMap: Record<string, string> = {
+        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+        bmp: "image/bmp", amr: "voice/amr", mp4: "video/mp4",
+    };
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const fileContentType = contentTypeMap[ext] || "application/octet-stream";
+
+    // 构造 multipart body
+    const header = Buffer.from(
+        `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="media"; filename="${filename}"; filelength=${buffer.length}\r\n` +
+        `Content-Type: ${fileContentType}\r\n\r\n`
+    );
+    const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+    const body = Buffer.concat([header, buffer, footer]);
+
+    console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": `multipart/form-data; boundary=${boundary}`,
+            "Content-Length": String(body.length),
+        },
+        body: body,
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+
+    // DEBUG: 输出完整响应
+    console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+
+    if (!json?.media_id) {
+        throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+    return json.media_id;
+}
+
+/**
+ * **sendMedia (发送媒体消息)**
+ * 
+ * 发送图片、音频、视频或文件。需先通过 `uploadMedia` 获取 media_id。
+ * 
+ * @param params.agent 发送方 Agent
+ * @param params.toUser 接收用户 ID (单聊可选)
+ * @param params.toParty 接收部门 ID (单聊可选)
+ * @param params.toTag 接收标签 ID (单聊可选)
+ * @param params.chatId 接收群 ID (群聊模式必填)
+ * @param params.mediaId 媒体 ID
+ * @param params.mediaType 媒体类型
+ * @param params.title 视频标题 (可选)
+ * @param params.description 视频描述 (可选)
+ */
+export async function sendMedia(params: {
+    agent: ResolvedAgentAccount;
+    toUser?: string;
+    toParty?: string;
+    toTag?: string;
+    chatId?: string;
+    mediaId: string;
+    mediaType: "image" | "voice" | "video" | "file";
+    title?: string;
+    description?: string;
+}): Promise<void> {
+    const { agent, toUser, toParty, toTag, chatId, mediaId, mediaType, title, description } = params;
+    const token = await getAccessToken(agent);
+
+    const useChat = Boolean(chatId);
+    const url = useChat
+        ? `${API_ENDPOINTS.SEND_APPCHAT}?access_token=${encodeURIComponent(token)}`
+        : `${API_ENDPOINTS.SEND_MESSAGE}?access_token=${encodeURIComponent(token)}`;
+
+    const mediaPayload = mediaType === "video"
+        ? { media_id: mediaId, title: title ?? "Video", description: description ?? "" }
+        : { media_id: mediaId };
+
+    const body = useChat
+        ? { chatid: chatId, msgtype: mediaType, [mediaType]: mediaPayload }
+        : {
+            touser: toUser,
+            toparty: toParty,
+            totag: toTag,
+            msgtype: mediaType,
+            agentid: agent.agentId,
+            [mediaType]: mediaPayload
+        };
+
+    const res = await wecomFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+    const json = await res.json() as {
+        errcode?: number;
+        errmsg?: string;
+        invaliduser?: string;
+        invalidparty?: string;
+        invalidtag?: string;
+    };
+
+    if (json?.errcode !== 0) {
+        throw new Error(`send ${mediaType} failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+
+    if (json?.invaliduser || json?.invalidparty || json?.invalidtag) {
+        const details = [
+            json.invaliduser ? `invaliduser=${json.invaliduser}` : "",
+            json.invalidparty ? `invalidparty=${json.invalidparty}` : "",
+            json.invalidtag ? `invalidtag=${json.invalidtag}` : ""
+        ].filter(Boolean).join(", ");
+        throw new Error(`send ${mediaType} partial failure: ${details}`);
+    }
+}
+
+/**
+ * **downloadMedia (下载媒体文件)**
+ * 
+ * 通过 media_id 从企业微信服务器下载临时素材。
+ * 
+ * @returns { buffer, contentType }
+ */
+export async function downloadMedia(params: {
+    agent: ResolvedAgentAccount;
+    mediaId: string;
+    maxBytes?: number;
+}): Promise<{ buffer: Buffer; contentType: string; filename?: string }> {
+    const { agent, mediaId } = params;
+    const token = await getAccessToken(agent);
+    const url = `${API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
+
+    const res = await wecomFetch(url, undefined, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+
+    if (!res.ok) {
+        throw new Error(`download failed: ${res.status}`);
+    }
+
+    const contentType = res.headers.get("content-type") || "application/octet-stream";
+    const disposition = res.headers.get("content-disposition") || "";
+    const filename = (() => {
+        // 兼容：filename="a.md" / filename=a.md / filename*=UTF-8''a%2Eb.md
+        const mStar = disposition.match(/filename\*\s*=\s*([^;]+)/i);
+        if (mStar) {
+            const raw = mStar[1]!.trim().replace(/^"(.*)"$/, "$1");
+            const parts = raw.split("''");
+            const encoded = parts.length === 2 ? parts[1]! : raw;
+            try {
+                return decodeURIComponent(encoded);
+            } catch {
+                return encoded;
+            }
+        }
+        const m = disposition.match(/filename\s*=\s*([^;]+)/i);
+        if (!m) return undefined;
+        return m[1]!.trim().replace(/^"(.*)"$/, "$1") || undefined;
+    })();
+
+    // 检查是否返回了错误 JSON
+    if (contentType.includes("application/json")) {
+        const json = await res.json() as { errcode?: number; errmsg?: string };
+        throw new Error(`download failed: ${json?.errcode} ${json?.errmsg}`);
+    }
+
+    const buffer = await readResponseBodyAsBuffer(res, params.maxBytes);
+    return { buffer, contentType, filename };
+}