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

package/dist/src/agent/handler.js

@@ -3,10 +3,12 @@
  * 处理 XML 格式回调
  */
 import { pathToFileURL } from "node:url";
+import os from "node:os";
 import path from "node:path";
 import { extractMsgType, extractFromUser, extractContent, extractChatId, extractMediaId, extractMsgId, extractFileName, extractAgentId, } from "../shared/xml-parser.js";
 import { sendText, downloadMedia, uploadMedia, sendMedia as sendAgentMedia } from "./api-client.js";
 import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
+import { processDynamicRouting } from "../dynamic-routing.js";
 import { DEFAULT_MEDIA_MAX_MB } from "../const.js";
 function resolveWecomMediaMaxBytes(config) {
     return config.channels?.wecom?.media?.maxBytes ?? DEFAULT_MEDIA_MAX_MB * 1024 * 1024;
@@ -331,7 +333,36 @@ async function processAgentMessage(params) {
         accountId: agent.accountId,
         peer: { kind: isGroup ? "group" : "direct", id: peerId },
     });
-    // ===== 动态 Agent 路由注入 (已移除) =====
+    // ===== 动态 Agent 路由处理 =====
+    const routingResult = processDynamicRouting({
+        route,
+        config,
+        core,
+        accountId: agent.accountId,
+        chatType: isGroup ? "group" : "dm",
+        chatId: peerId,
+        senderId: fromUser,
+        log: (msg) => log?.(msg.replace(/^\[dynamic-routing\]/, "[wecom-agent]")),
+        error: (msg) => error?.(msg.replace(/^\[dynamic-routing\]/, "[wecom-agent]")),
+    });
+    // 处理路由拦截
+    if (routingResult.rejected) {
+        error?.(`[wecom-agent] 🚫 routing guard: blocked default fallback accountId=${agent.accountId} matchedBy=${route.matchedBy} from=${fromUser}`);
+        try {
+            await sendText({ agent, toUser: fromUser, chatId: undefined, text: routingResult.rejectReason });
+            log?.(`[wecom-agent] routing guard prompt delivered to ${fromUser}`);
+        }
+        catch (err) {
+            error?.(`[wecom-agent] routing guard prompt failed: ${String(err)}`);
+        }
+        return;
+    }
+    // 应用动态路由结果
+    if (routingResult.routeModified) {
+        route.agentId = routingResult.finalAgentId;
+        route.sessionKey = routingResult.finalSessionKey;
+    }
+    // ===== 动态 Agent 路由处理结束 =====
     // 构建上下文
     const fromLabel = isGroup ? `group:${peerId}` : `user:${fromUser}`;
     const storePath = core.channel.session.resolveStorePath(config.session?.store, {
@@ -422,7 +453,7 @@ async function processAgentMessage(params) {
                     if (!p)
                         continue;
                     if (p.startsWith("~/") || p === "~") {
-                        const home = process.env.HOME || "/root";
+                        const home = os.homedir() || "/root";
                         p = p.replace(/^~/, home);
                     }
                     if (!mediaDirectivePaths.includes(p))

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

@@ -0,0 +1,37 @@
+/**
+ * **动态 Agent 路由模块**
+ *
+ * 为每个用户/群组自动生成独立的 Agent ID，实现会话隔离。
+ * 参考: openclaw-plugin-wecom/dynamic-agent.js
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+export interface DynamicAgentConfig {
+    enabled: boolean;
+    dmCreateAgent: boolean;
+    groupEnabled: boolean;
+    adminUsers: string[];
+}
+/**
+ * **getDynamicAgentConfig (读取动态 Agent 配置)**
+ *
+ * 从全局配置中读取动态 Agent 配置，提供默认值。
+ */
+export declare function getDynamicAgentConfig(config: OpenClawConfig): DynamicAgentConfig;
+/**
+ * **generateAgentId (生成动态 Agent ID)**
+ *
+ * 根据账号 + 聊天类型 + 对端 ID 生成确定性的 Agent ID，避免多账号串会话。
+ * 格式: wecom-{accountId}-{type}-{sanitizedPeerId}
+ */
+export declare function generateAgentId(chatType: "dm" | "group", peerId: string, accountId?: string): string;
+/**
+ * **shouldUseDynamicAgent (检查是否使用动态 Agent)**
+ *
+ * 根据配置和发送者信息判断是否应使用动态 Agent。
+ * 管理员（adminUsers）始终绕过动态路由，使用主 Agent。
+ */
+export declare function shouldUseDynamicAgent(params: {
+    chatType: "dm" | "group";
+    senderId: string;
+    config: OpenClawConfig;
+}): boolean;

package/dist/src/dynamic-agent.js

@@ -0,0 +1,60 @@
+/**
+ * **动态 Agent 路由模块**
+ *
+ * 为每个用户/群组自动生成独立的 Agent ID，实现会话隔离。
+ * 参考: openclaw-plugin-wecom/dynamic-agent.js
+ */
+/**
+ * **getDynamicAgentConfig (读取动态 Agent 配置)**
+ *
+ * 从全局配置中读取动态 Agent 配置，提供默认值。
+ */
+export function getDynamicAgentConfig(config) {
+    const dynamicAgents = config?.channels?.wecom?.dynamicAgents;
+    return {
+        enabled: dynamicAgents?.enabled ?? false,
+        dmCreateAgent: dynamicAgents?.dmCreateAgent ?? true,
+        groupEnabled: dynamicAgents?.groupEnabled ?? true,
+        adminUsers: dynamicAgents?.adminUsers ?? [],
+    };
+}
+function sanitizeDynamicIdPart(value) {
+    return String(value)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]/g, "_");
+}
+/**
+ * **generateAgentId (生成动态 Agent ID)**
+ *
+ * 根据账号 + 聊天类型 + 对端 ID 生成确定性的 Agent ID，避免多账号串会话。
+ * 格式: wecom-{accountId}-{type}-{sanitizedPeerId}
+ */
+export function generateAgentId(chatType, peerId, accountId) {
+    const sanitizedPeer = sanitizeDynamicIdPart(peerId) || "unknown";
+    const sanitizedAccountId = sanitizeDynamicIdPart(accountId ?? "default") || "default";
+    return `wecom-${sanitizedAccountId}-${chatType}-${sanitizedPeer}`;
+}
+/**
+ * **shouldUseDynamicAgent (检查是否使用动态 Agent)**
+ *
+ * 根据配置和发送者信息判断是否应使用动态 Agent。
+ * 管理员（adminUsers）始终绕过动态路由，使用主 Agent。
+ */
+export function shouldUseDynamicAgent(params) {
+    const { chatType, senderId, config } = params;
+    const dynamicConfig = getDynamicAgentConfig(config);
+    if (!dynamicConfig.enabled) {
+        return false;
+    }
+    // 管理员绕过动态路由
+    const sender = String(senderId).trim().toLowerCase();
+    const isAdmin = dynamicConfig.adminUsers.some((admin) => admin.trim().toLowerCase() === sender);
+    if (isAdmin) {
+        return false;
+    }
+    if (chatType === "group") {
+        return dynamicConfig.groupEnabled;
+    }
+    return dynamicConfig.dmCreateAgent;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 动态路由统一处理模块
+ * 提供统一的路由注入接口。
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+/**
+ * 路由对象（从 core.channel.routing.resolveAgentRoute 返回）
+ */
+export interface AgentRoute {
+    agentId: string;
+    sessionKey: string;
+    matchedBy: string;
+    accountId: string;
+    mainSessionKey?: string;
+}
+/**
+ * 动态路由处理参数
+ */
+export interface DynamicRoutingParams {
+    /** 原始路由对象 */
+    route: AgentRoute;
+    /** 全局配置 */
+    config: OpenClawConfig;
+    /** 插件运行时 */
+    core: PluginRuntime;
+    /** 账号 ID */
+    accountId: string;
+    /** 会话类型 */
+    chatType: "group" | "dm";
+    /** 对话 ID（群聊为 chatId，私聊为 userId） */
+    chatId: string;
+    /** 发送者用户 ID */
+    senderId: string;
+    /** 日志输出函数（可选） */
+    log?: (msg: string) => void;
+    /** 错误日志输出函数（可选） */
+    error?: (msg: string) => void;
+}
+/**
+ * 动态路由处理结果
+ */
+export interface DynamicRoutingResult {
+    /** 是否使用动态 Agent */
+    useDynamicAgent: boolean;
+    /** 是否被默认路由拦截 */
+    rejected: boolean;
+    /** 拒绝原因（如果 rejected=true） */
+    rejectReason?: string;
+    /** 最终的 agentId（可能被动态注入修改） */
+    finalAgentId: string;
+    /** 最终的 sessionKey（可能被动态注入修改） */
+    finalSessionKey: string;
+    /** 是否修改了路由（注入了动态 Agent） */
+    routeModified: boolean;
+}
+/**
+ * 统一处理动态路由注入逻辑
+ *
+ * 功能：
+ * 1. 判断是否需要使用动态 Agent
+ * 2. 根据 matchedBy 判断配置类型
+ * 3. 检查是否被默认路由拦截（fail-closed 策略）
+ * 4. 返回最终的路由信息（不修改传入的 route 对象）
+ * 5. 输出详细的调试日志
+ *
+ * **重要规则**：
+ * - matchedBy = "binding.peer" 或 "binding.peer.parent" → 跳过动态路由
+ * - matchedBy = "binding.account" 或其他 → 继续使用动态路由
+ * - matchedBy = "default" → 检查 fail-closed 策略
+ *
+ * @param params 动态路由处理参数
+ * @returns 处理结果
+ */
+export declare function processDynamicRouting(params: DynamicRoutingParams): DynamicRoutingResult;

package/dist/src/dynamic-routing.js

@@ -0,0 +1,124 @@
+/**
+ * 动态路由统一处理模块
+ * 提供统一的路由注入接口。
+ */
+import { shouldUseDynamicAgent, generateAgentId } from "./dynamic-agent.js";
+import { shouldRejectWecomDefaultRoute } from "./routing.js";
+/**
+ * 根据 matchedBy 和配置内容判断是否应该跳过动态路由
+ * **重要**：即使 matchedBy=binding.peer，也需要检查配置的 peer.kind 是否与实际聊天类型匹配
+ * @param params 判断参数
+ * @returns 是否跳过动态路由
+ */
+function shouldSkipDynamicRouting(params) {
+    const { matchedBy, config, route, chatType, log } = params;
+    // 只有精确匹配到 peer 时才可能跳过动态路由
+    if (matchedBy !== "binding.peer" && matchedBy !== "binding.peer.parent") {
+        return false;
+    }
+    const binding = config.bindings?.find(b => b.agentId === route.agentId);
+    if (!binding) {
+        log?.(`[dynamic-routing] ⚠️  警告：matchedBy=binding.peer，但在配置中找不到 agentId=${route.agentId} 的 binding`);
+        return false;
+    }
+    // 检查配置的 peer.kind 是否与实际聊天类型匹配
+    const configuredKind = binding.match?.peer?.kind;
+    if (!configuredKind) {
+        // 配置中没有指定 kind，使用动态路由
+        log?.(`[dynamic-routing] ℹ️  binding 未指定`);
+        return false;
+    }
+    const actualKind = chatType === "group" ? "group" : "direct";
+    if (configuredKind !== actualKind) {
+        // 类型不匹配，继续使用动态路由
+        log?.(`[dynamic-routing] ⚠️  binding 配置的聊天类型 (${configuredKind}) 与实际类型 (${actualKind}) 不匹配，继续使用动态路由`);
+        return false;
+    }
+    // 类型匹配，跳过动态路由
+    return true;
+}
+/**
+ * 统一处理动态路由注入逻辑
+ *
+ * 功能：
+ * 1. 判断是否需要使用动态 Agent
+ * 2. 根据 matchedBy 判断配置类型
+ * 3. 检查是否被默认路由拦截（fail-closed 策略）
+ * 4. 返回最终的路由信息（不修改传入的 route 对象）
+ * 5. 输出详细的调试日志
+ *
+ * **重要规则**：
+ * - matchedBy = "binding.peer" 或 "binding.peer.parent" → 跳过动态路由
+ * - matchedBy = "binding.account" 或其他 → 继续使用动态路由
+ * - matchedBy = "default" → 检查 fail-closed 策略
+ *
+ * @param params 动态路由处理参数
+ * @returns 处理结果
+ */
+export function processDynamicRouting(params) {
+    const { route, config, accountId, chatType, chatId, senderId, log } = params;
+    log?.(`[dynamic-routing] 🔍 调试 - matchedBy=${route.matchedBy}, agentId=${route.agentId}`);
+    if (route.matchedBy !== "default") {
+        // 根据 matchedBy 和配置内容判断是否跳过动态路由
+        if (shouldSkipDynamicRouting({ matchedBy: route.matchedBy, config, route, chatType, log })) {
+            // 精确配置（binding.peer）且类型匹配，跳过动态路由
+            log?.(`[dynamic-routing] ℹ️  检测到精确配置的 bindings (matchedBy=${route.matchedBy})，且聊天类型匹配，跳过动态路由`);
+            return {
+                useDynamicAgent: false,
+                rejected: false,
+                finalAgentId: route.agentId,
+                finalSessionKey: route.sessionKey,
+                routeModified: false,
+            };
+        }
+        else {
+            // 其他类型的配置（binding.account、binding.channel 等），继续使用动态路由
+            log?.(`[dynamic-routing] ℹ️  检测到非精确配置的 bindings (matchedBy=${route.matchedBy})，继续使用动态路由`);
+        }
+    }
+    // 判断是否使用动态 Agent
+    const useDynamicAgent = shouldUseDynamicAgent({
+        chatType,
+        senderId,
+        config,
+    });
+    // 检查是否被默认路由拦截
+    const rejected = shouldRejectWecomDefaultRoute({
+        cfg: config,
+        matchedBy: route.matchedBy,
+        useDynamicAgent,
+    });
+    if (rejected) {
+        const rejectReason = `当前账号（${accountId}）未绑定 OpenClaw Agent，已拒绝回退到默认主智能体。请在 bindings 中添加：{"agentId":"你的Agent","match":{"channel":"wecom","accountId":"${accountId}"}}`;
+        return {
+            useDynamicAgent,
+            rejected: true,
+            rejectReason,
+            finalAgentId: route.agentId,
+            finalSessionKey: route.sessionKey,
+            routeModified: false,
+        };
+    }
+    // 使用动态 Agent
+    if (useDynamicAgent) {
+        log?.(`[dynamic-routing] 原始路由信息: agentId=${route.agentId}, matchedBy=${route.matchedBy}, sessionKey=${route.sessionKey}`);
+        const targetAgentId = generateAgentId(chatType, chatId, accountId);
+        const targetSessionKey = `agent:${targetAgentId}:wecom:${accountId}:${chatType}:${chatId}`;
+        log?.(`[dynamic-routing] 🔄 路由注入: agentId=${targetAgentId}, sessionKey=${targetSessionKey}`);
+        return {
+            useDynamicAgent: true,
+            rejected: false,
+            finalAgentId: targetAgentId,
+            finalSessionKey: targetSessionKey,
+            routeModified: true,
+        };
+    }
+    // 不使用动态 Agent，返回原始路由
+    return {
+        useDynamicAgent: false,
+        rejected: false,
+        finalAgentId: route.agentId,
+        finalSessionKey: route.sessionKey,
+        routeModified: false,
+    };
+}

package/dist/src/monitor.js

@@ -19,6 +19,7 @@ import * as os from "os";
 import * as path from "path";
 import { WSClient, generateReqId, WSAuthFailureError, WSReconnectExhaustedError } from "@wecom/aibot-node-sdk";
 import { getWeComRuntime } from "./runtime.js";
+// @ts-ignore
 import { getDefaultMediaLocalRoots, resolveStateDir } from "./openclaw-compat.js";
 import { CHANNEL_ID, THINKING_MESSAGE, MEDIA_IMAGE_PLACEHOLDER, MEDIA_DOCUMENT_PLACEHOLDER, WS_HEARTBEAT_INTERVAL_MS, WS_MAX_RECONNECT_ATTEMPTS, WS_MAX_AUTH_FAILURE_ATTEMPTS, EVENT_ENTER_CHECK_UPDATE, CMD_ENTER_EVENT_REPLY, SCENE_WECOM_OPENCLAW, } from "./const.js";
 import { parseMessageContent } from "./message-parser.js";
@@ -31,6 +32,7 @@ import { checkGroupPolicy } from "./group-policy.js";
 import { checkDmPolicy } from "./dm-policy.js";
 import { setWeComWebSocket, setMessageState, deleteMessageState, setReqIdForChat, warmupReqIdStore, startMessageStateCleanup, stopMessageStateCleanup, cleanupAccount, } from "./state-manager.js";
 import { PLUGIN_VERSION } from "./version.js";
+import { processDynamicRouting } from "./dynamic-routing.js";
 /**
  * 去除文本中的 `<think>...</think>` 标签（支持跨行），返回剩余可见文本。
  * 用于判断大模型回复中是否包含实际用户可见内容（而非仅有 thinking 推理过程）。
@@ -98,13 +100,11 @@ function buildMediaErrorSummary(mediaUrl, result) {
 export { WeComCommand } from "./const.js";
 export { getWeComWebSocket, setReqIdForChat, getReqIdForChatAsync, getReqIdForChat, deleteReqIdForChat, warmupReqIdStore, flushReqIdStore, } from "./state-manager.js";
 export { sendWeComReply } from "./message-sender.js";
-// ============================================================================
-// 消息上下文构建
-// ============================================================================
 /**
  * 构建消息上下文
+ * @returns 消息上下文对象，或路由拒绝信息（当路由被拦截时）
  */
-function buildMessageContext(frame, account, config, text, mediaList, quoteContent) {
+function buildMessageContext(frame, account, config, text, mediaList, quoteContent, runtime) {
     const core = getWeComRuntime();
     const body = frame.body;
     const chatId = body.chatid || body.from.userid;
@@ -119,6 +119,32 @@ function buildMessageContext(frame, account, config, text, mediaList, quoteConte
             id: chatId,
         },
     });
+    // ===== 动态 Agent 路由注入 =====
+    const routingResult = processDynamicRouting({
+        route,
+        config,
+        core,
+        accountId: account.accountId,
+        chatType: chatType === "group" ? "group" : "dm",
+        chatId,
+        senderId: body.from.userid,
+        log: runtime?.log ? (...args) => runtime.log?.(...args) : undefined,
+        error: runtime?.error ? (...args) => runtime.error?.(...args) : undefined,
+    });
+    // 处理路由拦截
+    if (routingResult.rejected) {
+        runtime?.error?.(`[wecom] 🚫 routing guard: blocked default fallback accountId=${account.accountId} matchedBy=${route.matchedBy}`);
+        return {
+            rejected: true,
+            rejectReason: routingResult.rejectReason,
+        };
+    }
+    // 应用动态路由结果
+    if (routingResult.routeModified) {
+        route.agentId = routingResult.finalAgentId;
+        route.sessionKey = routingResult.finalSessionKey;
+    }
+    // ===== 动态 Agent 路由注入结束 =====
     // 构建会话标签
     const fromLabel = chatType === "group" ? `group:${chatId}` : `user:${body.from.userid}`;
     // 当只有媒体没有文本时，使用占位符标识媒体类型
@@ -162,7 +188,7 @@ function buildMessageContext(frame, account, config, text, mediaList, quoteConte
         MediaUrls: mediaPaths,
         ReplyToBody: quoteContent,
     });
-    return { ctxPayload, route, storePath, chatId, chatType };
+    return { rejected: false, ctxPayload, route, storePath, chatId, chatType };
 }
 /**
  * 发送"思考中"消息
@@ -553,7 +579,24 @@ async function processWeComMessageNow(entry) {
     //   await sendThinkingReply({ wsClient, frame, streamId, runtime });
     // }
     // Step 7: 构建上下文并路由到核心处理流程（带整体超时保护）
-    const { ctxPayload, route, storePath, chatId: resolvedChatId, chatType } = buildMessageContext(frame, account, config, text, mediaList, quoteContent);
+    const contextResult = buildMessageContext(frame, account, config, text, mediaList, quoteContent, runtime);
+    // 处理路由拦截
+    if (contextResult.rejected) {
+        runtime.log?.(`[wecom] Routing guard: sending rejection prompt to user`);
+        try {
+            await wsClient.sendMessage(chatId, {
+                msgtype: "markdown",
+                markdown: { content: contextResult.rejectReason },
+            });
+            runtime.log?.(`[wecom] Routing guard prompt delivered`);
+        }
+        catch (err) {
+            runtime.error?.(`[wecom] Routing guard prompt failed: ${String(err)}`);
+        }
+        cleanupState();
+        return;
+    }
+    const { ctxPayload, route, storePath, chatId: resolvedChatId, chatType } = contextResult;
     // runtime.log?.(`[plugin -> openclaw] body=${text}, mediaPaths=${JSON.stringify(mediaList.map(m => m.path))}${quoteContent ? `, quote=${quoteContent}` : ''}`);
     try {
         await routeAndDispatchMessage({

package/dist/src/openclaw-compat.d.ts

@@ -51,8 +51,6 @@ export declare function loadOutboundMediaFromUrl(mediaUrl: string, options?: Out
  * SDK 引用在模块加载时异步探测并缓存，调用时同步读取缓存。
  */
 export declare function addWildcardAllowFrom(allowFrom: string[]): string[];
-/** 通过框架 PluginRuntime 获取 openclaw 状态目录（避免直接访问环境变量） */
-export declare function resolveStateDir(): string;
 /**
  * 获取默认媒体本地路径白名单（兼容入口）
  *

package/dist/src/openclaw-compat.js

@@ -11,7 +11,8 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import * as os from "node:os";
 import { fileURLToPath } from "node:url";
-import { getWeComRuntime } from "./runtime.js";
+// @ts-ignore
+import { resolveStateDir } from "./state-dir-resolve";
 export const DEFAULT_ACCOUNT_ID = "default";
 const _sdkReady = import("openclaw/plugin-sdk/core")
     .then((sdk) => {
@@ -330,17 +331,6 @@ export function addWildcardAllowFrom(allowFrom) {
 // ============================================================================
 // getDefaultMediaLocalRoots —— 获取默认媒体本地路径白名单
 // ============================================================================
-/** 通过框架 PluginRuntime 获取 openclaw 状态目录（避免直接访问环境变量） */
-export function resolveStateDir() {
-    try {
-        const core = getWeComRuntime();
-        return core.state.resolveStateDir();
-    }
-    catch {
-        // fallback：runtime 尚未初始化时（如模块加载阶段），使用默认路径
-        return path.join(os.homedir(), ".openclaw");
-    }
-}
 /**
  * 获取默认媒体本地路径白名单（兼容入口）
  *

package/dist/src/routing.d.ts

@@ -0,0 +1,24 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { WeComMultiAccountConfig } from "./accounts.ts";
+/**
+ * 默认策略：
+ * - matrix（多账号）: 开启 fail-closed，防止未绑定账号回退到 main
+ * - legacy（单账号兼容）: 维持历史行为，不强制拦截
+ */
+/** 解析模式 */
+export type ResolvedMode = "disabled" | "legacy" | "matrix";
+/**
+ * 检测配置中启用的模式
+ */
+export declare function detectMode(config: WeComMultiAccountConfig | undefined): ResolvedMode;
+/**
+ * 默认策略：
+ * - matrix（多账号）: 开启 fail-closed，防止未绑定账号回退到 main
+ * - legacy（单账号兼容）: 维持历史行为，不强制拦截
+ */
+export declare function resolveWecomFailClosedOnDefaultRoute(cfg: OpenClawConfig): boolean;
+export declare function shouldRejectWecomDefaultRoute(params: {
+    cfg: OpenClawConfig;
+    matchedBy: string;
+    useDynamicAgent: boolean;
+}): boolean;

package/dist/src/routing.js

@@ -0,0 +1,34 @@
+/**
+ * 检测配置中启用的模式
+ */
+export function detectMode(config) {
+    if (!config || config.enabled === false)
+        return "disabled";
+    const accounts = config.accounts;
+    if (accounts && typeof accounts === "object") {
+        const enabledEntries = Object.values(accounts).filter((entry) => entry && entry.enabled !== false);
+        if (enabledEntries.length > 0)
+            return "matrix";
+    }
+    return "legacy";
+}
+/**
+ * 默认策略：
+ * - matrix（多账号）: 开启 fail-closed，防止未绑定账号回退到 main
+ * - legacy（单账号兼容）: 维持历史行为，不强制拦截
+ */
+export function resolveWecomFailClosedOnDefaultRoute(cfg) {
+    const wecom = cfg.channels?.wecom;
+    // @ts-ignore
+    const explicit = wecom?.routing?.failClosedOnDefaultRoute;
+    if (typeof explicit === "boolean")
+        return explicit;
+    return detectMode(wecom) === "matrix";
+}
+export function shouldRejectWecomDefaultRoute(params) {
+    if (params.matchedBy !== "default")
+        return false;
+    if (params.useDynamicAgent)
+        return false;
+    return resolveWecomFailClosedOnDefaultRoute(params.cfg);
+}

package/dist/src/state-dir-resolve.d.ts

@@ -0,0 +1,2 @@
+/** 解析 openclaw 状态目录 */
+export declare function resolveStateDir(): string;

package/dist/src/state-dir-resolve.js

@@ -0,0 +1,9 @@
+import * as path from "node:path";
+import * as os from "node:os";
+/** 解析 openclaw 状态目录 */
+export function resolveStateDir() {
+    const stateOverride = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+    if (stateOverride)
+        return stateOverride;
+    return path.join(os.homedir(), ".openclaw");
+}

package/dist/src/types/config.d.ts

@@ -78,3 +78,23 @@ export type WecomAgentConfig = {
     /** 允许的用户列表，为空表示允许所有人 */
     allowFrom?: Array<string | number>;
 };
+/** 路由行为配置 */
+export type WecomRoutingConfig = {
+    /**
+     * 当路由未命中 bindings（matchedBy=default）时是否拒绝继续处理。
+     * - true: fail-closed（推荐于多账号）
+     * - false: 允许回退默认 agent（历史兼容）
+     */
+    failClosedOnDefaultRoute?: boolean;
+};
+/** 动态 Agent 配置 */
+export type WecomDynamicAgentsConfig = {
+    /** 是否启用动态 Agent */
+    enabled?: boolean;
+    /** 私聊：是否为每个用户创建独立 Agent */
+    dmCreateAgent?: boolean;
+    /** 群聊：是否启用动态 Agent */
+    groupEnabled?: boolean;
+    /** 管理员列表（绕过动态路由，使用主 Agent） */
+    adminUsers?: string[];
+};

package/dist/src/webhook/monitor.js

@@ -5,12 +5,14 @@
  * 负责：入站消息解析、防抖聚合、Agent 调度、流式输出、超时兜底。
  */
 import { pathToFileURL } from "node:url";
+import os from "node:os";
 import { resolveWecomCommandAuthorization, buildWecomUnauthorizedCommandPrompt, } from "./command-auth.js";
 import { STREAM_MAX_BYTES, BOT_WINDOW_MS, BOT_SWITCH_MARGIN_MS, REQUEST_TIMEOUT_MS, } from "./types.js";
 import { getMonitorState } from "./gateway.js";
 import { sendText as sendAgentText, uploadMedia, sendMedia as sendAgentMedia } from "../agent/api-client.js";
 import { wecomFetch } from "./http.js";
 import { truncateUtf8Bytes, appendDmContent, buildFallbackPrompt, extractLocalFilePathsFromText, extractLocalImagePathsFromText, looksLikeSendLocalFileIntent, computeTaskKey, isAgentConfigured, guessContentTypeFromPath, buildStreamReplyFromState, computeMd5, resolveWecomMediaMaxBytes, buildCfgForDispatch, processInboundMessage, MIME_BY_EXT, resolveWecomSenderUserId, buildInboundBody, hasMedia, buildStreamResponse, buildStreamPlaceholderReply, buildStreamTextPlaceholderReply, } from "./helpers.js";
+import { processDynamicRouting } from "../dynamic-routing.js";
 // ============================================================================
 // 入站消息处理
 // ============================================================================
@@ -470,16 +472,10 @@ export async function startAgentForStream(params) {
     let videoFirstFramePath;
     if (mediaPath && mediaType?.startsWith("video/")) {
         try {
-            const { execFile } = await import("node:child_process");
-            const { promisify } = await import("node:util");
-            const execFileAsync = promisify(execFile);
-            const framePath = mediaPath.replace(/\.[^.]+$/, "_frame1.jpg");
-            await execFileAsync("ffmpeg", ["-i", mediaPath, "-vframes", "1", "-q:v", "2", "-y", framePath], { timeout: 10_000 });
-            const fs = await import("node:fs/promises");
-            const stat = await fs.stat(framePath);
-            if (stat.size > 0) {
-                videoFirstFramePath = framePath;
-                target.runtime.log?.(`[webhook] video: 第一帧提取成功 ${framePath} (${stat.size} bytes)`);
+            const { extractVideoFirstFrame } = await import("./video-frame.js");
+            videoFirstFramePath = await extractVideoFirstFrame(mediaPath);
+            if (videoFirstFramePath) {
+                target.runtime.log?.(`[webhook] video: 第一帧提取成功 ${videoFirstFramePath}`);
             }
         }
         catch (err) {
@@ -487,7 +483,7 @@ export async function startAgentForStream(params) {
         }
     }
     // ──────────────────────────────────────────────────────────────────
-    // 4. 路由解析
+    // 4. 路由解析 + 动态路由处理
     // ──────────────────────────────────────────────────────────────────
     const route = core.channel.routing.resolveAgentRoute({
         cfg: config,
@@ -495,6 +491,43 @@ export async function startAgentForStream(params) {
         accountId: account.accountId,
         peer: { kind: chatType === "group" ? "group" : "direct", id: chatId },
     });
+    // ===== 动态 Agent 路由处理 =====
+    const routingResult = processDynamicRouting({
+        route,
+        config,
+        core,
+        accountId: account.accountId,
+        chatType: chatType === "group" ? "group" : "dm",
+        chatId,
+        senderId: userid,
+        log: (msg) => target.runtime.log?.(msg.replace(/^\[dynamic-routing\]/, "[webhook]")),
+        error: (msg) => target.runtime.error?.(msg.replace(/^\[dynamic-routing\]/, "[webhook]")),
+    });
+    // 处理路由拦截
+    if (routingResult.rejected) {
+        target.runtime.error?.(`[wecom] routing guard: blocked default fallback accountId=${account.accountId} matchedBy=${route.matchedBy} streamId=${streamId}`);
+        if (account.agent) {
+            try {
+                await sendAgentText({
+                    agent: account.agent,
+                    toUser: chatType === "direct" ? userid : undefined,
+                    chatId: chatType === "group" ? chatId : undefined,
+                    text: routingResult.rejectReason,
+                });
+                target.runtime.log?.(`[webhook] routing guard prompt delivered to ${chatType === "direct" ? userid : chatId}`);
+            }
+            catch (err) {
+                target.runtime.error?.(`[webhook] routing guard prompt failed: ${String(err)}`);
+            }
+        }
+        return;
+    }
+    // 应用动态路由结果
+    if (routingResult.routeModified) {
+        route.agentId = routingResult.finalAgentId;
+        route.sessionKey = routingResult.finalSessionKey;
+    }
+    // ===== 动态 Agent 路由处理结束 =====
     // ──────────────────────────────────────────────────────────────────
     // 5. Agent Envelope 格式化（对齐原版）
     // ──────────────────────────────────────────────────────────────────
@@ -777,7 +810,7 @@ export async function startAgentForStream(params) {
                     if (!p)
                         continue;
                     if (p.startsWith("~/") || p === "~") {
-                        const home = process.env.HOME || "/root";
+                        const home = os.homedir() || "/root";
                         p = p.replace(/^~/, home);
                     }
                     if (!mediaDirectivePaths.includes(p))

package/dist/src/webhook/video-frame.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 视频第一帧提取（ffmpeg）
+ *
+ * 独立文件，避免 child_process 与网络请求在同一文件中触发安全扫描误报。
+ */
+/**
+ * 使用 ffmpeg 提取视频第一帧为 JPEG 图片。
+ *
+ * @param mediaPath 视频文件路径
+ * @param timeoutMs 超时时间（默认 10s）
+ * @returns 成功返回帧图片路径，失败或 ffmpeg 不可用返回 undefined
+ */
+export declare function extractVideoFirstFrame(mediaPath: string, timeoutMs?: number): Promise<string | undefined>;

package/dist/src/webhook/video-frame.js

@@ -0,0 +1,30 @@
+/**
+ * 视频第一帧提取（ffmpeg）
+ *
+ * 独立文件，避免 child_process 与网络请求在同一文件中触发安全扫描误报。
+ */
+/**
+ * 使用 ffmpeg 提取视频第一帧为 JPEG 图片。
+ *
+ * @param mediaPath 视频文件路径
+ * @param timeoutMs 超时时间（默认 10s）
+ * @returns 成功返回帧图片路径，失败或 ffmpeg 不可用返回 undefined
+ */
+export async function extractVideoFirstFrame(mediaPath, timeoutMs = 10_000) {
+    try {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const fs = await import("node:fs/promises");
+        const execFileAsync = promisify(execFile);
+        const framePath = mediaPath.replace(/\.[^.]+$/, "_frame1.jpg");
+        await execFileAsync("ffmpeg", ["-i", mediaPath, "-vframes", "1", "-q:v", "2", "-y", framePath], { timeout: timeoutMs });
+        const stat = await fs.stat(framePath);
+        if (stat.size > 0) {
+            return framePath;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.3.31-beta.0",
+  "version": "2026.3.31-beta.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",