@yanhaidao/wecom 2.3.10 → 2.3.13

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,57 @@
 
 ---
 
+<a id="sec-changelog"></a>
+
+## 📋 最近更新
+
+> 项目保持高频迭代，核心改进一览：
+
+#### v2.3.13（2026-03-13）
+
+- 🛠 **[重要修复]** `Bot WS` 现在会把“引用 + 提问”中的引用内容一起带入 Agent 上下文，不再只保留用户当前这句提问。
+- 🌊 **[重要修复]** `Bot WS` 流式回复改为按“累计全文刷新”发送，修复企业微信客户端里长回答断断续续、像被拆成多段的问题。
+- 🧩 `Bot WS` 这次显式对齐企业微信 `stream.id` 的刷新语义：后续更新会覆盖为当前完整内容，而不是只发送最新增量片段。
+- ✅ 新增 `bot-ws` 引用上下文与累计流式发送回归测试，避免后续重构回退。
+
+#### 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 而非崩溃。
+- ⏱ 回复窗口过期时占位符保活立即停止。
+- 🛠 **[重要修复]** Bot WS 模式下接收图片/文件现在使用消息体独立 `aeskey` 解密，修复之前保存密文导致 `Failed to optimize image` 的问题。
+- 🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的 81013 错误。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。
+
+#### 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 +246,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 +281,10 @@ openclaw channels status --deep
 最简的流式交互版（无兜底分发功能）。
 关键约束：`bot.primaryTransport = "ws"` 必须包含 `bot.ws` 参数。
 
+行为说明：
+- 收到用户消息后立即发送一次 `streamPlaceholderContent` 占位流。
+- 若模型首个真实文本块尚未产出，系统会持续发送保活占位，避免长思考期间 `req_id` 失效。
+
 ```jsonc
 {
   "accounts": {
@@ -279,6 +337,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 +430,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 企业微信群聊交付规则
@@ -422,32 +482,15 @@ openclaw channels status --deep
 **Q5: 为什么发视频给 Bot 没反应？**
 > **A:** 官方 Bot 接口**不支持接收视频**。如果您需要处理视频内容，必须配置 Agent 小微应用，由于 Agent 下行具备富媒体流承接功能，本插件会自动从底层拦截将其解码并传输给底层大模型看。
 
+**Q6: 支持个人微信吗？**
+> **A:** 支持企业微信场景下的“微信插件入口”（个人微信扫码进入企业应用对话），这不等同于“个人微信网页版协议”。您可以在个人微信中直接与企业号/应用对话，无需打开企业微信 App。
+
 ---
 
 <a id="sec-9"></a>
 
 ## 七、📮 联系我 与 版本协议
 
-### 最近更新
-
-近期保持高频迭代，最近版本如下：
-
-#### 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,25 @@
+# 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 两种模式都不支持的文件/媒体发送。
+- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。
+- 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。
+- 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。
+- 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。
+- 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。
+- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。
+
+## 验证结果
+- `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/changelog/v2.3.13.md

@@ -0,0 +1,19 @@
+# OpenClaw WeCom 插件 v2.3.13 变更简报
+
+> [!TIP]
+> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。
+
+## 2026-03-13（v2.3.13）
+- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。
+- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。
+- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。
+- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。
+
+## 验证结果
+- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.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.13` 后自动生效。
+- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。
+- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.10",
+  "version": "2.3.13",
   "type": "module",
-  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持 Agent 主动发消息与多账号接入",
+  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/YanHaidao/wecom.git"

package/src/agent/handler.ts

@@ -566,32 +566,31 @@ async function processAgentMessage(params: {
         }
         return;
     }
-
-    const ctxPayload = core.channel.reply.finalizeInboundContext({
-        Body: body,
-        RawBody: finalContent,
-        CommandBody: finalContent,
-        Attachments: attachments.length > 0 ? attachments : undefined,
-        From: isGroup ? `wecom:group:${peerId}` : `wecom:${fromUser}`,
-        To: `wecom:${peerId}`,
-        SessionKey: route.sessionKey,
-        AccountId: route.accountId,
-        ChatType: isGroup ? "group" : "direct",
-        ConversationLabel: fromLabel,
-        SenderName: fromUser,
-        SenderId: fromUser,
-        Provider: "wecom",
-        Surface: "webchat",
-        OriginatingChannel: "wecom",
-        // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
-        // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
-        // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）
-        OriginatingTo: buildAgentSessionTarget(fromUser, agent.accountId),
-        CommandAuthorized: authz.commandAuthorized ?? true,
-        MediaPath: mediaPath,
-        MediaType: mediaType,
-        MediaUrl: mediaPath,
-    });
+const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: finalContent,
+    CommandBody: finalContent,
+    Attachments: attachments.length > 0 ? attachments : undefined,
+    From: isGroup ? `wecom:group:${peerId}` : `wecom:user:${fromUser}`,
+    To: `wecom:user:${peerId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: fromUser,
+    SenderId: fromUser,
+    Provider: "wecom",
+    Surface: "webchat",
+    OriginatingChannel: "wecom",
+    // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
+    // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
+    // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）
+    OriginatingTo: buildAgentSessionTarget(fromUser, agent.accountId),
+    CommandAuthorized: authz.commandAuthorized ?? true,
+    MediaPath: mediaPath,
+    MediaType: mediaType,
+    MediaUrl: mediaPath,
+});
 
     // 记录会话
     await core.channel.session.recordInboundSession({

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/dynamic-agent.ts

@@ -51,7 +51,8 @@ export function generateAgentId(chatType: "dm" | "group", peerId: string, accoun
 export function buildAgentSessionTarget(userId: string, accountId?: string): string {
     const normalizedUserId = String(userId).trim();
     const sanitizedAccountId = sanitizeDynamicIdPart(accountId ?? "default") || "default";
-    return `wecom-agent:${sanitizedAccountId}:${normalizedUserId}`;
+    // Always use explicit user: prefix to avoid ambiguity with numeric party IDs
+    return `wecom-agent:${sanitizedAccountId}:user:${normalizedUserId}`;
 }
 
 /**

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");