@yanhaidao/wecom 2.2.28 → 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` | 智能体回调 |
-| Agent | `/wecom/agent` | 自建应用回调 |
-| Bot（多账号） | `/wecom/bot/{accountId}` | 指定账号回调 |
-| Agent（多账号） | `/wecom/agent/{accountId}` | 指定账号回调 |
+| 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`
+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`
+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

@@ -0,0 +1,28 @@
+# 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.2.28",
+  "version": "2.3.3",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "repository": {

package/src/agent/api-client.ts

@@ -25,6 +25,43 @@ type TokenCache = {
 
 const tokenCaches = new Map<string, TokenCache>();
 
+function normalizeUploadFilename(filename: string): string {
+    const trimmed = filename.trim();
+    if (!trimmed) return "file.bin";
+    const ext = trimmed.includes(".") ? `.${trimmed.split(".").pop()!.toLowerCase()}` : "";
+    const base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+    const sanitizedBase = base
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\\/;=]/g, "_")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const safeBase = sanitizedBase || "file";
+    const safeExt = ext.replace(/[^a-z0-9.]/g, "");
+    return `${safeBase}${safeExt || ".bin"}`;
+}
+
+function guessUploadContentType(filename: string): string {
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const contentTypeMap: Record<string, string> = {
+        // image
+        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp", bmp: "image/bmp",
+        // audio / video
+        amr: "voice/amr", mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", ogg: "audio/ogg", mp4: "video/mp4", mov: "video/quicktime",
+        // documents
+        txt: "text/plain", md: "text/markdown", csv: "text/csv", tsv: "text/tab-separated-values", json: "application/json",
+        xml: "application/xml", yaml: "application/yaml", yml: "application/yaml",
+        pdf: "application/pdf", doc: "application/msword", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ppt: "application/vnd.ms-powerpoint", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        rtf: "application/rtf", odt: "application/vnd.oasis.opendocument.text",
+        // archives
+        zip: "application/zip", rar: "application/vnd.rar", "7z": "application/x-7z-compressed",
+        gz: "application/gzip", tgz: "application/gzip", tar: "application/x-tar",
+    };
+    return contentTypeMap[ext] || "application/octet-stream";
+}
+
 function requireAgentId(agent: ResolvedAgentAccount): number {
     if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId)) return agent.agentId;
     throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
@@ -163,48 +200,53 @@ export async function uploadMedia(params: {
     filename: string;
 }): Promise<string> {
     const { agent, type, buffer, filename } = params;
+    const safeFilename = normalizeUploadFilename(filename);
     const token = await getAccessToken(agent);
+    const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
     // 添加 debug=1 参数获取更多错误信息
     const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
 
     // DEBUG: 输出上传信息
-    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${filename}, size=${buffer.length} bytes`);
-
-    // 手动构造 multipart/form-data 请求体
-    // 企业微信要求包含 filename 和 filelength
-    const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
-
-    // 根据文件类型设置 Content-Type
-    const contentTypeMap: Record<string, string> = {
-        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
-        bmp: "image/bmp", amr: "voice/amr", mp4: "video/mp4",
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${safeFilename}, size=${buffer.length} bytes`);
+
+    const uploadOnce = async (fileContentType: string) => {
+        // 手动构造 multipart/form-data 请求体
+        // 企业微信要求包含 filename 和 filelength
+        const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+
+        const header = Buffer.from(
+            `--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="media"; filename="${safeFilename}"; filelength=${buffer.length}\r\n` +
+            `Content-Type: ${fileContentType}\r\n\r\n`
+        );
+        const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+        const body = Buffer.concat([header, buffer, footer]);
+
+        console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+
+        const res = await wecomFetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": String(body.length),
+            },
+            body: body,
+        }, { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+        const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+        console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+        return json;
     };
-    const ext = filename.split(".").pop()?.toLowerCase() || "";
-    const fileContentType = contentTypeMap[ext] || "application/octet-stream";
-
-    // 构造 multipart body
-    const header = Buffer.from(
-        `--${boundary}\r\n` +
-        `Content-Disposition: form-data; name="media"; filename="${filename}"; filelength=${buffer.length}\r\n` +
-        `Content-Type: ${fileContentType}\r\n\r\n`
-    );
-    const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
-    const body = Buffer.concat([header, buffer, footer]);
-
-    console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
 
-    const res = await wecomFetch(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": `multipart/form-data; boundary=${boundary}`,
-            "Content-Length": String(body.length),
-        },
-        body: body,
-    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
-    const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+    const preferredContentType = guessUploadContentType(safeFilename);
+    let json = await uploadOnce(preferredContentType);
 
-    // DEBUG: 输出完整响应
-    console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+    // 某些文件类型在严格网关/企业微信校验下可能失败，回退到通用类型再试一次。
+    if (!json?.media_id && preferredContentType !== "application/octet-stream") {
+        console.warn(
+            `[wecom-upload] Upload failed with ${preferredContentType}, retrying as application/octet-stream: ${json?.errcode} ${json?.errmsg}`,
+        );
+        json = await uploadOnce("application/octet-stream");
+    }
 
     if (!json?.media_id) {
         throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);

package/src/agent/api-client.upload.test.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedAgentAccount } from "../types/index.js";
+
+const { wecomFetchMock, resolveProxyMock } = vi.hoisted(() => ({
+  wecomFetchMock: vi.fn(),
+  resolveProxyMock: vi.fn(() => undefined),
+}));
+
+vi.mock("../http.js", () => ({
+  wecomFetch: wecomFetchMock,
+  readResponseBodyAsBuffer: vi.fn(),
+}));
+
+vi.mock("../config/index.js", () => ({
+  resolveWecomEgressProxyUrlFromNetwork: resolveProxyMock,
+}));
+
+import { uploadMedia } from "./api-client.js";
+
+function createAgent(agentId: number): ResolvedAgentAccount {
+  return {
+    accountId: `acct-${agentId}`,
+    enabled: true,
+    configured: true,
+    corpId: "corp",
+    corpSecret: "secret",
+    agentId,
+    token: "token",
+    encodingAESKey: "aes",
+    config: {} as any,
+  };
+}
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("wecom agent uploadMedia", () => {
+  beforeEach(() => {
+    wecomFetchMock.mockReset();
+    resolveProxyMock.mockReset();
+    resolveProxyMock.mockReturnValue(undefined);
+  });
+
+  it("uses text/plain for .txt uploads", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-1", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-1" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10001),
+      type: "file",
+      buffer: Buffer.from("hello txt"),
+      filename: "note.txt",
+    });
+
+    expect(mediaId).toBe("m-1");
+    const [, init] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const body = init.body as Buffer;
+    const bodyText = body.toString("utf8");
+    expect(bodyText).toContain('filename="note.txt"');
+    expect(bodyText).toContain("Content-Type: text/plain");
+  });
+
+  it("uses docx mime and normalizes non-ascii filename", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-2", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-2" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10002),
+      type: "file",
+      buffer: Buffer.from("docx bytes"),
+      filename: "需求文档.docx",
+    });
+
+    expect(mediaId).toBe("m-2");
+    const [, init] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const body = init.body as Buffer;
+    const bodyText = body.toString("utf8");
+    expect(bodyText).toContain('filename="file.docx"');
+    expect(bodyText).toContain(
+      "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    );
+  });
+
+  it("retries with octet-stream when preferred mime upload fails", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-3", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 40005, errmsg: "invalid media type" }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-3" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10003),
+      type: "file",
+      buffer: Buffer.from("yaml bytes"),
+      filename: "config.yaml",
+    });
+
+    expect(mediaId).toBe("m-3");
+    expect(wecomFetchMock).toHaveBeenCalledTimes(3);
+
+    const [, firstUploadInit] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const [, retryUploadInit] = wecomFetchMock.mock.calls[2] as [string, RequestInit];
+    const firstUploadBody = (firstUploadInit.body as Buffer).toString("utf8");
+    const retryUploadBody = (retryUploadInit.body as Buffer).toString("utf8");
+    expect(firstUploadBody).toContain("Content-Type: application/yaml");
+    expect(retryUploadBody).toContain("Content-Type: application/octet-stream");
+  });
+});

package/src/agent/handler.ts

@@ -526,7 +526,7 @@ async function processAgentMessage(params: {
         SenderName: fromUser,
         SenderId: fromUser,
         Provider: "wecom",
-        Surface: "wecom",
+        Surface: "webchat",
         OriginatingChannel: "wecom",
         // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
         // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
@@ -562,9 +562,9 @@ async function processAgentMessage(params: {
                     await sendText({ agent, toUser: fromUser, chatId: undefined, text });
                     log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser}`);
                 } catch (err: unknown) {
-                    error?.(`[wecom-agent] reply failed: ${String(err)}`);
-                }
-            },
+                    const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
+                    error?.(`[wecom-agent] reply failed: ${message}`);
+                }            },
             onError: (err: unknown, info: { kind: string }) => {
                 error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
             },

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/config/network.ts

@@ -3,11 +3,15 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import type { WecomConfig, WecomNetworkConfig } from "../types/index.js";
 
 export function resolveWecomEgressProxyUrlFromNetwork(network?: WecomNetworkConfig): string | undefined {
-  const env = (process.env.OPENCLAW_WECOM_EGRESS_PROXY_URL ?? process.env.WECOM_EGRESS_PROXY_URL ?? "").trim();
-  if (env) return env;
-
-  const fromCfg = network?.egressProxyUrl?.trim() ?? "";
-  return fromCfg || undefined;
+  const proxyUrl = network?.egressProxyUrl ??
+    process.env.OPENCLAW_WECOM_EGRESS_PROXY_URL ??
+    process.env.WECOM_EGRESS_PROXY_URL ??
+    process.env.HTTPS_PROXY ??
+    process.env.ALL_PROXY ??
+    process.env.HTTP_PROXY ??
+    "";
+    
+  return proxyUrl.trim() || undefined;
 }
 
 export function resolveWecomEgressProxyUrl(cfg: OpenClawConfig): string | undefined {