@mocrane/wecom 2026.3.4 → 2026.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocrane/wecom",
-  "version": "2026.3.4",
+  "version": "2026.3.9",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "main": "index.ts",
@@ -42,6 +42,7 @@
     }
   },
   "dependencies": {
+    "@wecom/aibot-node-sdk": "^1.0.0",
     "fast-xml-parser": "5.3.4",
     "undici": "^7.20.0",
     "zod": "^4.3.6"

package/src/channel.ts

@@ -15,9 +15,9 @@ import {
   resolveWecomAccount,
   resolveWecomAccountConflict,
 } from "./config/index.js";
-import type { ResolvedWecomAccount } from "./types/index.js";
+import type { ResolvedWecomAccount, WecomBotConfig } from "./types/index.js";
 import { monitorWecomProvider } from "./gateway-monitor.js";
-import { wecomOnboardingAdapter } from "./onboarding.js";
+import { setWecomBotConfig, wecomOnboardingAdapter } from "./onboarding.js";
 import { wecomOutbound } from "./outbound.js";
 import { WEBHOOK_PATHS } from "./types/constants.js";
 
@@ -43,6 +43,42 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
   id: "wecom",
   meta,
   onboarding: wecomOnboardingAdapter,
+  setup: {
+    resolveAccountId: ({ cfg, accountId }) => {
+      return accountId?.trim() || resolveDefaultWecomAccountId(cfg as OpenClawConfig) || DEFAULT_ACCOUNT_ID;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const isWsMode = input.url === "ws" || input.url === "websocket";
+
+      if (isWsMode) {
+        // websocket 模式: --bot-token → botId, --token → secret
+        const botConfig: WecomBotConfig = {
+          connectionMode: "websocket",
+          botId: input.botToken?.trim() || undefined,
+          secret: input.token?.trim() || undefined,
+        };
+        return setWecomBotConfig(cfg as OpenClawConfig, botConfig, accountId);
+      }
+
+      // webhook 模式: --token → token, --access-token → encodingAESKey
+      const botConfig: WecomBotConfig = {
+        connectionMode: "webhook",
+        token: input.token?.trim() ?? "",
+        encodingAESKey: input.accessToken?.trim() ?? "",
+      };
+      return setWecomBotConfig(cfg as OpenClawConfig, botConfig, accountId);
+    },
+    validateInput: ({ input }) => {
+      const isWsMode = input.url === "ws" || input.url === "websocket";
+      if (isWsMode) {
+        if (!input.botToken?.trim()) return "websocket 模式需要 --bot-token <BotID>";
+        if (!input.token?.trim()) return "websocket 模式需要 --token <Secret>";
+      } else {
+        if (!input.token?.trim()) return "webhook 模式需要 --token <Token>";
+      }
+      return null;
+    },
+  },
   capabilities: {
     chatTypes: ["direct", "group"],
     media: true,

package/src/config/accounts.ts

@@ -46,15 +46,22 @@ export function detectMode(config: WecomConfig | undefined): ResolvedMode {
  * 解析 Bot 模式账号
  */
 function resolveBotAccount(accountId: string, config: WecomBotConfig, network?: WecomNetworkConfig): ResolvedBotAccount {
+    const connectionMode = config.connectionMode ?? 'webhook';
+    const configured = connectionMode === 'websocket'
+        ? Boolean(config.botId && config.secret)
+        : Boolean(config.token && config.encodingAESKey);
     return {
         accountId,
         enabled: true,
-        configured: Boolean(config.token && config.encodingAESKey),
-        token: config.token,
-        encodingAESKey: config.encodingAESKey,
+        configured,
+        token: config.token ?? "",
+        encodingAESKey: config.encodingAESKey ?? "",
         receiveId: config.receiveId?.trim() ?? "",
         config,
         network,
+        connectionMode,
+        botId: config.botId,
+        secret: config.secret,
     };
 }
 

package/src/config/schema.ts

@@ -81,13 +81,17 @@ const routingSchema = z.object({
  */
 const botSchema = z.object({
     aibotid: z.string().optional(),
-    token: z.string(),
-    encodingAESKey: z.string(),
+    token: z.string().optional(),
+    encodingAESKey: z.string().optional(),
     botIds: z.array(z.string()).optional(),
     receiveId: z.string().optional(),
     streamPlaceholderContent: z.string().optional(),
     welcomeText: z.string().optional(),
     dm: dmSchema,
+    // 长链接模式 (WebSocket)
+    connectionMode: z.enum(['webhook', 'websocket']).optional(),
+    botId: z.string().optional(),
+    secret: z.string().optional(),
 }).optional();
 
 /**

package/src/gateway-monitor.ts

@@ -11,6 +11,7 @@ import {
   resolveWecomAccountConflict,
 } from "./config/index.js";
 import { registerAgentWebhookTarget, registerWecomWebhookTarget } from "./monitor.js";
+import { startWsClient } from "./ws-adapter.js";
 import type { ResolvedWecomAccount, WecomConfig } from "./types/index.js";
 import { WEBHOOK_PATHS } from "./types/constants.js";
 
@@ -164,26 +165,47 @@ export async function monitorWecomProvider(
   const agentPaths: string[] = [];
   try {
     if (bot && botConfigured) {
-      const paths = resolveBotRegistrationPaths({
-        accountId: account.accountId,
-        matrixMode,
-      });
-      for (const path of paths) {
+      const connectionMode = bot.connectionMode ?? 'webhook';
+
+      if (connectionMode === 'websocket') {
+        // 长链接模式：启动 WSClient
         unregisters.push(
-          registerWecomWebhookTarget({
+          startWsClient({
+            accountId: account.accountId,
+            botId: bot.botId!,
+            secret: bot.secret!,
             account: bot,
             config: cfg,
             runtime: ctx.runtime,
-            // The HTTP handler resolves the active PluginRuntime via getWecomRuntime().
-            // The stored target only needs to be decrypt/verify-capable.
             core: {} as PluginRuntime,
-            path,
             statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+            welcomeText: bot.config.welcomeText,
+            network: bot.network,
           }),
         );
+        botPaths.push(`ws://${account.accountId}`);
+        ctx.log?.info(`[${account.accountId}] wecom bot websocket client started (botId=${bot.botId})`);
+      } else {
+        // Webhook 模式：注册 HTTP 路径（现有逻辑不变）
+        const paths = resolveBotRegistrationPaths({
+          accountId: account.accountId,
+          matrixMode,
+        });
+        for (const path of paths) {
+          unregisters.push(
+            registerWecomWebhookTarget({
+              account: bot,
+              config: cfg,
+              runtime: ctx.runtime,
+              core: {} as PluginRuntime,
+              path,
+              statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+            }),
+          );
+        }
+        botPaths.push(...paths);
+        ctx.log?.info(`[${account.accountId}] wecom bot webhook registered at ${paths.join(", ")}`);
       }
-      botPaths.push(...paths);
-      ctx.log?.info(`[${account.accountId}] wecom bot webhook registered at ${paths.join(", ")}`);
     }
 
     if (agent && agentConfigured) {

package/src/monitor/types.ts

@@ -84,6 +84,8 @@ export type StreamState = {
     dmContent?: string;
     /** 已通过 Agent 私信发送过的媒体标识（防重复发送附件） */
     agentMediaKeys?: string[];
+    /** 是否来自 WebSocket 长链接模式（用于跳过 6 分钟超时等 webhook 特有逻辑） */
+    wsMode?: boolean;
 };
 
 /**
@@ -114,6 +116,8 @@ export type PendingInbound = {
     /** 已到达防抖截止时间，但因前序批次仍在处理中而暂存 */
     readyToFlush?: boolean;
     createdAt: number;
+    /** 是否来自 WebSocket 长链接模式 */
+    wsMode?: boolean;
 };
 
 /**

package/src/monitor.ts

@@ -931,7 +931,7 @@ function parseWecomPlainMessage(raw: string): WecomInboundMessage {
   return parsed as WecomInboundMessage;
 }
 
-type InboundResult = {
+export type InboundResult = {
   body: string;
   media?: {
     buffer: Buffer;
@@ -952,15 +952,16 @@ type InboundResult = {
  * @param target Webhook 目标配置
  * @param msg 企业微信原始消息对象
  */
-async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInboundMessage): Promise<InboundResult> {
+export async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInboundMessage): Promise<InboundResult> {
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
-  const aesKey = target.account.encodingAESKey;
+  const globalAesKey = target.account.encodingAESKey;
   const maxBytes = resolveWecomMediaMaxBytes(target.config);
   const proxyUrl = resolveWecomEgressProxyUrl(target.config);
 
   // 图片消息处理：如果存在 url 且配置了 aesKey，则尝试解密下载
   if (msgtype === "image") {
     const url = String((msg as any).image?.url ?? "").trim();
+    const aesKey = globalAesKey || (msg as any).image?.aeskey || "";
     if (url && aesKey) {
       try {
         const decrypted = await decryptWecomMediaWithMeta(url, aesKey, { maxBytes, http: { proxyUrl } });
@@ -995,6 +996,7 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
 
   if (msgtype === "file") {
     const url = String((msg as any).file?.url ?? "").trim();
+    const aesKey = globalAesKey || (msg as any).file?.aeskey || "";
     if (url && aesKey) {
       try {
         const decrypted = await decryptWecomMediaWithMeta(url, aesKey, { maxBytes, http: { proxyUrl } });
@@ -1038,12 +1040,16 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
         if (t === "text") {
           const content = String(item.text?.content ?? "").trim();
           if (content) bodyParts.push(content);
-        } else if ((t === "image" || t === "file") && !foundMedia && aesKey) {
+        } else if ((t === "image" || t === "file") && !foundMedia) {
           // Found first media, try to download
+          const itemAesKey = globalAesKey || item[t]?.aeskey || "";
           const url = String(item[t]?.url ?? "").trim();
-          if (url) {
+          if (!itemAesKey) {
+            bodyParts.push(`[${t}]`);
+          } else
+            if (url) {
             try {
-              const decrypted = await decryptWecomMediaWithMeta(url, aesKey, { maxBytes, http: { proxyUrl } });
+              const decrypted = await decryptWecomMediaWithMeta(url, itemAesKey, { maxBytes, http: { proxyUrl } });
               const inferred = inferInboundMediaMeta({
                 kind: t,
                 buffer: decrypted.buffer,
@@ -2049,7 +2055,7 @@ function formatQuote(quote: WecomInboundQuote): string {
   return "";
 }
 
-function buildInboundBody(msg: WecomInboundMessage): string {
+export function buildInboundBody(msg: WecomInboundMessage): string {
   let body = "";
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
 

package/src/onboarding.ts

@@ -38,6 +38,39 @@ function setWecomEnabled(cfg: OpenClawConfig, enabled: boolean): OpenClawConfig
     } as OpenClawConfig;
 }
 
+/**
+ * 确保 cfg.bindings 中存在一条 wecom 账号到默认 agent 的路由。
+ *
+ * `openclaw channels add` 流程会在插件 configure() 返回后单独提示用户绑定 agent，
+ * 但 `openclaw onboard` 的 quickstart 路径会跳过这一步，导致消息路由缺失。
+ * 在插件层面主动补全 binding 可以让两种流程都能正常工作。
+ *
+ * 如果 bindings 中已存在匹配 channel+accountId 的条目，则不会重复添加。
+ */
+function ensureWecomBinding(cfg: OpenClawConfig, accountId: string): OpenClawConfig {
+    const existing = cfg.bindings ?? [];
+    const alreadyBound = existing.some(
+        (b) => b.match.channel === channel && (b.match.accountId === accountId || (!b.match.accountId && accountId === DEFAULT_ACCOUNT_ID)),
+    );
+    if (alreadyBound) return cfg;
+
+    // 默认路由到 main agent（OpenClaw 约定 defaultAgentId 为 "main"）
+    const defaultAgentId = "main";
+    return {
+        ...cfg,
+        bindings: [
+            ...existing,
+            {
+                agentId: defaultAgentId,
+                match: {
+                    channel,
+                    accountId,
+                },
+            },
+        ],
+    };
+}
+
 function setGatewayBindLan(cfg: OpenClawConfig): OpenClawConfig {
     return {
         ...cfg,
@@ -48,6 +81,20 @@ function setGatewayBindLan(cfg: OpenClawConfig): OpenClawConfig {
     } as OpenClawConfig;
 }
 
+function setWecomDefaultAccount(cfg: OpenClawConfig, accountId: string): OpenClawConfig {
+    const wecom = getWecomConfig(cfg) ?? {};
+    return {
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            wecom: {
+                ...wecom,
+                defaultAccount: accountId,
+            },
+        },
+    } as OpenClawConfig;
+}
+
 function shouldUseAccountScopedConfig(wecom: WecomConfig | undefined, accountId: string): boolean {
     void wecom;
     void accountId;
@@ -85,7 +132,7 @@ function accountWebhookPath(kind: "bot" | "agent", accountId: string): string {
     return `${recommendedBase}/${accountId}`;
 }
 
-function setWecomBotConfig(cfg: OpenClawConfig, bot: WecomBotConfig, accountId: string): OpenClawConfig {
+export function setWecomBotConfig(cfg: OpenClawConfig, bot: WecomBotConfig, accountId: string): OpenClawConfig {
     const wecom = getWecomConfig(cfg) ?? {};
     if (!shouldUseAccountScopedConfig(wecom, accountId)) {
         return {
@@ -190,7 +237,7 @@ function setWecomDmPolicy(
                     agent: {
                         ...existingAccount.agent,
                         dm,
-                    },
+                    } as WecomAgentConfig,
                 };
         return {
             ...cfg,
@@ -315,18 +362,47 @@ async function configureBotMode(
     cfg: OpenClawConfig,
     prompter: WizardPrompter,
     accountId: string,
+): Promise<OpenClawConfig> {
+    // 选择接入方式
+    const connectionMode = (await prompter.select({
+        message: "请选择 Bot 接入方式:",
+        options: [
+            {
+                value: "websocket",
+                label: "WebSocket 长链接模式",
+                hint: "无需公网 IP，SDK 主动连接企微服务器，适合内网环境",
+            },
+            {
+                value: "webhook",
+                label: "Webhook 回调模式",
+                hint: "需要公网 IP + 回调 URL，适合有公网服务器的环境",
+            },
+        ],
+        initialValue: "websocket",
+    })) as "webhook" | "websocket";
+
+    if (connectionMode === "websocket") {
+        return configureBotWebsocket(cfg, prompter, accountId);
+    }
+    return configureBotWebhook(cfg, prompter, accountId);
+}
+
+async function configureBotWebhook(
+    cfg: OpenClawConfig,
+    prompter: WizardPrompter,
+    accountId: string,
 ): Promise<OpenClawConfig> {
     const recommendedPath = accountWebhookPath("bot", accountId);
     await prompter.note(
         [
-            "正在配置 Bot 模式...",
+            "正在配置 Bot 模式（Webhook 回调）...",
             "",
             "💡 操作指南: 请在企微后台【管理工具 -> 智能机器人】开启 API 模式。",
             `🔗 回调 URL (推荐): https://您的域名${recommendedPath}`,
             "",
             "请先在后台填入回调 URL，然后获取以下信息。",
         ].join("\n"),
-        "Bot 模式配置",
+        "Bot 模式配置 — Webhook",
     );
 
     const token = String(
@@ -361,6 +437,7 @@ async function configureBotMode(
     });
 
     const botConfig: WecomBotConfig = {
+        connectionMode: "webhook",
         token,
         encodingAESKey,
         streamPlaceholderContent: streamPlaceholder?.trim() || undefined,
@@ -370,6 +447,59 @@ async function configureBotMode(
     return setWecomBotConfig(cfg, botConfig, accountId);
 }
 
+async function configureBotWebsocket(
+    cfg: OpenClawConfig,
+    prompter: WizardPrompter,
+    accountId: string,
+): Promise<OpenClawConfig> {
+    await prompter.note(
+        [
+            "正在配置 Bot 模式（WebSocket 长链接）...",
+            "",
+            "💡 操作指南: 请在企微后台【管理工具 -> 智能机器人】获取 BotID 和 Secret。",
+            "",
+            "长链接模式无需公网 IP 和回调 URL，适合内网环境。",
+        ].join("\n"),
+        "Bot 模式配置 — WebSocket",
+    );
+
+    const botId = String(
+        await prompter.text({
+            message: "请输入 BotID (机器人ID):",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "BotID 不能为空"),
+        }),
+    ).trim();
+
+    const secret = String(
+        await prompter.text({
+            message: "请输入 Secret (机器人密钥):",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "Secret 不能为空"),
+        }),
+    ).trim();
+
+    const streamPlaceholder = await prompter.text({
+        message: "流式占位符 (可选):",
+        placeholder: "正在思考...",
+        initialValue: "正在思考...",
+    });
+
+    const welcomeText = await prompter.text({
+        message: "欢迎语 (可选):",
+        placeholder: "你好！我是 AI 助手",
+        initialValue: "你好！我是 AI 助手",
+    });
+
+    const botConfig: WecomBotConfig = {
+        connectionMode: "websocket",
+        botId,
+        secret,
+        streamPlaceholderContent: streamPlaceholder?.trim() || undefined,
+        welcomeText: welcomeText?.trim() || undefined,
+    };
+
+    return setWecomBotConfig(cfg, botConfig, accountId);
+}
+
 // ============================================================
 // Agent 模式配置
 // ============================================================
@@ -516,8 +646,13 @@ async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter, accoun
     const lines: string[] = ["✅ 配置已保存！", ""];
 
     if (account.bot?.configured) {
-        lines.push("📱 Bot 模式: 已配置");
-        lines.push(`   回调 URL: https://您的域名${accountWebhookPath("bot", accountId)}`);
+        if (account.bot.connectionMode === "websocket") {
+            lines.push("📱 Bot 模式: 已配置 (WebSocket 长链接)");
+            lines.push("   无需配置回调 URL，SDK 将主动连接企微服务器");
+        } else {
+            lines.push("📱 Bot 模式: 已配置 (Webhook 回调)");
+            lines.push(`   回调 URL: https://您的域名${accountWebhookPath("bot", accountId)}`);
+        }
     }
 
     if (account.agent?.configured) {
@@ -527,9 +662,17 @@ async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter, accoun
 
     lines.push(`   账号 ID: ${accountId}`);
 
+    const hasWebhook =
+        (account.bot?.configured && account.bot.connectionMode !== "websocket") ||
+        account.agent?.configured;
+
     lines.push("");
-    lines.push("⚠️ 请确保您已在企微后台填写了正确的回调 URL，");
-    lines.push("   并点击了后台的『保存』按钮完成验证。");
+    if (hasWebhook) {
+        lines.push("⚠️ 请确保您已在企微后台填写了正确的回调 URL，");
+        lines.push("   并点击了后台的『保存』按钮完成验证。");
+    } else {
+        lines.push("💡 WebSocket 模式将在服务启动时自动连接企微服务器。");
+    }
 
     await prompter.note(lines.join("\n"), "配置完成");
 }
@@ -634,13 +777,19 @@ export const wecomOnboardingAdapter: ChannelOnboardingAdapter = {
         // 6. DM 策略
         next = await promptDmPolicy(next, prompter, configuredModes, accountId);
 
-        // 7. 启用通道
+        // 7. 设置 defaultAccount
+        next = setWecomDefaultAccount(next, accountId);
+
+        // 8. 启用通道
         next = setWecomEnabled(next, true);
 
-        // 8. 设置 gateway.bind 为 lan（允许外部访问回调）
+        // 9. 设置 gateway.bind 为 lan（允许外部访问回调）
         next = setGatewayBindLan(next);
 
-        // 9. 汇总
+        // 10. 确保 bindings 中有默认路由（onboard quickstart 不会提示绑定）
+        next = ensureWecomBinding(next, accountId);
+
+        // 11. 汇总
         await showSummary(next, prompter, accountId);
 
         return { cfg: next, accountId };

package/src/outbound.ts

@@ -3,6 +3,7 @@ import type { ChannelOutboundAdapter, ChannelOutboundContext } from "openclaw/pl
 import { sendText as sendAgentText, sendMedia as sendAgentMedia, uploadMedia } from "./agent/api-client.js";
 import { resolveWecomAccount, resolveWecomAccountConflict, resolveWecomAccounts } from "./config/index.js";
 import { getWecomRuntime } from "./runtime.js";
+import { getWsClient, waitForWsConnection } from "./ws-adapter.js";
 
 import { resolveWecomTarget } from "./target.js";
 
@@ -61,6 +62,43 @@ export const wecomOutbound: ChannelOutboundAdapter = {
   sendText: async ({ cfg, to, text, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
+    // ── Bot WebSocket outbound 独立路径 ──
+    // WS Bot 完全独立收发，不与 Agent 组成双模，失败时直接抛错而非 fallthrough
+    const resolvedAccount = resolveWecomAccount({ cfg, accountId });
+    const botAccount = resolvedAccount.bot;
+    if (botAccount?.connectionMode === 'websocket' && botAccount.configured) {
+      const wsClient = getWsClient(botAccount.accountId);
+      const wsTarget = resolveWecomTarget(to);
+      const chatid = wsTarget?.touser || wsTarget?.chatid;
+
+      // 如果目标是 Agent 会话（wecom-agent:），跳过 WS Bot，走 Agent outbound
+      const rawTo = typeof to === "string" ? to.trim().toLowerCase() : "";
+      if (!rawTo.startsWith("wecom-agent:")) {
+        if (!wsClient?.isConnected) {
+          console.log(`[wecom-outbound] Bot WS 未连接，等待重连... (accountId=${botAccount.accountId})`);
+          const reconnected = await waitForWsConnection(botAccount.accountId, 10_000);
+          if (!reconnected) {
+            throw new Error(`[wecom-outbound] Bot WS 等待重连超时，无法发送消息 (accountId=${botAccount.accountId})`);
+          }
+        }
+        if (!chatid) {
+          throw new Error(`[wecom-outbound] Bot WS 无法解析目标 chatid (to=${String(to)})`);
+        }
+        // 重连后重新获取 client（可能是新实例）
+        const activeClient = getWsClient(botAccount.accountId);
+        if (!activeClient?.isConnected) {
+          throw new Error(`[wecom-outbound] Bot WS 重连后仍不可用 (accountId=${botAccount.accountId})`);
+        }
+        await activeClient.sendMessage(chatid, {
+          msgtype: 'markdown',
+          markdown: { content: text },
+        });
+        console.log(`[wecom-outbound] Sent text via Bot WS to chatid=${chatid} (len=${text.length})`);
+        return { channel: "wecom", messageId: `ws-bot-${Date.now()}`, timestamp: Date.now() };
+      }
+    }
+
+    // ── Agent outbound（Webhook Bot 双模 / Agent 独立）──
     const agent = resolveAgentConfigOrThrow({ cfg, accountId });
     const target = resolveWecomTarget(to);
     if (!target) {

package/src/types/account.ts

@@ -20,9 +20,9 @@ export type ResolvedBotAccount = {
     enabled: boolean;
     /** 是否配置完整 */
     configured: boolean;
-    /** 回调 Token */
+    /** 回调 Token (webhook 模式) */
     token: string;
-    /** 回调加密密钥 */
+    /** 回调加密密钥 (webhook 模式) */
     encodingAESKey: string;
     /** 接收者 ID */
     receiveId: string;
@@ -30,6 +30,15 @@ export type ResolvedBotAccount = {
     config: WecomBotConfig;
     /** 网络配置（来自 channels.wecom.network） */
     network?: WecomNetworkConfig;
+
+    // --- 长链接模式 (WebSocket) ---
+
+    /** 连接模式 */
+    connectionMode: 'webhook' | 'websocket';
+    /** 机器人 BotID（websocket 模式下有值） */
+    botId?: string;
+    /** 机器人 Secret（websocket 模式下有值） */
+    secret?: string;
 };
 
 /**

package/src/types/config.ts

@@ -45,12 +45,12 @@ export type WecomRoutingConfig = {
  * 用于接收 JSON 格式回调 + 流式回复
  */
 export type WecomBotConfig = {
-    /** 智能机器人 ID（用于 Matrix 模式二次身份确认） */
+    /** 智能机器人 ID（用于 Matrix 模式二次身份确认，webhook 模式） */
     aibotid?: string;
-    /** 回调 Token (企微后台生成) */
-    token: string;
-    /** 回调加密密钥 (企微后台生成) */
-    encodingAESKey: string;
+    /** 回调 Token (企微后台生成，webhook 模式必填) */
+    token?: string;
+    /** 回调加密密钥 (企微后台生成，webhook 模式必填) */
+    encodingAESKey?: string;
     /**
      * BotId 列表（可选，用于审计与告警）。
      * - 回调路由优先由 URL + 签名决定；botIds 不参与强制拦截。
@@ -65,6 +65,15 @@ export type WecomBotConfig = {
     welcomeText?: string;
     /** DM 策略 */
     dm?: WecomDmConfig;
+
+    // --- 长链接模式 (WebSocket) ---
+
+    /** 连接模式：webhook（默认）或 websocket */
+    connectionMode?: 'webhook' | 'websocket';
+    /** 机器人 BotID（websocket 模式必填，企微后台获取） */
+    botId?: string;
+    /** 机器人 Secret（websocket 模式必填，企微后台获取） */
+    secret?: string;
 };
 
 /**

package/src/ws-adapter.ts

@@ -0,0 +1,481 @@
+/**
+ * WeCom WebSocket 长链接模式适配器
+ *
+ * 职责：管理 WSClient 生命周期，将 SDK 事件桥接到现有 monitor.ts 消息管线。
+ *
+ * SDK WsFrame 事件
+ *   ↓
+ * ws-adapter 转换为 WecomBotInboundMessage 格式
+ *   ↓
+ * 复用 monitor.ts 中的 shouldProcessBotInboundMessage → buildInboundBody
+ *   → streamStore.addPendingMessage → flushPending 管线
+ */
+
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import { WSClient } from "@wecom/aibot-node-sdk";
+import type {
+    WsFrame,
+    BaseMessage,
+    TextMessage,
+    ImageMessage,
+    MixedMessage,
+    VoiceMessage,
+    FileMessage,
+    EventMessage,
+    EventMessageWith,
+    ReplyMsgItem,
+} from "@wecom/aibot-node-sdk";
+import type { EnterChatEvent, TemplateCardEventData } from "@wecom/aibot-node-sdk";
+
+import type { ResolvedBotAccount, WecomNetworkConfig, WecomBotInboundMessage } from "./types/index.js";
+import type { WecomRuntimeEnv, WecomWebhookTarget, StreamState } from "./monitor/types.js";
+import { shouldProcessBotInboundMessage, buildInboundBody } from "./monitor.js";
+import { monitorState } from "./monitor/state.js";
+import { getWecomRuntime } from "./runtime.js";
+
+// ─── WSClient Instance Registry ────────────────────────────────────────
+
+const wsClients = new Map<string, WSClient>();
+
+/**
+ * 获取指定账号的 WSClient 实例
+ */
+export function getWsClient(accountId: string): WSClient | undefined {
+    return wsClients.get(accountId);
+}
+
+/**
+ * 等待 WSClient 连接就绪，最多等待 timeoutMs 毫秒（默认 30 秒）。
+ * 如果已连接则立即返回；如果 client 尚未创建，会轮询等待创建后再监听连接事件。
+ */
+export async function waitForWsConnection(accountId: string, timeoutMs = 30_000): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+
+    // 等待 client 实例出现（gateway 重启时 client 可能还没注册）
+    while (!wsClients.has(accountId)) {
+        if (Date.now() >= deadline) return false;
+        await new Promise((r) => setTimeout(r, 500));
+    }
+
+    const client = wsClients.get(accountId)!;
+    if (client.isConnected) return true;
+
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+
+    return new Promise<boolean>((resolve) => {
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve(false);
+        }, remaining);
+
+        const onConnected = () => {
+            cleanup();
+            resolve(true);
+        };
+
+        const cleanup = () => {
+            clearTimeout(timer);
+            client.off("connected", onConnected);
+        };
+
+        client.on("connected", onConnected);
+        // 再检查一次，防止在注册监听器之前已连上
+        if (client.isConnected) {
+            cleanup();
+            resolve(true);
+        }
+    });
+}
+
+// ─── Stream Reply Watcher ──────────────────────────────────────────────
+
+/**
+ * 流式回复监听器：轮询 StreamState 变化并通过 WSClient 推送回复
+ */
+function watchStreamReply(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    streamId: string;
+    log?: (msg: string) => void;
+    error?: (msg: string) => void;
+}): void {
+    const { wsClient, frame, streamId, log, error } = params;
+    const streamStore = monitorState.streamStore;
+    let lastSentContent = "";
+    let finished = false;
+    const POLL_INTERVAL_MS = 200;
+
+    const tick = async () => {
+        if (finished) return;
+
+        const state = streamStore.getStream(streamId);
+        if (!state) {
+            finished = true;
+            return;
+        }
+
+        const content = state.content ?? "";
+        const isFinished = state.finished ?? false;
+
+        // 有新内容或流结束时发送
+        if (content !== lastSentContent || isFinished) {
+            try {
+                // 构建图片附件（仅在结束时）
+                let msgItems: ReplyMsgItem[] | undefined;
+                if (isFinished && state.images?.length) {
+                    msgItems = state.images.map((img) => ({
+                        msgtype: "image" as const,
+                        image: { base64: img.base64, md5: img.md5 },
+                    }));
+                }
+
+                await wsClient.replyStream(
+                    frame,
+                    streamId,
+                    content,
+                    isFinished,
+                    msgItems,
+                );
+                lastSentContent = content;
+                log?.(`ws-reply: streamId=${streamId} len=${content.length} finish=${isFinished}`);
+            } catch (err) {
+                error?.(`ws-reply: replyStream failed streamId=${streamId}: ${String(err)}`);
+            }
+        }
+
+        if (isFinished) {
+            finished = true;
+            return;
+        }
+
+        setTimeout(tick, POLL_INTERVAL_MS);
+    };
+
+    // 初次延迟启动，等待 agent 开始生产内容
+    setTimeout(tick, POLL_INTERVAL_MS);
+}
+
+// ─── SDK Message → WecomBotInboundMessage Conversion ───────────────────
+
+/**
+ * 将 SDK 的 WsFrame<BaseMessage> 转换为现有的 WecomBotInboundMessage 格式
+ */
+function convertSdkMessageToInbound(body: BaseMessage): WecomBotInboundMessage {
+    const base: WecomBotInboundMessage = {
+        msgid: body.msgid,
+        aibotid: body.aibotid,
+        chattype: body.chattype,
+        chatid: body.chatid,
+        response_url: body.response_url,
+        from: body.from ? { userid: body.from.userid } : undefined,
+        msgtype: body.msgtype as string,
+    };
+
+    const msgtype = String(body.msgtype ?? "").toLowerCase();
+
+    if (msgtype === "text") {
+        const textBody = body as TextMessage;
+        return { ...base, msgtype: "text", text: textBody.text, quote: textBody.quote as any };
+    }
+    if (msgtype === "voice") {
+        const voiceBody = body as VoiceMessage;
+        return { ...base, msgtype: "voice", voice: voiceBody.voice, quote: voiceBody.quote as any };
+    }
+    if (msgtype === "image") {
+        const imageBody = body as ImageMessage;
+        return { ...base, msgtype: "image" as any, image: imageBody.image, quote: imageBody.quote as any } as any;
+    }
+    if (msgtype === "file") {
+        const fileBody = body as FileMessage;
+        return { ...base, msgtype: "file" as any, file: fileBody.file, quote: fileBody.quote as any } as any;
+    }
+    if (msgtype === "mixed") {
+        const mixedBody = body as MixedMessage;
+        return { ...base, msgtype: "mixed" as any, mixed: mixedBody.mixed, quote: mixedBody.quote as any } as any;
+    }
+
+    // Fallback: pass through as-is
+    return { ...base, ...body };
+}
+
+// ─── WS Event Handlers ────────────────────────────────────────────────
+
+function setupMessageHandler(params: {
+    wsClient: WSClient;
+    accountId: string;
+    target: WecomWebhookTarget;
+}) {
+    const { wsClient, accountId, target } = params;
+    const streamStore = monitorState.streamStore;
+
+    // 监听所有消息类型
+    wsClient.on("message", (frame: WsFrame<BaseMessage>) => {
+        const body = frame.body;
+        if (!body) return;
+
+        const msgtype = String(body.msgtype ?? "").toLowerCase();
+
+        // event 类型由专门的 event handler 处理
+        if (msgtype === "event") return;
+
+        const msg = convertSdkMessageToInbound(body);
+        const decision = shouldProcessBotInboundMessage(msg);
+        if (!decision.shouldProcess) {
+            target.runtime.log?.(
+                `[${accountId}] ws-inbound: skipped msgtype=${msgtype} reason=${decision.reason}`,
+            );
+            return;
+        }
+
+        const userid = decision.senderUserId!;
+        const chatId = decision.chatId ?? userid;
+        const conversationKey = `wecom:${accountId}:${userid}:${chatId}`;
+        const msgContent = buildInboundBody(msg);
+
+        target.runtime.log?.(
+            `[${accountId}] ws-inbound: msgtype=${msgtype} chattype=${String(msg.chattype ?? "")} ` +
+            `from=${userid} msgid=${String(msg.msgid ?? "")}`,
+        );
+
+        // 消息去重
+        if (msg.msgid) {
+            const existingStreamId = streamStore.getStreamByMsgId(String(msg.msgid));
+            if (existingStreamId) {
+                target.runtime.log?.(
+                    `[${accountId}] ws-inbound: duplicate msgid=${msg.msgid}, skipping`,
+                );
+                return;
+            }
+        }
+
+        // 加入 Pending 队列（复用现有防抖/聚合逻辑）
+        const { streamId } = streamStore.addPendingMessage({
+            conversationKey,
+            target,
+            msg,
+            msgContent,
+            nonce: "",
+            timestamp: String(Date.now()),
+            debounceMs: (target.account.config as any).debounceMs,
+        });
+
+        // 标记 wsMode
+        streamStore.updateStream(streamId, (s: StreamState) => {
+            s.wsMode = true;
+        });
+
+        // 注册流式回复监听器
+        watchStreamReply({
+            wsClient,
+            frame,
+            streamId,
+            log: (msg) => target.runtime.log?.(`[${accountId}] ${msg}`),
+            error: (msg) => target.runtime.error?.(`[${accountId}] ${msg}`),
+        });
+
+        target.statusSink?.({ lastInboundAt: Date.now() });
+    });
+}
+
+function setupEventHandler(params: {
+    wsClient: WSClient;
+    accountId: string;
+    target: WecomWebhookTarget;
+    welcomeText?: string;
+}) {
+    const { wsClient, accountId, target, welcomeText } = params;
+    const streamStore = monitorState.streamStore;
+
+    // 进入会话事件 → 欢迎语
+    wsClient.on("event.enter_chat", async (frame: WsFrame<EventMessageWith<EnterChatEvent>>) => {
+        const text = welcomeText?.trim();
+        if (!text) return;
+
+        try {
+            await wsClient.replyWelcome(frame, {
+                msgtype: "text",
+                text: { content: text },
+            });
+            target.runtime.log?.(`[${accountId}] ws-event: sent welcome text`);
+        } catch (err) {
+            target.runtime.error?.(`[${accountId}] ws-event: replyWelcome failed: ${String(err)}`);
+        }
+    });
+
+    // 模板卡片交互事件 → 转换为文本消息注入管线
+    wsClient.on("event.template_card_event", (frame: WsFrame<EventMessageWith<TemplateCardEventData>>) => {
+        const body = frame.body;
+        if (!body) return;
+
+        const eventData = body.event;
+        let interactionDesc = `[卡片交互] 按钮: ${eventData?.event_key || "unknown"}`;
+        if (eventData?.task_id) interactionDesc += ` (任务ID: ${eventData.task_id})`;
+
+        const msgid = body.msgid ? String(body.msgid) : undefined;
+
+        // 去重
+        if (msgid && streamStore.getStreamByMsgId(msgid)) {
+            target.runtime.log?.(`[${accountId}] ws-event: template_card_event already processed msgid=${msgid}`);
+            return;
+        }
+
+        const streamId = streamStore.createStream({ msgid });
+        streamStore.markStarted(streamId);
+        streamStore.updateStream(streamId, (s: StreamState) => {
+            s.wsMode = true;
+        });
+
+        const syntheticMsg: WecomBotInboundMessage = {
+            msgid,
+            aibotid: body.aibotid,
+            chattype: body.chattype,
+            chatid: body.chatid,
+            from: body.from ? { userid: body.from.userid } : undefined,
+            msgtype: "text",
+            text: { content: interactionDesc },
+        };
+
+        let core: PluginRuntime;
+        try {
+            core = getWecomRuntime();
+        } catch {
+            target.runtime.error?.(`[${accountId}] ws-event: runtime not ready for template_card_event`);
+            streamStore.markFinished(streamId);
+            return;
+        }
+
+        // 由于卡片事件没有经过防抖队列，直接触发 flushPending 的等效操作
+        // 需要通过 addPendingMessage 注入，让现有管线处理
+        const userid = body.from?.userid ?? "unknown";
+        const chatId = body.chatid ?? userid;
+        const conversationKey = `wecom:${accountId}:${userid}:${chatId}`;
+
+        // 先清除之前创建的 stream（addPendingMessage 会创建新的）
+        // 直接用 addPendingMessage 复用完整管线
+        const enrichedTarget: WecomWebhookTarget = { ...target, core };
+        const { streamId: actualStreamId } = streamStore.addPendingMessage({
+            conversationKey,
+            target: enrichedTarget,
+            msg: syntheticMsg,
+            msgContent: interactionDesc,
+            nonce: "",
+            timestamp: String(Date.now()),
+            debounceMs: 0, // 卡片事件不防抖
+        });
+
+        streamStore.updateStream(actualStreamId, (s: StreamState) => {
+            s.wsMode = true;
+        });
+
+        watchStreamReply({
+            wsClient,
+            frame,
+            streamId: actualStreamId,
+            log: (msg) => target.runtime.log?.(`[${accountId}] ${msg}`),
+            error: (msg) => target.runtime.error?.(`[${accountId}] ${msg}`),
+        });
+    });
+
+    // 反馈事件 → 仅记录日志
+    wsClient.on("event.feedback_event", (frame) => {
+        target.runtime.log?.(
+            `[${accountId}] ws-event: feedback_event received (logged only)`,
+        );
+    });
+}
+
+// ─── WSClient Lifecycle ────────────────────────────────────────────────
+
+export type StartWsClientParams = {
+    accountId: string;
+    botId: string;
+    secret: string;
+    account: ResolvedBotAccount;
+    config: OpenClawConfig;
+    runtime: WecomRuntimeEnv;
+    core: PluginRuntime;
+    statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+    welcomeText?: string;
+    network?: WecomNetworkConfig;
+};
+
+/**
+ * 启动 WebSocket 长链接客户端
+ * @returns cleanup 函数（用于注销）
+ */
+export function startWsClient(params: StartWsClientParams): () => void {
+    const {
+        accountId, botId, secret,
+        account, config, runtime, core,
+        statusSink, welcomeText,
+    } = params;
+
+    // 如果已有实例，先停止
+    stopWsClient(accountId);
+
+    const wsClient = new WSClient({
+        botId,
+        secret,
+        maxReconnectAttempts: -1, // 无限重连
+        logger: {
+            debug: (msg: string) => runtime.log?.(`[${accountId}][ws-sdk] ${msg}`),
+            info: (msg: string) => runtime.log?.(`[${accountId}][ws-sdk] ${msg}`),
+            warn: (msg: string) => runtime.log?.(`[${accountId}][ws-sdk] WARN: ${msg}`),
+            error: (msg: string) => runtime.error?.(`[${accountId}][ws-sdk] ERROR: ${msg}`),
+        },
+    });
+
+    wsClients.set(accountId, wsClient);
+
+    // 构建 WecomWebhookTarget 以复用 monitor 管线
+    const target: WecomWebhookTarget = {
+        account,
+        config,
+        runtime,
+        core,
+        path: `ws://${accountId}`,
+        statusSink,
+    };
+
+    // 设置消息和事件处理
+    setupMessageHandler({ wsClient, accountId, target });
+    setupEventHandler({ wsClient, accountId, target, welcomeText });
+
+    // 连接状态日志
+    wsClient.on("connected", () => {
+        runtime.log?.(`[${accountId}] ws: connected`);
+    });
+    wsClient.on("authenticated", () => {
+        runtime.log?.(`[${accountId}] ws: authenticated successfully`);
+    });
+    wsClient.on("disconnected", (reason: string) => {
+        runtime.log?.(`[${accountId}] ws: disconnected - ${reason}`);
+    });
+    wsClient.on("reconnecting", (attempt: number) => {
+        runtime.log?.(`[${accountId}] ws: reconnecting attempt=${attempt}`);
+    });
+    wsClient.on("error", (err: Error) => {
+        runtime.error?.(`[${accountId}] ws: error - ${err.message}`);
+    });
+
+    // 建立连接
+    wsClient.connect();
+    runtime.log?.(`[${accountId}] ws: starting connection (botId=${botId})`);
+
+    // 返回清理函数
+    return () => {
+        stopWsClient(accountId);
+    };
+}
+
+/**
+ * 停止指定账号的 WSClient
+ */
+export function stopWsClient(accountId: string): void {
+    const existing = wsClients.get(accountId);
+    if (existing) {
+        existing.disconnect();
+        wsClients.delete(accountId);
+    }
+}