Fix memory plugin CLI help dispatch (#83841)

joshavant · web-flow · commit eb6dd2c65d11 · 2026-05-18T20:35:55.000-05:00
* fix cli help for active memory plugin

* docs add changelog for memory cli help

* test fix root help mock type
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -137,6 +137,7 @@ Docs: https://docs.openclaw.ai
 - Mac app: render channel quick config as aligned Settings rows and hide schema-only variants that cannot be edited safely from the quick pane.
 - Gateway/webchat: hide internal runtime-context and other `display: false` transcript messages from Chat history and live message events. Fixes #83216. Thanks @EmpireCreator.
 - CLI/help: keep `gateway`, `doctor`, `status`, and `health` help registration out of action/runtime imports so subcommand `--help` stays lightweight in constrained terminals. Fixes #83228. Thanks @dfguerrerom.
+- CLI/help: show plugin-owned command help based on the active memory slot so LanceDB memory users see `ltm` instead of unavailable `memory` commands. Fixes #83745. (#83841) Thanks @joshavant.
 - Cron/Discord: keep explicit announce runs in message-tool-only source-reply mode so scheduled agent turns post once instead of also echoing through automatic visible replies. Fixes #83261. Thanks @Theralley.
 - Telegram: preserve forum-topic origin targets in inbound, audio-preflight, and skipped-message hook contexts so follow-up delivery stays bound to the originating topic. Fixes #83302. Thanks @M00zyx.
 - Telegram: retry HTTP 421 Misdirected Request send failures on a fresh fallback transport so transient edge-node routing errors no longer drop outbound replies. Fixes #48892. (#48908) Thanks @MarsDoge.
diff --git a/docs/cli/memory.md b/docs/cli/memory.md
@@ -10,7 +10,9 @@ title: "Memory"
 # `openclaw memory`
 
 Manage semantic memory indexing and search.
-Provided by the active memory plugin (default: `memory-core`; set `plugins.slots.memory = "none"` to disable).
+Provided by the bundled `memory-core` plugin. The command is available when
+`plugins.slots.memory` selects `memory-core` (the default); other memory plugins
+expose their own CLI namespaces.
 
 Related:
 
diff --git a/docs/plugins/memory-lancedb.md b/docs/plugins/memory-lancedb.md
@@ -238,12 +238,12 @@ openclaw ltm search "project preferences"
 openclaw ltm stats
 ```
 
-The plugin also extends `openclaw memory` with a non-vector `query` subcommand
-that runs against the LanceDB table directly:
+The `query` subcommand runs a non-vector query against the LanceDB table
+directly:
 
 ```bash
-openclaw memory query --cols id,text,createdAt --limit 20
-openclaw memory query --filter "category = 'preference'" --order-by createdAt:desc
+openclaw ltm query --cols id,text,createdAt --limit 20
+openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc
 ```
 
 - `--cols <columns>`: comma-separated column allowlist (defaults to `id`, `text`, `importance`, `category`, `createdAt`).
diff --git a/extensions/memory-lancedb/cli-metadata.ts b/extensions/memory-lancedb/cli-metadata.ts
@@ -5,6 +5,14 @@ export default definePluginEntry({
   name: "Memory LanceDB",
   description: "LanceDB-backed memory provider",
   register(api) {
-    api.registerCli(() => {}, { commands: ["ltm"] });
+    api.registerCli(() => {}, {
+      descriptors: [
+        {
+          name: "ltm",
+          description: "Inspect and query LanceDB-backed memory",
+          hasSubcommands: true,
+        },
+      ],
+    });
   },
 });
diff --git a/openclaw.mjs b/openclaw.mjs
@@ -334,6 +334,72 @@ const isBrowserHelpInvocation = (argv) =>
 const isHelpFastPathDisabled = () =>
   process.env.OPENCLAW_DISABLE_CLI_STARTUP_HELP_FAST_PATH === "1";
 
+const normalizeLauncherHomeValue = (value) => {
+  const trimmed = value?.trim();
+  return trimmed && trimmed !== "undefined" && trimmed !== "null" ? trimmed : undefined;
+};
+
+const resolveLauncherOsHomeDir = () =>
+  normalizeLauncherHomeValue(process.env.HOME) ??
+  normalizeLauncherHomeValue(process.env.USERPROFILE) ??
+  os.homedir();
+
+const resolveLauncherHomeDir = () => {
+  const explicit = normalizeLauncherHomeValue(process.env.OPENCLAW_HOME);
+  const rawHome =
+    explicit && (explicit === "~" || explicit.startsWith("~/") || explicit.startsWith("~\\"))
+      ? explicit.replace(/^~(?=$|[\\/])/, resolveLauncherOsHomeDir())
+      : (explicit ?? resolveLauncherOsHomeDir());
+  return path.resolve(rawHome);
+};
+
+const resolveLauncherUserPath = (input) => {
+  if (input === "~") {
+    return resolveLauncherHomeDir();
+  }
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return path.join(resolveLauncherHomeDir(), input.slice(2));
+  }
+  return path.resolve(input);
+};
+
+const resolveLauncherConfigPaths = () => {
+  const explicit = process.env.OPENCLAW_CONFIG_PATH?.trim();
+  if (explicit) {
+    return [resolveLauncherUserPath(explicit)];
+  }
+  const stateOverride = process.env.OPENCLAW_STATE_DIR?.trim();
+  if (stateOverride) {
+    const stateDir = resolveLauncherUserPath(stateOverride);
+    return [path.join(stateDir, "openclaw.json"), path.join(stateDir, "clawdbot.json")];
+  }
+  const homeDir = resolveLauncherHomeDir();
+  return [
+    path.join(homeDir, ".openclaw", "openclaw.json"),
+    path.join(homeDir, ".openclaw", "clawdbot.json"),
+    path.join(homeDir, ".clawdbot", "openclaw.json"),
+    path.join(homeDir, ".clawdbot", "clawdbot.json"),
+  ];
+};
+
+const shouldDeferRootHelpToRuntimeEntry = () => {
+  if (
+    process.env.OPENCLAW_BUNDLED_PLUGINS_DIR?.trim() ||
+    process.env.OPENCLAW_DISABLE_BUNDLED_PLUGINS?.trim()
+  ) {
+    return true;
+  }
+  for (const configPath of resolveLauncherConfigPaths()) {
+    try {
+      const raw = readFileSync(configPath, "utf8");
+      return /\bplugins\b|\$include\b/.test(raw);
+    } catch {
+      continue;
+    }
+  }
+  return false;
+};
+
 const loadPrecomputedHelpText = (key) => {
   try {
     const raw = readFileSync(new URL("./dist/cli-startup-metadata.json", import.meta.url), "utf8");
@@ -349,6 +415,9 @@ const tryOutputBareRootHelp = async () => {
   if (!isBareRootHelpInvocation(process.argv)) {
     return false;
   }
+  if (shouldDeferRootHelpToRuntimeEntry()) {
+    return false;
+  }
   const precomputed = loadPrecomputedHelpText("rootHelpText");
   if (precomputed) {
     process.stdout.write(precomputed);
@@ -358,7 +427,7 @@ const tryOutputBareRootHelp = async () => {
     try {
       const mod = await import(specifier);
       if (typeof mod.outputRootHelp === "function") {
-        mod.outputRootHelp();
+        await mod.outputRootHelp();
         return true;
       }
     } catch (err) {
diff --git a/src/cli/command-registration-policy.test.ts b/src/cli/command-registration-policy.test.ts
@@ -35,7 +35,7 @@ describe("command-registration-policy", () => {
         primary: "voicecall",
         hasBuiltinPrimary: false,
       }),
-    ).toBe(true);
+    ).toBe(false);
     expect(
       shouldSkipPluginCommandRegistration({
         argv: ["node", "openclaw", "help", "--help"],
diff --git a/src/cli/command-registration-policy.ts b/src/cli/command-registration-policy.ts
@@ -22,7 +22,9 @@ export function shouldSkipPluginCommandRegistration(params: {
     return invocation.hasHelpOrVersion && invocation.commandPath.length <= 1;
   }
   if (invocation.hasHelpOrVersion) {
-    return true;
+    return (
+      !params.primary || params.hasBuiltinPrimary || isReservedNonPluginCommandRoot(params.primary)
+    );
   }
   if (params.hasBuiltinPrimary) {
     return true;
diff --git a/src/cli/root-help-live-config.test.ts b/src/cli/root-help-live-config.test.ts
@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { loadRootHelpRenderOptionsForConfigSensitivePlugins } from "./root-help-live-config.js";
+
+const readConfigFileSnapshotMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../config/config.js", () => ({
+  readConfigFileSnapshot: readConfigFileSnapshotMock,
+}));
+
+describe("root help live config", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses precomputed help when plugin-sensitive config is invalid", async () => {
+    readConfigFileSnapshotMock.mockResolvedValueOnce({
+      valid: false,
+      sourceConfig: {
+        plugins: {
+          slots: {
+            memory: "memory-lancedb",
+          },
+        },
+      },
+      runtimeConfig: {},
+    });
+
+    await expect(loadRootHelpRenderOptionsForConfigSensitivePlugins({})).resolves.toBeNull();
+  });
+
+  it("uses snapshot runtime config when plugin config affects help", async () => {
+    const runtimeConfig = {
+      plugins: {
+        slots: {
+          memory: "memory-lancedb",
+        },
+      },
+    };
+    const env = {};
+    readConfigFileSnapshotMock.mockResolvedValueOnce({
+      valid: true,
+      sourceConfig: runtimeConfig,
+      runtimeConfig,
+    });
+
+    await expect(loadRootHelpRenderOptionsForConfigSensitivePlugins(env)).resolves.toEqual({
+      config: runtimeConfig,
+      env,
+    });
+  });
+});
diff --git a/src/cli/root-help-live-config.ts b/src/cli/root-help-live-config.ts
@@ -0,0 +1,53 @@
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import type { RootHelpRenderOptions } from "./program/root-help.js";
+
+function hasEntries(value: object | undefined): boolean {
+  return !!value && Object.keys(value).length > 0;
+}
+
+function hasListEntries(value: string[] | undefined): boolean {
+  return Array.isArray(value) && value.length > 0;
+}
+
+export function hasPluginHelpAffectingConfig(config: OpenClawConfig | null | undefined): boolean {
+  const plugins = config?.plugins;
+  if (!plugins) {
+    return false;
+  }
+  return (
+    plugins.enabled === false ||
+    hasListEntries(plugins.allow) ||
+    hasListEntries(plugins.deny) ||
+    plugins.bundledDiscovery !== undefined ||
+    hasListEntries(plugins.load?.paths) ||
+    hasEntries(plugins.slots) ||
+    hasEntries(plugins.entries) ||
+    hasEntries(plugins.installs)
+  );
+}
+
+export function hasPluginHelpAffectingEnv(env: NodeJS.ProcessEnv): boolean {
+  return Boolean(
+    env.OPENCLAW_BUNDLED_PLUGINS_DIR?.trim() || env.OPENCLAW_DISABLE_BUNDLED_PLUGINS?.trim(),
+  );
+}
+
+export async function loadRootHelpRenderOptionsForConfigSensitivePlugins(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<RootHelpRenderOptions | null> {
+  const configModule = await import("../config/config.js");
+  const snapshot = await configModule.readConfigFileSnapshot({
+    observe: false,
+    skipPluginValidation: true,
+  });
+  if (!snapshot.valid) {
+    return null;
+  }
+  if (!hasPluginHelpAffectingEnv(env) && !hasPluginHelpAffectingConfig(snapshot.sourceConfig)) {
+    return null;
+  }
+  return {
+    config: snapshot.runtimeConfig,
+    env,
+  };
+}
diff --git a/src/cli/run-main.exit.test.ts b/src/cli/run-main.exit.test.ts
@@ -2,6 +2,7 @@ import process from "node:process";
 import { CommanderError } from "commander";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { loggingState } from "../logging/state.js";
+import type { RootHelpRenderOptions } from "./program/root-help.js";
 import { runCli, shouldStartProxyForCli } from "./run-main.js";
 
 const tryRouteCliMock = vi.hoisted(() => vi.fn());
@@ -18,6 +19,9 @@ const startTaskRegistryMaintenanceMock = vi.hoisted(() => vi.fn());
 const outputRootHelpMock = vi.hoisted(() => vi.fn());
 const outputPrecomputedRootHelpTextMock = vi.hoisted(() => vi.fn(() => false));
 const outputPrecomputedBrowserHelpTextMock = vi.hoisted(() => vi.fn(() => false));
+const loadRootHelpRenderOptionsForConfigSensitivePluginsMock = vi.hoisted(() =>
+  vi.fn<() => Promise<RootHelpRenderOptions | null>>(async () => null),
+);
 const buildProgramMock = vi.hoisted(() => vi.fn());
 const getProgramContextMock = vi.hoisted(() => vi.fn(() => null));
 const registerCoreCliByNameMock = vi.hoisted(() => vi.fn());
@@ -168,6 +172,11 @@ vi.mock("./root-help-metadata.js", () => ({
   outputPrecomputedRootHelpText: outputPrecomputedRootHelpTextMock,
 }));
 
+vi.mock("./root-help-live-config.js", () => ({
+  loadRootHelpRenderOptionsForConfigSensitivePlugins:
+    loadRootHelpRenderOptionsForConfigSensitivePluginsMock,
+}));
+
 vi.mock("./program.js", () => ({
   buildProgram: buildProgramMock,
 }));
@@ -242,6 +251,7 @@ describe("runCli exit behavior", () => {
     listAgentHarnessIdsMock.mockReturnValue([]);
     outputPrecomputedBrowserHelpTextMock.mockReturnValue(false);
     outputPrecomputedRootHelpTextMock.mockReturnValue(false);
+    loadRootHelpRenderOptionsForConfigSensitivePluginsMock.mockResolvedValue(null);
     hasEnvHttpProxyAgentConfiguredMock.mockReturnValue(false);
     loadConfigMock.mockReturnValue({});
     startProxyMock.mockResolvedValue(null);
@@ -401,6 +411,7 @@ describe("runCli exit behavior", () => {
 
     await runCli(["node", "openclaw", "--help"]);
 
+    expect(loadRootHelpRenderOptionsForConfigSensitivePluginsMock).toHaveBeenCalledTimes(1);
     expect(outputPrecomputedRootHelpTextMock).toHaveBeenCalledTimes(1);
     expect(hasEnvHttpProxyAgentConfiguredMock).not.toHaveBeenCalled();
     expect(ensureGlobalUndiciEnvProxyDispatcherMock).not.toHaveBeenCalled();
@@ -416,6 +427,7 @@ describe("runCli exit behavior", () => {
 
     expect(maybeRunCliInContainerMock).toHaveBeenCalledWith(["node", "openclaw", "--help"]);
     expect(tryRouteCliMock).not.toHaveBeenCalled();
+    expect(loadRootHelpRenderOptionsForConfigSensitivePluginsMock).toHaveBeenCalledTimes(1);
     expect(outputPrecomputedRootHelpTextMock).toHaveBeenCalledTimes(1);
     expect(outputRootHelpMock).toHaveBeenCalledTimes(1);
     expect(buildProgramMock).not.toHaveBeenCalled();
@@ -424,6 +436,28 @@ describe("runCli exit behavior", () => {
     exitSpy.mockRestore();
   });
 
+  it("renders config-sensitive root help live instead of precomputed metadata", async () => {
+    const liveOptions: RootHelpRenderOptions = {
+      config: {
+        plugins: {
+          slots: {
+            memory: "memory-lancedb",
+          },
+        },
+      },
+      env: process.env,
+    };
+    loadRootHelpRenderOptionsForConfigSensitivePluginsMock.mockResolvedValueOnce(liveOptions);
+    outputPrecomputedRootHelpTextMock.mockReturnValueOnce(true);
+
+    await runCli(["node", "openclaw", "--help"]);
+
+    expect(loadRootHelpRenderOptionsForConfigSensitivePluginsMock).toHaveBeenCalledTimes(1);
+    expect(outputPrecomputedRootHelpTextMock).not.toHaveBeenCalled();
+    expect(outputRootHelpMock).toHaveBeenCalledWith(liveOptions);
+    expect(buildProgramMock).not.toHaveBeenCalled();
+  });
+
   it("does not start the managed proxy for local gateway client commands", async () => {
     tryRouteCliMock.mockResolvedValueOnce(true);
 
diff --git a/src/cli/run-main.ts b/src/cli/run-main.ts
@@ -534,11 +534,19 @@ export async function runCli(argv: string[] = process.argv) {
 
   try {
     if (shouldUseRootHelpFastPath(normalizedArgv)) {
-      const { outputPrecomputedRootHelpText } = await import("./root-help-metadata.js");
-      if (!outputPrecomputedRootHelpText()) {
-        const { outputRootHelp } = await import("./program/root-help.js");
-        await outputRootHelp();
+      const { loadRootHelpRenderOptionsForConfigSensitivePlugins } =
+        await import("./root-help-live-config.js");
+      const liveRootHelpOptions = await loadRootHelpRenderOptionsForConfigSensitivePlugins(
+        process.env,
+      );
+      if (!liveRootHelpOptions) {
+        const { outputPrecomputedRootHelpText } = await import("./root-help-metadata.js");
+        if (outputPrecomputedRootHelpText()) {
+          return;
+        }
       }
+      const { outputRootHelp } = await import("./program/root-help.js");
+      await outputRootHelp(liveRootHelpOptions ?? undefined);
       return;
     }
 
diff --git a/src/entry.test.ts b/src/entry.test.ts
diff --git a/src/entry.ts b/src/entry.ts
diff --git a/test/openclaw-launcher.e2e.test.ts b/test/openclaw-launcher.e2e.test.ts

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,9 @@ export function shouldSkipPluginCommandRegistration(params: {`
`22`	`22`	`return invocation.hasHelpOrVersion && invocation.commandPath.length <= 1;`
`23`	`23`	`}`
`24`	`24`	`if (invocation.hasHelpOrVersion) {`
`25`		`- return true;`
	`25`	`+ return (`
	`26`	`+ !params.primary \|\| params.hasBuiltinPrimary \|\| isReservedNonPluginCommandRoot(params.primary)`
	`27`	`+ );`
`26`	`28`	`}`
`27`	`29`	`if (params.hasBuiltinPrimary) {`
`28`	`30`	`return true;`