@turquoisebay/mqtt 0.1.13

package/dist/src/client.d.ts

@@ -0,0 +1,23 @@
+import type { MqttConfig } from "./config-schema.js";
+export interface MqttClientManager {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    publish(topic: string, message: string, qos?: 0 | 1 | 2): Promise<void>;
+    subscribe(topic: string, handler: MessageHandler): void;
+    isConnected(): boolean;
+}
+export type MessageHandler = (topic: string, payload: Buffer) => void;
+interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/**
+ * MQTT Client Manager
+ *
+ * Handles connection lifecycle, reconnection, and message routing.
+ */
+export declare function createMqttClient(rawConfig: Partial<MqttConfig>, logger: Logger): MqttClientManager;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,MAAM,WAAW,iBAAiB;IAChC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxD,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtE,UAAU,MAAM;IACd,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,EAC9B,MAAM,EAAE,MAAM,GACb,iBAAiB,CAoLnB"}

package/dist/src/client.js

@@ -0,0 +1,192 @@
+import mqtt from "mqtt";
+import { mergeWithEnv } from "./env.js";
+const DEFAULT_RECONNECT_MS = 5000;
+const MAX_RECONNECT_MS = 60000;
+/**
+ * MQTT Client Manager
+ *
+ * Handles connection lifecycle, reconnection, and message routing.
+ */
+export function createMqttClient(rawConfig, logger) {
+    const config = mergeWithEnv(rawConfig);
+    let client = null;
+    let messageHandlers = new Map();
+    let reconnectAttempts = 0;
+    function getClientOptions() {
+        const options = {
+            clientId: config.clientId ?? `openclaw-${Math.random().toString(36).slice(2, 10)}`,
+            clean: true,
+            connectTimeout: 10000,
+            reconnectPeriod: DEFAULT_RECONNECT_MS,
+        };
+        // Auth
+        if (config.username) {
+            options.username = config.username;
+        }
+        if (config.password) {
+            options.password = config.password;
+        }
+        // TLS
+        if (config.tls?.enabled) {
+            options.rejectUnauthorized = config.tls.rejectUnauthorized ?? true;
+            if (config.tls.ca) {
+                // Note: In production, read the CA file
+                // options.ca = fs.readFileSync(config.tls.ca);
+            }
+        }
+        return options;
+    }
+    async function connect() {
+        if (client?.connected) {
+            logger.debug("MQTT already connected");
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            logger.info(`Connecting to MQTT broker: ${config.brokerUrl}`);
+            const options = getClientOptions();
+            client = mqtt.connect(config.brokerUrl, options);
+            client.on("connect", () => {
+                logger.info("MQTT connected");
+                reconnectAttempts = 0;
+                // Resubscribe to all topics
+                for (const topic of messageHandlers.keys()) {
+                    client?.subscribe(topic, { qos: config.qos }, (err) => {
+                        if (err) {
+                            logger.error(`Failed to subscribe to ${topic}: ${err.message}`);
+                        }
+                        else {
+                            logger.debug(`Subscribed to ${topic}`);
+                        }
+                    });
+                }
+                resolve();
+            });
+            client.on("message", (topic, payload) => {
+                logger.debug(`Received message on ${topic}: ${payload.length} bytes`);
+                const handlers = [...(messageHandlers.get(topic) ?? [])];
+                // Also check wildcard subscriptions (skip exact match to avoid duplicates)
+                for (const [pattern, patternHandlers] of messageHandlers) {
+                    if (pattern === topic)
+                        continue;
+                    if (topicMatches(pattern, topic)) {
+                        handlers.push(...patternHandlers);
+                    }
+                }
+                for (const handler of handlers) {
+                    try {
+                        handler(topic, payload);
+                    }
+                    catch (err) {
+                        logger.error(`Message handler error: ${err}`);
+                    }
+                }
+            });
+            client.on("error", (err) => {
+                logger.error(`MQTT error: ${err.message}`);
+                reject(err);
+            });
+            client.on("close", () => {
+                logger.warn("MQTT connection closed");
+            });
+            client.on("reconnect", () => {
+                reconnectAttempts++;
+                const backoff = Math.min(DEFAULT_RECONNECT_MS * Math.pow(2, reconnectAttempts), MAX_RECONNECT_MS);
+                logger.info(`MQTT reconnecting (attempt ${reconnectAttempts}, backoff ${backoff}ms)`);
+            });
+            client.on("offline", () => {
+                logger.warn("MQTT client offline");
+            });
+            // Timeout for initial connection
+            setTimeout(() => {
+                if (!client?.connected) {
+                    reject(new Error("MQTT connection timeout"));
+                }
+            }, 15000);
+        });
+    }
+    async function disconnect() {
+        if (!client)
+            return;
+        return new Promise((resolve) => {
+            logger.info("Disconnecting from MQTT broker");
+            client?.end(false, {}, () => {
+                client = null;
+                messageHandlers.clear();
+                logger.info("MQTT disconnected");
+                resolve();
+            });
+        });
+    }
+    async function publish(topic, message, qos = config.qos) {
+        if (!client?.connected) {
+            throw new Error("MQTT not connected");
+        }
+        return new Promise((resolve, reject) => {
+            client.publish(topic, message, { qos }, (err) => {
+                if (err) {
+                    logger.error(`Failed to publish to ${topic}: ${err.message}`);
+                    reject(err);
+                }
+                else {
+                    logger.debug(`Published to ${topic}: ${message.slice(0, 100)}...`);
+                    resolve();
+                }
+            });
+        });
+    }
+    function subscribe(topic, handler) {
+        const handlers = messageHandlers.get(topic) ?? [];
+        handlers.push(handler);
+        messageHandlers.set(topic, handlers);
+        // If already connected, subscribe immediately
+        if (client?.connected) {
+            client.subscribe(topic, { qos: config.qos }, (err) => {
+                if (err) {
+                    logger.error(`Failed to subscribe to ${topic}: ${err.message}`);
+                }
+                else {
+                    logger.debug(`Subscribed to ${topic}`);
+                }
+            });
+        }
+    }
+    function isConnected() {
+        return client?.connected ?? false;
+    }
+    return {
+        connect,
+        disconnect,
+        publish,
+        subscribe,
+        isConnected,
+    };
+}
+/**
+ * Check if a topic matches a subscription pattern.
+ * Supports MQTT wildcards: + (single level) and # (multi level)
+ */
+function topicMatches(pattern, topic) {
+    if (pattern === topic)
+        return true;
+    if (!pattern.includes("+") && !pattern.includes("#"))
+        return false;
+    const patternParts = pattern.split("/");
+    const topicParts = topic.split("/");
+    for (let i = 0; i < patternParts.length; i++) {
+        const p = patternParts[i];
+        if (p === "#") {
+            // # matches everything from here
+            return true;
+        }
+        if (p === "+") {
+            // + matches exactly one level
+            if (i >= topicParts.length)
+                return false;
+            continue;
+        }
+        if (p !== topicParts[i]) {
+            return false;
+        }
+    }
+    return patternParts.length === topicParts.length;
+}

package/dist/src/config-schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * MQTT Configuration Schema
+ *
+ * Values can come from:
+ * 1. ~/.openclaw/openclaw.json (channels.mqtt.*)
+ * 2. Environment variables (MQTT_*)
+ *
+ * Environment variables take precedence for secrets.
+ */
+export declare const mqttConfigSchema: z.ZodObject<{
+    brokerUrl: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodOptional<z.ZodString>;
+    topics: z.ZodDefault<z.ZodObject<{
+        inbound: z.ZodDefault<z.ZodString>;
+        outbound: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        inbound: string;
+        outbound: string;
+    }, {
+        inbound?: string | undefined;
+        outbound?: string | undefined;
+    }>>;
+    qos: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    tls: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        rejectUnauthorized: z.ZodDefault<z.ZodBoolean>;
+        ca: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        rejectUnauthorized: boolean;
+        ca?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        rejectUnauthorized?: boolean | undefined;
+        ca?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    brokerUrl: string;
+    topics: {
+        inbound: string;
+        outbound: string;
+    };
+    qos: 0 | 1 | 2;
+    username?: string | undefined;
+    password?: string | undefined;
+    clientId?: string | undefined;
+    tls?: {
+        enabled: boolean;
+        rejectUnauthorized: boolean;
+        ca?: string | undefined;
+    } | undefined;
+}, {
+    brokerUrl: string;
+    username?: string | undefined;
+    password?: string | undefined;
+    clientId?: string | undefined;
+    topics?: {
+        inbound?: string | undefined;
+        outbound?: string | undefined;
+    } | undefined;
+    qos?: 0 | 1 | 2 | undefined;
+    tls?: {
+        enabled?: boolean | undefined;
+        rejectUnauthorized?: boolean | undefined;
+        ca?: string | undefined;
+    } | undefined;
+}>;
+export type MqttConfig = z.infer<typeof mqttConfigSchema>;
+export declare const defaultConfig: Partial<MqttConfig>;
+//# sourceMappingURL=config-schema.d.ts.map

package/dist/src/config-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["../../src/config-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,UAAU,CAM7C,CAAC"}

package/dist/src/config-schema.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/**
+ * MQTT Configuration Schema
+ *
+ * Values can come from:
+ * 1. ~/.openclaw/openclaw.json (channels.mqtt.*)
+ * 2. Environment variables (MQTT_*)
+ *
+ * Environment variables take precedence for secrets.
+ */
+export const mqttConfigSchema = z.object({
+    // Connection - env: MQTT_BROKER_URL
+    brokerUrl: z.string().url().describe("MQTT broker URL"),
+    // Auth - env: MQTT_USERNAME, MQTT_PASSWORD (recommended for secrets)
+    username: z.string().optional().describe("Broker username"),
+    password: z.string().optional().describe("Broker password"),
+    // Client - env: MQTT_CLIENT_ID
+    clientId: z.string().optional().describe("MQTT client ID"),
+    topics: z
+        .object({
+        inbound: z.string().default("openclaw/inbound"),
+        outbound: z.string().default("openclaw/outbound"),
+    })
+        .default({}),
+    qos: z.union([z.literal(0), z.literal(1), z.literal(2)]).default(1),
+    tls: z
+        .object({
+        enabled: z.boolean().default(false),
+        rejectUnauthorized: z.boolean().default(true),
+        ca: z.string().optional(),
+    })
+        .optional(),
+});
+export const defaultConfig = {
+    topics: {
+        inbound: "openclaw/inbound",
+        outbound: "openclaw/outbound",
+    },
+    qos: 1,
+};

package/dist/src/env.d.ts

@@ -0,0 +1,18 @@
+import type { MqttConfig } from "./config-schema.js";
+/**
+ * Environment variable names for MQTT config.
+ * These override values from openclaw.json for sensitive data.
+ */
+export declare const ENV_VARS: {
+    readonly BROKER_URL: "MQTT_BROKER_URL";
+    readonly USERNAME: "MQTT_USERNAME";
+    readonly PASSWORD: "MQTT_PASSWORD";
+    readonly CLIENT_ID: "MQTT_CLIENT_ID";
+    readonly CA_PATH: "MQTT_CA_PATH";
+};
+/**
+ * Merge config from openclaw.json with environment variables.
+ * Environment variables take precedence (recommended for secrets).
+ */
+export declare function mergeWithEnv(config: Partial<MqttConfig>): MqttConfig;
+//# sourceMappingURL=env.d.ts.map

package/dist/src/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAC;AAEX;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAkBpE"}

package/dist/src/env.js

@@ -0,0 +1,34 @@
+/**
+ * Environment variable names for MQTT config.
+ * These override values from openclaw.json for sensitive data.
+ */
+export const ENV_VARS = {
+    BROKER_URL: "MQTT_BROKER_URL",
+    USERNAME: "MQTT_USERNAME",
+    PASSWORD: "MQTT_PASSWORD",
+    CLIENT_ID: "MQTT_CLIENT_ID",
+    CA_PATH: "MQTT_CA_PATH",
+};
+/**
+ * Merge config from openclaw.json with environment variables.
+ * Environment variables take precedence (recommended for secrets).
+ */
+export function mergeWithEnv(config) {
+    return {
+        brokerUrl: process.env[ENV_VARS.BROKER_URL] ?? config.brokerUrl ?? "",
+        username: process.env[ENV_VARS.USERNAME] ?? config.username,
+        password: process.env[ENV_VARS.PASSWORD] ?? config.password,
+        clientId: process.env[ENV_VARS.CLIENT_ID] ?? config.clientId,
+        topics: config.topics ?? {
+            inbound: "openclaw/inbound",
+            outbound: "openclaw/outbound",
+        },
+        qos: config.qos ?? 1,
+        tls: config.tls
+            ? {
+                ...config.tls,
+                ca: process.env[ENV_VARS.CA_PATH] ?? config.tls.ca,
+            }
+            : undefined,
+    };
+}

package/dist/src/onboarding.d.ts

@@ -0,0 +1,73 @@
+/**
+ * MQTT Channel Onboarding Adapter
+ * Provides interactive setup via `openclaw configure channels`
+ */
+interface MqttConfig {
+    channels?: {
+        mqtt?: {
+            enabled?: boolean;
+            brokerUrl?: string;
+            username?: string;
+            password?: string;
+            topics?: {
+                inbound?: string;
+                outbound?: string;
+            };
+            tls?: {
+                enabled?: boolean;
+                rejectUnauthorized?: boolean;
+            };
+            qos?: 0 | 1 | 2;
+        };
+    };
+}
+interface Prompter {
+    text(opts: {
+        message: string;
+        placeholder?: string;
+        initialValue?: string;
+        validate?: (value: string | undefined) => string | undefined;
+    }): Promise<string>;
+    confirm(opts: {
+        message: string;
+        initialValue?: boolean;
+    }): Promise<boolean>;
+    select<T>(opts: {
+        message: string;
+        options: Array<{
+            value: T;
+            label: string;
+            hint?: string;
+        }>;
+        initialValue?: T;
+    }): Promise<T>;
+    note(message: string, title?: string): Promise<void>;
+}
+interface OnboardingStatus {
+    channel: string;
+    configured: boolean;
+    statusLines: string[];
+    selectionHint: string;
+    quickstartScore: number;
+}
+interface ConfigureParams {
+    cfg: MqttConfig;
+    prompter: Prompter;
+    accountOverrides?: Record<string, string>;
+    shouldPromptAccountIds?: boolean;
+    forceAllowFrom?: boolean;
+}
+interface ConfigureResult {
+    cfg: MqttConfig;
+    accountId: string;
+}
+export declare const mqttOnboardingAdapter: {
+    channel: string;
+    getStatus: ({ cfg }: {
+        cfg: MqttConfig;
+    }) => Promise<OnboardingStatus>;
+    configure: ({ cfg, prompter, }: ConfigureParams) => Promise<ConfigureResult>;
+    disable: (cfg: MqttConfig) => MqttConfig;
+};
+export {};
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/src/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/onboarding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE;YACL,OAAO,CAAC,EAAE,OAAO,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,MAAM,CAAC,EAAE;gBACP,OAAO,CAAC,EAAE,MAAM,CAAC;gBACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;aACnB,CAAC;YACF,GAAG,CAAC,EAAE;gBACJ,OAAO,CAAC,EAAE,OAAO,CAAC;gBAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;aAC9B,CAAC;YACF,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACjB,CAAC;KACH,CAAC;CACH;AAED,UAAU,QAAQ;IAChB,IAAI,CAAC,IAAI,EAAE;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAC;KAC9D,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpB,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7E,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,CAAC,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC3D,YAAY,CAAC,EAAE,CAAC,CAAC;KAClB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACf,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAED,UAAU,gBAAgB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,eAAe;IACvB,GAAG,EAAE,UAAU,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,UAAU,eAAe;IACvB,GAAG,EAAE,UAAU,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,qBAAqB;;yBAGL;QAAE,GAAG,EAAE,UAAU,CAAA;KAAE,KAAG,OAAO,CAAC,gBAAgB,CAAC;oCAoBvE,eAAe,KAAG,OAAO,CAAC,eAAe,CAAC;mBA6I9B,UAAU,KAAG,UAAU;CAOvC,CAAC"}

package/dist/src/onboarding.js

@@ -0,0 +1,138 @@
+/**
+ * MQTT Channel Onboarding Adapter
+ * Provides interactive setup via `openclaw configure channels`
+ */
+const channel = "mqtt";
+export const mqttOnboardingAdapter = {
+    channel,
+    getStatus: async ({ cfg }) => {
+        const mqtt = cfg.channels?.mqtt;
+        const configured = Boolean(mqtt?.brokerUrl && mqtt?.enabled !== false);
+        return {
+            channel,
+            configured,
+            statusLines: [
+                `MQTT: ${configured ? `configured (${mqtt?.brokerUrl})` : "not configured"}`,
+            ],
+            selectionHint: configured
+                ? "configured"
+                : "IoT / home automation integration",
+            quickstartScore: configured ? 1 : 50, // Lower priority than chat channels
+        };
+    },
+    configure: async ({ cfg, prompter, }) => {
+        let next = { ...cfg };
+        // Show help note
+        await prompter.note([
+            "MQTT connects OpenClaw to IoT devices and home automation systems.",
+            "",
+            "Common brokers:",
+            "  • Mosquitto: mqtt://localhost:1883",
+            "  • EMQX: mqtt://localhost:1883",
+            "  • HiveMQ Cloud: mqtts://broker.hivemq.com:8883",
+            "",
+            "You can also use environment variables:",
+            "  MQTT_BROKER_URL, MQTT_USERNAME, MQTT_PASSWORD",
+        ].join("\n"), "MQTT Setup");
+        // Prompt for broker URL
+        const existingUrl = cfg.channels?.mqtt?.brokerUrl;
+        const brokerUrl = String(await prompter.text({
+            message: "MQTT broker URL",
+            placeholder: "mqtt://localhost:1883",
+            initialValue: existingUrl || process.env.MQTT_BROKER_URL || "",
+            validate: (value) => {
+                if (!value?.trim())
+                    return "Required";
+                if (!/^mqtts?:\/\/.+/.test(value.trim())) {
+                    return "Must start with mqtt:// or mqtts://";
+                }
+                return undefined;
+            },
+        })).trim();
+        // Check if auth is needed
+        const needsAuth = await prompter.confirm({
+            message: "Does your broker require authentication?",
+            initialValue: Boolean(cfg.channels?.mqtt?.username || process.env.MQTT_USERNAME),
+        });
+        let username;
+        let password;
+        if (needsAuth) {
+            username = String(await prompter.text({
+                message: "MQTT username",
+                initialValue: cfg.channels?.mqtt?.username || process.env.MQTT_USERNAME || "",
+                validate: (value) => (value?.trim() ? undefined : "Required"),
+            })).trim();
+            password = String(await prompter.text({
+                message: "MQTT password",
+                initialValue: cfg.channels?.mqtt?.password || "",
+                validate: (value) => (value?.trim() ? undefined : "Required"),
+            })).trim();
+        }
+        // TLS settings for mqtts://
+        let tls;
+        if (brokerUrl.startsWith("mqtts://")) {
+            const rejectUnauthorized = await prompter.confirm({
+                message: "Verify TLS certificate? (disable for self-signed certs)",
+                initialValue: true,
+            });
+            tls = { enabled: true, rejectUnauthorized };
+        }
+        // Topics
+        await prompter.note([
+            "Topics define where OpenClaw listens and publishes:",
+            "",
+            "  • Inbound: messages TO OpenClaw (e.g., alerts, commands)",
+            "  • Outbound: messages FROM OpenClaw (e.g., responses)",
+            "",
+            "Wildcards supported: + (single level), # (multi level)",
+            "Example: home/+/alerts, sensors/#",
+        ].join("\n"), "MQTT Topics");
+        const inboundTopic = String(await prompter.text({
+            message: "Inbound topic (messages to OpenClaw)",
+            placeholder: "openclaw/inbound",
+            initialValue: cfg.channels?.mqtt?.topics?.inbound || "openclaw/inbound",
+        })).trim();
+        const outboundTopic = String(await prompter.text({
+            message: "Outbound topic (messages from OpenClaw)",
+            placeholder: "openclaw/outbound",
+            initialValue: cfg.channels?.mqtt?.topics?.outbound || "openclaw/outbound",
+        })).trim();
+        // QoS level
+        const qos = (await prompter.select({
+            message: "QoS level",
+            options: [
+                { value: 0, label: "0 - At most once", hint: "fire and forget" },
+                { value: 1, label: "1 - At least once", hint: "recommended" },
+                { value: 2, label: "2 - Exactly once", hint: "highest overhead" },
+            ],
+            initialValue: cfg.channels?.mqtt?.qos ?? 1,
+        }));
+        // Build config
+        next = {
+            ...next,
+            channels: {
+                ...next.channels,
+                mqtt: {
+                    enabled: true,
+                    brokerUrl,
+                    ...(username && { username }),
+                    ...(password && { password }),
+                    ...(tls && { tls }),
+                    topics: {
+                        inbound: inboundTopic,
+                        outbound: outboundTopic,
+                    },
+                    qos,
+                },
+            },
+        };
+        return { cfg: next, accountId: "default" };
+    },
+    disable: (cfg) => ({
+        ...cfg,
+        channels: {
+            ...cfg.channels,
+            mqtt: { ...cfg.channels?.mqtt, enabled: false },
+        },
+    }),
+};

package/dist/src/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+export declare function setMqttRuntime(r: PluginRuntime): void;
+export declare function getMqttRuntime(): PluginRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/src/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,wBAAgB,cAAc,CAAC,CAAC,EAAE,aAAa,QAE9C;AAED,wBAAgB,cAAc,IAAI,aAAa,CAK9C"}

package/dist/src/runtime.js

@@ -0,0 +1,10 @@
+let runtime;
+export function setMqttRuntime(r) {
+    runtime = r;
+}
+export function getMqttRuntime() {
+    if (!runtime) {
+        throw new Error("MQTT runtime not initialized");
+    }
+    return runtime;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,22 @@
+import type { CoreConfig } from "openclaw/plugin-sdk";
+import type { MqttConfig } from "./config-schema.js";
+export interface MqttChannelConfig {
+    channels?: {
+        mqtt?: MqttConfig;
+    };
+}
+export type MqttCoreConfig = CoreConfig & MqttChannelConfig;
+export interface MqttInboundMessage {
+    topic: string;
+    payload: string | Buffer;
+    qos: 0 | 1 | 2;
+    retain: boolean;
+    timestamp: number;
+}
+export interface MqttOutboundMessage {
+    topic?: string;
+    payload: string;
+    qos?: 0 | 1 | 2;
+    retain?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,UAAU,CAAC;KACnB,CAAC;CACH;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,iBAAiB,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/src/types.js

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

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "mqtt",
+  "name": "MQTT",
+  "description": "Bidirectional MQTT channel for IoT and home automation integration",
+  "channels": ["mqtt"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}