@wecom/wecom-openclaw-plugin 2026.3.31-beta.3 → 2026.3.31-beta.5

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,27 @@
 
 ## ✨ 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, file, and **mixed (图文混排)** messages with automatic downloading
+- 🗣️ Voice-to-text: automatically extracts transcribed text from voice messages
+- 💬 Quote message support: processes quoted text, image, voice, and file messages
 - ⏳ 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) with **event callback handling**
 - 🔒 Built-in access control: DM Policy (pairing / open / allowlist / disabled) and Group Policy (open / allowlist / disabled)
+- 🔑 Command authorization: per-account command permission control with access group support
 - 👥 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`) with interceptor pipeline (biz-error, media, smartpage-create, smartpage-export)
+- 🎯 **15 built-in Skills**: contact lookup, doc management, todo, meeting, schedule, messaging, smartsheet, template cards, and more
+- 🔀 Dynamic Agent routing: auto-create isolated agents per user/group
+- 📁 Local file sending with configurable media path allowlist (`mediaLocalRoots`)
+- 📊 Smart media size limits with auto-downgrade (image 10MB → file, video 10MB → file, voice 2MB/AMR-only → file, max 20MB)
+- 🔄 **Bot-first, Agent-fallback** outbound delivery: auto fallback to Agent HTTP API when Bot WS is unavailable
+- ⚡ Auto heartbeat keep-alive and reconnection (up to 10 reconnect attempts, 5 auth failure retries)
+- 🛡️ Anti-kick protection: suppresses auto-restart on server-side disconnection to prevent mutual kicking loops
 - 🧙 Interactive CLI setup wizard
 
 ---
@@ -46,7 +57,7 @@
 
 ### Requirements
 
-- OpenClaw `>= 2026.2.13`
+- OpenClaw `>= 2026.3.28`
 
 ### Quick Install
 
@@ -97,22 +108,81 @@ 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 | `20971520` (20MB) |
+| `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 | — |
+
+**Media Size Limits & Auto-Downgrade:**
+
+| Media Type | Max Size | Downgrade Behavior |
+|---|---|---|
+| Image | 10 MB | Exceeds → sent as file |
+| Video | 10 MB | Exceeds → sent as file |
+| Voice | 2 MB (AMR only) | Non-AMR format or exceeds → sent as file |
+| File | 20 MB | Exceeds → rejected (cannot send) |
+
+#### 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
 
@@ -121,13 +191,16 @@ Agent mode uses HTTP webhook callbacks with XML encrypted messages. You need to
 #### Prerequisites
 
 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)
-   - **Token**: auto-generated or custom
-   - **EncodingAESKey**: auto-generated or custom
-3. Note down the **CorpID**, **CorpSecret**, **Token**, and **EncodingAESKey**
+2. Note down the **CorpID**, **CorpSecret** (from app settings), and **AgentId**
+3. In the app settings, go to "API Receive" (API接收):
+   - Note down the **Token** and **EncodingAESKey** (auto-generated or custom)
+   - **Do NOT click save yet** — WeCom will verify the callback URL immediately when you save
 
-#### Quick Setup
+#### Setup Steps
+
+> **Important**: You must configure the Gateway **before** saving the callback URL in WeCom admin console. WeCom sends a verification request (GET with `echostr`) immediately when you save, and the Gateway needs the `token` and `encodingAESKey` to decrypt and respond correctly.
+
+**Step 1: Configure Gateway**
 
 ```shell
 openclaw config set channels.wecom.agent.corpId <YOUR_CORP_ID>
@@ -139,6 +212,13 @@ openclaw config set channels.wecom.enabled true
 openclaw gateway restart
 ```
 
+**Step 2: Save callback URL in WeCom admin console**
+
+Go back to the "API Receive" settings and enter the callback URL:
+- **URL**: `https://<your-gateway-host>/plugins/wecom/agent/<accountId>` (e.g. `/plugins/wecom/agent/default`); single-account mode can also use `/plugins/wecom/agent`
+
+Now click save — the verification should pass.
+
 #### JSON Configuration
 
 ```json
@@ -167,14 +247,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)
 
@@ -186,6 +281,7 @@ The plugin uses a **Bot-first, Agent-fallback** strategy for outbound message de
 This means:
 - **Agent-only accounts** (no Bot configured) can still send proactive messages, cron deliveries, and broadcasts
 - **Target formats** like `party:1`, `tag:Ops`, `user:zhangsan` are fully supported in both paths
+- **Media fallback**: when Bot WS is unavailable, media files are downloaded, uploaded to WeCom via Agent API, then sent; if upload fails, falls back to text + URL
 - No manual switching needed — the plugin handles fallback transparently
 
 ### Using Both Modes Together
@@ -213,19 +309,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 +331,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 +347,41 @@ Use `accounts` to configure multiple WeCom accounts, each with optional bot and/
 }
 ```
 
+> **Note**: In multi-account mode, 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) | `[]` |
+
 ---
 
 ## 🔒 Access Control
@@ -353,17 +486,19 @@ The plugin supports scheduled message delivery via OpenClaw's built-in Cron serv
 The `delivery.to` field supports the following target formats:
 
 | Format | Target | Example |
-|--------|--------|---------|
+|--------|--------|--------|
 | `party:<id>` | Department (all members) | `party:1` (root dept = all employees) |
-| `dept:<id>` | Department (alias) | `dept:5` |
+| `dept:<id>` | Department (alias for party) | `dept:5` |
 | `tag:<id>` | Tag group | `tag:Ops` |
 | `user:<id>` | Specific user | `user:zhangsan` |
 | `group:<id>` | External group chat | `group:wr123abc` |
-| `chat:<id>` | Group chat (alias) | `chat:wc456def` |
+| `chat:<id>` | Group chat (alias for group) | `chat:wc456def` |
 | Pure number | Auto-detected as department | `1` → `party:1` |
 | `wr...` / `wc...` | Auto-detected as group chat | `wr123` → `chatid` |
 | Other string | Auto-detected as user | `zhangsan` → `touser` |
 
+> **Namespace prefixes** (`wecom:`, `qywx:`, `wework:`, `wechatwork:`, `wecom-agent:`) are automatically stripped before parsing.
+
 ### Method 1: CLI (Recommended — takes effect immediately)
 
 ```shell
@@ -371,20 +506,26 @@ openclaw cron add \
   --name "daily-report" \
   --agent main \
   --cron "0 9 * * 1-5" \
+  --tz "Asia/Shanghai" \
   --message "Good morning! Here is your daily briefing." \
-  --deliver \
-  --delivery-channel wecom \
-  --delivery-to "party:1"
+  --announce \
+  --channel wecom \
+  --to "party:1"
 ```
 
+> **Note**: `--announce` enables delivery mode (broadcasts the AI response to the target chat). Use `--no-deliver` to keep output internal. The deprecated `--deliver` flag is an alias for `--announce`.
+
 Common CLI commands:
 
 ```shell
 openclaw cron list              # List all cron jobs
+openclaw cron show <id>         # Show job details
 openclaw cron enable <id>       # Enable a job
 openclaw cron disable <id>      # Disable a job
 openclaw cron remove <id>       # Remove a job
 openclaw cron run <id>          # Manually trigger a job
+openclaw cron runs --id <id>    # View run history
+openclaw cron edit <id> --message "New prompt"  # Edit a job
 ```
 
 ### Method 2: Edit `jobs.json` (requires gateway restart)
@@ -405,10 +546,7 @@ File path: `~/.openclaw/cron/jobs.json`
       "wakeMode": "now",
       "payload": {
         "kind": "agentTurn",
-        "message": "Generate today's briefing and send it.",
-        "deliver": true,
-        "channel": "wecom",
-        "to": "party:1"
+        "message": "Generate today's briefing and send it."
       },
       "delivery": {
         "mode": "announce",

package/dist/index.js

@@ -3,59 +3,8 @@ 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 的工具名列表
-// ============================================================================
-const REQUIRED_ALSO_ALLOW_TOOLS = ["wecom_mcp"];
-/**
- * 确保 tools.alsoAllow 中包含插件所需的工具名。
- *
- * 逻辑：
- *  1. 读取当前配置
- *  2. 检查 tools.alsoAllow 中是否已包含所需工具
- *  3. 如有缺失，合并写入配置文件
- *
- * 幂等操作——重复调用不会产生副作用。
- * 若 tools.allow 已显式设置（与 alsoAllow 互斥），则跳过注入并打印提示。
- */
-async function ensureToolsAlsoAllow(api) {
-    try {
-        const cfg = api.runtime.config.loadConfig();
-        const tools = cfg.tools ?? {};
-        // 如果用户显式配置了 tools.allow（全量白名单），则 alsoAllow 与之互斥，
-        // 此时不应自动追加 alsoAllow，避免产生校验冲突
-        if (tools.allow && tools.allow.length > 0) {
-            const missing = REQUIRED_ALSO_ALLOW_TOOLS.filter((t) => !tools.allow.includes(t));
-            if (missing.length > 0) {
-                console.warn(`[wecom] tools.allow 已显式设置，无法自动注入 alsoAllow。` +
-                    `请手动将 ${JSON.stringify(missing)} 加入 tools.allow。`);
-            }
-            return;
-        }
-        const existing = tools.alsoAllow ?? [];
-        const missing = REQUIRED_ALSO_ALLOW_TOOLS.filter((t) => !existing.includes(t));
-        if (missing.length === 0) {
-            // 所有工具已在白名单中，无需操作
-            return;
-        }
-        const merged = [...existing, ...missing];
-        const nextConfig = {
-            ...cfg,
-            tools: {
-                ...tools,
-                alsoAllow: merged,
-            },
-        };
-        await api.runtime.config.writeConfigFile(nextConfig);
-        console.log(`[wecom] 已自动将 ${JSON.stringify(missing)} 加入 tools.alsoAllow`);
-    }
-    catch (err) {
-        // 配置写入失败不应阻断 Gateway 启动
-        console.error(`[wecom] 自动注入 tools.alsoAllow 失败:`, err instanceof Error ? err.message : String(err));
-    }
-}
 const plugin = {
     id: "wecom-openclaw-plugin",
     name: "企业微信",
@@ -66,16 +15,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",
         });
@@ -90,11 +40,6 @@ const plugin = {
                 match: "prefix",
             });
         }
-        // ── Gateway 启动时自动确保 tools.alsoAllow 包含 wecom_mcp ──────────
-        // 在 gateway_start 阶段检测并写入，保证插件安装/更新后首次启动即生效
-        // api.on("gateway_start", async () => {
-        //   await ensureToolsAlsoAllow(api);
-        // });
         // 注入媒体发送指令和文件大小限制提示词（仅对企业微信 channel 生效）
         api.on("before_prompt_build", (_event, ctx) => {
             // 只在企业微信 channel 的会话中注入，避免影响其他 channel 插件

package/dist/src/agent/handler.js

@@ -9,7 +9,7 @@ import { extractMsgType, extractFromUser, extractContent, extractChatId, extract
 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";
+import { CHANNEL_ID, DEFAULT_MEDIA_MAX_MB } from "../const.js";
 function resolveWecomMediaMaxBytes(config) {
     return config.channels?.wecom?.media?.maxBytes ?? DEFAULT_MEDIA_MAX_MB * 1024 * 1024;
 }
@@ -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;
@@ -416,9 +404,9 @@ async function processAgentMessage(params) {
         ConversationLabel: fromLabel,
         SenderName: fromUser,
         SenderId: fromUser,
-        Provider: "wecom",
+        Provider: CHANNEL_ID,
         Surface: "webchat",
-        OriginatingChannel: "wecom",
+        OriginatingChannel: CHANNEL_ID,
         // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
         // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
         // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）

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,14 +416,29 @@ 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,
                     ]
-                    : [WEBHOOK_PATHS.AGENT_PLUGIN, WEBHOOK_PATHS.AGENT];
+                    : [
+                        // 单账号模式：同时注册 /default 路径以支持显式指定
+                        WEBHOOK_PATHS.AGENT_PLUGIN,
+                        WEBHOOK_PATHS.AGENT,
+                        `${WEBHOOK_PATHS.AGENT_PLUGIN}/${DEFAULT_ACCOUNT_ID}`,
+                        `${WEBHOOK_PATHS.AGENT}/${DEFAULT_ACCOUNT_ID}`,
+                    ];
                 for (const p of paths) {
                     registerAgentWebhookTarget({
                         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 处理结果