fix(cli): clarify error when unknown subcommand is actually an agent tool name

100yenadmin · claude · commit ae62a99b3537 · 2026-05-08T17:02:30.000+07:00
When `openclaw <name>` does not match a CLI subcommand or a plugin id, the unknown-subcommand handler now first looks up <name> against the manifest plugin tool registry. If <name> is an agent tool declared by a plugin (e.g. `lcm_recent` from `lossless-claw`), emit a clear 'this is an agent tool, not a CLI subcommand' error pointing at model tool-use instead of the misleading `plugins.allow` suggestion. The previous error told the user to add the tool name to `plugins.allow`, but `plugins.allow` accepts plugin ids (not tool names), and config patches against it are rejected by the protected-config-paths guard. In the wild this sent an agent down 3 restart cycles trying to 'fix' config that was never the problem. Filtering: the runtime resolver consults the full manifest snapshot and filters through `isManifestPluginAvailableForControlPlane` (covering `plugins.allow`/`plugins.deny`/`plugins.entries[id].enabled`/installed index) plus per-tool `hasManifestToolAvailability` (covering `toolMetadata.configSignals` like Feishu's `appId`/`appSecret` gate). The diagnostic also re-checks `plugins.allow` and `plugins.entries[X].enabled` for the OWNING plugin before emitting, so denied/disabled plugins are not falsely attributed. Wording: when ownership is only manifest-provable (per-account `enabled` flags and per-tool toggles in the Feishu family are runtime-only and not declarable as configSignals, so the manifest is necessarily an over-approximation), emit a softer 'may be provided by the X plugin' message instead of asserting 'registered by'. The strong wording is reserved for the case where both control-plane availability and tool availability pass. Fall-throughs: if <name> is not a registered tool, the existing `plugins.allow` and `plugins.entries.<id>.enabled` suggestions are emitted unchanged. The new branch only fires when the tool-registry lookup matches AND the owning plugin passes availability filters. Closes #77214.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -183,6 +183,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- CLI/router: when `openclaw <name>` does not match a CLI subcommand, check the runtime plugin tool registry first so that names that are actually agent tools (e.g. `lcm_recent`) get a "this is an agent tool registered by the `<plugin>` plugin, not a CLI subcommand" error instead of the misleading suggestion to add the tool name to `plugins.allow`. Fixes #77214.
 - Agents/compaction: keep the recent tail after manual `/compact` when Pi returns an empty or no-op compaction summary, preventing blank checkpoints from replacing the live context.
 - fix(discord): gate user allowlist name resolution [AI]. (#79002) Thanks @pgondhi987.
 - fix(msteams): gate startup user allowlist resolution [AI]. (#79003) Thanks @pgondhi987.
diff --git a/src/cli/run-main-policy.ts b/src/cli/run-main-policy.ts
@@ -1,8 +1,10 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   resolveManifestCommandAliasOwnerInRegistry,
+  resolveManifestToolOwnerInRegistry,
   type PluginManifestCommandAliasRecord,
   type PluginManifestCommandAliasRegistry,
+  type PluginManifestToolOwnerRecord,
 } from "../plugins/manifest-command-aliases.js";
 import {
   normalizeLowercaseStringOrEmpty,
@@ -105,6 +107,11 @@ export function resolveMissingPluginCommandMessage(
       config?: OpenClawConfig;
       registry?: PluginManifestCommandAliasRegistry;
     }) => PluginManifestCommandAliasRecord | undefined;
+    resolveToolOwner?: (params: {
+      toolName: string | undefined;
+      config?: OpenClawConfig;
+      registry?: PluginManifestCommandAliasRegistry;
+    }) => PluginManifestToolOwnerRecord | undefined;
   },
 ): string | null {
   const normalizedPluginId = normalizeLowercaseStringOrEmpty(pluginId);
@@ -171,6 +178,47 @@ export function resolveMissingPluginCommandMessage(
     return null;
   }
 
+  const toolOwner = options?.registry
+    ? resolveManifestToolOwnerInRegistry({
+        toolName: normalizedPluginId,
+        registry: options.registry,
+      })
+    : options?.resolveToolOwner?.({
+        toolName: normalizedPluginId,
+        config,
+        ...(options?.registry ? { registry: options.registry } : {}),
+      });
+  if (toolOwner) {
+    // Apply plugins.allow / plugins.entries[X].enabled to the owning plugin so
+    // a disabled/denied plugin's manifest-declared tool name does not get a
+    // false "registered by" attribution. The runtime resolver
+    // (resolveManifestToolOwner) already filters by control-plane availability,
+    // but pure-registry callers and any future ones still need this guard.
+    const ownerEnabled =
+      config?.plugins?.entries?.[toolOwner.pluginId]?.enabled !== false &&
+      (allow.length === 0 || allow.includes(toolOwner.pluginId));
+    if (ownerEnabled) {
+      // Per-account / per-tool runtime gates (e.g. Feishu's
+      // channels.feishu.enabled / tools.<x> toggles) are not declarable as
+      // manifest configSignals, so a positive manifest-availability signal
+      // proves "could be loaded if config permits", not "currently registered".
+      // Soften the wording when the runtime resolver could only prove
+      // manifest-level ownership.
+      if (toolOwner.availability === "manifest-only") {
+        return (
+          `"${normalizedPluginId}" may be provided by the "${toolOwner.pluginId}" plugin ` +
+          `as an agent tool, not a CLI subcommand. ` +
+          "Run `openclaw --help` to see available CLI subcommands."
+        );
+      }
+      return (
+        `"${normalizedPluginId}" is an agent tool registered by the "${toolOwner.pluginId}" plugin, ` +
+        `not a CLI subcommand. Use it from an agent turn (model tool-use), not the CLI. ` +
+        "Run `openclaw --help` to see available CLI subcommands."
+      );
+    }
+  }
+
   if (allow.length > 0 && !allow.includes(normalizedPluginId)) {
     if (parentPluginId && allow.includes(parentPluginId)) {
       return null;
diff --git a/src/cli/run-main.test.ts b/src/cli/run-main.test.ts
@@ -31,6 +31,15 @@ const memoryCoreCommandAliasRegistry: PluginManifestCommandAliasRegistry = {
   ],
 };
 
+const losslessClawToolRegistry: PluginManifestCommandAliasRegistry = {
+  plugins: [
+    {
+      id: "lossless-claw",
+      contracts: { tools: ["lcm_recent", "lcm_search"] },
+    },
+  ],
+};
+
 describe("isGatewayRunFastPathArgv", () => {
   it("matches only plain gateway foreground starts without root options or help", () => {
     expect(isGatewayRunFastPathArgv(["node", "openclaw", "gateway"])).toBe(true);
@@ -367,4 +376,101 @@ describe("resolveMissingPluginCommandMessage", () => {
     expect(message).toContain('"memory-wiki"');
     expect(message).toContain("plugins.allow");
   });
+
+  it("identifies an agent tool name and points the user at model tool-use", () => {
+    const message = resolveMissingPluginCommandMessage(
+      "lcm_recent",
+      {
+        plugins: {
+          allow: ["lossless-claw"],
+        },
+      },
+      { registry: losslessClawToolRegistry },
+    );
+    expect(message).not.toBeNull();
+    expect(message).toContain('"lcm_recent"');
+    expect(message).toContain('"lossless-claw"');
+    expect(message).toContain("agent tool");
+    expect(message).not.toContain("plugins.allow");
+  });
+
+  it("matches agent tool names case-insensitively", () => {
+    const message = resolveMissingPluginCommandMessage("LCM_Recent", undefined, {
+      registry: losslessClawToolRegistry,
+    });
+    expect(message).not.toBeNull();
+    expect(message).toContain("agent tool");
+    expect(message).toContain('"lossless-claw"');
+  });
+
+  it("preserves the plugins.allow suggestion when the unknown name is not a registered tool", () => {
+    const message = resolveMissingPluginCommandMessage(
+      "totally-unknown",
+      {
+        plugins: {
+          allow: ["quietchat"],
+        },
+      },
+      { registry: losslessClawToolRegistry },
+    );
+    expect(message).not.toBeNull();
+    expect(message).toContain('`plugins.allow` excludes "totally-unknown"');
+  });
+
+  it("does not attribute a tool to an owning plugin excluded by plugins.allow", () => {
+    // The owning plugin is denied via plugins.allow, so the manifest-declared
+    // tool is not actually registered at runtime. Fall through to the standard
+    // plugins.allow message instead of falsely asserting "registered by".
+    const message = resolveMissingPluginCommandMessage(
+      "lcm_recent",
+      {
+        plugins: {
+          allow: ["quietchat"],
+        },
+      },
+      { registry: losslessClawToolRegistry },
+    );
+    expect(message).not.toBeNull();
+    expect(message).not.toContain("agent tool registered");
+    expect(message).toContain('`plugins.allow` excludes "lcm_recent"');
+  });
+
+  it("does not attribute a tool to an owning plugin disabled via plugins.entries", () => {
+    const message = resolveMissingPluginCommandMessage(
+      "lcm_recent",
+      {
+        plugins: {
+          entries: {
+            "lossless-claw": { enabled: false },
+          },
+        },
+      },
+      { registry: losslessClawToolRegistry },
+    );
+    // entries.<id>.enabled = false on the OWNING plugin invalidates the
+    // "registered by" claim. With no allow filter on the bare name the
+    // diagnostic returns null (no actionable message); callers handle that
+    // as "not a recognised plugin command".
+    expect(message).toBeNull();
+  });
+
+  it("uses softer 'may be provided by' wording for manifest-only availability", () => {
+    // Some runtime gates (per-account enabled, per-tool toggles in the Feishu
+    // family etc.) cannot be expressed as manifest configSignals, so the
+    // runtime resolver reports availability: "manifest-only" when ownership is
+    // only manifest-provable. The diagnostic must avoid asserting "registered
+    // by" in that case.
+    const manifestOnlyOwner = {
+      toolName: "feishu_chat",
+      pluginId: "feishu",
+      availability: "manifest-only" as const,
+    };
+    const message = resolveMissingPluginCommandMessage("feishu_chat", undefined, {
+      resolveToolOwner: () => manifestOnlyOwner,
+    });
+    expect(message).not.toBeNull();
+    expect(message).toContain("may be provided by");
+    expect(message).toContain('"feishu"');
+    expect(message).not.toContain("registered by");
+  });
 });
diff --git a/src/cli/run-main.ts b/src/cli/run-main.ts
@@ -665,13 +665,14 @@ export async function runCli(argv: string[] = process.argv) {
               (command) => command.name() === primary || command.aliases().includes(primary),
             )
           ) {
-            const { resolveManifestCommandAliasOwner } =
+            const { resolveManifestCommandAliasOwner, resolveManifestToolOwner } =
               await import("../plugins/manifest-command-aliases.runtime.js");
             const missingPluginCommandMessage = resolveMissingPluginCommandMessageFromPolicy(
               primary,
               config,
               {
                 resolveCommandAliasOwner: resolveManifestCommandAliasOwner,
+                resolveToolOwner: resolveManifestToolOwner,
               },
             );
             if (missingPluginCommandMessage) {
diff --git a/src/plugins/manifest-command-aliases.runtime.ts b/src/plugins/manifest-command-aliases.runtime.ts
@@ -1,10 +1,18 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { normalizeOptionalLowercaseString } from "../shared/string-coerce.js";
 import {
   resolveManifestCommandAliasOwnerInRegistry,
+  resolveManifestToolOwnerInRegistry,
   type PluginManifestCommandAliasRegistry,
   type PluginManifestCommandAliasRecord,
+  type PluginManifestToolOwnerRecord,
 } from "./manifest-command-aliases.js";
-import { loadManifestMetadataRegistry } from "./manifest-contract-eligibility.js";
+import {
+  isManifestPluginAvailableForControlPlane,
+  loadManifestMetadataRegistry,
+  loadManifestMetadataSnapshot,
+} from "./manifest-contract-eligibility.js";
+import { hasManifestToolAvailability } from "./manifest-tool-availability.js";
 
 export function resolveManifestCommandAliasOwner(params: {
   command: string | undefined;
@@ -25,3 +33,83 @@ export function resolveManifestCommandAliasOwner(params: {
     registry,
   });
 }
+
+/**
+ * Resolve which plugin owns an agent-tool name, applying control-plane
+ * availability filters so disabled/denied plugins are not falsely attributed.
+ *
+ * Behavior:
+ * - Walks the full manifest snapshot (not the lighter-weight registry view) so
+ *   per-tool `configSignals`/`authSignals` are visible.
+ * - Skips plugins that fail `isManifestPluginAvailableForControlPlane`
+ *   (`plugins.allow` / `plugins.deny` / `plugins.entries[id].enabled` /
+ *   installed-index).
+ * - For matched tools, runs `hasManifestToolAvailability` to check the
+ *   tool's own configSignals (e.g. Feishu's `appId`/`appSecret` gate).
+ * - Reports `availability: "loaded"` when both filters pass — caller can use
+ *   the strong "registered by" wording.
+ * - Reports `availability: "manifest-only"` when the manifest declares
+ *   ownership but availability is not provable from manifest alone (e.g.
+ *   per-account `enabled` flags or per-tool toggles that are runtime-only).
+ *   Caller should soften the wording to "may be provided by".
+ *
+ * Falls back to the pure registry walk only when an explicit registry is
+ * supplied (no snapshot to filter against).
+ */
+export function resolveManifestToolOwner(params: {
+  toolName: string | undefined;
+  config?: OpenClawConfig;
+  workspaceDir?: string;
+  env?: NodeJS.ProcessEnv;
+  registry?: PluginManifestCommandAliasRegistry;
+}): PluginManifestToolOwnerRecord | undefined {
+  if (params.registry) {
+    return resolveManifestToolOwnerInRegistry({
+      toolName: params.toolName,
+      registry: params.registry,
+    });
+  }
+  const normalizedToolName = normalizeOptionalLowercaseString(params.toolName);
+  if (!normalizedToolName) {
+    return undefined;
+  }
+  const snapshot = loadManifestMetadataSnapshot({
+    config: params.config,
+    workspaceDir: params.workspaceDir,
+    env: params.env,
+  });
+  const env = params.env ?? process.env;
+  for (const plugin of snapshot.plugins) {
+    const tools = plugin.contracts?.tools;
+    if (!tools || tools.length === 0) {
+      continue;
+    }
+    const match = tools.find(
+      (entry) => normalizeOptionalLowercaseString(entry) === normalizedToolName,
+    );
+    if (!match) {
+      continue;
+    }
+    const pluginAvailable = isManifestPluginAvailableForControlPlane({
+      snapshot,
+      plugin,
+      config: params.config,
+    });
+    if (!pluginAvailable) {
+      // Plugin is denied/disabled/uninstalled; do not attribute this tool to it.
+      continue;
+    }
+    const toolAvailable = hasManifestToolAvailability({
+      plugin,
+      toolNames: [match],
+      config: params.config,
+      env,
+    });
+    return {
+      toolName: match,
+      pluginId: plugin.id,
+      availability: toolAvailable ? "loaded" : "manifest-only",
+    };
+  }
+  return undefined;
+}
diff --git a/src/plugins/manifest-command-aliases.test.ts b/src/plugins/manifest-command-aliases.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
   normalizeManifestCommandAliases,
   resolveManifestCommandAliasOwnerInRegistry,
+  resolveManifestToolOwnerInRegistry,
 } from "./manifest-command-aliases.js";
 
 describe("manifest command aliases", () => {
@@ -46,4 +47,31 @@ describe("manifest command aliases", () => {
       name: "legacy-memory",
     });
   });
+
+  it("resolves agent tool owners from contracts.tools", () => {
+    const registry = {
+      plugins: [
+        {
+          id: "lossless-claw",
+          contracts: { tools: ["lcm_recent", "lcm_search"] },
+        },
+        {
+          id: "other-plugin",
+          contracts: { tools: ["unrelated_tool"] },
+        },
+      ],
+    };
+
+    expect(resolveManifestToolOwnerInRegistry({ toolName: "lcm_recent", registry })).toMatchObject({
+      pluginId: "lossless-claw",
+      toolName: "lcm_recent",
+    });
+    expect(resolveManifestToolOwnerInRegistry({ toolName: "LCM_Recent", registry })).toMatchObject({
+      pluginId: "lossless-claw",
+    });
+    expect(
+      resolveManifestToolOwnerInRegistry({ toolName: "missing_tool", registry }),
+    ).toBeUndefined();
+    expect(resolveManifestToolOwnerInRegistry({ toolName: "", registry })).toBeUndefined();
+  });
 });
diff --git a/src/plugins/manifest-command-aliases.ts b/src/plugins/manifest-command-aliases.ts
