@marshulll/openclaw-wecom 0.1.27 → 0.1.28

package/README.en.md

@@ -96,7 +96,7 @@ Install guide: `docs/INSTALL.md`
   - Example: `/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - Natural language also works: "send me this file image-xxx.jpg" (default match in `media.tempDir`)
   - Search scope keywords: `桌面` → `~/Desktop`, `下载` → `~/Downloads`, `临时` → `media.tempDir`
-  - If multiple matches are found, a list will be returned for confirmation
+  - If multiple matches are found, a list will be returned for confirmation; reply "more" to paginate
 
 ## Proactive send (App mode)
 Push endpoint path: `{webhookPath}/push` (e.g. `/wecom/app/push`).
@@ -137,5 +137,6 @@ Media (file/image/voice/video): use `mediaUrl` or `mediaBase64`. You can also se
 - Dev doc: `docs/TECHNICAL.md`
 - Install: `docs/INSTALL.md`
 - Examples: `docs/wecom.config.example.json` / `docs/wecom.config.full.example.json`
+- Testing: `docs/TESTING.md`
 
 Recommendation: use **separate webhookPath** for Bot and App (e.g. `/wecom/bot` and `/wecom/app`) for clearer debugging and fewer callback mix-ups.

package/README.md

@@ -98,7 +98,7 @@ openclaw gateway restart
   - 示例：`/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - 也支持自然语言：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
   - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
-  - 多文件会先返回列表，回复“全部”或序号再发送
+  - 多文件会先返回列表，回复“全部”或序号再发送；回复“更多”可翻页
 
 ## 主动消息（App 模式）
 主动推送接口路径为：`{webhookPath}/push`（例如 `/wecom/app/push`）。
@@ -139,3 +139,4 @@ curl -X POST "https://你的域名/wecom/app/push" \
 - 开发文档：`docs/TECHNICAL.md`
 - 安装配置：`docs/INSTALL.md`
 - 配置示例：`docs/wecom.config.example.json` / `docs/wecom.config.full.example.json`
+- 测试清单：`docs/TESTING.md`

package/README.zh.md

@@ -98,7 +98,7 @@ openclaw gateway restart
   - 示例：`/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - 也支持自然语言：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
   - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
-  - 多文件会先返回列表，回复“全部”或序号再发送
+  - 多文件会先返回列表，回复“全部”或序号再发送；回复“更多”可翻页
 
 ## 主动消息（App 模式）
 主动推送接口路径为：`{webhookPath}/push`（例如 `/wecom/app/push`）。
@@ -139,3 +139,4 @@ curl -X POST "https://你的域名/wecom/app/push" \
 - 开发文档：`docs/TECHNICAL.md`
 - 安装配置：`docs/INSTALL.md`
 - 配置示例：`docs/wecom.config.example.json` / `docs/wecom.config.full.example.json`
+- 测试清单：`docs/TESTING.md`

package/docs/INSTALL.md

@@ -134,7 +134,7 @@ openclaw gateway restart
 - 目录会自动打包为 zip 再发送
 - 自然语言也可触发：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
   - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
-  - 如匹配多个文件，会返回列表让你确认（回复“全部”或序号）
+  - 如匹配多个文件，会返回列表让你确认（回复“全部”或序号；回复“更多”翻页）
 
 示例：
 ```

package/docs/TESTING.md

@@ -0,0 +1,30 @@
+# 测试清单（手动）
+
+> 用于快速回归核对，不要求自动化。
+
+## Bot 模式（/wecom/bot）
+- 文本：收到文本后能正常回复
+- 图片：能识别/描述（如开启视觉）或至少回复“已收到图片”
+- 语音：如有识别文本则直接处理，否则走语音文件
+- 视频：能返回视频概述（启用 `media.auto.video` 时）
+- 文件：提示已保存路径并可用 Read 工具读取
+
+## App 模式（/wecom/app）
+- 文本：正常回复
+- 图片/语音/视频/文件：同上，确认保存路径与识别结果
+- 群聊：`chatId` 有效，能在群聊回复
+
+## /sendfile（App 模式）
+- 单文件绝对路径发送
+- 多文件路径发送（含空格路径）
+- 目录自动打包 zip
+- 自然语言：唯一命中直接发送，多命中返回列表，回复“全部/序号”生效
+- 多页列表：回复“更多”可翻页
+
+## 主动推送（App 模式）
+- `/wecom/app/push` 文本
+- `/wecom/app/push` 媒体（file/image/voice/video）
+
+## 大文件与异常
+- 超过 `media.maxBytes` 的媒体会提示“过大”
+- 未配置 App 凭据时，Bot 媒体提示更明确

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshulll/openclaw-wecom",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "type": "module",
   "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
   "author": "OpenClaw",
@@ -56,6 +56,7 @@
   "files": [
     "wecom/**",
     "docs/INSTALL.md",
+    "docs/TESTING.md",
     "docs/wecom.config.example.json",
     "docs/wecom.config.full.example.json",
     "openclaw.plugin.json",

package/wecom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshulll/openclaw-wecom",
-  "version": "0.1.5",
+  "version": "0.1.28",
   "type": "module",
   "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
   "author": "OpenClaw",
@@ -41,5 +41,5 @@
     "channel",
     "plugin"
   ],
-  "license": "ISC"
+  "license": "MIT"
 }

package/wecom/src/media-utils.ts

@@ -0,0 +1,73 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { WecomWebhookTarget } from "./monitor.js";
+
+const cleanupExecuted = new Set<string>();
+
+export function resolveExtFromContentType(contentType: string, fallback: string): string {
+  if (!contentType) return fallback;
+  if (contentType.includes("png")) return "png";
+  if (contentType.includes("gif")) return "gif";
+  if (contentType.includes("jpeg") || contentType.includes("jpg")) return "jpg";
+  if (contentType.includes("mp4")) return "mp4";
+  if (contentType.includes("amr")) return "amr";
+  if (contentType.includes("wav")) return "wav";
+  if (contentType.includes("mp3")) return "mp3";
+  return fallback;
+}
+
+export async function cleanupMediaDir(
+  dir: string,
+  retentionHours?: number,
+  cleanupOnStart?: boolean,
+): Promise<void> {
+  if (cleanupOnStart === false) return;
+  if (!retentionHours || retentionHours <= 0) return;
+  if (cleanupExecuted.has(dir)) return;
+  cleanupExecuted.add(dir);
+  const cutoff = Date.now() - retentionHours * 3600 * 1000;
+  try {
+    const entries = await readdir(dir);
+    await Promise.all(entries.map(async (entry) => {
+      const full = join(dir, entry);
+      try {
+        const info = await stat(full);
+        if (info.isFile() && info.mtimeMs < cutoff) {
+          await rm(full, { force: true });
+        }
+      } catch {
+        // ignore
+      }
+    }));
+  } catch {
+    // ignore
+  }
+}
+
+export function resolveMediaTempDir(target: WecomWebhookTarget): string {
+  return target.account.config.media?.tempDir?.trim()
+    || join(tmpdir(), "openclaw-wecom");
+}
+
+export function resolveMediaMaxBytes(target: WecomWebhookTarget): number | undefined {
+  const maxBytes = target.account.config.media?.maxBytes;
+  return typeof maxBytes === "number" && maxBytes > 0 ? maxBytes : undefined;
+}
+
+export function resolveMediaRetentionMs(target: WecomWebhookTarget): number | undefined {
+  const hours = target.account.config.media?.retentionHours;
+  return typeof hours === "number" && hours > 0 ? hours * 3600 * 1000 : undefined;
+}
+
+export function sanitizeFilename(name: string, fallback: string): string {
+  const base = name.split(/[/\\\\]/).pop() ?? "";
+  const trimmed = base.trim();
+  const safe = trimmed
+    .replace(/[^\w.\-() ]+/g, "_")
+    .replace(/\s+/g, " ")
+    .trim();
+  const finalName = safe.slice(0, 120);
+  return finalName || fallback;
+}

package/wecom/src/wecom-api.ts

@@ -61,6 +61,7 @@ class RateLimiter {
 
 const accessTokenCaches = new Map<string, WecomTokenState>();
 const apiLimiter = new RateLimiter({ maxConcurrent: 3, minInterval: 200 });
+export const MEDIA_TOO_LARGE_ERROR = "MEDIA_TOO_LARGE";
 
 function ensureAppConfig(account: ResolvedWecomAccount): { corpId: string; corpSecret: string; agentId: number } {
   const corpId = account.corpId ?? "";
@@ -106,6 +107,23 @@ async function fetchWithRetry(account: ResolvedWecomAccount, input: RequestInfo
   throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
 }
 
+function resolveContentLength(res: Response): number | null {
+  const raw = res.headers.get("content-length");
+  if (!raw) return null;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function ensureNotTooLarge(res: Response, maxBytes?: number): void {
+  if (!maxBytes || maxBytes <= 0) return;
+  const length = resolveContentLength(res);
+  if (length && length > maxBytes) {
+    const err = new Error(`${MEDIA_TOO_LARGE_ERROR}: content-length ${length} > limit ${maxBytes}`);
+    (err as { code?: string }).code = MEDIA_TOO_LARGE_ERROR;
+    throw err;
+  }
+}
+
 export async function getWecomAccessToken(account: ResolvedWecomAccount): Promise<string> {
   const { corpId, corpSecret } = ensureAppConfig(account);
   const cacheKey = corpId;
@@ -335,8 +353,9 @@ export async function sendWecomFile(params: {
 export async function downloadWecomMedia(params: {
   account: ResolvedWecomAccount;
   mediaId: string;
+  maxBytes?: number;
 }): Promise<{ buffer: Buffer; contentType: string } > {
-  const { account, mediaId } = params;
+  const { account, mediaId, maxBytes } = params;
   const accessToken = await getWecomAccessToken(account);
   const mediaUrl = `https://qyapi.weixin.qq.com/cgi-bin/media/get?access_token=${encodeURIComponent(accessToken)}&media_id=${encodeURIComponent(mediaId)}`;
 
@@ -346,6 +365,7 @@ export async function downloadWecomMedia(params: {
   }
 
   const contentType = res.headers.get("content-type") || "";
+  ensureNotTooLarge(res, maxBytes);
   if (contentType.includes("application/json")) {
     const json = await res.json();
     throw new Error(`WeCom media download failed: ${JSON.stringify(json)}`);
@@ -355,11 +375,16 @@ export async function downloadWecomMedia(params: {
   return { buffer, contentType };
 }
 
-export async function fetchMediaFromUrl(url: string, account?: ResolvedWecomAccount): Promise<{ buffer: Buffer; contentType: string } > {
+export async function fetchMediaFromUrl(
+  url: string,
+  account?: ResolvedWecomAccount,
+  maxBytes?: number,
+): Promise<{ buffer: Buffer; contentType: string } > {
   const res = account ? await fetchWithRetry(account, url) : await fetch(url);
   if (!res.ok) {
     throw new Error(`Failed to fetch media from URL: ${res.status}`);
   }
+  ensureNotTooLarge(res, maxBytes);
   const buffer = Buffer.from(await res.arrayBuffer());
   const contentType = res.headers.get("content-type") || "application/octet-stream";
   return { buffer, contentType };

package/wecom/src/wecom-app.ts

@@ -1,8 +1,8 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import crypto from "node:crypto";
 import { XMLParser } from "fast-xml-parser";
-import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
+import { appendFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 
 import type { WecomWebhookTarget } from "./monitor.js";
@@ -19,7 +19,25 @@ import {
   transcribeAudioWithOpenAI,
 } from "./media-auto.js";
 import { describeImageWithVision, resolveVisionConfig } from "./media-vision.js";
-import { downloadWecomMedia, fetchMediaFromUrl, sendWecomFile, sendWecomImage, sendWecomText, sendWecomVideo, sendWecomVoice, uploadWecomMedia } from "./wecom-api.js";
+import {
+  MEDIA_TOO_LARGE_ERROR,
+  downloadWecomMedia,
+  fetchMediaFromUrl,
+  sendWecomFile,
+  sendWecomImage,
+  sendWecomText,
+  sendWecomVideo,
+  sendWecomVoice,
+  uploadWecomMedia,
+} from "./wecom-api.js";
+import {
+  cleanupMediaDir,
+  resolveExtFromContentType,
+  resolveMediaMaxBytes,
+  resolveMediaRetentionMs,
+  resolveMediaTempDir,
+  sanitizeFilename,
+} from "./media-utils.js";
 
 const xmlParser = new XMLParser({
   ignoreAttributes: false,
@@ -138,6 +156,7 @@ function resolveSendIntervalMs(target: WecomWebhookTarget): number {
 type PendingSendList = {
   items: { name: string; path: string }[];
   dirLabel: string;
+  offset: number;
   createdAt: number;
   expiresAt: number;
 };
@@ -145,6 +164,7 @@ type PendingSendList = {
 const pendingSendLists = new Map<string, PendingSendList>();
 const PENDING_TTL_MS = 10 * 60 * 1000;
 const MAX_LIST_PREVIEW = 30;
+const LIST_MORE_PATTERN = /(更多|下一页|下页|继续|下一批|more|next)/i;
 
 function pendingKey(fromUser: string, chatId?: string): string {
   return chatId ? `${fromUser}::${chatId}` : fromUser;
@@ -214,6 +234,21 @@ function parseSelection(text: string, items: { name: string; path: string }[]):
   return picked.length > 0 ? picked : null;
 }
 
+function buildPendingListText(pending: PendingSendList): { text: string; hasMore: boolean } {
+  const start = Math.max(0, pending.offset);
+  const total = pending.items.length;
+  const slice = pending.items.slice(start, start + MAX_LIST_PREVIEW);
+  const preview = slice
+    .map((item, idx) => `${start + idx + 1}. ${item.name}`)
+    .join("\n");
+  const hasMore = start + MAX_LIST_PREVIEW < total;
+  const tail = hasMore
+    ? `\n…共 ${total} 个文件，回复“更多”查看下一页。`
+    : `\n共 ${total} 个文件。`;
+  const text = `在${pending.dirLabel}找到 ${total} 个文件：\n${preview}${tail}\n\n回复“全部”或“1 3 5”或直接发送具体文件名。`;
+  return { text, hasMore };
+}
+
 async function tryHandleNaturalFileSend(params: {
   target: WecomWebhookTarget;
   text: string;
@@ -227,6 +262,27 @@ async function tryHandleNaturalFileSend(params: {
   const key = pendingKey(fromUser, chatId);
   const pending = pendingSendLists.get(key);
   if (pending) {
+    if (LIST_MORE_PATTERN.test(text)) {
+      const nextOffset = pending.offset + MAX_LIST_PREVIEW;
+      if (nextOffset >= pending.items.length) {
+        await sendWecomText({
+          account: target.account,
+          toUser: fromUser,
+          chatId: isGroup ? chatId : undefined,
+          text: "已经是最后一页了。",
+        });
+        return true;
+      }
+      pending.offset = nextOffset;
+      const { text: listText } = buildPendingListText(pending);
+      await sendWecomText({
+        account: target.account,
+        toUser: fromUser,
+        chatId: isGroup ? chatId : undefined,
+        text: listText,
+      });
+      return true;
+    }
     const selection = parseSelection(text, pending.items);
     if (selection) {
       pendingSendLists.delete(key);
@@ -305,21 +361,19 @@ async function tryHandleNaturalFileSend(params: {
     return true;
   }
 
-  const preview = resolved.slice(0, MAX_LIST_PREVIEW)
-    .map((item, idx) => `${idx + 1}. ${item.name}`)
-    .join("\n");
-  const tail = resolved.length > MAX_LIST_PREVIEW ? `\n…共 ${resolved.length} 个文件` : "";
   pendingSendLists.set(key, {
     items: resolved,
     dirLabel: searchDir.label,
+    offset: 0,
     createdAt: Date.now(),
     expiresAt: Date.now() + PENDING_TTL_MS,
   });
+  const { text: listText } = buildPendingListText(pendingSendLists.get(key)!);
   await sendWecomText({
     account: target.account,
     toUser: fromUser,
     chatId: isGroup ? chatId : undefined,
-    text: `在${searchDir.label}找到 ${resolved.length} 个文件：\n${preview}${tail}\n\n回复“全部”或“1 3 5”或直接发送具体文件名。`,
+    text: listText,
   });
   return true;
 }
@@ -406,62 +460,6 @@ function isTextCommand(text: string): boolean {
   return text.trim().startsWith("/");
 }
 
-function resolveExtFromContentType(contentType: string, fallback: string): string {
-  if (!contentType) return fallback;
-  if (contentType.includes("png")) return "png";
-  if (contentType.includes("gif")) return "gif";
-  if (contentType.includes("jpeg") || contentType.includes("jpg")) return "jpg";
-  if (contentType.includes("mp4")) return "mp4";
-  if (contentType.includes("amr")) return "amr";
-  if (contentType.includes("wav")) return "wav";
-  if (contentType.includes("mp3")) return "mp3";
-  return fallback;
-}
-
-const cleanupExecuted = new Set<string>();
-
-async function cleanupMediaDir(
-  dir: string,
-  retentionHours?: number,
-  cleanupOnStart?: boolean,
-): Promise<void> {
-  if (cleanupOnStart === false) return;
-  if (!retentionHours || retentionHours <= 0) return;
-  if (cleanupExecuted.has(dir)) return;
-  cleanupExecuted.add(dir);
-  const cutoff = Date.now() - retentionHours * 3600 * 1000;
-  try {
-    const entries = await readdir(dir);
-    await Promise.all(entries.map(async (entry) => {
-      const full = join(dir, entry);
-      try {
-        const info = await stat(full);
-        if (info.isFile() && info.mtimeMs < cutoff) {
-          await rm(full, { force: true });
-        }
-      } catch {
-        // ignore
-      }
-    }));
-  } catch {
-    // ignore
-  }
-}
-
-function resolveMediaTempDir(target: WecomWebhookTarget): string {
-  return target.account.config.media?.tempDir?.trim()
-    || join(tmpdir(), "openclaw-wecom");
-}
-
-function resolveMediaMaxBytes(target: WecomWebhookTarget): number | undefined {
-  const maxBytes = target.account.config.media?.maxBytes;
-  return typeof maxBytes === "number" && maxBytes > 0 ? maxBytes : undefined;
-}
-
-function resolveMediaRetentionMs(target: WecomWebhookTarget): number | undefined {
-  const hours = target.account.config.media?.retentionHours;
-  return typeof hours === "number" && hours > 0 ? hours * 3600 * 1000 : undefined;
-}
 
 function normalizeMediaType(raw?: string): "image" | "voice" | "video" | "file" | null {
   if (!raw) return null;
@@ -477,6 +475,18 @@ function pickString(...values: unknown[]): string {
   return "";
 }
 
+function isMediaTooLargeError(err: unknown): boolean {
+  if (!err) return false;
+  if (typeof err === "string") return err.includes(MEDIA_TOO_LARGE_ERROR);
+  if (typeof err === "object") {
+    const anyErr = err as { code?: string; message?: string };
+    if (anyErr.code === MEDIA_TOO_LARGE_ERROR) return true;
+    if (typeof anyErr.message === "string" && anyErr.message.includes(MEDIA_TOO_LARGE_ERROR)) return true;
+    if (typeof anyErr.message === "string" && anyErr.message.toLowerCase().includes("media too large")) return true;
+  }
+  return false;
+}
+
 function resolveContentTypeFromExt(ext: string): string {
   const value = ext.toLowerCase();
   if (value === "png") return "image/png";
@@ -588,7 +598,7 @@ async function loadOutboundMedia(params: {
       contentType = resolveContentTypeFromExt(ext);
     }
   } else if (spec.url) {
-    const media = await fetchMediaFromUrl(spec.url, params.account);
+    const media = await fetchMediaFromUrl(spec.url, params.account, params.maxBytes);
     buffer = media.buffer;
     if (!contentType) contentType = media.contentType;
   }
@@ -603,17 +613,6 @@ async function loadOutboundMedia(params: {
   return { buffer, contentType: contentType || resolveContentTypeFromExt(ext), type, filename: safeName };
 }
 
-function sanitizeFilename(name: string, fallback: string): string {
-  const base = name.split(/[/\\\\]/).pop() ?? "";
-  const trimmed = base.trim();
-  const safe = trimmed
-    .replace(/[^\w.\-() ]+/g, "_")
-    .replace(/\s+/g, " ")
-    .trim();
-  const finalName = safe.slice(0, 120);
-  return finalName || fallback;
-}
-
 function hashKey(input: string): string {
   return crypto.createHash("sha1").update(input).digest("hex");
 }
@@ -849,8 +848,8 @@ async function processAppMessage(params: {
             logVerbose(target, `app voice cache hit: ${cached.path}`);
             messageText = "[用户发送了一条语音消息]\n\n请根据语音内容回复用户。";
           } else {
-            const media = await downloadWecomMedia({ account: target.account, mediaId });
             const maxBytes = resolveMediaMaxBytes(target);
+            const media = await downloadWecomMedia({ account: target.account, mediaId, maxBytes });
             if (maxBytes && media.buffer.length > maxBytes) {
               messageText = "[语音消息过大，未处理]\n\n请发送更短的语音消息。";
             } else {
@@ -885,7 +884,9 @@ async function processAppMessage(params: {
           }
         } catch (err) {
           target.runtime.error?.(`wecom app voice download failed: ${String(err)}`);
-          messageText = "[用户发送了一条语音消息，但下载失败]\n\n请告诉用户语音处理暂时不可用。";
+          messageText = isMediaTooLargeError(err)
+            ? "[语音消息过大，未处理]\n\n请发送更短的语音消息。"
+            : "[用户发送了一条语音消息，但下载失败]\n\n请告诉用户语音处理暂时不可用。";
         }
       } else {
         messageText = "[用户发送了一条语音消息]\n\n请告诉用户语音处理暂时不可用。";
@@ -896,6 +897,7 @@ async function processAppMessage(params: {
   if (msgType === "image") {
     const mediaId = String(msgObj?.MediaId ?? "");
     const picUrl = String(msgObj?.PicUrl ?? "");
+    const maxBytes = resolveMediaMaxBytes(target);
     try {
       const cacheKey = buildMediaCacheKey({ mediaId, url: picUrl });
       const cached = await getCachedMedia(cacheKey, retentionMs);
@@ -911,11 +913,11 @@ async function processAppMessage(params: {
         let buffer: Buffer | null = null;
         let contentType = "";
         if (mediaId) {
-          const media = await downloadWecomMedia({ account: target.account, mediaId });
+          const media = await downloadWecomMedia({ account: target.account, mediaId, maxBytes });
           buffer = media.buffer;
           contentType = media.contentType;
         } else if (picUrl) {
-          const media = await fetchMediaFromUrl(picUrl, target.account);
+          const media = await fetchMediaFromUrl(picUrl, target.account, maxBytes);
           buffer = media.buffer;
           contentType = media.contentType;
         }
@@ -973,7 +975,9 @@ async function processAppMessage(params: {
       }
     } catch (err) {
       target.runtime.error?.(`wecom app image download failed: ${String(err)}`);
-      messageText = "[用户发送了一张图片，但下载失败]\n\n请告诉用户图片处理暂时不可用。";
+      messageText = isMediaTooLargeError(err)
+        ? "[图片过大，未处理]\n\n请发送更小的图片。"
+        : "[用户发送了一张图片，但下载失败]\n\n请告诉用户图片处理暂时不可用。";
     }
   }
 
@@ -995,47 +999,49 @@ async function processAppMessage(params: {
           logVerbose(target, `app video cache hit: ${cached.path}`);
           messageText = "[用户发送了一个视频文件]\n\n请根据视频内容回复用户。";
         } else {
-          const media = await downloadWecomMedia({ account: target.account, mediaId });
-        const maxBytes = resolveMediaMaxBytes(target);
-        if (maxBytes && media.buffer.length > maxBytes) {
-          messageText = "[视频过大，未处理]\n\n请发送更小的视频。";
-        } else {
-          const ext = resolveExtFromContentType(media.contentType, "mp4");
-          const tempDir = resolveMediaTempDir(target);
-          await mkdir(tempDir, { recursive: true });
-          await cleanupMediaDir(
-            tempDir,
-            target.account.config.media?.retentionHours,
-            target.account.config.media?.cleanupOnStart,
-          );
-          const tempVideoPath = join(tempDir, `video-${Date.now()}-${Math.random().toString(36).slice(2)}.${ext}`);
-          await writeFile(tempVideoPath, media.buffer);
-          const mimeType = media.contentType || "video/mp4";
-          mediaContext = { type: "video", path: tempVideoPath, mimeType };
-          storeCachedMedia(cacheKey, {
-            path: tempVideoPath,
-            type: "video",
-            mimeType,
-            createdAt: Date.now(),
-            size: media.buffer.length,
-          });
-          logVerbose(target, `app video saved (${media.buffer.length} bytes): ${tempVideoPath}`);
-          const videoCfg = resolveAutoVideoConfig(target.account.config);
-          const summary = videoCfg
-            ? await summarizeVideoWithVision({
-              cfg: videoCfg,
-              account: target.account.config,
-              videoPath: tempVideoPath,
-            })
-            : null;
-          messageText = summary
-            ? `[用户发送了一个视频文件]\n\n[视频画面概述]\n${summary}\n\n请根据视频内容回复用户。`
-            : "[用户发送了一个视频文件]\n\n请根据视频内容回复用户。";
-        }
+          const maxBytes = resolveMediaMaxBytes(target);
+          const media = await downloadWecomMedia({ account: target.account, mediaId, maxBytes });
+          if (maxBytes && media.buffer.length > maxBytes) {
+            messageText = "[视频过大，未处理]\n\n请发送更小的视频。";
+          } else {
+            const ext = resolveExtFromContentType(media.contentType, "mp4");
+            const tempDir = resolveMediaTempDir(target);
+            await mkdir(tempDir, { recursive: true });
+            await cleanupMediaDir(
+              tempDir,
+              target.account.config.media?.retentionHours,
+              target.account.config.media?.cleanupOnStart,
+            );
+            const tempVideoPath = join(tempDir, `video-${Date.now()}-${Math.random().toString(36).slice(2)}.${ext}`);
+            await writeFile(tempVideoPath, media.buffer);
+            const mimeType = media.contentType || "video/mp4";
+            mediaContext = { type: "video", path: tempVideoPath, mimeType };
+            storeCachedMedia(cacheKey, {
+              path: tempVideoPath,
+              type: "video",
+              mimeType,
+              createdAt: Date.now(),
+              size: media.buffer.length,
+            });
+            logVerbose(target, `app video saved (${media.buffer.length} bytes): ${tempVideoPath}`);
+            const videoCfg = resolveAutoVideoConfig(target.account.config);
+            const summary = videoCfg
+              ? await summarizeVideoWithVision({
+                cfg: videoCfg,
+                account: target.account.config,
+                videoPath: tempVideoPath,
+              })
+              : null;
+            messageText = summary
+              ? `[用户发送了一个视频文件]\n\n[视频画面概述]\n${summary}\n\n请根据视频内容回复用户。`
+              : "[用户发送了一个视频文件]\n\n请根据视频内容回复用户。";
+          }
         }
       } catch (err) {
         target.runtime.error?.(`wecom app video download failed: ${String(err)}`);
-        messageText = "[用户发送了一个视频，但下载失败]\n\n请告诉用户视频处理暂时不可用。";
+        messageText = isMediaTooLargeError(err)
+          ? "[视频过大，未处理]\n\n请发送更小的视频。"
+          : "[用户发送了一个视频，但下载失败]\n\n请告诉用户视频处理暂时不可用。";
       }
     }
   }
@@ -1059,44 +1065,46 @@ async function processAppMessage(params: {
             ? `[用户发送了一个文件: ${cachedName}，已保存到: ${cached.path}]\n\n[文件内容预览]\n${preview}\n\n如需更多内容请使用 Read 工具。`
             : `[用户发送了一个文件: ${cachedName}，已保存到: ${cached.path}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`;
         } else {
-          const media = await downloadWecomMedia({ account: target.account, mediaId });
-        const maxBytes = resolveMediaMaxBytes(target);
-        if (maxBytes && media.buffer.length > maxBytes) {
-          messageText = "[文件过大，未处理]\n\n请发送更小的文件。";
-        } else {
-          const ext = fileName.includes(".") ? fileName.split(".").pop() : resolveExtFromContentType(media.contentType, "bin");
-          const tempDir = resolveMediaTempDir(target);
-          await mkdir(tempDir, { recursive: true });
-          await cleanupMediaDir(
-            tempDir,
-            target.account.config.media?.retentionHours,
-            target.account.config.media?.cleanupOnStart,
-          );
-          const safeName = sanitizeFilename(fileName, `file-${Date.now()}.${ext}`);
-          const tempFilePath = join(tempDir, safeName);
-          await writeFile(tempFilePath, media.buffer);
-          const mimeType = media.contentType || "application/octet-stream";
-          mediaContext = { type: "file", path: tempFilePath, mimeType };
-          storeCachedMedia(cacheKey, {
-            path: tempFilePath,
-            type: "file",
-            mimeType,
-            createdAt: Date.now(),
-            size: media.buffer.length,
-          });
-          logVerbose(target, `app file saved (${media.buffer.length} bytes): ${tempFilePath}`);
-          const fileCfg = resolveAutoFileConfig(target.account.config);
-          const preview = fileCfg
-            ? await extractFileTextPreview({ path: tempFilePath, mimeType, cfg: fileCfg })
-            : null;
-          messageText = preview
-            ? `[用户发送了一个文件: ${safeName}，已保存到: ${tempFilePath}]\n\n[文件内容预览]\n${preview}\n\n如需更多内容请使用 Read 工具。`
-            : `[用户发送了一个文件: ${safeName}，已保存到: ${tempFilePath}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`;
-        }
+          const maxBytes = resolveMediaMaxBytes(target);
+          const media = await downloadWecomMedia({ account: target.account, mediaId, maxBytes });
+          if (maxBytes && media.buffer.length > maxBytes) {
+            messageText = "[文件过大，未处理]\n\n请发送更小的文件。";
+          } else {
+            const ext = fileName.includes(".") ? fileName.split(".").pop() : resolveExtFromContentType(media.contentType, "bin");
+            const tempDir = resolveMediaTempDir(target);
+            await mkdir(tempDir, { recursive: true });
+            await cleanupMediaDir(
+              tempDir,
+              target.account.config.media?.retentionHours,
+              target.account.config.media?.cleanupOnStart,
+            );
+            const safeName = sanitizeFilename(fileName, `file-${Date.now()}.${ext}`);
+            const tempFilePath = join(tempDir, safeName);
+            await writeFile(tempFilePath, media.buffer);
+            const mimeType = media.contentType || "application/octet-stream";
+            mediaContext = { type: "file", path: tempFilePath, mimeType };
+            storeCachedMedia(cacheKey, {
+              path: tempFilePath,
+              type: "file",
+              mimeType,
+              createdAt: Date.now(),
+              size: media.buffer.length,
+            });
+            logVerbose(target, `app file saved (${media.buffer.length} bytes): ${tempFilePath}`);
+            const fileCfg = resolveAutoFileConfig(target.account.config);
+            const preview = fileCfg
+              ? await extractFileTextPreview({ path: tempFilePath, mimeType, cfg: fileCfg })
+              : null;
+            messageText = preview
+              ? `[用户发送了一个文件: ${safeName}，已保存到: ${tempFilePath}]\n\n[文件内容预览]\n${preview}\n\n如需更多内容请使用 Read 工具。`
+              : `[用户发送了一个文件: ${safeName}，已保存到: ${tempFilePath}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`;
+          }
         }
       } catch (err) {
         target.runtime.error?.(`wecom app file download failed: ${String(err)}`);
-        messageText = "[用户发送了一个文件，但下载失败]\n\n请告诉用户文件处理暂时不可用。";
+        messageText = isMediaTooLargeError(err)
+          ? "[文件过大，未处理]\n\n请发送更小的文件。"
+          : "[用户发送了一个文件，但下载失败]\n\n请告诉用户文件处理暂时不可用。";
       }
     }
   }

package/wecom/src/wecom-bot.ts

@@ -1,7 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import crypto from "node:crypto";
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 
 import type { PluginRuntime } from "openclaw/plugin-sdk";
@@ -10,6 +9,7 @@ import type { WecomWebhookTarget } from "./monitor.js";
 import type { ResolvedWecomAccount, WecomInboundMessage } from "./types.js";
 import { computeWecomMsgSignature, decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature } from "./crypto.js";
 import {
+  MEDIA_TOO_LARGE_ERROR,
   downloadWecomMedia,
   fetchMediaFromUrl,
   sendWecomFile,
@@ -28,6 +28,14 @@ import {
   summarizeVideoWithVision,
   transcribeAudioWithOpenAI,
 } from "./media-auto.js";
+import {
+  cleanupMediaDir,
+  resolveExtFromContentType,
+  resolveMediaMaxBytes,
+  resolveMediaRetentionMs,
+  resolveMediaTempDir,
+  sanitizeFilename,
+} from "./media-utils.js";
 
 const STREAM_TTL_MS = 10 * 60 * 1000;
 const STREAM_MAX_BYTES = 20_480;
@@ -36,7 +44,6 @@ const DEDUPE_TTL_MS = 2 * 60 * 1000;
 const DEDUPE_MAX_ENTRIES = 2_000;
 const MEDIA_CACHE_MAX_ENTRIES = 200;
 
-const cleanupExecuted = new Set<string>();
 const mediaCache = new Map<string, { entry: InboundMedia; createdAt: number; size: number; summary?: string }>();
 
 type StreamState = {
@@ -111,66 +118,6 @@ function truncateUtf8Bytes(text: string, maxBytes: number): string {
   return slice.toString("utf8");
 }
 
-function resolveExtFromContentType(contentType: string, fallback: string): string {
-  if (!contentType) return fallback;
-  if (contentType.includes("png")) return "png";
-  if (contentType.includes("gif")) return "gif";
-  if (contentType.includes("jpeg") || contentType.includes("jpg")) return "jpg";
-  if (contentType.includes("mp4")) return "mp4";
-  if (contentType.includes("amr")) return "amr";
-  if (contentType.includes("wav")) return "wav";
-  if (contentType.includes("mp3")) return "mp3";
-  return fallback;
-}
-
-async function cleanupMediaDir(
-  dir: string,
-  retentionHours?: number,
-  cleanupOnStart?: boolean,
-): Promise<void> {
-  if (cleanupOnStart === false) return;
-  if (!retentionHours || retentionHours <= 0) return;
-  if (cleanupExecuted.has(dir)) return;
-  cleanupExecuted.add(dir);
-  const cutoff = Date.now() - retentionHours * 3600 * 1000;
-  try {
-    const entries = await readdir(dir);
-    await Promise.all(entries.map(async (entry) => {
-      const full = join(dir, entry);
-      try {
-        const info = await stat(full);
-        if (info.isFile() && info.mtimeMs < cutoff) {
-          await rm(full, { force: true });
-        }
-      } catch {
-        // ignore
-      }
-    }));
-  } catch {
-    // ignore
-  }
-}
-
-function resolveMediaTempDir(target: WecomWebhookTarget): string {
-  return target.account.config.media?.tempDir?.trim()
-    || join(tmpdir(), "openclaw-wecom");
-}
-
-function resolveMediaMaxBytes(target: WecomWebhookTarget): number | undefined {
-  const maxBytes = target.account.config.media?.maxBytes;
-  return typeof maxBytes === "number" && maxBytes > 0 ? maxBytes : undefined;
-}
-
-function sanitizeFilename(name: string, fallback: string): string {
-  const base = name.split(/[/\\\\]/).pop() ?? "";
-  const trimmed = base.trim();
-  const safe = trimmed
-    .replace(/[^\w.\-() ]+/g, "_")
-    .replace(/\s+/g, " ")
-    .trim();
-  const finalName = safe.slice(0, 120);
-  return finalName || fallback;
-}
 
 function jsonOk(res: ServerResponse, body: unknown): void {
   res.statusCode = 200;
@@ -503,6 +450,18 @@ function pickString(...values: unknown[]): string {
   return "";
 }
 
+function isMediaTooLargeError(err: unknown): boolean {
+  if (!err) return false;
+  if (typeof err === "string") return err.includes(MEDIA_TOO_LARGE_ERROR);
+  if (typeof err === "object") {
+    const anyErr = err as { code?: string; message?: string };
+    if (anyErr.code === MEDIA_TOO_LARGE_ERROR) return true;
+    if (typeof anyErr.message === "string" && anyErr.message.includes(MEDIA_TOO_LARGE_ERROR)) return true;
+    if (typeof anyErr.message === "string" && anyErr.message.toLowerCase().includes("media too large")) return true;
+  }
+  return false;
+}
+
 function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "file"): string {
   if (!msg || typeof msg !== "object") return "";
   const block = msg[msgtype] ?? {};
@@ -628,9 +587,15 @@ async function buildBotMediaMessage(params: {
         : "[file]";
 
   if (!url && !base64 && !mediaId) return { text: fallbackLabel };
+  const hasAppCreds = Boolean(target.account.corpId && target.account.corpSecret && target.account.agentId);
+  if (!url && !base64 && mediaId && !hasAppCreds) {
+    return {
+      text: "[用户发送了媒体，但当前仅配置 Bot]\n\n未配置 App 凭据，无法下载或识别媒体内容。请补充 corpId/corpSecret/agentId。",
+    };
+  }
 
   try {
-    const cacheKey = buildMediaCacheKey({ url, base64 });
+    const cacheKey = buildMediaCacheKey({ url, base64, mediaId });
     const cached = await getCachedMedia(cacheKey, resolveMediaRetentionMs(target));
     if (cached) {
       if (msgtype === "image" && cached.summary) {
@@ -660,6 +625,7 @@ async function buildBotMediaMessage(params: {
 
     let buffer: Buffer | null = null;
     let contentType = "";
+    const maxBytes = resolveMediaMaxBytes(target);
     if (base64) {
       const parsed = parseBase64Input(base64);
       buffer = Buffer.from(parsed.data, "base64");
@@ -671,18 +637,17 @@ async function buildBotMediaMessage(params: {
         else contentType = "application/octet-stream";
       }
     } else if (url) {
-      const media = await fetchMediaFromUrl(url, target.account);
+      const media = await fetchMediaFromUrl(url, target.account, maxBytes);
       buffer = media.buffer;
       contentType = media.contentType;
-    } else if (mediaId && target.account.corpId && target.account.corpSecret && target.account.agentId) {
-      const media = await downloadWecomMedia({ account: target.account, mediaId });
+    } else if (mediaId && hasAppCreds) {
+      const media = await downloadWecomMedia({ account: target.account, mediaId, maxBytes });
       buffer = media.buffer;
       contentType = media.contentType;
     }
 
     if (!buffer) return { text: fallbackLabel };
 
-    const maxBytes = resolveMediaMaxBytes(target);
     if (maxBytes && buffer.length > maxBytes) {
       if (msgtype === "image") return { text: "[图片过大，未处理]\n\n请发送更小的图片。" };
       if (msgtype === "voice") return { text: "[语音消息过大，未处理]\n\n请发送更短的语音消息。" };
@@ -798,6 +763,12 @@ async function buildBotMediaMessage(params: {
     return { text: fallbackLabel };
   } catch (err) {
     target.runtime.error?.(`wecom bot ${msgtype} download failed: ${String(err)}`);
+    if (isMediaTooLargeError(err)) {
+      if (msgtype === "image") return { text: "[图片过大，未处理]\n\n请发送更小的图片。" };
+      if (msgtype === "voice") return { text: "[语音消息过大，未处理]\n\n请发送更短的语音消息。" };
+      if (msgtype === "video") return { text: "[视频过大，未处理]\n\n请发送更小的视频。" };
+      return { text: "[文件过大，未处理]\n\n请发送更小的文件。" };
+    }
     if (msgtype === "image") return { text: "[用户发送了一张图片，但下载失败]\n\n请告诉用户图片处理暂时不可用。" };
     if (msgtype === "voice") return { text: "[用户发送了一条语音消息，但下载失败]\n\n请告诉用户语音处理暂时不可用。" };
     if (msgtype === "video") return { text: "[用户发送了一个视频，但下载失败]\n\n请告诉用户视频处理暂时不可用。" };
@@ -991,7 +962,7 @@ async function loadOutboundMedia(params: {
       contentType = resolveContentTypeFromExt(ext);
     }
   } else if (spec.url) {
-    const media = await fetchMediaFromUrl(spec.url, params.account);
+    const media = await fetchMediaFromUrl(spec.url, params.account, params.maxBytes);
     buffer = media.buffer;
     if (!contentType) contentType = media.contentType;
   }
@@ -1014,16 +985,12 @@ function mediaSentLabel(type: string): string {
   return "[已发送媒体]";
 }
 
-function resolveMediaRetentionMs(target: WecomWebhookTarget): number | undefined {
-  const hours = target.account.config.media?.retentionHours;
-  return typeof hours === "number" && hours > 0 ? hours * 3600 * 1000 : undefined;
-}
-
 function hashCacheKey(input: string): string {
   return crypto.createHash("sha1").update(input).digest("hex");
 }
 
-function buildMediaCacheKey(params: { url?: string; base64?: string }): string | null {
+function buildMediaCacheKey(params: { url?: string; base64?: string; mediaId?: string }): string | null {
+  if (params.mediaId) return `media:${params.mediaId}`;
   if (params.url) return `url:${hashCacheKey(params.url)}`;
   if (params.base64) return `b64:${hashCacheKey(params.base64)}`;
   return null;