openclaw-elys 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { elysPlugin } from "./src/channel.js";
+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 { loadCredentials, saveCredentials, deleteCredentials, loadGatewayUrl, } from "./src/config.js";
+export type { DeviceCredentials, CommandMessage, AckMessage, ResultMessage, ElysConfig, } from "./src/types.js";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: "object";
+        properties: {};
+    };
+    register(api: {
+        runtime: unknown;
+        registerChannel: (reg: {
+            plugin: typeof elysPlugin;
+        }) => void;
+    }): void;
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,16 @@
+import { elysPlugin } from "./src/channel.js";
+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 { loadCredentials, saveCredentials, deleteCredentials, loadGatewayUrl, } from "./src/config.js";
+const plugin = {
+    id: "openclaw-elys",
+    name: "Elys",
+    description: "Elys App channel plugin — connects to Elys App via MQTT gateway",
+    configSchema: { type: "object", properties: {} },
+    register(api) {
+        api.registerChannel({ plugin: elysPlugin });
+    },
+};
+export default plugin;

package/dist/src/channel.d.ts

@@ -0,0 +1,89 @@
+import type { ResolvedElysAccount } from "./types.js";
+export declare const elysPlugin: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        docsLabel: string;
+        blurb: string;
+        order: number;
+    };
+    capabilities: {
+        chatTypes: "direct"[];
+        polls: boolean;
+        threads: boolean;
+        media: boolean;
+        reactions: boolean;
+        edit: boolean;
+        reply: boolean;
+    };
+    reload: {
+        configPrefixes: string[];
+    };
+    configSchema: {
+        schema: {
+            type: "object";
+            additionalProperties: boolean;
+            properties: {
+                enabled: {
+                    type: "boolean";
+                };
+                gatewayUrl: {
+                    type: "string";
+                };
+                registerToken: {
+                    type: "string";
+                };
+            };
+        };
+    };
+    config: {
+        listAccountIds: () => string[];
+        resolveAccount: (cfg: Record<string, unknown>, accountId?: string | null) => {
+            accountId: string;
+            enabled: boolean;
+            configured: boolean;
+            gatewayUrl: string;
+            credentials: import("./types.js").DeviceCredentials | null;
+        };
+        isConfigured: (account: ResolvedElysAccount) => boolean;
+        isEnabled: (account: ResolvedElysAccount) => boolean;
+        describeAccount: (account: ResolvedElysAccount) => {
+            accountId: string;
+            enabled: boolean;
+            configured: boolean;
+            gatewayUrl: string;
+        };
+    };
+    outbound: {
+        deliveryMode: "direct";
+        textChunkLimit: number;
+        sendText: (ctx: {
+            cfg: Record<string, unknown>;
+            to: string;
+            text: string;
+            accountId?: string | null;
+        }) => Promise<{
+            messageId: string;
+            channel: string;
+        }>;
+    };
+    gateway: {
+        startAccount: (ctx: {
+            cfg: Record<string, unknown>;
+            accountId: string;
+            account: ResolvedElysAccount;
+            runtime: Record<string, unknown>;
+            abortSignal: AbortSignal;
+            log?: {
+                info: (...args: unknown[]) => void;
+                warn?: (...args: unknown[]) => void;
+                error?: (...args: unknown[]) => void;
+            };
+            setStatus: (status: Record<string, unknown>) => void;
+            channelRuntime?: Record<string, unknown>;
+        }) => Promise<void>;
+    };
+};

package/dist/src/channel.js

@@ -0,0 +1,63 @@
+import { resolveElysAccount } from "./config.js";
+import { elysOutbound } from "./outbound.js";
+export const elysPlugin = {
+    id: "elys",
+    meta: {
+        id: "elys",
+        label: "Elys",
+        selectionLabel: "Elys App",
+        docsPath: "/channels/elys",
+        docsLabel: "elys",
+        blurb: "Elys App integration via MQTT gateway.",
+        order: 80,
+    },
+    capabilities: {
+        chatTypes: ["direct"],
+        polls: false,
+        threads: false,
+        media: false,
+        reactions: false,
+        edit: false,
+        reply: true,
+    },
+    reload: { configPrefixes: ["channels.elys"] },
+    configSchema: {
+        schema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                enabled: { type: "boolean" },
+                gatewayUrl: { type: "string" },
+                registerToken: { type: "string" },
+            },
+        },
+    },
+    config: {
+        listAccountIds: () => ["default"],
+        resolveAccount: (cfg, accountId) => resolveElysAccount(cfg, accountId),
+        isConfigured: (account) => account.configured,
+        isEnabled: (account) => account.enabled,
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            enabled: account.enabled,
+            configured: account.configured,
+            gatewayUrl: account.gatewayUrl,
+        }),
+    },
+    outbound: elysOutbound,
+    gateway: {
+        startAccount: async (ctx) => {
+            const { monitorElysProvider } = await import("./monitor.js");
+            const account = resolveElysAccount(ctx.cfg, ctx.accountId);
+            ctx.setStatus({ accountId: ctx.accountId });
+            ctx.log?.info(`starting elys[${ctx.accountId}] (gateway: ${account.gatewayUrl})`);
+            return monitorElysProvider({
+                config: ctx.cfg,
+                runtime: ctx.runtime,
+                abortSignal: ctx.abortSignal,
+                accountId: ctx.accountId,
+                channelRuntime: ctx.channelRuntime,
+            });
+        },
+    },
+};

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { registerDevice } from "./register.js";
+import { loadCredentials, loadGatewayUrl, deleteCredentials, } from "./config.js";
+const args = process.argv.slice(2);
+const command = args[0];
+if (command === "setup") {
+    const gatewayUrl = args[1];
+    const registerToken = args[2];
+    if (!gatewayUrl || !registerToken) {
+        console.error("Usage: openclaw-elys setup <gateway_url> <register_token>");
+        console.error("Example: openclaw-elys setup https://your-gateway.com reg_abc123");
+        process.exit(1);
+    }
+    console.log(`Registering device with gateway: ${gatewayUrl}`);
+    registerDevice(gatewayUrl, registerToken)
+        .then((creds) => {
+        console.log("Device registered successfully!");
+        console.log(`  Device ID:    ${creds.deviceId}`);
+        console.log(`  MQTT Broker:  ${creds.mqttBroker}`);
+        console.log(`  Credentials saved to ~/.elys/config.json`);
+    })
+        .catch((err) => {
+        console.error("Registration failed:", err.message);
+        process.exit(1);
+    });
+}
+else if (command === "uninstall") {
+    const creds = loadCredentials();
+    const gatewayUrl = loadGatewayUrl();
+    if (!creds) {
+        console.log("No credentials found. Nothing to clean up.");
+        deleteCredentials();
+        process.exit(0);
+    }
+    if (!gatewayUrl) {
+        console.log("No gateway URL found. Cleaning up local credentials only.");
+        deleteCredentials();
+        console.log("Local credentials removed.");
+        process.exit(0);
+    }
+    console.log(`Revoking device ${creds.deviceId} from gateway...`);
+    fetch(`${gatewayUrl}/api/v1/device/revoke`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${creds.deviceToken}` },
+    })
+        .then(async (resp) => {
+        if (resp.ok) {
+            console.log("Device revoked successfully on gateway.");
+        }
+        else {
+            const text = await resp.text();
+            console.warn(`Gateway revoke returned ${resp.status}: ${text}`);
+            console.warn("Proceeding with local cleanup anyway.");
+        }
+    })
+        .catch((err) => {
+        console.warn(`Could not reach gateway: ${err.message}`);
+        console.warn("Proceeding with local cleanup anyway.");
+    })
+        .finally(() => {
+        deleteCredentials();
+        console.log("Local credentials removed.");
+    });
+}
+else if (command === "status") {
+    const creds = loadCredentials();
+    if (creds) {
+        console.log("Elys device credentials:");
+        console.log(`  Device ID:    ${creds.deviceId}`);
+        console.log(`  MQTT Broker:  ${creds.mqttBroker}`);
+        console.log(`  Config file:  ~/.elys/config.json`);
+    }
+    else {
+        console.log("No credentials found. Run: openclaw-elys setup <gateway_url> <register_token>");
+    }
+}
+else {
+    console.log("openclaw-elys - Elys OpenClaw channel plugin CLI");
+    console.log("");
+    console.log("Commands:");
+    console.log("  setup <gateway_url> <register_token>  Register device with gateway");
+    console.log("  uninstall                              Revoke device and clean up");
+    console.log("  status                                 Show current device credentials");
+}

package/dist/src/config.d.ts

@@ -0,0 +1,13 @@
+import type { DeviceCredentials, ElysConfig } from "./types.js";
+export declare function loadCredentials(): DeviceCredentials | null;
+export declare function saveCredentials(creds: DeviceCredentials, gatewayUrl?: string): void;
+export declare function deleteCredentials(): void;
+export declare function loadGatewayUrl(): string | null;
+export declare function resolveElysConfig(cfg: Record<string, unknown>): ElysConfig;
+export declare function resolveElysAccount(cfg: Record<string, unknown>, _accountId?: string | null): {
+    accountId: string;
+    enabled: boolean;
+    configured: boolean;
+    gatewayUrl: string;
+    credentials: DeviceCredentials | null;
+};

package/dist/src/config.js

@@ -0,0 +1,74 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+const CONFIG_DIR = path.join(os.homedir(), ".elys");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export function loadCredentials() {
+    try {
+        if (!fs.existsSync(CONFIG_FILE))
+            return null;
+        const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.device_id && data.device_token && data.mqtt_broker) {
+            return {
+                deviceId: data.device_id,
+                deviceToken: data.device_token,
+                mqttBroker: data.mqtt_broker,
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCredentials(creds, gatewayUrl) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const data = {
+        device_id: creds.deviceId,
+        device_token: creds.deviceToken,
+        mqtt_broker: creds.mqttBroker,
+    };
+    if (gatewayUrl) {
+        data.gateway_url = gatewayUrl;
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), "utf-8");
+}
+export function deleteCredentials() {
+    try {
+        if (fs.existsSync(CONFIG_FILE))
+            fs.unlinkSync(CONFIG_FILE);
+        if (fs.existsSync(CONFIG_DIR))
+            fs.rmdirSync(CONFIG_DIR);
+    }
+    catch {
+        // ignore
+    }
+}
+export function loadGatewayUrl() {
+    try {
+        if (!fs.existsSync(CONFIG_FILE))
+            return null;
+        const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        return data.gateway_url || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveElysConfig(cfg) {
+    const elysCfg = cfg?.channels?.elys ?? {};
+    return elysCfg;
+}
+export function resolveElysAccount(cfg, _accountId) {
+    const elysCfg = resolveElysConfig(cfg);
+    const credentials = loadCredentials();
+    return {
+        accountId: "default",
+        enabled: elysCfg.enabled !== false,
+        configured: !!credentials && !!elysCfg.gatewayUrl,
+        gatewayUrl: elysCfg.gatewayUrl ?? "http://localhost:8080",
+        credentials,
+    };
+}

package/dist/src/monitor.d.ts

@@ -0,0 +1,43 @@
+export interface MonitorElysOpts {
+    config: Record<string, unknown>;
+    runtime?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
+    accountId?: string;
+    channelRuntime?: ChannelRuntimeReply;
+}
+/** Subset of OpenClaw's channelRuntime.reply API that we use */
+type ReplyPayload = {
+    text?: string;
+    mediaUrl?: string;
+    audioAsVoice?: boolean;
+    [key: string]: unknown;
+};
+type ChannelRuntimeReply = {
+    reply?: {
+        dispatchReplyWithBufferedBlockDispatcher?: (params: {
+            ctx: Record<string, unknown>;
+            cfg: Record<string, unknown>;
+            dispatcherOptions: {
+                deliver: (payload: ReplyPayload) => Promise<void>;
+                deliverBlock?: (payload: ReplyPayload) => Promise<void>;
+                deliverToolResult?: (payload: ReplyPayload) => Promise<void>;
+            };
+            replyOptions?: Record<string, unknown>;
+        }) => Promise<{
+            queuedFinal: boolean;
+            counts: Record<string, number>;
+        }>;
+        finalizeInboundContext?: (ctx: Record<string, unknown>) => Record<string, unknown>;
+    };
+    routing?: {
+        resolveAgentRoute?: (params: Record<string, unknown>) => Record<string, unknown>;
+    };
+};
+/**
+ * The main monitor loop for the Elys channel.
+ * Ensures device is registered, then connects to MQTT and dispatches
+ * incoming commands to the OpenClaw agent runtime using the standard
+ * channelRuntime dispatch API (supports streaming).
+ */
+export declare function monitorElysProvider(opts: MonitorElysOpts): Promise<void>;
+export {};

package/dist/src/monitor.js

@@ -0,0 +1,131 @@
+import { loadCredentials } from "./config.js";
+import { registerDevice } from "./register.js";
+import { ElysDeviceMQTTClient } from "./mqtt-client.js";
+/**
+ * The main monitor loop for the Elys channel.
+ * Ensures device is registered, then connects to MQTT and dispatches
+ * incoming commands to the OpenClaw agent runtime using the standard
+ * channelRuntime dispatch API (supports streaming).
+ */
+export async function monitorElysProvider(opts) {
+    const log = opts.runtime?.log ?? console.log;
+    const elysCfg = opts.config?.channels
+        ?.elys;
+    const gatewayUrl = elysCfg?.gatewayUrl ?? "http://localhost:8080";
+    // 1. Load or register credentials
+    let credentials = loadCredentials();
+    if (!credentials) {
+        const registerToken = elysCfg?.registerToken;
+        if (!registerToken) {
+            throw new Error("Elys plugin: no credentials found and no registerToken configured. " +
+                "Set channels.elys.registerToken in your config or run: npx openclaw-elys setup <gateway_url> <register_token>");
+        }
+        log("[elys] no credentials found, registering device...");
+        credentials = await registerDevice(gatewayUrl, registerToken);
+        log(`[elys] registered as device ${credentials.deviceId}`);
+    }
+    // 2. Connect MQTT
+    const mqttClient = new ElysDeviceMQTTClient(credentials, log);
+    // 3. Set up command handler
+    const channelRuntime = opts.channelRuntime;
+    const dispatchReply = channelRuntime?.reply?.dispatchReplyWithBufferedBlockDispatcher;
+    const finalizeCtx = channelRuntime?.reply?.finalizeInboundContext;
+    const commandHandler = async (cmd) => {
+        log(`[elys] executing command: ${cmd.command}`, cmd.args);
+        // If we have the full OpenClaw channelRuntime, use the standard dispatch path
+        if (dispatchReply && finalizeCtx) {
+            try {
+                let seq = 0;
+                let fullText = "";
+                // Build inbound context following OpenClaw protocol
+                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,
+                });
+                await dispatchReply({
+                    ctx: inboundCtx,
+                    cfg: opts.config,
+                    dispatcherOptions: {
+                        // Block (streaming) delivery — send each chunk via MQTT
+                        deliverBlock: async (payload) => {
+                            if (payload.text) {
+                                fullText += payload.text;
+                                seq++;
+                                mqttClient.publishStreamChunk(cmd.id, payload.text, seq, false);
+                                log(`[elys] stream chunk #${seq}: ${payload.text.slice(0, 80)}...`);
+                            }
+                        },
+                        // Final delivery
+                        deliver: async (payload) => {
+                            if (payload.text) {
+                                fullText += payload.text;
+                            }
+                            // Send final stream marker
+                            seq++;
+                            mqttClient.publishStreamChunk(cmd.id, payload.text ?? "", seq, true);
+                            log(`[elys] final reply delivered`);
+                        },
+                        // Tool result delivery (optional)
+                        deliverToolResult: async (payload) => {
+                            if (payload.text) {
+                                seq++;
+                                mqttClient.publishStreamChunk(cmd.id, payload.text, seq, false);
+                            }
+                        },
+                    },
+                });
+                return {
+                    id: cmd.id,
+                    type: "result",
+                    timestamp: Math.floor(Date.now() / 1000),
+                    status: "success",
+                    result: { text: fullText || "done" },
+                };
+            }
+            catch (err) {
+                return {
+                    id: cmd.id,
+                    type: "result",
+                    timestamp: Math.floor(Date.now() / 1000),
+                    status: "error",
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        }
+        // Fallback: echo the command back (no channelRuntime available)
+        return {
+            id: cmd.id,
+            type: "result",
+            timestamp: Math.floor(Date.now() / 1000),
+            status: "success",
+            result: { text: `command received: ${cmd.command}` },
+        };
+    };
+    mqttClient.setCommandHandler(commandHandler);
+    await mqttClient.connect(opts.abortSignal);
+    // 4. Keep alive until abort
+    if (opts.abortSignal) {
+        await new Promise((resolve) => {
+            opts.abortSignal.addEventListener("abort", () => resolve());
+        });
+    }
+}
+function formatCommandAsText(cmd) {
+    const parts = [cmd.command];
+    if (cmd.args) {
+        for (const [k, v] of Object.entries(cmd.args)) {
+            parts.push(`${k}=${typeof v === "string" ? v : JSON.stringify(v)}`);
+        }
+    }
+    return parts.join(" ");
+}

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

@@ -0,0 +1,24 @@
+import type { DeviceCredentials, CommandMessage, ResultMessage } from "./types.js";
+export type CommandHandler = (cmd: CommandMessage) => Promise<ResultMessage>;
+/**
+ * Manages the MQTT connection to EMQX for a single device.
+ * Subscribes to elys/down/{device_id}, publishes to elys/up/{device_id}.
+ */
+export declare class ElysDeviceMQTTClient {
+    private client;
+    private credentials;
+    private commandHandler;
+    private log;
+    private consecutiveFailures;
+    private static readonly MAX_FAILURES_BEFORE_REVOKE_WARNING;
+    constructor(credentials: DeviceCredentials, log?: (...args: unknown[]) => void);
+    setCommandHandler(handler: CommandHandler): void;
+    connect(abortSignal?: AbortSignal): Promise<void>;
+    disconnect(): void;
+    /** Send a stream chunk (for streaming AI responses) */
+    publishStreamChunk(commandId: string, chunk: string, seq: number, done: boolean): void;
+    private handleMessage;
+    private publishAck;
+    private publishResult;
+    private publish;
+}

package/dist/src/mqtt-client.js

@@ -0,0 +1,164 @@
+import mqtt from "mqtt";
+/**
+ * Manages the MQTT connection to EMQX for a single device.
+ * Subscribes to elys/down/{device_id}, publishes to elys/up/{device_id}.
+ */
+export class ElysDeviceMQTTClient {
+    client = null;
+    credentials;
+    commandHandler = null;
+    log;
+    consecutiveFailures = 0;
+    static MAX_FAILURES_BEFORE_REVOKE_WARNING = 3;
+    constructor(credentials, log) {
+        this.credentials = credentials;
+        this.log = log ?? console.log;
+    }
+    setCommandHandler(handler) {
+        this.commandHandler = handler;
+    }
+    async connect(abortSignal) {
+        const { deviceId, deviceToken, mqttBroker } = this.credentials;
+        this.log(`[elys] connecting to MQTT broker: ${mqttBroker}`);
+        this.client = mqtt.connect(mqttBroker, {
+            clientId: deviceId,
+            username: deviceToken,
+            password: deviceToken,
+            reconnectPeriod: 5000,
+            keepalive: 30,
+            rejectUnauthorized: true, // verify TLS cert
+        });
+        this.client.on("connect", () => {
+            this.log(`[elys] MQTT connected as ${deviceId}`);
+            this.consecutiveFailures = 0;
+            const downTopic = `elys/down/${deviceId}`;
+            this.client.subscribe(downTopic, { qos: 1 }, (err) => {
+                if (err) {
+                    this.log(`[elys] failed to subscribe to ${downTopic}:`, err);
+                }
+                else {
+                    this.log(`[elys] subscribed to ${downTopic}`);
+                }
+            });
+        });
+        this.client.on("message", (_topic, payload) => {
+            this.handleMessage(payload).catch((err) => {
+                this.log("[elys] error handling message:", err);
+            });
+        });
+        this.client.on("reconnect", () => {
+            this.consecutiveFailures++;
+            if (this.consecutiveFailures >= ElysDeviceMQTTClient.MAX_FAILURES_BEFORE_REVOKE_WARNING) {
+                this.log(`[elys] WARNING: MQTT reconnect failed ${this.consecutiveFailures} times. ` +
+                    `Your device credentials may have been revoked. ` +
+                    `Please re-register: npx openclaw-elys setup <gateway_url> <register_token>`);
+            }
+            else {
+                this.log("[elys] MQTT reconnecting...");
+            }
+        });
+        this.client.on("error", (err) => {
+            // MQTT auth failures indicate revoked credentials
+            if (err.message.includes("Not authorized") || err.message.includes("Connection refused")) {
+                this.log(`[elys] ERROR: MQTT authentication failed — device credentials may have been revoked. ` +
+                    `Please re-register: npx openclaw-elys setup <gateway_url> <register_token>`);
+            }
+            else {
+                this.log("[elys] MQTT error:", err.message);
+            }
+        });
+        this.client.on("close", () => {
+            this.log("[elys] MQTT connection closed");
+        });
+        // Handle abort signal for graceful shutdown
+        if (abortSignal) {
+            abortSignal.addEventListener("abort", () => {
+                this.disconnect();
+            });
+        }
+        // Wait for initial connection
+        return new Promise((resolve, reject) => {
+            const onConnect = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                cleanup();
+                reject(err);
+            };
+            const cleanup = () => {
+                this.client?.removeListener("connect", onConnect);
+                this.client?.removeListener("error", onError);
+            };
+            this.client.once("connect", onConnect);
+            this.client.once("error", onError);
+        });
+    }
+    disconnect() {
+        if (this.client) {
+            this.client.end(true);
+            this.client = null;
+            this.log("[elys] MQTT disconnected");
+        }
+    }
+    /** Send a stream chunk (for streaming AI responses) */
+    publishStreamChunk(commandId, chunk, seq, done) {
+        const msg = {
+            id: commandId,
+            type: "stream",
+            timestamp: Math.floor(Date.now() / 1000),
+            chunk,
+            seq,
+            done,
+        };
+        this.publish(msg);
+    }
+    async handleMessage(payload) {
+        const raw = JSON.parse(payload.toString());
+        if (raw.type !== "command") {
+            this.log(`[elys] ignoring non-command message type: ${raw.type}`);
+            return;
+        }
+        this.log(`[elys] received command: ${raw.command} (id: ${raw.id})`);
+        // Send ACK immediately
+        this.publishAck(raw.id);
+        // Execute command
+        if (this.commandHandler) {
+            try {
+                const result = await this.commandHandler(raw);
+                this.publishResult(result);
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                this.publishResult({
+                    id: raw.id,
+                    type: "result",
+                    timestamp: Date.now() / 1000,
+                    status: "error",
+                    error: errMsg,
+                });
+            }
+        }
+    }
+    publishAck(commandId) {
+        const msg = {
+            id: commandId,
+            type: "ack",
+            timestamp: Math.floor(Date.now() / 1000),
+        };
+        this.publish(msg);
+    }
+    publishResult(msg) {
+        this.publish(msg);
+    }
+    publish(msg) {
+        if (!this.client)
+            return;
+        const topic = `elys/up/${this.credentials.deviceId}`;
+        this.client.publish(topic, JSON.stringify(msg), { qos: 1 }, (err) => {
+            if (err) {
+                this.log(`[elys] failed to publish to ${topic}:`, err);
+            }
+        });
+    }
+}

package/dist/src/outbound.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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;
+    sendText: (ctx: {
+        cfg: Record<string, unknown>;
+        to: string;
+        text: string;
+        accountId?: string | null;
+    }) => Promise<{
+        messageId: string;
+        channel: string;
+    }>;
+};

package/dist/src/outbound.js

@@ -0,0 +1,44 @@
+import { loadCredentials } from "./config.js";
+/**
+ * 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 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}`);
+    }
+    return { messageId: `msg_${Date.now()}` };
+}
+export const elysOutbound = {
+    deliveryMode: "direct",
+    textChunkLimit: 4000,
+    sendText: async (ctx) => {
+        const elysCfg = ctx.cfg?.channels?.elys;
+        const gatewayUrl = elysCfg?.gatewayUrl ?? "http://localhost:8080";
+        const result = await sendTextToGateway({
+            gatewayUrl,
+            text: ctx.text,
+            deviceId: ctx.to,
+        });
+        return { channel: "elys", ...result };
+    },
+};

package/dist/src/register.d.ts

@@ -0,0 +1,6 @@
+import type { DeviceCredentials } from "./types.js";
+/**
+ * Register this device with the Elys gateway.
+ * Saves credentials to ~/.elys/config.json on success.
+ */
+export declare function registerDevice(gatewayUrl: string, registerToken: string): Promise<DeviceCredentials>;

package/dist/src/register.js

@@ -0,0 +1,33 @@
+import os from "os";
+import { saveCredentials } from "./config.js";
+/**
+ * Register this device with the Elys gateway.
+ * Saves credentials to ~/.elys/config.json on success.
+ */
+export async function registerDevice(gatewayUrl, registerToken) {
+    const body = {
+        register_token: registerToken,
+        hostname: os.hostname(),
+        os: process.platform,
+        os_version: os.release(),
+        arch: os.arch(),
+        client_version: "1.0.0",
+    };
+    const resp = await fetch(`${gatewayUrl}/api/v1/device/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`Device registration failed (${resp.status}): ${text}`);
+    }
+    const data = (await resp.json());
+    const credentials = {
+        deviceId: data.device_id,
+        deviceToken: data.device_token,
+        mqttBroker: data.mqtt_broker,
+    };
+    saveCredentials(credentials, gatewayUrl);
+    return credentials;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,42 @@
+export interface ElysConfig {
+    enabled?: boolean;
+    gatewayUrl?: string;
+    registerToken?: string;
+}
+export interface DeviceCredentials {
+    deviceId: string;
+    deviceToken: string;
+    mqttBroker: string;
+}
+export interface ResolvedElysAccount {
+    accountId: string;
+    enabled: boolean;
+    configured: boolean;
+    gatewayUrl: string;
+    credentials: DeviceCredentials | null;
+}
+export interface MQTTBaseMessage {
+    id: string;
+    type: "command" | "ack" | "result" | "stream";
+    timestamp: number;
+}
+export interface CommandMessage extends MQTTBaseMessage {
+    type: "command";
+    command: string;
+    args?: Record<string, unknown>;
+}
+export interface AckMessage extends MQTTBaseMessage {
+    type: "ack";
+}
+export interface StreamMessage extends MQTTBaseMessage {
+    type: "stream";
+    chunk: string;
+    done: boolean;
+    seq: number;
+}
+export interface ResultMessage extends MQTTBaseMessage {
+    type: "result";
+    status: "success" | "error";
+    result?: Record<string, unknown>;
+    error?: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "openclaw-elys",
+  "channels": ["elys"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "gatewayUrl": {
+        "type": "string"
+      },
+      "registerToken": {
+        "type": "string"
+      }
+    }
+  },
+  "uiHints": {
+    "gatewayUrl": {
+      "label": "Gateway URL",
+      "placeholder": "https://your-gateway.com"
+    },
+    "registerToken": {
+      "label": "Register Token",
+      "placeholder": "reg_xxx (one-time, get from Elys App)",
+      "sensitive": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "openclaw-elys",
+  "version": "1.1.0",
+  "description": "OpenClaw Elys channel plugin — connects to Elys App",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "openclaw-elys": "dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "mqtt": "^5.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "typescript": "^5.9.3"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "elys",
+      "label": "Elys",
+      "selectionLabel": "Elys App",
+      "docsPath": "/channels/elys",
+      "docsLabel": "elys",
+      "blurb": "Elys App integration",
+      "order": 80
+    },
+    "install": {
+      "npmSpec": "openclaw-elys",
+      "localPath": "plugin",
+      "defaultChoice": "npm"
+    }
+  }
+}