@seeed-studio/meshtastic 0.1.1 → 0.2.1

package/src/monitor.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import { createLoggerBackedRuntime, type RuntimeEnv } from "openclaw/plugin-sdk";
+import { createLoggerBackedRuntime, type RuntimeEnv } from "openclaw/plugin-sdk/irc";
 import { resolveMeshtasticAccount } from "./accounts.js";
-import { connectMeshtasticClient, type MeshtasticClient } from "./client.js";
+import { connectMeshtasticClient, DeviceStatus, SetOwnerRebootError, type MeshtasticClient } from "./client.js";
 import { handleMeshtasticInbound } from "./inbound.js";
 import { connectMeshtasticMqtt, type MeshtasticMqttClient } from "./mqtt-client.js";
 import { nodeNumToHex } from "./normalize.js";
@@ -9,6 +9,28 @@ import { getMeshtasticRuntime } from "./runtime.js";
 import { setActiveSerialSend, setActiveMqttSend } from "./send.js";
 import type { CoreConfig, MeshtasticInboundMessage } from "./types.js";
 
+/** Inject a mention pattern (e.g. "@bard2") into the config so group messages
+ *  containing the pattern are recognized as mentions. */
+function injectMentionPattern(cfg: CoreConfig, name: string | undefined): CoreConfig {
+  if (!name) return cfg;
+  const mentionPattern = `@${name}`;
+  const existingPatterns =
+    (cfg as Record<string, unknown> & { messages?: { groupChat?: { mentionPatterns?: string[] } } })
+      .messages?.groupChat?.mentionPatterns ?? [];
+  if (existingPatterns.includes(mentionPattern)) return cfg;
+  return {
+    ...cfg,
+    messages: {
+      ...(cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined,
+      groupChat: {
+        ...((cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined)
+          ?.groupChat as Record<string, unknown> | undefined,
+        mentionPatterns: [...existingPatterns, mentionPattern],
+      },
+    },
+  };
+}
+
 export type MeshtasticMonitorOptions = {
   accountId?: string;
   config?: CoreConfig;
@@ -37,7 +59,7 @@ export async function monitorMeshtasticProvider(
   if (!account.configured) {
     throw new Error(
       `Meshtastic is not configured for account "${account.accountId}". ` +
-        `Set channels.meshtastic.transport and connection details.`,
+        `Run 'openclaw onboard' or set channels.meshtastic.transport and connection details in config.`,
     );
   }
 
@@ -48,33 +70,14 @@ export async function monitorMeshtasticProvider(
 
   const transport = account.transport;
 
-  // Auto-inject nodeName into mentionPatterns so "@NodeName" triggers replies.
-  // buildMentionRegexes reads from cfg.messages.groupChat.mentionPatterns, so
-  // we merge nodeName there (not in channel-specific config).
-  const nodeName = account.config.nodeName?.trim();
-  const mentionPattern = nodeName ? `@${nodeName}` : undefined;
-  const existingPatterns =
-    (cfg as Record<string, unknown> & { messages?: { groupChat?: { mentionPatterns?: string[] } } })
-      .messages?.groupChat?.mentionPatterns ?? [];
-  const effectiveCfg =
-    mentionPattern && !existingPatterns.includes(mentionPattern)
-      ? {
-          ...cfg,
-          messages: {
-            ...(cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined,
-            groupChat: {
-              ...((cfg as Record<string, unknown>).messages as Record<string, unknown> | undefined)
-                ?.groupChat as Record<string, unknown> | undefined,
-              mentionPatterns: [...existingPatterns, mentionPattern],
-            },
-          },
-        }
-      : cfg;
-
   if (transport === "mqtt") {
+    // MQTT: use config nodeName for mention pattern (no device to read from).
+    const effectiveCfg = injectMentionPattern(cfg, account.config.nodeName?.trim());
     return monitorMqtt({ account, cfg: effectiveCfg, runtime, logger, opts });
   }
-  return monitorDevice({ account, cfg: effectiveCfg, runtime, logger, opts, transport });
+  // Serial/HTTP: mention pattern is injected after connection so the device's
+  // actual name can be used as fallback when nodeName is not configured.
+  return monitorDevice({ account, cfg, runtime, logger, opts, transport });
 }
 
 async function monitorDevice(params: {
@@ -85,87 +88,110 @@ async function monitorDevice(params: {
   opts: MeshtasticMonitorOptions;
   transport: "serial" | "http";
 }): Promise<{ stop: () => void }> {
-  const { account, cfg, runtime, logger, opts, transport } = params;
+  const { account, runtime, logger, opts, transport } = params;
+  let cfg = params.cfg;
   const core = getMeshtasticRuntime();
 
   let client: MeshtasticClient | null = null;
 
-  client = await connectMeshtasticClient({
-    transport,
-    serialPort: account.serialPort,
-    httpAddress: account.httpAddress,
-    httpTls: account.httpTls,
-    region: account.config.region,
-    nodeName: account.config.nodeName,
-    abortSignal: opts.abortSignal,
-    onStatus: (status) => {
-      logger.info(`[${account.accountId}] device ${status}`);
-    },
-    onError: (error) => {
-      logger.error(`[${account.accountId}] error: ${error.message}`);
-    },
-    onText: async (event) => {
-      if (!client) {
-        return;
-      }
-
-      const channelName =
-        client.getChannelName(event.channelIndex) ?? `channel-${event.channelIndex}`;
-
-      const message: MeshtasticInboundMessage = {
-        messageId: randomUUID(),
-        senderNodeId: event.senderNodeId,
-        senderName: event.senderName ?? client.getNodeName(event.senderNodeNum),
-        channelIndex: event.channelIndex,
-        channelName,
-        text: event.text,
-        timestamp: event.rxTime,
-        isGroup: !event.isDirect,
-      };
+  try {
+    client = await connectMeshtasticClient({
+      transport,
+      serialPort: account.serialPort,
+      httpAddress: account.httpAddress,
+      httpTls: account.httpTls,
+      region: account.config.region,
+      nodeName: account.config.nodeName,
+      abortSignal: opts.abortSignal,
+      onStatus: (status) => {
+        logger.info(`[${account.accountId}] device ${status}`);
+      },
+      onError: (error) => {
+        logger.error(`[${account.accountId}] error: ${error.message}`);
+      },
+      onText: async (event) => {
+        if (!client) {
+          return;
+        }
 
-      core.channel.activity.record({
-        channel: "meshtastic",
-        accountId: account.accountId,
-        direction: "inbound",
-        at: message.timestamp,
-      });
+        const channelName =
+          client.getChannelName(event.channelIndex) ?? `channel-${event.channelIndex}`;
+
+        const message: MeshtasticInboundMessage = {
+          messageId: randomUUID(),
+          senderNodeId: event.senderNodeId,
+          senderName: event.senderName ?? client.getNodeName(event.senderNodeNum),
+          channelIndex: event.channelIndex,
+          channelName,
+          text: event.text,
+          timestamp: event.rxTime,
+          isGroup: !event.isDirect,
+        };
+
+        core.channel.activity.record({
+          channel: "meshtastic",
+          accountId: account.accountId,
+          direction: "inbound",
+          at: message.timestamp,
+        });
+
+        await handleMeshtasticInbound({
+          message,
+          account,
+          config: cfg,
+          runtime,
+          sendReply: async (target, text) => {
+            if (!client) {
+              return;
+            }
+            // For DM replies, resolve node number from hex ID.
+            // For group replies, broadcast to the same channel.
+            if (message.isGroup) {
+              // Broadcast: fire-and-forget.  The SDK's sendText promise waits
+              // for internal queue confirmation which may time out for broadcasts.
+              // The radio sends the packet regardless, so we don't await.
+              client.sendText(text, undefined, false, message.channelIndex).catch((err) => {
+                logger.warn(`[${account.accountId}] broadcast send failed: ${err instanceof Error ? err.message : String(err)}`);
+              });
+            } else {
+              // DM: fire-and-forget.  The SDK's sendText awaits ACK from the
+              // target node; if ACK times out the promise rejects, but the radio
+              // has already transmitted the packet.  Awaiting would block
+              // subsequent reply chunks.
+              const { hexToNodeNum } = await import("./normalize.js");
+              const destNum = hexToNodeNum(target);
+              client.sendText(text, destNum, true).catch((err) => {
+                logger.warn(`[${account.accountId}] DM send failed to ${target}: ${err instanceof Error ? err.message : String(err)}`);
+              });
+            }
+            opts.statusSink?.({ lastOutboundAt: Date.now() });
+            core.channel.activity.record({
+              channel: "meshtastic",
+              accountId: account.accountId,
+              direction: "outbound",
+            });
+          },
+          statusSink: opts.statusSink,
+        });
+      },
+    });
+  } catch (err) {
+    if (err instanceof SetOwnerRebootError) {
+      logger.info(`[${account.accountId}] ${err.message}`);
+      // Wait for the device to finish rebooting before the framework retries.
+      logger.info(`[${account.accountId}] waiting 30s for device reboot...`);
+      await new Promise((r) => setTimeout(r, 30_000));
+    }
+    throw err;
+  }
 
-      await handleMeshtasticInbound({
-        message,
-        account,
-        config: cfg,
-        runtime,
-        sendReply: async (target, text) => {
-          if (!client) {
-            return;
-          }
-          // For DM replies, resolve node number from hex ID.
-          // For group replies, broadcast to the same channel.
-          if (message.isGroup) {
-            // Broadcast: fire-and-forget.  The SDK's sendText promise waits
-            // for internal queue confirmation which may time out for broadcasts.
-            // The radio sends the packet regardless, so we don't await.
-            client.sendText(text, undefined, false, message.channelIndex).catch(() => {});
-          } else {
-            // DM: fire-and-forget.  The SDK's sendText awaits ACK from the
-            // target node; if ACK times out the promise rejects, but the radio
-            // has already transmitted the packet.  Awaiting would block
-            // subsequent reply chunks.
-            const { hexToNodeNum } = await import("./normalize.js");
-            const destNum = hexToNodeNum(target);
-            client.sendText(text, destNum, true).catch(() => {});
-          }
-          opts.statusSink?.({ lastOutboundAt: Date.now() });
-          core.channel.activity.record({
-            channel: "meshtastic",
-            accountId: account.accountId,
-            direction: "outbound",
-          });
-        },
-        statusSink: opts.statusSink,
-      });
-    },
-  });
+  // Determine the effective device name for @mention matching.
+  // If nodeName is configured, use it.  Otherwise read the device's actual name.
+  const effectiveName = account.config.nodeName?.trim() || client.getMyNodeName();
+  cfg = injectMentionPattern(cfg, effectiveName);
+  if (effectiveName) {
+    logger.info(`[${account.accountId}] mention trigger: @${effectiveName}`);
+  }
 
   // Register active send function for `openclaw message send`.
   setActiveSerialSend((text, destination, channelIndex) =>
@@ -189,7 +215,7 @@ async function monitorDevice(params: {
       opts.abortSignal.addEventListener("abort", () => resolve(), { once: true });
     }
     client!.device.events.onDeviceStatus.subscribe((status: number) => {
-      if (status === 2 /* DeviceDisconnected */) {
+      if (status === DeviceStatus.Disconnected) {
         logger.info(`[${account.accountId}] device disconnected, exiting monitor`);
         resolve();
       }
@@ -203,6 +229,7 @@ async function monitorDevice(params: {
 
   // Give the OS time to release the serial port lock before the framework
   // restarts the channel (which would immediately try to reopen it).
+  logger.info(`[${account.accountId}] releasing serial port (3s delay)...`);
   await new Promise<void>((r) => setTimeout(r, 3_000));
 
   return { stop: () => {} };
@@ -220,7 +247,7 @@ async function monitorMqtt(params: {
   const mqttConfig = account.config.mqtt;
 
   if (!mqttConfig?.broker) {
-    throw new Error("MQTT broker not configured");
+    throw new Error("MQTT broker not configured. Set channels.meshtastic.mqtt.broker or run 'openclaw onboard'.");
   }
 
   let mqttClient: MeshtasticMqttClient | null = null;

package/src/mqtt-client.ts

@@ -2,6 +2,16 @@ import mqtt from "mqtt";
 import { nodeNumToHex } from "./normalize.js";
 import type { MeshtasticMqttConfig } from "./types.js";
 
+/** Derive a publish topic from a subscribe topic.
+ *  Standard pattern: "msh/REGION/NUM/json/#" → "msh/REGION/NUM/json/mqtt".
+ *  If the topic has no wildcard suffix, appends "/mqtt" as the publish leaf. */
+function derivePublishTopic(subscribeTopic: string): string {
+  if (subscribeTopic.endsWith("/#")) {
+    return subscribeTopic.slice(0, -2) + "/mqtt";
+  }
+  return subscribeTopic + "/mqtt";
+}
+
 export type MeshtasticMqttTextEvent = {
   senderNodeId: string;
   senderName?: string;
@@ -50,9 +60,16 @@ export async function connectMeshtasticMqtt(
   const username = mqttConfig.username ?? "meshdev";
   const password = mqttConfig.password ?? "large4cats";
   const topic = mqttConfig.topic ?? "msh/US/2/json/#";
-  const publishTopic = mqttConfig.publishTopic ?? topic.replace("/#", "/mqtt");
+  const publishTopic = mqttConfig.publishTopic ?? derivePublishTopic(topic);
   const protocol = mqttConfig.tls ? "mqtts" : "mqtt";
-  const myNodeId = options.myNodeId?.toLowerCase();
+  const myNodeId = (mqttConfig.myNodeId ?? options.myNodeId)?.toLowerCase();
+
+  if (!myNodeId) {
+    options.onStatus?.(
+      "warning: myNodeId not set — all messages will be treated as group. " +
+        "Set channels.meshtastic.mqtt.myNodeId for DM support.",
+    );
+  }
 
   const client = mqtt.connect(`${protocol}://${broker}:${port}`, {
     username,
@@ -111,13 +128,19 @@ export async function connectMeshtasticMqtt(
     }
 
     // Determine DM vs broadcast.
-    // MQTT JSON doesn't clearly distinguish DM; if `to` is a specific node and matches our ID, it's direct.
-    const isDirect = myNodeId
-      ? msg.to !== undefined && nodeNumToHex(msg.to).toLowerCase() === myNodeId
-      : false;
+    // MQTT JSON: if `to` matches our node ID, it's a direct message.
+    const isDirect = myNodeId !== undefined
+      && msg.to !== undefined
+      && msg.to !== 0xffffffff
+      && nodeNumToHex(msg.to).toLowerCase() === myNodeId;
+
+    const senderName = msg.sender && msg.sender !== senderNodeId
+      ? msg.sender
+      : undefined;
 
     const event: MeshtasticMqttTextEvent = {
       senderNodeId: senderNodeId.startsWith("!") ? senderNodeId : `!${senderNodeId}`,
+      senderName,
       text: msg.payload.text,
       channelIndex: msg.channel ?? 0,
       channelName: msg.channel_name,
@@ -152,6 +175,7 @@ export async function connectMeshtasticMqtt(
         type: "sendtext",
         payload: { text },
         ...(destination ? { to: Number.parseInt(destination.replace("!", ""), 16) } : {}),
+        ...(channelName ? { channel_name: channelName } : {}),
       };
       client.publish(outboundTopic, JSON.stringify(message));
     },

package/src/normalize.ts

@@ -28,13 +28,16 @@ export function normalizeMeshtasticNodeId(raw: string): string {
     }
     return trimmed;
   }
+  // Bare hex string (contains at least one a-f character to disambiguate from decimal).
+  if (/^[0-9a-f]{1,8}$/i.test(trimmed) && !/^\d+$/.test(trimmed)) {
+    return `!${trimmed.padStart(8, "0")}`;
+  }
   const num = Number.parseInt(trimmed, 10);
   if (Number.isFinite(num) && num >= 0) {
     return nodeNumToHex(num);
   }
   return trimmed;
 }
-
 /** Check if a string looks like a Meshtastic node ID (!hex or numeric). */
 export function looksLikeMeshtasticNodeId(raw: string): boolean {
   const trimmed = raw.trim();
@@ -44,10 +47,13 @@ export function looksLikeMeshtasticNodeId(raw: string): boolean {
   if (trimmed.startsWith("!") && /^![0-9a-f]{1,8}$/i.test(trimmed)) {
     return true;
   }
+  // Bare hex string (contains at least one a-f to disambiguate from decimal).
+  if (/^[0-9a-f]{1,8}$/i.test(trimmed) && !/^\d+$/.test(trimmed)) {
+    return true;
+  }
   const num = Number.parseInt(trimmed, 10);
   return Number.isFinite(num) && num >= 0 && String(num) === trimmed;
 }
-
 /** Normalize a messaging target. Strips "meshtastic:" prefix, resolves channel: prefix. */
 export function normalizeMeshtasticMessagingTarget(raw: string): string | undefined {
   const trimmed = raw.trim();
@@ -89,8 +95,10 @@ export function normalizeMeshtasticAllowEntry(raw: string): string {
 }
 
 /** Normalize a list of allowlist entries. */
-export function normalizeMeshtasticAllowlist(entries?: string[]): string[] {
-  return (entries ?? []).map((entry) => normalizeMeshtasticAllowEntry(entry)).filter(Boolean);
+export function normalizeMeshtasticAllowlist(entries?: unknown[]): string[] {
+  return (entries ?? [])
+    .map((entry) => (typeof entry === "string" ? normalizeMeshtasticAllowEntry(entry) : ""))
+    .filter(Boolean);
 }
 
 /** Check if sender matches an allowlist. */

package/src/onboarding.ts

@@ -1,14 +1,19 @@
+import { readdir } from "node:fs/promises";
 import {
   addWildcardAllowFrom,
   DEFAULT_ACCOUNT_ID,
   formatDocsLink,
-  promptAccountId,
-  promptChannelAccessConfig,
-  type ChannelOnboardingAdapter,
-  type ChannelOnboardingDmPolicy,
   type DmPolicy,
   type WizardPrompter,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/irc";
+import {
+  promptAccountId,
+  promptChannelAccessConfig,
+} from "openclaw/plugin-sdk/matrix";
+import type {
+  ChannelSetupAdapter as ChannelOnboardingAdapter,
+  ChannelSetupDmPolicy as ChannelOnboardingDmPolicy,
+} from "openclaw/plugin-sdk/setup";
 import {
   listMeshtasticAccountIds,
   resolveDefaultMeshtasticAccountId,
@@ -24,6 +29,57 @@ import type {
 
 const channel = "meshtastic" as const;
 
+async function detectMeshtasticSerialPortCandidates(): Promise<string[]> {
+  const candidates = new Set<string>();
+
+  try {
+    const devEntries = await readdir("/dev");
+    for (const entry of devEntries) {
+      if (
+        entry.startsWith("cu.usb")
+        || entry.startsWith("tty.usb")
+        || entry.startsWith("ttyUSB")
+        || entry.startsWith("ttyACM")
+      ) {
+        candidates.add(`/dev/${entry}`);
+      }
+    }
+  } catch {}
+
+  try {
+    const byIdEntries = await readdir("/dev/serial/by-id");
+    for (const entry of byIdEntries) {
+      candidates.add(`/dev/serial/by-id/${entry}`);
+    }
+  } catch {}
+
+  return [...candidates].sort((a, b) => a.localeCompare(b));
+}
+
+const REGION_OPTIONS: { value: string; label: string }[] = [
+  { value: "US", label: "US (902-928 MHz)" },
+  { value: "EU_433", label: "EU_433 (433 MHz)" },
+  { value: "EU_868", label: "EU_868 (869 MHz)" },
+  { value: "CN", label: "CN (470-510 MHz)" },
+  { value: "JP", label: "JP (920 MHz)" },
+  { value: "ANZ", label: "ANZ (915-928 MHz)" },
+  { value: "KR", label: "KR (920-923 MHz)" },
+  { value: "TW", label: "TW (920-925 MHz)" },
+  { value: "RU", label: "RU (868 MHz)" },
+  { value: "IN", label: "IN (865-867 MHz)" },
+  { value: "TH", label: "TH (920-925 MHz)" },
+  { value: "LORA_24", label: "LORA_24 (2.4 GHz)" },
+];
+
+function regionToMqttTopic(region: string): string {
+  return `msh/${region}/2/json/#`;
+}
+
+function parseRegionFromTopic(topic: string): string | undefined {
+  const match = topic.match(/^msh\/([^/]+)\//);
+  return match?.[1];
+}
+
 function parseListInput(raw: string): string[] {
   return raw
     .split(/[\n,;]+/g)
@@ -227,14 +283,39 @@ export const meshtasticOnboardingAdapter: ChannelOnboardingAdapter = {
     const transport = String(transportChoice) as MeshtasticTransport;
 
     if (transport === "serial") {
-      const serialPort = String(
-        await prompter.text({
-          message: "Serial port path",
-          placeholder: "/dev/ttyUSB0 or /dev/tty.usbmodem*",
-          initialValue: resolved.serialPort || undefined,
-          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
-        }),
-      ).trim();
+      const serialCandidates = await detectMeshtasticSerialPortCandidates();
+      let serialPort = resolved.serialPort || "";
+      let needsManualSerialInput = true;
+
+      if (serialCandidates.length > 0) {
+        const initialDetected = serialCandidates.includes(serialPort)
+          ? serialPort
+          : serialCandidates[0];
+        const detectedChoice = await prompter.select({
+          message: "Detected serial port",
+          options: [
+            ...serialCandidates.map((value) => ({ value, label: value })),
+            { value: "__manual__", label: "Manual input" },
+          ],
+          initialValue: initialDetected,
+        });
+        const selected = String(detectedChoice);
+        if (selected !== "__manual__") {
+          serialPort = selected;
+          needsManualSerialInput = false;
+        }
+      }
+
+      if (needsManualSerialInput) {
+        serialPort = String(
+          await prompter.text({
+            message: "Serial port path",
+            placeholder: "/dev/ttyUSB0 or /dev/tty.usbmodem*",
+            initialValue: serialPort || undefined,
+            validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+          }),
+        ).trim();
+      }
 
       next = updateMeshtasticAccountConfig(next, accountId, {
         enabled: true,
@@ -295,10 +376,20 @@ export const meshtasticOnboardingAdapter: ChannelOnboardingAdapter = {
         }),
       ).trim();
 
+      // Region selection — generates the default MQTT topic.
+      const existingTopic = resolved.config.mqtt?.topic || "msh/US/2/json/#";
+      const currentMqttRegion = parseRegionFromTopic(existingTopic) ?? "US";
+      const mqttRegionChoice = await prompter.select({
+        message: "LoRa region (determines which mesh traffic to receive)",
+        options: REGION_OPTIONS,
+        initialValue: currentMqttRegion,
+      });
+      const mqttRegion = String(mqttRegionChoice);
+
       const topic = String(
         await prompter.text({
           message: "MQTT subscribe topic",
-          initialValue: resolved.config.mqtt?.topic || "msh/US/2/json/#",
+          initialValue: regionToMqttTopic(mqttRegion),
           validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
         }),
       ).trim();
@@ -328,18 +419,7 @@ export const meshtasticOnboardingAdapter: ChannelOnboardingAdapter = {
         message: "LoRa region",
         options: [
           { value: "UNSET", label: "UNSET (keep device default)" },
-          { value: "US", label: "US (902-928 MHz)" },
-          { value: "EU_433", label: "EU_433 (433 MHz)" },
-          { value: "EU_868", label: "EU_868 (869 MHz)" },
-          { value: "CN", label: "CN (470-510 MHz)" },
-          { value: "JP", label: "JP (920 MHz)" },
-          { value: "ANZ", label: "ANZ (915-928 MHz)" },
-          { value: "KR", label: "KR (920-923 MHz)" },
-          { value: "TW", label: "TW (920-925 MHz)" },
-          { value: "RU", label: "RU (868 MHz)" },
-          { value: "IN", label: "IN (865-867 MHz)" },
-          { value: "TH", label: "TH (920-925 MHz)" },
-          { value: "LORA_24", label: "LORA_24 (2.4 GHz)" },
+          ...REGION_OPTIONS,
         ],
         initialValue: resolved.config.region ?? "UNSET",
       });
@@ -352,11 +432,19 @@ export const meshtasticOnboardingAdapter: ChannelOnboardingAdapter = {
     // Device display name — also used as a mention pattern so users can
     // @NodeName the bot in group channels.
     const currentNodeName = resolveMeshtasticAccount({ cfg: next, accountId }).config.nodeName;
+    const isMqtt = transport === "mqtt";
     const nodeNameInput = String(
       await prompter.text({
-        message: "Device display name (also used as @mention trigger)",
-        placeholder: "e.g. OpenClaw",
+        message: isMqtt
+          ? "Device display name (required for MQTT — used as @mention trigger)"
+          : "Device display name (leave empty to auto-detect from device)",
+        placeholder: isMqtt
+          ? "e.g. OpenClaw"
+          : "e.g. OpenClaw (empty = use device's current name)",
         initialValue: currentNodeName || undefined,
+        validate: isMqtt
+          ? (value) => (String(value ?? "").trim() ? undefined : "Required for MQTT (no device to auto-detect from)")
+          : undefined,
       }),
     ).trim();
     if (nodeNameInput) {

package/src/policy.ts

@@ -137,11 +137,15 @@ export function resolveMeshtasticGroupSenderAllowed(params: {
   const inner = normalizeMeshtasticAllowlist(params.innerAllowFrom);
   const outer = normalizeMeshtasticAllowlist(params.outerAllowFrom);
 
+  // Fallback strategy: check channel-specific allowlist first, then fall
+  // back to the global allowlist.  This ensures global admin nodes are
+  // never locked out of channels that define their own lists.
   if (inner.length > 0) {
-    return resolveMeshtasticAllowlistMatch({
+    const innerResult = resolveMeshtasticAllowlistMatch({
       allowFrom: inner,
       message: params.message,
-    }).allowed;
+    });
+    if (innerResult.allowed) return true;
   }
   if (outer.length > 0) {
     return resolveMeshtasticAllowlistMatch({