@sunnoy/wecom 1.6.0 → 1.7.0

package/README.md

@@ -2,6 +2,40 @@
 
 `openclaw-plugin-wecom` 是一个专为 [OpenClaw](https://github.com/openclaw/openclaw) 框架开发的企业微信（WeCom）集成插件。它允许你将强大的 AI 能力无缝接入企业微信，支持 AI 机器人模式和自建应用模式，并具备多层消息投递回退机制。
 
+## 目录导航
+
+### 快速开始
+- [核心特性](#核心特性)
+- [前置要求](#前置要求)
+- [安装](#安装)
+- [运行测试](#运行测试)
+- [运行真实 E2E 测试（远程 OpenClaw）](#运行真实-e2e-测试远程-openclaw)
+
+### 配置与接入
+- [配置](#配置)
+- [配置说明](#配置说明)
+- [企业微信后台配置](#企业微信后台配置)
+- [方式一：创建 AI 机器人 (Bot 模式)](#方式一创建-ai-机器人-bot-模式)
+- [方式二：创建自建应用 (Agent 模式)](#方式二创建自建应用-agent-模式)
+- [方式三：配置群机器人 (Webhook 模式)](#方式三配置群机器人-webhook-模式)
+
+### 能力与路由
+- [支持的消息类型](#支持的消息类型)
+- [流式回复能力](#流式回复能力)
+- [管理员用户](#管理员用户)
+- [动态 Agent 路由](#动态-agent-路由)
+- [支持的目标格式](#支持的目标格式)
+- [指令白名单](#指令白名单)
+- [消息防抖合并](#消息防抖合并)
+
+### 运维与参考
+- [常见问题 (FAQ)](#常见问题-faq)
+- [项目结构](#项目结构)
+- [贡献规范](#贡献规范)
+- [开源协议](#开源协议)
+- [配置示例参考](#配置示例参考)
+- [自定义 Skills 配合沙箱使用实践](#自定义-skills-配合沙箱使用实践)
+
 ## 核心特性
 
 ### 消息模式支持
@@ -9,6 +43,12 @@
 - **自建应用模式 (Agent Mode)**: 支持企业微信自建应用，可处理 XML 格式的回调消息，支持收发消息、上传下载媒体文件。
 - **Webhook Bot 模式**: 支持通过 Webhook 发送消息到群聊，适用于群通知场景。
 
+### 流式回复增强
+- **Markdown 格式支持**: 流式回复的 `content` 字段支持常见 Markdown 格式，包括加粗、斜体、代码块、列表、标题、链接等，企业微信客户端会自动渲染。
+- **思考过程展示**: 当 LLM 回复包含 `<think>...</think>` 标签时，插件自动解析并通过 `thinking_content` 字段在客户端展示可折叠的思考过程。
+- **被动回复思考模式**: 首次被动回复即启用思考模式 UI（通过 `thinking_content` 字段），用户无需等待即可看到模型正在思考的状态。
+- **图片混合回复**: 支持在最终回复（`finish=true`）时包含 `msgtype` 为 `image` 的 `msg_item`，流式过程中图片会排队等待最终发送。
+
 ### 智能消息投递
 - **四层投递回退机制**: 确保消息可靠送达
   1. **流式通道**: 优先通过活跃流式通道发送
@@ -21,7 +61,7 @@
 ### 动态 Agent 与隔离
 - **动态 Agent 管理**: 默认按"每个私聊用户 / 每个群聊"自动创建独立 Agent。每个 Agent 拥有独立的工作区与对话上下文，实现更强的数据隔离。
 - **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
-- **管理员用户**: 可配置管理员列表，绕过指令白名单和动态 Agent 路由限制。
+- **管理员用户**: 可配置管理员列表，默认绕过指令白名单；可选开启“绕过动态 Agent 路由”。
 - **指令白名单**: 内置常用指令支持（如 `/new`、`/status`），并提供指令白名单配置功能。
 
 ### 多媒体支持
@@ -152,7 +192,7 @@ npm run test:e2e
 | `plugins.entries.wecom.enabled` | boolean | 是 | 启用插件 |
 | `channels.wecom.token` | string | 是* | 企业微信机器人 Token (*Bot 模式必填) |
 | `channels.wecom.encodingAesKey` | string | 是* | 消息加密密钥（43 位）(*Bot 模式必填) |
-| `channels.wecom.adminUsers` | array | 否 | 管理员用户 ID 列表（绕过指令白名单和动态路由） |
+| `channels.wecom.adminUsers` | array | 否 | 管理员用户 ID 列表（绕过指令白名单） |
 | `channels.wecom.commands.enabled` | boolean | 否 | 是否启用指令白名单过滤（默认 true） |
 | `channels.wecom.commands.allowlist` | array | 否 | 允许的指令白名单 |
 
@@ -163,6 +203,7 @@ npm run test:e2e
 | 配置项 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
 | `channels.wecom.dynamicAgents.enabled` | boolean | 否 | 是否启用动态 Agent（默认 true） |
+| `channels.wecom.dynamicAgents.adminBypass` | boolean | 否 | 管理员是否跳过动态 Agent 路由（默认 false） |
 | `channels.wecom.dm.createAgentOnFirstMessage` | boolean | 否 | 私聊时为每个用户创建独立 Agent（默认 true） |
 | `channels.wecom.groupChat.enabled` | boolean | 否 | 是否启用群聊处理（默认 true） |
 | `channels.wecom.groupChat.requireMention` | boolean | 否 | 群聊是否必须 @ 提及才响应（默认 true） |
@@ -293,15 +334,58 @@ Webhook Bot 用于向群聊发送通知消息。
 | 位置 (location) | 收 | 位置分享（转换为文本描述） |
 | 链接 (link) | 收 | 分享链接（提取标题、描述、URL 为文本） |
 
+## 流式回复能力
+
+### Markdown 格式
+
+流式回复的 `content` 字段支持以下 Markdown 格式，企业微信客户端会自动渲染：
+
+| 格式 | 语法 | 示例 |
+|------|------|------|
+| 加粗 | `**text**` | **加粗文本** |
+| 斜体 | `*text*` | *斜体文本* |
+| 行内代码 | `` `code` `` | `code` |
+| 代码块 | ` ```lang ... ``` ` | 多行代码 |
+| 列表 | `- item` / `1. item` | 有序/无序列表 |
+| 标题 | `# H1` / `## H2` | 各级标题 |
+| 链接 | `[text](url)` | 超链接 |
+
+### 思考过程展示（Thinking Mode）
+
+当 LLM 模型（如 DeepSeek、QwQ 等支持思考模式的模型）在回复中输出 `<think>...</think>` 标签时，插件会自动：
+
+1. **解析** `<think>` 标签，将思考内容与可见内容分离
+2. **映射** 思考内容到企业微信流式回复的 `thinking_content` 字段
+3. **展示** 企业微信客户端会以可折叠的方式显示模型的思考过程
+
+**流式处理说明：**
+- 被动回复（首次同步响应）立即启用思考模式 UI，显示「思考中...」
+- 当检测到未闭合的 `<think>` 标签（流式输出中），`thinking_content` 持续更新
+- `</think>` 闭合后，思考内容固定，后续内容显示为可见回复
+- 代码块内的 `<think>` 标签不会被解析（避免误匹配）
+
+**支持的标签变体：** `<think>`, `<thinking>`, `<thought>`（均不区分大小写）
+
+### 图片回复
+
+图片通过 `msg_item` 以 base64 编码在流式回复结束时发送：
+
+- 仅在 `finish=true`（最终回复）时包含 `msgtype` 为 `image` 的 `msg_item`
+- 流式过程中生成的图片会排队，待回复完成后一次性发送
+- 单张图片最大 2MB，支持 JPG/PNG 格式，每条消息最多 10 张
+
 ## 管理员用户
 
-管理员用户可以绕过指令白名单限制，并跳过动态 Agent 路由（直接路由到主 Agent）。
+管理员用户默认可以绕过指令白名单限制。若希望管理员用户同时跳过动态 Agent 路由（直接路由到主 Agent），可开启 `dynamicAgents.adminBypass`。
 
 ```json
 {
   "channels": {
     "wecom": {
-      "adminUsers": ["user1", "user2"]
+      "adminUsers": ["user1", "user2"],
+      "dynamicAgents": {
+        "adminBypass": true
+      }
     }
   }
 }
@@ -322,7 +406,7 @@ Webhook Bot 用于向群聊发送通知消息。
    - **多账号群聊**: `wecom-<accountId>-group-<chatId>`
 2. OpenClaw 自动创建/复用对应的 Agent 工作区
 3. 每个用户/群聊拥有独立的对话历史和上下文
-4. **管理员用户**跳过动态路由，直接使用主 Agent
+4. 管理员用户默认参与动态路由；当 `dynamicAgents.adminBypass=true` 时跳过动态路由，直接使用主 Agent
 
 ### 高级配置
 
@@ -350,6 +434,7 @@ Webhook Bot 用于向群聊发送通知消息。
 | 配置项 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | `dynamicAgents.enabled` | boolean | `true` | 是否启用动态 Agent |
+| `dynamicAgents.adminBypass` | boolean | `false` | 管理员是否跳过动态 Agent 路由 |
 | `dm.createAgentOnFirstMessage` | boolean | `true` | 私聊使用动态 Agent |
 | `groupChat.enabled` | boolean | `true` | 启用群聊处理 |
 | `groupChat.requireMention` | boolean | `true` | 群聊必须 @ 提及才响应 |
@@ -384,6 +469,7 @@ Webhook Bot 用于向群聊发送通知消息。
         "token": "Bot1 的 Token",
         "encodingAesKey": "Bot1 的 EncodingAESKey",
         "adminUsers": ["admin1"],
+        "workspaceTemplate": "/path/to/bot1-template",
         "agent": {
           "corpId": "企业 CorpID",
           "corpSecret": "Bot1 应用 Secret",
@@ -417,6 +503,7 @@ Webhook Bot 用于向群聊发送通知消息。
 | 完全兼容 | 旧的单账号配置（`token` 直接写在 `wecom` 下）自动识别为 `default` 账号，无需修改 |
 | Webhook 路径 | 自动按账号分配：`/webhooks/wecom/bot1`、`/webhooks/wecom/bot2` |
 | Agent 回调路径 | 自动按账号分配：`/webhooks/app/bot1`、`/webhooks/app/bot2` |
+| 工作区模板 | 支持按账号自定义：`channels.wecom.<accountId>.workspaceTemplate`（覆盖全局配置） |
 | 动态 Agent ID | 按账号隔离：`wecom-bot1-dm-{userId}`、`wecom-bot2-group-{chatId}` |
 | 冲突检测 | 启动时自动检测重复的 Token 或 Agent ID，避免消息路由错乱 |
 
@@ -708,6 +795,7 @@ openclaw-plugin-wecom/
 ├── logger.js                # 日志模块
 ├── utils.js                 # 工具函数（TTL 缓存、消息去重）
 ├── stream-manager.js        # 流式回复管理
+├── think-parser.js          # 思考标签解析（<think> 标签分离）
 ├── image-processor.js       # 图片编码/校验（msg_item）
 ├── webhook.js               # 企业微信 Bot 模式 HTTP 通信处理
 ├── dynamic-agent.js         # 动态 Agent 分配逻辑

package/dynamic-agent.js

@@ -47,17 +47,21 @@ export function getDynamicAgentConfig(config) {
     groupEnabled: wecom.groupChat?.enabled !== false,
     groupRequireMention: wecom.groupChat?.requireMention !== false,
     groupMentionPatterns: wecom.groupChat?.mentionPatterns || ["@"],
+    adminBypass: wecom.dynamicAgents?.adminBypass === true,
   };
 }
 
 /**
  * Decide whether this message context should route to a dynamic agent.
  */
-export function shouldUseDynamicAgent({ chatType, config }) {
+export function shouldUseDynamicAgent({ chatType, config, senderIsAdmin = false }) {
   const dynamicConfig = getDynamicAgentConfig(config);
   if (!dynamicConfig.enabled) {
     return false;
   }
+  if (senderIsAdmin && dynamicConfig.adminBypass) {
+    return false;
+  }
   if (chatType === "group") {
     return dynamicConfig.groupEnabled;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -15,6 +15,7 @@
         "LICENSE",
         "CONTRIBUTING.md",
         "stream-manager.js",
+        "think-parser.js",
         "utils.js",
         "webhook.js",
         "openclaw.plugin.json"

package/think-parser.js

@@ -0,0 +1,119 @@
+/**
+ * Parse <think>...</think> tags from LLM output.
+ *
+ * Separates content into visible text and thinking process for WeCom's
+ * thinking_content stream field. Handles streaming (unclosed tags) and
+ * ignores tags inside code blocks.
+ */
+
+const QUICK_TAG_RE = /<\s*\/?\s*(?:think(?:ing)?|thought)\b/i;
+const THINK_TAG_RE = /<\s*(\/?)\s*(?:think(?:ing)?|thought)\b[^<>]*>/gi;
+
+/**
+ * Find code regions (``` blocks and `inline`) to avoid processing think tags
+ * that appear inside code.
+ * @param {string} text
+ * @returns {Array<[number, number]>}
+ */
+function findCodeRegions(text) {
+  const regions = [];
+  // Fenced code blocks (triple backtick).
+  const blockRe = /```[\s\S]*?```/g;
+  for (const m of text.matchAll(blockRe)) {
+    regions.push([m.index, m.index + m[0].length]);
+  }
+  // Inline code (single backtick, same line).
+  const inlineRe = /`[^`\n]+`/g;
+  for (const m of text.matchAll(inlineRe)) {
+    if (!isInsideRegion(m.index, regions)) {
+      regions.push([m.index, m.index + m[0].length]);
+    }
+  }
+  return regions;
+}
+
+/**
+ * @param {number} pos
+ * @param {Array<[number, number]>} regions
+ */
+function isInsideRegion(pos, regions) {
+  for (const [start, end] of regions) {
+    if (pos >= start && pos < end) return true;
+  }
+  return false;
+}
+
+/**
+ * Parse thinking content from text that may contain <think>...</think> tags.
+ *
+ * @param {string} text - Raw accumulated stream text
+ * @returns {{ visibleContent: string, thinkingContent: string, isThinking: boolean }}
+ *   - visibleContent: text with think blocks removed (for content field)
+ *   - thinkingContent: concatenated thinking text (for thinking_content field)
+ *   - isThinking: true when an unclosed <think> tag is present (streaming)
+ */
+export function parseThinkingContent(text) {
+  if (!text) {
+    return { visibleContent: "", thinkingContent: "", isThinking: false };
+  }
+
+  // Fast path: no think tags at all.
+  if (!QUICK_TAG_RE.test(text)) {
+    return { visibleContent: text, thinkingContent: "", isThinking: false };
+  }
+
+  const codeRegions = findCodeRegions(text);
+
+  const visibleParts = [];
+  const thinkingParts = [];
+  let lastIndex = 0;
+  let inThinking = false;
+
+  THINK_TAG_RE.lastIndex = 0;
+  for (const match of text.matchAll(THINK_TAG_RE)) {
+    const idx = match.index;
+    const isClose = match[1] === "/";
+
+    // Skip tags inside code blocks.
+    if (isInsideRegion(idx, codeRegions)) {
+      continue;
+    }
+
+    const segment = text.slice(lastIndex, idx);
+
+    if (!inThinking) {
+      if (!isClose) {
+        // Opening <think>: preceding text is visible.
+        visibleParts.push(segment);
+        inThinking = true;
+      } else {
+        // Stray </think> without opening: treat as visible text.
+        visibleParts.push(segment);
+      }
+    } else {
+      if (isClose) {
+        // Closing </think>: text since opening is thinking content.
+        thinkingParts.push(segment);
+        inThinking = false;
+      }
+      // Nested or duplicate opening tag inside thinking: ignore.
+    }
+
+    lastIndex = idx + match[0].length;
+  }
+
+  // Remaining text after the last tag.
+  const remaining = text.slice(lastIndex);
+  if (inThinking) {
+    // Unclosed <think>: remaining text is part of thinking (streaming state).
+    thinkingParts.push(remaining);
+  } else {
+    visibleParts.push(remaining);
+  }
+
+  return {
+    visibleContent: visibleParts.join("").trim(),
+    thinkingContent: thinkingParts.join("\n").trim(),
+    isThinking: inThinking,
+  };
+}

package/webhook.js

@@ -435,7 +435,12 @@ export class WecomWebhook {
       content: content,
     };
 
-    // Optional mixed media list (images are valid on finished responses).
+    // Thinking content for model reasoning display (collapsible in WeCom client).
+    if (options.thinkingContent) {
+      stream.thinking_content = options.thinkingContent;
+    }
+
+    // Optional mixed media list (images are valid only on finished responses).
     if (options.msgItem && options.msgItem.length > 0) {
       stream.msg_item = options.msgItem;
     }

package/wecom/accounts.js

@@ -79,16 +79,17 @@ function buildAccount(accountId, accountCfg) {
     agent?.corpId && agent?.corpSecret && agent?.agentId && agent?.token && agent?.encodingAesKey,
   );
 
+  const hasBotTokens = Boolean(accountCfg?.token && accountCfg?.encodingAesKey);
+  const defaultPath = accountId === DEFAULT_ACCOUNT_ID ? "/webhooks/wecom" : `/webhooks/wecom/${accountId}`;
+
   return {
     accountId,
     name: accountCfg?.name || accountId,
     enabled: accountCfg?.enabled !== false,
-    configured: Boolean(accountCfg?.token && accountCfg?.encodingAesKey) || agentConfigured,
+    configured: hasBotTokens || agentConfigured,
     token: accountCfg?.token || "",
     encodingAesKey: accountCfg?.encodingAesKey || "",
-    webhookPath:
-      accountCfg?.webhookPath ||
-      (accountId === DEFAULT_ACCOUNT_ID ? "/webhooks/wecom" : `/webhooks/wecom/${accountId}`),
+    webhookPath: accountCfg?.webhookPath || (hasBotTokens ? defaultPath : ""),
     config: accountCfg || {},
     agentConfigured,
     agentInboundConfigured,

package/wecom/agent-inbound.js

@@ -43,6 +43,7 @@ import {
 
 const RECENT_MSGID_TTL_MS = 10 * 60 * 1000;
 const recentAgentMsgIds = new Map();
+const AGENT_INBOUND_ALLOWED_MSG_TYPES = new Set(["text", "image", "voice", "video", "file"]);
 
 function rememberAgentMsgId(msgId) {
   const now = Date.now();
@@ -157,6 +158,21 @@ async function handleMessageCallback(req, res, crypto, agentConfig, config, acco
     const msgId = extractMsgId(msg);
     const content = extractContent(msg);
 
+    // White-list inbound message types to prevent event callbacks
+    // (for example subscribe/unsubscribe) from triggering LLM replies.
+    if (!AGENT_INBOUND_ALLOWED_MSG_TYPES.has(msgType)) {
+      logger.info("[agent-inbound] unsupported msgType ignored", {
+        msgType,
+        fromUser,
+        chatId: chatId || "N/A",
+        msgId: msgId || "N/A",
+        contentPreview: content.substring(0, 100),
+      });
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("success");
+      return true;
+    }
+
     // Deduplication
     if (msgId) {
       if (!rememberAgentMsgId(msgId)) {
@@ -292,12 +308,18 @@ async function processAgentMessage({
 
   const dynamicConfig = getDynamicAgentConfig(accountCfg);
   const targetAgentId =
-    dynamicConfig.enabled && shouldUseDynamicAgent({ chatType: peerKind, config: accountCfg })
+    dynamicConfig.enabled
+    && shouldUseDynamicAgent({
+      chatType: peerKind,
+      config: accountCfg,
+      senderIsAdmin,
+    })
       ? generateAgentId(peerKind, peerId, accountId)
       : null;
 
+  const templateDir = accountCfg?.workspaceTemplate || config?.channels?.wecom?.workspaceTemplate;
   if (targetAgentId) {
-    await ensureDynamicAgentListed(targetAgentId);
+    await ensureDynamicAgentListed(targetAgentId, templateDir);
     logger.debug("[agent-inbound] dynamic agent", { agentId: targetAgentId, peerId });
   }
 

package/wecom/channel-plugin.js

@@ -92,6 +92,11 @@ export const wecomChannelPlugin = {
               description: "Enable per-user/per-group agent isolation",
               default: true,
             },
+            adminBypass: {
+              type: "boolean",
+              description: "When true, adminUsers bypass dynamic agent routing and use the default route",
+              default: false,
+            },
           },
         },
         dm: {
@@ -277,12 +282,20 @@ export const wecomChannelPlugin = {
       // `to` format: "wecom:userid" or "userid".
       const userId = to.replace(/^wecom:/, "");
 
-      // Prefer stream from async context (correct for concurrent processing).
+      // Prefer async-context stream only when it is still writable.
+      // If the context stream already finished (common with concurrent messages),
+      // fall back to the latest recoverable active stream for this user/group.
       const ctx = streamContext.getStore();
-      const streamId = ctx?.streamId ?? resolveRecoverableStream(userId);
+      const ctxStreamId = ctx?.streamId ?? null;
+      const ctxStream = ctxStreamId ? streamManager.getStream(ctxStreamId) : null;
+      const canUseCtxStream = !!(ctxStreamId && ctxStream && !ctxStream.finished);
+      const streamId = canUseCtxStream ? ctxStreamId : resolveRecoverableStream(userId);
+      const streamObj = streamId ? streamManager.getStream(streamId) : null;
+      const hasStream = streamId ? streamManager.hasStream(streamId) : false;
+      const finished = streamObj?.finished ?? true;
 
       // Layer 1: Active stream (normal path)
-      if (streamId && streamManager.hasStream(streamId) && !streamManager.getStream(streamId)?.finished) {
+      if (streamId && hasStream && !finished) {
         logger.debug("Appending outbound text to stream", {
           userId,
           streamId,
@@ -298,6 +311,19 @@ export const wecomChannelPlugin = {
         };
       }
 
+      // Log stream miss details for debugging concurrent-message issues.
+      logger.warn("WeCom sendText: Layer 1 stream miss", {
+        userId,
+        streamId: streamId ?? null,
+        hasStream,
+        finished,
+        hasAsyncContext: !!ctx,
+        ctxStreamId,
+        canUseCtxStream,
+        ctxStreamKey: ctx?.streamKey ?? null,
+        textPreview: text.substring(0, 50),
+      });
+
       // Layer 2: Fallback via response_url
       // response_url is valid for 1 hour and can be used only once.
       // responseUrls is keyed by streamKey (fromUser for DM, chatId for group).
@@ -307,7 +333,7 @@ export const wecomChannelPlugin = {
           const response = await wecomFetch(saved.url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ msgtype: "text", text: { content: text } }),
+            body: JSON.stringify({ msgtype: "markdown", markdown: { content: text } }),
           });
           const responseBody = await response.text().catch(() => "");
           const result = parseResponseUrlResult(response, responseBody);
@@ -395,11 +421,14 @@ export const wecomChannelPlugin = {
     sendMedia: async ({ cfg: _cfg, to, text, mediaUrl, accountId: _accountId }) => {
       const userId = to.replace(/^wecom:/, "");
 
-      // Prefer stream from async context (correct for concurrent processing).
+      // Prefer async-context stream only when it is still writable.
       const ctx = streamContext.getStore();
-      const streamId = ctx?.streamId ?? resolveRecoverableStream(userId);
+      const ctxStreamId = ctx?.streamId ?? null;
+      const ctxStream = ctxStreamId ? streamManager.getStream(ctxStreamId) : null;
+      const canUseCtxStream = !!(ctxStreamId && ctxStream && !ctxStream.finished);
+      const streamId = canUseCtxStream ? ctxStreamId : resolveRecoverableStream(userId);
 
-      if (streamId && streamManager.hasStream(streamId)) {
+      if (streamId && streamManager.hasStream(streamId) && !streamManager.getStream(streamId)?.finished) {
         // Check if mediaUrl is a local path (sandbox: prefix or absolute path)
         const isLocalPath = mediaUrl.startsWith("sandbox:") || mediaUrl.startsWith("/");
 
@@ -720,18 +749,18 @@ export const wecomChannelPlugin = {
         });
       }
 
-      const unregister = registerWebhookTarget({
-        path: account.webhookPath || "/webhooks/wecom",
-        account,
-        config: ctx.cfg,
-      });
-
-      // HTTP routing is handled by the wildcard handler registered in
-      // index.js via api.registerHttpHandler. That handler bypasses gateway
-      // auth, which is required for WeCom webhook callbacks (they carry
-      // msg_signature, not Bearer tokens).
-      const botPath = account.webhookPath || "/webhooks/wecom";
-      logger.info("WeCom Bot webhook path active", { path: botPath });
+      let unregister;
+      const botPath = account.webhookPath;
+      if (botPath) {
+        unregister = registerWebhookTarget({
+          path: botPath,
+          account,
+          config: ctx.cfg,
+        });
+        logger.info("WeCom Bot webhook path active", { path: botPath });
+      } else {
+        logger.debug("No Bot webhook path for this account, skipping", { accountId: account.accountId });
+      }
 
       // Register Agent inbound webhook if agent inbound is fully configured.
       let unregisterAgent;
@@ -773,7 +802,7 @@ export const wecomChannelPlugin = {
           clearTimeout(buf.timer);
         }
         messageBuffers.clear();
-        unregister();
+        if (unregister) unregister();
         if (unregisterAgent) unregisterAgent();
       };
 

package/wecom/http-handler.js

@@ -1,6 +1,7 @@
 import * as crypto from "node:crypto";
 import { logger } from "../logger.js";
 import { streamManager } from "../stream-manager.js";
+import { parseThinkingContent } from "../think-parser.js";
 import { WecomWebhook } from "../webhook.js";
 import { handleAgentInbound } from "./agent-inbound.js";
 import { extractLeadingSlashCommand, isHighPriorityCommand } from "./commands.js";
@@ -151,9 +152,16 @@ async function handleWecomRequest(req, res, targets, query, path) {
       streamManager.createStream(streamId);
       streamManager.appendStream(streamId, THINKING_PLACEHOLDER);
 
-      // Passive reply: return stream id immediately in the sync response.
-      // Include the placeholder so the client displays it right away.
-      const streamResponse = webhook.buildStreamResponse(streamId, THINKING_PLACEHOLDER, false, timestamp, nonce);
+      // Passive reply: return stream id with thinking_content so the WeCom
+      // client shows the collapsible "thinking" UI while the LLM processes.
+      const streamResponse = webhook.buildStreamResponse(
+        streamId,
+        "",
+        false,
+        timestamp,
+        nonce,
+        { thinkingContent: THINKING_PLACEHOLDER },
+      );
 
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(streamResponse);
@@ -266,15 +274,31 @@ async function handleWecomRequest(req, res, targets, query, path) {
         }
       }
 
+      // Parse thinking tags from accumulated content so WeCom can display
+      // the model's reasoning in a collapsible section.
+      const { visibleContent, thinkingContent, isThinking } =
+        parseThinkingContent(stream.content);
+
+      // While the model is still thinking (unclosed <think> tag) and there is
+      // no visible content yet, keep showing the placeholder in thinking_content.
+      const effectiveThinking =
+        thinkingContent || (isThinking ? THINKING_PLACEHOLDER : "");
+
       // Return current stream payload.
       const streamResponse = webhook.buildStreamResponse(
         streamId,
-        stream.content,
+        visibleContent,
         stream.finished,
         timestamp,
         nonce,
-        // Pass msgItem when stream is finished and has images
-        stream.finished && stream.msgItem.length > 0 ? { msgItem: stream.msgItem } : {},
+        {
+          // Pass msgItem only when stream is finished and has images.
+          ...(stream.finished && stream.msgItem.length > 0
+            ? { msgItem: stream.msgItem }
+            : {}),
+          // Include thinking content when available.
+          ...(effectiveThinking ? { thinkingContent: effectiveThinking } : {}),
+        },
       );
 
       res.writeHead(200, { "Content-Type": "application/json" });

package/wecom/inbound-processor.js

@@ -241,12 +241,19 @@ export async function processInboundMessage({
 
   // Compute deterministic agent target for this conversation.
   const targetAgentId =
-    dynamicConfig.enabled && shouldUseDynamicAgent({ chatType: peerKind, config: account.config })
+    dynamicConfig.enabled
+    && shouldUseDynamicAgent({
+      chatType: peerKind,
+      config: account.config,
+      senderIsAdmin,
+    })
       ? generateAgentId(peerKind, peerId, account.accountId)
       : null;
 
+  // Resolve template directory: per-account or global.
+  const templateDir = account.config?.workspaceTemplate || config?.channels?.wecom?.workspaceTemplate;
   if (targetAgentId) {
-    await ensureDynamicAgentListed(targetAgentId);
+    await ensureDynamicAgentListed(targetAgentId, templateDir);
     logger.debug("Using dynamic agent", { agentId: targetAgentId, chatType: peerKind, peerId });
   } else if (senderIsAdmin) {
     logger.debug("Admin user, dynamic agent disabled for this chat type; falling back to default route", {
@@ -436,7 +443,7 @@ export async function processInboundMessage({
           }
           unregisterActiveStream(streamKey, streamId);
         }
-      }, 3000); // 3s grace after last delivery
+      }, 200); // short grace for I/O flush; dispatcher is already done
     };
 
     // Dispatch reply with AI processing.

package/wecom/outbound-delivery.js

@@ -1,5 +1,5 @@
-import { readFile, access, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
 import { logger } from "../logger.js";
 import { streamManager } from "../stream-manager.js";
 import { agentSendText, agentUploadMedia, agentSendMedia } from "./agent-api.js";
@@ -19,10 +19,36 @@ const WECOM_MIN_FILE_SIZE = 5;
  * ~/.openclaw/workspace-{agentId} on the host.  Any path starting with
  * /workspace/ is transparently rewritten when an agentId is available.
  */
+export function resolveWorkspaceHostPathSafe({ workspaceDir, workspacePath }) {
+  const relativePath = String(workspacePath || "").replace(/^\/workspace\/?/, "");
+  if (!relativePath) {
+    return null;
+  }
+
+  const hostPath = resolve(workspaceDir, relativePath);
+  const rel = relative(workspaceDir, hostPath);
+  const escapesWorkspace = rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+  if (escapesWorkspace) {
+    return null;
+  }
+  return hostPath;
+}
+
 function resolveHostPath(filePath, effectiveAgentId) {
   if (effectiveAgentId && filePath.startsWith("/workspace/")) {
-    const relative = filePath.slice("/workspace/".length);
-    const hostPath = join(resolveAgentWorkspaceDirLocal(effectiveAgentId), relative);
+    const workspaceDir = resolveAgentWorkspaceDirLocal(effectiveAgentId);
+    const hostPath = resolveWorkspaceHostPathSafe({
+      workspaceDir,
+      workspacePath: filePath,
+    });
+    if (!hostPath) {
+      logger.warn("Rejected unsafe /workspace/ path outside workspace", {
+        sandbox: filePath,
+        workspaceDir,
+        agentId: effectiveAgentId,
+      });
+      return null;
+    }
     logger.debug("Resolved sandbox path to host path", { sandbox: filePath, host: hostPath });
     return hostPath;
   }
@@ -83,8 +109,8 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
   });
 
   // Handle absolute-path MEDIA lines manually; OpenClaw rejects these paths upstream.
-  // Match both line-start (^MEDIA:) and inline (…MEDIA:) patterns.
-  const mediaRegex = /(?:^|(?<=\s))MEDIA:\s*(.+?)$/gm;
+  // Match only line-start MEDIA directives to align with upstream OpenClaw.
+  const mediaRegex = /^MEDIA:\s*(.+?)$/gm;
   const mediaMatches = [];
   let match;
   while ((match = mediaRegex.exec(text)) !== null) {
@@ -110,6 +136,12 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
     for (const media of mediaMatches) {
       // Resolve /workspace/ sandbox paths to host-side paths.
       const resolvedMediaPath = resolveHostPath(media.path, effectiveAgentId);
+      if (!resolvedMediaPath) {
+        processedText = processedText
+          .replace(media.fullMatch, "⚠️ 检测到不安全的 /workspace/ 路径，已拒绝发送")
+          .trim();
+        continue;
+      }
       const mediaExt = resolvedMediaPath.split(".").pop()?.toLowerCase() || "";
       if (mediaImageExts.has(mediaExt)) {
         // Image: queue for delivery when stream finishes.
@@ -177,6 +209,15 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
       }
       // Resolve /workspace/ sandbox paths to host-side paths.
       absPath = resolveHostPath(absPath, effectiveAgentId);
+      if (!absPath) {
+        const unsafeHint = "⚠️ 检测到不安全的 /workspace/ 路径，已拒绝发送";
+        if (streamId && streamManager.hasStream(streamId)) {
+          streamManager.appendStream(streamId, `\n\n${unsafeHint}`);
+        } else {
+          processedText = processedText ? `${processedText}\n\n${unsafeHint}` : unsafeHint;
+        }
+        continue;
+      }
 
       const isLocal = absPath.startsWith("/");
       const mediaFilename = isLocal ? basename(absPath) : (basename(new URL(mediaPath).pathname) || "file");
@@ -271,97 +312,6 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
     }
   }
 
-  // ──────────────────────────────────────────────────────────────────────────
-  // Auto-detect /workspace/… file paths in LLM reply text.
-  // The sandbox container mounts /workspace → host ~/.openclaw/workspace-{agentId}.
-  // When the LLM mentions a file path like "/workspace/report.pdf", we resolve
-  // the host-side path, verify the file exists, and send it via Agent DM.
-  // ──────────────────────────────────────────────────────────────────────────
-  if (effectiveAgentId && processedText) {
-    // Match /workspace/ paths (non-greedy: stop at whitespace, quotes, backticks,
-    // angle brackets, parentheses, or end of string).
-    const workspacePathRegex = /\/workspace\/[^\s"'`<>()]+/g;
-    const detectedPaths = [];
-    let wpMatch;
-    while ((wpMatch = workspacePathRegex.exec(processedText)) !== null) {
-      const rawPath = wpMatch[0]
-        // Strip trailing punctuation that is likely not part of the filename.
-        .replace(/[.,;:!?。，；：！？）》」』\]]+$/, "");
-      if (rawPath.length > "/workspace/".length) {
-        detectedPaths.push(rawPath);
-      }
-    }
-
-    if (detectedPaths.length > 0) {
-      const workspaceDir = resolveAgentWorkspaceDirLocal(effectiveAgentId);
-      const agentCfgAuto = resolveAgentConfig();
-      const imageExtsAuto = new Set(["jpg", "jpeg", "png", "gif", "bmp", "webp"]);
-
-      for (const wsPath of detectedPaths) {
-        // /workspace/foo.pdf → hostDir/foo.pdf
-        const relativePath = wsPath.replace(/^\/workspace\/?/, "");
-        if (!relativePath) continue;
-        const hostPath = join(workspaceDir, relativePath);
-        const filename = basename(hostPath);
-        const ext = filename.split(".").pop()?.toLowerCase() || "";
-
-        // Skip image files — they are handled by the stream msg_item mechanism.
-        if (imageExtsAuto.has(ext)) continue;
-
-        // Check file existence on host.
-        try {
-          await access(hostPath);
-        } catch {
-          logger.debug("Auto-detect: workspace file not found on host, skipping", {
-            wsPath,
-            hostPath,
-          });
-          continue;
-        }
-
-        // File exists on host — send via Agent DM.
-        if (agentCfgAuto && senderId) {
-          try {
-            const hint = await uploadAndSendFile({
-              hostPath,
-              filename,
-              agent: agentCfgAuto,
-              senderId,
-              streamId,
-            });
-            // Replace the path mention in text with a delivery hint.
-            // Also strip any preceding "MEDIA:" prefix if the LLM wrote "MEDIA:/workspace/…".
-            const escapedPath = wsPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-            const withMediaPrefix = new RegExp(`MEDIA:\\s*${escapedPath}`, "g");
-            if (withMediaPrefix.test(processedText)) {
-              processedText = processedText.replace(withMediaPrefix, hint);
-            } else {
-              processedText = processedText.replace(wsPath, hint);
-            }
-            logger.info("Auto-detect: sent workspace file via Agent DM", {
-              streamId,
-              wsPath,
-              hostPath,
-              filename,
-              senderId,
-            });
-          } catch (autoErr) {
-            processedText = processedText.replace(
-              wsPath,
-              `⚠️ 文件「${filename}」发送失败：${autoErr.message}`,
-            );
-            logger.error("Auto-detect: failed to send workspace file via Agent DM", {
-              streamId,
-              wsPath,
-              hostPath,
-              error: autoErr.message,
-            });
-          }
-        }
-      }
-    }
-  }
-
   // All outbound content is sent via stream updates.
   if (!processedText.trim()) {
     logger.debug("WeCom: empty block after processing, skipping stream update");
@@ -424,7 +374,7 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
         const response = await wecomFetch(saved.url, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ msgtype: "text", text: { content: processedText } }),
+          body: JSON.stringify({ msgtype: "markdown", markdown: { content: processedText } }),
         });
         const responseBody = await response.text().catch(() => "");
         const result = parseResponseUrlResult(response, responseBody);

package/wecom/stream-utils.js

@@ -26,6 +26,12 @@ export function registerActiveStream(streamKey, streamId) {
   activeStreamHistory.set(streamKey, deduped);
   activeStreams.set(streamKey, streamId);
   lastStreamByKey.set(streamKey, streamId);
+  logger.info("registerActiveStream", {
+    streamKey,
+    streamId,
+    historySize: deduped.length,
+    history: deduped,
+  });
 }
 
 export function unregisterActiveStream(streamKey, streamId) {
@@ -38,6 +44,7 @@ export function unregisterActiveStream(streamKey, streamId) {
     if (activeStreams.get(streamKey) === streamId) {
       activeStreams.delete(streamKey);
     }
+    logger.info("unregisterActiveStream (empty history)", { streamKey, streamId });
     return;
   }
 
@@ -45,11 +52,18 @@ export function unregisterActiveStream(streamKey, streamId) {
   if (remaining.length === 0) {
     activeStreamHistory.delete(streamKey);
     activeStreams.delete(streamKey);
+    logger.info("unregisterActiveStream (last stream)", { streamKey, streamId });
     return;
   }
 
   activeStreamHistory.set(streamKey, remaining);
   activeStreams.set(streamKey, remaining[remaining.length - 1]);
+  logger.info("unregisterActiveStream", {
+    streamKey,
+    streamId,
+    remainingSize: remaining.length,
+    remaining,
+  });
 }
 
 export function resolveActiveStream(streamKey) {

package/wecom/workspace-template.js

@@ -36,9 +36,13 @@ export function getWorkspaceTemplateDir(config) {
  * Copy template files into a newly created agent's workspace directory.
  * Only copies files that don't already exist (writeFileIfMissing semantics).
  * Silently skips if workspaceTemplate is not configured or directory is missing.
+ *
+ * @param {string} agentId
+ * @param {object} config - OpenClaw config
+ * @param {string} [overrideTemplateDir] - Optional per-account template directory
  */
-export function seedAgentWorkspace(agentId, config) {
-  const templateDir = getWorkspaceTemplateDir(config);
+export function seedAgentWorkspace(agentId, config, overrideTemplateDir) {
+  const templateDir = overrideTemplateDir || getWorkspaceTemplateDir(config);
   if (!templateDir) {
     return;
   }
@@ -114,7 +118,7 @@ export function upsertAgentIdOnlyEntry(cfg, agentId) {
   return changed;
 }
 
-export async function ensureDynamicAgentListed(agentId) {
+export async function ensureDynamicAgentListed(agentId, templateDir) {
   const normalizedId = String(agentId || "")
     .trim()
     .toLowerCase();
@@ -128,28 +132,22 @@ export async function ensureDynamicAgentListed(agentId) {
     return;
   }
 
-  const queue = getEnsureDynamicAgentWriteQueue()
+  const queue = (getEnsureDynamicAgentWriteQueue() || Promise.resolve())
     .then(async () => {
-      const latestConfig = configRuntime.loadConfig();
-      if (!latestConfig || typeof latestConfig !== "object") {
+      const openclawConfig = getOpenclawConfig();
+      if (!openclawConfig || typeof openclawConfig !== "object") {
         return;
       }
 
-      const changed = upsertAgentIdOnlyEntry(latestConfig, normalizedId);
+      // Upsert into memory only. Writing to config file is dangerous and can wipe user settings.
+      const changed = upsertAgentIdOnlyEntry(openclawConfig, normalizedId);
       if (changed) {
-        await configRuntime.writeConfigFile(latestConfig);
-        logger.info("WeCom: dynamic agent added to agents.list", { agentId: normalizedId });
+        logger.info("WeCom: dynamic agent added to in-memory agents.list", { agentId: normalizedId });
       }
+      
       // Always attempt seeding so recreated/cleaned dynamic agents can recover
-      // template files even when the id already exists in agents.list.
-      seedAgentWorkspace(normalizedId, latestConfig);
-
-      // Keep runtime in-memory config aligned to avoid stale reads in this process.
-      const openclawConfig = getOpenclawConfig();
-      if (openclawConfig && typeof openclawConfig === "object") {
-        upsertAgentIdOnlyEntry(openclawConfig, normalizedId);
-        setOpenclawConfig(openclawConfig);
-      }
+      // template files.
+      seedAgentWorkspace(normalizedId, openclawConfig, templateDir);
 
       getEnsuredDynamicAgentIds().add(normalizedId);
     })