@yanhaidao/wecom 2.3.9 → 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,8 +31,10 @@
 ## 💡 核心价值：为什么选择本插件？
 
 ### 🎉 重大特性一览
-1. **无需域名，极低门槛**：全面支持基于 WebSocket 的长连接（Bot WS）模式接入企业微信机器人，**彻底打通无公网 IP、无备案域名的内网服务器**与企微的实时对话桥梁！
-2. **主动发消息，能力全覆盖**：基于 Agent 模式，全面支持**主动触达**，轻松实现早报定时任务、服务器异常报警、自动每日总结。
+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 路由绑定**，丝滑跳过全局冗杂的路由分配步骤。
 
 ### 🔧 全新统一运行时架构 (Unified Runtime)
 插件现已采用全新解耦架构：
@@ -53,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，实现闭环的高可用。
 
@@ -93,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>
 ## 一、🚀 快速开始
 
@@ -154,7 +199,7 @@ openclaw channels add
           },
           "agent": {
             "corpId": "CORP_ID",
-            "corpSecret": "CORP_SECRET",
+            "agentSecret": "AGENT_SECRET",
             "agentId": 1000001,
             "token": "AGENT_TOKEN",
             "encodingAESKey": "AGENT_AES_KEY",
@@ -189,6 +234,12 @@ 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接入方式。
 
@@ -221,6 +272,10 @@ openclaw channels status --deep
 最简的流式交互版（无兜底分发功能）。
 关键约束：`bot.primaryTransport = "ws"` 必须包含 `bot.ws` 参数。
 
+行为说明：
+- 收到用户消息后立即发送一次 `streamPlaceholderContent` 占位流。
+- 若模型首个真实文本块尚未产出，系统会持续发送保活占位，避免长思考期间 `req_id` 失效。
+
 ```jsonc
 {
   "accounts": {
@@ -273,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。
 
 ---
 
@@ -364,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 企业微信群聊交付规则
@@ -422,19 +479,6 @@ openclaw channels status --deep
 
 ## 七、📮 联系我 与 版本协议
 
-### v2.3.9 更新日志（2026-03-09）
-
-本次版本重点收敛为“默认更易用、排障更直接、回调更稳定”：
-
-- **默认 Bot WebSocket 引导**：onboarding 默认写入 `bot.ws`，新用户无需域名即可完成机器人接入。
-- **中文化配置体验**：企业微信插件自管账号创建与私聊策略提示，尽量避免流程中重复出现英文术语。
-- **Bot WS 流式输出修复**：长连接模式支持块级流式交付，不再只保留最终结果。
-- **Webhook / Agent 回调稳定性增强**：统一 HTTP 分发链路，并补齐默认账号显式路径，便于 Bot 与 Agent 回调稳定命中。
-- **Agent 排障日志增强**：补充原始 callback、解密摘要、发送请求与响应日志，更容易定位“能接收但不能回复”的问题。
-- **配置收敛**：移除 `bot.enabled` / `agent.enabled` 冗余字段，减少误导。
-
-详细版本记录见 `changelog/v2.3.9.md`。
-
 微信交流群（扫码入群）：
 
 ![企业微信交流群](https://openclaw.cc/wechat-github.jpg)

package/changelog/v2.3.10.md

@@ -0,0 +1,17 @@
+# OpenClaw WeCom 插件 v2.3.10 变更简报
+
+> [!TIP]
+> **默认更易用、修复更直接的版本。**
+
+## 2026-03-10（v2.3.10）
+- 【消息防丢修复】🐛 **[重要修复]** 针对由于模型 API 限速或超长思考（如 DeepSeek R1）导致的企微 WebSocket 5秒超时断连问题，引入了 4 秒前置保活机制（自动下发"⏳ 正在思考中..."），彻底阻断了因为模型响应慢而造成的“消息卡死不再回复”。
+- 【双重回复修复】🐛 **[重要修复]** 修复 `Bot WS` 长文本场景下可能被超时截断并触发兜底通道进行二次重复回复的边界异常。
+- 【向导自动路由】✨ **[体验升级]** 重构了企业微信的渠道交互配置向导。在单账号场景下将静默触发自动路由绑定，丝滑跳过 OpenClaw 全局冗长的 Agent 路由分配询问。
+- 【账号兜底修复】🧩 修复企业微信 onboarding 在首个账号非字面量 `default` 时，后续流程报 `WeCom account "default" not found` 的问题。
+- 【默认选项收敛】🚀 onboarding 的默认回车选项已变更为更普适的 `Bot` 模式、`WS` 接入和 `开放模式` 策略。
+- 【字段命名收敛】📝 Agent 新配置统一推荐使用 `agentSecret`，历史 `corpSecret` 保持兼容读取，保障平滑升级。
+- 【文档与提示精简】📘 README、向导交互文案与示例结构已全面统一为更符合直觉的精简说明。
+
+## 验证结果
+- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`
+- `pnpm build`

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/compat-single-account.md

@@ -31,7 +31,7 @@ openclaw config set channels.wecom.bot.dm.allowFrom '["*"]'
 
 ```bash
 openclaw config set channels.wecom.agent.corpId "YOUR_CORP_ID"
-openclaw config set channels.wecom.agent.corpSecret "YOUR_CORP_SECRET"
+openclaw config set channels.wecom.agent.agentSecret "YOUR_AGENT_SECRET"
 openclaw config set channels.wecom.agent.agentId 1000001
 openclaw config set channels.wecom.agent.token "YOUR_CALLBACK_TOKEN"
 openclaw config set channels.wecom.agent.encodingAESKey "YOUR_CALLBACK_AES_KEY"
@@ -71,7 +71,7 @@ openclaw channels status
 
       "agent": {
         "corpId": "YOUR_CORP_ID",
-        "corpSecret": "YOUR_CORP_SECRET",
+        "agentSecret": "YOUR_AGENT_SECRET",
         "agentId": 1000001,
         "token": "YOUR_CALLBACK_TOKEN",
         "encodingAESKey": "YOUR_CALLBACK_AES_KEY",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.9",
+  "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/config/accounts.resolve.test.ts

@@ -13,8 +13,11 @@ describe("resolveWecomAccount", () => {
           "acct-a": {
             enabled: true,
             bot: {
-              token: "token-a",
-              encodingAESKey: "aes-a",
+              primaryTransport: "webhook",
+              webhook: {
+                token: "token-a",
+                encodingAESKey: "aes-a",
+              },
             },
           },
         },
@@ -35,4 +38,38 @@ describe("resolveWecomAccount", () => {
     expect(account.enabled).toBe(true);
     expect(account.configured).toBe(true);
   });
+
+  it("treats literal default as an alias for configured default account", () => {
+    const account = resolveWecomAccount({ cfg, accountId: "default" });
+    expect(account.accountId).toBe("acct-a");
+    expect(account.enabled).toBe(true);
+    expect(account.configured).toBe(true);
+  });
+
+  it("accepts agentSecret for fresh configs and normalizes it for runtime use", () => {
+    const agentCfg: OpenClawConfig = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-agent",
+          accounts: {
+            "acct-agent": {
+              enabled: true,
+              agent: {
+                corpId: "corp-id",
+                agentSecret: "agent-secret",
+                agentId: 1000001,
+                token: "token",
+                encodingAESKey: "1234567890123456789012345678901234567890123",
+              },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const account = resolveWecomAccount({ cfg: agentCfg });
+    expect(account.agent?.apiConfigured).toBe(true);
+    expect(account.agent?.corpSecret).toBe("agent-secret");
+  });
 });

package/src/config/accounts.ts

@@ -73,14 +73,15 @@ function resolveAgentAccount(
 ): ResolvedAgentAccount {
   const agentId = toNumber(config.agentId);
   const callbackConfigured = Boolean(config.token && config.encodingAESKey);
-  const apiConfigured = Boolean(config.corpId && config.corpSecret && agentId);
+  const normalizedAgentSecret = config.agentSecret?.trim() || config.corpSecret?.trim() || "";
+  const apiConfigured = Boolean(config.corpId && normalizedAgentSecret && agentId);
   return {
     accountId,
     configured: callbackConfigured || apiConfigured,
     callbackConfigured,
     apiConfigured,
     corpId: config.corpId,
-    corpSecret: config.corpSecret,
+    corpSecret: normalizedAgentSecret,
     agentId,
     token: config.token,
     encodingAESKey: config.encodingAESKey,
@@ -113,6 +114,15 @@ function toResolvedAccount(params: {
   };
 }
 
+function createMissingResolvedAccount(accountId: string): ResolvedWecomAccount {
+  return {
+    accountId,
+    enabled: false,
+    configured: false,
+    config: {},
+  };
+}
+
 export function detectMode(config: WecomConfig | undefined): ResolvedMode {
   if (!config || config.enabled === false) return "disabled";
   if (config.accounts && Object.keys(config.accounts).length > 0) {
@@ -260,12 +270,24 @@ export function resolveWecomAccount(params: {
   accountId?: string | null;
 }): ResolvedWecomAccount {
   const resolved = resolveWecomAccounts(params.cfg);
-  const accountId = params.accountId?.trim() || resolved.defaultAccountId;
-  const account = resolved.accounts[accountId];
-  if (!account) {
-    throw new Error(`WeCom account "${accountId}" not found.`);
+  const explicitAccountId = params.accountId?.trim();
+  const accountId = explicitAccountId || resolved.defaultAccountId;
+  const direct = resolved.accounts[accountId];
+  if (direct) {
+    return direct;
   }
-  return account;
+
+  // Treat the literal "default" as an alias for the configured default account.
+  // This keeps generic onboarding flows working even when the first WeCom account
+  // was created under a custom id like "haidao" instead of a literal "default".
+  if (explicitAccountId === DEFAULT_ACCOUNT_ID) {
+    const fallback = resolved.accounts[resolved.defaultAccountId];
+    if (fallback) {
+      return fallback;
+    }
+  }
+
+  return createMissingResolvedAccount(accountId);
 }
 
 export function isWecomEnabled(cfg: OpenClawConfig): boolean {

package/src/config/schema.ts

@@ -67,13 +67,18 @@ const botSchema = z
 const agentSchema = z
   .object({
     corpId: z.string(),
-    corpSecret: z.string(),
+    agentSecret: z.string().optional(),
+    corpSecret: z.string().optional(),
     agentId: z.union([z.number(), z.string()]).optional(),
     token: z.string(),
     encodingAESKey: z.string(),
     welcomeText: z.string().optional(),
     dm: dmSchema,
   })
+  .refine((value) => Boolean(value.agentSecret?.trim() || value.corpSecret?.trim()), {
+    path: ["agentSecret"],
+    message: "agentSecret 不能为空",
+  })
   .optional();
 
 const dynamicAgentsSchema = z

package/src/onboarding.test.ts

@@ -168,7 +168,7 @@ describe("wecom onboarding", () => {
   it("uses plugin-owned chinese account selection and no generic dm adapter", async () => {
     const prompter = createPrompter({
       select: vi.fn(async ({ message }: { message: string }) => {
-        if (message === "请选择企业微信账号:") {
+        if (message === "请选择企业微信接入标识（英文）:") {
           return "__new__";
         }
         if (message === "请选择您要配置的接入模式:") {
@@ -180,7 +180,7 @@ describe("wecom onboarding", () => {
         throw new Error(`Unexpected select prompt: ${message}`);
       }) as WizardPrompter["select"],
       text: vi.fn(async ({ message }: { message: string }) => {
-        if (message === "请输入新的企业微信账号 ID:") {
+        if (message === "请输入新的企业微信接入标识（英文）:") {
           return "HaiDao";
         }
         if (message === "请输入 BotId（机器人 ID）:") {
@@ -213,7 +213,106 @@ describe("wecom onboarding", () => {
     const noteText = (prompter.note as ReturnType<typeof vi.fn>).mock.calls
       .map(([message]) => String(message))
       .join("\n");
-    expect(noteText).toContain("账号 ID 已规范化为：haidao");
+    expect(noteText).toContain("接入标识已规范化为：haidao");
     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 }) => {
+        if (message === "请选择您要配置的接入模式:") {
+          return "agent";
+        }
+        if (message === "请选择私聊 (DM) 访问策略:") {
+          return "open";
+        }
+        throw new Error(`Unexpected select prompt: ${message}`);
+      }) as WizardPrompter["select"],
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "请输入 CorpID (企业ID):") {
+          return "corp-id";
+        }
+        if (message === "请输入 AgentID (应用ID):") {
+          return "1000001";
+        }
+        if (message === "请输入应用 Secret:") {
+          return "agent-secret";
+        }
+        if (message === "请输入 Token (回调令牌):") {
+          return "callback-token";
+        }
+        if (message === "请输入 EncodingAESKey (回调加密密钥):") {
+          return "1234567890123456789012345678901234567890123";
+        }
+        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: false,
+      forceAllowFrom: false,
+    });
+
+    const agent = result.cfg.channels?.wecom?.accounts?.default?.agent;
+    expect(agent?.agentSecret).toBe("agent-secret");
+    expect(agent?.corpSecret).toBeUndefined();
+  });
 });

package/src/onboarding.ts

@@ -249,27 +249,30 @@ 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: "请选择企业微信账号:",
+            message: "请选择企业微信接入标识（英文）:",
             options: [
-                ...existingIds.map((id) => ({
+                ...selectableIds.map((id) => ({
                     value: id,
-                    label: id === DEFAULT_ACCOUNT_ID ? "default（主账号）" : id,
+                    label: id === DEFAULT_ACCOUNT_ID ? "default（默认标识）" : id,
                 })),
-                { value: "__new__", label: "新增账号" },
+                { value: "__new__", label: "新增接入标识" },
             ],
             initialValue: accountId,
         });
         if (choice === "__new__") {
             const entered = await params.prompter.text({
-                message: "请输入新的企业微信账号 ID:",
-                validate: (value: string | undefined) => (value?.trim() ? undefined : "账号 ID 不能为空"),
+                message: "请输入新的企业微信接入标识（英文）:",
+                validate: (value: string | undefined) => (value?.trim() ? undefined : "接入标识不能为空"),
             });
             const normalized = normalizeAccountId(String(entered));
             if (String(entered).trim() !== normalized) {
                 await params.prompter.note(
-                    `账号 ID 已规范化为：${normalized}`,
-                    "企业微信账号",
+                    `接入标识已规范化为：${normalized}`,
+                    "企业微信接入标识",
                 );
             }
             accountId = normalized;
@@ -325,7 +328,7 @@ async function promptMode(prompter: WizardPrompter): Promise<WecomMode> {
                 hint: "Bot 默认 WS 易上手，Agent 负责应用回调、主动推送和媒体发送",
             },
         ],
-        initialValue: "both",
+        initialValue: "bot",
     });
     return choice as WecomMode;
 }
@@ -433,10 +436,10 @@ async function configureAgentMode(
     ).trim();
     const agentId = Number(agentIdStr);
 
-    const corpSecret = String(
+    const agentSecret = String(
         await prompter.text({
-            message: "请输入 Secret (应用密钥):",
-            validate: (value: string | undefined) => (value?.trim() ? undefined : "Secret 不能为空"),
+            message: "请输入应用 Secret:",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "应用 Secret 不能为空"),
         }),
     ).trim();
 
@@ -478,7 +481,7 @@ async function configureAgentMode(
 
     const agentConfig: WecomAgentConfig = {
         corpId,
-        corpSecret,
+        agentSecret,
         agentId,
         token,
         encodingAESKey,
@@ -506,7 +509,7 @@ async function promptDmPolicy(
             { value: "open", label: "开放模式", hint: "任何人可发起" },
             { value: "disabled", label: "禁用私聊", hint: "不接受私聊消息" },
         ],
-        initialValue: "pairing",
+        initialValue: "open",
     });
 
     const policy = policyChoice as "pairing" | "allowlist" | "open" | "disabled";
@@ -560,7 +563,7 @@ async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter, accoun
         lines.push("   出站能力: Agent API（主动发送 / 补送 / 媒体）");
     }
 
-    lines.push(`   账号 ID: ${accountId}`);
+    lines.push(`   接入标识: ${accountId}`);
     lines.push("   运维检查: openclaw channels status --deep");
     lines.push("   关键日志: [wecom-runtime] [wecom-ws] [wecom-http] [wecom-agent-delivery]");