@yanhaidao/wecom 2.3.4 → 2.3.9

package/changelog/v2.3.9.md

@@ -0,0 +1,22 @@
+# OpenClaw WeCom 插件 v2.3.9 变更简报
+
+> [!TIP]
+> **易用性与可观测性版本**：`v2.3.9` 重点优化默认 Bot WebSocket 接入体验、中文 onboarding、Bot/Agent 回调稳定性与排障日志。
+
+## 2026-03-09（v2.3.9）
+- 【默认接入】🚀 Bot onboarding 默认收敛为 `WebSocket` 模式，直接引导填写 `bot.ws.botId` 与 `bot.ws.secret`，新用户无需域名即可接入。
+- 【主动消息】📣 在引导文案中明确 Bot WS 支持主动发消息，适合定时任务、异常提醒、工作流通知等企业场景。
+- 【中文体验】🈶 企业微信插件自管账号创建与私聊策略配置流程，减少重复英文提示与术语负担。
+- 【流式修复】🌊 修复 Bot WS 仅输出最终结果的问题，恢复块级流式交付能力。
+- 【路由稳定】🧭 统一 HTTP 分发链路，并补齐默认账号的显式 Bot/Agent 回调路径别名，降低回调命中偏差。
+- 【排障增强】🔎 增加 Agent callback 原始请求、解密摘要、发送请求与响应日志，便于定位“能接收但不能回复”的问题。
+- 【配置清理】🧹 移除 `bot.enabled` / `agent.enabled` 冗余字段，README 与配置模型保持一致。
+
+## 验证结果
+- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`
+- `pnpm build`
+
+## 升级提示
+- 默认推荐继续使用 `Bot WebSocket` 模式；如需公网回调，可手动补充 `bot.webhook`。
+- 推荐回调路径使用 `/plugins/wecom/bot/{accountId}` 与 `/plugins/wecom/agent/{accountId}`。
+- `package.json` 与插件元数据已同步更新为 `WeCom (企业微信)`，便于在 OpenClaw 渠道列表中直接识别。

package/compat-single-account.md

@@ -18,6 +18,7 @@ openclaw config set channels.wecom.enabled true
 openclaw config set channels.wecom.bot.token "YOUR_BOT_TOKEN"
 openclaw config set channels.wecom.bot.encodingAESKey "YOUR_BOT_AES_KEY"
 openclaw config set channels.wecom.bot.receiveId ""
+openclaw config set channels.wecom.bot.primaryTransport "webhook"
 openclaw config set channels.wecom.bot.streamPlaceholderContent "正在思考..."
 openclaw config set channels.wecom.bot.welcomeText "你好！我是 AI 助手"
 
@@ -108,8 +109,37 @@ openclaw channels status
 
 ## A.4 Webhook 路径
 
-- Bot: `/wecom`（默认）或 `/wecom/bot`
-- Agent: `/wecom/agent`
+- Bot Webhook: `/plugins/wecom/bot`（推荐），兼容 `/wecom/bot`、`/wecom`
+- Agent Callback: `/plugins/wecom/agent`（推荐），兼容 `/wecom/agent`
+
+说明：
+
+- 路径由系统派生，不建议额外维护自定义 path。
+- 如果 Bot 主 transport 改成 `ws`，则 Bot 不再依赖 HTTP callback，但 Agent Callback 仍可保留。
+
+## A.4.1 Bot WS 单账号示例
+
+```bash
+openclaw config set channels.wecom.bot.primaryTransport "ws"
+openclaw config set channels.wecom.bot.ws.botId "YOUR_BOT_ID"
+openclaw config set channels.wecom.bot.ws.secret "YOUR_BOT_SECRET"
+```
+
+运维检查：
+
+```bash
+openclaw channels status --deep
+```
+
+重点看：
+
+- `primaryTransport`
+- `transport`
+- `health`
+- `ownerId`
+- `lastError`
+- `lastInboundAt`
+- `lastOutboundAt`
 
 ## A.5 迁移建议
 

package/index.ts

@@ -10,16 +10,16 @@ import { wecomPlugin } from "./src/channel.js";
 
 const plugin = {
   id: "wecom",
-  name: "WeCom",
-  description: "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
+  name: "WeCom (企业微信)",
+  description: "企业微信官方推荐三方插件，默认 Bot WS，支持主动发消息与统一运行时能力",
   configSchema: emptyPluginConfigSchema(),
   /**
    * **register (注册插件)**
    *
    * OpenClaw 插件入口点。
-   * 1. 注入 Runtime 环境 (api.runtime)。
-   * 2. 注册 WeCom 渠道插件 (ChannelPlugin)。
-   * 3. 注册 Webhook HTTP 路由（推荐 /plugins/wecom/*，兼容 /wecom*）。
+   * 1. 注入统一 runtime compatibility layer。
+   * 2. 注册 capability-first WeCom 渠道插件。
+   * 3. 注册统一 HTTP 入口（所有 webhook 请求都走共享路由器）。
    */
   register(api: OpenClawPluginApi) {
     setWecomRuntime(api.runtime);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.4",
+  "version": "2.3.9",
   "type": "module",
-  "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
+  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持 Agent 主动发消息与多账号接入",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/YanHaidao/wecom.git"
@@ -18,12 +18,12 @@
     ],
     "channel": {
       "id": "wecom",
-      "label": "WeCom",
-      "selectionLabel": "WeCom (plugin)",
-      "detailLabel": "WeCom Bot",
+      "label": "WeCom (企业微信)",
+      "selectionLabel": "WeCom (企业微信)",
+      "detailLabel": "WeCom (企业微信)",
       "docsPath": "/channels/wecom",
-      "docsLabel": "wecom",
-      "blurb": "Enterprise WeCom intelligent bot (API mode) via encrypted webhooks + passive replies.",
+      "docsLabel": "企业微信",
+      "blurb": "企业微信官方推荐三方插件，默认 Bot WS 配置简单，支持主动发消息与 Agent 全能力。",
       "aliases": [
         "wechatwork",
         "wework",
@@ -40,6 +40,7 @@
     }
   },
   "dependencies": {
+    "@wecom/aibot-node-sdk": "^1.0.0",
     "fast-xml-parser": "5.3.4",
     "undici": "^7.20.0",
     "zod": "^4.3.6"

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

@@ -15,12 +15,11 @@ vi.mock("../config/index.js", () => ({
   resolveWecomEgressProxyUrlFromNetwork: resolveProxyMock,
 }));
 
-import { uploadMedia } from "./api-client.js";
+import { uploadMedia } from "../transport/agent-api/core.js";
 
 function createAgent(agentId: number): ResolvedAgentAccount {
   return {
     accountId: `acct-${agentId}`,
-    enabled: true,
     configured: true,
     corpId: "corp",
     corpSecret: "secret",

package/src/agent/handler.ts

@@ -18,12 +18,14 @@ import {
     extractFileName,
     extractAgentId,
 } from "../shared/xml-parser.js";
-import { sendText, downloadMedia } from "./api-client.js";
+import { downloadAgentApiMedia, sendAgentApiText } from "../transport/agent-api/client.js";
 import { getWecomRuntime } from "../runtime.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
+import type { TransportSessionPatch } from "../types/index.js";
 import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
 import { resolveWecomMediaMaxBytes, shouldRejectWecomDefaultRoute } from "../config/index.js";
-import { generateAgentId, shouldUseDynamicAgent, ensureDynamicAgentListed } from "../dynamic-agent.js";
+import { buildAgentSessionTarget, generateAgentId, shouldUseDynamicAgent, ensureDynamicAgentListed } from "../dynamic-agent.js";
+import type { WecomRuntimeAuditEvent } from "../types/runtime-context.js";
 
 /** 错误提示信息 */
 const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaidao)";
@@ -122,6 +124,8 @@ export type AgentWebhookParams = {
     core: PluginRuntime;
     log?: (msg: string) => void;
     error?: (msg: string) => void;
+    auditSink?: (event: WecomRuntimeAuditEvent) => void;
+    touchTransportSession?: (patch: TransportSessionPatch) => void;
 };
 
 export type AgentInboundProcessDecision = {
@@ -194,7 +198,7 @@ function resolveQueryParams(req: IncomingMessage): URLSearchParams {
  * 处理消息回调 (POST)
  */
 async function handleMessageCallback(params: AgentWebhookParams): Promise<boolean> {
-    const { req, res, verifiedPost, agent, config, core, log, error } = params;
+    const { req, res, verifiedPost, agent, config, core, log, error, auditSink } = params;
 
     try {
         if (!verifiedPost) {
@@ -241,6 +245,17 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
             const ok = rememberAgentMsgId(msgId);
             if (!ok) {
                 log?.(`[wecom-agent] duplicate msgId=${msgId} from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}; skipped`);
+                auditSink?.({
+                    transport: "agent-callback",
+                    category: "duplicate-reply",
+                    messageId: msgId,
+                    summary: `duplicate agent callback from=${fromUser} chatId=${chatId ?? "N/A"} type=${msgType}`,
+                    raw: {
+                        transport: "agent-callback",
+                        envelopeType: "xml",
+                        body: msg,
+                    },
+                });
                 res.statusCode = 200;
                 res.setHeader("Content-Type", "text/plain; charset=utf-8");
                 res.end("success");
@@ -281,6 +296,8 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
             msg,
             log,
             error,
+            auditSink,
+            touchTransportSession: params.touchTransportSession,
         }).catch((err) => {
             error?.(`[wecom-agent] process failed: ${String(err)}`);
         });
@@ -317,8 +334,10 @@ async function processAgentMessage(params: {
     msg: WecomAgentInboundMessage;
     log?: (msg: string) => void;
     error?: (msg: string) => void;
+    auditSink?: (event: WecomRuntimeAuditEvent) => void;
+    touchTransportSession?: (patch: TransportSessionPatch) => void;
 }): Promise<void> {
-    const { agent, config, core, fromUser, chatId, content, msg, msgType, log, error } = params;
+    const { agent, config, core, fromUser, chatId, content, msg, msgType, log, error, auditSink, touchTransportSession } = params;
 
     const isGroup = Boolean(chatId);
     const peerId = isGroup ? chatId! : fromUser;
@@ -335,7 +354,7 @@ async function processAgentMessage(params: {
         if (mediaId) {
             try {
                 log?.(`[wecom-agent] downloading media: ${mediaId} (${msgType})`);
-                const { buffer, contentType, filename: headerFileName } = await downloadMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
+                const { buffer, contentType, filename: headerFileName } = await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
                 const xmlFileName = extractFileName(msg);
                 const originalFileName = (xmlFileName || headerFileName || `${mediaId}.bin`).trim();
                 const heuristic = analyzeTextHeuristic(buffer);
@@ -413,6 +432,18 @@ async function processAgentMessage(params: {
                 log?.(`[wecom-agent] file preview: enabled=${looksText} finalContentLen=${finalContent.length} attachments=${attachments.length}`);
             } catch (err) {
                 error?.(`[wecom-agent] media processing failed: ${String(err)}`);
+                auditSink?.({
+                    transport: "agent-callback",
+                    category: "runtime-error",
+                    messageId: extractMsgId(msg) ?? undefined,
+                    summary: `agent media processing failed mediaId=${mediaId}`,
+                    raw: {
+                        transport: "agent-callback",
+                        envelopeType: "xml",
+                        body: msg,
+                    },
+                    error: err instanceof Error ? err.message : String(err),
+                });
                 finalContent = [
                     content,
                     "",
@@ -450,10 +481,22 @@ async function processAgentMessage(params: {
             `[wecom-agent] routing guard: blocked default fallback accountId=${agent.accountId} matchedBy=${route.matchedBy} from=${fromUser}`,
         );
         try {
-            await sendText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
+            await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
+            touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
             log?.(`[wecom-agent] routing guard prompt delivered to ${fromUser}`);
         } catch (err: unknown) {
             error?.(`[wecom-agent] routing guard prompt failed: ${String(err)}`);
+            auditSink?.({
+                transport: "agent-callback",
+                category: "fallback-delivery-failed",
+                summary: `routing guard prompt failed user=${fromUser}`,
+                raw: {
+                    transport: "agent-callback",
+                    envelopeType: "xml",
+                    body: msg,
+                },
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
         return;
     }
@@ -504,10 +547,22 @@ async function processAgentMessage(params: {
     if (authz.shouldComputeAuth && authz.commandAuthorized !== true) {
         const prompt = buildWecomUnauthorizedCommandPrompt({ senderUserId: fromUser, dmPolicy: authz.dmPolicy, scope: "agent" });
         try {
-            await sendText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
+            await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text: prompt });
+            touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
             log?.(`[wecom-agent] unauthorized command: replied via DM to ${fromUser}`);
         } catch (err: unknown) {
             error?.(`[wecom-agent] unauthorized command reply failed: ${String(err)}`);
+            auditSink?.({
+                transport: "agent-callback",
+                category: "fallback-delivery-failed",
+                summary: `unauthorized prompt failed user=${fromUser}`,
+                raw: {
+                    transport: "agent-callback",
+                    envelopeType: "xml",
+                    body: msg,
+                },
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
         return;
     }
@@ -531,7 +586,7 @@ async function processAgentMessage(params: {
         // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
         // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
         // - 群聊场景也统一路由为私信触发者（与 deliver 策略一致）
-        OriginatingTo: `wecom-agent:${fromUser}`,
+        OriginatingTo: buildAgentSessionTarget(fromUser, agent.accountId),
         CommandAuthorized: authz.commandAuthorized ?? true,
         MediaPath: mediaPath,
         MediaType: mediaType,
@@ -552,18 +607,36 @@ async function processAgentMessage(params: {
     await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
         ctx: ctxPayload,
         cfg: config,
+        replyOptions: {
+            disableBlockStreaming: true,
+        },
         dispatcherOptions: {
             deliver: async (payload: { text?: string }, info: { kind: string }) => {
+                if (info.kind !== "final") {
+                    return;
+                }
                 const text = payload.text ?? "";
                 if (!text) return;
 
                 try {
                     // 统一策略：Agent 模式在群聊场景默认只私信触发者（避免 wr/wc chatId 86008）
-                    await sendText({ agent, toUser: fromUser, chatId: undefined, text });
+                    await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text });
+                    touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
                     log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser}`);
                 } catch (err: unknown) {
                     const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
                     error?.(`[wecom-agent] reply failed: ${message}`);
+                    auditSink?.({
+                        transport: "agent-callback",
+                        category: "fallback-delivery-failed",
+                        summary: `agent callback reply failed user=${fromUser} kind=${info.kind}`,
+                        raw: {
+                            transport: "agent-callback",
+                            envelopeType: "xml",
+                            body: msg,
+                        },
+                        error: message,
+                    });
                 }            },
             onError: (err: unknown, info: { kind: string }) => {
                 error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);

package/src/agent/index.ts

@@ -9,4 +9,4 @@ export {
     uploadMedia,
     sendMedia,
     downloadMedia,
-} from "./api-client.js";
+} from "../transport/agent-api/core.js";

package/src/app/account-runtime.ts

@@ -0,0 +1,245 @@
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+
+import { InMemoryRuntimeStore } from "../store/memory-store.js";
+import { WecomMediaService } from "../shared/media-service.js";
+import { summarizeTransportSessions } from "../observability/transport-session-view.js";
+import type {
+  AccountRuntimeStatusSnapshot,
+  ReplyHandle,
+  ReplyPayload,
+  TransportSessionPatch,
+  TransportSessionSnapshot,
+  UnifiedInboundEvent,
+  WecomAuditCategory,
+  WecomRuntimeHealth,
+  WecomTransportKind,
+} from "../types/index.js";
+import type { ResolvedRuntimeAccount } from "../config/runtime-config.js";
+import { dispatchInboundEvent } from "../runtime/dispatcher.js";
+import { WecomAuditLog } from "../observability/audit-log.js";
+import { WecomStatusRegistry } from "../observability/status-registry.js";
+
+export class WecomAccountRuntime {
+  readonly store = new InMemoryRuntimeStore();
+  readonly mediaService: WecomMediaService;
+  readonly auditLog = new WecomAuditLog();
+  readonly statusRegistry = new WecomStatusRegistry();
+  private readonly runtimeStatus: AccountRuntimeStatusSnapshot;
+
+  constructor(
+    readonly core: PluginRuntime,
+    readonly cfg: OpenClawConfig,
+    readonly resolved: ResolvedRuntimeAccount,
+    private readonly log: {
+      info?: (message: string) => void;
+      warn?: (message: string) => void;
+      error?: (message: string) => void;
+    } = {},
+    private readonly statusSink?: (snapshot: Record<string, unknown>) => void,
+  ) {
+    this.mediaService = new WecomMediaService(core);
+    this.runtimeStatus = {
+      accountId: resolved.account.accountId,
+      health: "idle",
+      ownerId: null,
+      ownerDriftAt: null,
+      lastError: null,
+      lastErrorAt: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+      recentInboundSummary: null,
+      recentOutboundSummary: null,
+      recentIssueCategory: null,
+      recentIssueSummary: null,
+      transportSessions: [],
+    };
+  }
+
+  get account() {
+    return this.resolved.account;
+  }
+
+  async handleEvent(event: UnifiedInboundEvent, replyHandle: ReplyHandle): Promise<void> {
+    this.runtimeStatus.lastInboundAt = Date.now();
+    this.runtimeStatus.recentInboundSummary = `${event.transport} ${event.inboundKind} ${event.messageId}`;
+    this.log.info?.(
+      `[wecom-runtime] inbound account=${event.accountId} transport=${event.transport} kind=${event.inboundKind} messageId=${event.messageId} peer=${event.conversation.peerKind}:${event.conversation.peerId}`,
+    );
+    this.emitStatus();
+
+    const trackedReplyHandle: ReplyHandle = {
+      context: replyHandle.context,
+      deliver: async (payload: ReplyPayload, info) => {
+        await replyHandle.deliver(payload, info);
+        this.runtimeStatus.lastOutboundAt = Date.now();
+        const outboundSummary = payload.text?.trim() || payload.mediaUrl || payload.mediaUrls?.[0] || info.kind;
+        this.runtimeStatus.recentOutboundSummary = `${replyHandle.context.transport} ${outboundSummary.slice(0, 120)}`;
+        this.log.info?.(
+          `[wecom-runtime] outbound account=${event.accountId} transport=${replyHandle.context.transport} kind=${info.kind} messageId=${event.messageId} summary=${JSON.stringify(this.runtimeStatus.recentOutboundSummary)}`,
+        );
+        this.emitStatus();
+      },
+      fail: async (error: unknown) => {
+        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),
+        });
+        this.log.error?.(
+          `[wecom-runtime] reply-fail account=${event.accountId} transport=${replyHandle.context.transport} messageId=${event.messageId} error=${String(error)}`,
+        );
+        await replyHandle.fail?.(error);
+      },
+    };
+
+    await dispatchInboundEvent({
+      core: this.core,
+      cfg: this.cfg,
+      store: this.store,
+      auditLog: this.auditLog,
+      mediaService: this.mediaService,
+      event,
+      replyHandle: trackedReplyHandle,
+    });
+  }
+
+  updateTransportSession(snapshot: TransportSessionSnapshot): void {
+    const previous = this.store.readTransportSession(snapshot.accountId, snapshot.transport);
+    this.store.writeTransportSession(snapshot);
+    this.statusRegistry.write(snapshot);
+    this.log.info?.(
+      `[wecom-runtime] session account=${snapshot.accountId} transport=${snapshot.transport} running=${snapshot.running} owner=${snapshot.ownerId ?? "none"} connected=${String(snapshot.connected ?? false)} authenticated=${String(snapshot.authenticated ?? false)} error=${snapshot.lastError ?? "none"}`,
+    );
+    if (
+      previous?.ownerId &&
+      snapshot.ownerId &&
+      previous.ownerId !== snapshot.ownerId &&
+      previous.running
+    ) {
+      this.recordOperationalIssue({
+        transport: snapshot.transport,
+        category: "owner-drift",
+        summary: `owner drift ${previous.ownerId} -> ${snapshot.ownerId}`,
+      });
+    }
+    if (snapshot.lastError) {
+      this.runtimeStatus.lastError = snapshot.lastError;
+      this.runtimeStatus.lastErrorAt = Date.now();
+    } else if (snapshot.running) {
+      this.runtimeStatus.lastError = null;
+    }
+    this.emitStatus();
+  }
+
+  touchTransportSession(transport: WecomTransportKind, patch: TransportSessionPatch): void {
+    const current = this.store.readTransportSession(this.account.accountId, transport);
+    const next: TransportSessionSnapshot = {
+      accountId: this.account.accountId,
+      transport,
+      running: patch.running ?? current?.running ?? true,
+      ownerId: patch.ownerId ?? current?.ownerId,
+      connected: patch.connected ?? current?.connected,
+      authenticated: patch.authenticated ?? current?.authenticated,
+      lastConnectedAt: patch.lastConnectedAt ?? current?.lastConnectedAt,
+      lastDisconnectedAt: patch.lastDisconnectedAt ?? current?.lastDisconnectedAt,
+      lastInboundAt: patch.lastInboundAt ?? current?.lastInboundAt,
+      lastOutboundAt: patch.lastOutboundAt ?? current?.lastOutboundAt,
+      lastError: "lastError" in patch ? patch.lastError ?? undefined : current?.lastError,
+    };
+    this.updateTransportSession(next);
+  }
+
+  listTransportSessions() {
+    return this.statusRegistry.read(this.account.accountId);
+  }
+
+  listAuditEntries() {
+    return this.auditLog.list();
+  }
+
+  buildRuntimeStatus(): AccountRuntimeStatusSnapshot {
+    const sessions = this.listTransportSessions();
+    const primarySession = this.resolvePrimarySession(sessions);
+    return {
+      ...this.runtimeStatus,
+      health: this.computeHealth(sessions),
+      transport: primarySession?.transport,
+      ownerId: primarySession?.ownerId ?? this.runtimeStatus.ownerId ?? null,
+      connected: primarySession?.connected,
+      authenticated: primarySession?.authenticated,
+      lastError:
+        primarySession?.lastError ??
+        (primarySession?.running ? null : this.runtimeStatus.lastError ?? null),
+      transportSessions: summarizeTransportSessions(sessions),
+    };
+  }
+
+  recordOperationalIssue(params: {
+    transport: WecomTransportKind;
+    category: WecomAuditCategory;
+    summary: string;
+    messageId?: string;
+    raw?: ReplyHandle["context"]["raw"];
+    error?: string;
+  }): void {
+    this.auditLog.appendOperational({
+      accountId: this.account.accountId,
+      transport: params.transport,
+      category: params.category,
+      messageId: params.messageId,
+      summary: params.summary,
+      raw: params.raw,
+      error: params.error,
+    });
+    if (params.category === "owner-drift" || params.category === "ws-kicked") {
+      this.runtimeStatus.ownerDriftAt = Date.now();
+    }
+    this.runtimeStatus.lastError = params.error ?? params.summary;
+    this.runtimeStatus.lastErrorAt = Date.now();
+    this.runtimeStatus.recentIssueCategory = params.category;
+    this.runtimeStatus.recentIssueSummary = params.summary;
+    const sink = params.category === "runtime-error" || params.category === "fallback-delivery-failed" ? this.log.error : this.log.warn;
+    sink?.(
+      `[wecom-runtime] issue account=${this.account.accountId} transport=${params.transport} category=${params.category} messageId=${params.messageId ?? "n/a"} summary=${params.summary}`,
+    );
+    this.emitStatus();
+  }
+
+  private emitStatus(): void {
+    this.statusSink?.(this.buildRuntimeStatus() as unknown as Record<string, unknown>);
+  }
+
+  private resolvePrimarySession(
+    sessions: TransportSessionSnapshot[],
+  ): TransportSessionSnapshot | undefined {
+    const primaryTransport = this.account.bot?.configured
+      ? this.account.bot.primaryTransport === "ws"
+        ? "bot-ws"
+        : "bot-webhook"
+      : this.account.agent?.callbackConfigured
+        ? "agent-callback"
+        : undefined;
+    if (!primaryTransport) {
+      return sessions[0];
+    }
+    return sessions.find((session) => session.transport === primaryTransport) ?? sessions[0];
+  }
+
+  private computeHealth(sessions: TransportSessionSnapshot[]): WecomRuntimeHealth {
+    if (sessions.length === 0) {
+      return this.runtimeStatus.lastError ? "down" : "idle";
+    }
+    const hasRunning = sessions.some((session) => session.running);
+    const hasError = sessions.some((session) => Boolean(session.lastError));
+    if (hasRunning && !hasError) {
+      return "healthy";
+    }
+    if (hasRunning) {
+      return "degraded";
+    }
+    return hasError ? "down" : "idle";
+  }
+}

package/src/app/bootstrap.ts

@@ -0,0 +1,29 @@
+import type { ChannelGatewayContext } from "openclaw/plugin-sdk";
+
+import { resolveWecomRuntimeAccount } from "../config/runtime-config.js";
+import type { ResolvedWecomAccount } from "../types/index.js";
+import { WecomAccountRuntime } from "./account-runtime.js";
+import { getWecomRuntime } from "./index.js";
+
+export function createAccountRuntime(ctx: ChannelGatewayContext<ResolvedWecomAccount>): WecomAccountRuntime {
+  const resolved = resolveWecomRuntimeAccount({
+    cfg: ctx.cfg,
+    accountId: ctx.accountId,
+  });
+  return new WecomAccountRuntime(
+    getWecomRuntime(),
+    ctx.cfg,
+    resolved,
+    {
+      info: (message) => ctx.log?.info(message),
+      warn: (message) => ctx.log?.warn(message),
+      error: (message) => ctx.log?.error(message),
+    },
+    (snapshot) => {
+      ctx.setStatus({
+        accountId: ctx.accountId,
+        ...snapshot,
+      });
+    },
+  );
+}

package/src/app/index.ts

@@ -0,0 +1,31 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+import { WecomAccountRuntime } from "./account-runtime.js";
+
+let runtime: PluginRuntime | null = null;
+const runtimes = new Map<string, WecomAccountRuntime>();
+
+export function setWecomRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getWecomRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("WeCom runtime not initialized");
+  }
+  return runtime;
+}
+
+export function registerAccountRuntime(accountRuntime: WecomAccountRuntime): void {
+  runtimes.set(accountRuntime.account.accountId, accountRuntime);
+  console.log(`[wecom-runtime] register account=${accountRuntime.account.accountId}`);
+}
+
+export function getAccountRuntimeSnapshot(accountId: string) {
+  return runtimes.get(accountId)?.buildRuntimeStatus();
+}
+
+export function unregisterAccountRuntime(accountId: string): void {
+  runtimes.delete(accountId);
+  console.log(`[wecom-runtime] unregister account=${accountId}`);
+}