@wecom/wecom-openclaw-plugin 2026.4.10-beta.1 → 2026.4.21-beta.0

package/README.md

@@ -479,13 +479,7 @@ 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 the WeCom Agent mode (`corpId` + `corpSecret` + `agentId`) must be configured for the account used by the cron job.
-
-> **Important**: The `--agent` (CLI) or `agentId` (jobs.json) refers to the **OpenClaw agent** that processes the cron job. This OpenClaw agent must be bound (via `bindings`) to a WeCom account that has Agent mode configured. If the bound WeCom account is Bot-only (no `agent` sub-config), delivery will fail with:
-> ```
-> WSClient not connected for account <name> and Agent mode is not configured.
-> ```
-> If `--agent` is omitted, the cron job uses the default OpenClaw agent. Make sure its bound WeCom account (or the `defaultAccount`) has Agent mode enabled.
+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
 
@@ -510,6 +504,7 @@ The `delivery.to` field supports the following target formats:
 ```shell
 openclaw cron add \
   --name "daily-report" \
+  --agent main \
   --cron "0 9 * * 1-5" \
   --tz "Asia/Shanghai" \
   --message "Good morning! Here is your daily briefing." \
@@ -519,7 +514,6 @@ openclaw cron add \
 ```
 
 > **Note**: `--announce` enables delivery mode (broadcasts the AI response to the target chat). Use `--no-deliver` to keep output internal. The deprecated `--deliver` flag is an alias for `--announce`.
-> You can specify `--agent <agentId>` to select a specific OpenClaw agent (e.g. `--agent main`). The agent must be bound to a WeCom account with Agent mode configured.
 
 Common CLI commands:
 

package/dist/index.js

@@ -1,6 +1,7 @@
 import { emptyPluginConfigSchema } from "./src/openclaw-compat.js";
 import { wecomPlugin } from "./src/channel.js";
 import { createWeComMcpTool } from "./src/mcp/index.js";
+import { getSessionChatInfo } from "./src/state-manager.js";
 import { setWeComRuntime } from "./src/runtime.js";
 import { CHANNEL_ID, WEBHOOK_PATHS } from "./src/const.js";
 import { createWecomAgentWebhookHandler } from "./src/agent/webhook.js";
@@ -14,7 +15,23 @@ const plugin = {
         setWeComRuntime(api.runtime);
         api.registerChannel({ plugin: wecomPlugin });
         // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
-        api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
+        api.registerTool((ctx) => {
+            const trustedRequesterUserId = ctx.messageChannel === CHANNEL_ID ? ctx.requesterSenderId?.trim() ?? undefined : undefined;
+            // 按 sessionKey 精确取回「原始大小写」的 chatId / chatType。
+            // 数据由 monitor.ts 在消息入站时通过 setSessionChatInfo 写入，
+            // 避免 parseSessionKeyChat 反解导致 chatId 被 OpenClaw core 小写化
+            // （小写后的 chatId 调用企业微信 aibot_send_biz_msg 会报 invalid chatid）。
+            const sessionChat = getSessionChatInfo(ctx.sessionKey);
+            console.log(`[mcp] registerTool ctx: sessionKey="${ctx.sessionKey}", messageChannel="${ctx.messageChannel}", ` +
+                `requesterSenderId="${ctx.requesterSenderId}", agentAccountId="${ctx.agentAccountId}", ` +
+                `sessionChat=${JSON.stringify(sessionChat)}`);
+            return createWeComMcpTool({
+                requesterUserId: trustedRequesterUserId,
+                accountId: ctx.agentAccountId,
+                chatId: sessionChat?.chatId,
+                chatType: sessionChat?.chatType,
+            });
+        }, { name: "wecom_mcp" });
         const agentWebhookHandler = createWecomAgentWebhookHandler(api.runtime);
         // 注册 Agent 模式 HTTP 路由（prefix match 覆盖带 accountId 的子路径）
         api.registerHttpRoute({

package/dist/src/accounts.d.ts

@@ -1,4 +1,4 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import type { WeComConfig, WeComAccountConfig, ResolvedWeComAccount } from "./utils.js";
 /**
  * 企业微信多账号配置结构（扩展 WeComConfig）

package/dist/src/agent/handler.d.ts

@@ -3,7 +3,7 @@
  * 处理 XML 格式回调
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
 import type { ResolvedAgentAccount } from "../types/index.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 /**

package/dist/src/agent/webhook.d.ts

@@ -7,7 +7,7 @@
  * 3. POST → XML body 解密 → 调用 handleAgentWebhook
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
 import type { ResolvedAgentAccount } from "../types/index.js";
 export type AgentWebhookTarget = {
     agent: ResolvedAgentAccount;

package/dist/src/channel.js

@@ -16,7 +16,7 @@ import { startWebhookGateway, stopWebhookGateway } from "./webhook/index.js";
  * 优先 Bot WebSocket，不可用时自动回退到 Agent HTTP API
  */
 async function sendWeComMessage({ to, content, accountId, cfg, }) {
-    const resolvedAccountId = accountId ?? (cfg ? resolveDefaultWeComAccountId(cfg) : DEFAULT_ACCOUNT_ID);
+    const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
     // 从 to 中提取目标（格式是 "${CHANNEL_ID}:xxx" 或直接是目标字符串）
     const channelPrefix = new RegExp(`^${CHANNEL_ID}:`, "i");
     const chatId = to.replace(channelPrefix, "");
@@ -264,7 +264,7 @@ export const wecomPlugin = {
             return sendWeComMessage({ to, content: text, accountId: accountId ?? undefined, cfg });
         },
         sendMedia: async ({ to, text, mediaUrl, mediaLocalRoots, accountId, cfg }) => {
-            const resolvedAccountId = accountId ?? (cfg ? resolveDefaultWeComAccountId(cfg) : DEFAULT_ACCOUNT_ID);
+            const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
             const channelPrefix = new RegExp(`^${CHANNEL_ID}:`, "i");
             const chatId = to.replace(channelPrefix, "");
             // 如果没有 mediaUrl，fallback 为纯文本
@@ -508,7 +508,7 @@ export const wecomPlugin = {
             });
         },
         logoutAccount: async ({ cfg, accountId }) => {
-            const resolvedAccountId = accountId ?? resolveDefaultWeComAccountId(cfg);
+            const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
             const isMulti = hasMultiAccounts(cfg);
             let nextCfg = { ...cfg };
             let cleared = false;

package/dist/src/const.d.ts

@@ -48,6 +48,10 @@ export declare const MEDIA_IMAGE_PLACEHOLDER = "<media:image>";
 export declare const MEDIA_DOCUMENT_PLACEHOLDER = "<media:document>";
 /** 获取 MCP 配置的 WebSocket 命令 */
 export declare const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
+/** 发送业务消息的 WebSocket 命令（如文档授权卡片） */
+export declare const AIBOT_SEND_BIZ_MSG_CMD = "aibot_send_biz_msg";
+/** 业务消息超时时间（毫秒） */
+export declare const BIZ_MSG_SEND_TIMEOUT_MS = 10000;
 /** MCP 配置拉取超时时间（毫秒） */
 export declare const MCP_CONFIG_FETCH_TIMEOUT_MS = 15000;
 /** 默认媒体大小上限（MB） */

package/dist/src/const.js

@@ -64,6 +64,10 @@ export const MEDIA_DOCUMENT_PLACEHOLDER = "<media:document>";
 // ============================================================================
 /** 获取 MCP 配置的 WebSocket 命令 */
 export const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
+/** 发送业务消息的 WebSocket 命令（如文档授权卡片） */
+export const AIBOT_SEND_BIZ_MSG_CMD = "aibot_send_biz_msg";
+/** 业务消息超时时间（毫秒） */
+export const BIZ_MSG_SEND_TIMEOUT_MS = 10_000;
 /** MCP 配置拉取超时时间（毫秒） */
 export const MCP_CONFIG_FETCH_TIMEOUT_MS = 15_000;
 // ============================================================================

package/dist/src/dynamic-agent.d.ts

@@ -4,7 +4,7 @@
  * 为每个用户/群组自动生成独立的 Agent ID，实现会话隔离。
  * 参考: openclaw-plugin-wecom/dynamic-agent.js
  */
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 export interface DynamicAgentConfig {
     enabled: boolean;
     dmCreateAgent: boolean;

package/dist/src/dynamic-routing.d.ts

@@ -3,7 +3,7 @@
  * 提供统一的路由注入接口。
  */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 /**
  * 路由对象（从 core.channel.routing.resolveAgentRoute 返回）
  */

package/dist/src/mcp/index.d.ts

@@ -2,5 +2,5 @@
  * MCP 模块统一导出
  */
 export { createWeComMcpTool } from "./tool.js";
-export { sendJsonRpc, clearCategoryCache, McpRpcError, McpHttpError, type McpToolInfo } from "./transport.js";
+export { sendJsonRpc, clearCategoryCache, clearAccountCache, resolveCurrentAccountId, McpRpcError, McpHttpError, type McpToolInfo } from "./transport.js";
 export { cleanSchemaForGemini } from "./schema.js";

package/dist/src/mcp/index.js

@@ -2,5 +2,9 @@
  * MCP 模块统一导出
  */
 export { createWeComMcpTool } from "./tool.js";
-export { sendJsonRpc, clearCategoryCache, McpRpcError, McpHttpError } from "./transport.js";
+export { sendJsonRpc, clearCategoryCache, clearAccountCache, resolveCurrentAccountId, McpRpcError, McpHttpError } from "./transport.js";
 export { cleanSchemaForGemini } from "./schema.js";
+// 注意：parseSessionKeyChat 已废弃不再导出。
+//   OpenClaw core 构建 sessionKey 时会把 chatId 小写化，
+//   企业微信接口（如 aibot_send_biz_msg）是大小写敏感的，反解结果不可用。
+//   chatId 请通过 state-manager 的 getSessionChatInfo(sessionKey) 获取。

package/dist/src/mcp/interceptors/biz-error.js

@@ -17,9 +17,9 @@ import { clearCategoryCache } from "../transport.js";
  * 这些错误码出现在 MCP 工具调用返回的 content 文本中（业务层面），
  * 与 JSON-RPC 层面的错误码不同，需要在此处额外检测。
  *
- * - 850002: 机器人未被授权使用对应能力，需清理缓存以便下次重新拉取配置
+ * - 850001/ 851014: 机器人授权过期/ 重置，需清理缓存以便下次重新拉取配置
  */
-const BIZ_CACHE_CLEAR_ERROR_CODES = new Set([850002]);
+const BIZ_CACHE_CLEAR_ERROR_CODES = new Set([850001, 851014]);
 // ============================================================================
 // 拦截器实现
 // ============================================================================
@@ -29,7 +29,7 @@ export const bizErrorInterceptor = {
     match: () => true,
     /** 检查返回结果中的业务错误码，必要时清理缓存 */
     afterCall(ctx, result) {
-        checkBizErrorAndClearCache(result, ctx.category);
+        checkBizErrorAndClearCache(result, ctx);
         // 不修改 result，透传给下一个拦截器
         return result;
     },
@@ -40,7 +40,7 @@ export const bizErrorInterceptor = {
 /**
  * 检查 tools/call 的返回结果中是否包含需要清理缓存的业务错误码
  */
-function checkBizErrorAndClearCache(result, category) {
+function checkBizErrorAndClearCache(result, ctx) {
     if (!result || typeof result !== "object")
         return;
     const { content } = result;
@@ -52,8 +52,13 @@ function checkBizErrorAndClearCache(result, category) {
         try {
             const parsed = JSON.parse(item.text);
             if (typeof parsed.errcode === "number" && BIZ_CACHE_CLEAR_ERROR_CODES.has(parsed.errcode)) {
-                console.log(`[mcp] 检测到业务错误码 ${parsed.errcode} (category="${category}")，清理缓存`);
-                clearCategoryCache(category);
+                const accountId = ctx.accountId;
+                if (!accountId) {
+                    console.warn(`[mcp] 检测到业务错误码 ${parsed.errcode} (category="${ctx.category}")，但 ctx.accountId 为空，跳过缓存清理`);
+                    return;
+                }
+                console.log(`[mcp] 检测到业务错误码 ${parsed.errcode} (accountId="${accountId}", category="${ctx.category}")，清理缓存`);
+                clearCategoryCache(accountId, ctx.category);
                 return;
             }
         }

package/dist/src/mcp/interceptors/doc-auth-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 文档授权错误拦截器
+ *
+ * 当 category=doc 的 MCP 调用返回 errcode=851013/851014/851008（文档授权错误）时：
+ * 1. 通过 aibot_send_biz_msg 命令向用户发送授权引导卡片
+ * 2. 拦截 help_message 内容，不将其传递给 LLM
+ * 3. 返回简化响应，告知 LLM 授权卡片已发送、无需再做处理
+ */
+import type { CallInterceptor } from "./types.js";
+export declare const docAuthErrorInterceptor: CallInterceptor;

package/dist/src/mcp/interceptors/doc-auth-error.js

@@ -0,0 +1,171 @@
+/**
+ * 文档授权错误拦截器
+ *
+ * 当 category=doc 的 MCP 调用返回 errcode=851013/851014/851008（文档授权错误）时：
+ * 1. 通过 aibot_send_biz_msg 命令向用户发送授权引导卡片
+ * 2. 拦截 help_message 内容，不将其传递给 LLM
+ * 3. 返回简化响应，告知 LLM 授权卡片已发送、无需再做处理
+ */
+import { generateReqId } from "@wecom/aibot-node-sdk";
+import { getWeComWebSocket } from "../../state-manager.js";
+import { resolveCurrentAccountId } from "../transport.js";
+import { withTimeout } from "../../timeout.js";
+import { AIBOT_SEND_BIZ_MSG_CMD, BIZ_MSG_SEND_TIMEOUT_MS } from "../../const.js";
+// ============================================================================
+// 常量
+// ============================================================================
+/** 需要拦截的文档授权错误码集合 */
+/* https://doc.weixin.qq.com/sheet/e3_AFcARgbdAFwCNU0pwubawRtGzcd6z?scode=AJEAIQdfAAoEpqtRfRAMEA4QYkACk&tab=BB08J2 */
+const DOC_AUTH_ERROR_CODES = new Set([851013, 851014, 851008]);
+/**
+ * 业务消息类型枚举（对应 AiBotBizMsgType）
+ * - 1: 文档权限
+ */
+const AIBOT_BIZ_MSG_TYPE_DOC_READ_AUTH = 1;
+/**
+ * 聊天类型枚举（对应 AiBotBizMsgChatType）
+ * - 1: 单聊
+ * - 2: 群聊
+ */
+const AIBOT_BIZ_MSG_CHAT_TYPE_SINGLE = 1;
+const AIBOT_BIZ_MSG_CHAT_TYPE_GROUP = 2;
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+export const docAuthErrorInterceptor = {
+    name: "doc-auth-error",
+    /** 仅对 doc 品类生效 */
+    match: (ctx) => ctx.category === "doc",
+    /** 检测文档授权错误，发送授权引导卡片并拦截原始响应 */
+    async afterCall(ctx, result) {
+        return interceptDocAuthError(ctx, result);
+    },
+};
+// ============================================================================
+// 内部实现
+// ============================================================================
+/**
+ * 从 MCP 返回结果中解析业务 JSON
+ */
+function parseBizData(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const { content } = result;
+    if (!Array.isArray(content))
+        return null;
+    const textItem = content.find((c) => c.type === "text" && typeof c.text === "string");
+    if (!textItem)
+        return null;
+    try {
+        return JSON.parse(textItem.text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 通过 WSClient 发送 aibot_send_biz_msg 命令
+ *
+ * 按照 WwOpenWsSendAiBotBizMsgReq proto 定义构造请求体：
+ *   - chat_id:   会话标识
+ *   - userid:    发送者 userid
+ *   - biz_type:  业务消息类型（AiBotBizMsgType）
+ *   - chat_type: 聊天类型（AiBotBizMsgChatType，1=单聊，2=群聊）
+ */
+async function sendBizMsg(params) {
+    const accountId = params.accountId || resolveCurrentAccountId();
+    const wsClient = getWeComWebSocket(accountId);
+    if (!wsClient) {
+        console.warn(`[mcp] doc-auth-error: WSClient 未连接 (accountId="${accountId}")，无法发送授权卡片`);
+        return;
+    }
+    const reqId = generateReqId("biz_msg");
+    // 构造 WwOpenWsSendAiBotBizMsgReqBody
+    const body = {
+        biz_type: AIBOT_BIZ_MSG_TYPE_DOC_READ_AUTH,
+    };
+    if (params.chatId) {
+        body.chat_id = params.chatId;
+    }
+    if (params.userid) {
+        body.userid = params.userid;
+    }
+    if (params.chatType) {
+        body.chat_type = params.chatType === "group"
+            ? AIBOT_BIZ_MSG_CHAT_TYPE_GROUP
+            : AIBOT_BIZ_MSG_CHAT_TYPE_SINGLE;
+    }
+    console.log(`[mcp] doc-auth-error: 发送 aibot_send_biz_msg, body=${JSON.stringify(body)}`);
+    try {
+        await withTimeout(wsClient.reply({ headers: { req_id: reqId } }, body, AIBOT_SEND_BIZ_MSG_CMD), BIZ_MSG_SEND_TIMEOUT_MS, `aibot_send_biz_msg timed out after ${BIZ_MSG_SEND_TIMEOUT_MS}ms`);
+        console.log(`[mcp] doc-auth-error: 授权卡片发送成功 (chatId="${params.chatId}", userid="${params.userid}", chatType="${params.chatType}")`);
+    }
+    catch (err) {
+        console.error(`[mcp] doc-auth-error: 授权卡片发送失败: ${err instanceof Error ? err.message : JSON.stringify(err)}`);
+    }
+}
+/**
+ * 拦截文档授权错误
+ *
+ * 检测 errcode=851013/851014/851008 时：
+ * 1. 通过 aibot_send_biz_msg 发送授权引导卡片（携带 chat_id、userid、chat_type）
+ * 2. 返回简化响应，告知 LLM 授权卡片已直接发送给用户
+ *
+ * 数据来源链路（chatId 全程保留原始大小写，单一事实来源）：
+ *
+ *   aibot_msg_callback.body.chatid  (原始大小写)
+ *     ↓
+ *   monitor.ts:processWeComMessageNow
+ *     → setSessionChatInfo(route.sessionKey, { chatId, chatType })  ← 以 sessionKey 为键
+ *     ↓
+ *   OpenClaw core 调用工具工厂，传入 ctx.sessionKey
+ *     ↓
+ *   index.ts:registerTool
+ *     → getSessionChatInfo(ctx.sessionKey) 精确取回 { chatId, chatType }
+ *     → createWeComMcpTool({ chatId, chatType })
+ *     ↓
+ *   tool.ts:handleCall 将其注入 CallContext
+ *     ↓
+ *   本拦截器直接使用 ctx.chatId / ctx.chatType （无需反解 sessionKey、无需兜底）
+ *
+ * ⚠️ 切勿使用 parseSessionKeyChat(ctx.sessionKey) 反向解析 chatId：
+ *    OpenClaw core 构建 sessionKey 时会将 peer.id 强制小写化，
+ *    企业微信 aibot_send_biz_msg 的 chat_id 是大小写敏感的，
+ *    小写后会收到 errcode=93006 (invalid chatid)。
+ */
+async function interceptDocAuthError(ctx, result) {
+    const bizData = parseBizData(result);
+    if (!bizData)
+        return result;
+    const errcode = bizData.errcode;
+    if (typeof errcode !== "number" || !DOC_AUTH_ERROR_CODES.has(errcode)) {
+        return result;
+    }
+    console.log(`[mcp] doc-auth-error: 检测到文档授权错误 errcode=${errcode}, ` +
+        `method=${ctx.method}, category=${ctx.category}`);
+    // chatId / chatType 已由 monitor.ts → state-manager → index.ts 透传到 ctx，
+    // 这里直接使用即可，原始大小写保留不变。
+    const { requesterUserId: userid, chatId, chatType, accountId } = ctx;
+    if (!chatId || !chatType) {
+        console.warn(`[mcp] doc-auth-error: ctx 缺少 chatId/chatType（可能会话信息未记录），` +
+            `userid="${userid}", chatId="${chatId}", chatType="${chatType}"，跳过发送授权卡片`);
+    }
+    else {
+        console.log(`[mcp] doc-auth-error: 发送授权卡片参数: userid="${userid}", chatId="${chatId}", chatType="${chatType}"`);
+        await sendBizMsg({ chatId, userid, chatType, accountId });
+    }
+    // 构造简化响应：不将 help_message 传递给 LLM，
+    // 告知 LLM 授权提示已直接发送给用户，无需再做任何操作
+    const simplifiedResult = {
+        errcode,
+        errmsg: bizData.errmsg ?? "authorization error",
+        _biz_msg_sent: true,
+        _user_hint: "文档授权提示卡片已直接发送给用户，无需再向用户转述任何授权相关的信息。请告知用户：已发送授权引导，请按照提示完成授权后重试。",
+    };
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(simplifiedResult),
+            }],
+    };
+}

package/dist/src/mcp/interceptors/index.js

@@ -9,6 +9,7 @@
  * tool.ts 的 handleCall 无需任何改动。
  */
 import { bizErrorInterceptor } from "./biz-error.js";
+import { docAuthErrorInterceptor } from "./doc-auth-error.js";
 import { mediaInterceptor } from "./msg-media.js";
 import { smartpageCreateInterceptor } from "./smartpage-create.js";
 import { smartpageExportInterceptor } from "./smartpage-export.js";
@@ -17,6 +18,7 @@ import { smartpageExportInterceptor } from "./smartpage-export.js";
 // ============================================================================
 const interceptors = [
     bizErrorInterceptor, // 业务错误码检查（所有 call 生效）
+    docAuthErrorInterceptor, // 文档授权错误拦截（category=doc, errcode=851013/851014/851008）
     mediaInterceptor, // get_msg_media base64 拦截
     smartpageCreateInterceptor, // smartpage_create 本地文件读取
     smartpageExportInterceptor, // smartpage_get_export_result content → 本地文件

package/dist/src/mcp/interceptors/types.d.ts

@@ -13,6 +13,14 @@ export interface CallContext {
     method: string;
     /** 调用 MCP 方法的参数 */
     args: Record<string, unknown>;
+    /** 当前会话对应的账户 ID（由工具工厂透传，用于精确清理缓存等场景） */
+    accountId?: string;
+    /** 当前会话的 chatId（群组 ID 或用户 ID），用于 aibot_send_biz_msg 等命令 */
+    chatId?: string;
+    /** 当前会话的聊天类型：single（单聊）或 group（群聊） */
+    chatType?: "single" | "group";
+    /** 当前会话可信的企业微信 userid */
+    requesterUserId?: string;
 }
 /**
  * beforeCall 返回的选项

package/dist/src/mcp/tool.d.ts

@@ -12,10 +12,20 @@
  *   wecom_mcp list contact
  *   wecom_mcp call contact getContact '{}'
  */
+interface CreateWeComMcpToolOptions {
+    /** 当前会话可信的企业微信 userid */
+    requesterUserId?: string;
+    /** 当前会话对应的账户 ID（来自 ctx.agentAccountId） */
+    accountId?: string;
+    /** 当前会话的 chatId（群组 ID 或用户 ID），用于 aibot_send_biz_msg 等命令 */
+    chatId?: string;
+    /** 当前会话的聊天类型：single（单聊）或 group（群聊） */
+    chatType?: "single" | "group";
+}
 /**
  * 创建 wecom_mcp Agent Tool 定义
  */
-export declare function createWeComMcpTool(): {
+export declare function createWeComMcpTool(options?: CreateWeComMcpToolOptions): {
     name: string;
     label: string;
     description: string;
@@ -47,5 +57,7 @@ export declare function createWeComMcpTool(): {
             type: "text";
             text: string;
         }[];
+        details: unknown;
     }>;
 };
+export {};

package/dist/src/mcp/tool.js

@@ -21,7 +21,12 @@ import { resolveBeforeCall, runAfterCall } from "./interceptors/index.js";
 /** 构造统一的文本响应结构 */
 const textResult = (data) => ({
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    details: data,
 });
+const normalizeOptionalString = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+};
 /** 构造错误响应 */
 const errorResult = (err) => {
     // 适配企业微信 API 返回的 { errcode, errmsg } 结构
@@ -35,14 +40,17 @@ const errorResult = (err) => {
 // ============================================================================
 // list 操作：列出某品类的所有 MCP 工具
 // ============================================================================
-const handleList = async (category) => {
-    const result = await sendJsonRpc(category, "tools/list");
+const handleList = async (ctx) => {
+    const result = await sendJsonRpc(ctx.category, "tools/list", undefined, {
+        requesterUserId: ctx.requesterUserId,
+        accountId: ctx.accountId,
+    });
     const tools = result?.tools ?? [];
     if (tools.length === 0) {
-        return { message: `品类 "${category}" 下暂无可用工具`, tools: [] };
+        return { message: `品类 "${ctx.category}" 下暂无可用工具`, tools: [] };
     }
     return {
-        category,
+        category: ctx.category,
         count: tools.length,
         tools: tools.map((t) => ({
             name: t.name,
@@ -56,13 +64,14 @@ const handleList = async (category) => {
 // ============================================================================
 // call 操作：调用某品类的某个 MCP 工具
 // ============================================================================
-const handleCall = async (category, method, args) => {
-    const ctx = { category, method, args };
+const handleCall = async (ctx) => {
+    const { category, method, args, requesterUserId, accountId } = ctx;
     const callStart = performance.now();
     console.log(`[mcp] handleCall ${category}/${method} 入参: ${JSON.stringify(args)}`);
     // 1. 收集拦截器的 beforeCall 配置（如超时时间、替换 args）
     const { options, args: resolvedArgs } = await resolveBeforeCall(ctx);
     const finalArgs = resolvedArgs ?? args;
+    const requestOptions = { ...options, ...(requesterUserId ? { requesterUserId } : {}), ...(accountId ? { accountId } : {}) };
     if (resolvedArgs) {
         console.log(`[mcp] handleCall ${category}/${method} 拦截器替换 args: ${JSON.stringify(resolvedArgs).slice(0, 500)}` +
             (JSON.stringify(resolvedArgs).length > 500 ? "...(truncated)" : ""));
@@ -74,7 +83,7 @@ const handleCall = async (category, method, args) => {
     const result = await sendJsonRpc(category, "tools/call", {
         name: method,
         arguments: finalArgs,
-    }, options);
+    }, requestOptions);
     const rpcDone = performance.now();
     const rpcMs = (rpcDone - callStart).toFixed(1);
     const resultStr = JSON.stringify(result);
@@ -122,7 +131,11 @@ const parseArgs = (args) => {
 /**
  * 创建 wecom_mcp Agent Tool 定义
  */
-export function createWeComMcpTool() {
+export function createWeComMcpTool(options = {}) {
+    const requesterUserId = normalizeOptionalString(options.requesterUserId);
+    const accountId = normalizeOptionalString(options.accountId);
+    const chatId = normalizeOptionalString(options.chatId);
+    const chatType = options.chatType;
     return {
         name: "wecom_mcp",
         label: "企业微信 MCP 工具",
@@ -170,17 +183,26 @@ export function createWeComMcpTool() {
                 (p.args ? `, args=${typeof p.args === "string" ? p.args : JSON.stringify(p.args)}` : ""));
             try {
                 let result;
+                const ctx = {
+                    category: p.category,
+                    method: p.method ?? "",
+                    args: {},
+                    requesterUserId,
+                    accountId,
+                    chatId,
+                    chatType,
+                };
                 switch (p.action) {
                     case "list":
-                        result = textResult(await handleList(p.category));
+                        result = textResult(await handleList(ctx));
                         break;
                     case "call": {
                         if (!p.method) {
                             result = textResult({ error: "action 为 call 时必须提供 method 参数" });
                             break;
                         }
-                        const args = parseArgs(p.args);
-                        result = textResult(await handleCall(p.category, p.method, args));
+                        ctx.args = parseArgs(p.args);
+                        result = textResult(await handleCall(ctx));
                         break;
                     }
                     default:
@@ -194,7 +216,7 @@ export function createWeComMcpTool() {
             catch (err) {
                 console.error(`[mcp] execute: action=${p.action}, category=${p.category}` +
                     (p.method ? `, method=${p.method}` : "") +
-                    ` → 异常: ${err instanceof Error ? err.message : String(err)}`);
+                    ` → 异常: ${err instanceof Error ? err.message : JSON.stringify(err)}`);
                 return errorResult(err);
             }
         },

package/dist/src/mcp/transport.d.ts

@@ -11,6 +11,8 @@
  */
 /** 媒体下载请求超时时间（毫秒），base64 编码的媒体文件最大可达 ~27MB */
 export declare const MEDIA_DOWNLOAD_TIMEOUT_MS = 120000;
+/** 请求 MCP Server 时透传可信企业微信 userid 的 header 名 */
+export declare const WECOM_USERID_HEADER = "x-openclaw-wecom-userid";
 /**
  * MCP JSON-RPC 错误
  *
@@ -33,13 +35,31 @@ export declare class McpHttpError extends Error {
     constructor(statusCode: number, message: string);
 }
 /**
- * 清理指定品类的所有 MCP 缓存（配置、会话、无状态标记）
+ * 根据配置解析当前用于 MCP 的账户 ID
+ *
+ * 通过 PluginRuntime 读取全局配置，按以下优先级选择账户：
+ * 1. 默认账户（如果配置了 botId + secret）
+ * 2. 第一个配置了 botId + secret 的长连接账户
+ * 3. 无可用长连接账户时回退到默认账户（会导致后续 WSClient 获取失败）
+ */
+export declare function resolveCurrentAccountId(): string;
+/**
+ * 清理指定账户+品类的所有 MCP 缓存（配置、会话、无状态标记）
  *
  * 当 MCP Server 返回特定错误码时调用，确保下次请求重新拉取配置并重建会话。
  *
+ * @param accountId - 账户 ID
  * @param category - MCP 品类名称
  */
-export declare function clearCategoryCache(category: string): void;
+export declare function clearCategoryCache(accountId: string, category: string): void;
+/**
+ * 清理指定账户下所有品类的 MCP 缓存
+ *
+ * 适用于账户掉线、凭据变更等需要整体清理的场景。
+ *
+ * @param accountId - 账户 ID
+ */
+export declare function clearAccountCache(accountId: string): void;
 /** tools/list 返回的工具描述 */
 export interface McpToolInfo {
     name: string;
@@ -50,6 +70,10 @@ export interface McpToolInfo {
 export interface SendJsonRpcOptions {
     /** 自定义 HTTP 请求超时时间（毫秒），默认使用 HTTP_REQUEST_TIMEOUT_MS */
     timeoutMs?: number;
+    /** 当前会话可信的企业微信 userid，有值时会注入自定义 header */
+    requesterUserId?: string;
+    /** 指定使用的账户 ID，有值时优先使用，否则 fallback 到 resolveCurrentAccountId() */
+    accountId?: string;
 }
 /**
  * 发送 JSON-RPC 请求到 MCP Server（Streamable HTTP 协议）
@@ -58,10 +82,13 @@ export interface SendJsonRpcOptions {
  * - 无状态 Server：跳过 session 管理，直接发送请求
  * - 有状态 Server：首次调用先执行 initialize 握手，session 失效（404）时自动重建并重试
  *
+ * accountId 优先使用 options.accountId（由工具工厂从 ctx.agentAccountId 传入），
+ * 未提供时 fallback 到 resolveCurrentAccountId()。解析结果贯穿整条调用链，避免跨账号污染。
+ *
  * @param category - MCP 品类名称
  * @param method - JSON-RPC 方法名
  * @param params - JSON-RPC 参数
- * @param options - 可选配置（如自定义超时）
+ * @param options - 可选配置（如自定义超时、指定账户）
  * @returns JSON-RPC result
  */
 export declare function sendJsonRpc(category: string, method: string, params?: Record<string, unknown>, options?: SendJsonRpcOptions): Promise<unknown>;