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

package/README.md

@@ -19,7 +19,7 @@
 
 **WeCom channel plugin for [OpenClaw](https://github.com/openclaw)** — by the Tencent WeCom team.
 
-> A channel plugin powered by WeCom. Supports **Bot mode** (WebSocket long-polling) and **Agent mode** (HTTP webhook with XML encrypted callbacks). Direct messages, group chats, streaming replies, and proactive messaging.
+> A channel plugin powered by WeCom. Supports **Bot mode** (WebSocket long-polling or HTTP webhook with JSON callbacks) and **Agent mode** (HTTP webhook with XML encrypted callbacks). Direct messages, group chats, streaming replies, and proactive messaging.
 
 ---
 
@@ -28,16 +28,20 @@
 
 ## ✨ Features
 
-- 🔗 **Dual-mode**: Bot (WebSocket) and Agent (HTTP webhook) can run independently or together
+- 🔗 **Dual-mode**: Bot (WebSocket / Webhook) and Agent (HTTP webhook) can run independently or together
 - 💬 Supports both direct messages (DM) and group chat
-- 📤 Proactive messaging to specific users or groups
-- 🖼️ Receives and processes image and file messages with automatic downloading
+- 📤 Proactive messaging to specific users, groups, departments, or tags
+- 🖼️ Receives and processes image, voice, video, and file messages with automatic downloading
 - ⏳ Streaming replies with "thinking" placeholder messages (Bot mode)
 - 🔐 Agent mode: AES-256-CBC encrypted XML callbacks with SHA1 signature verification
 - 📝 Markdown formatting support for replies
+- 🃏 Template card messages (text_notice, news_notice, button_interaction, vote_interaction, multiple_interaction)
 - 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)
 - 👥 Multi-account support: run multiple WeCom accounts with independent bot/agent configs
-- ⚡ Auto heartbeat keep-alive and reconnection (up to 100 reconnect attempts)
+- 🧩 MCP tool integration (`wecom_mcp`) for calling WeCom MCP Server
+- 🔀 Dynamic Agent routing: auto-create isolated agents per user/group
+- 📁 Local file sending with configurable media path allowlist (`mediaLocalRoots`)
+- ⚡ Auto heartbeat keep-alive and reconnection (up to 10 reconnect attempts)
 - 🧙 Interactive CLI setup wizard
 
 ---
@@ -46,7 +50,7 @@
 
 ### Requirements
 
-- OpenClaw `>= 2026.2.13`
+- OpenClaw `>= 2026.3.28`
 
 ### Quick Install
 
@@ -97,22 +101,72 @@ The plugin supports two connection modes that can be used independently or toget
 
 | Mode | Connection | Message Format | Use Case |
 |------|-----------|---------------|----------|
-| **Bot** (智能体) | WebSocket long-polling | JSON | Quick setup, streaming replies |
+| **Bot** (智能体) | WebSocket (default) or HTTP webhook | JSON | Quick setup, streaming replies |
 | **Agent** (自建应用) | HTTP webhook callbacks | XML | Enterprise apps, API-driven messaging |
 
+> **Note**: Bot mode supports two connection methods via `connectionMode`:
+> - `websocket` (default) — WebSocket long-polling, requires `botId` + `secret`
+> - `webhook` — HTTP callback, requires `token` + `encodingAESKey`
+
 ### Bot Mode Configuration
 
+#### Core Settings
+
+| Config Path | Description | Options | Default |
+|---|---|---|---|
+| `channels.wecom.enabled` | Enable the channel | `true` / `false` | `false` |
+| `channels.wecom.connectionMode` | Bot connection mode | `websocket` / `webhook` | `websocket` |
+| `channels.wecom.name` | Account display name | — | `企业微信` |
+
+#### WebSocket Mode (default)
+
 | Config Path | Description | Options | Default |
 |---|---|---|---|
 | `channels.wecom.botId` | WeCom bot ID | — | — |
 | `channels.wecom.secret` | WeCom bot secret | — | — |
-| `channels.wecom.enabled` | Enable the channel | `true` / `false` | `false` |
 | `channels.wecom.websocketUrl` | WebSocket endpoint | — | `wss://openws.work.weixin.qq.com` |
+| `channels.wecom.sendThinkingMessage` | Send "thinking" placeholder | `true` / `false` | `true` |
+
+#### Webhook Mode (`connectionMode: "webhook"`)
+
+| Config Path | Description | Options | Default |
+|---|---|---|---|
+| `channels.wecom.token` | Webhook verification token | — | — |
+| `channels.wecom.encodingAESKey` | AES encryption key (43 chars Base64) | — | — |
+| `channels.wecom.receiveId` | Receiver ID (for decryption verification) | — | — |
+| `channels.wecom.welcomeText` | Welcome message on enter_chat event | — | — |
+| `channels.wecom.streamPlaceholderContent` | Stream placeholder content | — | — |
+
+#### Access Control
+
+| Config Path | Description | Options | Default |
+|---|---|---|---|
 | `channels.wecom.dmPolicy` | DM access policy | `pairing` / `open` / `allowlist` / `disabled` | `open` |
 | `channels.wecom.allowFrom` | DM allowlist (user IDs) | — | `[]` |
 | `channels.wecom.groupPolicy` | Group chat access policy | `open` / `allowlist` / `disabled` | `open` |
 | `channels.wecom.groupAllowFrom` | Group allowlist (group IDs) | — | `[]` |
-| `channels.wecom.sendThinkingMessage` | Send "thinking" placeholder | `true` / `false` | `true` |
+| `channels.wecom.groups` | Per-group config (e.g. sender allowlist) | — | `{}` |
+
+#### Media Settings
+
+| Config Path | Description | Default |
+|---|---|---|
+| `channels.wecom.mediaLocalRoots` | Extra local paths allowed for media sending (supports `~`) | `[]` |
+| `channels.wecom.media.maxBytes` | Max media file size in bytes | `5242880` (5MB) |
+| `channels.wecom.media.tempDir` | Temp directory for media processing | — |
+| `channels.wecom.media.retentionHours` | Media file retention hours | — |
+| `channels.wecom.media.cleanupOnStart` | Clean temp media on startup | — |
+
+#### Network Settings
+
+| Config Path | Description | Default |
+|---|---|---|
+| `channels.wecom.network.timeoutMs` | HTTP request timeout (ms) | — |
+| `channels.wecom.network.retries` | Number of retries | — |
+| `channels.wecom.network.retryDelayMs` | Delay between retries (ms) | — |
+| `channels.wecom.network.egressProxyUrl` | Egress proxy URL for trusted IP scenarios | — |
+
+> **Egress Proxy Priority**: `channels.wecom.network.egressProxyUrl` > `OPENCLAW_WECOM_EGRESS_PROXY_URL` > `WECOM_EGRESS_PROXY_URL` > `HTTPS_PROXY` > `ALL_PROXY` > `HTTP_PROXY`
 
 ### Agent Mode Configuration
 
@@ -122,7 +176,7 @@ Agent mode uses HTTP webhook callbacks with XML encrypted messages. You need to
 
 1. Create a self-built app in [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#apps)
 2. In the app settings, go to "API Receive" (API接收) and configure:
-   - **URL**: `https://<your-gateway-host>/plugins/wecom/agent` (or `/plugins/wecom/agent/<accountId>` for multi-account)
+   - **URL**: `https://<your-gateway-host>/plugins/wecom/agent/<accountId>`（例如 `/plugins/wecom/agent/default`）；单账号模式也可使用 `/plugins/wecom/agent`
    - **Token**: auto-generated or custom
    - **EncodingAESKey**: auto-generated or custom
 3. Note down the **CorpID**, **CorpSecret**, **Token**, and **EncodingAESKey**
@@ -167,14 +221,29 @@ openclaw gateway restart
 | `channels.wecom.agent.agentId` | App agent ID | No (needed for proactive messaging) |
 | `channels.wecom.agent.token` | Callback verification token | Yes |
 | `channels.wecom.agent.encodingAESKey` | Callback encryption key (43 chars) | Yes |
+| `channels.wecom.agent.welcomeText` | Welcome message | No |
+| `channels.wecom.agent.dmPolicy` | DM access policy (overrides top-level) | No |
+| `channels.wecom.agent.allowFrom` | DM allowlist (overrides top-level) | No |
 
 #### Webhook Paths
 
+**Agent Mode:**
+
+| Path | Description |
+|---|---|
+| `/plugins/wecom/agent/<accountId>` | 推荐路径（例如 `/plugins/wecom/agent/default`） |
+| `/plugins/wecom/agent/default` | 多账号模式下自动路由到默认账号（即使默认账号 ID 不是 `default`） |
+| `/plugins/wecom/agent` | 兼容路径（单账号 / 多账号签名匹配） |
+| `/wecom/agent` | Legacy 兼容路径 |
+
+**Bot Webhook Mode** (`connectionMode: "webhook"`):
+
 | Path | Description |
 |---|---|
-| `/plugins/wecom/agent` | Recommended path (single account) |
-| `/plugins/wecom/agent/<accountId>` | Multi-account path |
-| `/wecom/agent` | Legacy compatible path |
+| `/plugins/wecom/bot` | Recommended path (single account) |
+| `/plugins/wecom/bot/<accountId>` | Multi-account path |
+| `/wecom/bot` | Legacy compatible path |
+| `/wecom` | Legacy compatible path |
 
 ### Outbound Delivery (Bot WS → Agent HTTP Fallback)
 
@@ -213,19 +282,19 @@ Bot and Agent can run simultaneously on the same account. Bot handles WebSocket
 
 ### Multi-Account Configuration
 
-Use `accounts` to configure multiple WeCom accounts, each with optional bot and/or agent sub-configs:
+Use `accounts` to configure multiple WeCom accounts, each with optional bot and/or agent sub-configs. Account-level fields override top-level fields of the same name.
 
 ```json
 {
   "channels": {
     "wecom": {
       "enabled": true,
+      "defaultAccount": "main",
+      "dmPolicy": "open",
       "accounts": {
         "main": {
-          "bot": {
-            "botId": "bot-id-1",
-            "secret": "secret-1"
-          },
+          "botId": "bot-id-1",
+          "secret": "secret-1",
           "agent": {
             "corpId": "ww1234567890abcdef",
             "corpSecret": "secret-a",
@@ -235,6 +304,8 @@ Use `accounts` to configure multiple WeCom accounts, each with optional bot and/
           }
         },
         "support": {
+          "dmPolicy": "allowlist",
+          "allowFrom": ["admin1"],
           "agent": {
             "corpId": "ww1234567890abcdef",
             "corpSecret": "secret-b",
@@ -249,6 +320,47 @@ Use `accounts` to configure multiple WeCom accounts, each with optional bot and/
 }
 ```
 
+> **Note**: In multi-account mode, `routing.failClosedOnDefaultRoute` defaults to `true` — accounts without explicit `bindings` will not fall back to the default agent. Configure bindings for each account:
+> ```json
+> {
+>   "bindings": [
+>     { "agentId": "your-agent", "match": { "channel": "wecom", "accountId": "main" } }
+>   ]
+> }
+> ```
+
+### Dynamic Agent Configuration
+
+Dynamic Agent routing automatically creates isolated agents per user or group, enabling session isolation.
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dynamicAgents": {
+        "enabled": true,
+        "dmCreateAgent": true,
+        "groupEnabled": true,
+        "adminUsers": ["admin_user_id"]
+      }
+    }
+  }
+}
+```
+
+| Config Path | Description | Default |
+|---|---|---|
+| `channels.wecom.dynamicAgents.enabled` | Enable dynamic agent routing | `false` |
+| `channels.wecom.dynamicAgents.dmCreateAgent` | Create isolated agent per DM user | `true` |
+| `channels.wecom.dynamicAgents.groupEnabled` | Enable dynamic agent for group chats | `true` |
+| `channels.wecom.dynamicAgents.adminUsers` | Admin users (bypass dynamic routing, use main agent) | `[]` |
+
+### Routing Configuration
+
+| Config Path | Description | Default |
+|---|---|---|
+| `channels.wecom.routing.failClosedOnDefaultRoute` | Reject unbound accounts from falling back to default agent | `true` (multi-account) / `false` (single account) |
+
 ---
 
 ## 🔒 Access Control

package/dist/index.js

@@ -3,7 +3,7 @@ import { wecomPlugin } from "./src/channel.js";
 import { createWeComMcpTool } from "./src/mcp/index.js";
 import { setWeComRuntime } from "./src/runtime.js";
 import { CHANNEL_ID, WEBHOOK_PATHS } from "./src/const.js";
-import { handleWecomAgentWebhookRequest } from "./src/agent/webhook.js";
+import { createWecomAgentWebhookHandler } from "./src/agent/webhook.js";
 import { handleWecomWebhookRequest } from "./src/webhook/index.js";
 // ============================================================================
 // 需要自动注入 tools.alsoAllow 的工具名列表
@@ -66,16 +66,17 @@ const plugin = {
         api.registerChannel({ plugin: wecomPlugin });
         // 注册 wecom_mcp：通过 HTTP 直接调用企业微信 MCP Server
         api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
+        const agentWebhookHandler = createWecomAgentWebhookHandler(api.runtime);
         // 注册 Agent 模式 HTTP 路由（prefix match 覆盖带 accountId 的子路径）
         api.registerHttpRoute({
             path: WEBHOOK_PATHS.AGENT_PLUGIN,
-            handler: handleWecomAgentWebhookRequest,
+            handler: agentWebhookHandler,
             auth: "plugin",
             match: "prefix",
         });
         api.registerHttpRoute({
             path: WEBHOOK_PATHS.AGENT,
-            handler: handleWecomAgentWebhookRequest,
+            handler: agentWebhookHandler,
             auth: "plugin",
             match: "prefix",
         });

package/dist/src/agent/handler.js

@@ -345,18 +345,6 @@ async function processAgentMessage(params) {
         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;

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 } from "openclaw/plugin-sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 import type { ResolvedAgentAccount } from "../types/index.js";
 export type AgentWebhookTarget = {
     agent: ResolvedAgentAccount;
@@ -20,4 +20,5 @@ export type AgentWebhookTarget = {
 };
 export declare function registerAgentWebhookTarget(target: AgentWebhookTarget): void;
 export declare function deregisterAgentWebhookTarget(accountId: string): void;
-export declare function handleWecomAgentWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean | void>;
+export declare function createWecomAgentWebhookHandler(runtime: PluginRuntime): (req: IncomingMessage, res: ServerResponse) => Promise<boolean | void>;
+export declare function handleWecomAgentWebhookRequest(req: IncomingMessage, res: ServerResponse, runtime: PluginRuntime): Promise<boolean | void>;

package/dist/src/agent/webhook.js

@@ -11,7 +11,6 @@ import { WecomCrypto } from "@wecom/aibot-node-sdk";
 import { extractEncryptFromXml } from "./xml.js";
 import { parseXml, extractAgentId } from "../shared/xml-parser.js";
 import { handleAgentWebhook } from "./index.js";
-import { getWeComRuntime } from "../runtime.js";
 import { WEBHOOK_PATHS, LIMITS } from "../const.js";
 // ============================================================================
 // Target Registry
@@ -92,7 +91,10 @@ function normalizeAgentIdValue(value) {
 // ============================================================================
 // Main HTTP handler
 // ============================================================================
-export async function handleWecomAgentWebhookRequest(req, res) {
+export function createWecomAgentWebhookHandler(runtime) {
+    return (req, res) => handleWecomAgentWebhookRequest(req, res, runtime);
+}
+export async function handleWecomAgentWebhookRequest(req, res, runtime) {
     const path = resolvePath(req);
     const reqId = crypto.randomUUID().slice(0, 8);
     // 检查是否为 Agent 路径
@@ -204,7 +206,7 @@ export async function handleWecomAgentWebhookRequest(req, res) {
         inboundAgentId !== selected.agent.agentId) {
         selected.runtime.error?.(`[wecom] inbound(agent): reqId=${reqId} accountId=${selected.agent.accountId} agentId_mismatch expected=${selected.agent.agentId} actual=${inboundAgentId}`);
     }
-    const core = getWeComRuntime();
+    const core = runtime;
     selected.runtime.log?.(`[wecom] inbound(agent): reqId=${reqId} method=POST remote=${req.socket?.remoteAddress ?? "unknown"} accountId=${selected.agent.accountId}`);
     return handleAgentWebhook({
         req,

package/dist/src/channel.js

@@ -416,10 +416,19 @@ export const wecomPlugin = {
             const agent = account.agent;
             if (agent?.configured) {
                 const isMulti = hasMultiAccounts(ctx.cfg);
+                const defaultId = resolveDefaultWeComAccountId(ctx.cfg);
+                const isDefault = ctx.accountId === defaultId;
                 const paths = isMulti
                     ? [
                         `${WEBHOOK_PATHS.AGENT_PLUGIN}/${ctx.accountId}`,
                         `${WEBHOOK_PATHS.AGENT}/${ctx.accountId}`,
+                        // 默认账号额外注册 /default 别名路径
+                        ...(isDefault && ctx.accountId !== DEFAULT_ACCOUNT_ID
+                            ? [
+                                `${WEBHOOK_PATHS.AGENT_PLUGIN}/${DEFAULT_ACCOUNT_ID}`,
+                                `${WEBHOOK_PATHS.AGENT}/${DEFAULT_ACCOUNT_ID}`,
+                            ]
+                            : []),
                         WEBHOOK_PATHS.AGENT_PLUGIN,
                         WEBHOOK_PATHS.AGENT,
                     ]

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

@@ -43,10 +43,6 @@ export interface DynamicRoutingParams {
 export interface DynamicRoutingResult {
     /** 是否使用动态 Agent */
     useDynamicAgent: boolean;
-    /** 是否被默认路由拦截 */
-    rejected: boolean;
-    /** 拒绝原因（如果 rejected=true） */
-    rejectReason?: string;
     /** 最终的 agentId（可能被动态注入修改） */
     finalAgentId: string;
     /** 最终的 sessionKey（可能被动态注入修改） */
@@ -60,14 +56,8 @@ export interface DynamicRoutingResult {
  * 功能：
  * 1. 判断是否需要使用动态 Agent
  * 2. 根据 matchedBy 判断配置类型
- * 3. 检查是否被默认路由拦截（fail-closed 策略）
- * 4. 返回最终的路由信息（不修改传入的 route 对象）
- * 5. 输出详细的调试日志
- *
- * **重要规则**：
- * - matchedBy = "binding.peer" 或 "binding.peer.parent" → 跳过动态路由
- * - matchedBy = "binding.account" 或其他 → 继续使用动态路由
- * - matchedBy = "default" → 检查 fail-closed 策略
+ * 3. 返回最终的路由信息（不修改传入的 route 对象）
+ * 4. 输出详细的调试日志
  *
  * @param params 动态路由处理参数
  * @returns 处理结果

package/dist/src/dynamic-routing.js

@@ -3,54 +3,14 @@
  * 提供统一的路由注入接口。
  */
 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 策略
+ * 3. 返回最终的路由信息（不修改传入的 route 对象）
+ * 4. 输出详细的调试日志
  *
  * @param params 动态路由处理参数
  * @returns 处理结果
@@ -59,22 +19,13 @@ 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})，继续使用动态路由`);
-        }
+        log?.(`[dynamic-routing] ℹ️  检测到匹配的 bindings (matchedBy=${route.matchedBy})，跳过动态路由`);
+        return {
+            useDynamicAgent: false,
+            finalAgentId: route.agentId,
+            finalSessionKey: route.sessionKey,
+            routeModified: false,
+        };
     }
     // 判断是否使用动态 Agent
     const useDynamicAgent = shouldUseDynamicAgent({
@@ -82,23 +33,7 @@ export function processDynamicRouting(params) {
         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,
-        };
-    }
+    log?.(`[dynamic-routing] 是否使用动态路由: useDynamicAgent=${useDynamicAgent}`);
     // 使用动态 Agent
     if (useDynamicAgent) {
         log?.(`[dynamic-routing] 原始路由信息: agentId=${route.agentId}, matchedBy=${route.matchedBy}, sessionKey=${route.sessionKey}`);
@@ -107,16 +42,15 @@ export function processDynamicRouting(params) {
         log?.(`[dynamic-routing] 🔄 路由注入: agentId=${targetAgentId}, sessionKey=${targetSessionKey}`);
         return {
             useDynamicAgent: true,
-            rejected: false,
             finalAgentId: targetAgentId,
             finalSessionKey: targetSessionKey,
             routeModified: true,
         };
     }
+    log?.('[dynamic-routing] 🔄不使用动态路由');
     // 不使用动态 Agent，返回原始路由
     return {
         useDynamicAgent: false,
-        rejected: false,
         finalAgentId: route.agentId,
         finalSessionKey: route.sessionKey,
         routeModified: false,

package/dist/src/monitor.js

@@ -19,7 +19,6 @@ 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";
@@ -100,9 +99,12 @@ 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 消息上下文对象，或路由拒绝信息（当路由被拦截时）
+ * @returns 消息上下文对象
  */
 function buildMessageContext(frame, account, config, text, mediaList, quoteContent, runtime) {
     const core = getWeComRuntime();
@@ -131,14 +133,6 @@ function buildMessageContext(frame, account, config, text, mediaList, quoteConte
         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;
@@ -188,7 +182,7 @@ function buildMessageContext(frame, account, config, text, mediaList, quoteConte
         MediaUrls: mediaPaths,
         ReplyToBody: quoteContent,
     });
-    return { rejected: false, ctxPayload, route, storePath, chatId, chatType };
+    return { ctxPayload, route, storePath, chatId, chatType };
 }
 /**
  * 发送"思考中"消息
@@ -579,24 +573,7 @@ async function processWeComMessageNow(entry) {
     //   await sendThinkingReply({ wsClient, frame, streamId, runtime });
     // }
     // Step 7: 构建上下文并路由到核心处理流程（带整体超时保护）
-    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;
+    const { ctxPayload, route, storePath, chatId: resolvedChatId, chatType } = buildMessageContext(frame, account, config, text, mediaList, quoteContent, runtime);
     // 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

@@ -7,6 +7,8 @@
  * 本模块在加载时一次性探测 SDK 导出，存在则直接 re-export SDK 版本，
  * 不存在则导出 fallback 实现。其他模块统一从本文件导入，无需关心底层兼容细节。
  */
+import { resolveStateDir } from "./state-dir-resolve.js";
+export { resolveStateDir };
 export declare const DEFAULT_ACCOUNT_ID = "default";
 /** 与 openclaw plugin-sdk 中 WebMediaResult 兼容的类型 */
 export type WebMediaResult = {

package/dist/src/openclaw-compat.js

@@ -11,8 +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";
-// @ts-ignore
-import { resolveStateDir } from "./state-dir-resolve";
+import { resolveStateDir } from "./state-dir-resolve.js";
+export { resolveStateDir };
 export const DEFAULT_ACCOUNT_ID = "default";
 const _sdkReady = import("openclaw/plugin-sdk/core")
     .then((sdk) => {

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

@@ -78,15 +78,6 @@ 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 */

package/dist/src/utils.d.ts

@@ -3,7 +3,7 @@
  */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import type { ResolvedAgentAccount } from "./types/account.js";
-import type { WecomAgentConfig, WecomNetworkConfig, WecomMediaConfig } from "./types/config.js";
+import type { WecomAgentConfig, WecomNetworkConfig, WecomMediaConfig, WecomDynamicAgentsConfig } from "./types/config.js";
 /**
  * 企业微信群组配置
  */
@@ -38,6 +38,8 @@ export interface WeComConfig {
     network?: WecomNetworkConfig;
     /** 媒体处理配置 */
     media?: WecomMediaConfig;
+    /** 动态 Agent 配置 */
+    dynamicAgents?: WecomDynamicAgentsConfig;
     /** 连接模式：webhook | websocket（默认 websocket） */
     connectionMode?: "webhook" | "websocket";
     /** Webhook 验证 token */

package/dist/src/webhook/monitor.js

@@ -503,25 +503,6 @@ export async function startAgentForStream(params) {
         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;

package/package.json

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

package/skills/wecom-doc-manager/references/api-edit-doc-content.md

@@ -65,4 +65,4 @@
 
 - `content_type` 当前仅支持 `1`（Markdown 格式）
 - 此操作为**覆写**，会替换文档全部内容
-- 建议先调用 `get_document` 了解当前内容再编辑
+- 建议先调用 `get_doc_content` 了解当前内容再编辑

package/skills/wecom-meeting-create/SKILL.md

@@ -39,7 +39,7 @@ wecom-meeting-create 提供企业微信预约会议的创建能力, 支持设置
 | `meeting_duration`       | integer | 是   | 会议持续时长 (秒), 例如 3600 = 1 小时             |
 | `description`            | string  | 否   | 会议描述                                          |
 | `location`               | string  | 否   | 会议地点                                          |
-| `invitees`               | object  | 是   | 被邀请人, 格式:`{"userid": ["lisi", "wangwu"]}` |
+| `invitees`               | object  | 否   | 被邀请人, 格式:`{"userid": ["lisi", "wangwu"]}` |
 | `settings`               | object  | 否   | 会议设置 (详见下方)                               |
 
 > 被邀请人 userid 通过 `wecom-contact-lookup` 技能获取

package/skills/wecom-meeting-manage/SKILL.md

@@ -63,7 +63,7 @@ wecom-meeting-manage 提供企业微信会议管理能力, 包含以下功能:
 | 参数          | 类型   | 必填 | 说明                                   |
 | ------------- | ------ | ---- | -------------------------------------- |
 | `meetingid` | string | 是   | 会议 ID, 通过 `wecom-meeting-query` 技能获取                          |
-| `invitees`  | array  | 否   | 受邀成员列表, 每项包含 `userid` 字段 |
+| `invitees`  | array  | 是   | 受邀成员列表, 每项包含 `userid` 字段 |
 
 > **注意**: invitees 为全量覆盖, 传入的列表将替换现有成员列表.
 > invitees 的 userid 通过 `wecom-contact-lookup` 技能获取
@@ -92,7 +92,7 @@ wecom-meeting-manage 提供企业微信会议管理能力, 包含以下功能:
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting cancel_meeting '{"meetingid": "<target_meetingid>"}'`
 
-4. **展示结果**:
+3. **展示结果**:
 
 ```
 ✅ 会议已取消: 技术方案评审
@@ -107,7 +107,7 @@ wecom-meeting-manage 提供企业微信会议管理能力, 包含以下功能:
 **步骤:**
 
 1. **定位会议**: 通过 `wecom-meeting-query` 技能查询会议列表 + 匹配找到目标会议.
-2. **获取当前受邀成员**: `set_invite_members` 为全量覆盖, 必须先通过 `wecom-meeting-query` 技能的 `get_meeting_info` 获取会议详情, 获取现有成员后再合并.
+2. **获取当前受邀成员**: `set_invite_meeting_members` 为全量覆盖, 必须先通过 `wecom-meeting-query` 技能的 `get_meeting_info` 获取会议详情, 获取现有成员后再合并.
 3. **通讯录查询**: 调用 `wecom-contact-lookup` 技能获取通讯录成员, 按姓名筛选出王五的 userid.
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'`
@@ -119,7 +119,7 @@ wecom-meeting-manage 提供企业微信会议管理能力, 包含以下功能:
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting set_invite_meeting_members '{"meetingid": "<target_meetingid>", "invitees": [{"userid": "zhangsan"}, {"userid": "lisi"}, {"userid": "wangwu"}]}'`
 
-7. **展示结果**:
+6. **展示结果**:
 
 ```
 ✅ 会议成员已更新: 技术方案评审
@@ -133,4 +133,4 @@ wecom-meeting-manage 提供企业微信会议管理能力, 包含以下功能:
 - **参与人仅支持企业内成员**, 不支持外部人员
 - **通讯录查询**: 涉及参与人时, 需先通过 `wecom-contact-lookup` 技能的 `get_userlist` 接口获取全量通讯录成员, 再按姓名/别名本地筛选匹配出对应的 `userid`. 该接口无入参, 返回当前用户可见范围内的成员列表 (含 `userid`, `name`, `alias`)
 - **定位会议**: 管理操作需先通过 `wecom-meeting-query` 技能查询到目标会议的 meetingid
-- **成员更新为全量覆盖**: `set_invite_members` 传入的列表将替换现有成员列表, 需先获取当前成员再合并
+- **成员更新为全量覆盖**: `set_invite_meeting_members` 传入的列表将替换现有成员列表, 需先获取当前成员再合并

package/skills/wecom-schedule/SKILL.md

@@ -64,9 +64,9 @@ metadata:
 - 添加参与人：使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule add_schedule_attendees '{"schedule_id": "SCHEDULE_ID", "attendees": [{"userid": "USER_ID"}]}'`
 - 移除参与人：使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule del_schedule_attendees '{"schedule_id": "SCHEDULE_ID", "attendees": [{"userid": "USER_ID"}]}'`
 
-### check_availablity — 查询闲忙
+### check_availability — 查询闲忙
 
-使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule check_availablity '{"check_user_list": ["USER_ID_1", "USER_ID_2"], "start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule check_availability '{"check_user_list": ["USER_ID_1", "USER_ID_2"], "start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
 
 支持 1~10 个用户，返回各用户的忙碌时段列表。参见 [API 详情](references/api-check-availability.md)。
 
@@ -156,6 +156,6 @@ metadata:
 
 **流程：**
 1. 通过 **wecom-contact-lookup** 获取相关人员 userid
-2. 调用 `check_availablity` 查询指定时间范围内各用户的忙碌时段
+2. 调用 `check_availability` 查询指定时间范围内各用户的忙碌时段
 3. 分析所有用户的忙碌时段，计算出共同空闲时段并推荐给用户
 4. 用户确认时段后，调用 `create_schedule` 创建会议并自动添加参与人

package/skills/wecom-schedule/references/api-check-availability.md

@@ -1,4 +1,4 @@
-# check_availablity API
+# check_availability API
 
 查询指定用户在某时间范围内的忙碌时段。
 
@@ -12,7 +12,7 @@
 
 ## 请求示例
 
-使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule check_availablity '{"check_user_list": ["USER_ID_1", "USER_ID_2"], "start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule check_availability '{"check_user_list": ["USER_ID_1", "USER_ID_2"], "start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
 
 ## 返回字段
 

package/skills/wecom-smartsheet-data/SKILL.md

@@ -32,7 +32,7 @@ description: 企业微信智能表格数据（记录）管理技能。提供智
 
 查询子表全部记录。
 
-- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'`
+- 通过 sheetid：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'`
 - 或通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'`
 
 参见 [API 详情](references/api-get-records.md)。
@@ -49,7 +49,10 @@ description: 企业微信智能表格数据（记录）管理技能。提供智
 
 ### smartsheet_update_records
 
-更新一行或多行记录，单次必须在 500 行内。需提供 record_id（通过 `smartsheet_get_records` 获取）。
+更新一行或多行记录，单次建议在 500 行内。需提供 record_id（通过 `smartsheet_get_records` 获取）。支持通过 `key_type` 指定 values 的 key 使用字段标题或字段 ID：
+
+- `CELL_VALUE_KEY_TYPE_FIELD_TITLE`：key 为字段标题
+- `CELL_VALUE_KEY_TYPE_FIELD_ID`：key 为字段 ID
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_ID", "records": [{"record_id": "RECORDID", "values": {"FIELDID": [{"type": "text", "text": "更新后的内容"}]}}]}'`
 

package/skills/wecom-smartsheet-data/references/api-get-records.md

@@ -59,3 +59,4 @@
     "sheet_id": "123Abc"
 }
 ```
+

package/skills/wecom-smartsheet-data/references/cell-value-formats.md

@@ -1,6 +1,7 @@
 # 单元格值格式参考
 
-在 `smartsheet_add_records` 和 `smartsheet_update_records` 中，`values` 的 key **必须是字段标题（field_title）**，不能使用字段 ID。
+`smartsheet_add_records` 仅支持**字段标题**作为key。
+`smartsheet_update_records` 支持通过 `key_type` 参数指定使用字段标题（`CELL_VALUE_KEY_TYPE_FIELD_TITLE`）或字段 ID（`CELL_VALUE_KEY_TYPE_FIELD_ID`）。
 
 ## 各字段类型的值格式
 
@@ -36,10 +37,40 @@
 
 ```json
 "优先级": [{"text": "高"}],
-"标签": [{"text": "紧急"}, {"text": "重要"}]
+"标签": [{"text": "紧急", "style": 17}, {"text": "重要", "style": 12}]
 ```
 
-选项可附带 `id`（已存在选项）和 `style`（颜色 1-27）。
+已存在的选项应通过 `id` 匹配（`id` 可从 `smartsheet_get_fields` 返回中获取），新增选项时不填 `id`。可附带 `style`（颜色 1-27），对照表如下：
+
+| style | 颜色 |
+|-------|------|
+| 1 | 浅红1 |
+| 2 | 浅橙1 |
+| 3 | 浅天蓝1 |
+| 4 | 浅绿1 |
+| 5 | 浅紫1 |
+| 6 | 浅粉红1 |
+| 7 | 浅灰1 |
+| 8 | 白 |
+| 9 | 灰 |
+| 10 | 浅蓝1 |
+| 11 | 浅蓝2 |
+| 12 | 蓝 |
+| 13 | 浅天蓝2 |
+| 14 | 天蓝 |
+| 15 | 浅绿2 |
+| 16 | 绿 |
+| 17 | 浅红2 |
+| 18 | 红 |
+| 19 | 浅橙2 |
+| 20 | 橙 |
+| 21 | 浅黄1 |
+| 22 | 浅黄2 |
+| 23 | 黄 |
+| 24 | 浅紫2 |
+| 25 | 紫 |
+| 26 | 浅粉红2 |
+| 27 | 粉红 |
 
 ### 5. 日期时间 (DATE_TIME)
 
@@ -118,3 +149,4 @@
     }]
 }
 ```
+

package/dist/src/routing.d.ts

@@ -1,24 +0,0 @@
-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

@@ -1,34 +0,0 @@
-/**
- * 检测配置中启用的模式
- */
-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);
-}