@yanhaidao/wecom 2.3.2 → 2.3.3

package/README.md

@@ -1,5 +1,8 @@
 # OpenClaw 企业微信（WeCom）Channel 插件
 
+> [!WARNING]
+> **OpenClaw 3.1+ 升级必读**：升级到 OpenClaw `3.1` 及以上版本的用户务必同步升级本插件，并将企业微信回调 URL 更新为 OpenClaw 推荐路径：`/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`（旧 `/wecom/*` 仍兼容但不再维护）。
+
 <p align="center">
   <img src="https://img.shields.io/badge/Original%20Project-YanHaidao-orange?style=for-the-badge&logo=github" alt="Original Project" />
   <img src="https://img.shields.io/badge/License-ISC-blue?style=for-the-badge" alt="License" />
@@ -80,7 +83,6 @@
 ## 一、🚀 快速开始
 
 > 默认推荐：**多账号 + 多 Agent（matrix）**。  
-> 单账号 Bot/Agent 配置仍然支持，但建议仅用于兼容或小规模场景。
 > 建议 OpenClaw 使用 **2026.2.24+** 版本以获得完整生命周期与多账号行为修复。
 
 ### 1.1 安装插件
@@ -152,19 +154,12 @@ openclaw channels status
 ```
 
 Webhook 回调建议按账号分别配置：
-- Bot：`/wecom/bot/{accountId}`
-- Agent：`/wecom/agent/{accountId}`
+- Bot（推荐）：`/plugins/wecom/bot/{accountId}`
+- Agent（推荐）：`/plugins/wecom/agent/{accountId}`
 
 > 提示：如果你已有 `bindings`，请先备份并按需合并，避免覆盖其它通道绑定。
 
-### 1.3 兼容模式（单账号）
-
-为降低主线认知负担，README 默认仅展示多账号配置。  
-如果你在维护历史部署或只需单账号，请查看兼容文档：
-
-- [单账号兼容模式配置指南](./compat-single-account.md)
-
-### 1.4 高级网络配置（公网出口代理）
+### 1.3 高级网络配置（公网出口代理）
 如果您的服务器使用 **动态 IP** (如家庭宽带、内网穿透) 或 **无公网 IP**，企业微信 API 会因 IP 变动报错 `60020 not allow to access from your ip`。
 此时需配置一个**固定 IP 的正向代理** (如 Squid)，让插件通过该代理访问企微 API。
 
@@ -172,7 +167,7 @@ Webhook 回调建议按账号分别配置：
 openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"
 ```
 
-### 1.5 验证
+### 1.4 验证
 
 ```bash
 openclaw config set gateway.bind lan
@@ -286,38 +281,32 @@ openclaw channels status
 }
 ```
 
-### 2.2 兼容模式文档（单账号）
-
-- [单账号兼容模式配置指南](./compat-single-account.md)
-
-### 2.3 路由第一性原则
+### 2.2 路由第一性原则
 
 - `accountId` 是会话隔离边界：不同账号不共享会话、不共享动态 Agent。
 - Bot 无法交付时，只回退到**同组** Agent，不跨账号兜底。
 - 只有在未显式指定 `accountId` 时，才使用 `defaultAccount`。
 
-### 2.4 Webhook 路径（优先使用账号路径）
+### 2.3 Webhook 路径（必须使用账号路径）
 
 | 模式 | 路径 | 说明 |
 |:---|:---|:---|
-| Bot（推荐，多账号） | `/wecom/bot/{accountId}` | 指定账号回调（例如 `/wecom/bot/default`） |
-| Agent（推荐，多账号） | `/wecom/agent/{accountId}` | 指定账号回调（例如 `/wecom/agent/default`） |
-| Bot（兼容，单账号 legacy） | `/wecom/bot` 或 `/wecom` | 历史路径，仅单账号模式建议保留 |
-| Agent（兼容，单账号 legacy） | `/wecom/agent` | 历史路径，单账号模式可用 |
+| Bot（推荐，多账号） | `/plugins/wecom/bot/{accountId}` | 指定账号回调（例如 `/plugins/wecom/bot/default`） |
+| Agent（推荐，多账号） | `/plugins/wecom/agent/{accountId}` | 指定账号回调（例如 `/plugins/wecom/agent/default`） |
 
-### 2.5 从单账号迁移到多账号（4 步）
+### 2.4 从单账号迁移到多账号（4 步）
 
 1. 把原来的 `channels.wecom.bot` / `channels.wecom.agent` 拆到 `channels.wecom.accounts.default.bot/agent`。
 2. 按业务继续新增 `channels.wecom.accounts.<accountId>`（例如 `ops`、`sales`）。
 3. 为每个账号增加 `bindings[].match.accountId`，映射到对应 OpenClaw agent。
-4. 企业微信后台把回调 URL 改成账号路径：`/wecom/bot/{accountId}`、`/wecom/agent/{accountId}`，然后执行 `openclaw channels status` 验证。
+4. 企业微信后台把回调 URL 改成账号路径：`/plugins/wecom/bot/{accountId}`、`/plugins/wecom/agent/{accountId}`，然后执行 `openclaw channels status` 验证。
 
-### 2.6 DM 策略
+### 2.5 DM 策略
 
 - **不配置 `dm.allowFrom`** → 所有人可用（默认）
 - **配置 `dm.allowFrom: ["user1", "user2"]`** → 白名单模式，仅列表内用户可私聊
 
-### 2.7 常用指令
+### 2.6 常用指令
 
 | 指令 | 说明 | 示例 |
 |:---|:---|:---|
@@ -335,7 +324,7 @@ openclaw channels status
 1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/manageTools)
 2. 进入「安全与管理」→「管理工具」→「智能机器人」
 3. 创建机器人，选择 **API 模式**
-4. 填写回调 URL：`https://your-domain.com/wecom/bot/{accountId}`（例如默认账号：`https://your-domain.com/wecom/bot/default`）
+4. 填写回调 URL：`https://your-domain.com/plugins/wecom/bot/{accountId}`（例如默认账号：`https://your-domain.com/plugins/wecom/bot/default`）
 5. 记录 Token 和 EncodingAESKey
 
 ### 3.2 Agent 模式（自建应用）
@@ -346,7 +335,7 @@ openclaw channels status
 4. **重要：** 进入「企业可信IP」→「配置」→ 添加你服务器的 IP 地址
    - 如果你使用内网穿透/动态 IP，建议配置 `channels.wecom.network.egressProxyUrl` 走固定出口代理，否则可能出现：`60020 not allow to access from your ip`
 5. 在应用详情中设置「接收消息 - 设置API接收」
-6. 填写回调 URL：`https://your-domain.com/wecom/agent/{accountId}`（例如默认账号：`https://your-domain.com/wecom/agent/default`）
+6. 填写回调 URL：`https://your-domain.com/plugins/wecom/agent/{accountId}`（例如默认账号：`https://your-domain.com/plugins/wecom/agent/default`）
 7. 记录回调 Token 和 EncodingAESKey
 
 <div align="center">
@@ -511,6 +500,22 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 <a id="sec-10"></a>
 ## 八、📝 更新日志
 
+### 2026.3.3（今日更新简报）
+
+- 【兼容性修复】🧩 **OpenClaw 3.1 路由抢占问题修复**：推荐回调地址升级为 `/plugins/wecom/bot/{accountId}`、`/plugins/wecom/agent/{accountId}`，规避根路径 Control UI fallback 抢占 webhook。
+- 【引导收敛】🧭 **Onboarding 仅支持账号化配置**：配置向导统一写入 `channels.wecom.accounts.<accountId>`，不再引导单账号旧结构。
+- 【兼容策略】🔁 **旧路径兼容保留**：`/wecom/*` 历史回调路径保留兼容能力，但不再作为维护主路径。
+- 【分流稳定性】🧭 **路由识别增强**：monitor 按插件命名空间账号路径识别，确保 Bot/Agent 分支稳定命中。
+- 【链路一致性】🔒 **Bot 回复不再误走 Agent**：修复 Bot 上下文通道标识，避免 `routeReply` 误触发到 outbound 主动发送链路。
+- 【验证结果】✅ WeCom 插件测试通过：`10` files / `41` tests。
+
+### 2026.3.2（版本更新简报）
+
+- 【交付收口】🔄 修复 Bot 会话“正在搜索相关内容”不结束的问题，并在可用时推送最终流帧结束状态。  
+- 【媒体兜底】📎 统一非图片文件、媒体失败和超时场景为“Bot 提示 + Agent 私信兜底”闭环，确保结果可达。  
+- 【类型兼容】🧠 扩展 `txt/docx/xlsx/pptx/csv/zip` 等常见文件类型识别，并保留 `application/octet-stream` 自动重试。  
+- 【工具治理】🛡 修复 Bot 会话 `message` 工具禁用策略，避免绕过 Bot 交付链路导致会话错位。  
+
 ### 2026.2.28
 
 - 【重磅更新】🎯 **多账号/多智能体可用性增强**：支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效），动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。

package/changelog/v2.3.2.md

@@ -1,70 +1,28 @@
-# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.3.2 - Bot/Agent 交付收口与文件发送兼容性增强
-
-本次 v2.3.2 版本聚焦修复企业微信 Bot 模式在复杂交付场景下的稳定性问题，重点解决：
-- Bot 已收到文件但界面仍停留在“正在搜索相关内容”不结束。
-- 本地文件下发时，`txt`、`docx` 以及更多文件类型发送不稳定的问题。
-
----
-
-### 🌟 版本亮点 (Release Highlights)
-
-* ✅ **修复“正在搜索相关内容”不收口**：Agent 链路执行完成后，Bot 会主动推送最终流帧，确保企微思考态正确结束。
-* 🔒 **修复消息工具绕过链路问题**：在 WeCom Bot 会话中正确禁用顶层 `message` 工具，避免模型绕开 Bot 流式交付导致链路错位。
-* 📁 **本地路径下发能力增强**：支持识别 `/root`、`/home` 等 Linux 常见路径，减少文件请求误分流。
-* 📄 **文件类型兼容大幅提升**：补齐 `txt`、`docx`、`xlsx`、`pptx`、`csv`、`zip` 等常见类型 MIME，并增强入站媒体类型推断准确率。
-* 🛟 **未知类型自动兜底**：上传失败时自动回退到 `application/octet-stream` 重试，提高“能发出去”的成功率。
-
----
-
-### 📝 详细更新日志 (Changelog)
-
-#### 【交付稳定性】🔄 Bot/Agent 链路收口修复
-- 增加统一“最终流帧”主动推送逻辑，确保 `response_url` 可用时会主动收口。
-- 当回复内容为空时增加最终可见兜底文案，避免企微前端悬空态。
-- 非图片文件、媒体处理失败、超时切换等场景统一走“Bot 提示 + Agent 私信兜底”闭环。
-
-#### 【链路一致性】🧭 工具策略修复
-- 在 WeCom Bot 会话中将 `message` 工具写入 `tools.deny`（并同步 sandbox deny），修复错误禁用位置造成的链路绕过。
-- 避免“文件已发出但 Bot 思考流未结束”的链路错位。
-
-#### 【文件兼容性】📎 MIME 与上传兜底增强
-- 扩展本地文件 MIME 推断覆盖：`txt/csv/tsv/md/json/xml/yaml/yml/pdf/doc/docx/xls/xlsx/ppt/pptx/zip/rar/7z/tar/gz/tgz/rtf/odt`。
-- 上传 multipart 时增加文件名规范化，降低特殊文件名导致的兼容性问题。
-- 新增“首选 MIME 失败 -> octet-stream 自动重试”机制，提升未知/边缘类型上传成功率。
-
-#### 【类型识别优化】🧠 入站文件名与后缀判定更准确
-- 下载并解密媒体时保留源信息（`content-type`、`content-disposition`、最终 URL），用于后续精确判断。
-- 新增三层文件类型判定策略（按优先级）：
-  - 二进制内容特征（Magic Number / 文件头）
-  - 非泛型响应头 `content-type`
-  - 文件名后缀映射
-- 文件名确定策略（按优先级）：
-  - 回调体显式文件名字段
-  - 下载响应 `content-disposition` 文件名
-  - URL 路径 basename（仅在看起来是有效文件名时采用）
-  - 兜底默认名（自动补扩展名）
-- 对 OOXML（`docx/xlsx/pptx`）增加 ZIP 内容探测，降低仅靠 URL 无后缀时误判为 `zip/bin` 的概率。
-
-#### 【质量保障】✅ 回归测试补充
-- 新增上传链路单测，覆盖：
-  - `.txt` 使用 `text/plain`
-  - `.docx` 使用官方 MIME
-  - 首次 MIME 失败时自动回退重试
-- 同步通过 WeCom monitor/outbound 相关回归测试，确保无行为回退。
-
----
-
-### 💾 安装与升级 (Install & Update)
-
-使用 **OpenClaw** CLI 一键升级 **插件**：
-
-```bash
-openclaw plugins upgrade wecom
-```
-
-或手动更新版本至 `v2.3.2`。
-
----
-
-### 📮 联系我们
-如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 反馈日志与复现场景。
+# OpenClaw WeCom 插件 v2.3.2 变更简报
+
+> [!WARNING]
+> **OpenClaw 3.1+ 升级必读**：升级到 OpenClaw `3.1` 及以上版本的用户务必同步升级本插件，并将企业微信回调 URL 更新为 OpenClaw 推荐路径：`/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`（旧 `/wecom/*` 仍兼容但不再维护）。
+
+## 2026-03-03（今日）
+- 【路由兼容】🧩 修复 OpenClaw 3.1 下 Control UI fallback 可能抢占 `/wecom/*` webhook 的路由冲突问题。  
+- 【引导收敛】🧭 将 WeCom onboarding 统一为账号化配置写入 `channels.wecom.accounts.<accountId>`，不再引导单账号旧结构。  
+- 【回调路径】🔁 将 WeCom 回调路径的推荐方案统一为 `/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`。  
+- 【兼容策略】🔁 保留 `/wecom/*` 历史回调路径兼容能力，但不再维护旧路径分支。  
+- 【分流稳定】🧭 将 monitor 分流升级为按插件命名空间账号路径识别，确保 Bot/Agent 稳定命中。  
+- 【链路一致】🔒 将 Bot 上下文 `Surface` 对齐为 `wecom`，避免核心误判后错误走到 Agent outbound。  
+- 【账号必填】🧱 在 matrix 模式下对无 accountId 的基础路径返回 `wecom_matrix_path_required`，强制使用账号化回调路径。  
+- 【文档同步】📘 将回调地址文档与 onboarding 提示统一为 `/plugins/wecom/*/{accountId}` 唯一推荐路径。  
+
+## 2026-03-02（v2.3.2 主体）
+- 【交付收口】🔄 修复 Bot 结果回写后“正在搜索相关内容”不收口的问题，并在可用时推送最终流帧结束思考态。  
+- 【媒体兜底】📎 统一非图片文件、媒体失败和超时场景为“Bot 提示 + Agent 私信兜底”闭环，保证结果可达。  
+- 【工具治理】🛡 修复 WeCom Bot 会话中 `message` 工具禁用位置，避免模型绕过 Bot 交付链路直接主动发送。  
+- 【类型兼容】🧠 扩展本地与远端文件 MIME 识别覆盖 `txt/docx/xlsx/pptx/csv/zip` 等常见类型，并保留 `octet-stream` 重试兜底。  
+- 【判定增强】🔍 将入站文件类型推断升级为“文件头特征 + 响应头 + 文件名后缀”多层判定，提升无后缀和异常 URL 的识别准确率。  
+
+## 验证结果
+- WeCom 插件测试通过 `10` 个测试文件共 `41` 条用例，覆盖 webhook 生命周期、路径分流、媒体兜底与回归场景。  
+
+## 升级提示
+- 推荐在企业微信后台使用 `https://<your-domain>/plugins/wecom/bot/{accountId}` 与 `https://<your-domain>/plugins/wecom/agent/{accountId}` 作为回调地址。  
+- 旧地址 `/wecom/bot/{accountId}` 与 `/wecom/agent/{accountId}` 仍兼容但不再维护，建议尽快迁移到 `/plugins/wecom/*/{accountId}`。  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "repository": {

package/src/channel.lifecycle.test.ts

@@ -178,26 +178,44 @@ describe("wecomPlugin gateway lifecycle", () => {
     const startPromise = wecomPlugin.gateway!.startAccount!(ctx);
     await Promise.resolve();
 
-    const active = await sendWecomGetVerify({
+    const activeLegacyRoute = await sendWecomGetVerify({
       path: "/wecom/bot",
       token,
       encodingAESKey,
       receiveId,
     });
-    expect(active.handled).toBe(true);
-    expect(active.status).toBe(200);
-    expect(active.body).toBe("ping");
+    expect(activeLegacyRoute.handled).toBe(true);
+    expect(activeLegacyRoute.status).toBe(200);
+    expect(activeLegacyRoute.body).toBe("ping");
+
+    const activePluginRoute = await sendWecomGetVerify({
+      path: "/plugins/wecom/bot",
+      token,
+      encodingAESKey,
+      receiveId,
+    });
+    expect(activePluginRoute.handled).toBe(true);
+    expect(activePluginRoute.status).toBe(200);
+    expect(activePluginRoute.body).toBe("ping");
 
     abortController.abort();
     await startPromise;
 
-    const inactive = await sendWecomGetVerify({
+    const inactiveLegacyRoute = await sendWecomGetVerify({
       path: "/wecom/bot",
       token,
       encodingAESKey,
       receiveId,
     });
-    expect(inactive.handled).toBe(false);
+    expect(inactiveLegacyRoute.handled).toBe(false);
+
+    const inactivePluginRoute = await sendWecomGetVerify({
+      path: "/plugins/wecom/bot",
+      token,
+      encodingAESKey,
+      receiveId,
+    });
+    expect(inactivePluginRoute.handled).toBe(false);
   });
 
   it("rejects startup when matrix account credentials conflict", async () => {

package/src/channel.ts

@@ -19,6 +19,7 @@ import type { ResolvedWecomAccount } from "./types/index.js";
 import { monitorWecomProvider } from "./gateway-monitor.js";
 import { wecomOnboardingAdapter } from "./onboarding.js";
 import { wecomOutbound } from "./outbound.js";
+import { WEBHOOK_PATHS } from "./types/constants.js";
 
 const meta = {
   id: "wecom",
@@ -108,10 +109,10 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         enabled: account.enabled,
         configured: account.configured && !conflict,
         webhookPath: account.bot?.config
-          ? (matrixMode ? `/wecom/bot/${account.accountId}` : "/wecom/bot")
+          ? (matrixMode ? `${WEBHOOK_PATHS.BOT_PLUGIN}/${account.accountId}` : WEBHOOK_PATHS.BOT_PLUGIN)
           : account.agent?.config
-            ? (matrixMode ? `/wecom/agent/${account.accountId}` : "/wecom/agent")
-            : "/wecom",
+            ? (matrixMode ? `${WEBHOOK_PATHS.AGENT_PLUGIN}/${account.accountId}` : WEBHOOK_PATHS.AGENT_PLUGIN)
+            : WEBHOOK_PATHS.BOT_PLUGIN,
       };
     },
     resolveAllowFrom: ({ cfg, accountId }) => {
@@ -176,10 +177,14 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         enabled: account.enabled,
         configured: account.configured && !conflict,
         webhookPath: account.bot?.config
-          ? (account.accountId === DEFAULT_ACCOUNT_ID ? "/wecom/bot" : `/wecom/bot/${account.accountId}`)
+          ? (account.accountId === DEFAULT_ACCOUNT_ID
+              ? WEBHOOK_PATHS.BOT_PLUGIN
+              : `${WEBHOOK_PATHS.BOT_PLUGIN}/${account.accountId}`)
           : account.agent?.config
-            ? (account.accountId === DEFAULT_ACCOUNT_ID ? "/wecom/agent" : `/wecom/agent/${account.accountId}`)
-            : "/wecom",
+            ? (account.accountId === DEFAULT_ACCOUNT_ID
+                ? WEBHOOK_PATHS.AGENT_PLUGIN
+                : `${WEBHOOK_PATHS.AGENT_PLUGIN}/${account.accountId}`)
+            : WEBHOOK_PATHS.BOT_PLUGIN,
         running: runtime?.running ?? false,
         lastStartAt: runtime?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? null,

package/src/gateway-monitor.ts

@@ -12,10 +12,11 @@ import {
 } from "./config/index.js";
 import { registerAgentWebhookTarget, registerWecomWebhookTarget } from "./monitor.js";
 import type { ResolvedWecomAccount, WecomConfig } from "./types/index.js";
+import { WEBHOOK_PATHS } from "./types/constants.js";
 
 type AccountRouteRegistryItem = {
   botPaths: string[];
-  agentPath?: string;
+  agentPaths: string[];
 };
 
 const accountRouteRegistry = new Map<string, AccountRouteRegistryItem>();
@@ -41,7 +42,7 @@ function logRegisteredRouteSummary(
       const routes = accountRouteRegistry.get(accountId);
       if (!routes) return undefined;
       const botText = routes.botPaths.length > 0 ? routes.botPaths.join(", ") : "未启用";
-      const agentText = routes.agentPath ?? "未启用";
+      const agentText = routes.agentPaths.length > 0 ? routes.agentPaths.join(", ") : "未启用";
       return `accountId=${accountId}（Bot: ${botText}；Agent: ${agentText}）`;
     })
     .filter((entry): entry is string => Boolean(entry));
@@ -74,6 +75,30 @@ function waitForAbortSignal(abortSignal: AbortSignal): Promise<void> {
   });
 }
 
+function uniquePaths(paths: string[]): string[] {
+  return Array.from(new Set(paths.map((path) => path.trim()).filter(Boolean)));
+}
+
+function resolveBotRegistrationPaths(params: { accountId: string; matrixMode: boolean }): string[] {
+  if (params.matrixMode) {
+    return uniquePaths([
+      `${WEBHOOK_PATHS.BOT_PLUGIN}/${params.accountId}`,
+      `${WEBHOOK_PATHS.BOT_ALT}/${params.accountId}`,
+    ]);
+  }
+  return uniquePaths([WEBHOOK_PATHS.BOT_PLUGIN, WEBHOOK_PATHS.BOT, WEBHOOK_PATHS.BOT_ALT]);
+}
+
+function resolveAgentRegistrationPaths(params: { accountId: string; matrixMode: boolean }): string[] {
+  if (params.matrixMode) {
+    return uniquePaths([
+      `${WEBHOOK_PATHS.AGENT_PLUGIN}/${params.accountId}`,
+      `${WEBHOOK_PATHS.AGENT}/${params.accountId}`,
+    ]);
+  }
+  return uniquePaths([WEBHOOK_PATHS.AGENT_PLUGIN, WEBHOOK_PATHS.AGENT]);
+}
+
 /**
  * Keeps WeCom webhook targets registered for the account lifecycle.
  * The promise only settles after gateway abort/reload signals shutdown.
@@ -129,12 +154,13 @@ export async function monitorWecomProvider(
 
   const unregisters: Array<() => void> = [];
   const botPaths: string[] = [];
-  let agentPath: string | undefined;
+  const agentPaths: string[] = [];
   try {
     if (bot && botConfigured) {
-      const paths = matrixMode
-        ? [`/wecom/bot/${account.accountId}`]
-        : ["/wecom", "/wecom/bot"];
+      const paths = resolveBotRegistrationPaths({
+        accountId: account.accountId,
+        matrixMode,
+      });
       for (const path of paths) {
         unregisters.push(
           registerWecomWebhookTarget({
@@ -154,20 +180,25 @@ export async function monitorWecomProvider(
     }
 
     if (agent && agentConfigured) {
-      const path = matrixMode ? `/wecom/agent/${account.accountId}` : "/wecom/agent";
-      unregisters.push(
-        registerAgentWebhookTarget({
-          agent,
-          config: cfg,
-          runtime: ctx.runtime,
-          path,
-        }),
-      );
-      agentPath = path;
-      ctx.log?.info(`[${account.accountId}] wecom agent webhook registered at ${path}`);
+      const paths = resolveAgentRegistrationPaths({
+        accountId: account.accountId,
+        matrixMode,
+      });
+      for (const path of paths) {
+        unregisters.push(
+          registerAgentWebhookTarget({
+            agent,
+            config: cfg,
+            runtime: ctx.runtime,
+            path,
+          }),
+        );
+      }
+      agentPaths.push(...paths);
+      ctx.log?.info(`[${account.accountId}] wecom agent webhook registered at ${paths.join(", ")}`);
     }
 
-    accountRouteRegistry.set(account.accountId, { botPaths, agentPath });
+    accountRouteRegistry.set(account.accountId, { botPaths, agentPaths });
     const shouldLogSummary =
       expectedRouteSummaryAccountIds.length <= 1 ||
       expectedRouteSummaryAccountIds.every((accountId) => accountRouteRegistry.has(accountId));
@@ -180,8 +211,8 @@ export async function monitorWecomProvider(
       running: true,
       configured: true,
       webhookPath: botConfigured
-        ? (matrixMode ? `/wecom/bot/${account.accountId}` : "/wecom/bot")
-        : (matrixMode ? `/wecom/agent/${account.accountId}` : "/wecom/agent"),
+        ? (botPaths[0] ?? WEBHOOK_PATHS.BOT_PLUGIN)
+        : (agentPaths[0] ?? WEBHOOK_PATHS.AGENT_PLUGIN),
       lastStartAt: Date.now(),
     });
 

package/src/monitor.active.test.ts

@@ -28,7 +28,7 @@ function createMockRequest(bodyObj: any): IncomingMessage {
     const socket = new Socket();
     const req = new IncomingMessage(socket);
     req.method = "POST";
-    req.url = "/wecom?timestamp=123&nonce=456&signature=789";
+    req.url = "/plugins/wecom/bot/default?timestamp=123&nonce=456&signature=789";
     req.push(JSON.stringify(bodyObj));
     req.push(null);
     return req;
@@ -140,7 +140,7 @@ describe("Monitor Active Features", () => {
             } as any,
             runtime: { log: () => { } },
             core: mockCore,
-            path: "/wecom"
+            path: "/plugins/wecom/bot/default"
         });
     });
 

package/src/monitor.integration.test.ts

@@ -21,7 +21,7 @@ function createMockRequest(bodyObj: any, query: URLSearchParams): IncomingMessag
     const socket = new Socket();
     const req = new IncomingMessage(socket);
     req.method = "POST";
-    req.url = `/wecom?${query.toString()}`;
+    req.url = `/plugins/wecom/bot/default?${query.toString()}`;
     req.push(JSON.stringify(bodyObj));
     req.push(null);
     return req;
@@ -108,7 +108,7 @@ describe("Monitor Integration: Inbound Image", () => {
             config: {} as any,
             runtime: { log: console.log, error: console.error },
             core: mockCore as any,
-            path: "/wecom"
+            path: "/plugins/wecom/bot/default"
         });
     });
 
@@ -198,6 +198,8 @@ describe("Monitor Integration: Inbound Image", () => {
         // Expect Context Injection
         expect(ctx.MediaPath).toBe("/tmp/saved-image.jpg");
         expect(ctx.MediaType).toBe("image/jpeg");
+        expect(ctx.Surface).toBe("wecom");
+        expect(ctx.OriginatingChannel).toBe("wecom");
 
         expect(undiciFetch).toHaveBeenCalledWith(
             imageUrl,

package/src/monitor.ts

@@ -220,16 +220,24 @@ type RouteFailureReason =
   | "wecom_identity_mismatch"
   | "wecom_matrix_path_required";
 
-function isLegacyWecomPath(path: string): boolean {
-  return path === WEBHOOK_PATHS.BOT || path === WEBHOOK_PATHS.BOT_ALT || path === WEBHOOK_PATHS.AGENT;
+function isNonMatrixWecomBasePath(path: string): boolean {
+  return (
+    path === WEBHOOK_PATHS.BOT ||
+    path === WEBHOOK_PATHS.BOT_ALT ||
+    path === WEBHOOK_PATHS.AGENT ||
+    path === WEBHOOK_PATHS.BOT_PLUGIN ||
+    path === WEBHOOK_PATHS.AGENT_PLUGIN
+  );
 }
 
 function hasMatrixExplicitRoutesRegistered(): boolean {
   for (const key of webhookTargets.keys()) {
     if (key.startsWith(`${WEBHOOK_PATHS.BOT_ALT}/`)) return true;
+    if (key.startsWith(`${WEBHOOK_PATHS.BOT_PLUGIN}/`)) return true;
   }
   for (const key of agentTargets.keys()) {
     if (key.startsWith(`${WEBHOOK_PATHS.AGENT}/`)) return true;
+    if (key.startsWith(`${WEBHOOK_PATHS.AGENT_PLUGIN}/`)) return true;
   }
   return false;
 }
@@ -1549,7 +1557,11 @@ async function startAgentForStream(params: {
     SenderName: userid,
     SenderId: userid,
     Provider: "wecom",
-    Surface: "webchat",
+    // Keep Surface aligned with OriginatingChannel for Bot-mode delivery.
+    // If Surface is "webchat", core dispatch treats this as cross-channel
+    // and routes replies via routeReply -> wecom outbound (Agent API),
+    // bypassing the Bot stream deliver path.
+    Surface: "wecom",
     MessageSid: msg.msgid,
     CommandAuthorized: commandAuthorized,
     OriginatingChannel: "wecom",
@@ -2110,7 +2122,7 @@ export function registerAgentWebhookTarget(target: AgentWebhookTarget): () => vo
  * 
  * 处理来自企业微信的所有 Webhook 请求。
  * 职责：
- * 1. 路由分发：按 Matrix/Legacy 路径分流 Bot 与 Agent 回调。
+ * 1. 路由分发：优先按 `/plugins/wecom/{bot|agent}/{accountId}` 分流，并兼容历史 `/wecom/*` 路径。
  * 2. 安全校验：验证企业微信签名 (Signature)。
  * 3. 消息解密：处理企业微信的加密包。
  * 4. 响应处理：
@@ -2134,7 +2146,7 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
     `[wecom] inbound(http): reqId=${reqId} path=${path} method=${req.method ?? "UNKNOWN"} remote=${remote} ua=${ua ? `"${ua}"` : "N/A"} contentLength=${cl || "N/A"} query={timestamp:${hasTimestamp},nonce:${hasNonce},echostr:${hasEchostr},msg_signature:${hasMsgSig},signature:${hasSignature}}`,
   );
 
-  if (hasMatrixExplicitRoutesRegistered() && isLegacyWecomPath(path)) {
+  if (hasMatrixExplicitRoutesRegistered() && isNonMatrixWecomBasePath(path)) {
     logRouteFailure({
       reqId,
       path,
@@ -2145,14 +2157,19 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
     writeRouteFailure(
       res,
       "wecom_matrix_path_required",
-      "Matrix mode requires explicit account path. Use /wecom/bot/{accountId} or /wecom/agent/{accountId}.",
+      "Matrix mode requires explicit account path. Use /plugins/wecom/bot/{accountId} or /plugins/wecom/agent/{accountId}.",
     );
     return true;
   }
 
-  const isAgentPath = path === WEBHOOK_PATHS.AGENT || path.startsWith(`${WEBHOOK_PATHS.AGENT}/`);
-  if (isAgentPath) {
-    const targets = agentTargets.get(path) ?? [];
+  const isAgentPathCandidate =
+    path === WEBHOOK_PATHS.AGENT ||
+    path === WEBHOOK_PATHS.AGENT_PLUGIN ||
+    path.startsWith(`${WEBHOOK_PATHS.AGENT}/`) ||
+    path.startsWith(`${WEBHOOK_PATHS.AGENT_PLUGIN}/`);
+  const matchedAgentTargets = agentTargets.get(path) ?? [];
+  if (matchedAgentTargets.length > 0 || isAgentPathCandidate) {
+    const targets = matchedAgentTargets;
     if (targets.length > 0) {
       const query = resolveQueryParams(req);
       const timestamp = query.get("timestamp") ?? "";
@@ -2328,7 +2345,7 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
     return true;
   }
 
-  // Bot 模式路由: /wecom, /wecom/bot
+  // Bot 模式路由: /plugins/wecom/bot（推荐）以及 /wecom、/wecom/bot（兼容）
   const targets = webhookTargets.get(path);
   if (!targets || targets.length === 0) return false;
 

package/src/monitor.webhook.test.ts

@@ -369,7 +369,7 @@ describe("handleWecomWebhookRequest", () => {
     }
   });
 
-  it("routes matrix bot callback by explicit account path", async () => {
+  it("routes bot callback by explicit plugin account path", async () => {
     const token = "MATRIX-TOKEN";
     const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG";
 
@@ -390,7 +390,7 @@ describe("handleWecomWebhookRequest", () => {
       config: { channels: { wecom: { accounts: {} } } } as OpenClawConfig,
       runtime: {},
       core: {} as any,
-      path: "/wecom/bot/acct-a",
+      path: "/plugins/wecom/bot/acct-a",
     });
     const unregisterB = registerWecomWebhookTarget({
       account: {
@@ -409,12 +409,12 @@ describe("handleWecomWebhookRequest", () => {
       config: { channels: { wecom: { accounts: {} } } } as OpenClawConfig,
       runtime: {},
       core: {} as any,
-      path: "/wecom/bot/acct-b",
+      path: "/plugins/wecom/bot/acct-b",
     });
 
     try {
       const timestamp = "1700000999";
-      const nonce = "nonce-matrix";
+      const nonce = "nonce-plugin-account";
       const plain = JSON.stringify({
         msgid: "MATRIX-MSG-1",
         aibotid: "BOT_B",
@@ -422,13 +422,94 @@ describe("handleWecomWebhookRequest", () => {
         from: { userid: "USERID_B" },
         response_url: "RESPONSEURL",
         msgtype: "text",
-        text: { content: "hello matrix" },
+        text: { content: "hello plugin account path" },
       });
       const encrypt = encryptWecomPlaintext({ encodingAESKey, receiveId: "", plaintext: plain });
       const msg_signature = computeWecomMsgSignature({ token, timestamp, nonce, encrypt });
       const req = createMockRequest({
         method: "POST",
-        url: `/wecom/bot/acct-b?msg_signature=${encodeURIComponent(msg_signature)}&timestamp=${encodeURIComponent(timestamp)}&nonce=${encodeURIComponent(nonce)}`,
+        url: `/plugins/wecom/bot/acct-b?msg_signature=${encodeURIComponent(msg_signature)}&timestamp=${encodeURIComponent(timestamp)}&nonce=${encodeURIComponent(nonce)}`,
+        body: { encrypt },
+      });
+      const res = createMockResponse();
+      const handled = await handleWecomWebhookRequest(req, res);
+      expect(handled).toBe(true);
+      expect(res._getStatusCode()).toBe(200);
+
+      const json = JSON.parse(res._getData()) as any;
+      const replyPlain = decryptWecomEncrypted({
+        encodingAESKey,
+        receiveId: "",
+        encrypt: json.encrypt,
+      });
+      const reply = JSON.parse(replyPlain) as any;
+      expect(reply.stream?.content).toBe("B处理中");
+    } finally {
+      unregisterA();
+      unregisterB();
+    }
+  });
+
+  it("routes bot callback by explicit plugin namespace path", async () => {
+    const token = "MATRIX-TOKEN-PLUGIN";
+    const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG";
+
+    const unregisterA = registerWecomWebhookTarget({
+      account: {
+        accountId: "acct-a",
+        enabled: true,
+        configured: true,
+        token,
+        encodingAESKey,
+        receiveId: "",
+        config: {
+          token,
+          encodingAESKey,
+          streamPlaceholderContent: "A处理中",
+        } as any,
+      } as any,
+      config: { channels: { wecom: { accounts: {} } } } as OpenClawConfig,
+      runtime: {},
+      core: {} as any,
+      path: "/plugins/wecom/bot/acct-a",
+    });
+    const unregisterB = registerWecomWebhookTarget({
+      account: {
+        accountId: "acct-b",
+        enabled: true,
+        configured: true,
+        token,
+        encodingAESKey,
+        receiveId: "",
+        config: {
+          token,
+          encodingAESKey,
+          streamPlaceholderContent: "B处理中",
+        } as any,
+      } as any,
+      config: { channels: { wecom: { accounts: {} } } } as OpenClawConfig,
+      runtime: {},
+      core: {} as any,
+      path: "/plugins/wecom/bot/acct-b",
+    });
+
+    try {
+      const timestamp = "1700001000";
+      const nonce = "nonce-matrix-plugin";
+      const plain = JSON.stringify({
+        msgid: "MATRIX-MSG-PLUGIN-1",
+        aibotid: "BOT_B",
+        chattype: "single",
+        from: { userid: "USERID_B_PLUGIN" },
+        response_url: "RESPONSEURL",
+        msgtype: "text",
+        text: { content: "hello matrix plugin path" },
+      });
+      const encrypt = encryptWecomPlaintext({ encodingAESKey, receiveId: "", plaintext: plain });
+      const msg_signature = computeWecomMsgSignature({ token, timestamp, nonce, encrypt });
+      const req = createMockRequest({
+        method: "POST",
+        url: `/plugins/wecom/bot/acct-b?msg_signature=${encodeURIComponent(msg_signature)}&timestamp=${encodeURIComponent(timestamp)}&nonce=${encodeURIComponent(nonce)}`,
         body: { encrypt },
       });
       const res = createMockResponse();
@@ -501,7 +582,7 @@ describe("handleWecomWebhookRequest", () => {
     }
   });
 
-  it("rejects legacy bot path when matrix explicit routes are registered", async () => {
+  it("rejects legacy paths and accountless plugin paths", async () => {
     const token = "MATRIX-TOKEN-3";
     const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG";
     const unregister = registerWecomWebhookTarget({
@@ -517,7 +598,7 @@ describe("handleWecomWebhookRequest", () => {
       config: { channels: { wecom: { accounts: { "acct-a": { bot: {} } } } } } as OpenClawConfig,
       runtime: {},
       core: {} as any,
-      path: "/wecom/bot/acct-a",
+      path: "/plugins/wecom/bot/acct-a",
     });
     try {
       const req = createMockRequest({
@@ -531,6 +612,18 @@ describe("handleWecomWebhookRequest", () => {
       expect(JSON.parse(res._getData())).toMatchObject({
         error: "wecom_matrix_path_required",
       });
+
+      const pluginReq = createMockRequest({
+        method: "GET",
+        url: "/plugins/wecom/bot?timestamp=t&nonce=n&msg_signature=s&echostr=e",
+      });
+      const pluginRes = createMockResponse();
+      const pluginHandled = await handleWecomWebhookRequest(pluginReq, pluginRes);
+      expect(pluginHandled).toBe(true);
+      expect(pluginRes._getStatusCode()).toBe(401);
+      expect(JSON.parse(pluginRes._getData())).toMatchObject({
+        error: "wecom_matrix_path_required",
+      });
     } finally {
       unregister();
     }
@@ -557,7 +650,7 @@ describe("handleWecomWebhookRequest", () => {
       },
       config: { channels: { wecom: { accounts: {} } } } as OpenClawConfig,
       runtime: {},
-      path: "/wecom/agent",
+      path: "/plugins/wecom/agent/default",
     } as any);
     const unregisterB = registerAgentWebhookTarget({
       agent: {
@@ -573,13 +666,13 @@ describe("handleWecomWebhookRequest", () => {
       },
       config: { channels: { wecom: { accounts: {} } } } as OpenClawConfig,
       runtime: {},
-      path: "/wecom/agent",
+      path: "/plugins/wecom/agent/default",
     } as any);
 
     try {
       const req = createMockRequest({
         method: "GET",
-        url: `/wecom/agent?msg_signature=${encodeURIComponent(signature)}&timestamp=${encodeURIComponent(timestamp)}&nonce=${encodeURIComponent(nonce)}&echostr=${encodeURIComponent(echostr)}`,
+        url: `/plugins/wecom/agent/default?msg_signature=${encodeURIComponent(signature)}&timestamp=${encodeURIComponent(timestamp)}&nonce=${encodeURIComponent(nonce)}&echostr=${encodeURIComponent(echostr)}`,
       });
       const res = createMockResponse();
       const handled = await handleWecomWebhookRequest(req, res);

package/src/onboarding.ts

@@ -9,8 +9,9 @@ import type {
     OpenClawConfig,
     WizardPrompter,
 } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
-import type { WecomConfig, WecomBotConfig, WecomAgentConfig, WecomDmConfig } from "./types/index.js";
+import { DEFAULT_ACCOUNT_ID, promptAccountId } from "openclaw/plugin-sdk";
+import { listWecomAccountIds, resolveDefaultWecomAccountId, resolveWecomAccount, resolveWecomAccounts } from "./config/index.js";
+import type { WecomConfig, WecomBotConfig, WecomAgentConfig, WecomDmConfig, WecomAccountConfig } from "./types/index.js";
 
 const channel = "wecom" as const;
 
@@ -37,29 +38,118 @@ function setWecomEnabled(cfg: OpenClawConfig, enabled: boolean): OpenClawConfig
     } as OpenClawConfig;
 }
 
-function setWecomBotConfig(cfg: OpenClawConfig, bot: WecomBotConfig): OpenClawConfig {
+function shouldUseAccountScopedConfig(wecom: WecomConfig | undefined, accountId: string): boolean {
+    void wecom;
+    void accountId;
+    return true;
+}
+
+function ensureMatrixAccounts(wecom: WecomConfig): WecomConfig {
+    const accounts = wecom.accounts ?? {};
+    if (Object.keys(accounts).length > 0) {
+        return wecom;
+    }
+
+    if (!wecom.bot && !wecom.agent) {
+        return wecom;
+    }
+
+    const { bot: legacyBot, agent: legacyAgent, ...rest } = wecom;
+    const defaultAccount: WecomAccountConfig = {
+        enabled: true,
+        ...(legacyBot ? { bot: legacyBot } : {}),
+        ...(legacyAgent ? { agent: legacyAgent } : {}),
+    };
+
+    return {
+        ...rest,
+        defaultAccount: rest.defaultAccount?.trim() || DEFAULT_ACCOUNT_ID,
+        accounts: {
+            [DEFAULT_ACCOUNT_ID]: defaultAccount,
+        },
+    };
+}
+
+function accountWebhookPath(kind: "bot" | "agent", accountId: string): string {
+    const recommendedBase = kind === "bot" ? "/plugins/wecom/bot" : "/plugins/wecom/agent";
+    return `${recommendedBase}/${accountId}`;
+}
+
+function setWecomBotConfig(cfg: OpenClawConfig, bot: WecomBotConfig, accountId: string): OpenClawConfig {
+    const wecom = getWecomConfig(cfg) ?? {};
+    if (!shouldUseAccountScopedConfig(wecom, accountId)) {
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                wecom: {
+                    ...wecom,
+                    enabled: true,
+                    bot,
+                },
+            },
+        } as OpenClawConfig;
+    }
+
+    const matrixWecom = ensureMatrixAccounts(wecom);
+    const accounts = matrixWecom.accounts ?? {};
+    const existingAccount = accounts[accountId] ?? {};
     return {
         ...cfg,
         channels: {
             ...cfg.channels,
             wecom: {
-                ...(cfg.channels?.wecom ?? {}),
+                ...matrixWecom,
                 enabled: true,
-                bot,
+                defaultAccount: matrixWecom.defaultAccount?.trim() || DEFAULT_ACCOUNT_ID,
+                accounts: {
+                    ...accounts,
+                    [accountId]: {
+                        ...existingAccount,
+                        enabled: existingAccount.enabled ?? true,
+                        bot,
+                    },
+                },
             },
         },
     } as OpenClawConfig;
 }
 
-function setWecomAgentConfig(cfg: OpenClawConfig, agent: WecomAgentConfig): OpenClawConfig {
+function setWecomAgentConfig(cfg: OpenClawConfig, agent: WecomAgentConfig, accountId: string): OpenClawConfig {
+    const wecom = getWecomConfig(cfg) ?? {};
+    if (!shouldUseAccountScopedConfig(wecom, accountId)) {
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                wecom: {
+                    ...wecom,
+                    enabled: true,
+                    agent,
+                },
+            },
+        } as OpenClawConfig;
+    }
+
+    const matrixWecom = ensureMatrixAccounts(wecom);
+    const accounts = matrixWecom.accounts ?? {};
+    const existingAccount = accounts[accountId] ?? {};
     return {
         ...cfg,
         channels: {
             ...cfg.channels,
             wecom: {
-                ...(cfg.channels?.wecom ?? {}),
+                ...matrixWecom,
                 enabled: true,
-                agent,
+                defaultAccount: matrixWecom.defaultAccount?.trim() || DEFAULT_ACCOUNT_ID,
+                accounts: {
+                    ...accounts,
+                    [accountId]: {
+                        ...existingAccount,
+                        enabled: existingAccount.enabled ?? true,
+                        agent,
+                    },
+                },
             },
         },
     } as OpenClawConfig;
@@ -69,8 +159,49 @@ function setWecomDmPolicy(
     cfg: OpenClawConfig,
     mode: "bot" | "agent",
     dm: WecomDmConfig,
+    accountId: string,
 ): OpenClawConfig {
     const wecom = getWecomConfig(cfg) ?? {};
+    if (shouldUseAccountScopedConfig(wecom, accountId)) {
+        const matrixWecom = ensureMatrixAccounts(wecom);
+        const accounts = matrixWecom.accounts ?? {};
+        const existingAccount = accounts[accountId] ?? {};
+        const nextAccount: WecomAccountConfig =
+            mode === "bot"
+                ? {
+                    ...existingAccount,
+                    bot: {
+                        ...existingAccount.bot,
+                        dm,
+                    },
+                }
+                : {
+                    ...existingAccount,
+                    agent: {
+                        ...existingAccount.agent,
+                        dm,
+                    },
+                };
+        return {
+            ...cfg,
+            channels: {
+                ...cfg.channels,
+                wecom: {
+                    ...matrixWecom,
+                    enabled: true,
+                    defaultAccount: matrixWecom.defaultAccount?.trim() || DEFAULT_ACCOUNT_ID,
+                    accounts: {
+                        ...accounts,
+                        [accountId]: {
+                            ...nextAccount,
+                            enabled: nextAccount.enabled ?? true,
+                        },
+                    },
+                },
+            },
+        } as OpenClawConfig;
+    }
+
     if (mode === "bot") {
         return {
             ...cfg,
@@ -101,6 +232,28 @@ function setWecomDmPolicy(
     } as OpenClawConfig;
 }
 
+async function resolveOnboardingAccountId(params: {
+    cfg: OpenClawConfig;
+    prompter: WizardPrompter;
+    accountOverride?: string;
+    shouldPromptAccountIds: boolean;
+}): Promise<string> {
+    const defaultAccountId = resolveDefaultWecomAccountId(params.cfg);
+    const override = params.accountOverride?.trim();
+    let accountId = override || defaultAccountId;
+    if (!override && params.shouldPromptAccountIds) {
+        accountId = await promptAccountId({
+            cfg: params.cfg,
+            prompter: params.prompter,
+            label: "WeCom",
+            currentId: accountId,
+            listAccountIds: (cfg) => listWecomAccountIds(cfg),
+            defaultAccountId,
+        });
+    }
+    return accountId.trim() || DEFAULT_ACCOUNT_ID;
+}
+
 // ============================================================
 // 欢迎与引导
 // ============================================================
@@ -155,13 +308,15 @@ async function promptMode(prompter: WizardPrompter): Promise<WecomMode> {
 async function configureBotMode(
     cfg: OpenClawConfig,
     prompter: WizardPrompter,
+    accountId: string,
 ): Promise<OpenClawConfig> {
+    const recommendedPath = accountWebhookPath("bot", accountId);
     await prompter.note(
         [
             "正在配置 Bot 模式...",
             "",
             "💡 操作指南: 请在企微后台【管理工具 -> 智能机器人】开启 API 模式。",
-            "🔗 回调 URL: https://您的域名/wecom/bot",
+            `🔗 回调 URL (推荐): https://您的域名${recommendedPath}`,
             "",
             "请先在后台填入回调 URL，然后获取以下信息。",
         ].join("\n"),
@@ -206,7 +361,7 @@ async function configureBotMode(
         welcomeText: welcomeText?.trim() || undefined,
     };
 
-    return setWecomBotConfig(cfg, botConfig);
+    return setWecomBotConfig(cfg, botConfig, accountId);
 }
 
 // ============================================================
@@ -216,7 +371,9 @@ async function configureBotMode(
 async function configureAgentMode(
     cfg: OpenClawConfig,
     prompter: WizardPrompter,
+    accountId: string,
 ): Promise<OpenClawConfig> {
+    const recommendedPath = accountWebhookPath("agent", accountId);
     await prompter.note(
         [
             "正在配置 Agent 模式...",
@@ -256,7 +413,7 @@ async function configureAgentMode(
     await prompter.note(
         [
             "💡 操作指南: 请在自建应用详情页进入【接收消息 -> 设置API接收】。",
-            "🔗 回调 URL: https://您的域名/wecom/agent",
+            `🔗 回调 URL (推荐): https://您的域名${recommendedPath}`,
             "",
             "请先在后台填入回调 URL，然后获取以下信息。",
         ].join("\n"),
@@ -297,7 +454,7 @@ async function configureAgentMode(
         welcomeText: welcomeText?.trim() || undefined,
     };
 
-    return setWecomAgentConfig(cfg, agentConfig);
+    return setWecomAgentConfig(cfg, agentConfig, accountId);
 }
 
 // ============================================================
@@ -308,6 +465,7 @@ async function promptDmPolicy(
     cfg: OpenClawConfig,
     prompter: WizardPrompter,
     modes: ("bot" | "agent")[],
+    accountId: string,
 ): Promise<OpenClawConfig> {
     const policyChoice = await prompter.select({
         message: "请选择私聊 (DM) 访问策略:",
@@ -338,7 +496,7 @@ async function promptDmPolicy(
 
     let result = cfg;
     for (const mode of modes) {
-        result = setWecomDmPolicy(result, mode, dm);
+        result = setWecomDmPolicy(result, mode, dm, accountId);
     }
     return result;
 }
@@ -347,20 +505,22 @@ async function promptDmPolicy(
 // 配置汇总
 // ============================================================
 
-async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter): Promise<void> {
-    const wecom = getWecomConfig(cfg);
+async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter, accountId: string): Promise<void> {
+    const account = resolveWecomAccount({ cfg, accountId });
     const lines: string[] = ["✅ 配置已保存！", ""];
 
-    if (wecom?.bot?.token) {
+    if (account.bot?.configured) {
         lines.push("📱 Bot 模式: 已配置");
-        lines.push(`   回调 URL: https://您的域名/wecom/bot`);
+        lines.push(`   回调 URL: https://您的域名${accountWebhookPath("bot", accountId)}`);
     }
 
-    if (wecom?.agent?.corpId) {
+    if (account.agent?.configured) {
         lines.push("🏢 Agent 模式: 已配置");
-        lines.push(`   回调 URL: https://您的域名/wecom/agent`);
+        lines.push(`   回调 URL: https://您的域名${accountWebhookPath("agent", accountId)}`);
     }
 
+    lines.push(`   账号 ID: ${accountId}`);
+
     lines.push("");
     lines.push("⚠️ 请确保您已在企微后台填写了正确的回调 URL，");
     lines.push("   并点击了后台的『保存』按钮完成验证。");
@@ -378,11 +538,12 @@ const dmPolicy: ChannelOnboardingDmPolicy = {
     policyKey: "channels.wecom.bot.dm.policy",
     allowFromKey: "channels.wecom.bot.dm.allowFrom",
     getCurrent: (cfg: OpenClawConfig) => {
-        const wecom = getWecomConfig(cfg);
-        return (wecom?.bot?.dm?.policy ?? "pairing") as "pairing";
+        const account = resolveWecomAccount({ cfg });
+        return (account.bot?.config.dm?.policy ?? "pairing") as "pairing";
     },
     setPolicy: (cfg: OpenClawConfig, policy: "pairing" | "allowlist" | "open" | "disabled") => {
-        return setWecomDmPolicy(cfg, "bot", { policy });
+        const accountId = resolveDefaultWecomAccountId(cfg);
+        return setWecomDmPolicy(cfg, "bot", { policy }, accountId);
     },
     promptAllowFrom: async ({ cfg, prompter }: { cfg: OpenClawConfig; prompter: WizardPrompter }) => {
         const allowFromStr = String(
@@ -392,7 +553,8 @@ const dmPolicy: ChannelOnboardingDmPolicy = {
             }),
         ).trim();
         const allowFrom = allowFromStr.split(",").map((s) => s.trim()).filter(Boolean);
-        return setWecomDmPolicy(cfg, "bot", { policy: "allowlist", allowFrom });
+        const accountId = resolveDefaultWecomAccountId(cfg);
+        return setWecomDmPolicy(cfg, "bot", { policy: "allowlist", allowFrom }, accountId);
     },
 };
 
@@ -404,60 +566,74 @@ export const wecomOnboardingAdapter: ChannelOnboardingAdapter = {
     channel,
     dmPolicy,
     getStatus: async ({ cfg }: { cfg: OpenClawConfig }) => {
-        const wecom = getWecomConfig(cfg);
-        const botConfigured = Boolean(wecom?.bot?.token && wecom?.bot?.encodingAESKey);
-        const agentConfigured = Boolean(
-            wecom?.agent?.corpId && wecom?.agent?.corpSecret && wecom?.agent?.agentId,
-        );
-        const configured = botConfigured || agentConfigured;
+        const resolved = resolveWecomAccounts(cfg);
+        const accounts = Object.values(resolved.accounts).filter((account) => account.enabled !== false);
+        const botConfigured = accounts.some((account) => Boolean(account.bot?.configured));
+        const agentConfigured = accounts.some((account) => Boolean(account.agent?.configured));
+        const configured = accounts.some((account) => account.configured);
 
         const statusParts: string[] = [];
         if (botConfigured) statusParts.push("Bot ✓");
         if (agentConfigured) statusParts.push("Agent ✓");
+        const accountSuffix = accounts.length > 1 ? ` · ${accounts.length} accounts` : "";
+        const statusSummary = statusParts.length > 0 ? statusParts.join(" + ") : "已配置";
 
         return {
             channel,
             configured,
             statusLines: [
-                `WeCom: ${configured ? statusParts.join(" + ") : "需要配置"}`,
+                `WeCom: ${configured ? `${statusSummary}${accountSuffix}` : "需要配置"}`,
             ],
             selectionHint: configured
-                ? `configured · ${statusParts.join(" + ")}`
+                ? `configured · ${statusSummary}${accountSuffix}`
                 : "enterprise-ready · dual-mode",
             quickstartScore: configured ? 1 : 8,
         };
     },
-    configure: async ({ cfg, prompter }: { cfg: OpenClawConfig; prompter: WizardPrompter }) => {
+    configure: async ({
+        cfg,
+        prompter,
+        accountOverrides,
+        shouldPromptAccountIds,
+    }) => {
         // 1. 欢迎
         await showWelcome(prompter);
 
-        // 2. 模式选择
+        // 2. 账号选择
+        const accountId = await resolveOnboardingAccountId({
+            cfg,
+            prompter,
+            accountOverride: accountOverrides.wecom,
+            shouldPromptAccountIds,
+        });
+
+        // 3. 模式选择
         const mode = await promptMode(prompter);
 
         let next = cfg;
         const configuredModes: ("bot" | "agent")[] = [];
 
-        // 3. 配置 Bot
+        // 4. 配置 Bot
         if (mode === "bot" || mode === "both") {
-            next = await configureBotMode(next, prompter);
+            next = await configureBotMode(next, prompter, accountId);
             configuredModes.push("bot");
         }
 
-        // 4. 配置 Agent
+        // 5. 配置 Agent
         if (mode === "agent" || mode === "both") {
-            next = await configureAgentMode(next, prompter);
+            next = await configureAgentMode(next, prompter, accountId);
             configuredModes.push("agent");
         }
 
-        // 5. DM 策略
-        next = await promptDmPolicy(next, prompter, configuredModes);
+        // 6. DM 策略
+        next = await promptDmPolicy(next, prompter, configuredModes, accountId);
 
-        // 6. 启用通道
+        // 7. 启用通道
         next = setWecomEnabled(next, true);
 
-        // 7. 汇总
-        await showSummary(next, prompter);
+        // 8. 汇总
+        await showSummary(next, prompter, accountId);
 
-        return { cfg: next, accountId: DEFAULT_ACCOUNT_ID };
+        return { cfg: next, accountId };
     },
 };

package/src/types/constants.ts

@@ -4,12 +4,16 @@
 
 /** 固定 Webhook 路径 */
 export const WEBHOOK_PATHS = {
-    /** Bot 模式 (智能体) - 兼容原有路径 */
+    /** Bot 模式历史兼容路径（不再维护） */
     BOT: "/wecom",
-    /** Bot 模式备用路径 */
+    /** Bot 模式历史备用兼容路径（不再维护） */
     BOT_ALT: "/wecom/bot",
-    /** Agent 模式 (自建应用) */
+    /** Agent 模式历史兼容路径（不再维护） */
     AGENT: "/wecom/agent",
+    /** Bot 模式（唯一支持路径前缀） */
+    BOT_PLUGIN: "/plugins/wecom/bot",
+    /** Agent 模式（唯一支持路径前缀） */
+    AGENT_PLUGIN: "/plugins/wecom/agent",
 } as const;
 
 /** 企业微信 API 端点 */