@sunnoy/wecom 2.4.1 → 3.0.0

package/README.md

@@ -69,7 +69,7 @@
 
 ## 前置要求
 
-- 已安装 [OpenClaw](https://github.com/openclaw/openclaw) `2026.3.2+`
+- 已安装 [OpenClaw](https://github.com/openclaw/openclaw) `2026.3.23-2+`
 - 企业微信管理后台权限，可创建 AI 机器人或自建应用
 - **机器人已切换到长连接模式**（参考[官方文档](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)）
 - 运行 OpenClaw 的机器可以出站访问：
@@ -84,6 +84,8 @@ Bot 主链路不需要企业微信反向访问你的 HTTP 回调地址。
 openclaw plugins install @sunnoy/wecom
 ```
 
+> **3.0 兼容性说明：** 从 `3.0.0` 开始，本插件仅支持 OpenClaw `2026.3.23-2+`。旧版 OpenClaw 请继续使用 `2.x`。
+
 > **从官方插件迁移：** 如果之前使用 `openclaw plugins install @wecom/wecom-openclaw-plugin`，请先卸载官方插件再安装本插件。`channels.wecom` 配置字段兼容，无需修改。
 
 ## 从 HTTP 回调迁移
@@ -525,6 +527,10 @@ Webhook 只负责群通知。
 
 2.0 完全采用 WebSocket 长连接，不再使用 HTTP 回调。需要在企业微信后台将机器人切换到[长连接模式](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)。
 
+### Q: 3.0 为什么不能再装在旧 OpenClaw 上？
+
+3.0 开始直接适配 OpenClaw `2026.3.23-2+` 的新版 plugin SDK 导出和媒体/runtime 约定，旧版 core 缺少这些接口。旧环境请固定使用 `2.x`。
+
 ### Q: 之前用的官方插件 `@wecom/wecom-openclaw-plugin`，怎么迁移？
 
 ```bash

package/index.js

@@ -1,5 +1,10 @@
 import { logger } from "./logger.js";
-import { wecomChannelPlugin } from "./wecom/channel-plugin.js";
+import {
+  wecomChannelPlugin,
+  handleSubagentDeliveryTarget,
+  handleSubagentSpawned,
+  handleSubagentEnded,
+} from "./wecom/channel-plugin.js";
 import { createWeComMcpTool } from "./wecom/mcp-tool.js";
 import { createImageStudioTool } from "./wecom/image-studio-tool.js";
 import { resolveQwenImageToolsConfig, wecomPluginConfigSchema } from "./wecom/plugin-config.js";
@@ -7,6 +12,7 @@ import { setOpenclawConfig, setRuntime } from "./wecom/state.js";
 import { buildReplyMediaGuidance } from "./wecom/ws-monitor.js";
 import { listAccountIds, resolveAccount } from "./wecom/accounts.js";
 import { createCallbackHandler } from "./wecom/callback-inbound.js";
+import { prepareWecomMessageToolParams } from "./wecom/outbound-sender-protocol.js";
 
 const plugin = {
   id: "wecom",
@@ -49,6 +55,21 @@ const plugin = {
       const guidance = buildReplyMediaGuidance(api.config, ctx.agentId);
       return { appendSystemContext: guidance };
     });
+
+    api.on("subagent_delivery_target", handleSubagentDeliveryTarget);
+    api.on("subagent_spawned", handleSubagentSpawned);
+    api.on("subagent_ended", handleSubagentEnded);
+
+    api.on("before_tool_call", (event, ctx) => {
+      if (event.toolName !== "message") {
+        return;
+      }
+      const params = prepareWecomMessageToolParams(event.params, ctx.agentId);
+      if (params === event.params) {
+        return;
+      }
+      return { params };
+    });
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "2.4.1",
+    "version": "3.0.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -18,7 +18,7 @@
         "openclaw.plugin.json"
     ],
     "peerDependencies": {
-        "openclaw": "*"
+        "openclaw": "^2026.3.23-2"
     },
     "optionalDependencies": {
         "undici": "^7.0.0"
@@ -60,6 +60,7 @@
     "license": "ISC",
     "dependencies": {
         "@wecom/aibot-node-sdk": "^1.0.3",
-        "file-type": "^21.3.0"
+        "file-type": "^21.3.0",
+        "pinyin-pro": "^3.28.0"
     }
 }

package/wecom/callback-media.js

@@ -13,7 +13,7 @@ import { wecomFetch } from "./http.js";
 import { AGENT_API_ENDPOINTS, CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS } from "./constants.js";
 
 function resolveManagedCallbackMediaDir() {
-  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  const override = process.env.OPENCLAW_STATE_DIR?.trim();
   const stateDir = override || path.join(process.env.HOME || "/tmp", ".openclaw");
   return path.join(stateDir, "media", "wecom");
 }

package/wecom/channel-plugin.js

@@ -3,8 +3,8 @@ import { basename } from "node:path";
 import {
   buildBaseAccountStatusSnapshot,
   buildBaseChannelStatusSummary,
-  formatPairingApproveHint,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/status-helpers";
+import { formatPairingApproveHint } from "openclaw/plugin-sdk/core";
 import { logger } from "../logger.js";
 import { splitTextByByteLimit } from "../utils.js";
 import {
@@ -22,7 +22,7 @@ import { agentSendMedia, agentSendText, agentUploadMedia } from "./agent-api.js"
 import { setConfigProxyUrl, wecomFetch } from "./http.js";
 import { wecomOnboardingAdapter } from "./onboarding.js";
 import { getAccountTelemetry, recordOutboundActivity } from "./runtime-telemetry.js";
-import { getOpenclawConfig, getRuntime, setOpenclawConfig } from "./state.js";
+import { getOpenclawConfig, getRuntime, setChannelRuntime, setOpenclawConfig } from "./state.js";
 import { resolveWecomTarget } from "./target.js";
 import { webhookSendFile, webhookSendImage, webhookSendMarkdown, webhookSendText, webhookUploadFile } from "./webhook-bot.js";
 import { loadOutboundMediaFromUrl as loadOutboundMediaFromUrlCompat } from "./openclaw-compat.js";
@@ -36,6 +36,7 @@ import {
 } from "./constants.js";
 import { uploadAndSendMedia } from "./media-uploader.js";
 import { getExtendedMediaLocalRoots } from "./openclaw-compat.js";
+import { applyOutboundSenderProtocol } from "./outbound-sender-protocol.js";
 import { extractParentAgentId } from "./parent-resolver.js";
 import { sendWsMessage, startWsMonitor } from "./ws-monitor.js";
 import { getWsClient } from "./ws-state.js";
@@ -144,6 +145,7 @@ function applyNetworkConfig(cfg, accountId) {
 
 async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, preparedMedia, replyFormat }) {
   const account = resolveAccount(cfg, accountId);
+  const outboundText = text ? applyOutboundSenderProtocol(text).content : text;
   const raw = account?.config?.webhooks?.[webhookName];
   const url = raw ? (String(raw).startsWith("http") ? String(raw) : `${getWebhookBotSendUrl()}?key=${raw}`) : null;
   if (!url) {
@@ -156,7 +158,7 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
     : (opts) => webhookSendMarkdown(opts);
 
   if (!mediaUrl) {
-    await sendWebhookText({ url, content: text });
+    await sendWebhookText({ url, content: outboundText });
     recordOutboundActivity({ accountId });
     return { channel: CHANNEL_ID, messageId: `wecom-webhook-${Date.now()}` };
   }
@@ -164,8 +166,8 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
   const { buffer, filename, mediaType } =
     preparedMedia ?? (await loadResolvedMedia(mediaUrl, { accountConfig: account?.config }));
 
-  if (text) {
-    await sendWebhookText({ url, content: text });
+  if (outboundText) {
+    await sendWebhookText({ url, content: outboundText });
   }
 
   if (mediaType === "image") {
@@ -186,13 +188,14 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
 async function sendViaAgent({ cfg, accountId, target, text, mediaUrl, preparedMedia, replyFormat }) {
   const account = resolveAccount(cfg, accountId);
   const agent = account?.agentCredentials;
+  const outboundText = text ? applyOutboundSenderProtocol(text).content : text;
   if (!agent) {
     throw new Error("Agent API is not configured for this account");
   }
 
   const effectiveFormat = replyFormat || account?.agentReplyFormat || "markdown";
-  if (text) {
-    for (const chunk of splitTextByByteLimit(text)) {
+  if (outboundText) {
+    for (const chunk of splitTextByByteLimit(outboundText)) {
       await agentSendText({ agent, ...target, text: chunk, format: effectiveFormat });
     }
   }
@@ -619,6 +622,9 @@ export const wecomChannelPlugin = {
   gateway: {
     startAccount: async (ctx) => {
       setOpenclawConfig(ctx.cfg);
+      if (ctx.channelRuntime) {
+        setChannelRuntime(ctx.channelRuntime);
+      }
       logAccountConflicts(ctx.cfg);
 
       const network = ctx.account.config.network ?? {};
@@ -664,55 +670,51 @@ export const wecomChannelPlugin = {
       };
     },
   },
-  hooks: {
-    /**
-     * Ensure announce delivery uses a valid WeCom channel accountId.
-     *
-     * When a dynamic agent (e.g. wecom-yoyo-dm-xxx) spawns a sub-agent,
-     * the announce delivery may reference the dynamic agent ID as accountId.
-     * This hook resolves it to the actual WeCom account (e.g. yoyo) so the
-     * outbound sendText can find valid WS/Agent API credentials.
-     */
-    subagent_delivery_target: async (event, ctx) => {
-      const origin = event.requesterOrigin;
-      if (!origin?.channel || origin.channel !== CHANNEL_ID) return;
-
-      const cfg = ctx?.cfg ?? getOpenclawConfig();
-
-      // Check whether current accountId already resolves to a valid account
-      const currentAccount = resolveAccount(cfg, origin.accountId);
-      if (currentAccount?.enabled) return;
-
-      // Try to extract the base account from a dynamic agent ID
-      const baseId = extractParentAgentId(origin.accountId);
-      if (baseId && baseId !== origin.accountId) {
-        const baseAccount = resolveAccount(cfg, baseId);
-        if (baseAccount?.enabled) {
-          logger.info(`[wecom] subagent_delivery_target: ${origin.accountId} → ${baseId}`);
-          return { origin: { ...origin, accountId: baseId } };
-        }
-      }
+};
 
-      // Fallback to default account
-      const defaultId = resolveDefaultAccountId(cfg);
-      if (defaultId && defaultId !== origin.accountId) {
-        logger.info(`[wecom] subagent_delivery_target: fallback → ${defaultId}`);
-        return { origin: { ...origin, accountId: defaultId } };
-      }
-    },
+/**
+ * Ensure announce delivery uses a valid WeCom channel accountId.
+ *
+ * When a dynamic agent (e.g. wecom-yoyo-dm-xxx) spawns a sub-agent,
+ * the announce delivery may reference the dynamic agent ID as accountId.
+ * This hook resolves it to the actual WeCom account (e.g. yoyo) so the
+ * outbound sendText can find valid WS/Agent API credentials.
+ */
+export async function handleSubagentDeliveryTarget(event, ctx) {
+  const origin = event.requesterOrigin;
+  if (!origin?.channel || origin.channel !== CHANNEL_ID) return;
+
+  const cfg = ctx?.cfg ?? getOpenclawConfig();
+
+  const currentAccount = resolveAccount(cfg, origin.accountId);
+  if (currentAccount?.enabled) return;
+
+  const baseId = extractParentAgentId(origin.accountId);
+  if (baseId && baseId !== origin.accountId) {
+    const baseAccount = resolveAccount(cfg, baseId);
+    if (baseAccount?.enabled) {
+      logger.info(`[wecom] subagent_delivery_target: ${origin.accountId} → ${baseId}`);
+      return { origin: { ...origin, accountId: baseId } };
+    }
+  }
 
-    subagent_spawned: async (event) => {
-      logger.info(
-        `[wecom] subagent spawned: child=${event.childSessionKey} requester=${event.requesterSessionKey}`,
-      );
-    },
+  const defaultId = resolveDefaultAccountId(cfg);
+  if (defaultId && defaultId !== origin.accountId) {
+    logger.info(`[wecom] subagent_delivery_target: fallback → ${defaultId}`);
+    return { origin: { ...origin, accountId: defaultId } };
+  }
+}
 
-    subagent_ended: async (event) => {
-      logger.info(
-        `[wecom] subagent ended: target=${event.targetSessionKey} reason=${event.reason} outcome=${event.outcome}`,
-      );
-    },
-  },
-};
+export async function handleSubagentSpawned(event) {
+  logger.info(
+    `[wecom] subagent spawned: child=${event.childSessionKey} requester=${event.requesterSessionKey}`,
+  );
+}
+
+export async function handleSubagentEnded(event) {
+  logger.info(
+    `[wecom] subagent ended: target=${event.targetSessionKey} reason=${event.reason} outcome=${event.outcome}`,
+  );
+}
 
 export const wecomChannelPluginTesting = {};

package/wecom/onboarding.js

@@ -1,4 +1,4 @@
-import { addWildcardAllowFrom } from "openclaw/plugin-sdk";
+import { addWildcardAllowFrom } from "openclaw/plugin-sdk/setup";
 import { DEFAULT_WS_URL, DEFAULT_ACCOUNT_ID } from "./constants.js";
 import { resolveAccount, updateAccountConfig } from "./accounts.js";
 

package/wecom/openclaw-compat.js

@@ -3,10 +3,8 @@ import { homedir, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { readFile, realpath, stat } from "node:fs/promises";
 
-const sdkReady = import("openclaw/plugin-sdk")
+const sdkReady = import("openclaw/plugin-sdk/media-runtime")
   .then((sdk) => ({
-    loadOutboundMediaFromUrl:
-      typeof sdk.loadOutboundMediaFromUrl === "function" ? sdk.loadOutboundMediaFromUrl.bind(sdk) : undefined,
     detectMime: typeof sdk.detectMime === "function" ? sdk.detectMime.bind(sdk) : undefined,
     getDefaultMediaLocalRoots:
       typeof sdk.getDefaultMediaLocalRoots === "function" ? sdk.getDefaultMediaLocalRoots.bind(sdk) : undefined,
@@ -82,7 +80,7 @@ function normalizeMediaReference(mediaUrl) {
 }
 
 function resolveStateDir() {
-  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  const override = process.env.OPENCLAW_STATE_DIR?.trim();
   if (override) {
     return resolve(resolveUserPath(override));
   }
@@ -137,6 +135,30 @@ function shouldFallbackFromLocalAccessError(error, options) {
   return isLocalMediaAccessError(error) && !hasExplicitMediaRoots(options);
 }
 
+function isPathInsideRoot(filePath, rootPath) {
+  const normalizedRoot = rootPath.endsWith("/") ? rootPath : `${rootPath}/`;
+  return filePath === rootPath || filePath.startsWith(normalizedRoot);
+}
+
+async function assertLocalPathAllowed(filePath, roots) {
+  const canonicalFilePath = await realpath(filePath);
+
+  for (const root of roots) {
+    try {
+      const canonicalRoot = await realpath(root);
+      if (isPathInsideRoot(canonicalFilePath, canonicalRoot)) {
+        return canonicalFilePath;
+      }
+    } catch {
+      if (isPathInsideRoot(canonicalFilePath, root)) {
+        return canonicalFilePath;
+      }
+    }
+  }
+
+  throw new Error(`LocalMediaAccessError: path is not under an allowed directory: ${filePath}`);
+}
+
 async function readLocalMediaFile(filePath, { maxBytes } = {}) {
   const info = await stat(filePath);
   if (!info.isFile()) {
@@ -251,16 +273,18 @@ export async function loadOutboundMediaFromUrl(mediaUrl, options = {}) {
   const normalized = normalizeMediaReference(mediaUrl);
   const filePath = asLocalPath(normalized);
   const localRoots = await getExtendedMediaLocalRoots(options);
-  const sdk = await sdkReady;
+  const enforceLocalRoots = options.includeDefaultMediaLocalRoots === false || hasExplicitMediaRoots(options);
 
   if (filePath) {
+    const allowedFilePath = enforceLocalRoots ? await assertLocalPathAllowed(filePath, localRoots) : filePath;
+
     if (typeof options.runtimeLoadMedia === "function" && localRoots.length > 0) {
       try {
-        const loaded = await options.runtimeLoadMedia(filePath, { localRoots });
+        const loaded = await options.runtimeLoadMedia(allowedFilePath, { localRoots });
         return {
           buffer: loaded.buffer,
           contentType: loaded.contentType || "",
-          fileName: loaded.fileName || basename(filePath) || "file",
+          fileName: loaded.fileName || basename(allowedFilePath) || "file",
         };
       } catch (error) {
         if (!shouldFallbackFromLocalAccessError(error, options)) {
@@ -269,27 +293,7 @@ export async function loadOutboundMediaFromUrl(mediaUrl, options = {}) {
       }
     }
 
-    if (sdk.loadOutboundMediaFromUrl) {
-      try {
-        return await sdk.loadOutboundMediaFromUrl(filePath, {
-          maxBytes: options.maxBytes,
-          mediaLocalRoots: localRoots,
-        });
-      } catch (error) {
-        if (!shouldFallbackFromLocalAccessError(error, options)) {
-          throw error;
-        }
-      }
-    }
-
-    return readLocalMediaFile(filePath, options);
-  }
-
-  if (sdk.loadOutboundMediaFromUrl && !options.fetchImpl) {
-    return sdk.loadOutboundMediaFromUrl(normalized, {
-      maxBytes: options.maxBytes,
-      mediaLocalRoots: localRoots,
-    });
+    return readLocalMediaFile(allowedFilePath, options);
   }
 
   return fetchRemoteMedia(normalized, options);

package/wecom/outbound-sender-protocol.js

@@ -0,0 +1,142 @@
+import { resolveWecomTarget } from "./target.js";
+
+const OUTBOUND_SENDER_PROTOCOL_PATTERN = /^\s*\[\[\s*sender\s*:\s*([^\]\r\n]+?)\s*\]\]\s*(?:\r?\n)?/i;
+
+function sanitizeSenderLabel(value) {
+  return String(value ?? "")
+    .replace(/[\[\]\r\n]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function buildVisibleContent(sender, body) {
+  const normalizedSender = sanitizeSenderLabel(sender);
+  if (!normalizedSender) {
+    return String(body ?? "");
+  }
+
+  const normalizedBody = String(body ?? "").replace(/^\r?\n/, "");
+  if (!normalizedBody.trim()) {
+    return `【sender:${normalizedSender}】`;
+  }
+  if (normalizedBody.includes("\n")) {
+    return `【sender:${normalizedSender}】\n${normalizedBody}`;
+  }
+  return `【sender:${normalizedSender}】${normalizedBody.trimStart()}`;
+}
+
+function resolveDynamicSender(agentId) {
+  const normalized = String(agentId ?? "").trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+
+  const dmMatch = normalized.match(/^wecom-(?:(.+?)-)?dm-(.+)$/);
+  if (dmMatch?.[2]) {
+    return {
+      kind: "user",
+      id: dmMatch[2],
+      label: dmMatch[2],
+    };
+  }
+
+  const groupMatch = normalized.match(/^wecom-(?:(.+?)-)?group-(.+)$/);
+  if (groupMatch?.[2]) {
+    return {
+      kind: "group",
+      id: groupMatch[2],
+      label: `group:${groupMatch[2]}`,
+    };
+  }
+
+  return null;
+}
+
+export function resolveOutboundSenderLabel(agentId) {
+  const sender = resolveDynamicSender(agentId);
+  if (sender?.label) {
+    return sender.label;
+  }
+
+  const normalized = String(agentId ?? "").trim().toLowerCase();
+  return normalized || "main";
+}
+
+export function ensureOutboundSenderProtocol(content, sender) {
+  const raw = String(content ?? "");
+  const normalizedSender = sanitizeSenderLabel(sender);
+  if (!normalizedSender || OUTBOUND_SENDER_PROTOCOL_PATTERN.test(raw)) {
+    return raw;
+  }
+  return raw ? `[[sender:${normalizedSender}]]\n${raw}` : `[[sender:${normalizedSender}]]`;
+}
+
+export function prepareWecomMessageToolParams(params, agentId) {
+  const action = String(params?.action ?? "").trim().toLowerCase();
+  if (action !== "send" && action !== "sendattachment") {
+    return params;
+  }
+
+  const channel = String(params?.channel ?? "").trim().toLowerCase();
+  const sender = resolveDynamicSender(agentId);
+  if ((!channel && !sender) || (channel && channel !== "wecom")) {
+    return params;
+  }
+
+  const target = typeof params?.target === "string" ? params.target.trim() : "";
+  const message = typeof params?.message === "string" ? params.message : "";
+  if (!sender || !target || !message) {
+    return params;
+  }
+
+  const resolvedTarget = resolveWecomTarget(target);
+  const normalizedSenderId = sender.id.toLowerCase();
+  const isSameDirectTarget =
+    sender.kind === "user" &&
+    typeof resolvedTarget?.toUser === "string" &&
+    resolvedTarget.toUser.trim().toLowerCase() === normalizedSenderId;
+  const isSameGroupTarget =
+    sender.kind === "group" &&
+    typeof resolvedTarget?.chatId === "string" &&
+    resolvedTarget.chatId.trim().toLowerCase() === normalizedSenderId;
+  if (isSameDirectTarget || isSameGroupTarget) {
+    return params;
+  }
+
+  const nextMessage = ensureOutboundSenderProtocol(message, sender.label);
+  if (nextMessage === message) {
+    return params;
+  }
+
+  return {
+    ...params,
+    message: nextMessage,
+  };
+}
+
+export function applyOutboundSenderProtocol(content) {
+  const raw = String(content ?? "");
+  const match = raw.match(OUTBOUND_SENDER_PROTOCOL_PATTERN);
+  if (!match) {
+    return {
+      sender: "",
+      content: raw,
+      usedProtocol: false,
+    };
+  }
+
+  const sender = sanitizeSenderLabel(match[1]);
+  if (!sender) {
+    return {
+      sender: "",
+      content: raw,
+      usedProtocol: false,
+    };
+  }
+
+  return {
+    sender,
+    content: buildVisibleContent(sender, raw.slice(match[0].length)),
+    usedProtocol: true,
+  };
+}

package/wecom/state.js

@@ -5,6 +5,7 @@ import { resolveAgentConfigForAccount, resolveDefaultAccountId, resolveAccount }
 const runtimeState = {
   runtime: null,
   openclawConfig: null,
+  channelRuntime: null,
   ensuredDynamicAgentIds: new Set(),
   ensureDynamicAgentWriteQueue: Promise.resolve(),
 };
@@ -23,6 +24,14 @@ export function getRuntime() {
   return runtimeState.runtime;
 }
 
+export function setChannelRuntime(channelRuntime) {
+  runtimeState.channelRuntime = channelRuntime;
+}
+
+export function getChannelRuntime() {
+  return runtimeState.channelRuntime;
+}
+
 export function setOpenclawConfig(config) {
   runtimeState.openclawConfig = config;
 }
@@ -77,6 +86,7 @@ export function resolveWebhookUrl(name, accountId) {
 export function resetStateForTesting() {
   runtimeState.runtime = null;
   runtimeState.openclawConfig = null;
+  runtimeState.channelRuntime = null;
   runtimeState.ensuredDynamicAgentIds = new Set();
   runtimeState.ensureDynamicAgentWriteQueue = Promise.resolve();
   dispatchLocks.clear();

package/wecom/target.js

@@ -7,6 +7,88 @@
  * Supports explicit prefixes (party:, tag:, etc.) and heuristic fallback.
  */
 
+import { readdirSync } from "node:fs";
+import { pinyin } from "pinyin-pro";
+import { resolveStateDir } from "./openclaw-compat.js";
+
+let knownUserIdsCache = {
+  loadedAt: 0,
+  stateDir: "",
+  userIds: [],
+};
+
+function getKnownWecomUserIds() {
+  const now = Date.now();
+  const stateDir = resolveStateDir();
+  if (knownUserIdsCache.stateDir === stateDir && now - knownUserIdsCache.loadedAt < 5_000) {
+    return knownUserIdsCache.userIds;
+  }
+
+  try {
+    const agentDirs = readdirSync(`${stateDir}/agents`, { withFileTypes: true });
+    const userIds = [];
+    for (const entry of agentDirs) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const match = entry.name.match(/^wecom-(?:(.+?)-)?dm-(.+)$/);
+      if (match?.[2]) {
+        userIds.push(match[2].toLowerCase());
+      }
+    }
+    knownUserIdsCache = {
+      loadedAt: now,
+      stateDir,
+      userIds: [...new Set(userIds)],
+    };
+  } catch {
+    knownUserIdsCache = {
+      loadedAt: now,
+      stateDir,
+      userIds: [],
+    };
+  }
+
+  return knownUserIdsCache.userIds;
+}
+
+function transliterateChineseNameToUserId(value) {
+  const collapsed = String(value ?? "").replace(/[\s·•・]/g, "");
+  if (!collapsed || !/^\p{Script=Han}+$/u.test(collapsed)) {
+    return "";
+  }
+
+  return pinyin(collapsed, { toneType: "none", type: "array" }).join("").toLowerCase();
+}
+
+function resolveKnownWecomUserId(value) {
+  const needle = String(value ?? "").trim().toLowerCase();
+  if (!needle) {
+    return "";
+  }
+
+  const candidates = getKnownWecomUserIds();
+  if (candidates.length === 0) {
+    return "";
+  }
+
+  if (candidates.includes(needle)) {
+    return needle;
+  }
+
+  const suffixMatches = candidates.filter((candidate) => candidate.endsWith(needle));
+  if (suffixMatches.length === 1) {
+    return suffixMatches[0];
+  }
+
+  const containsMatches = candidates.filter((candidate) => candidate.includes(needle));
+  if (containsMatches.length === 1) {
+    return containsMatches[0];
+  }
+
+  return "";
+}
+
 /**
  * @param {string|undefined} raw
  * @returns {{ webhook?: string, toUser?: string, toParty?: string, toTag?: string, chatId?: string } | undefined}
@@ -53,6 +135,11 @@ export function resolveWecomTarget(raw) {
     return { toParty: clean };
   }
 
+  const pinyinUserId = transliterateChineseNameToUserId(clean);
+  if (pinyinUserId) {
+    return { toUser: resolveKnownWecomUserId(pinyinUserId) || pinyinUserId };
+  }
+
   // Default: treat as user ID.
-  return { toUser: clean };
+  return { toUser: resolveKnownWecomUserId(clean) || clean };
 }

package/wecom/welcome-messages-file.js

@@ -22,7 +22,7 @@ function resolveUserPath(value) {
 }
 
 function resolveOpenclawStateDir() {
-  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  const override = process.env.OPENCLAW_STATE_DIR?.trim();
   if (override) {
     return resolveUserPath(override);
   }

package/wecom/workspace-template.js

@@ -65,7 +65,6 @@ export function clearTemplateMtimeCache({ agentSeedCache = true } = {}) {
 export function resolveAgentWorkspaceDirLocal(agentId) {
   const stateDir =
     process.env.OPENCLAW_STATE_DIR?.trim() ||
-    process.env.CLAWDBOT_STATE_DIR?.trim() ||
     join(process.env.HOME || "/root", ".openclaw");
   return join(stateDir, `workspace-${agentId}`);
 }

package/wecom/ws-monitor.js

@@ -7,6 +7,7 @@ import { WSClient, generateReqId } from "@wecom/aibot-node-sdk";
 import { uploadAndSendMedia, buildMediaErrorSummary } from "./media-uploader.js";
 import { createPersistentReqIdStore } from "./reqid-store.js";
 import { agentSendMedia, agentSendText, agentUploadMedia } from "./agent-api.js";
+import { applyOutboundSenderProtocol, resolveOutboundSenderLabel } from "./outbound-sender-protocol.js";
 import { logger } from "../logger.js";
 import { normalizeThinkingTags } from "../think-parser.js";
 import { MessageDeduplicator } from "../utils.js";
@@ -309,7 +310,7 @@ function resolveUserPath(value) {
 }
 
 function resolveStateDir() {
-  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  const override = process.env.OPENCLAW_STATE_DIR?.trim();
   if (override) {
     return resolveUserPath(override);
   }
@@ -418,6 +419,7 @@ function buildReplyMediaGuidance(config, agentId) {
   const browserMediaDir = path.join(resolveStateDir(), "media", "browser");
   const configuredRoots = resolveConfiguredReplyMediaLocalRoots(config);
   const qwenImageToolsConfig = config?.plugins?.entries?.wecom?.config?.qwenImageTools;
+  const senderLabel = resolveOutboundSenderLabel(agentId);
   const guidance = [
     WECOM_REPLY_MEDIA_GUIDANCE_HEADER,
     `Local reply files are allowed only under the current workspace: ${workspaceDir}`,
@@ -432,6 +434,10 @@ function buildReplyMediaGuidance(config, agentId) {
     "CRITICAL: If a tool already returned a path prefixed with FILE: (e.g. FILE:/abs/path.pdf), keep the FILE: prefix exactly as-is. Do NOT change it to MEDIA:.",
     "Each directive MUST be on its own line with no other text on that line.",
     "The plugin will automatically send the media to the user.",
+    "[WeCom cross-chat send rule]",
+    `If you proactively send a WeCom message to a different user/group via message.send, prepend this exact hidden header on the first line: [[sender:${senderLabel}]]`,
+    `Example cross-chat content: [[sender:${senderLabel}]]\\n你好`,
+    "Use the sender header only for proactive cross-chat sends. Do NOT add it when replying in the current WeCom chat.",
   ];
 
   if (configuredRoots.length > 0) {
@@ -455,6 +461,13 @@ function buildReplyMediaGuidance(config, agentId) {
   }
 
   guidance.push("Never reference any other host path.");
+
+  guidance.push(
+    "[WeCom visible text rule]",
+    "ALL text you want the user to see MUST be wrapped in <final> tags — this includes short status messages before tool calls (e.g. <final>正在查询，稍等～</final>).",
+    "Text outside <final> tags is silently discarded and never delivered to the WeCom chat.",
+  );
+
   return guidance.join("\n");
 }
 
@@ -498,9 +511,38 @@ function normalizeReplyMediaUrlForLoad(mediaUrl, config, agentId) {
 }
 
 function buildBodyForAgent(body, config, agentId) {
-  // Guidance is now injected via before_prompt_build hook into system prompt.
-  // Keep buildBodyForAgent as a plain passthrough for the user message body.
-  return typeof body === "string" && body.length > 0 ? body : "";
+  if (typeof body !== "string" || body.length === 0) {
+    return "";
+  }
+
+  const senderLabel = resolveOutboundSenderLabel(agentId);
+  const inlineRules = [
+    "[WeCom agent rules]",
+    "If proactively sending to a different WeCom user/group via message.send, prepend this exact hidden header on the first line:",
+    `[[sender:${senderLabel}]]`,
+    `Example: [[sender:${senderLabel}]]\\n你好`,
+    "Do NOT add that header when replying in the current WeCom chat.",
+    "To send files back to the current WeCom chat, do NOT use message.send or message.sendAttachment; emit MEDIA:/... or FILE:/... directives on their own lines instead.",
+  ].join("\n");
+
+  return `${inlineRules}\n\n${body}`;
+}
+
+function shouldUseMarkdownForActiveSend(content) {
+  const text = String(content ?? "").trim();
+  if (!text) {
+    return true;
+  }
+
+  return true;
+}
+
+function buildWsActiveSendBody(content) {
+  const text = String(content ?? "");
+  return {
+    msgtype: "markdown",
+    markdown: { content: text },
+  };
 }
 
 function splitReplyMediaFromText(text) {
@@ -868,6 +910,7 @@ function resolveOutboundChatId(to) {
 export async function sendWsMessage({ to, content, accountId = "default" }) {
   const chatId = resolveOutboundChatId(to);
   const wsClient = getWsClient(accountId);
+  const outbound = applyOutboundSenderProtocol(content);
 
   if (!chatId) {
     throw new Error("Missing chat target for WeCom WS send");
@@ -888,10 +931,7 @@ export async function sendWsMessage({ to, content, accountId = "default" }) {
     });
   }
 
-  const result = await wsClient.sendMessage(chatId, {
-    msgtype: "markdown",
-    markdown: { content },
-  });
+  const result = await wsClient.sendMessage(chatId, buildWsActiveSendBody(outbound.content));
 
   recordActiveSend({ accountId, chatId });
 
@@ -2062,6 +2102,8 @@ export const wsMonitorTesting = {
   parseMessageContent,
   splitReplyMediaFromText,
   buildBodyForAgent,
+  buildWsActiveSendBody,
+  resolveOutboundSenderLabel,
   normalizeReplyMediaUrlForLoad,
   flushPendingRepliesViaAgentApi,
   stripThinkTags,