@marshulll/openclaw-wecom 0.1.25 → 0.1.27

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -10,7 +10,7 @@ OpenClaw WeCom plugin supporting **Bot API mode** and **Internal App mode** with
 - Dual mode: Bot API (JSON callback + stream) / App (XML callback + ACK + proactive send)
 - Multi-account: `channels.wecom.accounts`
 - Message types: text / image / voice / video / file (send & receive)
-- Commands: `/help`, `/status`, `/clear`, `/sendfile`
+- Commands (App mode): `/help`, `/status`, `/clear`, `/sendfile`
 - Stability: signature verification, AES decrypt, token cache, rate limit & retries
 - Group chat: uses `appchat/send` when `chatId` is present
 - Advanced: folder zip sending, send queue, operation logs, media auto recognition
@@ -88,18 +88,38 @@ Install guide: `docs/INSTALL.md`
 - App mode: downloads inbound media to local temp dir (`media.tempDir`)
 - Bot mode media bridge: if reply payload includes `mediaUrl + mediaType`,
   and App credentials are present, media will be uploaded and sent
+> Bot-only config cannot send/receive media (image/voice/video/file). Full media support requires App credentials.
 
-## Extra commands
+## Extra commands (App mode)
 - `/sendfile`: send files from server (multiple absolute paths)
   - Directories are zipped automatically
   - 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
 
+## Proactive send (App mode)
+Push endpoint path: `{webhookPath}/push` (e.g. `/wecom/app/push`).
+
+- Method: `POST`
+- Auth: `pushToken` (optional but recommended)
+  - Accepts `Authorization: Bearer <token>`, `x-openclaw-token`, query/body `token`
+- Target: `toUser` (DM) or `chatId` (group)
+
+Minimal example (text):
+```bash
+curl -X POST "https://your-domain/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"Hello"}'
+```
+
+Media (file/image/voice/video): use `mediaUrl` or `mediaBase64`. You can also send text together.
+
 ## Media auto recognition (optional)
 - **Voice send/receive does NOT require API**; only auto transcription needs an OpenAI-compatible API
 - **Video recognition requires ffmpeg** (install on server, then set `media.auto.video.enabled = true`)
-- Video recognition supports **light / full** modes (default: light)
+- Video recognition supports **light / full** modes (default: light) via `media.auto.video.mode`
 - Small text files can be previewed automatically
 
 ## Send queue & operation logs (optional)

package/README.md

@@ -10,7 +10,7 @@ OpenClaw WeCom 插件，支持 **智能机器人 API 模式** 与 **自建应用
 - 双模式：Bot API（JSON 回调 + stream）/ App（XML 回调 + ACK + 主动发送）
 - 多账户：`channels.wecom.accounts`
 - 消息类型：文本 / 图片 / 语音 / 视频 / 文件（收发均支持）
-- 机器人命令：`/help`、`/status`、`/clear`、`/sendfile`
+- 机器人命令（App 模式）：`/help`、`/status`、`/clear`、`/sendfile`
 - 稳定性：签名校验、AES 解密、token 缓存、限流与重试
 - 群聊：自动识别 `chatId` 并使用 `appchat/send`
 - 进阶：文件夹打包发送、发送队列、操作日志、多媒体自动识别
@@ -90,18 +90,38 @@ openclaw gateway restart
 - App 模式：收到媒体会下载到本地临时目录（可配置 `media.tempDir`）
 - Bot 模式媒体桥接：当 reply payload 含 `mediaUrl + mediaType` 时，
   若已配置 App 凭据，会自动上传并发送媒体
+> 仅配置 Bot 时，媒体（图片/语音/视频/文件）无法收发；需补齐 App 凭据才能启用完整媒体能力。
 
-## 命令补充
+## 命令补充（App 模式）
 - `/sendfile`：发送服务器文件（支持多个绝对路径）
   - 支持目录：自动打包为 zip 后发送
   - 示例：`/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - 也支持自然语言：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
+  - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
   - 多文件会先返回列表，回复“全部”或序号再发送
 
+## 主动消息（App 模式）
+主动推送接口路径为：`{webhookPath}/push`（例如 `/wecom/app/push`）。
+
+- 方法：`POST`
+- 鉴权：`pushToken`（可选，但建议开启）
+  - 可放在 `Authorization: Bearer <token>`、`x-openclaw-token`、`token` 参数或 body 的 `token` 字段
+- 目标：`toUser`（单人）或 `chatId`（群聊），二选一
+
+最小示例（文本）：
+```bash
+curl -X POST "https://你的域名/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"你好"}'
+```
+
+发送媒体（file/image/voice/video）：支持 `mediaUrl` 或 `mediaBase64`，可与 `text` 同时发送。
+
 ## 多媒体自动识别（可选）
 - **语音收发不需要 API**，只有开启“语音自动转写”才需要 OpenAI 兼容接口
 - **视频识别需要 ffmpeg**（服务器已安装后，将 `media.auto.video.enabled` 设为 `true`）
-- 视频识别支持 **light / full** 两种模式（默认 light）
+- 视频识别支持 **light / full** 两种模式（默认 light），可通过 `media.auto.video.mode` 切换
 - 文本文件可自动预览（小文件直接读入）
 
 ## 发送队列与操作日志（可选）

package/README.zh.md

@@ -10,7 +10,7 @@ OpenClaw WeCom 插件，支持 **智能机器人 API 模式** 与 **自建应用
 - 双模式：Bot API（JSON 回调 + stream）/ App（XML 回调 + ACK + 主动发送）
 - 多账户：`channels.wecom.accounts`
 - 消息类型：文本 / 图片 / 语音 / 视频 / 文件（收发均支持）
-- 机器人命令：`/help`、`/status`、`/clear`、`/sendfile`
+- 机器人命令（App 模式）：`/help`、`/status`、`/clear`、`/sendfile`
 - 稳定性：签名校验、AES 解密、token 缓存、限流与重试
 - 群聊：自动识别 `chatId` 并使用 `appchat/send`
 - 进阶：文件夹打包发送、发送队列、操作日志、多媒体自动识别
@@ -90,18 +90,38 @@ openclaw gateway restart
 - App 模式：收到媒体会下载到本地临时目录（可配置 `media.tempDir`）
 - Bot 模式媒体桥接：当 reply payload 含 `mediaUrl + mediaType` 时，
   若已配置 App 凭据，会自动上传并发送媒体
+> 仅配置 Bot 时，媒体（图片/语音/视频/文件）无法收发；需补齐 App 凭据才能启用完整媒体能力。
 
-## 命令补充
+## 命令补充（App 模式）
 - `/sendfile`：发送服务器文件（支持多个绝对路径）
   - 支持目录：自动打包为 zip 后发送
   - 示例：`/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - 也支持自然语言：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
+  - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
   - 多文件会先返回列表，回复“全部”或序号再发送
 
+## 主动消息（App 模式）
+主动推送接口路径为：`{webhookPath}/push`（例如 `/wecom/app/push`）。
+
+- 方法：`POST`
+- 鉴权：`pushToken`（可选，但建议开启）
+  - 可放在 `Authorization: Bearer <token>`、`x-openclaw-token`、`token` 参数或 body 的 `token` 字段
+- 目标：`toUser`（单人）或 `chatId`（群聊），二选一
+
+最小示例（文本）：
+```bash
+curl -X POST "https://你的域名/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"你好"}'
+```
+
+发送媒体（file/image/voice/video）：支持 `mediaUrl` 或 `mediaBase64`，可与 `text` 同时发送。
+
 ## 多媒体自动识别（可选）
 - **语音收发不需要 API**，只有开启“语音自动转写”才需要 OpenAI 兼容接口
 - **视频识别需要 ffmpeg**（服务器已安装后，将 `media.auto.video.enabled` 设为 `true`）
-- 视频识别支持 **light / full** 两种模式（默认 light）
+- 视频识别支持 **light / full** 两种模式（默认 light），可通过 `media.auto.video.mode` 切换
 - 文本文件可自动预览（小文件直接读入）
 
 ## 发送队列与操作日志（可选）

package/docs/INSTALL.md

@@ -129,9 +129,11 @@ openclaw gateway restart
 
 ## 高级能力（可选）
 ### /sendfile（文件与文件夹）
+- 仅 **App 模式** 支持 `/sendfile`
 - `/sendfile` 仅支持 **服务器绝对路径**
 - 目录会自动打包为 zip 再发送
 - 自然语言也可触发：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
+  - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
   - 如匹配多个文件，会返回列表让你确认（回复“全部”或序号）
 
 示例：
@@ -142,8 +144,14 @@ openclaw gateway restart
 ### 多媒体自动识别
 - **语音收发不需要 API**；只有开启“语音自动转写”才需要 OpenAI 兼容接口
 - **视频识别需要 ffmpeg**（服务器安装后将 `media.auto.video.enabled=true`）
+- **视频识别 light/full 模式**：`media.auto.video.mode`（默认 `light`）
 - 文本文件可自动预览（小文件直接读入）
 
+建议安装 ffmpeg（Ubuntu）：
+```bash
+sudo apt-get update && sudo apt-get install -y ffmpeg
+```
+
 ### 发送队列与操作日志
 - `sendQueue.intervalMs`：/sendfile 多文件发送间隔
 - `operations.logPath`：JSONL 日志，记录发送文件与主动推送
@@ -153,6 +161,24 @@ openclaw gateway restart
 - 在企业微信后台配置回调 URL。
 - 建议 Bot 与 App 使用不同 `webhookPath`，便于排障与避免回调混淆。
 
+## 主动推送（App 模式）
+主动推送接口路径：`{webhookPath}/push`（例如 `/wecom/app/push`）。
+
+- 方法：`POST`
+- 鉴权：`pushToken`（可选，但建议开启）
+  - `Authorization: Bearer <token>`、`x-openclaw-token`、`token` 参数或 body `token`
+- 目标：`toUser`（单人）或 `chatId`（群聊），二选一
+
+最小示例（文本）：
+```bash
+curl -X POST "https://你的域名/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"你好"}'
+```
+
+媒体发送（file/image/voice/video）：使用 `mediaUrl` 或 `mediaBase64`，可与 `text` 同时发送。
+
 ## 常见问题
 - 回调验证失败：检查 Token / AESKey / URL 是否一致
 - 没有回复：检查 OpenClaw 是否已启用插件并重启 gateway

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshulll/openclaw-wecom",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
   "author": "OpenClaw",
@@ -52,7 +52,7 @@
     "channel",
     "plugin"
   ],
-  "license": "ISC",
+  "license": "MIT",
   "files": [
     "wecom/**",
     "docs/INSTALL.md",

package/wecom/src/wecom-bot.ts

@@ -9,7 +9,15 @@ import type { PluginRuntime } from "openclaw/plugin-sdk";
 import type { WecomWebhookTarget } from "./monitor.js";
 import type { ResolvedWecomAccount, WecomInboundMessage } from "./types.js";
 import { computeWecomMsgSignature, decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature } from "./crypto.js";
-import { fetchMediaFromUrl, sendWecomFile, sendWecomImage, sendWecomVideo, sendWecomVoice, uploadWecomMedia } from "./wecom-api.js";
+import {
+  downloadWecomMedia,
+  fetchMediaFromUrl,
+  sendWecomFile,
+  sendWecomImage,
+  sendWecomVideo,
+  sendWecomVoice,
+  uploadWecomMedia,
+} from "./wecom-api.js";
 import { getWecomRuntime } from "./runtime.js";
 import { describeImageWithVision, resolveVisionConfig } from "./media-vision.js";
 import {
@@ -501,9 +509,13 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
   if (msgtype === "image") {
     return pickString(
       block.url,
+      block.imageUrl,
+      block.image_url,
       block.picurl,
       block.picUrl,
       block.pic_url,
+      msg.imageUrl,
+      msg.image_url,
       msg.picurl,
       msg.picUrl,
       msg.pic_url,
@@ -516,6 +528,8 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
       block.fileurl,
       block.fileUrl,
       block.file_url,
+      block.downloadUrl,
+      block.download_url,
       block.mediaUrl,
       block.media_url,
       msg.voiceUrl,
@@ -529,6 +543,8 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
       block.fileurl,
       block.fileUrl,
       block.file_url,
+      block.downloadUrl,
+      block.download_url,
       block.mediaUrl,
       block.media_url,
       msg.videoUrl,
@@ -541,6 +557,8 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
     block.fileurl,
     block.fileUrl,
     block.file_url,
+    block.downloadUrl,
+    block.download_url,
     block.mediaUrl,
     block.media_url,
     msg.fileUrl,
@@ -554,12 +572,28 @@ function resolveBotMediaBase64(msg: any, msgtype: "image" | "voice" | "video" |
   const block = msg[msgtype] ?? {};
   return pickString(
     block.base64,
+    block.base64Data,
     block.data,
     msg.base64,
     msg.data,
   );
 }
 
+function resolveBotMediaId(msg: any, msgtype: "image" | "voice" | "video" | "file"): string {
+  if (!msg || typeof msg !== "object") return "";
+  const block = msg[msgtype] ?? {};
+  return pickString(
+    block.media_id,
+    block.mediaId,
+    block.mediaid,
+    block.mediaID,
+    msg.media_id,
+    msg.mediaId,
+    msg.mediaid,
+    msg.mediaID,
+  );
+}
+
 function resolveBotMediaFilename(msg: any): string {
   if (!msg || typeof msg !== "object") return "";
   const block = msg.file ?? {};
@@ -568,6 +602,7 @@ function resolveBotMediaFilename(msg: any): string {
     block.fileName,
     block.name,
     block.file_name,
+    block.file,
     msg.filename,
     msg.fileName,
     msg.name,
@@ -579,9 +614,10 @@ async function buildBotMediaMessage(params: {
   msgtype: "image" | "voice" | "video" | "file";
   url?: string;
   base64?: string;
+  mediaId?: string;
   filename?: string;
 }): Promise<InboundBody> {
-  const { target, msgtype, url, base64, filename } = params;
+  const { target, msgtype, url, base64, mediaId, filename } = params;
 
   const fallbackLabel = msgtype === "image"
     ? "[image]"
@@ -591,7 +627,7 @@ async function buildBotMediaMessage(params: {
         ? "[video]"
         : "[file]";
 
-  if (!url && !base64) return { text: fallbackLabel };
+  if (!url && !base64 && !mediaId) return { text: fallbackLabel };
 
   try {
     const cacheKey = buildMediaCacheKey({ url, base64 });
@@ -625,15 +661,23 @@ async function buildBotMediaMessage(params: {
     let buffer: Buffer | null = null;
     let contentType = "";
     if (base64) {
-      buffer = Buffer.from(base64, "base64");
-      if (msgtype === "image") contentType = "image/jpeg";
-      else if (msgtype === "voice") contentType = "audio/amr";
-      else if (msgtype === "video") contentType = "video/mp4";
-      else contentType = "application/octet-stream";
+      const parsed = parseBase64Input(base64);
+      buffer = Buffer.from(parsed.data, "base64");
+      if (parsed.mimeType) contentType = parsed.mimeType;
+      if (!contentType) {
+        if (msgtype === "image") contentType = "image/jpeg";
+        else if (msgtype === "voice") contentType = "audio/amr";
+        else if (msgtype === "video") contentType = "video/mp4";
+        else contentType = "application/octet-stream";
+      }
     } else if (url) {
       const media = await fetchMediaFromUrl(url, target.account);
       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 });
+      buffer = media.buffer;
+      contentType = media.contentType;
     }
 
     if (!buffer) return { text: fallbackLabel };
@@ -771,9 +815,17 @@ async function buildInboundBody(params: { target: WecomWebhookTarget; msg: Wecom
   if (msgtype === "voice") {
     const content = (msg as any).voice?.content;
     if (typeof content === "string" && content.trim()) return { text: content.trim() };
+    const recognition = pickString(
+      (msg as any).voice?.recognition,
+      (msg as any).voice?.text,
+      (msg as any).voice?.transcript,
+      (msg as any).recognition,
+    );
+    if (recognition) return { text: recognition };
     const url = resolveBotMediaUrl(msg as any, "voice");
     const base64 = resolveBotMediaBase64(msg as any, "voice");
-    return await buildBotMediaMessage({ target, msgtype: "voice", url, base64 });
+    const mediaId = resolveBotMediaId(msg as any, "voice");
+    return await buildBotMediaMessage({ target, msgtype: "voice", url, base64, mediaId });
   }
   if (msgtype === "mixed") {
     const items = (msg as any).mixed?.msg_item;
@@ -794,18 +846,21 @@ async function buildInboundBody(params: { target: WecomWebhookTarget; msg: Wecom
   if (msgtype === "image") {
     const url = resolveBotMediaUrl(msg as any, "image");
     const base64 = resolveBotMediaBase64(msg as any, "image");
-    return await buildBotMediaMessage({ target, msgtype: "image", url, base64 });
+    const mediaId = resolveBotMediaId(msg as any, "image");
+    return await buildBotMediaMessage({ target, msgtype: "image", url, base64, mediaId });
   }
   if (msgtype === "file") {
     const url = resolveBotMediaUrl(msg as any, "file");
     const base64 = resolveBotMediaBase64(msg as any, "file");
+    const mediaId = resolveBotMediaId(msg as any, "file");
     const filename = resolveBotMediaFilename(msg as any);
-    return await buildBotMediaMessage({ target, msgtype: "file", url, base64, filename });
+    return await buildBotMediaMessage({ target, msgtype: "file", url, base64, mediaId, filename });
   }
   if (msgtype === "video") {
     const url = resolveBotMediaUrl(msg as any, "video");
     const base64 = resolveBotMediaBase64(msg as any, "video");
-    return await buildBotMediaMessage({ target, msgtype: "video", url, base64 });
+    const mediaId = resolveBotMediaId(msg as any, "video");
+    return await buildBotMediaMessage({ target, msgtype: "video", url, base64, mediaId });
   }
   if (msgtype === "event") {
     const eventtype = String((msg as any).event?.eventtype ?? "").trim();