rol-websocket-channel 1.5.3 → 1.5.5

package/SDK-CHANNEL-TODO.md

@@ -0,0 +1,6 @@
+# SDK Channel TODO
+
+1. Migrate the plugin entry to the current SDK style with `defineChannelPluginEntry({ channel, cli, hooks, manifest })`.
+2. Move `sender` message normalization into a dedicated inbound normalizer while keeping admin MQTT command types out of the chat inbound path.
+3. Align CLI metadata with the SDK entry format while preserving `admin-bridge` and `rol-websocket-channel` command compatibility.
+4. Keep `package.json`, `openclaw.plugin.json`, and ClawHub release versions in sync for update/install flows.

package/dist/index.js

@@ -9,6 +9,26 @@ import * as ConnectionManager from "./src/mqtt/connection-manager.js";
 // ============================================
 import { getContext, initializeContext } from "./src/shared/context.js";
 let pluginRuntime = null;
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function pickNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+function getChannelConfig(cfg) {
+    const entry = cfg.channels?.["rol-websocket-channel"];
+    if (!isRecord(entry))
+        return null;
+    const nested = isRecord(entry.config) ? entry.config : {};
+    return { entry, nested };
+}
 export function getPluginRuntime() {
     return pluginRuntime;
 }
@@ -99,7 +119,7 @@ const WebSocketChannel = {
                             enum: ["pairing", "allowlist", "open", "disabled"],
                         },
                     },
-                    required: ["mqttUrl"],
+                    required: ["mqttUrl", "mqttTopic"],
                 },
             },
         },
@@ -139,12 +159,12 @@ const WebSocketChannel = {
             },
             "config.mqttUrl": {
                 label: "MQTT Broker URL",
-                placeholder: "ws://192.168.1.152:8083/mqtt",
+                placeholder: "ws://mqtt.example.com:8083/mqtt",
                 help: "MQTT broker WebSocket URL",
             },
             "config.mqttTopic": {
                 label: "MQTT Topic",
-                placeholder: "announcement/tester",
+                placeholder: "announcement/{userId}/{agentId}/#",
                 help: "MQTT topic to subscribe/publish",
             },
             "config.groupPolicy": {
@@ -155,26 +175,37 @@ const WebSocketChannel = {
     },
     config: {
         listAccountIds: (cfg) => {
-            const channelCfg = cfg.channels?.["rol-websocket-channel"];
-            if (!channelCfg || !channelCfg.config || !channelCfg.config.mqttUrl) {
+            const channelCfg = getChannelConfig(cfg);
+            const mqttUrl = channelCfg
+                ? pickNonEmptyString(channelCfg.nested.mqttUrl, channelCfg.entry.mqttUrl)
+                : undefined;
+            if (!mqttUrl) {
                 return [];
             }
             return ["default"];
         },
         resolveAccount: (cfg, accountId) => {
-            const channelCfg = cfg.channels?.["rol-websocket-channel"];
-            if (!channelCfg || !channelCfg.config) {
+            const channelCfg = getChannelConfig(cfg);
+            if (!channelCfg) {
+                return undefined;
+            }
+            const config = channelCfg.nested;
+            const mqttUrl = pickNonEmptyString(config.mqttUrl, channelCfg.entry.mqttUrl);
+            if (!mqttUrl) {
+                return undefined;
+            }
+            const mqttTopic = pickNonEmptyString(config.mqttTopic, channelCfg.entry.mqttTopic);
+            if (!mqttTopic) {
                 return undefined;
             }
-            const config = channelCfg.config;
             return {
                 accountId: "default",
-                mqttUrl: config.mqttUrl || "ws://192.168.1.152:8083/mqtt",
-                mqttTopic: config.mqttTopic || "announcement/tester",
+                mqttUrl,
+                mqttTopic,
                 enabled: config.enabled !== false,
-                dmPolicy: channelCfg.dmPolicy || config.groupPolicy || "open",
-                allowFrom: Array.isArray(channelCfg.allowFrom)
-                    ? channelCfg.allowFrom
+                dmPolicy: channelCfg.entry.dmPolicy || config.groupPolicy || "open",
+                allowFrom: Array.isArray(channelCfg.entry.allowFrom)
+                    ? channelCfg.entry.allowFrom
                     : [],
                 groupPolicy: config.groupPolicy || "open",
             };
@@ -262,8 +293,31 @@ const WebSocketChannel = {
                 console.error(`[MQTT] startAccount(${account.accountId}): Runtime API not available`);
                 throw new Error("Runtime API not available");
             }
-            const mqttUrl = account.mqttUrl || "ws://192.168.1.152:8083/mqtt";
-            const mqttTopic = account.mqttTopic || "announcement/tester";
+            const mqttUrl = pickNonEmptyString(account.mqttUrl);
+            if (!mqttUrl) {
+                const message = "MQTT broker URL is not configured";
+                console.error(`[MQTT] startAccount(${account.accountId}): ${message}`);
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    running: false,
+                    connected: false,
+                    lastError: message,
+                });
+                throw new Error(message);
+            }
+            const mqttTopic = pickNonEmptyString(account.mqttTopic);
+            if (!mqttTopic) {
+                const message = "MQTT topic is not configured";
+                console.error(`[MQTT] startAccount(${account.accountId}): ${message}`);
+                ctx.setStatus({
+                    accountId: account.accountId,
+                    mqttUrl,
+                    running: false,
+                    connected: false,
+                    lastError: message,
+                });
+                throw new Error(message);
+            }
             console.log(`[MQTT] startAccount(${account.accountId}): url=${mqttUrl}, topic=${mqttTopic}`);
             ctx.setStatus({
                 accountId: account.accountId,

package/dist/src/admin/methods/pairing.js

@@ -105,7 +105,16 @@ function normalizePairingPayload(raw, endpoint, existingMqttUrl) {
         ?? pickString(root.mqttTopic)
         ?? pickString(root.mqtt_topic)
         ?? rawValue
-        ?? 'announcement/tester';
+        ?? null;
+    if (!mqttTopic) {
+        throwPairingError('PAIR_CHANNEL_CONFIG_INVALID', 'mqttTopic is missing from pairing payload', {
+            endpoint,
+            rootKeys: Object.keys(root),
+            channelKeys: Object.keys(channelValue),
+            channelConfigKeys: Object.keys(channelConfigValue),
+            hasRawValue: Boolean(rawValue)
+        });
+    }
     const groupPolicy = normalizeGroupPolicy(pickString(channelValue.groupPolicy)
         ?? pickString(channelValue.group_policy)
         ?? pickString(channelValue.dmPolicy)
@@ -181,7 +190,7 @@ function applyPairingConfig(config, key, payload) {
             ...existingChannelConfig,
             enabled: true,
             mqttUrl: payload.channel.mqttUrl,
-            mqttTopic: payload.channel.mqttTopic ?? existingChannelConfig.mqttTopic ?? 'announcement/tester',
+            mqttTopic: payload.channel.mqttTopic,
             groupPolicy: payload.channel.groupPolicy
         }
     };

package/index.ts

@@ -34,6 +34,29 @@ import { getContext, initializeContext } from "./src/shared/context.js";
 
 let pluginRuntime: any = null;
 
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function pickNonEmptyString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (trimmed) return trimmed;
+  }
+  return undefined;
+}
+
+function getChannelConfig(cfg: OpenClawConfig): {
+  entry: Record<string, any>;
+  nested: Record<string, any>;
+} | null {
+  const entry = cfg.channels?.["rol-websocket-channel"];
+  if (!isRecord(entry)) return null;
+  const nested = isRecord(entry.config) ? entry.config : {};
+  return { entry, nested };
+}
+
 export function getPluginRuntime(): any {
   return pluginRuntime;
 }
@@ -135,7 +158,7 @@ const WebSocketChannel: ChannelPlugin<WebSocketChannelAccount> = {
               enum: ["pairing", "allowlist", "open", "disabled"],
             },
           },
-          required: ["mqttUrl"],
+          required: ["mqttUrl", "mqttTopic"],
         },
       },
     },
@@ -175,12 +198,12 @@ const WebSocketChannel: ChannelPlugin<WebSocketChannelAccount> = {
       },
       "config.mqttUrl": {
         label: "MQTT Broker URL",
-        placeholder: "ws://192.168.1.152:8083/mqtt",
+        placeholder: "ws://mqtt.example.com:8083/mqtt",
         help: "MQTT broker WebSocket URL",
       },
       "config.mqttTopic": {
         label: "MQTT Topic",
-        placeholder: "announcement/tester",
+        placeholder: "announcement/{userId}/{agentId}/#",
         help: "MQTT topic to subscribe/publish",
       },
       "config.groupPolicy": {
@@ -192,29 +215,43 @@ const WebSocketChannel: ChannelPlugin<WebSocketChannelAccount> = {
 
   config: {
     listAccountIds: (cfg: OpenClawConfig) => {
-      const channelCfg = cfg.channels?.["rol-websocket-channel"];
-      if (!channelCfg || !channelCfg.config || !channelCfg.config.mqttUrl) {
+      const channelCfg = getChannelConfig(cfg);
+      const mqttUrl = channelCfg
+        ? pickNonEmptyString(channelCfg.nested.mqttUrl, channelCfg.entry.mqttUrl)
+        : undefined;
+      if (!mqttUrl) {
         return [];
       }
       return ["default"];
     },
 
     resolveAccount: (cfg: OpenClawConfig, accountId: string) => {
-      const channelCfg = cfg.channels?.["rol-websocket-channel"];
-      if (!channelCfg || !channelCfg.config) {
+      const channelCfg = getChannelConfig(cfg);
+      if (!channelCfg) {
         return undefined;
       }
 
-      const config = channelCfg.config as any;
+      const config = channelCfg.nested;
+      const mqttUrl = pickNonEmptyString(config.mqttUrl, channelCfg.entry.mqttUrl);
+      if (!mqttUrl) {
+        return undefined;
+      }
+      const mqttTopic = pickNonEmptyString(
+        config.mqttTopic,
+        channelCfg.entry.mqttTopic,
+      );
+      if (!mqttTopic) {
+        return undefined;
+      }
 
       return {
         accountId: "default",
-        mqttUrl: config.mqttUrl || "ws://192.168.1.152:8083/mqtt",
-        mqttTopic: config.mqttTopic || "announcement/tester",
+        mqttUrl,
+        mqttTopic,
         enabled: config.enabled !== false,
-        dmPolicy: channelCfg.dmPolicy || config.groupPolicy || "open",
-        allowFrom: Array.isArray(channelCfg.allowFrom)
-          ? channelCfg.allowFrom
+        dmPolicy: channelCfg.entry.dmPolicy || config.groupPolicy || "open",
+        allowFrom: Array.isArray(channelCfg.entry.allowFrom)
+          ? channelCfg.entry.allowFrom
           : [],
         groupPolicy: config.groupPolicy || "open",
       };
@@ -322,8 +359,35 @@ const WebSocketChannel: ChannelPlugin<WebSocketChannelAccount> = {
         throw new Error("Runtime API not available");
       }
 
-      const mqttUrl = account.mqttUrl || "ws://192.168.1.152:8083/mqtt";
-      const mqttTopic = account.mqttTopic || "announcement/tester";
+      const mqttUrl = pickNonEmptyString(account.mqttUrl);
+      if (!mqttUrl) {
+        const message = "MQTT broker URL is not configured";
+        console.error(
+          `[MQTT] startAccount(${account.accountId}): ${message}`,
+        );
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          connected: false,
+          lastError: message,
+        });
+        throw new Error(message);
+      }
+      const mqttTopic = pickNonEmptyString(account.mqttTopic);
+      if (!mqttTopic) {
+        const message = "MQTT topic is not configured";
+        console.error(
+          `[MQTT] startAccount(${account.accountId}): ${message}`,
+        );
+        ctx.setStatus({
+          accountId: account.accountId,
+          mqttUrl,
+          running: false,
+          connected: false,
+          lastError: message,
+        });
+        throw new Error(message);
+      }
       console.log(
         `[MQTT] startAccount(${account.accountId}): url=${mqttUrl}, topic=${mqttTopic}`,
       );

package/openclaw.plugin.json

@@ -69,12 +69,12 @@
         },
         "mqttUrl": {
           "label": "MQTT Broker URL",
-          "placeholder": "ws://192.168.1.152:8083/mqtt",
-          "help": "MQTT broker WebSocket URL (e.g., ws://192.168.1.152:8083/mqtt)"
+          "placeholder": "ws://mqtt.example.com:8083/mqtt",
+          "help": "MQTT broker WebSocket URL"
         },
         "mqttTopic": {
           "label": "MQTT Topic",
-          "placeholder": "announcement/tester",
+          "placeholder": "announcement/{userId}/{agentId}/#",
           "help": "MQTT topic to subscribe/publish"
         },
         "groupPolicy": {
@@ -216,7 +216,7 @@
                     "enum": ["pairing", "allowlist", "open", "disabled"]
                   }
                 },
-                "required": ["mqttUrl"]
+                "required": ["mqttUrl", "mqttTopic"]
               }
             }
           }
@@ -294,12 +294,12 @@
     },
     "channels.rol-websocket-channel.config.mqttUrl": {
       "label": "MQTT Broker URL",
-      "placeholder": "ws://192.168.1.152:8083/mqtt",
-      "help": "MQTT broker WebSocket URL (e.g., ws://192.168.1.152:8083/mqtt)"
+      "placeholder": "ws://mqtt.example.com:8083/mqtt",
+      "help": "MQTT broker WebSocket URL"
     },
     "channels.rol-websocket-channel.config.mqttTopic": {
       "label": "MQTT Topic",
-      "placeholder": "announcement/tester",
+      "placeholder": "announcement/{userId}/{agentId}/#",
       "help": "MQTT topic to subscribe/publish"
     },
     "channels.rol-websocket-channel.config.groupPolicy": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rol-websocket-channel",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Unified OpenClaw plugin: MQTT Channel + Admin Bridge for remote management",
   "license": "MIT",
   "author": "nixgnehc",

package/src/admin/methods/pairing.ts

@@ -41,7 +41,7 @@ interface PairingPayload {
   };
   channel: {
     mqttUrl: string;
-    mqttTopic?: string;
+    mqttTopic: string;
     groupPolicy: 'pairing' | 'allowlist' | 'open' | 'disabled';
   };
 }
@@ -51,7 +51,8 @@ interface PairingPayloadDebug {
   rootKeys: string[];
   channelKeys: string[];
   channelConfigKeys: string[];
-  hasExistingMqttUrl: boolean;
+  hasExistingMqttUrl?: boolean;
+  hasRawValue?: boolean;
 }
 
 export async function pairWithKey(
@@ -181,7 +182,16 @@ function normalizePairingPayload(
     ?? pickString(root.mqttTopic)
     ?? pickString(root.mqtt_topic)
     ?? rawValue
-    ?? 'announcement/tester';
+    ?? null;
+  if (!mqttTopic) {
+    throwPairingError('PAIR_CHANNEL_CONFIG_INVALID', 'mqttTopic is missing from pairing payload', {
+      endpoint,
+      rootKeys: Object.keys(root),
+      channelKeys: Object.keys(channelValue),
+      channelConfigKeys: Object.keys(channelConfigValue),
+      hasRawValue: Boolean(rawValue)
+    });
+  }
 
   const groupPolicy = normalizeGroupPolicy(
     pickString(channelValue.groupPolicy)
@@ -266,7 +276,7 @@ function applyPairingConfig(config: OpenClawConfig, key: string, payload: Pairin
       ...existingChannelConfig,
       enabled: true,
       mqttUrl: payload.channel.mqttUrl,
-      mqttTopic: payload.channel.mqttTopic ?? existingChannelConfig.mqttTopic ?? 'announcement/tester',
+      mqttTopic: payload.channel.mqttTopic,
       groupPolicy: payload.channel.groupPolicy
     }
   };