@yanhaidao/wecom 2.3.10 → 2.3.12

package/README.md

@@ -16,6 +16,7 @@
 <p align="center">
   <a href="#sec-1">💡 核心价值</a> •
   <a href="#sec-2">📊 模式对比</a> •
+  <a href="#sec-changelog">📋 最近更新</a> •
   <a href="#sec-3">一、快速开始</a> •
   <a href="#sec-4">二、配置说明</a> •
   <a href="#sec-5">三、企业微信接入</a> •
@@ -30,7 +31,7 @@
 ## 💡 核心价值：为什么选择本插件？
 
 ### 🎉 重大特性一览
-1. **防断连黑科技** (v2.3.10 新增)：针对 DeepSeek R1 等长时间 <think> 的推理模型，首创 **4秒前置保活 ACK** 机制。彻底断绝模型限速或慢思考导致的 WebSocket 5秒超时重试风暴与消息卡死现象。
+1. **防断连黑科技** (v2.3.11 升级)：针对 DeepSeek R1 等长时间 <think> 的推理模型，Bot WS 已升级为 **即时占位 + 持续保活 ACK** 机制。收到用户消息后立即展示 `streamPlaceholderContent`，并在首个真实回复块到来前持续保活，显著降低 WebSocket `invalid req_id` 与消息卡死现象。
 2. **无需域名，极低门槛**：全面支持基于 WebSocket 的长连接（Bot WS）模式接入企业微信机器人，**彻底打通无公网 IP、无备案域名的内网服务器**与企微的实时对话桥梁！
 3. **主动发消息，能力全覆盖**：基于 Agent 模式，全面支持**主动触达**，轻松实现早报定时任务、服务器异常报警、自动每日总结。
 4. **向导自动路由自动适配** (v2.3.10 新增)：在终端执行 `openclaw channels add` 时，若是单企微账号接入，将**静默触发自动 Agent 路由绑定**，丝滑跳过全局冗杂的路由分配步骤。
@@ -55,7 +56,7 @@
 本插件支持 **无限扩展的账号矩阵**，这是本插件区别于普通插件的核心壁垒：
 
 *   **千人千面 (Dynamic Agents)**：内置自动会话隔离机制，百人同时私聊或群聊自动分摊至专属独立助理，告别上下文串扰。
-*   **完全隔离 (Isolation)**：不同 `accountId` 之间的会话、动态 Agent、上下文完全物理隔离，互不串扰。
+*   **账号级隔离 (Isolation)**：不同 `accountId` 之间的收发链路、运行时实例与动态 Agent 默认隔离；若多个账号共用同一个静态 Agent，建议额外配合 `session.dmScope = "per-account-channel-peer"`，避免私聊上下文共用。
 *   **矩阵绑定 (Binding)**：支持一个 OpenClaw 实例同时挂载多个企业/多个应用，通过 `bindings` 灵活分发流量。
 *   **智能路由 (Routing)**：基于入站 `accountId` 自动分拣回复路径，Bot 无法回复时仅回退到**同账号组内**的 Agent，实现闭环的高可用。
 
@@ -95,6 +96,48 @@
 
 ---
 
+<a id="sec-changelog"></a>
+
+## 📋 最近更新
+
+> 项目保持高频迭代，核心改进一览：
+
+#### v2.3.12（2026-03-12）
+
+- 🛠 **[重要修复]** Bot WS 流式回复超 6 分钟后的 `846608 stream message update expired` 现在被识别为终态错误，不再导致进程退出。
+- 🛠 **[重要修复]** SDK 5 秒回执超时 (`Reply ack timeout`) 也被识别为终态错误，超时后立即停止占位保活，不再产生 `unhandledRejection`。
+- 🚀 Bot WS 模式下主动文本消息优先走 WS 长连接；Agent 仅兜底文件/媒体或未启用 WS 的场景。
+- 🧯 `sdk-adapter` 为 WebSocket frame 异步处理补上显式兜底捕获，漏网异常记录为 runtime issue 而非崩溃。
+- ⏱ 回复窗口过期时占位符保活立即停止。
+
+#### v2.3.11（2026-03-11）
+
+- `Bot WS` 升级为即时占位 + 持续保活，降低长思考时的 `invalid req_id`。
+- `streamPlaceholderContent` 统一作用于 `Bot WS` 与 `Bot Webhook`。
+- onboarding 在空配置下也会提供 `default` 账号选项。
+
+#### v2.3.10（2026-03-10）
+
+- onboarding 默认收敛为 `Bot + WS + 开放私聊`。
+- 修复 `Bot WS` 长文本双重回复问题。
+- Agent 新配置统一使用 `agentSecret`。
+
+<details>
+<summary>更早版本</summary>
+
+#### v2.3.9（2026-03-09）
+
+- Bot 默认接入改为 `WebSocket`，无需域名更易上手。
+- 完善中文 onboarding，减少重复提示。
+- 恢复 `Bot WS` 流式输出能力。
+- 增强 Agent 回调与发送日志，排障更直接。
+
+</details>
+
+详细版本记录见 `changelog/` 目录。
+
+---
+
 <a id="sec-3"></a>
 ## 一、🚀 快速开始
 
@@ -194,6 +237,8 @@ openclaw channels add
 说明：
 - 新配置推荐使用 `agent.agentSecret`
 - 历史配置里的 `agent.corpSecret` 仍兼容读取，但后续文档统一使用 `agentSecret`
+- `bot.streamPlaceholderContent` 会同时作用于 `Bot WS` 与 `Bot Webhook`；在 `Bot WS` 下，收到用户消息后会立即显示该占位符，并在长思考期间持续保活。
+- 如果你在一个 OpenClaw 实例里挂载多个 `accounts`，并让它们共同路由到同一个静态 Agent，建议在全局配置里加上 `session.dmScope = "per-account-channel-peer"`，让私聊 session key 显式带上 `accountId`。
 
 ### 1.3 高级网络配置（公网出口代理）
 如果您的服务器使用 **动态 IP** (如家庭宽带、内网穿透) 或 **无公网 IP**，首先使用Bot模式的ws接入方式。
@@ -227,6 +272,10 @@ openclaw channels status --deep
 最简的流式交互版（无兜底分发功能）。
 关键约束：`bot.primaryTransport = "ws"` 必须包含 `bot.ws` 参数。
 
+行为说明：
+- 收到用户消息后立即发送一次 `streamPlaceholderContent` 占位流。
+- 若模型首个真实文本块尚未产出，系统会持续发送保活占位，避免长思考期间 `req_id` 失效。
+
 ```jsonc
 {
   "accounts": {
@@ -279,6 +328,8 @@ openclaw channels status --deep
 
 > **🌟 多账号矩阵下的全局生效与物理隔离**
 > `dynamicAgents` 属于通道级的全局开关，开启后会对配置的所有账号（`accounts`）生效。为了维持账号的绝对隔离，生成的隔离 Agent ID 内置了 Account 维度（例如：`wecom-ops-dm-张三` vs `wecom-sales-dm-张三`），保证跨企业应用依旧安全隔绝。
+>
+> 如果你没有开启 `dynamicAgents`，但多个 `accountId` 共享同一个静态 Agent，请在 OpenClaw 全局配置里显式设置 `session.dmScope = "per-account-channel-peer"`，确保不同账号的私聊上下文不会被收敛到同一个 session key。
 
 ---
 
@@ -370,7 +421,7 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 
 ### 5.1 运行约束原则
 - **协议单工限制**：同一账号下，Bot 只能选择一个主传输协议 `primaryTransport` (`ws` 或 `webhook`) 运作。
-- **帧边界不可打破**：Bot WS 是基于官方微信内部通信协议的扩展，它必须携带并原路奉还对应的 `req_id`。标准化的事件不会替代原始数据帧，业务流始终可访问该原始微信底层框架。
+- **帧边界不可打破**：Bot WS 是基于官方微信内部通信协议的扩展，它必须携带并原路奉还对应的 `req_id`。插件会在长思考期间自动发送占位/保活帧来维持该回复窗口，但标准化事件不会替代原始数据帧，业务流始终可访问该原始微信底层框架。
 - **媒体沙盒边界**：不论是 `Webhook`，还是 `WS`，涉及企微媒体加解密的处理绝不再跨界干预业务执行层。由内部服务自动在 Transport / Media Service 网关边界卸载 `aeskey` 解密并转换为统一 OpenClaw 媒体类抛出。
 
 ### 5.2 企业微信群聊交付规则
@@ -428,26 +479,6 @@ openclaw channels status --deep
 
 ## 七、📮 联系我 与 版本协议
 
-### 最近更新
-
-近期保持高频迭代，最近版本如下：
-
-#### v2.3.10（2026-03-10）
-
-- onboarding 默认收敛为 `Bot + WS + 开放私聊`。
-- 修复 `Bot WS` 长文本双重回复问题。
-- 修复首个自定义接入标识时报 `default not found`。
-- Agent 新配置统一使用 `agentSecret`。
-
-#### v2.3.9（2026-03-09）
-
-- Bot 默认接入改为 `WebSocket`，无需域名更易上手。
-- 完善中文 onboarding，减少重复提示。
-- 恢复 `Bot WS` 流式输出能力。
-- 增强 Agent 回调与发送日志，排障更直接。
-
-详细版本记录见 `changelog/v2.3.10.md` 与 `changelog/v2.3.9.md`。
-
 微信交流群（扫码入群）：
 
 ![企业微信交流群](https://openclaw.cc/wechat-github.jpg)

package/changelog/v2.3.11.md

@@ -0,0 +1,19 @@
+# OpenClaw WeCom 插件 v2.3.11 变更简报
+
+> [!TIP]
+> **稳定性与多账号说明版本**：`v2.3.11` 重点修复 Bot WS 长思考场景下的 `invalid req_id`，同步收敛 onboarding 账号默认值与多账号隔离文档说明。
+
+## 2026-03-11（v2.3.11）
+- 【WS 保活升级】🚀 **[重要修复]** Bot WebSocket 从“4 秒后补发占位”升级为“收到用户消息立即下发占位符，并在长思考期间持续保活”，显著降低慢模型或长任务下的 `invalid req_id` 与回复丢失风险。
+- 【占位符配置生效】🌊 `bot.streamPlaceholderContent` 现在对 `Bot WS` 与 `Bot Webhook` 两条链路统一生效，配置一次即可保持体验一致。
+- 【错误兜底收敛】🛡 修复 `req_id` 已失效时仍尝试二次回错消息的问题，避免出现重复报错与未处理 Promise 拒绝。
+- 【账号选择兜底】🧩 onboarding 在“配置里还没有任何账号”时，也会显式提供 `default` 默认账号选项，减少首次接入时的困惑。
+- 【多账号文档补强】📘 README 新增说明：如果多个 `accountId` 复用同一个静态 Agent，建议配合 `session.dmScope = "per-account-channel-peer"`，避免不同账号的私聊上下文共用。
+- 【日志可读性】🔎 WeCom runtime 的 Bot WS 失败日志改为可读错误文本，排查时不再只看到 `[object Object]`。
+
+## 验证结果
+- `pnpm exec vitest run extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/onboarding.test.ts`
+
+## 升级提示
+- 已有 `bot.streamPlaceholderContent` 配置无需调整，升级后 `Bot WS` 会自动使用它。
+- 如果你在同一个 OpenClaw 实例里挂了多个 WeCom 账号，并让它们指向同一个静态 Agent，建议补上 `session.dmScope = "per-account-channel-peer"` 以隔离私聊上下文。

package/changelog/v2.3.12.md

@@ -0,0 +1,23 @@
+# OpenClaw WeCom 插件 v2.3.12 变更简报
+
+> [!TIP]
+> **WS 主动推送与过期更新兜底版本**：`v2.3.12` 重点修复企业微信 Bot WebSocket 在流式回复超过 6 分钟后返回 `846608 stream message update expired`，并同步调整主动消息路由为“WS 文本优先、Agent 文件兜底”。
+
+## 2026-03-12（v2.3.12）
+- 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。
+- 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。
+- 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。
+- 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。
+- 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。
+- 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。
+- 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。
+
+## 验证结果
+- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`
+- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/outbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`
+- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`
+
+## 升级提示
+- 无需新增配置，升级到 `v2.3.12` 后自动生效。
+- 如果账号正在使用 `Bot WS`，主动文本消息会优先走 WS 长连接；只有文件/媒体或未启用 WS 的场景才会继续使用 Agent。
+- 如果模型或工具链路存在超长执行，超过企业微信 6 分钟回复窗口时，OpenClaw 现在会保持存活并记录运行时错误，不再因该异常退出。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.10",
+  "version": "2.3.12",
   "type": "module",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持 Agent 主动发消息与多账号接入",
   "repository": {

package/src/app/account-runtime.ts

@@ -1,4 +1,4 @@
-import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import { formatErrorMessage, type OpenClawConfig, type PluginRuntime } from "openclaw/plugin-sdk";
 
 import { InMemoryRuntimeStore } from "../store/memory-store.js";
 import { WecomMediaService } from "../shared/media-service.js";
@@ -80,16 +80,17 @@ export class WecomAccountRuntime {
         this.emitStatus();
       },
       fail: async (error: unknown) => {
+        const formattedError = formatErrorMessage(error);
         this.recordOperationalIssue({
           transport: replyHandle.context.transport,
           category: "runtime-error",
           messageId: event.messageId,
           raw: replyHandle.context.raw,
-          summary: `reply-fail ${String(error)}`,
-          error: error instanceof Error ? error.message : String(error),
+          summary: `reply-fail ${formattedError}`,
+          error: formattedError,
         });
         this.log.error?.(
-          `[wecom-runtime] reply-fail account=${event.accountId} transport=${replyHandle.context.transport} messageId=${event.messageId} error=${String(error)}`,
+          `[wecom-runtime] reply-fail account=${event.accountId} transport=${replyHandle.context.transport} messageId=${event.messageId} error=${formattedError}`,
         );
         await replyHandle.fail?.(error);
       },

package/src/app/index.ts

@@ -4,6 +4,12 @@ import { WecomAccountRuntime } from "./account-runtime.js";
 
 let runtime: PluginRuntime | null = null;
 const runtimes = new Map<string, WecomAccountRuntime>();
+const botWsPushHandles = new Map<string, BotWsPushHandle>();
+
+export type BotWsPushHandle = {
+  isConnected: () => boolean;
+  sendMarkdown: (chatId: string, content: string) => Promise<void>;
+};
 
 export function setWecomRuntime(next: PluginRuntime): void {
   runtime = next;
@@ -25,7 +31,20 @@ export function getAccountRuntimeSnapshot(accountId: string) {
   return runtimes.get(accountId)?.buildRuntimeStatus();
 }
 
+export function registerBotWsPushHandle(accountId: string, handle: BotWsPushHandle): void {
+  botWsPushHandles.set(accountId, handle);
+}
+
+export function getBotWsPushHandle(accountId: string): BotWsPushHandle | undefined {
+  return botWsPushHandles.get(accountId);
+}
+
+export function unregisterBotWsPushHandle(accountId: string): void {
+  botWsPushHandles.delete(accountId);
+}
+
 export function unregisterAccountRuntime(accountId: string): void {
   runtimes.delete(accountId);
+  botWsPushHandles.delete(accountId);
   console.log(`[wecom-runtime] unregister account=${accountId}`);
 }

package/src/onboarding.test.ts

@@ -217,6 +217,56 @@ describe("wecom onboarding", () => {
     expect(wecomOnboardingAdapter.dmPolicy).toBeUndefined();
   });
 
+  it("offers default account selection when config has no accounts", async () => {
+    const prompter = createPrompter({
+      select: vi.fn(async ({ message, options }: { message: string; options: Array<{ value: string; label: string }> }) => {
+        if (message === "请选择企业微信接入标识（英文）:") {
+          expect(options.map((option) => option.value)).toEqual(["default", "__new__"]);
+          expect(options[0]?.label).toBe("default（默认标识）");
+          return "default";
+        }
+        if (message === "请选择您要配置的接入模式:") {
+          return "bot";
+        }
+        if (message === "请选择私聊 (DM) 访问策略:") {
+          return "pairing";
+        }
+        throw new Error(`Unexpected select prompt: ${message}`);
+      }) as WizardPrompter["select"],
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "请输入 BotId（机器人 ID）:") {
+          return "bot-id-default";
+        }
+        if (message === "请输入 Secret（机器人密钥）:") {
+          return "bot-secret-default";
+        }
+        if (message === "流式占位符 (可选):") {
+          return "";
+        }
+        if (message === "欢迎语 (可选):") {
+          return "";
+        }
+        throw new Error(`Unexpected text prompt: ${message}`);
+      }) as WizardPrompter["text"],
+    });
+
+    const result = await wecomOnboardingAdapter.configure({
+      cfg: {} as OpenClawConfig,
+      runtime: createRuntime(),
+      prompter,
+      options: {},
+      accountOverrides: {},
+      shouldPromptAccountIds: true,
+      forceAllowFrom: false,
+    });
+
+    expect(result.accountId).toBe("default");
+    expect(result.cfg.channels?.wecom?.accounts?.default?.bot?.ws).toEqual({
+      botId: "bot-id-default",
+      secret: "bot-secret-default",
+    });
+  });
+
   it("writes agentSecret for fresh agent onboarding", async () => {
     const prompter = createPrompter({
       select: vi.fn(async ({ message }: { message: string }) => {

package/src/onboarding.ts

@@ -249,10 +249,13 @@ async function resolveOnboardingAccountId(params: {
     let accountId = override ? normalizeAccountId(override) : defaultAccountId;
     if (!override && params.shouldPromptAccountIds) {
         const existingIds = listWecomAccountIds(params.cfg);
+        const selectableIds = existingIds.includes(DEFAULT_ACCOUNT_ID)
+            ? existingIds
+            : [DEFAULT_ACCOUNT_ID, ...existingIds];
         const choice = await params.prompter.select({
             message: "请选择企业微信接入标识（英文）:",
             options: [
-                ...existingIds.map((id) => ({
+                ...selectableIds.map((id) => ({
                     value: id,
                     label: id === DEFAULT_ACCOUNT_ID ? "default（默认标识）" : id,
                 })),

package/src/outbound.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("./transport/agent-api/core.js", () => ({
   sendText: vi.fn(),
@@ -7,6 +7,13 @@ vi.mock("./transport/agent-api/core.js", () => ({
 }));
 
 describe("wecomOutbound", () => {
+  afterEach(async () => {
+    const runtime = await import("./runtime.js");
+    runtime.unregisterBotWsPushHandle("default");
+    runtime.unregisterBotWsPushHandle("acct-ws");
+    vi.unstubAllGlobals();
+  });
+
   it("does not crash when called with core outbound params", async () => {
     const { wecomOutbound } = await import("./outbound.js");
     await expect(
@@ -173,6 +180,151 @@ describe("wecomOutbound", () => {
     now.mockRestore();
   });
 
+  it("prefers Bot WS active push for text when ws is the active bot transport", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const runtime = await import("./runtime.js");
+    const api = await import("./transport/agent-api/core.js");
+    const sendMarkdown = vi.fn().mockResolvedValue(undefined);
+    const now = vi.spyOn(Date, "now").mockReturnValue(789);
+    runtime.registerBotWsPushHandle("acct-ws", {
+      isConnected: () => true,
+      sendMarkdown,
+    });
+    (api.sendText as any).mockClear();
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-ws",
+          accounts: {
+            "acct-ws": {
+              enabled: true,
+              bot: {
+                primaryTransport: "ws",
+                ws: {
+                  botId: "bot-1",
+                  secret: "secret-1",
+                },
+              },
+              agent: {
+                corpId: "corp-ws",
+                corpSecret: "agent-secret",
+                agentId: 10001,
+                token: "token-ws",
+                encodingAESKey: "aes-ws",
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const result = await wecomOutbound.sendText({
+      cfg,
+      accountId: "acct-ws",
+      to: "user:lisi",
+      text: "hello ws",
+    } as any);
+
+    expect(sendMarkdown).toHaveBeenCalledWith("lisi", "hello ws");
+    expect(api.sendText).not.toHaveBeenCalled();
+    expect(result.messageId).toBe("bot-ws-789");
+
+    now.mockRestore();
+  });
+
+  it("does not silently fall back to Agent when Bot WS active push is configured but unavailable", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const api = await import("./transport/agent-api/core.js");
+    (api.sendText as any).mockClear();
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          bot: {
+            primaryTransport: "ws",
+            ws: {
+              botId: "bot-1",
+              secret: "secret-1",
+            },
+          },
+          agent: {
+            corpId: "corp",
+            corpSecret: "secret",
+            agentId: 1000002,
+            token: "token",
+            encodingAESKey: "aes",
+          },
+        },
+      },
+    };
+
+    await expect(
+      wecomOutbound.sendText({
+        cfg,
+        to: "user:zhangsan",
+        text: "hello",
+      } as any),
+    ).rejects.toThrow(/no live ws runtime is registered/i);
+    expect(api.sendText).not.toHaveBeenCalled();
+  });
+
+  it("keeps outbound media on Agent even when Bot WS is active", async () => {
+    const { wecomOutbound } = await import("./outbound.js");
+    const runtime = await import("./runtime.js");
+    const api = await import("./transport/agent-api/core.js");
+    const sendMarkdown = vi.fn().mockResolvedValue(undefined);
+    runtime.registerBotWsPushHandle("default", {
+      isConnected: () => true,
+      sendMarkdown,
+    });
+    (api.uploadMedia as any).mockResolvedValue("media-1");
+    (api.sendMedia as any).mockResolvedValue(undefined);
+    (api.sendMedia as any).mockClear();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+        headers: new Headers({ "content-type": "image/png" }),
+      }),
+    );
+
+    const cfg = {
+      channels: {
+        wecom: {
+          enabled: true,
+          bot: {
+            primaryTransport: "ws",
+            ws: {
+              botId: "bot-1",
+              secret: "secret-1",
+            },
+          },
+          agent: {
+            corpId: "corp",
+            corpSecret: "secret",
+            agentId: 1000002,
+            token: "token",
+            encodingAESKey: "aes",
+          },
+        },
+      },
+    };
+
+    await wecomOutbound.sendMedia({
+      cfg,
+      to: "user:zhangsan",
+      text: "caption",
+      mediaUrl: "https://example.com/media.png",
+    } as any);
+
+    expect(api.sendMedia).toHaveBeenCalledTimes(1);
+    expect(sendMarkdown).not.toHaveBeenCalled();
+  });
+
   it("uses account-scoped agent config in matrix mode", async () => {
     const { wecomOutbound } = await import("./outbound.js");
     const api = await import("./transport/agent-api/core.js");

package/src/outbound.ts

@@ -2,9 +2,10 @@ import type { ChannelOutboundAdapter, ChannelOutboundContext } from "openclaw/pl
 
 import { resolveWecomAccount, resolveWecomAccountConflict, resolveWecomAccounts } from "./config/index.js";
 import { WecomAgentDeliveryService } from "./capability/agent/index.js";
-import { getWecomRuntime } from "./runtime.js";
+import { getBotWsPushHandle, getWecomRuntime } from "./runtime.js";
+import { resolveScopedWecomTarget } from "./target.js";
 
-function resolveAgentConfigOrThrow(params: {
+function resolveOutboundAccountOrThrow(params: {
   cfg: ChannelOutboundContext["cfg"];
   accountId?: string | null;
 }) {
@@ -26,10 +27,17 @@ function resolveAgentConfigOrThrow(params: {
       );
     }
   }
-  const account = resolveWecomAccount({
+  return resolveWecomAccount({
     cfg: params.cfg,
     accountId: params.accountId,
-  }).agent;
+  });
+}
+
+function resolveAgentConfigOrThrow(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+}) {
+  const account = resolveOutboundAccountOrThrow(params).agent;
   if (!account?.apiConfigured) {
     throw new Error(
       `WeCom outbound requires Agent mode for account=${params.accountId ?? "default"}. Configure channels.wecom.accounts.<accountId>.agent (or legacy channels.wecom.agent).`,
@@ -45,6 +53,81 @@ function resolveAgentConfigOrThrow(params: {
   return account;
 }
 
+function isExplicitAgentTarget(raw: string | undefined): boolean {
+  return /^wecom-agent:/i.test(String(raw ?? "").trim());
+}
+
+function resolveBotWsChatTarget(params: {
+  to: string | undefined;
+  accountId: string;
+}): string | undefined {
+  const scoped = resolveScopedWecomTarget(params.to, params.accountId);
+  if (!scoped) {
+    return undefined;
+  }
+  if (scoped.accountId && scoped.accountId !== params.accountId) {
+    throw new Error(
+      `WeCom outbound account mismatch: target belongs to account=${scoped.accountId}, current account=${params.accountId}.`,
+    );
+  }
+  if (scoped.target.chatid) {
+    return scoped.target.chatid;
+  }
+  if (scoped.target.touser) {
+    return scoped.target.touser;
+  }
+  return undefined;
+}
+
+function shouldPreferBotWsOutbound(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+  to: string | undefined;
+}): { preferred: boolean; accountId: string } {
+  const account = resolveOutboundAccountOrThrow({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  return {
+    preferred: !isExplicitAgentTarget(params.to) && Boolean(account.bot?.configured && account.bot.primaryTransport === "ws" && account.bot.wsConfigured),
+    accountId: account.accountId,
+  };
+}
+
+async function sendTextViaBotWs(params: {
+  cfg: ChannelOutboundContext["cfg"];
+  accountId?: string | null;
+  to: string | undefined;
+  text: string;
+}): Promise<boolean> {
+  const { preferred, accountId } = shouldPreferBotWsOutbound(params);
+  if (!preferred) {
+    return false;
+  }
+  const chatId = resolveBotWsChatTarget({
+    to: params.to,
+    accountId,
+  });
+  if (!chatId) {
+    return false;
+  }
+  const handle = getBotWsPushHandle(accountId);
+  if (!handle) {
+    throw new Error(
+      `WeCom outbound account=${accountId} is configured for Bot WS active push, but no live WS runtime is registered.`,
+    );
+  }
+  if (!handle.isConnected()) {
+    throw new Error(
+      `WeCom outbound account=${accountId} is configured for Bot WS active push, but the WS transport is not connected.`,
+    );
+  }
+  console.log(`[wecom-outbound] Sending Bot WS active message to target=${String(params.to ?? "")} chatId=${chatId} (len=${params.text.length})`);
+  await handle.sendMarkdown(chatId, params.text);
+  console.log(`[wecom-outbound] Successfully sent Bot WS active message to ${chatId}`);
+  return true;
+}
+
 export const wecomOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
   chunkerMode: "text",
@@ -59,9 +142,6 @@ export const wecomOutbound: ChannelOutboundAdapter = {
   sendText: async ({ cfg, to, text, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
-    const agent = resolveAgentConfigOrThrow({ cfg, accountId });
-    const deliveryService = new WecomAgentDeliveryService(agent);
-
     // 体验优化：/new /reset 的“New session started”回执在 OpenClaw 核心里是英文固定文案，
     // 且通过 routeReply 走 wecom outbound（Agent 主动发送）。
     // 在 WeCom“双模式”场景下，这会造成：
@@ -93,12 +173,23 @@ export const wecomOutbound: ChannelOutboundAdapter = {
 
     console.log(`[wecom-outbound] Sending text to target=${String(to ?? "")} (len=${outgoingText.length})`);
 
+    let sentViaBotWs = false;
     try {
-      await deliveryService.sendText({
+      sentViaBotWs = await sendTextViaBotWs({
+        cfg,
+        accountId,
         to,
         text: outgoingText,
       });
-      console.log(`[wecom-outbound] Successfully sent text to ${String(to ?? "")}`);
+      if (!sentViaBotWs) {
+        const agent = resolveAgentConfigOrThrow({ cfg, accountId });
+        const deliveryService = new WecomAgentDeliveryService(agent);
+        await deliveryService.sendText({
+          to,
+          text: outgoingText,
+        });
+        console.log(`[wecom-outbound] Successfully sent Agent text to ${String(to ?? "")}`);
+      }
     } catch (err) {
       console.error(`[wecom-outbound] Failed to send text to ${String(to ?? "")}:`, err);
       throw err;
@@ -106,13 +197,17 @@ export const wecomOutbound: ChannelOutboundAdapter = {
 
     return {
       channel: "wecom",
-      messageId: `agent-${Date.now()}`,
+      messageId: `${sentViaBotWs ? "bot-ws" : "agent"}-${Date.now()}`,
       timestamp: Date.now(),
     };
   },
   sendMedia: async ({ cfg, to, text, mediaUrl, accountId }: ChannelOutboundContext) => {
     // signal removed - not supported in current SDK
 
+    const { preferred } = shouldPreferBotWsOutbound({ cfg, accountId, to });
+    if (preferred) {
+      console.log(`[wecom-outbound] Bot WS active push does not support outbound media; falling back to Agent for target=${String(to ?? "")}`);
+    }
     const agent = resolveAgentConfigOrThrow({ cfg, accountId });
     const deliveryService = new WecomAgentDeliveryService(agent);
     if (!mediaUrl) {