@xgjktech/xg_cwork_im 1.11.0 → 1.11.3

package/README.md

@@ -304,19 +304,26 @@ openclaw-channel-xg-cwork-im/
 
 代码在内部 Git 上维护，发布到 npm 后同事即可一条命令安装。按下列步骤操作。
 
-### 步骤 1：在 npm 注册 / 登录
+### 步骤 1：在 npm 注册 / 登录（仅本次发布走官方）
+
+你可以保留系统默认镜像不变；只在本项目发布时显式指定官方 registry。
 
 1. 无 npm 账号：打开 [https://www.npmjs.com/signup](https://www.npmjs.com/signup) 注册。
-2. 在项目根目录执行：
+2. 在项目根目录执行（不会改全局配置）：
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+```
+
+3. 登录成功后校验当前身份（同样只看官方 registry）：
 
 ```bash
-npm login
+npm whoami --registry=https://registry.npmjs.org/
 ```
 
-3. 按提示输入 **Username**、**Password**、**Email**。
 4. 若账号开启了**双因素认证（2FA）**，发布时必须使用：
    - 在 npm 网站 **Access Tokens** 里创建 **Granular Access Token**，勾选 **Publish packages**，并勾选 **Bypass 2FA**；或  
-   - 在命令行登录时使用 **OTP**（一次性密码）。  
+   - 在发布时输入 **OTP**（一次性密码）。  
    否则会报错：`Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages`。
 
 ### 步骤 2：确认 scope 与权限
@@ -335,12 +342,12 @@ npm pack --dry-run
 
 确认列出的文件无敏感内容（如 `.env`、密钥）。发布内容由 `package.json` 的 `"files"` 控制。
 
-### 步骤 4：执行发布
+### 步骤 4：执行发布（强制官方 registry）
 
 **scoped 包必须加 `--access public`**，否则会按私有包计费并可能报 402：
 
 ```bash
-npm publish --access public
+npm publish --access public --registry=https://registry.npmjs.org/
 ```
 
 成功后可在此查看：  
@@ -355,7 +362,7 @@ npm publish --access public
 3. 在项目根目录执行：
 
 ```bash
-npm publish --access public
+npm publish --access public --registry=https://registry.npmjs.org/
 ```
 
 4. 通知同事执行 **更新已安装的插件**（见上文「更新已安装的插件」），例如：  

package/index.ts

@@ -1,34 +1,37 @@
-/**
- * XG-IM Channel Plugin for OpenClaw
- *
- * 插件入口：注册 XG-IM channel，并注入 PluginRuntime 供消息路由使用
- */
-
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-import { setXgImRuntime, xgCworkImChannelPlugin } from "./src/channel.js";
-import { buildGroupHistoryTool, extractXgCworkImConfig } from "./src/group-history-tool.js";
-import { buildSendGroupMessageTool } from "./src/send-group-message-tool.js";
-import type { XgCworkImPluginModule } from "./src/types.js";
-
-const plugin: XgCworkImPluginModule = {
-    id: "xg_cwork_im",
-    name: "XG CWork IM Channel",
-    description: "工作说说 IM 机器人 Channel 插件，通过 WebSocket 长连接接入",
-    configSchema: emptyPluginConfigSchema(),
-    register(api: OpenClawPluginApi): void {
-        setXgImRuntime(api.runtime);
-        api.registerChannel({ plugin: xgCworkImChannelPlugin });
-        // 注册 AI 工具（静态工具对象，确保 toolNames 正确注册）
-        const cworkConfig = extractXgCworkImConfig(api.config);
-        if (cworkConfig) {
-            // 工具涉及网络请求 / 副作用，按文档要求标记为 optional，由用户在 Agent 的 tools.allow 中显式启用
-            api.registerTool(buildGroupHistoryTool(cworkConfig), { optional: true });
-            api.registerTool(buildSendGroupMessageTool(cworkConfig), { optional: true });
-        } else {
-            console.warn("[xg_cwork_im] channel config not found, skipping tool registration");
-        }
-    },
-};
-
-export default plugin;
+/**
+ * XG-IM Channel Plugin for OpenClaw
+ *
+ * 插件入口：注册 XG-IM channel，并注入 PluginRuntime 供消息路由使用
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { setXgImRuntime, xgCworkImChannelPlugin } from "./src/channel.js";
+import { buildGroupHistoryTool, extractXgCworkImConfig } from "./src/group-history-tool.js";
+import { buildSendGroupMessageTool } from "./src/send-group-message-tool.js";
+import type { XgCworkImPluginModule } from "./src/types.js";
+
+export { XG_IM_RECOMMENDED_CHANNEL_SYSTEM_PROMPT } from "./src/recommended-system-prompt.js";
+
+const plugin: XgCworkImPluginModule = {
+    id: "xg_cwork_im",
+    name: "XG CWork IM Channel",
+    description: "工作说说 IM 机器人 Channel 插件，通过 WebSocket 长连接接入",
+    configSchema: emptyPluginConfigSchema(),
+    register(api: OpenClawPluginApi): void {
+        setXgImRuntime(api.runtime);
+        api.registerChannel({ plugin: xgCworkImChannelPlugin });
+        // 注册 AI 工具（静态工具对象，确保 toolNames 正确注册）
+        const cworkConfig = extractXgCworkImConfig(api.config);
+        if (cworkConfig) {
+            // 工具涉及网络请求 / 副作用，按文档要求标记为 optional，由用户在 Agent 的 tools.allow 中显式启用
+            api.registerTool(buildGroupHistoryTool(cworkConfig), { optional: true });
+            // 主动推送（Cron/定时等）向 IM 发纯文本；用户经 IM 对话时不用此工具
+            api.registerTool(buildSendGroupMessageTool(cworkConfig), { optional: true });
+        } else {
+            console.warn("[xg_cwork_im] channel config not found, skipping tool registration");
+        }
+    },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -3,6 +3,15 @@
     "channels": [
         "xg_cwork_im"
     ],
+    "channelConfigs": {
+        "xg_cwork_im": {
+            "schema": {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {}
+            }
+        }
+    },
     "configSchema": {
         "type": "object",
         "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgjktech/xg_cwork_im",
-  "version": "1.11.0",
+  "version": "1.11.3",
   "description": "XG CWork IM channel plugin for OpenClaw",
   "keywords": [
     "bot",

package/src/channel.ts

@@ -46,9 +46,10 @@ function getXgImRuntime(): PluginRuntime {
 // ─── 配置 Schema ──────────────────────────────────────────────────────────────
 
 const XgImAccountConfigSchema = z.object({
-    // 注意：为了兼容 OpenClaw doctor 生成的 accounts.default（仅包含默认项，不含 appKey），这里先放宽为 optional，
-    // 然后在 XgImConfigSchema.superRefine 中强制校验：除 default 之外的账号必须提供 appKey。
-    appKey: z.string().min(1, "appKey is required").optional(),
+    // 注意：为了兼容 OpenClaw doctor 生成的 accounts.default（仅包含默认项，不含 appKey/robotKey），这里先放宽为 optional，
+    // 然后在 XgImConfigSchema.superRefine 中强制校验：除 default 之外的账号必须提供 robotKey 或 appKey。
+    robotKey: z.string().min(1).optional(),
+    appKey: z.string().min(1).optional(),
     agentId: z.string().optional().default("main"),
     name: z.string().optional(),
     groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
@@ -61,6 +62,7 @@ const XgImAccountConfigSchema = z.object({
 });
 
 const XgImConfigSchema = z.object({
+    robotKey: z.string().optional(),
     appKey: z.string().optional(),
     agentId: z.string().optional().default("main"),
     baseUrl: z.string().url("baseUrl must be a valid URL"),
@@ -117,11 +119,11 @@ const XgImConfigSchema = z.object({
     for (const [key, acc] of Object.entries(accounts)) {
         if (key === "default") continue;
         if (!acc || typeof acc !== "object") continue;
-        if (!("appKey" in acc) || !acc.appKey) {
+        if (!acc.robotKey && !acc.appKey) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
-                path: ["accounts", key, "appKey"],
-                message: "appKey is required for account entries (except accounts.default)",
+                path: ["accounts", key, "robotKey"],
+                message: "robotKey (or appKey) is required for account entries (except accounts.default)",
             });
         }
         if (badSubdir(acc.inboundMediaWorkspaceSubdir)) {
@@ -145,6 +147,16 @@ const XgImConfigSchema = z.object({
 
 // ─── 辅助函数 ─────────────────────────────────────────────────────────────────
 
+/**
+ * 规范化 key 字段：优先取 robotKey，没有则取 appKey，统一写入 appKey。
+ * 这样下游代码（auth.ts 等）只需读 config.appKey，无需感知 robotKey 的存在。
+ */
+function normalizeRobotKey<T extends { robotKey?: string; appKey?: string }>(config: T): T {
+    const resolved = config.robotKey ?? config.appKey;
+    if (resolved === config.appKey) return config;
+    return { ...config, appKey: resolved };
+}
+
 /** 从顶层 cfg 中取出 XgImConfig，支持多账户（README：channels.xg_cwork_im） */
 function getXgImConfig(cfg: OpenClawConfig, accountId?: string | null): XgImConfig {
     const raw = (cfg as Record<string, Record<string, unknown>>)?.channels?.xg_cwork_im as XgImConfig | undefined;
@@ -160,18 +172,18 @@ function getXgImConfig(cfg: OpenClawConfig, accountId?: string | null): XgImConf
     // 指定了具体账户 ID 时，优先合并对应账户配置
     if (accountId && accountId !== "default" && accountMap) {
         const sub = accountMap[accountId];
-        if (sub) return { ...raw, ...(defaults ?? {}), ...sub };
+        if (sub) return normalizeRobotKey({ ...raw, ...(defaults ?? {}), ...sub });
     }
 
     // 没有指定 accountId（如 Cron outbound 场景），自动 fallback 到「第一个账户」
-    // 避免顶层 raw 没有 appKey 时 getToken 失败
-    if (accountMap && !raw.appKey) {
+    // 避免顶层 raw 没有 appKey/robotKey 时 getToken 失败
+    if (accountMap && !raw.appKey && !raw.robotKey) {
         const firstKey = Object.keys(accountMap).find((k) => k !== "default");
         const first = firstKey ? accountMap[firstKey] : undefined;
-        if (first) return { ...raw, ...(defaults ?? {}), ...first };
+        if (first) return normalizeRobotKey({ ...raw, ...(defaults ?? {}), ...first });
     }
 
-    return raw;
+    return normalizeRobotKey(raw);
 }
 
 /**
@@ -420,6 +432,8 @@ async function dispatchMentionedReply(args: {
                 streamMsgId,
                 reply,
             );
+            // 标记已发送，让 finally 以 reason=stop 结束，避免后台再显示"AI未响应"
+            hasFirstReply = true;
             log.info(
                 `${logPrefix} [send] Timeout reply sent via HTTP: groupId=${params.groupId} msgId=${streamMsgId} text="${timeoutText}"`,
             );
@@ -428,20 +442,48 @@ async function dispatchMentionedReply(args: {
         }
     }, firstReplyTimeoutMs);
 
+    let deliverCallCount = 0;
+    let deliverSkippedCount = 0;
+    let dispatchError: unknown = undefined;
+    // 捕获 deliver 抛出后被 dispatcher 静默吞掉的错误：postImMessage 已带 5 次重试，
+    // 进到这里说明所有重试均失败（IM 后台不可用 / 4xx / resultCode 业务错误等），需要让 finally 走兜底分支
+    let lastDeliverError: unknown = undefined;
+
     try {
         await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
             ctx: inboundCtx,
             cfg,
             dispatcherOptions: {
                 responsePrefix: "",
+                // Logged when normalizeReplyPayload decides to skip a payload (e.g. heartbeat, silent token, empty).
+                onSkip: (payload: unknown, meta: { kind: string; reason: string }) => {
+                    deliverSkippedCount++;
+                    log.info(
+                        `${logPrefix} [deliver] Payload skipped by normalizer kind=${meta.kind} reason=${meta.reason}`,
+                    );
+                },
+                // Logged when deliver throws and the dispatcher catches it (error would otherwise be silently dropped).
+                onError: (err: unknown, meta: { kind: string }) => {
+                    lastDeliverError = err;
+                    log.error(
+                        `${logPrefix} [deliver] Dispatcher caught unhandled error kind=${meta.kind}: ${String(err)}`,
+                    );
+                },
                 deliver: async (payload: ReplyDeliverPayload) => {
                     try {
                         const textPart = (payload.markdown || payload.text || "").trim();
                         const hasMedia =
                             Boolean(payload.mediaUrl?.trim()) ||
                             Boolean(payload.mediaUrls?.some((u) => typeof u === "string" && u.trim()));
-                        if (!textPart && !(hasMedia && !payload.isThinking)) return;
+                        if (!textPart && !(hasMedia && !payload.isThinking)) {
+                            log.info(
+                                `${logPrefix} [deliver] Payload has no sendable content, skipping` +
+                                    ` (isThinking=${payload.isThinking ?? false} hasMedia=${hasMedia})`,
+                            );
+                            return;
+                        }
 
+                        deliverCallCount++;
                         if (isFirstReply) {
                             const ttfr = Date.now() - dispatchStart;
                             log.info(
@@ -454,7 +496,6 @@ async function dispatchMentionedReply(args: {
                         const atIds = [reply.targetUserId] as string[];
 
                         if (!hasFirstReply) {
-                            hasFirstReply = true;
                             clearTimeout(firstReplyTimeout);
                             await sendReplyDeliverBlock(
                                 config,
@@ -466,6 +507,7 @@ async function dispatchMentionedReply(args: {
                                 streamMsgId,
                                 reply,
                             );
+                            hasFirstReply = true; // set after successful send
                             const preview =
                                 textPart.length > 80 ? `${textPart.slice(0, 80)}...` : textPart || "[media]";
                             log.info(
@@ -490,18 +532,69 @@ async function dispatchMentionedReply(args: {
                             `${logPrefix} [send] Additional reply sent via HTTP: groupId=${params.groupId} preview="${preview}"`,
                         );
                     } catch (err: unknown) {
-                        log.error(`${logPrefix} Reply deliver failed: ${String(err)}`);
+                        log.error(`${logPrefix} [deliver] Reply deliver failed: ${String(err)}`);
                         throw err;
                     }
                 },
             },
         });
-        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}`);
+        log.info(
+            `${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}` +
+                ` (delivered=${deliverCallCount} skipped=${deliverSkippedCount})`,
+        );
+    } catch (dispatchErr: unknown) {
+        dispatchError = dispatchErr;
+        log.error(
+            `${logPrefix} [dispatch] Dispatch failed (delivered=${deliverCallCount} skipped=${deliverSkippedCount}): ${String(dispatchErr)}`,
+        );
     } finally {
         clearTimeout(firstReplyTimeout);
+
+        // 兜底原则：
+        // - 有"实际错误"（dispatch 自身异常 / deliver 全部重试后仍失败）且尚未发过任何消息
+        //   → 主动告知用户，以 reason=stop 结束（后台信任已发消息）。
+        // - 无错误也无回复（AI 输出为空 / 全部被 normalizer skip / /reset 类静默命令）
+        //   → 以 reason=no_reply 结束，由后台展示"AI未响应"。
+        if (!hasFirstReply) {
+            const reportableError = dispatchError ?? lastDeliverError;
+            if (reportableError !== undefined) {
+                const errSource = dispatchError !== undefined ? "dispatch" : "deliver";
+                log.warn(
+                    `${logPrefix} [dispatch] ${errSource} error with no prior reply` +
+                        ` (delivered=${deliverCallCount} skipped=${deliverSkippedCount}), sending error notice`,
+                );
+                const replyMeta = buildTargetReplyMeta(params);
+                try {
+                    await sendTextMessage(
+                        config,
+                        currentIdentity.token,
+                        params.groupId,
+                        `当前请求处理时出现异常，请稍后重试。\n错误信息：${String(reportableError)}`,
+                        [replyMeta.targetUserId] as string[],
+                        log,
+                        streamMsgId,
+                        replyMeta,
+                    );
+                    hasFirstReply = true;
+                } catch (fallbackErr: unknown) {
+                    log.error(
+                        `${logPrefix} [dispatch] Failed to send error notice (${errSource} error): ${String(fallbackErr)}`,
+                    );
+                }
+            } else {
+                log.warn(
+                    `${logPrefix} [dispatch] No reply was sent to user` +
+                        ` (delivered=${deliverCallCount} skipped=${deliverSkippedCount}), ending with reason=no_reply`,
+                );
+            }
+        }
+
+        // reason=stop：已通过 HTTP 发送了至少一条回复（含兜底错误消息），后台信任已有消息。
+        // reason=no_reply：本次无任何回复且无异常，后台凭此展示"AI未响应"。
+        const endReason = hasFirstReply ? "stop" : "no_reply";
         try {
-            await streamClient.end(streamMsgId, "stop");
-            log.info(`${logPrefix} [stream] END sent: msgId=${streamMsgId}`);
+            await streamClient.end(streamMsgId, endReason);
+            log.info(`${logPrefix} [stream] END sent: msgId=${streamMsgId} reason=${endReason}`);
         } catch (endErr: unknown) {
             log.error(`${logPrefix} [stream] END failed (msgId=${streamMsgId}): ${String(endErr)}`);
         }

package/src/recommended-system-prompt.ts

@@ -0,0 +1,3 @@
+/** 建议复制到 `channels.xg_cwork_im.systemPrompt`。 */
+export const XG_IM_RECOMMENDED_CHANNEL_SYSTEM_PROMPT =
+    "发文件给用户时，在回复正文里单独写一行 `MEDIA:<路径>`，例如：MEDIA:/workspace/report.pdf。路径支持 /workspace/…、file://…、http(s)://…。OpenClaw 会自动读取该路径并让通道上传，用户可直接在 IM 中下载。不要把路径当作已发送；也不要上传到外部网站。";

package/src/resource-file.ts

@@ -1,253 +1,339 @@
-/**
- * 资源中心整文件上传 + OpenClaw deliver 媒体 URL 拉取
- *
- * 上传地址固定为 `baseUrl + /file/upDownload/uploadWholeFile`，与 IM 同域，使用与发消息相同的 access-token。
- */
-
-import axios from "axios";
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { Log } from "./auth.js";
-
-const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
-
-/** 整文件上传接口路径（拼在 channels.xg_cwork_im.baseUrl 上） */
-export const RESOURCE_UPLOAD_PATH = "/file/upDownload/uploadWholeFile";
-
-export function resolveResourceUploadUrl(baseUrl: string): string {
-    const b = baseUrl.trim();
-    if (!b) throw new Error("[cwork_im] baseUrl is required for resource upload");
-    return new URL(RESOURCE_UPLOAD_PATH, b.endsWith("/") ? b : `${b}/`).href;
-}
-
-/** 从上传接口 JSON 中解析 fileId（兼容常见嵌套 data） */
-export function extractFileIdFromUploadResponse(data: unknown): string | undefined {
-    if (data == null) return undefined;
-    if (typeof data === "string" && data.trim().length > 0) return data.trim();
-    if (typeof data !== "object") return undefined;
-    const o = data as Record<string, unknown>;
-    for (const key of ["fileId", "id", "resourceId", "file_id"]) {
-        const v = o[key];
-        if (typeof v === "string" && v.length > 0) return v;
-    }
-    if (o.data != null) {
-        const nested = extractFileIdFromUploadResponse(o.data);
-        if (nested) return nested;
-    }
-    return undefined;
-}
-
-export function formatFromFilename(filename: string): string {
-    const ext = path.extname(filename).replace(/^\./, "").toLowerCase();
-    if (ext && ext.length <= 16 && /^[a-z0-9]+$/i.test(ext)) return ext;
-    return "bin";
-}
-
-export function displayNameFromUrl(url: string): string {
-    try {
-        if (url.startsWith("file://")) {
-            return path.basename(fileURLToPath(url)) || "file";
-        }
-        const u = new URL(url);
-        const seg = path.basename(u.pathname) || "attachment";
-        return seg.split("?")[0] || "attachment";
-    } catch {
-        return "attachment";
-    }
-}
-
-/** 日志用：截断过长路径/URL */
-export function summarizeMediaRef(ref: string, maxLen = 160): string {
-    const t = ref.trim().replace(/\s+/g, " ");
-    if (t.length <= maxLen) return t;
-    return `${t.slice(0, maxLen)}…(len=${t.length})`;
-}
-
-function isHttpOrHttps(ref: string): boolean {
-    try {
-        const u = new URL(ref.trim());
-        return u.protocol === "http:" || u.protocol === "https:";
-    } catch {
-        return false;
-    }
-}
-
-/**
- * 将字符串解析为可交给 readFile 的本机路径（兼容 Windows / macOS / Linux）。
- * - 使用当前进程的 path.isAbsolute（各 OS 语义正确）。
- * - Windows：Git Bash / MSYS 的 `/c/Users/...`、Cygwin `/cygdrive/c/...`。
- * - 非 Windows：若传入 `D:\...` 形式仍做一次规范化（多用于日志/失败提示，读文件通常会失败）。
- */
-export function resolveLocalFsPath(ref: string): { fsPath: string; via: string } | null {
-    const raw = ref.trim();
-    if (!raw) return null;
-
-    if (process.platform === "win32") {
-        // MSYS/Git Bash: /c/Users/foo → C:\Users\foo（要求 /<盘符>/ 后仍有路径，避免误伤 /Users）
-        const msys = /^\/([a-zA-Z])\/(.+)$/.exec(raw.replace(/\\/g, "/"));
-        if (msys) {
-            const letter = msys[1].toUpperCase();
-            const rest = msys[2].split("/").join(path.win32.sep);
-            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
-            return { fsPath, via: "git-bash-msys" };
-        }
-        const cyg = /^\/cygdrive\/([a-zA-Z])\/(.+)$/i.exec(raw.replace(/\\/g, "/"));
-        if (cyg) {
-            const letter = cyg[1].toUpperCase();
-            const rest = cyg[2].split("/").join(path.win32.sep);
-            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
-            return { fsPath, via: "cygwin" };
-        }
-    }
-
-    if (path.isAbsolute(raw)) {
-        return { fsPath: path.normalize(raw), via: `native-${process.platform}` };
-    }
-
-    // Linux/macOS 上 WSL 互操作常见：/mnt/c/... 已是 posix 绝对路径，上面已命中
-
-    if (process.platform !== "win32" && /^[a-zA-Z]:[/\\]/.test(raw)) {
-        return { fsPath: path.win32.normalize(raw), via: "win-style-path" };
-    }
-
-    return null;
-}
-
-async function readLocalFsIntoBuffer(fsPath: string, maxBytes: number, log?: Log): Promise<{ buffer: Buffer; filename: string }> {
-    const buffer = await readFile(fsPath);
-    if (buffer.length > maxBytes) {
-        throw new Error(`local file size ${buffer.length} exceeds maxAttachmentBytes=${maxBytes}`);
-    }
-    const filename = path.basename(fsPath) || "file";
-    log?.info(`[cwork_im:media] local ok bytes=${buffer.length} name=${filename}`);
-    return { buffer, filename };
-}
-
-export async function downloadMediaBuffer(
-    url: string,
-    maxBytes: number,
-    log?: Log,
-): Promise<{ buffer: Buffer; filename: string }> {
-    const raw = url.trim();
-    log?.info(`[cwork_im:media] resolve ref=${summarizeMediaRef(raw)}`);
-
-    if (raw.startsWith("file://")) {
-        let fsPath: string;
-        try {
-            fsPath = fileURLToPath(raw);
-        } catch (e) {
-            log?.error(`[cwork_im:media] invalid file:// URL: ${summarizeMediaRef(raw)} ${String(e)}`);
-            throw e;
-        }
-        log?.info(`[cwork_im:media] read file:// -> ${summarizeMediaRef(fsPath)}`);
-        try {
-            return await readLocalFsIntoBuffer(fsPath, maxBytes, log);
-        } catch (err: unknown) {
-            log?.error(`[cwork_im:media] readFile failed file:// ${summarizeMediaRef(fsPath)}: ${String(err)}`);
-            throw err;
-        }
-    }
-
-    if (isHttpOrHttps(raw)) {
-        log?.info(`[cwork_im:media] GET ${summarizeMediaRef(raw)}`);
-        try {
-            const res = await axios.get(raw, {
-                responseType: "arraybuffer",
-                timeout: 120_000,
-                maxContentLength: maxBytes,
-                maxBodyLength: maxBytes,
-                validateStatus: (s) => s >= 200 && s < 300,
-            });
-            const buffer = Buffer.from(res.data as ArrayBuffer);
-            let filename = displayNameFromUrl(raw);
-            const cd = res.headers["content-disposition"];
-            if (typeof cd === "string") {
-                const m = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(cd);
-                if (m?.[1]) {
-                    try {
-                        filename = decodeURIComponent(m[1].trim());
-                    } catch {
-                        filename = m[1].trim();
-                    }
-                }
-            }
-            log?.info(`[cwork_im:media] http ok bytes=${buffer.length} name=${filename}`);
-            return { buffer, filename };
-        } catch (err: unknown) {
-            const detail = axios.isAxiosError(err)
-                ? `${err.message}${err.code ? ` axiosCode=${err.code}` : ""}${err.response?.status != null ? ` httpStatus=${err.response.status}` : ""}`
-                : String(err);
-            log?.error(`[cwork_im:media] http failed ref=${summarizeMediaRef(raw)}: ${detail}`);
-            throw err;
-        }
-    }
-
-    const resolved = resolveLocalFsPath(raw);
-    if (resolved) {
-        log?.info(`[cwork_im:media] local via=${resolved.via} -> ${summarizeMediaRef(resolved.fsPath)}`);
-        try {
-            return await readLocalFsIntoBuffer(resolved.fsPath, maxBytes, log);
-        } catch (err: unknown) {
-            log?.error(`[cwork_im:media] readFile failed ${summarizeMediaRef(resolved.fsPath)}: ${String(err)}`);
-            throw err;
-        }
-    }
-
-    const hint =
-        "请使用 http(s)、file://（三系统通用），或本机绝对路径：Windows C:\\\\... / UNC；macOS/Linux /Users、/home、/mnt/c/...（WSL）；Windows 下 Git Bash 可用 /c/...";
-    log?.error(`[cwork_im:media] unsupported ref=${summarizeMediaRef(raw)} (${hint})`);
-    throw new Error(`[cwork_im] 无法读取媒体（${hint}）: ${summarizeMediaRef(raw)}`);
-}
-
-/**
- * multipart 上传整文件，返回 fileId 与字节数。
- */
-export async function uploadWholeResourceFile(args: {
-    fileUploadUrl: string;
-    token: string;
-    buffer: Buffer;
-    filename: string;
-    formField: string;
-    log?: Log;
-}): Promise<{ fileId: string; size: number }> {
-    const { fileUploadUrl, token, buffer, filename, formField, log } = args;
-    const blob = new Blob([new Uint8Array(buffer)]);
-    const form = new FormData();
-    form.append(formField, blob, filename);
-
-    log?.info(`[cwork_im:upload] POST ${fileUploadUrl} field=${formField} name=${filename} bytes=${buffer.length}`);
-
-    const res = await fetch(fileUploadUrl, {
-        method: "POST",
-        headers: {
-            "access-token": token,
-        },
-        body: form,
-    });
-
-    const rawText = await res.text();
-    let json: unknown;
-    try {
-        json = rawText ? JSON.parse(rawText) : undefined;
-    } catch {
-        json = undefined;
-    }
-
-    if (!res.ok) {
-        log?.error(`[cwork_im:upload] HTTP ${res.status} body=${rawText.slice(0, 500)}`);
-        throw new Error(`upload HTTP ${res.status}: ${rawText.slice(0, 500)}`);
-    }
-
-    const fileId = extractFileIdFromUploadResponse(json ?? rawText);
-    if (!fileId) {
-        log?.error(`[cwork_im:upload] missing fileId in body=${rawText.slice(0, 500)}`);
-        throw new Error(`upload response missing fileId: ${rawText.slice(0, 500)}`);
-    }
-
-    return { fileId, size: buffer.length };
-}
-
-export function resolveMaxAttachmentBytes(config: { maxAttachmentBytes?: number }): number {
-    return config.maxAttachmentBytes ?? DEFAULT_MAX_BYTES;
-}
+/**
+ * 资源中心整文件上传 + OpenClaw deliver 媒体 URL 拉取
+ *
+ * 上传地址固定为 `baseUrl + /file/upDownload/uploadWholeFile`，与 IM 同域，使用与发消息相同的 access-token。
+ */
+
+import axios from "axios";
+import { File } from "node:buffer";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Log } from "./auth.js";
+
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+
+/** 整文件上传接口路径（拼在 channels.xg_cwork_im.baseUrl 上） */
+export const RESOURCE_UPLOAD_PATH = "/file/upDownload/uploadWholeFile";
+
+export function resolveResourceUploadUrl(baseUrl: string): string {
+    const b = baseUrl.trim();
+    if (!b) throw new Error("[cwork_im] baseUrl is required for resource upload");
+    return new URL(RESOURCE_UPLOAD_PATH, b.endsWith("/") ? b : `${b}/`).href;
+}
+
+/** 从上传接口 JSON 中解析 fileId（兼容常见嵌套 data） */
+export function extractFileIdFromUploadResponse(data: unknown): string | undefined {
+    if (data == null) return undefined;
+    if (typeof data === "string" && data.trim().length > 0) return data.trim();
+    if (typeof data !== "object") return undefined;
+    const o = data as Record<string, unknown>;
+    for (const key of ["fileId", "id", "resourceId", "file_id"]) {
+        const v = o[key];
+        if (typeof v === "string" && v.length > 0) return v;
+    }
+    if (o.data != null) {
+        const nested = extractFileIdFromUploadResponse(o.data);
+        if (nested) return nested;
+    }
+    return undefined;
+}
+
+export function formatFromFilename(filename: string): string {
+    const ext = path.extname(filename).replace(/^\./, "").toLowerCase();
+    if (ext && ext.length <= 16 && /^[a-z0-9]+$/i.test(ext)) return ext;
+    return "bin";
+}
+
+/** 仅当含 %XX 序列时 decodeURIComponent，避免对已解码的 Unicode 再 decode 抛错 */
+export function safeDecodeUriFilenameSegment(segment: string): string {
+    const s = segment.trim();
+    if (!s) return s;
+    if (!/%[0-9A-Fa-f]{2}/.test(s)) return s;
+    try {
+        return decodeURIComponent(s.replace(/\+/g, " "));
+    } catch {
+        return s;
+    }
+}
+
+/**
+ * 从 HTTP Content-Disposition 解析文件名（优先 RFC 5987 `filename*=` UTF-8，再普通 filename=）。
+ */
+export function parseFilenameFromContentDisposition(header: string | undefined): string | undefined {
+    if (header == null || typeof header !== "string") return undefined;
+    const h = header.trim();
+    if (!h) return undefined;
+
+    const star = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;\r\n]+)/i.exec(h);
+    if (star?.[1]) {
+        const v = star[1].trim();
+        const decoded = safeDecodeUriFilenameSegment(v);
+        if (decoded) return decoded;
+    }
+
+    const quoted = /filename\s*=\s*"((?:[^"\\]|\\.)*)"/i.exec(h);
+    if (quoted?.[1]) {
+        const inner = quoted[1].replace(/\\(.)/g, "$1").trim();
+        if (inner) return safeDecodeUriFilenameSegment(inner);
+    }
+
+    const unquoted = /filename\s*=\s*([^;\r\n]+)/i.exec(h);
+    if (unquoted?.[1]) {
+        let v = unquoted[1].trim().replace(/^["']|["']$/g, "");
+        if (v.toLowerCase().startsWith("utf-8''")) v = v.slice(7);
+        if (v) return safeDecodeUriFilenameSegment(v);
+    }
+
+    return undefined;
+}
+
+export function displayNameFromUrl(url: string): string {
+    try {
+        if (url.startsWith("file://")) {
+            return path.basename(fileURLToPath(url)) || "file";
+        }
+        const u = new URL(url);
+        const qName = u.searchParams.get("filename") ?? u.searchParams.get("name");
+        if (qName?.trim()) {
+            return safeDecodeUriFilenameSegment(qName.trim()) || "attachment";
+        }
+        const pathname = u.pathname || "/";
+        const last = pathname.split("/").filter(Boolean).pop() ?? "";
+        const base = safeDecodeUriFilenameSegment(last.split("?")[0] || "");
+        return base || "attachment";
+    } catch {
+        return "attachment";
+    }
+}
+
+/** 日志用：截断过长路径/URL */
+export function summarizeMediaRef(ref: string, maxLen = 160): string {
+    const t = ref.trim().replace(/\s+/g, " ");
+    if (t.length <= maxLen) return t;
+    return `${t.slice(0, maxLen)}…(len=${t.length})`;
+}
+
+function isHttpOrHttps(ref: string): boolean {
+    try {
+        const u = new URL(ref.trim());
+        return u.protocol === "http:" || u.protocol === "https:";
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * 将字符串解析为可交给 readFile 的本机路径（兼容 Windows / macOS / Linux）。
+ * - 使用当前进程的 path.isAbsolute（各 OS 语义正确）。
+ * - Windows：Git Bash / MSYS 的 `/c/Users/...`、Cygwin `/cygdrive/c/...`。
+ * - 非 Windows：若传入 `D:\...` 形式仍做一次规范化（多用于日志/失败提示，读文件通常会失败）。
+ */
+export function resolveLocalFsPath(ref: string): { fsPath: string; via: string } | null {
+    const raw = ref.trim();
+    if (!raw) return null;
+
+    if (process.platform === "win32") {
+        // MSYS/Git Bash: /c/Users/foo → C:\Users\foo（要求 /<盘符>/ 后仍有路径，避免误伤 /Users）
+        const msys = /^\/([a-zA-Z])\/(.+)$/.exec(raw.replace(/\\/g, "/"));
+        if (msys) {
+            const letter = msys[1].toUpperCase();
+            const rest = msys[2].split("/").join(path.win32.sep);
+            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
+            return { fsPath, via: "git-bash-msys" };
+        }
+        const cyg = /^\/cygdrive\/([a-zA-Z])\/(.+)$/i.exec(raw.replace(/\\/g, "/"));
+        if (cyg) {
+            const letter = cyg[1].toUpperCase();
+            const rest = cyg[2].split("/").join(path.win32.sep);
+            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
+            return { fsPath, via: "cygwin" };
+        }
+    }
+
+    if (path.isAbsolute(raw)) {
+        return { fsPath: path.normalize(raw), via: `native-${process.platform}` };
+    }
+
+    // Linux/macOS 上 WSL 互操作常见：/mnt/c/... 已是 posix 绝对路径，上面已命中
+
+    if (process.platform !== "win32" && /^[a-zA-Z]:[/\\]/.test(raw)) {
+        return { fsPath: path.win32.normalize(raw), via: "win-style-path" };
+    }
+
+    return null;
+}
+
+async function readLocalFsIntoBuffer(fsPath: string, maxBytes: number, log?: Log): Promise<{ buffer: Buffer; filename: string }> {
+    const buffer = await readFile(fsPath);
+    if (buffer.length > maxBytes) {
+        throw new Error(`local file size ${buffer.length} exceeds maxAttachmentBytes=${maxBytes}`);
+    }
+    const filename = path.basename(fsPath) || "file";
+    log?.info(`[cwork_im:media] local ok bytes=${buffer.length} name=${filename}`);
+    return { buffer, filename };
+}
+
+/**
+ * 将 OpenClaw 约定的 `/workspace/<rel>` 路径解析为本机绝对路径（跨平台）。
+ *
+ * OpenClaw 在所有平台启动时均会 chdir 到 workspace 目录，因此
+ * `process.cwd()` 即为 workspace 根，/workspace/<rel> 等价于 cwd/<rel>：
+ *   - Windows : C:\Users\..\.openclaw\workspace\<rel>
+ *   - macOS   : ~/.openclaw/workspace/<rel>
+ *   - Linux容器: /workspace/<rel>（cwd=/workspace，path.join 结果不变）
+ *
+ * 返回 null 表示路径不符合 /workspace/ 格式。
+ */
+export function resolveWorkspacePrefixPath(raw: string): string | null {
+    if (!raw.startsWith("/workspace/") && raw !== "/workspace") return null;
+    const rel = raw.startsWith("/workspace/") ? raw.slice("/workspace/".length) : "";
+    const cwd = process.cwd();
+    return rel ? path.join(cwd, rel) : cwd;
+}
+
+export async function downloadMediaBuffer(
+    url: string,
+    maxBytes: number,
+    log?: Log,
+): Promise<{ buffer: Buffer; filename: string }> {
+    const raw = url.trim();
+    log?.info(`[cwork_im:media] resolve ref=${summarizeMediaRef(raw)}`);
+
+    // Handle OpenClaw /workspace/ convention: map to actual workspace directory.
+    const workspaceResolved = resolveWorkspacePrefixPath(raw);
+    if (workspaceResolved && workspaceResolved !== raw) {
+        log?.info(`[cwork_im:media] /workspace/ -> ${summarizeMediaRef(workspaceResolved)}`);
+        try {
+            return await readLocalFsIntoBuffer(workspaceResolved, maxBytes, log);
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:media] readFile failed /workspace/ ${summarizeMediaRef(workspaceResolved)}: ${String(err)}`);
+            throw err;
+        }
+    }
+
+    if (raw.startsWith("file://")) {
+        let fsPath: string;
+        try {
+            fsPath = fileURLToPath(raw);
+        } catch (e) {
+            log?.error(`[cwork_im:media] invalid file:// URL: ${summarizeMediaRef(raw)} ${String(e)}`);
+            throw e;
+        }
+        log?.info(`[cwork_im:media] read file:// -> ${summarizeMediaRef(fsPath)}`);
+        try {
+            return await readLocalFsIntoBuffer(fsPath, maxBytes, log);
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:media] readFile failed file:// ${summarizeMediaRef(fsPath)}: ${String(err)}`);
+            throw err;
+        }
+    }
+
+    if (isHttpOrHttps(raw)) {
+        log?.info(`[cwork_im:media] GET ${summarizeMediaRef(raw)}`);
+        try {
+            const res = await axios.get(raw, {
+                responseType: "arraybuffer",
+                timeout: 120_000,
+                maxContentLength: maxBytes,
+                maxBodyLength: maxBytes,
+                validateStatus: (s) => s >= 200 && s < 300,
+            });
+            const buffer = Buffer.from(res.data as ArrayBuffer);
+            let filename = displayNameFromUrl(raw);
+            const cdRaw = res.headers["content-disposition"];
+            const cd = Array.isArray(cdRaw) ? cdRaw[0] : cdRaw;
+            if (typeof cd === "string") {
+                const fromCd = parseFilenameFromContentDisposition(cd);
+                if (fromCd) filename = fromCd;
+            }
+            log?.info(`[cwork_im:media] http ok bytes=${buffer.length} name=${filename}`);
+            return { buffer, filename };
+        } catch (err: unknown) {
+            const detail = axios.isAxiosError(err)
+                ? `${err.message}${err.code ? ` axiosCode=${err.code}` : ""}${err.response?.status != null ? ` httpStatus=${err.response.status}` : ""}`
+                : String(err);
+            log?.error(`[cwork_im:media] http failed ref=${summarizeMediaRef(raw)}: ${detail}`);
+            throw err;
+        }
+    }
+
+    const resolved = resolveLocalFsPath(raw);
+    if (resolved) {
+        log?.info(`[cwork_im:media] local via=${resolved.via} -> ${summarizeMediaRef(resolved.fsPath)}`);
+        try {
+            return await readLocalFsIntoBuffer(resolved.fsPath, maxBytes, log);
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:media] readFile failed ${summarizeMediaRef(resolved.fsPath)}: ${String(err)}`);
+            throw err;
+        }
+    }
+
+    const hint =
+        "请使用 http(s)、file://（三系统通用），或本机绝对路径：Windows C:\\\\... / UNC；macOS/Linux /Users、/home、/mnt/c/...（WSL）；Windows 下 Git Bash 可用 /c/...";
+    log?.error(`[cwork_im:media] unsupported ref=${summarizeMediaRef(raw)} (${hint})`);
+    throw new Error(`[cwork_im] 无法读取媒体（${hint}）: ${summarizeMediaRef(raw)}`);
+}
+
+/**
+ * multipart 上传整文件，返回 fileId 与字节数。
+ */
+export async function uploadWholeResourceFile(args: {
+    fileUploadUrl: string;
+    token: string;
+    buffer: Buffer;
+    filename: string;
+    formField: string;
+    log?: Log;
+}): Promise<{ fileId: string; size: number }> {
+    const { fileUploadUrl, token, buffer, filename, formField, log } = args;
+    const form = new FormData();
+    // 使用 File 携带 UTF-8 文件名，避免部分环境下 Blob+第三参在 multipart 里被错误编码导致服务端乱码
+    const file = new File([buffer], filename, { type: "application/octet-stream" });
+    form.append(formField, file);
+
+    log?.info(`[cwork_im:upload] POST ${fileUploadUrl} field=${formField} name=${filename} bytes=${buffer.length}`);
+
+    const res = await fetch(fileUploadUrl, {
+        method: "POST",
+        headers: {
+            "access-token": token,
+        },
+        body: form,
+    });
+
+    const rawText = await res.text();
+    let json: unknown;
+    try {
+        json = rawText ? JSON.parse(rawText) : undefined;
+    } catch {
+        json = undefined;
+    }
+
+    if (!res.ok) {
+        log?.error(`[cwork_im:upload] HTTP ${res.status} body=${rawText.slice(0, 500)}`);
+        throw new Error(`upload HTTP ${res.status}: ${rawText.slice(0, 500)}`);
+    }
+
+    // Unified IM API response: { data, resultCode: 1, resultMsg: "" } — resultCode=1 means success.
+    if (json && typeof json === "object") {
+        const j = json as Record<string, unknown>;
+        if (j.resultCode !== undefined && j.resultCode !== 1) {
+            const msg = `upload IM API error resultCode=${j.resultCode}${j.resultMsg ? ` resultMsg=${j.resultMsg}` : ""}`;
+            log?.error(`[cwork_im:upload] ${msg} body=${rawText.slice(0, 500)}`);
+            throw new Error(msg);
+        }
+    }
+
+    const fileId = extractFileIdFromUploadResponse(json ?? rawText);
+    if (!fileId) {
+        log?.error(`[cwork_im:upload] missing fileId in body=${rawText.slice(0, 500)}`);
+        throw new Error(`upload response missing fileId: ${rawText.slice(0, 500)}`);
+    }
+
+    return { fileId, size: buffer.length };
+}
+
+export function resolveMaxAttachmentBytes(config: { maxAttachmentBytes?: number }): number {
+    return config.maxAttachmentBytes ?? DEFAULT_MAX_BYTES;
+}

package/src/send-group-message-tool.ts

@@ -1,11 +1,10 @@
 /**
- * XG-IM 发送群消息工具（供 AI 按需调用）
+ * XG-IM「主动推消息」工具（供 OpenClaw 在非对话场景下调用）
  *
- * 适用场景：
- * - Cron 定时任务主动推送通知
- * - AI 分析后需要主动发起提醒（无需用户先 @ 机器人）
+ * 用途：定时任务、Cron、后台任务等需要 **经本 channel 主动把结果推送到 IM 群** 时，发一条纯文本。
+ * **不用于**用户正通过 IM 与助手聊天时的回合内回复——那种情况走正常助手回复流，用不上本工具。
  *
- * 通过 api.registerTool() 注入，工具内部自动获取机器人 token，AI 无需感知鉴权细节。
+ * 通过 api.registerTool() 注入，工具内部自动获取机器人 token。
  */
 
 import { Type, type Static } from "@sinclair/typebox";
@@ -29,7 +28,7 @@ const SendGroupMessageParams = Type.Object({
         }),
     ),
     text: Type.String({
-        description: "要发送的消息内容（纯文本）",
+        description: "要发送的消息内容（仅纯文本，不支持附件/文件）",
     }),
     atUserIds: Type.Optional(
         Type.Array(Type.String(), {
@@ -41,19 +40,18 @@ const SendGroupMessageParams = Type.Object({
 // ─── 工具构建函数 ─────────────────────────────────────────────────────────────
 
 /**
- * 构建发送群消息工具对象。
- * 由 index.ts 在 register() 里调用，config 在注册时捕获进闭包，
- * 工具执行时自动调用 getToken(config) 获取机器人 token。
+ * 构建「主动推送群消息」工具（纯文本）。
+ * 由 index.ts 在 register() 里调用。
  */
 export function buildSendGroupMessageTool(config: XgImConfig): AnyAgentTool {
     return {
         name: "xg_cwork_im_send_group_message",
-        label: "【xg_cwork_im】发送群聊消息",
+        label: "【xg_cwork_im】主动推送群消息（纯文本）",
         description: [
-            "【仅限 xg_cwork_im 通道】向指定 IM 群聊发送一条消息。",
-            "适用于定时任务主动推送通知、AI 分析后发起提醒等场景。",
-            "消息将以机器人身份发出，可选择 @ 特定用户。",
-            "groupId 为 IM 群组的唯一 ID（不是群名称），通常从当前对话的 group_channel 字段中解析（格式：agent:main:xg_cwork_im:group:<groupId>）。",
+            "【用途】仅用于 OpenClaw **主动推消息**：例如定时任务 / Cron / 后台任务完成后，经 xg_cwork_im 向群里发一条**纯文字**结果或通知。",
+            "【不要用错】用户正在 IM 里和助手**对话**时，**不要**用本工具回话——对话回复由 OpenClaw 正常走 channel，**用不上**本工具。",
+            "【发文件】本工具不能发附件。用户要「发报告/发文件」时，在**对用户的助手回复**里用 **mediaUrl(s)** 指向 workspace 或 file://；**禁止**为发文件上传到 tmpfiles 等外站。",
+            "【参数】groupId 为 IM 群唯一 ID；主动推送时若需告知某人，可填 atUserIds。",
         ].join("\n"),
         parameters: SendGroupMessageParams,
         async execute(_toolCallId: string, params: Static<typeof SendGroupMessageParams>) {

package/src/send-service.ts

@@ -27,6 +27,36 @@ function formatDeliverError(err: unknown): string {
     return String(err);
 }
 
+/**
+ * 发消息接口的重试参数。
+ *
+ * 总尝试次数 = 1（首次） + IM_SEND_MAX_RETRIES（重试） = 6，间隔约 1 秒。
+ * 仅对网络层瞬时错误（无响应 / 5xx / 408 / 429）重试；4xx 与业务 resultCode 错误视为永久失败，立即抛出。
+ */
+const IM_SEND_MAX_RETRIES = 5;
+const IM_SEND_RETRY_DELAY_MS = 1_000;
+
+function delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 判断错误是否值得重试。
+ *
+ * - axios 网络错误 / 超时 / 5xx / 408 / 429 → 重试
+ * - 4xx（其它）/ 业务 resultCode 错误（普通 Error）→ 永久失败，不重试
+ */
+function isRetryableSendError(err: unknown): boolean {
+    if (axios.isAxiosError(err)) {
+        const status = err.response?.status;
+        if (status === undefined) return true;
+        if (status >= 500) return true;
+        if (status === 408 || status === 429) return true;
+        return false;
+    }
+    return false;
+}
+
 async function postImMessage(
     config: XgImConfig,
     token: string,
@@ -47,24 +77,62 @@ async function postImMessage(
         log?.debug?.(`[cwork_im:send] Request body: ${JSON.stringify(full)}`);
     }
 
-    try {
-        const res = await axios.post(url, full, {
-            headers: {
-                "Content-Type": "application/json",
-                "access-token": token,
-            },
-            timeout: 10_000,
-        });
+    const totalAttempts = 1 + IM_SEND_MAX_RETRIES;
+    let lastErr: unknown = undefined;
+
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        try {
+            const res = await axios.post(url, full, {
+                headers: {
+                    "Content-Type": "application/json",
+                    "access-token": token,
+                },
+                timeout: 10_000,
+            });
 
-        log?.info(`[cwork_im:send] Response status=${res.status}`);
-        if (config.debug) {
-            log?.debug?.(`[cwork_im:send] Response body: ${JSON.stringify(res.data)}`);
+            log?.info(`[cwork_im:send] Response status=${res.status} (attempt=${attempt}/${totalAttempts})`);
+            if (config.debug) {
+                log?.debug?.(`[cwork_im:send] Response body: ${JSON.stringify(res.data)}`);
+            }
+
+            // Detect business-level errors that arrive with HTTP 200.
+            // IM API unified response: { data, resultCode: 1, resultMsg: "" } — resultCode=1 means success.
+            const d = res.data;
+            if (d && typeof d === "object") {
+                const resultCode = (d as Record<string, unknown>).resultCode;
+                const resultMsg = (d as Record<string, unknown>).resultMsg;
+                if (resultCode !== undefined && resultCode !== 1) {
+                    throw new Error(
+                        `IM API error resultCode=${resultCode}${resultMsg ? ` resultMsg=${resultMsg}` : ""}`,
+                    );
+                }
+            }
+            return;
+        } catch (err: unknown) {
+            lastErr = err;
+            const msg = formatDeliverError(err);
+            const retryable = isRetryableSendError(err);
+            const isLast = attempt >= totalAttempts;
+
+            if (!retryable || isLast) {
+                log?.error(
+                    `[cwork_im:send] Failed to send message to groupId=${groupId} ` +
+                        `(attempt=${attempt}/${totalAttempts}, retryable=${retryable}): ${msg}`,
+                );
+                throw err;
+            }
+
+            const warn = log?.warn ?? log?.info;
+            warn?.(
+                `[cwork_im:send] Send failed (attempt=${attempt}/${totalAttempts}), ` +
+                    `retrying in ${IM_SEND_RETRY_DELAY_MS}ms: ${msg}`,
+            );
+            await delay(IM_SEND_RETRY_DELAY_MS);
         }
-    } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        log?.error(`[cwork_im:send] Failed to send message to groupId=${groupId}: ${msg}`);
-        throw err;
     }
+
+    // 理论上不可达：上面循环里要么 return 要么 throw。这里只是给 TS 一个安全兜底。
+    throw lastErr ?? new Error("[cwork_im:send] Send failed after retries");
 }
 
 /** OpenClaw dispatch deliver 单块载荷：文本 + 可选媒体 URL（与 plugin-sdk 约定对齐）。 */
@@ -141,21 +209,21 @@ export async function sendReplyDeliverBlock(
             return;
         } catch (err: unknown) {
             log?.error(`[cwork_im:send] FILE deliver failed, fallback to text if any: ${formatDeliverError(err)}`);
-            if (textToSend.length > 0) {
-                await postImMessage(
-                    config,
-                    token,
-                    groupId,
-                    {
-                        type: "RICH_TEXT",
-                        text: `${textToSend}\n\n（媒体未发出：${formatDeliverError(err)}）`,
-                        ...(msgId ? { msgId } : {}),
-                        ...(reply ? { reply } : {}),
-                    },
-                    atUserIds,
-                    log,
-                );
-            }
+            const errNote = `（文件发送失败：${formatDeliverError(err)}）`;
+            const fallbackText = textToSend.length > 0 ? `${textToSend}\n\n${errNote}` : errNote;
+            await postImMessage(
+                config,
+                token,
+                groupId,
+                {
+                    type: "RICH_TEXT",
+                    text: fallbackText,
+                    ...(msgId ? { msgId } : {}),
+                    ...(reply ? { reply } : {}),
+                },
+                atUserIds,
+                log,
+            );
             return;
         }
     }

package/src/types.ts

@@ -29,7 +29,9 @@ export type XgCworkImPluginModule = XgImPluginModule;
 
 /** 单个机器人账户配置 */
 export interface XgImAccountConfig {
-    /** 机器人 appKey，从 IM 后台注册获取 */
+    /** 机器人 Key（新字段，优先于 appKey） */
+    robotKey?: string;
+    /** 机器人 appKey，从 IM 后台注册获取（已改名为 robotKey，此字段保留兼容旧配置） */
     appKey?: string;
     /** 对应 OpenClaw 的 Agent ID，默认为 'main' */
     agentId?: string;
@@ -65,7 +67,9 @@ export interface XgImConfig extends OpenClawConfig {
     /** 多账户列表 */
     accounts?: Record<string, XgImAccountConfig>;
 
-    /** 机器人 appKey（单账户模式） */
+    /** 机器人 Key（新字段，优先于 appKey，单账户模式） */
+    robotKey?: string;
+    /** 机器人 appKey（单账户模式，已改名为 robotKey，此字段保留兼容旧配置） */
     appKey?: string;
     /** 对应 OpenClaw 的 Agent ID（单账户模式） */
     agentId?: string;
@@ -289,6 +293,7 @@ export type SendMessageBody =
           toUserId?: string;
           text: string;
           atUserIds?: string[];
+          /** 流式占位消息 ID，用于将回复更新到对应的占位消息上 */
           msgId?: string;
           reply?: SendMessageReply;
       }
@@ -299,6 +304,7 @@ export type SendMessageBody =
           text: string;
           attachments: SendMessageFileAttachment[];
           atUserIds?: string[];
+          /** 流式占位消息 ID，用于将回复更新到对应的占位消息上 */
           msgId?: string;
           reply?: SendMessageReply;
       };