rol-websocket-channel 1.5.2 → 1.5.5

package/{MQTT-API 5-6.md → MQTT-API System.md }

@@ -1,4 +1,4 @@
-# OpenClaw MQTT API 文档 （新增文件功能）
+# OpenClaw MQTT API 文档 （System 更新接口）
 
 ## 消息格式
 
@@ -1797,3 +1797,114 @@ MQTT 请求示例：
 - `category === "document"` 时，可以作为文档展示或下载。
 - `storageStatus === "local_only"` 时，先调 `artifactsEnsureUploaded` 获取可访问的 `downloadUrl`。
 - `storageStatus === "uploaded"` 且 `fileUrl` 存在时，可以直接使用 `fileUrl` 展示或下载。
+
+---
+
+## System 更新接口
+
+这两个接口用于 App 按钮触发本机 OpenClaw 或当前插件更新。请求通过 MQTT 发送到当前已配对设备，插件会在本机执行对应的 `openclaw` 命令。
+
+### openclawUpdate
+
+作用：升级本机 OpenClaw。
+
+实际执行命令：
+
+```bash
+openclaw update
+```
+
+MQTT 请求示例：
+
+```json
+{
+  "type": "openclawUpdate",
+  "trace_id": "openclaw-update-001",
+  "data": {}
+}
+```
+
+成功返回示例：
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "openclaw-update-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "action": "openclawUpdate",
+    "restartRecommended": true,
+    "command": "openclaw",
+    "args": ["update"],
+    "cwd": "/home/woowonjae/.openclaw",
+    "stdout": "...",
+    "stderr": ""
+  }
+}
+```
+
+### pluginSelfUpdate
+
+作用：升级当前 `rol-websocket-channel` 插件。
+
+实际执行命令：
+
+```bash
+openclaw plugins update rol-websocket-channel
+```
+
+MQTT 请求示例：
+
+```json
+{
+  "type": "pluginSelfUpdate",
+  "trace_id": "plugin-self-update-001",
+  "data": {}
+}
+```
+
+成功返回示例：
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "plugin-self-update-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "action": "pluginSelfUpdate",
+    "plugin": "rol-websocket-channel",
+    "restartRecommended": true,
+    "command": "openclaw",
+    "args": ["plugins", "update", "rol-websocket-channel"],
+    "cwd": "/home/woowonjae/.openclaw",
+    "stdout": "...",
+    "stderr": ""
+  }
+}
+```
+
+### 失败返回
+
+如果本机命令执行失败，`success` 会是 `false`，错误信息里会带上实际执行的命令、参数、工作目录、`stdout` 和 `stderr`，前端可以直接展示 `error.message` 或 `error.stderr`。
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "plugin-self-update-001",
+  "source": "system",
+  "success": false,
+  "error": {
+    "message": "OpenClaw system command failed: Command failed: openclaw plugins update rol-websocket-channel",
+    "action": "pluginSelfUpdate",
+    "command": "openclaw",
+    "args": ["plugins", "update", "rol-websocket-channel"],
+    "cwd": "/home/woowonjae/.openclaw",
+    "stdout": "...",
+    "stderr": "..."
+  }
+}
+```

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/mem9.js

@@ -211,6 +211,10 @@ async function writeMem9Config(openclawRoot, apiKey) {
     config.plugins.entries[MEM9_PLUGIN_ID] = {
         ...existingEntry,
         enabled: true,
+        hooks: {
+            ...(isRecord(existingEntry.hooks) ? existingEntry.hooks : {}),
+            allowConversationAccess: true
+        },
         config: {
             ...existingPluginConfig,
             apiUrl: MEM9_API_URL,
@@ -221,6 +225,7 @@ async function writeMem9Config(openclawRoot, apiKey) {
     await writeJsonFile(configPath, config);
     return [
         hadExistingKey ? 'plugins.entries.mem9.config.apiKey (replaced)' : 'plugins.entries.mem9',
+        'plugins.entries.mem9.hooks.allowConversationAccess',
         'plugins.slots.memory'
     ];
 }
@@ -240,6 +245,10 @@ async function ensureMem9SlotConfig(openclawRoot, apiKey) {
     config.plugins.entries[MEM9_PLUGIN_ID] = {
         ...existingEntry,
         enabled: true,
+        hooks: {
+            ...(isRecord(existingEntry.hooks) ? existingEntry.hooks : {}),
+            allowConversationAccess: true
+        },
         config: {
             ...existingPluginConfig,
             apiUrl: MEM9_API_URL,
@@ -250,6 +259,7 @@ async function ensureMem9SlotConfig(openclawRoot, apiKey) {
     await writeJsonFile(configPath, config);
     return [
         'plugins.entries.mem9',
+        'plugins.entries.mem9.hooks.allowConversationAccess',
         'plugins.slots.memory'
     ];
 }

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/dist/src/admin/methods/system.js

@@ -81,11 +81,11 @@ export const openclawUpdate = async (_params, context) => {
     };
 };
 export const pluginSelfUpdate = async (_params, context) => {
-    const result = await runOpenClawCommand(['plugins', 'install', 'clawhub:rol-websocket-channel'], context, 'pluginSelfUpdate');
+    const result = await runOpenClawCommand(['plugins', 'update', 'rol-websocket-channel'], context, 'pluginSelfUpdate');
     return {
         ok: true,
         action: 'pluginSelfUpdate',
-        plugin: 'clawhub:rol-websocket-channel',
+        plugin: 'rol-websocket-channel',
         restartRecommended: true,
         ...result
     };

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.2",
+  "version": "1.5.5",
   "description": "Unified OpenClaw plugin: MQTT Channel + Admin Bridge for remote management",
   "license": "MIT",
   "author": "nixgnehc",

package/src/admin/methods/mem9.ts

@@ -270,6 +270,10 @@ async function writeMem9Config(openclawRoot: string, apiKey: string): Promise<st
   config.plugins.entries[MEM9_PLUGIN_ID] = {
     ...existingEntry,
     enabled: true,
+    hooks: {
+      ...(isRecord(existingEntry.hooks) ? existingEntry.hooks : {}),
+      allowConversationAccess: true
+    },
     config: {
       ...existingPluginConfig,
       apiUrl: MEM9_API_URL,
@@ -282,6 +286,7 @@ async function writeMem9Config(openclawRoot: string, apiKey: string): Promise<st
 
   return [
     hadExistingKey ? 'plugins.entries.mem9.config.apiKey (replaced)' : 'plugins.entries.mem9',
+    'plugins.entries.mem9.hooks.allowConversationAccess',
     'plugins.slots.memory'
   ];
 }
@@ -304,6 +309,10 @@ async function ensureMem9SlotConfig(openclawRoot: string, apiKey: string): Promi
   config.plugins.entries[MEM9_PLUGIN_ID] = {
     ...existingEntry,
     enabled: true,
+    hooks: {
+      ...(isRecord(existingEntry.hooks) ? existingEntry.hooks : {}),
+      allowConversationAccess: true
+    },
     config: {
       ...existingPluginConfig,
       apiUrl: MEM9_API_URL,
@@ -316,6 +325,7 @@ async function ensureMem9SlotConfig(openclawRoot: string, apiKey: string): Promi
 
   return [
     'plugins.entries.mem9',
+    'plugins.entries.mem9.hooks.allowConversationAccess',
     'plugins.slots.memory'
   ];
 }

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
     }
   };

package/src/admin/methods/system.ts

@@ -91,7 +91,7 @@ export const openclawUpdate: MethodHandler = async (_params, context: MethodCont
 
 export const pluginSelfUpdate: MethodHandler = async (_params, context: MethodContext): Promise<JsonValue> => {
   const result = await runOpenClawCommand(
-    ['plugins', 'install', 'clawhub:rol-websocket-channel'],
+    ['plugins', 'update', 'rol-websocket-channel'],
     context,
     'pluginSelfUpdate'
   );
@@ -99,7 +99,7 @@ export const pluginSelfUpdate: MethodHandler = async (_params, context: MethodCo
   return {
     ok: true,
     action: 'pluginSelfUpdate',
-    plugin: 'clawhub:rol-websocket-channel',
+    plugin: 'rol-websocket-channel',
     restartRecommended: true,
     ...result
   };