openclaw-elys 1.8.4 → 1.10.6

package/README.md

@@ -147,6 +147,24 @@ OpenClaw 支持 block streaming，需要在 `~/.openclaw/openclaw.json` 中配
 }
 ```
 
+#### Push（上行，主动推送）
+
+定时任务/Cron 触发的主动消息，不关联任何 command。
+
+```json
+{
+  "id": "push_xxx",
+  "type": "push",
+  "timestamp": 1709827200,
+  "text": "这是定时任务的结果",
+  "media_url": "https://example.com/generated.png",
+  "media_urls": ["https://example.com/1.png"]
+}
+```
+
+- 与 `stream` 的区别：`push` 没有对应的 command_id，是 AI 主动发起的消息
+- 场景：用户设置了"每天早上给我一句励志名言"等定时任务
+
 ### Supported Media Types / 支持的媒体类型
 
 | 类型 | MIME type | 说明 |

package/dist/index.d.ts

@@ -3,8 +3,9 @@ export { elysPlugin } from "./src/channel.js";
 export { monitorElysProvider } from "./src/monitor.js";
 export { registerDevice } from "./src/register.js";
 export { ElysDeviceMQTTClient } from "./src/mqtt-client.js";
+export { TOSUploader } from "./src/tos-upload.js";
 export { loadCredentials, saveCredentials, deleteCredentials, loadGatewayUrl, } from "./src/config.js";
-export type { DeviceCredentials, CommandMessage, AckMessage, ResultMessage, ElysConfig, } from "./src/types.js";
+export type { DeviceCredentials, CommandMessage, AckMessage, StreamMessage, PushMessage, ElysConfig, } from "./src/types.js";
 declare const plugin: {
     id: string;
     name: string;

package/dist/index.js

@@ -4,6 +4,7 @@ export { elysPlugin } from "./src/channel.js";
 export { monitorElysProvider } from "./src/monitor.js";
 export { registerDevice } from "./src/register.js";
 export { ElysDeviceMQTTClient } from "./src/mqtt-client.js";
+export { TOSUploader } from "./src/tos-upload.js";
 export { loadCredentials, saveCredentials, deleteCredentials, loadGatewayUrl, } from "./src/config.js";
 const plugin = {
     id: "openclaw-elys",
@@ -13,6 +14,39 @@ const plugin = {
     register(api) {
         setElysRuntime(api.runtime);
         api.registerChannel({ plugin: elysPlugin });
+        // Diagnostic: intercept registry changes
+        try {
+            const REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");
+            const g = globalThis;
+            const state = g[REGISTRY_STATE];
+            if (state && !state.__elysProxied) {
+                state.__elysProxied = true;
+                const origRegistry = state.registry;
+                let registryRef = origRegistry;
+                Object.defineProperty(state, "registry", {
+                    get() {
+                        return registryRef;
+                    },
+                    set(newVal) {
+                        const oldChannels = registryRef?.channels?.length ?? 0;
+                        const newChannels = newVal?.channels?.length ?? 0;
+                        const newHasElys = newVal?.channels?.some((e) => e.plugin.id === "elys") ?? false;
+                        const newElysOutbound = newVal?.channels?.find((e) => e.plugin.id === "elys")?.plugin?.outbound;
+                        const newElysSendText = !!newElysOutbound?.sendText;
+                        console.log(`[elys-diag] REGISTRY SET! oldChannels=${oldChannels} newChannels=${newChannels} ` +
+                            `newHasElys=${newHasElys} newElysSendText=${newElysSendText} ` +
+                            `newChannelIds=${newVal?.channels?.map((c) => c.plugin.id).join(",") ?? "none"} ` +
+                            `stack=${new Error().stack?.split("\n").slice(1, 6).join(" | ")}`);
+                        registryRef = newVal;
+                    },
+                    configurable: true,
+                    enumerable: true,
+                });
+            }
+        }
+        catch (err) {
+            console.log(`[elys-diag] proxy setup failed: ${err}`);
+        }
     },
 };
 export default plugin;

package/dist/src/channel.d.ts

@@ -57,17 +57,48 @@ export declare const elysPlugin: {
             gatewayUrl: string;
         };
     };
+    messaging: {
+        targetResolver: {
+            hint: string;
+            looksLikeId: (raw: string) => boolean;
+        };
+    };
     outbound: {
         deliveryMode: "direct";
         textChunkLimit: number;
+        sendPayload: (ctx: {
+            cfg: Record<string, unknown>;
+            to: string;
+            text: string;
+            accountId?: string | null;
+            payload: {
+                text?: string;
+                mediaUrl?: string;
+                mediaUrls?: string[];
+                [key: string]: unknown;
+            };
+        }) => Promise<{
+            channel: string;
+            messageId: string;
+        }>;
         sendText: (ctx: {
             cfg: Record<string, unknown>;
             to: string;
             text: string;
             accountId?: string | null;
         }) => Promise<{
+            channel: string;
             messageId: string;
+        }>;
+        sendMedia: (ctx: {
+            cfg: Record<string, unknown>;
+            to: string;
+            text: string;
+            mediaUrl: string;
+            accountId?: string | null;
+        }) => Promise<{
             channel: string;
+            messageId: string;
         }>;
     };
     gateway: {

package/dist/src/channel.js

@@ -15,7 +15,7 @@ export const elysPlugin = {
         chatTypes: ["direct"],
         polls: false,
         threads: false,
-        media: false,
+        media: true,
         reactions: false,
         edit: false,
         reply: true,
@@ -44,6 +44,12 @@ export const elysPlugin = {
             gatewayUrl: account.gatewayUrl,
         }),
     },
+    messaging: {
+        targetResolver: {
+            hint: "Use a device ID like d_xxxx",
+            looksLikeId: (raw) => /^d_[a-f0-9]+$/i.test(raw.trim()),
+        },
+    },
     outbound: elysOutbound,
     gateway: {
         startAccount: async (ctx) => {

package/dist/src/monitor.js

@@ -1,12 +1,12 @@
 import { createWriteStream } from "node:fs";
-import { mkdtemp } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { access } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { loadCredentials } from "./config.js";
 import { registerDevice } from "./register.js";
 import { ElysDeviceMQTTClient } from "./mqtt-client.js";
-import { getElysRuntime } from "./runtime.js";
+import { getElysRuntime, setSharedMqttClient } from "./runtime.js";
+import { TOSUploader } from "./tos-upload.js";
 /**
  * The main monitor loop for the Elys channel.
  * Ensures device is registered, then connects to MQTT and dispatches
@@ -32,6 +32,8 @@ export async function monitorElysProvider(opts) {
     }
     // 2. Connect MQTT
     const mqttClient = new ElysDeviceMQTTClient(credentials, log);
+    // 2.5. Initialize TOS uploader for media uploads
+    const tosUploader = new TOSUploader(gatewayUrl, credentials.deviceToken, log);
     // 3. Set up command handler using PluginRuntime (same pattern as feishu)
     const core = getElysRuntime();
     const dispatchReplyFromConfig = core?.channel?.reply?.dispatchReplyFromConfig;
@@ -39,138 +41,166 @@ export async function monitorElysProvider(opts) {
     const finalizeCtx = core?.channel?.reply?.finalizeInboundContext;
     log(`[elys] pluginRuntime available: ${!!core}, dispatchReplyFromConfig: ${!!dispatchReplyFromConfig}, createDispatcher: ${!!createDispatcher}, finalizeCtx: ${!!finalizeCtx}`);
     const commandHandler = async (cmd, signal) => {
-        log(`[elys] executing command: ${cmd.command}`, cmd.args, `media_url=${cmd.media_url ?? "none"}`, `media_urls=${JSON.stringify(cmd.media_urls ?? [])}`);
+        log(`[elys] executing command: ${cmd.command} args=${JSON.stringify(cmd.args)} media_url=${cmd.media_url ?? "none"} media_urls=${JSON.stringify(cmd.media_urls ?? [])}`);
         if (dispatchReplyFromConfig && finalizeCtx && createDispatcher) {
-            try {
-                let seq = 0;
-                let fullText = "";
-                // Download inbound media (user-sent) to local temp files
-                // OpenClaw expects local file paths in MediaPath/MediaUrl, not remote URLs
-                const rawMediaUrls = cmd.media_urls?.length
-                    ? cmd.media_urls
-                    : cmd.media_url
-                        ? [cmd.media_url]
-                        : [];
-                const downloadedPaths = [];
-                const downloadedTypes = [];
-                for (const url of rawMediaUrls) {
+            let seq = 0;
+            let sentDone = false;
+            // Download inbound media (user-sent) to local temp files
+            // OpenClaw expects local file paths in MediaPath/MediaUrl, not remote URLs
+            const rawMediaUrls = cmd.media_urls?.length
+                ? cmd.media_urls
+                : cmd.media_url
+                    ? [cmd.media_url]
+                    : [];
+            const downloadedPaths = [];
+            const downloadedTypes = [];
+            for (const url of rawMediaUrls) {
+                try {
+                    const localPath = await downloadToTemp(url, log);
+                    downloadedPaths.push(localPath);
+                    downloadedTypes.push(cmd.media_type ?? guessMediaType(url));
+                }
+                catch (err) {
+                    log(`[elys] failed to download media ${url}:`, err);
+                }
+            }
+            const inboundCtx = finalizeCtx({
+                Body: formatCommandAsText(cmd),
+                BodyForAgent: formatCommandAsText(cmd),
+                RawBody: formatCommandAsText(cmd),
+                From: credentials.deviceId,
+                To: credentials.deviceId,
+                Surface: "elys",
+                Provider: "elys",
+                ChatType: "direct",
+                MessageSid: cmd.id,
+                AccountId: "default",
+                SessionKey: `elys:${credentials.deviceId}`,
+                CommandAuthorized: true,
+                OriginatingChannel: "elys",
+                OriginatingTo: credentials.deviceId,
+                // Inbound media as local file paths
+                ...(downloadedPaths.length > 0 && {
+                    MediaPath: downloadedPaths[0],
+                    MediaUrl: downloadedPaths[0],
+                    MediaPaths: downloadedPaths,
+                    MediaUrls: downloadedPaths,
+                    MediaType: downloadedTypes[0],
+                    MediaTypes: downloadedTypes,
+                }),
+            });
+            // Deliver callback: always send stream chunks via MQTT
+            const deliver = async (payload, info) => {
+                log(`[elys] deliver: kind=${info.kind} text=${(payload.text ?? "").slice(0, 120)} mediaUrl=${payload.mediaUrl ?? "none"}`);
+                let mediaUrl = payload.mediaUrl?.trim();
+                let mediaUrls = payload.mediaUrls?.filter((u) => u?.trim());
+                // Extract MEDIA: paths from text (OpenClaw embeds them as "MEDIA: /path/to/file")
+                let text = payload.text ?? "";
+                if (!mediaUrl && text.includes("MEDIA:")) {
+                    const extracted = extractMediaPaths(text);
+                    if (extracted.paths.length > 0) {
+                        mediaUrl = extracted.paths[0];
+                        if (extracted.paths.length > 1) {
+                            mediaUrls = [...(mediaUrls ?? []), ...extracted.paths.slice(1)];
+                        }
+                        text = extracted.cleanText;
+                    }
+                }
+                // Upload local media files to TOS (resolve relative paths first)
+                if (mediaUrl && isLocalPath(mediaUrl)) {
                     try {
-                        const localPath = await downloadToTemp(url, log);
-                        downloadedPaths.push(localPath);
-                        downloadedTypes.push(cmd.media_type ?? guessMediaType(url));
+                        const resolved = await resolveMediaPath(mediaUrl);
+                        log(`[elys] resolved media path: ${mediaUrl} → ${resolved}`);
+                        mediaUrl = await tosUploader.uploadFile(resolved);
                     }
                     catch (err) {
-                        log(`[elys] failed to download media ${url}:`, err);
+                        log(`[elys] TOS upload failed for ${mediaUrl}:`, err);
                     }
                 }
-                const inboundCtx = finalizeCtx({
-                    Body: formatCommandAsText(cmd),
-                    BodyForAgent: formatCommandAsText(cmd),
-                    RawBody: formatCommandAsText(cmd),
-                    From: credentials.deviceId,
-                    To: credentials.deviceId,
-                    Surface: "elys",
-                    Provider: "elys",
-                    ChatType: "direct",
-                    MessageSid: cmd.id,
-                    AccountId: "default",
-                    SessionKey: `elys:${credentials.deviceId}`,
-                    CommandAuthorized: true,
-                    OriginatingChannel: "elys",
-                    OriginatingTo: credentials.deviceId,
-                    // Inbound media as local file paths
-                    ...(downloadedPaths.length > 0 && {
-                        MediaPath: downloadedPaths[0],
-                        MediaUrl: downloadedPaths[0],
-                        MediaPaths: downloadedPaths,
-                        MediaUrls: downloadedPaths,
-                        MediaType: downloadedTypes[0],
-                        MediaTypes: downloadedTypes,
-                    }),
-                });
-                // Deliver callback: stream chunks back via MQTT
-                const wantStream = cmd.stream === true;
-                const deliver = async (payload, info) => {
-                    const mediaUrl = payload.mediaUrl?.trim();
-                    const mediaUrls = payload.mediaUrls?.filter((u) => u?.trim());
-                    const hasMedia = Boolean(mediaUrl || mediaUrls?.length);
-                    const media = hasMedia ? { mediaUrl, mediaUrls } : undefined;
-                    if (payload.text || hasMedia) {
-                        if (payload.text)
-                            fullText += payload.text;
-                        if (wantStream || info.kind === "final") {
-                            seq++;
-                            const done = info.kind === "final";
-                            mqttClient.publishStreamChunk(cmd.id, payload.text ?? "", seq, done, media);
-                        }
-                        if (hasMedia) {
-                            log(`[elys] media: ${mediaUrl ?? mediaUrls?.join(", ")}`);
-                        }
-                        if (info.kind === "block") {
-                            log(`[elys] stream chunk #${seq}: ${(payload.text ?? "").slice(0, 80)}...`);
-                        }
-                        else if (info.kind === "final") {
-                            log(`[elys] final reply delivered`);
+                if (mediaUrls?.length) {
+                    mediaUrls = await Promise.all(mediaUrls.map(async (u) => {
+                        if (isLocalPath(u)) {
+                            try {
+                                const resolved = await resolveMediaPath(u);
+                                return await tosUploader.uploadFile(resolved);
+                            }
+                            catch (err) {
+                                log(`[elys] TOS upload failed for ${u}:`, err);
+                                return u;
+                            }
                         }
+                        return u;
+                    }));
+                }
+                const hasMedia = Boolean(mediaUrl || mediaUrls?.length);
+                const media = hasMedia ? { mediaUrl, mediaUrls } : undefined;
+                const done = info.kind === "final";
+                if (text || hasMedia) {
+                    seq++;
+                    mqttClient.publishStreamChunk(cmd.id, text, seq, done, {
+                        ...(media ?? {}),
+                        ...(done && { status: "success" }),
+                    });
+                    if (done)
+                        sentDone = true;
+                    if (hasMedia) {
+                        log(`[elys] media: ${mediaUrl ?? mediaUrls?.join(", ")}`);
                     }
-                    else if (info.kind === "final") {
-                        if (wantStream) {
-                            seq++;
-                            mqttClient.publishStreamChunk(cmd.id, "", seq, true);
-                        }
-                        log(`[elys] final reply delivered (empty)`);
+                    if (done) {
+                        log(`[elys] final reply delivered`);
+                    }
+                    else {
+                        log(`[elys] stream chunk #${seq}: ${text.slice(0, 80)}...`);
                     }
-                };
-                // Create dispatcher + dispatch (same pattern as feishu built-in channel)
-                const { dispatcher, replyOptions, markDispatchIdle } = createDispatcher({
-                    deliver,
-                    onError: (err, info) => {
-                        log(`[elys] dispatch error (${info.kind}):`, err);
-                    },
-                });
-                try {
-                    await dispatchReplyFromConfig({
-                        ctx: inboundCtx,
-                        cfg: opts.config,
-                        dispatcher,
-                        replyOptions,
-                    });
                 }
-                finally {
-                    dispatcher.markComplete();
-                    await dispatcher.waitForIdle().catch(() => { });
-                    markDispatchIdle();
+                else if (done) {
+                    seq++;
+                    mqttClient.publishStreamChunk(cmd.id, "", seq, true, { status: "success" });
+                    sentDone = true;
+                    log(`[elys] final reply delivered (empty)`);
                 }
-                return {
-                    id: cmd.id,
-                    type: "result",
-                    timestamp: Math.floor(Date.now() / 1000),
-                    status: "success",
-                    result: { text: fullText || "done" },
-                };
+            };
+            // Create dispatcher + dispatch (same pattern as feishu built-in channel)
+            const { dispatcher, replyOptions, markDispatchIdle } = createDispatcher({
+                deliver,
+                onError: (err, info) => {
+                    log(`[elys] dispatch error (${info.kind}):`, err);
+                },
+            });
+            try {
+                await dispatchReplyFromConfig({
+                    ctx: inboundCtx,
+                    cfg: opts.config,
+                    dispatcher,
+                    replyOptions,
+                });
             }
             catch (err) {
                 log(`[elys] dispatch error:`, err);
-                return {
-                    id: cmd.id,
-                    type: "result",
-                    timestamp: Math.floor(Date.now() / 1000),
-                    status: "error",
-                    error: err instanceof Error ? err.message : String(err),
-                };
+                const errMsg = err instanceof Error ? err.message : String(err);
+                seq++;
+                mqttClient.publishStreamChunk(cmd.id, errMsg, seq, true, { status: "error", error: errMsg });
+                sentDone = true;
+            }
+            finally {
+                dispatcher.markComplete();
+                await dispatcher.waitForIdle().catch(() => { });
+                markDispatchIdle();
             }
+            // Safety: ensure done=true is always sent
+            if (!sentDone) {
+                seq++;
+                mqttClient.publishStreamChunk(cmd.id, "", seq, true, { status: "success" });
+                log(`[elys] sent final done=true (safety)`);
+            }
+            return;
         }
         // Fallback: echo the command back (no pluginRuntime available)
         log(`[elys] no pluginRuntime — using fallback echo handler`);
-        return {
-            id: cmd.id,
-            type: "result",
-            timestamp: Math.floor(Date.now() / 1000),
-            status: "success",
-            result: { text: `command received: ${cmd.command}` },
-        };
+        mqttClient.publishStreamChunk(cmd.id, `command received: ${cmd.command}`, 1, true, { status: "success" });
     };
     mqttClient.setCommandHandler(commandHandler);
+    setSharedMqttClient(mqttClient);
     await mqttClient.connect(opts.abortSignal);
     // 4. Keep alive until abort
     if (opts.abortSignal) {
@@ -220,15 +250,20 @@ function extFromMimeOrUrl(url, mime) {
     }
     return ".bin";
 }
-let tempDir = null;
+let mediaDir = null;
 async function downloadToTemp(url, log) {
-    if (!tempDir) {
-        tempDir = await mkdtemp(join(tmpdir(), "elys-media-"));
+    if (!mediaDir) {
+        // Use OpenClaw's media directory (~/.openclaw/media/) so that
+        // the image loader's allowlist check passes.
+        const { homedir } = await import("node:os");
+        const openclawMediaDir = join(homedir(), ".openclaw", "media");
+        await import("node:fs/promises").then((fs) => fs.mkdir(openclawMediaDir, { recursive: true }));
+        mediaDir = openclawMediaDir;
     }
     const mime = guessMediaType(url);
     const ext = extFromMimeOrUrl(url, mime);
     const filename = `media_${Date.now()}${ext}`;
-    const filePath = join(tempDir, filename);
+    const filePath = join(mediaDir, filename);
     log(`[elys] downloading media: ${url} → ${filePath}`);
     const resp = await fetch(url);
     if (!resp.ok || !resp.body) {
@@ -240,3 +275,77 @@ async function downloadToTemp(url, log) {
     log(`[elys] downloaded media: ${filePath}`);
     return filePath;
 }
+function isLocalPath(p) {
+    return p.startsWith("/") || p.startsWith("./") || p.startsWith("../");
+}
+/**
+ * Resolve OpenClaw state directory.
+ * Follows the same logic as OpenClaw core: OPENCLAW_STATE_DIR env or ~/.openclaw.
+ */
+function resolveOpenClawStateDir() {
+    if (process.env.OPENCLAW_STATE_DIR) {
+        return process.env.OPENCLAW_STATE_DIR;
+    }
+    const { homedir } = require("node:os");
+    // Support --profile via OPENCLAW_PROFILE env (e.g. ~/.openclaw-dev)
+    const profile = process.env.OPENCLAW_PROFILE;
+    if (profile) {
+        return join(homedir(), `.openclaw-${profile}`);
+    }
+    return join(homedir(), ".openclaw");
+}
+/**
+ * Resolve a relative media path to an absolute path.
+ * OpenClaw skills output paths relative to the agent workspace.
+ * We search all workspace* dirs under the state dir, plus media/ and sandboxes/.
+ */
+async function resolveMediaPath(p) {
+    if (p.startsWith("/"))
+        return p;
+    const { readdir } = await import("node:fs/promises");
+    const stateDir = resolveOpenClawStateDir();
+    const filename = p.replace(/^\.\//, "").replace(/^\.\.\//, "");
+    // Search candidate dirs: all workspace* dirs, media, sandboxes, agents
+    const candidates = [];
+    try {
+        const entries = await readdir(stateDir, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.isDirectory() && (e.name.startsWith("workspace") ||
+                e.name === "media" ||
+                e.name === "sandboxes" ||
+                e.name === "agents")) {
+                candidates.push(join(stateDir, e.name));
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Also try CWD
+    candidates.push(process.cwd());
+    for (const dir of candidates) {
+        const fullPath = join(dir, filename);
+        try {
+            await access(fullPath);
+            return fullPath;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    return resolve(p);
+}
+/**
+ * Extract MEDIA: file paths from text.
+ * OpenClaw embeds media references as "MEDIA: /path/to/file.png" in response text.
+ */
+function extractMediaPaths(text) {
+    const mediaRegex = /MEDIA:\s*(\S+)/g;
+    const paths = [];
+    let match;
+    while ((match = mediaRegex.exec(text)) !== null) {
+        paths.push(match[1]);
+    }
+    const cleanText = text.replace(/MEDIA:\s*\S+/g, "").trim();
+    return { paths, cleanText };
+}

package/dist/src/mqtt-client.d.ts

@@ -1,5 +1,5 @@
-import type { DeviceCredentials, CommandMessage, ResultMessage } from "./types.js";
-export type CommandHandler = (cmd: CommandMessage, signal: AbortSignal) => Promise<ResultMessage>;
+import type { DeviceCredentials, CommandMessage } from "./types.js";
+export type CommandHandler = (cmd: CommandMessage, signal: AbortSignal) => Promise<void>;
 export interface MQTTClientOptions {
     /** Debounce window in ms. Rapid messages within this window are merged. Default: 500 */
     debounceMs?: number;
@@ -37,9 +37,11 @@ export declare class ElysDeviceMQTTClient {
     connect(abortSignal?: AbortSignal): Promise<void>;
     disconnect(): void;
     /** Send a stream chunk (for streaming AI responses) */
-    publishStreamChunk(commandId: string, chunk: string, seq: number, done: boolean, media?: {
+    publishStreamChunk(commandId: string, chunk: string, seq: number, done: boolean, opts?: {
         mediaUrl?: string;
         mediaUrls?: string[];
+        status?: "success" | "error";
+        error?: string;
     }): void;
     private onMessage;
     private flushDebounce;
@@ -49,6 +51,13 @@ export declare class ElysDeviceMQTTClient {
     private mergeCommands;
     private executeCommand;
     private cleanupDedup;
+    /** Send a proactive push message (not a reply to any command) */
+    publishPush(text: string, opts?: {
+        mediaUrl?: string;
+        mediaUrls?: string[];
+    }): void;
+    /** Check if connected */
+    get connected(): boolean;
     private publishAck;
     private publish;
 }

package/dist/src/mqtt-client.js

@@ -123,7 +123,7 @@ export class ElysDeviceMQTTClient {
         }
     }
     /** Send a stream chunk (for streaming AI responses) */
-    publishStreamChunk(commandId, chunk, seq, done, media) {
+    publishStreamChunk(commandId, chunk, seq, done, opts) {
         const msg = {
             id: commandId,
             type: "stream",
@@ -132,10 +132,14 @@ export class ElysDeviceMQTTClient {
             seq,
             done,
         };
-        if (media?.mediaUrl)
-            msg.media_url = media.mediaUrl;
-        if (media?.mediaUrls?.length)
-            msg.media_urls = media.mediaUrls;
+        if (opts?.mediaUrl)
+            msg.media_url = opts.mediaUrl;
+        if (opts?.mediaUrls?.length)
+            msg.media_urls = opts.mediaUrls;
+        if (opts?.status)
+            msg.status = opts.status;
+        if (opts?.error)
+            msg.error = opts.error;
         this.publish(msg);
     }
     // ─── Inbound message pipeline: dedup → ack → debounce → abort → execute ───
@@ -245,7 +249,7 @@ export class ElysDeviceMQTTClient {
         if (!this.commandHandler)
             return;
         try {
-            const result = await Promise.race([
+            await Promise.race([
                 this.commandHandler(cmd, signal),
                 new Promise((_, reject) => {
                     const timer = setTimeout(() => {
@@ -254,7 +258,6 @@ export class ElysDeviceMQTTClient {
                     signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
                 }),
             ]);
-            this.publish(result);
         }
         catch (err) {
             if (signal.aborted) {
@@ -262,13 +265,7 @@ export class ElysDeviceMQTTClient {
                 return;
             }
             const errMsg = err instanceof Error ? err.message : String(err);
-            this.publish({
-                id: cmd.id,
-                type: "result",
-                timestamp: Math.floor(Date.now() / 1000),
-                status: "error",
-                error: errMsg,
-            });
+            this.publishStreamChunk(cmd.id, errMsg, 1, true, { status: "error", error: errMsg });
         }
     }
     cleanupDedup() {
@@ -279,6 +276,25 @@ export class ElysDeviceMQTTClient {
             }
         }
     }
+    /** Send a proactive push message (not a reply to any command) */
+    publishPush(text, opts) {
+        const msg = {
+            id: `push_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            type: "push",
+            timestamp: Math.floor(Date.now() / 1000),
+            text,
+        };
+        if (opts?.mediaUrl)
+            msg.media_url = opts.mediaUrl;
+        if (opts?.mediaUrls?.length)
+            msg.media_urls = opts.mediaUrls;
+        this.publish(msg);
+        this.log(`[elys] published push message: ${msg.id}`);
+    }
+    /** Check if connected */
+    get connected() {
+        return this.client?.connected ?? false;
+    }
     // ─── Outbound helpers ───
     publishAck(commandId) {
         const msg = {

package/dist/src/outbound.d.ts

@@ -1,28 +1,38 @@
-/**
- * Send a text result back to the gateway via MQTT upstream.
- * This is used by the outbound adapter when OpenClaw agent generates a response.
- *
- * In this channel the outbound is handled primarily through the MQTT result messages
- * inside the monitor's command handler. This outbound adapter is the HTTP fallback
- * for cases where we need to push a proactive message.
- */
-export declare function sendTextToGateway(params: {
-    gatewayUrl: string;
-    text: string;
-    deviceId?: string;
-}): Promise<{
-    messageId: string;
-}>;
 export declare const elysOutbound: {
     deliveryMode: "direct";
     textChunkLimit: number;
+    sendPayload: (ctx: {
+        cfg: Record<string, unknown>;
+        to: string;
+        text: string;
+        accountId?: string | null;
+        payload: {
+            text?: string;
+            mediaUrl?: string;
+            mediaUrls?: string[];
+            [key: string]: unknown;
+        };
+    }) => Promise<{
+        channel: string;
+        messageId: string;
+    }>;
     sendText: (ctx: {
         cfg: Record<string, unknown>;
         to: string;
         text: string;
         accountId?: string | null;
     }) => Promise<{
+        channel: string;
         messageId: string;
+    }>;
+    sendMedia: (ctx: {
+        cfg: Record<string, unknown>;
+        to: string;
+        text: string;
+        mediaUrl: string;
+        accountId?: string | null;
+    }) => Promise<{
         channel: string;
+        messageId: string;
     }>;
 };

package/dist/src/outbound.js

@@ -1,44 +1,85 @@
 import { loadCredentials } from "./config.js";
+import { getSharedMqttClient } from "./runtime.js";
+import { TOSUploader } from "./tos-upload.js";
+let cachedUploader = null;
+function isLocalPath(p) {
+    return p.startsWith("/") || p.startsWith("./") || p.startsWith("../");
+}
 /**
- * Send a text result back to the gateway via MQTT upstream.
- * This is used by the outbound adapter when OpenClaw agent generates a response.
- *
- * In this channel the outbound is handled primarily through the MQTT result messages
- * inside the monitor's command handler. This outbound adapter is the HTTP fallback
- * for cases where we need to push a proactive message.
+ * Upload local media paths to TOS, returns remote URLs.
  */
-export async function sendTextToGateway(params) {
-    const credentials = loadCredentials();
-    if (!credentials) {
-        throw new Error("Elys plugin: device not registered");
-    }
-    const deviceId = params.deviceId ?? credentials.deviceId;
-    const resp = await fetch(`${params.gatewayUrl}/api/v1/message/send`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            device_id: deviceId,
-            id: `msg_${Date.now()}`,
-            command: "elys.reply",
-            args: { text: params.text },
-        }),
-    });
-    if (!resp.ok) {
-        throw new Error(`Failed to send message: ${resp.status}`);
+async function resolveMediaUrls(gatewayUrl, deviceToken, urls) {
+    if (urls.length === 0)
+        return [];
+    if (!cachedUploader) {
+        cachedUploader = new TOSUploader(gatewayUrl, deviceToken);
     }
-    return { messageId: `msg_${Date.now()}` };
+    return Promise.all(urls.map(async (u) => {
+        if (isLocalPath(u)) {
+            try {
+                return await cachedUploader.uploadFile(u);
+            }
+            catch {
+                return u;
+            }
+        }
+        return u;
+    }));
 }
 export const elysOutbound = {
     deliveryMode: "direct",
     textChunkLimit: 4000,
+    sendPayload: async (ctx) => {
+        const mqttClient = getSharedMqttClient();
+        if (!mqttClient || !mqttClient.connected) {
+            throw new Error("Elys plugin: MQTT client not connected");
+        }
+        const credentials = loadCredentials();
+        const elysCfg = ctx.cfg?.channels?.elys;
+        const gatewayUrl = (elysCfg?.gatewayUrl ?? "http://localhost:8080").replace(/\/+$/, "");
+        const deviceToken = credentials?.deviceToken ?? "";
+        const text = ctx.payload.text ?? ctx.text ?? "";
+        // Collect media URLs
+        let mediaUrls = ctx.payload.mediaUrls?.length
+            ? [...ctx.payload.mediaUrls]
+            : ctx.payload.mediaUrl
+                ? [ctx.payload.mediaUrl]
+                : [];
+        // Upload local paths to TOS
+        if (deviceToken) {
+            mediaUrls = await resolveMediaUrls(gatewayUrl, deviceToken, mediaUrls);
+        }
+        mqttClient.publishPush(text, {
+            mediaUrl: mediaUrls[0],
+            mediaUrls: mediaUrls.length > 1 ? mediaUrls : undefined,
+        });
+        return { channel: "elys", messageId: `push_${Date.now()}` };
+    },
     sendText: async (ctx) => {
+        const mqttClient = getSharedMqttClient();
+        if (!mqttClient || !mqttClient.connected) {
+            throw new Error("Elys plugin: MQTT client not connected");
+        }
+        mqttClient.publishPush(ctx.text);
+        return { channel: "elys", messageId: `push_${Date.now()}` };
+    },
+    sendMedia: async (ctx) => {
+        const mqttClient = getSharedMqttClient();
+        if (!mqttClient || !mqttClient.connected) {
+            throw new Error("Elys plugin: MQTT client not connected");
+        }
+        const credentials = loadCredentials();
         const elysCfg = ctx.cfg?.channels?.elys;
-        const gatewayUrl = elysCfg?.gatewayUrl ?? "http://localhost:8080";
-        const result = await sendTextToGateway({
-            gatewayUrl,
-            text: ctx.text,
-            deviceId: ctx.to,
+        const gatewayUrl = (elysCfg?.gatewayUrl ?? "http://localhost:8080").replace(/\/+$/, "");
+        const deviceToken = credentials?.deviceToken ?? "";
+        let mediaUrl = ctx.mediaUrl;
+        if (deviceToken && mediaUrl && isLocalPath(mediaUrl)) {
+            const resolved = await resolveMediaUrls(gatewayUrl, deviceToken, [mediaUrl]);
+            mediaUrl = resolved[0] ?? mediaUrl;
+        }
+        mqttClient.publishPush(ctx.text ?? "", {
+            mediaUrl,
         });
-        return { channel: "elys", ...result };
+        return { channel: "elys", messageId: `push_${Date.now()}` };
     },
 };

package/dist/src/runtime.d.ts

@@ -1,2 +1,5 @@
 export declare function setElysRuntime(next: unknown): void;
 export declare function getElysRuntime(): any;
+import type { ElysDeviceMQTTClient } from "./mqtt-client.js";
+export declare function setSharedMqttClient(client: ElysDeviceMQTTClient | null): void;
+export declare function getSharedMqttClient(): ElysDeviceMQTTClient | null;

package/dist/src/runtime.js

@@ -8,3 +8,10 @@ export function setElysRuntime(next) {
 export function getElysRuntime() {
     return runtime;
 }
+let sharedMqttClient = null;
+export function setSharedMqttClient(client) {
+    sharedMqttClient = client;
+}
+export function getSharedMqttClient() {
+    return sharedMqttClient;
+}

package/dist/src/tos-upload.d.ts

@@ -0,0 +1,31 @@
+export interface STSTokenResponse {
+    access_key_id: string;
+    access_key_secret: string;
+    security_token: string;
+    expiration: string;
+    bucket: string;
+    endpoint: string;
+    region: string;
+    cdn_host?: string;
+    upload_prefix: string;
+}
+/**
+ * TOS uploader that caches STS tokens and uploads media files.
+ * Uses Volcengine TOS native signing (TOS4-HMAC-SHA256), not AWS S3 signing.
+ */
+export declare class TOSUploader {
+    private gatewayUrl;
+    private deviceToken;
+    private cachedToken;
+    private log;
+    constructor(gatewayUrl: string, deviceToken: string, log?: (...args: unknown[]) => void);
+    /**
+     * Upload a local file to TOS, returns the public URL (CDN or bucket URL).
+     */
+    uploadFile(localPath: string): Promise<string>;
+    private getToken;
+    /**
+     * Upload to TOS using PutObject with TOS V4 signing (TOS4-HMAC-SHA256).
+     */
+    private putObject;
+}

package/dist/src/tos-upload.js

@@ -0,0 +1,158 @@
+import { createHmac, createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+const MIME_MAP = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".mp4": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".pdf": "application/pdf",
+};
+/**
+ * TOS uploader that caches STS tokens and uploads media files.
+ * Uses Volcengine TOS native signing (TOS4-HMAC-SHA256), not AWS S3 signing.
+ */
+export class TOSUploader {
+    gatewayUrl;
+    deviceToken;
+    cachedToken = null;
+    log;
+    constructor(gatewayUrl, deviceToken, log) {
+        this.gatewayUrl = gatewayUrl.replace(/\/+$/, "");
+        this.deviceToken = deviceToken;
+        this.log = log ?? console.log;
+    }
+    /**
+     * Upload a local file to TOS, returns the public URL (CDN or bucket URL).
+     */
+    async uploadFile(localPath) {
+        const token = await this.getToken();
+        const data = await readFile(localPath);
+        const ext = extname(localPath).toLowerCase();
+        const contentType = MIME_MAP[ext] ?? "application/octet-stream";
+        const filename = `${Date.now()}${ext}`;
+        const objectKey = `${token.upload_prefix}${filename}`;
+        await this.putObject(token, objectKey, data, contentType);
+        // Return CDN URL if configured, otherwise bucket URL
+        if (token.cdn_host) {
+            return `https://${token.cdn_host}/${objectKey}`;
+        }
+        return `https://${token.bucket}.${token.endpoint}/${objectKey}`;
+    }
+    async getToken() {
+        // Return cached token if still valid (with 5 min buffer)
+        if (this.cachedToken) {
+            const bufferMs = 5 * 60 * 1000;
+            if (Date.now() < this.cachedToken.expiresAt - bufferMs) {
+                return this.cachedToken.token;
+            }
+        }
+        const url = `${this.gatewayUrl}/api/v1/device/sts-token`;
+        const resp = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.deviceToken}` },
+        });
+        if (!resp.ok) {
+            throw new Error(`STS token request failed: ${resp.status} ${await resp.text()}`);
+        }
+        const token = (await resp.json());
+        const expiresAt = new Date(token.expiration).getTime();
+        this.cachedToken = { token, expiresAt };
+        this.log(`[elys] STS token acquired, expires: ${token.expiration}`);
+        return token;
+    }
+    /**
+     * Upload to TOS using PutObject with TOS V4 signing (TOS4-HMAC-SHA256).
+     */
+    async putObject(token, objectKey, body, contentType) {
+        const host = `${token.bucket}.${token.endpoint}`;
+        const url = `https://${host}/${objectKey}`;
+        const now = new Date();
+        const headers = {
+            "host": host,
+            "content-type": contentType,
+            "x-tos-content-sha256": "UNSIGNED-PAYLOAD",
+            "x-tos-date": toTosDate(now),
+            "x-tos-acl": "public-read",
+        };
+        if (token.security_token) {
+            headers["x-tos-security-token"] = token.security_token;
+        }
+        const authorization = signTosV4("PUT", `/${objectKey}`, headers, token.access_key_id, token.access_key_secret, token.region, "tos", now);
+        headers["Authorization"] = authorization;
+        this.log(`[elys] TOS PutObject: ${url}`);
+        const resp = await fetch(url, {
+            method: "PUT",
+            headers,
+            body: new Uint8Array(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`TOS PutObject failed: ${resp.status} ${text}`);
+        }
+        this.log(`[elys] uploaded to TOS: ${objectKey}`);
+    }
+}
+// ─── TOS V4 Signing (TOS4-HMAC-SHA256) ───
+const TOS_ALGORITHM = "TOS4-HMAC-SHA256";
+function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function hmacSha256(key, data) {
+    return createHmac("sha256", key).update(data).digest();
+}
+function toTosDate(d) {
+    return d.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+function toDateStamp(d) {
+    return toTosDate(d).slice(0, 8);
+}
+function signTosV4(method, path, headers, accessKeyId, secretAccessKey, region, service, now) {
+    const dateStamp = toDateStamp(now);
+    const tosDate = toTosDate(now);
+    // TOS only signs "host" and "x-tos-*" headers
+    const signedHeaderKeys = Object.keys(headers)
+        .map((k) => k.toLowerCase())
+        .filter((k) => k === "host" || k.startsWith("x-tos-"))
+        .sort();
+    const signedHeaders = signedHeaderKeys.join(";");
+    // Canonical headers
+    const canonicalHeaders = signedHeaderKeys
+        .map((k) => `${k}:${headers[k]?.trim() ?? headers[Object.keys(headers).find((h) => h.toLowerCase() === k)]?.trim()}`)
+        .join("\n") + "\n";
+    // Canonical request (payload hash = UNSIGNED-PAYLOAD)
+    const canonicalRequest = [
+        method,
+        encodeURIPath(path),
+        "", // no query string
+        canonicalHeaders,
+        signedHeaders,
+        "UNSIGNED-PAYLOAD",
+    ].join("\n");
+    // Credential scope: date/region/service/request
+    const credentialScope = `${dateStamp}/${region}/${service}/request`;
+    // String to sign
+    const stringToSign = [
+        TOS_ALGORITHM,
+        tosDate,
+        credentialScope,
+        sha256Hex(canonicalRequest),
+    ].join("\n");
+    // Signing key (no "AWS4" prefix — TOS uses raw secret)
+    const kDate = hmacSha256(secretAccessKey, dateStamp);
+    const kRegion = hmacSha256(kDate, region);
+    const kService = hmacSha256(kRegion, service);
+    const kSigning = hmacSha256(kService, "request");
+    // Signature
+    const signature = hmacSha256(kSigning, stringToSign).toString("hex");
+    return `${TOS_ALGORITHM} Credential=${accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+}
+function encodeURIPath(p) {
+    return p
+        .split("/")
+        .map((s) => encodeURIComponent(s))
+        .join("/");
+}

package/dist/src/types.d.ts

@@ -17,7 +17,7 @@ export interface ResolvedElysAccount {
 }
 export interface MQTTBaseMessage {
     id: string;
-    type: "command" | "ack" | "result" | "stream";
+    type: "command" | "ack" | "result" | "stream" | "push";
     timestamp: number;
 }
 export interface CommandMessage extends MQTTBaseMessage {
@@ -37,14 +37,14 @@ export interface StreamMessage extends MQTTBaseMessage {
     chunk: string;
     done: boolean;
     seq: number;
+    status?: "success" | "error";
+    error?: string;
     media_url?: string;
     media_urls?: string[];
 }
-export interface ResultMessage extends MQTTBaseMessage {
-    type: "result";
-    status: "success" | "error";
-    result?: Record<string, unknown>;
-    error?: string;
+export interface PushMessage extends MQTTBaseMessage {
+    type: "push";
+    text?: string;
     media_url?: string;
     media_urls?: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-elys",
-  "version": "1.8.4",
+  "version": "1.10.6",
   "description": "OpenClaw Elys channel plugin — connects to Elys App",
   "type": "module",
   "main": "dist/index.js",