fix(config): give actionable guidance when command names are used in plugins.allow (#64191)

feiskyer · steipete · commit 8cb45c051ed0 · 2026-04-10T14:56:12.000+01:00
When users put a runtime command name like "dreaming" into `plugins.allow`,
validation now explains that it is a command provided by a specific plugin
(e.g. "memory-core") and suggests using the plugin id instead, rather than
the generic "plugin not found" warning that previously created a circular
trap with the CLI error message.

Similarly, running `openclaw dreaming` from the CLI now explains that
`/dreaming` is a runtime slash command (not a CLI command) and points users
to `openclaw memory` for CLI operations or `/dreaming` in a chat session.

Fixes two related UX problems:
1. `plugins.allow: ["dreaming"]` → validation warned "plugin not found"
2. `openclaw dreaming status` → CLI said "add dreaming to plugins.allow"
   (which then triggered problem 1)

Root cause: "dreaming" is a slash command registered by the memory-core
plugin via `api.registerCommand()`, not a standalone plugin or CLI command.
diff --git a/src/cli/run-main.test.ts b/src/cli/run-main.test.ts
@@ -105,4 +105,22 @@ describe("resolveMissingPluginCommandMessage", () => {
       }),
     ).toBeNull();
   });
+
+  it("explains that dreaming is a runtime slash command, not a CLI command", () => {
+    const message = resolveMissingPluginCommandMessage("dreaming", {});
+    expect(message).toContain("runtime slash command");
+    expect(message).toContain("/dreaming");
+    expect(message).toContain("memory-core");
+    expect(message).toContain("openclaw memory");
+  });
+
+  it("returns the runtime command message even when plugins.allow is set", () => {
+    const message = resolveMissingPluginCommandMessage("dreaming", {
+      plugins: {
+        allow: ["memory-core"],
+      },
+    });
+    expect(message).toContain("runtime slash command");
+    expect(message).not.toContain("plugins.allow");
+  });
 });
diff --git a/src/cli/run-main.ts b/src/cli/run-main.ts
@@ -63,6 +63,15 @@ export function shouldUseRootHelpFastPath(argv: string[]): boolean {
   return resolveCliArgvInvocation(argv).isRootHelpInvocation;
 }
 
+/**
+ * Maps well-known runtime command names to the plugin that provides them.
+ * Used to give actionable guidance when users try to run a runtime slash
+ * command (e.g. `/dreaming`) as a CLI command (`openclaw dreaming`).
+ */
+const RUNTIME_COMMAND_TO_PLUGIN_ID: Record<string, string> = {
+  dreaming: "memory-core",
+};
+
 export function resolveMissingPluginCommandMessage(
   pluginId: string,
   config?: OpenClawConfig,
@@ -71,6 +80,17 @@ export function resolveMissingPluginCommandMessage(
   if (!normalizedPluginId) {
     return null;
   }
+
+  // Check if this is a runtime slash command rather than a CLI command.
+  const parentPluginId = RUNTIME_COMMAND_TO_PLUGIN_ID[normalizedPluginId];
+  if (parentPluginId) {
+    return (
+      `"${normalizedPluginId}" is a runtime slash command (/${normalizedPluginId}), not a CLI command. ` +
+      `It is provided by the "${parentPluginId}" plugin. ` +
+      `Use \`openclaw memory\` for CLI memory operations, or \`/${normalizedPluginId}\` in a chat session.`
+    );
+  }
+
   const allow =
     Array.isArray(config?.plugins?.allow) && config.plugins.allow.length > 0
       ? config.plugins.allow
diff --git a/src/config/config.plugin-validation.test.ts b/src/config/config.plugin-validation.test.ts
@@ -278,6 +278,35 @@ describe("config plugin validation", () => {
     }
   });
 
+  it("warns with actionable guidance when a runtime command name is used in plugins.allow", async () => {
+    const res = validateInSuite({
+      agents: { list: [{ id: "pi" }] },
+      plugins: {
+        allow: ["dreaming"],
+        entries: {
+          "memory-core": {
+            config: { dreaming: { enabled: true } },
+          },
+        },
+      },
+    });
+    // Should not produce the generic "plugin not found" warning.
+    expect(
+      res.warnings?.some(
+        (w) => w.path === "plugins.allow" && w.message.includes("plugin not found: dreaming"),
+      ),
+    ).toBe(false);
+    // Should produce a helpful redirect to the parent plugin.
+    expect(
+      res.warnings?.some(
+        (w) =>
+          w.path === "plugins.allow" &&
+          w.message.includes('"dreaming" is not a plugin') &&
+          w.message.includes("memory-core"),
+      ),
+    ).toBe(true);
+  });
+
   it("does not fail validation for the implicit default memory slot when plugins config is explicit", async () => {
     const res = validateConfigObjectWithPlugins(
       {
diff --git a/src/config/validation.ts b/src/config/validation.ts
@@ -40,6 +40,19 @@ import { OpenClawSchema } from "./zod-schema.js";
 
 const LEGACY_REMOVED_PLUGIN_IDS = new Set(["google-antigravity-auth", "google-gemini-cli-auth"]);
 
+/**
+ * Maps well-known runtime command names to the plugin that provides them.
+ * Used to give actionable guidance when users accidentally put a command name
+ * (e.g. "dreaming") into `plugins.allow` instead of the parent plugin id.
+ */
+const COMMAND_NAME_TO_PLUGIN_ID: Record<string, string> = {
+  dreaming: "memory-core",
+  // "active-memory" omitted: command name equals plugin id, no redirect needed.
+  voice: "talk-voice",
+  phone: "phone-control",
+  pair: "device-pair",
+};
+
 type UnknownIssueRecord = Record<string, unknown>;
 type ConfigPathSegment = string | number;
 type AllowedValuesCollection = {
@@ -1040,7 +1053,17 @@ function validateConfigObjectWithPluginsBase(
       continue;
     }
     if (!knownIds.has(pluginId)) {
-      pushMissingPluginIssue("plugins.allow", pluginId, { warnOnly: true });
+      const parentPluginId = COMMAND_NAME_TO_PLUGIN_ID[pluginId];
+      if (parentPluginId && parentPluginId !== pluginId && knownIds.has(parentPluginId)) {
+        warnings.push({
+          path: "plugins.allow",
+          message:
+            `"${pluginId}" is not a plugin — it is a command provided by the "${parentPluginId}" plugin. ` +
+            `Use "${parentPluginId}" in plugins.allow instead.`,
+        });
+      } else {
+        pushMissingPluginIssue("plugins.allow", pluginId, { warnOnly: true });
+      }
     }
   }
 
