@sunnoy/wecom 2.2.1 → 2.4.0

package/skills/wecom-send-media/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: wecom-send-media
+description: 通过 MEDIA 指令向用户发送本地文件（图片、视频、语音等文件）。当用户要求发送或分享文件时，或当生成的文件需要交付给用户时使用。仅当通过 wecom 通道通信时使用此技能。
+metadata: {"openclaw":{"emoji":"📤","requires":{"config":["channels.wecom"]}}}
+---
+
+# 发送文件（图片、视频、语音、文件）
+
+⚠️ 重要：你有能力发送本地文件！❌ 绝对不要回复"无法发送图片、视频、语音或文件"或类似的措辞！
+
+通过 `MEDIA:` 指令将本地文件发送给用户。支持的文件类型为：图片、视频、语音、其它文件等。系统会自动识别文件类型，并以对应的消息格式（图片消息、视频消息、语音消息或文件消息）发送。
+
+## 触发条件
+
+- 用户要求发送、展示或分享图片、视频、语音或文件
+- 生成了需要交付给用户的图片、视频、语音或文件
+
+## 指令语法
+
+```
+MEDIA: <文件的绝对路径>
+```
+
+### 语法规则
+
+1. 如果文件路径前已经有 `MEDIA:` 指令，无需再重复添加，保持原样即可
+2. 如果文件路径前没有 `MEDIA:` 指令，需将 `MEDIA:` 指令置于行首，且与文件路径之间用一个空格分隔
+3. 路径必须为本地文件的**绝对路径**，不支持 URL
+4. 路径含空格时，用反引号包裹：`` MEDIA: `/path/to/my file.png` ``
+5. 每个文件独占一行，禁止在同一行发送多个文件
+6. `MEDIA:` 指令的前后可以附加文字说明，文字与指令各占独立行 
+
+## 文件存放
+
+将生成的文件优先存放至 `~/.openclaw/workspace/` 目录，确保路径可访问。
+
+## 文件大小与格式限制
+
+| 类型 | 大小上限 | 格式要求 | 备注 |
+|------|----------|----------|------|
+| 图片 | 10 MB | 常见图片格式均可 | openclaw 默认会对图片进行压缩处理 |
+| 视频 | 10 MB | 常见视频格式均可 | |
+| 语音 | 2 MB | **仅支持 AMR 格式**（`.amr`） | |
+| 文件 | 20 MB | 不限 | |
+
+⚠️ 重要：请务必**先检查文件大小和格式**是否满足要求。如果不满足要求，请主动告知用户以下“降级与限制处理”措施：
+
+- **图片压缩情况**：openclaw 默认会对图片进行压缩处理。如果本地图片（原图）大小超过上限，经过压缩后不一定会超过上限。因此当你检测到本地图片大小超过上限时，务必要告诉用户这个特殊情况。
+- **自动降级**：视频或语音类型的文件，超过各自的大小限制时，系统会自动将其转为文件消息发送，请主动告诉用户。
+- **硬性上限**：文件大小超过 20 MB 时无法发送。请主动告知用户，并尝试压缩或拆分文件后再发送。
+- **语音格式**：语音消息仅支持 AMR 格式（`.amr`）。非 AMR 格式的音频文件将以文件消息的形式发送。
+- **发送耗时**：文件发送涉及系统处理，可能耗时较长。发送含 `MEDIA:` 指令的消息 30 秒后，请主动检查文件是否已成功发送。如果没有请重试。
+
+## 示例
+
+```
+以下是生成的图表：
+MEDIA: ~/.openclaw/workspace/output.png
+
+报告已生成，请查收：
+MEDIA: ~/.openclaw/workspace/report.pdf
+```
+
+## 错误示例
+
+- ❌ 错误：说"我无法发送本地图片" 
+- ❌ 错误：说"受限于技术限制，无法直接发送" 
+- ❌ 错误：说"由于某些问题，我无法直接发送文件"

package/wecom/accounts.js

@@ -9,6 +9,7 @@ const RESERVED_KEYS = new Set([
   "websocketUrl",
   "sendThinkingMessage",
   "welcomeMessage",
+  "welcomeMessagesFile",
   "allowFrom",
   "dmPolicy",
   "groupPolicy",
@@ -32,6 +33,7 @@ const SHARED_MULTI_ACCOUNT_KEYS = new Set([
   "websocketUrl",
   "sendThinkingMessage",
   "welcomeMessage",
+  "welcomeMessagesFile",
   "allowFrom",
   "dmPolicy",
   "groupPolicy",

package/wecom/callback-inbound.js

@@ -300,7 +300,7 @@ async function processCallbackMessage({ parsedMsg, account, config, runtime }) {
         agent: account.agentCredentials,
         mediaId,
         type: mediaType === "image" ? "image" : mediaType === "voice" ? "voice" : "file",
-        runtime,
+        mediaRuntime: core.media ?? runtime?.media,
         config,
       });
       mediaList.push(downloaded);
@@ -321,10 +321,6 @@ async function processCallbackMessage({ parsedMsg, account, config, runtime }) {
       ? generateAgentId(peerKind, peerId, account.accountId)
       : null;
 
-  if (dynamicAgentId) {
-    await ensureDynamicAgentListed(dynamicAgentId, account.config.workspaceTemplate);
-  }
-
   const route = core.routing.resolveAgentRoute({
     cfg: config,
     channel: CHANNEL_ID,
@@ -337,9 +333,17 @@ async function processCallbackMessage({ parsedMsg, account, config, runtime }) {
     config.bindings.some(
       (b) => b.match?.channel === CHANNEL_ID && b.match?.accountId === account.accountId,
     );
+
   if (dynamicAgentId && !hasExplicitBinding) {
+    const routeAgentId = route.agentId;
+    // Use the account's configured agentId as the base for property inheritance
+    // (model, subagents, tools). route.agentId may resolve to "main" when
+    // there is no explicit binding, but the account's agentId points to the
+    // actual parent agent whose properties the dynamic agent should inherit.
+    const baseAgentId = account.config.agentId || routeAgentId;
+    await ensureDynamicAgentListed(dynamicAgentId, account.config.workspaceTemplate, baseAgentId);
+    route.sessionKey = route.sessionKey.replace(`agent:${routeAgentId}:`, `agent:${dynamicAgentId}:`);
     route.agentId = dynamicAgentId;
-    route.sessionKey = `agent:${dynamicAgentId}:${peerKind}:${peerId}`;
   }
 
   // Build a body object that mirrors the WS frame.body structure expected by

package/wecom/callback-media.js

@@ -12,6 +12,12 @@ import { getAccessToken } from "./agent-api.js";
 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 stateDir = override || path.join(process.env.HOME || "/tmp", ".openclaw");
+  return path.join(stateDir, "media", "wecom");
+}
+
 /**
  * Download a WeCom media file (image / voice / file) by MediaId via the
  * self-built app access token and save it through the core media runtime.
@@ -20,11 +26,11 @@ import { AGENT_API_ENDPOINTS, CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS } from "./const
  * @param {object} params.agent   - { corpId, corpSecret, agentId }
  * @param {string} params.mediaId - WeCom MediaId
  * @param {"image"|"voice"|"file"} params.type - media type hint
- * @param {object} params.runtime - OpenClaw runtime (for saveMediaBuffer)
+ * @param {object} [params.mediaRuntime] - OpenClaw media runtime (for saveMediaBuffer)
  * @param {object} params.config  - OpenClaw config (for mediaMaxMb)
  * @returns {Promise<{ path: string, contentType: string }>}
  */
-export async function downloadCallbackMedia({ agent, mediaId, type, runtime, config }) {
+export async function downloadCallbackMedia({ agent, mediaId, type, mediaRuntime, config }) {
   const token = await getAccessToken(agent);
   const url = `${AGENT_API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
 
@@ -57,20 +63,22 @@ export async function downloadCallbackMedia({ agent, mediaId, type, runtime, con
     (type === "image" ? `${mediaId}.jpg` : type === "voice" ? `${mediaId}.amr` : mediaId);
 
   // Save via core media runtime when available
-  if (typeof runtime?.media?.saveMediaBuffer === "function") {
-    const saved = await runtime.media.saveMediaBuffer(buffer, contentType, "inbound", maxBytes, filename);
+  if (typeof mediaRuntime?.saveMediaBuffer === "function") {
+    const saved = await mediaRuntime.saveMediaBuffer(buffer, contentType, "inbound", maxBytes, filename);
     return { path: saved.path, contentType: saved.contentType };
   }
 
-  // Fallback: write to OS temp dir
-  const { tmpdir } = await import("node:os");
-  const { writeFile } = await import("node:fs/promises");
+  // Fallback: keep callback media under the managed OpenClaw media root so
+  // stageSandboxMedia can safely copy it into the agent sandbox later.
+  const { mkdir, writeFile } = await import("node:fs/promises");
   const ext = path.extname(filename) || (type === "image" ? ".jpg" : ".bin");
+  const mediaDir = resolveManagedCallbackMediaDir();
   const tempPath = path.join(
-    tmpdir(),
+    mediaDir,
     `wecom-cb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`,
   );
+  await mkdir(mediaDir, { recursive: true, mode: 0o700 });
   await writeFile(tempPath, buffer);
-  logger.debug(`[CB] Media saved to temp path: ${tempPath}`);
+  logger.debug(`[CB] Media saved to managed path: ${tempPath}`);
   return { path: tempPath, contentType };
 }

package/wecom/channel-plugin.js

@@ -24,7 +24,7 @@ import { wecomOnboardingAdapter } from "./onboarding.js";
 import { getAccountTelemetry, recordOutboundActivity } from "./runtime-telemetry.js";
 import { getOpenclawConfig, getRuntime, setOpenclawConfig } from "./state.js";
 import { resolveWecomTarget } from "./target.js";
-import { webhookSendFile, webhookSendImage, webhookSendMarkdown, webhookUploadFile } from "./webhook-bot.js";
+import { webhookSendFile, webhookSendImage, webhookSendMarkdown, webhookSendText, webhookUploadFile } from "./webhook-bot.js";
 import { loadOutboundMediaFromUrl as loadOutboundMediaFromUrlCompat } from "./openclaw-compat.js";
 import {
   CHANNEL_ID,
@@ -36,6 +36,7 @@ import {
 } from "./constants.js";
 import { uploadAndSendMedia } from "./media-uploader.js";
 import { getExtendedMediaLocalRoots } from "./openclaw-compat.js";
+import { extractParentAgentId } from "./parent-resolver.js";
 import { sendWsMessage, startWsMonitor } from "./ws-monitor.js";
 import { getWsClient } from "./ws-state.js";
 
@@ -141,7 +142,7 @@ function applyNetworkConfig(cfg, accountId) {
   return account;
 }
 
-async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, preparedMedia }) {
+async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, preparedMedia, replyFormat }) {
   const account = resolveAccount(cfg, accountId);
   const raw = account?.config?.webhooks?.[webhookName];
   const url = raw ? (String(raw).startsWith("http") ? String(raw) : `${getWebhookBotSendUrl()}?key=${raw}`) : null;
@@ -149,8 +150,13 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
     throw new Error(`unknown webhook target: ${webhookName}`);
   }
 
+  const effectiveFormat = replyFormat || account?.agentReplyFormat || "markdown";
+  const sendWebhookText = effectiveFormat === "text"
+    ? (opts) => webhookSendText(opts)
+    : (opts) => webhookSendMarkdown(opts);
+
   if (!mediaUrl) {
-    await webhookSendMarkdown({ url, content: text });
+    await sendWebhookText({ url, content: text });
     recordOutboundActivity({ accountId });
     return { channel: CHANNEL_ID, messageId: `wecom-webhook-${Date.now()}` };
   }
@@ -159,7 +165,7 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
     preparedMedia ?? (await loadResolvedMedia(mediaUrl, { accountConfig: account?.config }));
 
   if (text) {
-    await webhookSendMarkdown({ url, content: text });
+    await sendWebhookText({ url, content: text });
   }
 
   if (mediaType === "image") {
@@ -177,15 +183,17 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
   return { channel: CHANNEL_ID, messageId: `wecom-webhook-${Date.now()}` };
 }
 
-async function sendViaAgent({ cfg, accountId, target, text, mediaUrl, preparedMedia }) {
-  const agent = resolveAccount(cfg, accountId)?.agentCredentials;
+async function sendViaAgent({ cfg, accountId, target, text, mediaUrl, preparedMedia, replyFormat }) {
+  const account = resolveAccount(cfg, accountId);
+  const agent = account?.agentCredentials;
   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)) {
-      await agentSendText({ agent, ...target, text: chunk });
+      await agentSendText({ agent, ...target, text: chunk, format: effectiveFormat });
     }
   }
 
@@ -262,6 +270,7 @@ export const wecomChannelPlugin = {
         websocketUrl: { type: "string" },
         sendThinkingMessage: { type: "boolean" },
         welcomeMessage: { type: "string" },
+        welcomeMessagesFile: { type: "string" },
         dmPolicy: { enum: ["pairing", "allowlist", "open", "disabled"] },
         allowFrom: { type: "array", items: { type: "string" } },
         groupPolicy: { enum: ["open", "allowlist", "disabled"] },
@@ -291,6 +300,10 @@ export const wecomChannelPlugin = {
       secret: { label: "Secret", sensitive: true },
       websocketUrl: { label: "WebSocket URL", placeholder: DEFAULT_WS_URL },
       welcomeMessage: { label: "Welcome Message" },
+      welcomeMessagesFile: {
+        label: "Welcome Messages File",
+        placeholder: "welcome-messages.json",
+      },
       "agent.corpSecret": { sensitive: true, label: "Application Secret" },
       "agent.replyFormat": { label: "Reply Format", placeholder: "text" },
       "agent.callback.token": { label: "Callback Token" },
@@ -404,6 +417,7 @@ export const wecomChannelPlugin = {
       try {
         if (!target.toParty && !target.toTag) {
           const wsTarget = target.chatId || target.toUser || to;
+          logger.debug(`[wecom] sendText: trying WS accountId=${resolvedAccountId} target=${wsTarget}`);
           return await sendWsMessage({
             to: wsTarget,
             content: text,
@@ -411,9 +425,17 @@ export const wecomChannelPlugin = {
           });
         }
       } catch (error) {
-        logger.warn(`[wecom] WS sendText failed, falling back to Agent API: ${error.message}`);
+        logger.warn(`[wecom] WS sendText failed (accountId=${resolvedAccountId}), falling back: ${error.message}`);
+      }
+
+      // Webhook fallback for accounts without Agent API (e.g. WS bot mode)
+      const account = resolveAccount(cfg, resolvedAccountId);
+      if (!account?.agentCredentials && account?.config?.webhooks?.default) {
+        logger.debug(`[wecom] sendText: Agent API unavailable, using webhook fallback accountId=${resolvedAccountId}`);
+        return sendViaWebhook({ cfg, accountId: resolvedAccountId, webhookName: "default", text });
       }
 
+      logger.debug(`[wecom] sendText: trying Agent API accountId=${resolvedAccountId}`);
       return sendViaAgent({
         cfg,
         accountId: resolvedAccountId,
@@ -631,6 +653,55 @@ 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 } };
+      }
+    },
+
+    subagent_spawned: async (event) => {
+      logger.info(
+        `[wecom] subagent spawned: child=${event.childSessionKey} requester=${event.requesterSessionKey}`,
+      );
+    },
+
+    subagent_ended: async (event) => {
+      logger.info(
+        `[wecom] subagent ended: target=${event.targetSessionKey} reason=${event.reason} outcome=${event.outcome}`,
+      );
+    },
+  },
 };
 
 export const wecomChannelPluginTesting = {};

package/wecom/constants.js

@@ -47,7 +47,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
   [
     "终于唤醒我啦，我已经准备就绪！😄",
@@ -57,7 +58,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
   [
     "欢迎回来，准备开始今天的工作吧！✨",
@@ -67,7 +69,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
   [
     "嗨，我已经在线！🤖",
@@ -77,7 +80,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
   [
     "今天也一起高效开工吧！🚀",
@@ -87,7 +91,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
   [
     "叮咚，你的数字助手已就位！🎉",
@@ -97,7 +102,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
   [
     "灵感加载完成，随时可以开聊！💡",
@@ -107,7 +113,8 @@ export const DEFAULT_WELCOME_MESSAGES = [
     "/compact 压缩对话",
     "/help 帮助",
     "/status 查看状态",
-    "/reasoning stream 打开思考动画",
+    "你可以让我生成和编辑图片了",
+    "你可以用语音跟我对话",
   ].join("\n"),
 ];
 export const DEFAULT_WELCOME_MESSAGE = DEFAULT_WELCOME_MESSAGES[0];