refactor: share plugin cli registration helpers

src/cli/completion-cli.ts

@@ -13,11 +13,7 @@ import {
 } from "./completion-fish.js";
 import { getCoreCliCommandNames, registerCoreCliByName } from "./program/command-registry.js";
 import { getProgramContext } from "./program/program-context.js";
-import {
-  getSubCliEntries,
-  loadValidatedConfigForPluginRegistration,
-  registerSubCliByName,
-} from "./program/register.subclis.js";
+import { getSubCliEntries, registerSubCliByName } from "./program/register.subclis.js";
 
 const COMPLETION_SHELLS = ["zsh", "bash", "powershell", "fish"] as const;
 type CompletionShell = (typeof COMPLETION_SHELLS)[number];
@@ -277,11 +273,10 @@ export function registerCompletionCli(program: Command) {
         await registerSubCliByName(program, entry.name);
       }
 
-      const config = await loadValidatedConfigForPluginRegistration();
-      if (config) {
-        const { registerPluginCliCommands } = await import("../plugins/cli.js");
-        await registerPluginCliCommands(program, config, undefined, undefined, { mode: "eager" });
-      }
+      const { registerPluginCliCommandsFromValidatedConfig } = await import("../plugins/cli.js");
+      await registerPluginCliCommandsFromValidatedConfig(program, undefined, undefined, {
+        mode: "eager",
+      });
 
       if (options.writeState) {
         const writeShells = options.shell ? [shell] : [...COMPLETION_SHELLS];

src/cli/program/register.subclis.test.ts

@@ -1,10 +1,6 @@
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  loadValidatedConfigForPluginRegistration,
-  registerSubCliByName,
-  registerSubCliCommands,
-} from "./register.subclis.js";
+import { registerSubCliByName, registerSubCliCommands } from "./register.subclis.js";
 
 const { acpAction, registerAcpCli } = vi.hoisted(() => {
   const action = vi.fn();
@@ -30,15 +26,9 @@ const { registerQaCli } = vi.hoisted(() => ({
   }),
 }));
 
-const configModule = vi.hoisted(() => ({
-  loadConfig: vi.fn(),
-  readConfigFileSnapshot: vi.fn(),
-}));
-
 vi.mock("../acp-cli.js", () => ({ registerAcpCli }));
 vi.mock("../nodes-cli.js", () => ({ registerNodesCli }));
 vi.mock("../qa-cli.js", () => ({ registerQaCli }));
-vi.mock("../../config/config.js", () => configModule);
 
 describe("registerSubCliCommands", () => {
   const originalArgv = process.argv;
@@ -64,8 +54,6 @@ describe("registerSubCliCommands", () => {
     acpAction.mockClear();
     registerNodesCli.mockClear();
     nodesAction.mockClear();
-    configModule.loadConfig.mockReset();
-    configModule.readConfigFileSnapshot.mockReset();
   });
 
   afterEach(() => {
@@ -99,28 +87,6 @@ describe("registerSubCliCommands", () => {
     expect(registerAcpCli).not.toHaveBeenCalled();
   });
 
-  it("returns null for plugin registration when the config snapshot is invalid", async () => {
-    configModule.readConfigFileSnapshot.mockResolvedValueOnce({
-      valid: false,
-      config: { plugins: { load: { paths: ["/tmp/evil"] } } },
-    });
-
-    await expect(loadValidatedConfigForPluginRegistration()).resolves.toBeNull();
-    expect(configModule.loadConfig).not.toHaveBeenCalled();
-  });
-
-  it("loads validated config for plugin registration when the snapshot is valid", async () => {
-    const loadedConfig = { plugins: { enabled: true } };
-    configModule.readConfigFileSnapshot.mockResolvedValueOnce({
-      valid: true,
-      config: loadedConfig,
-    });
-    configModule.loadConfig.mockReturnValueOnce(loadedConfig);
-
-    await expect(loadValidatedConfigForPluginRegistration()).resolves.toBe(loadedConfig);
-    expect(configModule.loadConfig).toHaveBeenCalledTimes(1);
-  });
-
   it("re-parses argv for lazy subcommands", async () => {
     const program = createRegisteredProgram(["node", "openclaw", "nodes", "list"], "openclaw");
 

src/cli/program/register.subclis.ts

@@ -1,10 +1,14 @@
 import type { Command } from "commander";
-import type { OpenClawConfig } from "../../config/config.js";
 import { resolveCliArgvInvocation } from "../argv-invocation.js";
 import {
   shouldEagerRegisterSubcommands,
   shouldRegisterPrimarySubcommandOnly,
 } from "../command-registration-policy.js";
+import {
+  buildCommandGroupEntries,
+  defineImportedProgramCommandGroupSpecs,
+  type CommandGroupDescriptorSpec,
+} from "./command-group-descriptors.js";
 import {
   registerCommandGroupByName,
   registerCommandGroups,
@@ -20,305 +24,197 @@ export { getSubCliCommandsWithSubcommands };
 
 type SubCliRegistrar = (program: Command) => Promise<void> | void;
 
-type SubCliEntry = SubCliDescriptor & {
-  register: SubCliRegistrar;
-};
-
-export const loadValidatedConfigForPluginRegistration =
-  async (): Promise<OpenClawConfig | null> => {
-    const mod = await import("../../config/config.js");
-    const snapshot = await mod.readConfigFileSnapshot();
-    if (!snapshot.valid) {
-      return null;
-    }
-    return mod.loadConfig();
-  };
+async function registerSubCliWithPluginCommands(
+  program: Command,
+  registerSubCli: () => Promise<void>,
+  pluginCliPosition: "before" | "after",
+) {
+  const { registerPluginCliCommandsFromValidatedConfig } = await import("../../plugins/cli.js");
+  if (pluginCliPosition === "before") {
+    await registerPluginCliCommandsFromValidatedConfig(program);
+  }
+  await registerSubCli();
+  if (pluginCliPosition === "after") {
+    await registerPluginCliCommandsFromValidatedConfig(program);
+  }
+}
 
 // Note for humans and agents:
 // If you update the list of commands, also check whether they have subcommands
 // and set the flag accordingly.
-const entries: SubCliEntry[] = [
-  {
-    name: "acp",
-    description: "Agent Control Protocol tools",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../acp-cli.js");
-      mod.registerAcpCli(program);
+const entrySpecs: readonly CommandGroupDescriptorSpec<SubCliRegistrar>[] = [
+  ...defineImportedProgramCommandGroupSpecs([
+    {
+      commandNames: ["acp"],
+      loadModule: () => import("../acp-cli.js"),
+      exportName: "registerAcpCli",
     },
-  },
-  {
-    name: "gateway",
-    description: "Run, inspect, and query the WebSocket Gateway",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../gateway-cli.js");
-      mod.registerGatewayCli(program);
+    {
+      commandNames: ["gateway"],
+      loadModule: () => import("../gateway-cli.js"),
+      exportName: "registerGatewayCli",
     },
-  },
-  {
-    name: "daemon",
-    description: "Gateway service (legacy alias)",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../daemon-cli.js");
-      mod.registerDaemonCli(program);
+    {
+      commandNames: ["daemon"],
+      loadModule: () => import("../daemon-cli.js"),
+      exportName: "registerDaemonCli",
     },
-  },
-  {
-    name: "logs",
-    description: "Tail gateway file logs via RPC",
-    hasSubcommands: false,
-    register: async (program) => {
-      const mod = await import("../logs-cli.js");
-      mod.registerLogsCli(program);
+    {
+      commandNames: ["logs"],
+      loadModule: () => import("../logs-cli.js"),
+      exportName: "registerLogsCli",
     },
-  },
-  {
-    name: "system",
-    description: "System events, heartbeat, and presence",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../system-cli.js");
-      mod.registerSystemCli(program);
+    {
+      commandNames: ["system"],
+      loadModule: () => import("../system-cli.js"),
+      exportName: "registerSystemCli",
     },
-  },
-  {
-    name: "models",
-    description: "Discover, scan, and configure models",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../models-cli.js");
-      mod.registerModelsCli(program);
+    {
+      commandNames: ["models"],
+      loadModule: () => import("../models-cli.js"),
+      exportName: "registerModelsCli",
     },
-  },
-  {
-    name: "approvals",
-    description: "Manage exec approvals (gateway or node host)",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../exec-approvals-cli.js");
-      mod.registerExecApprovalsCli(program);
+    {
+      commandNames: ["approvals"],
+      loadModule: () => import("../exec-approvals-cli.js"),
+      exportName: "registerExecApprovalsCli",
     },
-  },
-  {
-    name: "nodes",
-    description: "Manage gateway-owned node pairing and node commands",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../nodes-cli.js");
-      mod.registerNodesCli(program);
+    {
+      commandNames: ["nodes"],
+      loadModule: () => import("../nodes-cli.js"),
+      exportName: "registerNodesCli",
     },
-  },
-  {
-    name: "devices",
-    description: "Device pairing + token management",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../devices-cli.js");
-      mod.registerDevicesCli(program);
+    {
+      commandNames: ["devices"],
+      loadModule: () => import("../devices-cli.js"),
+      exportName: "registerDevicesCli",
     },
-  },
-  {
-    name: "node",
-    description: "Run and manage the headless node host service",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../node-cli.js");
-      mod.registerNodeCli(program);
+    {
+      commandNames: ["node"],
+      loadModule: () => import("../node-cli.js"),
+      exportName: "registerNodeCli",
     },
-  },
-  {
-    name: "sandbox",
-    description: "Manage sandbox containers for agent isolation",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../sandbox-cli.js");
-      mod.registerSandboxCli(program);
+    {
+      commandNames: ["sandbox"],
+      loadModule: () => import("../sandbox-cli.js"),
+      exportName: "registerSandboxCli",
     },
-  },
-  {
-    name: "tui",
-    description: "Open a terminal UI connected to the Gateway",
-    hasSubcommands: false,
-    register: async (program) => {
-      const mod = await import("../tui-cli.js");
-      mod.registerTuiCli(program);
+    {
+      commandNames: ["tui"],
+      loadModule: () => import("../tui-cli.js"),
+      exportName: "registerTuiCli",
     },
-  },
-  {
-    name: "cron",
-    description: "Manage cron jobs via the Gateway scheduler",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../cron-cli.js");
-      mod.registerCronCli(program);
+    {
+      commandNames: ["cron"],
+      loadModule: () => import("../cron-cli.js"),
+      exportName: "registerCronCli",
     },
-  },
-  {
-    name: "dns",
-    description: "DNS helpers for wide-area discovery (Tailscale + CoreDNS)",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../dns-cli.js");
-      mod.registerDnsCli(program);
+    {
+      commandNames: ["dns"],
+      loadModule: () => import("../dns-cli.js"),
+      exportName: "registerDnsCli",
     },
-  },
-  {
-    name: "docs",
-    description: "Search the live OpenClaw docs",
-    hasSubcommands: false,
-    register: async (program) => {
-      const mod = await import("../docs-cli.js");
-      mod.registerDocsCli(program);
+    {
+      commandNames: ["docs"],
+      loadModule: () => import("../docs-cli.js"),
+      exportName: "registerDocsCli",
     },
-  },
-  {
-    name: "qa",
-    description: "Run QA scenarios and launch the private QA debugger UI",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../qa-cli.js");
-      mod.registerQaCli(program);
+    {
+      commandNames: ["qa"],
+      loadModule: () => import("../qa-cli.js"),
+      exportName: "registerQaCli",
     },
-  },
-  {
-    name: "hooks",
-    description: "Manage internal agent hooks",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../hooks-cli.js");
-      mod.registerHooksCli(program);
+    {
+      commandNames: ["hooks"],
+      loadModule: () => import("../hooks-cli.js"),
+      exportName: "registerHooksCli",
     },
-  },
-  {
-    name: "webhooks",
-    description: "Webhook helpers and integrations",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../webhooks-cli.js");
-      mod.registerWebhooksCli(program);
+    {
+      commandNames: ["webhooks"],
+      loadModule: () => import("../webhooks-cli.js"),
+      exportName: "registerWebhooksCli",
     },
-  },
-  {
-    name: "qr",
-    description: "Generate mobile pairing QR/setup code",
-    hasSubcommands: false,
-    register: async (program) => {
-      const mod = await import("../qr-cli.js");
-      mod.registerQrCli(program);
+    {
+      commandNames: ["qr"],
+      loadModule: () => import("../qr-cli.js"),
+      exportName: "registerQrCli",
     },
-  },
-  {
-    name: "clawbot",
-    description: "Legacy clawbot command aliases",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../clawbot-cli.js");
-      mod.registerClawbotCli(program);
+    {
+      commandNames: ["clawbot"],
+      loadModule: () => import("../clawbot-cli.js"),
+      exportName: "registerClawbotCli",
     },
-  },
+  ]),
   {
-    name: "pairing",
-    description: "Secure DM pairing (approve inbound requests)",
-    hasSubcommands: true,
+    commandNames: ["pairing"],
     register: async (program) => {
       // Initialize plugins before registering pairing CLI.
       // The pairing CLI calls listPairingChannels() at registration time,
       // which requires the plugin registry to be populated with channel plugins.
-      const { registerPluginCliCommands } = await import("../../plugins/cli.js");
-      const config = await loadValidatedConfigForPluginRegistration();
-      if (config) {
-        await registerPluginCliCommands(program, config);
-      }
-      const mod = await import("../pairing-cli.js");
-      mod.registerPairingCli(program);
+      await registerSubCliWithPluginCommands(
+        program,
+        async () => {
+          const mod = await import("../pairing-cli.js");
+          mod.registerPairingCli(program);
+        },
+        "before",
+      );
     },
   },
   {
-    name: "plugins",
-    description: "Manage OpenClaw plugins and extensions",
-    hasSubcommands: true,
+    commandNames: ["plugins"],
     register: async (program) => {
-      const mod = await import("../plugins-cli.js");
-      mod.registerPluginsCli(program);
-      const { registerPluginCliCommands } = await import("../../plugins/cli.js");
-      const config = await loadValidatedConfigForPluginRegistration();
-      if (config) {
-        await registerPluginCliCommands(program, config);
-      }
+      await registerSubCliWithPluginCommands(
+        program,
+        async () => {
+          const mod = await import("../plugins-cli.js");
+          mod.registerPluginsCli(program);
+        },
+        "after",
+      );
     },
   },
-  {
-    name: "channels",
-    description: "Manage connected chat channels (Telegram, Discord, etc.)",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../channels-cli.js");
-      mod.registerChannelsCli(program);
+  ...defineImportedProgramCommandGroupSpecs([
+    {
+      commandNames: ["channels"],
+      loadModule: () => import("../channels-cli.js"),
+      exportName: "registerChannelsCli",
     },
-  },
-  {
-    name: "directory",
-    description: "Lookup contact and group IDs (self, peers, groups) for supported chat channels",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../directory-cli.js");
-      mod.registerDirectoryCli(program);
+    {
+      commandNames: ["directory"],
+      loadModule: () => import("../directory-cli.js"),
+      exportName: "registerDirectoryCli",
     },
-  },
-  {
-    name: "security",
-    description: "Security tools and local config audits",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../security-cli.js");
-      mod.registerSecurityCli(program);
+    {
+      commandNames: ["security"],
+      loadModule: () => import("../security-cli.js"),
+      exportName: "registerSecurityCli",
     },
-  },
-  {
-    name: "secrets",
-    description: "Secrets runtime reload controls",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../secrets-cli.js");
-      mod.registerSecretsCli(program);
+    {
+      commandNames: ["secrets"],
+      loadModule: () => import("../secrets-cli.js"),
+      exportName: "registerSecretsCli",
     },
-  },
-  {
-    name: "skills",
-    description: "List and inspect available skills",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../skills-cli.js");
-      mod.registerSkillsCli(program);
+    {
+      commandNames: ["skills"],
+      loadModule: () => import("../skills-cli.js"),
+      exportName: "registerSkillsCli",
     },
-  },
-  {
-    name: "update",
-    description: "Update OpenClaw and inspect update channel status",
-    hasSubcommands: true,
-    register: async (program) => {
-      const mod = await import("../update-cli.js");
-      mod.registerUpdateCli(program);
+    {
+      commandNames: ["update"],
+      loadModule: () => import("../update-cli.js"),
+      exportName: "registerUpdateCli",
     },
-  },
-  {
-    name: "completion",
-    description: "Generate shell completion script",
-    hasSubcommands: false,
-    register: async (program) => {
-      const mod = await import("../completion-cli.js");
-      mod.registerCompletionCli(program);
+    {
+      commandNames: ["completion"],
+      loadModule: () => import("../completion-cli.js"),
+      exportName: "registerCompletionCli",
     },
-  },
+  ]),
 ];
 
 function resolveSubCliCommandGroups(): CommandGroupEntry[] {
-  return entries.map((entry) => ({
-    placeholders: [entry],
-    register: entry.register,
-  }));
+  return buildCommandGroupEntries(getSubCliEntryDescriptors(), entrySpecs, (register) => register);
 }
 
 export function getSubCliEntries(): ReadonlyArray<SubCliDescriptor> {

src/cli/run-main.ts

@@ -191,15 +191,17 @@ export async function runCli(argv: string[] = process.argv) {
     });
     if (!shouldSkipPluginRegistration) {
       // Register plugin CLI commands before parsing
-      const { registerPluginCliCommands } = await import("../plugins/cli.js");
-      const { loadValidatedConfigForPluginRegistration } =
-        await import("./program/register.subclis.js");
-      const config = await loadValidatedConfigForPluginRegistration();
-      if (config) {
-        await registerPluginCliCommands(program, config, undefined, undefined, {
+      const { registerPluginCliCommandsFromValidatedConfig } = await import("../plugins/cli.js");
+      const config = await registerPluginCliCommandsFromValidatedConfig(
+        program,
+        undefined,
+        undefined,
+        {
           mode: "lazy",
           primary,
-        });
+        },
+      );
+      if (config) {
         if (primary && !program.commands.some((command) => command.name() === primary)) {
           const missingPluginCommandMessage = resolveMissingPluginCommandMessage(primary, config);
           if (missingPluginCommandMessage) {

src/plugins/cli-registry-loader.ts

@@ -0,0 +1,254 @@
+import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
+import { collectUniqueCommandDescriptors } from "../cli/program/command-descriptor-utils.js";
+import type { OpenClawConfig } from "../config/config.js";
+import { loadConfig } from "../config/config.js";
+import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import type { PluginLoadOptions } from "./loader.js";
+import { loadOpenClawPluginCliRegistry, loadOpenClawPlugins } from "./loader.js";
+import type { PluginRegistry } from "./registry.js";
+import type {
+  OpenClawPluginCliCommandDescriptor,
+  OpenClawPluginCliContext,
+  PluginLogger,
+} from "./types.js";
+
+const log = createSubsystemLogger("plugins");
+
+export type PluginCliLoaderOptions = Pick<PluginLoadOptions, "pluginSdkResolution">;
+
+export type PluginCliPublicLoadParams = {
+  cfg?: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+  loaderOptions?: PluginCliLoaderOptions;
+  logger?: PluginLogger;
+};
+
+export type PluginCliLoadContext = {
+  rawConfig: OpenClawConfig;
+  config: OpenClawConfig;
+  autoEnabledReasons: Readonly<Record<string, string[]>>;
+  workspaceDir: string | undefined;
+  logger: PluginLogger;
+};
+
+export type PluginCliRegistryLoadResult = PluginCliLoadContext & {
+  registry: PluginRegistry;
+};
+
+export type PluginCliCommandGroupEntry = {
+  pluginId: string;
+  placeholders: readonly OpenClawPluginCliCommandDescriptor[];
+  names: readonly string[];
+  register: (program: OpenClawPluginCliContext["program"]) => Promise<void>;
+};
+
+export function createPluginCliLogger(): PluginLogger {
+  return {
+    info: (message: string) => log.info(message),
+    warn: (message: string) => log.warn(message),
+    error: (message: string) => log.error(message),
+    debug: (message: string) => log.debug(message),
+  };
+}
+
+function resolvePluginCliLogger(logger?: PluginLogger): PluginLogger {
+  return logger ?? createPluginCliLogger();
+}
+
+function hasIgnoredAsyncPluginRegistration(registry: PluginRegistry): boolean {
+  return (registry.diagnostics ?? []).some(
+    (entry) =>
+      entry.message === "plugin register returned a promise; async registration is ignored",
+  );
+}
+
+function mergeCliRegistrars(params: {
+  runtimeRegistry: PluginRegistry;
+  metadataRegistry: PluginRegistry;
+}): PluginRegistry["cliRegistrars"] {
+  const runtimeCommands = new Set(
+    params.runtimeRegistry.cliRegistrars.flatMap((entry) => entry.commands),
+  );
+  return [
+    ...params.runtimeRegistry.cliRegistrars,
+    ...params.metadataRegistry.cliRegistrars.filter(
+      (entry) => !entry.commands.some((command) => runtimeCommands.has(command)),
+    ),
+  ];
+}
+
+function buildPluginCliLoaderParams(
+  context: PluginCliLoadContext,
+  env?: NodeJS.ProcessEnv,
+  loaderOptions?: PluginCliLoaderOptions,
+) {
+  return {
+    config: context.config,
+    activationSourceConfig: context.rawConfig,
+    autoEnabledReasons: context.autoEnabledReasons,
+    workspaceDir: context.workspaceDir,
+    env,
+    logger: context.logger,
+    ...loaderOptions,
+  };
+}
+
+export function resolvePluginCliLoadContext(params: {
+  cfg?: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+  logger: PluginLogger;
+}): PluginCliLoadContext {
+  const rawConfig = params.cfg ?? loadConfig();
+  const autoEnabled = applyPluginAutoEnable({ config: rawConfig, env: params.env ?? process.env });
+  const config = autoEnabled.config;
+  const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+  return {
+    rawConfig,
+    config,
+    autoEnabledReasons: autoEnabled.autoEnabledReasons,
+    workspaceDir,
+    logger: params.logger,
+  };
+}
+
+export async function loadPluginCliMetadataRegistryWithContext(
+  context: PluginCliLoadContext,
+  env?: NodeJS.ProcessEnv,
+  loaderOptions?: PluginCliLoaderOptions,
+): Promise<PluginCliRegistryLoadResult> {
+  return {
+    ...context,
+    registry: await loadOpenClawPluginCliRegistry(
+      buildPluginCliLoaderParams(context, env, loaderOptions),
+    ),
+  };
+}
+
+export async function loadPluginCliCommandRegistryWithContext(params: {
+  context: PluginCliLoadContext;
+  env?: NodeJS.ProcessEnv;
+  loaderOptions?: PluginCliLoaderOptions;
+  onMetadataFallbackError: (error: unknown) => void;
+}): Promise<PluginCliRegistryLoadResult> {
+  const runtimeRegistry = loadOpenClawPlugins(
+    buildPluginCliLoaderParams(params.context, params.env, params.loaderOptions),
+  );
+
+  if (!hasIgnoredAsyncPluginRegistration(runtimeRegistry)) {
+    return {
+      ...params.context,
+      registry: runtimeRegistry,
+    };
+  }
+
+  try {
+    const metadataRegistry = await loadOpenClawPluginCliRegistry(
+      buildPluginCliLoaderParams(params.context, params.env, params.loaderOptions),
+    );
+    return {
+      ...params.context,
+      registry: {
+        ...runtimeRegistry,
+        cliRegistrars: mergeCliRegistrars({
+          runtimeRegistry,
+          metadataRegistry,
+        }),
+      },
+    };
+  } catch (error) {
+    params.onMetadataFallbackError(error);
+    return {
+      ...params.context,
+      registry: runtimeRegistry,
+    };
+  }
+}
+
+function buildPluginCliCommandGroupEntries(params: {
+  registry: PluginRegistry;
+  config: OpenClawConfig;
+  workspaceDir: string | undefined;
+  logger: PluginLogger;
+}): PluginCliCommandGroupEntry[] {
+  return params.registry.cliRegistrars.map((entry) => ({
+    pluginId: entry.pluginId,
+    placeholders: entry.descriptors,
+    names: entry.commands,
+    register: async (program) => {
+      await entry.register({
+        program,
+        config: params.config,
+        workspaceDir: params.workspaceDir,
+        logger: params.logger,
+      });
+    },
+  }));
+}
+
+function logPluginCliMetadataFallbackError(logger: PluginLogger, error: unknown) {
+  logger.warn(`plugin CLI metadata fallback failed: ${String(error)}`);
+}
+
+export async function loadPluginCliDescriptors(
+  params: PluginCliPublicLoadParams,
+): Promise<OpenClawPluginCliCommandDescriptor[]> {
+  try {
+    const logger = resolvePluginCliLogger(params.logger);
+    const context = resolvePluginCliLoadContext({
+      cfg: params.cfg,
+      env: params.env,
+      logger,
+    });
+    const { registry } = await loadPluginCliMetadataRegistryWithContext(
+      context,
+      params.env,
+      params.loaderOptions,
+    );
+    return collectUniqueCommandDescriptors(
+      registry.cliRegistrars.map((entry) => entry.descriptors),
+    );
+  } catch {
+    return [];
+  }
+}
+
+export async function loadPluginCliRegistrationEntries(params: {
+  cfg?: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+  loaderOptions?: PluginCliLoaderOptions;
+  logger?: PluginLogger;
+  onMetadataFallbackError: (error: unknown) => void;
+}): Promise<PluginCliCommandGroupEntry[]> {
+  const resolvedLogger = resolvePluginCliLogger(params.logger);
+  const context = resolvePluginCliLoadContext({
+    cfg: params.cfg,
+    env: params.env,
+    logger: resolvedLogger,
+  });
+  const { config, workspaceDir, logger, registry } = await loadPluginCliCommandRegistryWithContext({
+    context,
+    env: params.env,
+    loaderOptions: params.loaderOptions,
+    onMetadataFallbackError: params.onMetadataFallbackError,
+  });
+  return buildPluginCliCommandGroupEntries({
+    registry,
+    config,
+    workspaceDir,
+    logger,
+  });
+}
+
+export async function loadPluginCliRegistrationEntriesWithDefaults(
+  params: PluginCliPublicLoadParams,
+): Promise<PluginCliCommandGroupEntry[]> {
+  const logger = resolvePluginCliLogger(params.logger);
+  return loadPluginCliRegistrationEntries({
+    ...params,
+    logger,
+    onMetadataFallbackError: (error) => {
+      logPluginCliMetadataFallbackError(logger, error);
+    },
+  });
+}

src/plugins/cli.test.ts

@@ -9,6 +9,8 @@ const mocks = vi.hoisted(() => ({
   loadOpenClawPluginCliRegistry: vi.fn(),
   loadOpenClawPlugins: vi.fn(),
   applyPluginAutoEnable: vi.fn(),
+  loadConfig: vi.fn(),
+  readConfigFileSnapshot: vi.fn(),
 }));
 
 vi.mock("./loader.js", () => ({
@@ -21,7 +23,17 @@ vi.mock("../config/plugin-auto-enable.js", () => ({
   applyPluginAutoEnable: (...args: unknown[]) => mocks.applyPluginAutoEnable(...args),
 }));
 
-import { getPluginCliCommandDescriptors, registerPluginCliCommands } from "./cli.js";
+vi.mock("../config/config.js", () => ({
+  loadConfig: (...args: unknown[]) => mocks.loadConfig(...args),
+  readConfigFileSnapshot: (...args: unknown[]) => mocks.readConfigFileSnapshot(...args),
+}));
+
+import {
+  getPluginCliCommandDescriptors,
+  loadValidatedConfigForPluginRegistration,
+  registerPluginCliCommands,
+  registerPluginCliCommandsFromValidatedConfig,
+} from "./cli.js";
 
 function createProgram(existingCommandName?: string) {
   const program = new Command();
@@ -131,6 +143,13 @@ describe("registerPluginCliCommands", () => {
       changes: [],
       autoEnabledReasons: {},
     }));
+    mocks.loadConfig.mockReset();
+    mocks.loadConfig.mockReturnValue({} as OpenClawConfig);
+    mocks.readConfigFileSnapshot.mockReset();
+    mocks.readConfigFileSnapshot.mockResolvedValue({
+      valid: true,
+      config: {},
+    });
   });
 
   it("skips plugin CLI registrars when commands already exist", async () => {
@@ -380,4 +399,36 @@ describe("registerPluginCliCommands", () => {
     expect(mocks.memoryRegister).toHaveBeenCalledTimes(1);
     expect(mocks.memoryListAction).toHaveBeenCalledTimes(1);
   });
+
+  it("returns null for validated plugin CLI config when the snapshot is invalid", async () => {
+    mocks.readConfigFileSnapshot.mockResolvedValueOnce({
+      valid: false,
+      config: { plugins: { load: { paths: ["/tmp/evil"] } } },
+    });
+
+    await expect(loadValidatedConfigForPluginRegistration()).resolves.toBeNull();
+    expect(mocks.loadConfig).not.toHaveBeenCalled();
+  });
+
+  it("loads validated plugin CLI config when the snapshot is valid", async () => {
+    const loadedConfig = { plugins: { enabled: true } } as OpenClawConfig;
+    mocks.readConfigFileSnapshot.mockResolvedValueOnce({
+      valid: true,
+      config: loadedConfig,
+    });
+    mocks.loadConfig.mockReturnValueOnce(loadedConfig);
+
+    await expect(loadValidatedConfigForPluginRegistration()).resolves.toBe(loadedConfig);
+    expect(mocks.loadConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips plugin CLI registration from validated config when the snapshot is invalid", async () => {
+    mocks.readConfigFileSnapshot.mockResolvedValueOnce({
+      valid: false,
+      config: {},
+    });
+
+    await expect(registerPluginCliCommandsFromValidatedConfig(createProgram())).resolves.toBeNull();
+    expect(mocks.loadOpenClawPlugins).not.toHaveBeenCalled();
+  });
 });

src/plugins/cli.ts

@@ -1,21 +1,13 @@
 import type { Command } from "commander";
-import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
-import { removeCommandByName } from "../cli/program/command-tree.js";
-import { registerLazyCommand } from "../cli/program/register-lazy-command.js";
-import type { OpenClawConfig } from "../config/config.js";
-import { loadConfig } from "../config/config.js";
-import { applyPluginAutoEnable } from "../config/plugin-auto-enable.js";
-import { createSubsystemLogger } from "../logging/subsystem.js";
+import { loadConfig, readConfigFileSnapshot, type OpenClawConfig } from "../config/config.js";
 import {
-  loadOpenClawPluginCliRegistry,
-  loadOpenClawPlugins,
-  type PluginLoadOptions,
-} from "./loader.js";
-import type { PluginRegistry } from "./registry.js";
+  createPluginCliLogger,
+  loadPluginCliDescriptors,
+  loadPluginCliRegistrationEntriesWithDefaults,
+  type PluginCliLoaderOptions,
+} from "./cli-registry-loader.js";
+import { registerPluginCliCommandGroups } from "./register-plugin-cli-command-groups.js";
 import type { OpenClawPluginCliCommandDescriptor } from "./types.js";
-import type { PluginLogger } from "./types.js";
-
-const log = createSubsystemLogger("plugins");
 
 type PluginCliRegistrationMode = "eager" | "lazy";
 
@@ -24,234 +16,57 @@ type RegisterPluginCliOptions = {
   primary?: string | null;
 };
 
-function canRegisterPluginCliLazily(entry: {
-  commands: string[];
-  descriptors: OpenClawPluginCliCommandDescriptor[];
-}): boolean {
-  if (entry.descriptors.length === 0) {
-    return false;
-  }
-  const descriptorNames = new Set(entry.descriptors.map((descriptor) => descriptor.name));
-  return entry.commands.every((command) => descriptorNames.has(command));
-}
+const logger = createPluginCliLogger();
 
-function hasIgnoredAsyncPluginRegistration(registry: PluginRegistry): boolean {
-  return (registry.diagnostics ?? []).some(
-    (entry) =>
-      entry.message === "plugin register returned a promise; async registration is ignored",
-  );
-}
-
-function mergeCliRegistrars(params: {
-  runtimeRegistry: PluginRegistry;
-  metadataRegistry: PluginRegistry;
-}) {
-  const runtimeCommands = new Set(
-    params.runtimeRegistry.cliRegistrars.flatMap((entry) => entry.commands),
-  );
-  return [
-    ...params.runtimeRegistry.cliRegistrars,
-    ...params.metadataRegistry.cliRegistrars.filter(
-      (entry) => !entry.commands.some((command) => runtimeCommands.has(command)),
-    ),
-  ];
-}
-
-function resolvePluginCliLoadContext(cfg?: OpenClawConfig, env?: NodeJS.ProcessEnv) {
-  const config = cfg ?? loadConfig();
-  const autoEnabled = applyPluginAutoEnable({ config, env: env ?? process.env });
-  const resolvedConfig = autoEnabled.config;
-  const workspaceDir = resolveAgentWorkspaceDir(
-    resolvedConfig,
-    resolveDefaultAgentId(resolvedConfig),
-  );
-  const logger: PluginLogger = {
-    info: (msg: string) => log.info(msg),
-    warn: (msg: string) => log.warn(msg),
-    error: (msg: string) => log.error(msg),
-    debug: (msg: string) => log.debug(msg),
+export const loadValidatedConfigForPluginRegistration =
+  async (): Promise<OpenClawConfig | null> => {
+    const snapshot = await readConfigFileSnapshot();
+    if (!snapshot.valid) {
+      return null;
+    }
+    return loadConfig();
   };
-  return {
-    rawConfig: config,
-    config: resolvedConfig,
-    autoEnabledReasons: autoEnabled.autoEnabledReasons,
-    workspaceDir,
-    logger,
-  };
-}
-
-async function loadPluginCliMetadataRegistry(
-  cfg?: OpenClawConfig,
-  env?: NodeJS.ProcessEnv,
-  loaderOptions?: Pick<PluginLoadOptions, "pluginSdkResolution">,
-) {
-  const context = resolvePluginCliLoadContext(cfg, env);
-  return {
-    ...context,
-    registry: await loadOpenClawPluginCliRegistry({
-      config: context.config,
-      activationSourceConfig: context.rawConfig,
-      autoEnabledReasons: context.autoEnabledReasons,
-      workspaceDir: context.workspaceDir,
-      env,
-      logger: context.logger,
-      ...loaderOptions,
-    }),
-  };
-}
-
-async function loadPluginCliCommandRegistry(
-  cfg?: OpenClawConfig,
-  env?: NodeJS.ProcessEnv,
-  loaderOptions?: Pick<PluginLoadOptions, "pluginSdkResolution">,
-) {
-  const context = resolvePluginCliLoadContext(cfg, env);
-  const runtimeRegistry = loadOpenClawPlugins({
-    config: context.config,
-    activationSourceConfig: context.rawConfig,
-    autoEnabledReasons: context.autoEnabledReasons,
-    workspaceDir: context.workspaceDir,
-    env,
-    logger: context.logger,
-    ...loaderOptions,
-  });
-
-  if (!hasIgnoredAsyncPluginRegistration(runtimeRegistry)) {
-    return {
-      ...context,
-      registry: runtimeRegistry,
-    };
-  }
-
-  try {
-    const metadataRegistry = await loadOpenClawPluginCliRegistry({
-      config: context.config,
-      activationSourceConfig: context.rawConfig,
-      autoEnabledReasons: context.autoEnabledReasons,
-      workspaceDir: context.workspaceDir,
-      env,
-      logger: context.logger,
-      ...loaderOptions,
-    });
-    return {
-      ...context,
-      registry: {
-        ...runtimeRegistry,
-        cliRegistrars: mergeCliRegistrars({
-          runtimeRegistry,
-          metadataRegistry,
-        }),
-      },
-    };
-  } catch (error) {
-    log.warn(`plugin CLI metadata fallback failed: ${String(error)}`);
-    return {
-      ...context,
-      registry: runtimeRegistry,
-    };
-  }
-}
 
 export async function getPluginCliCommandDescriptors(
   cfg?: OpenClawConfig,
   env?: NodeJS.ProcessEnv,
-  loaderOptions?: Pick<PluginLoadOptions, "pluginSdkResolution">,
+  loaderOptions?: PluginCliLoaderOptions,
 ): Promise<OpenClawPluginCliCommandDescriptor[]> {
-  try {
-    const { registry } = await loadPluginCliMetadataRegistry(cfg, env, loaderOptions);
-    const seen = new Set<string>();
-    const descriptors: OpenClawPluginCliCommandDescriptor[] = [];
-    for (const entry of registry.cliRegistrars) {
-      for (const descriptor of entry.descriptors) {
-        if (seen.has(descriptor.name)) {
-          continue;
-        }
-        seen.add(descriptor.name);
-        descriptors.push(descriptor);
-      }
-    }
-    return descriptors;
-  } catch {
-    return [];
-  }
+  return loadPluginCliDescriptors({ cfg, env, loaderOptions });
 }
 
 export async function registerPluginCliCommands(
   program: Command,
   cfg?: OpenClawConfig,
   env?: NodeJS.ProcessEnv,
-  loaderOptions?: Pick<PluginLoadOptions, "pluginSdkResolution">,
+  loaderOptions?: PluginCliLoaderOptions,
   options?: RegisterPluginCliOptions,
 ) {
-  const { config, workspaceDir, logger, registry } = await loadPluginCliCommandRegistry(
-    cfg,
-    env,
-    loaderOptions,
-  );
   const mode = options?.mode ?? "eager";
   const primary = options?.primary ?? null;
 
-  const existingCommands = new Set(program.commands.map((cmd) => cmd.name()));
-
-  for (const entry of registry.cliRegistrars) {
-    const registerEntry = async () => {
-      await entry.register({
-        program,
-        config,
-        workspaceDir,
-        logger,
-      });
-    };
-
-    if (primary && entry.commands.includes(primary)) {
-      for (const commandName of new Set(entry.commands)) {
-        removeCommandByName(program, commandName);
-      }
-      await registerEntry();
-      for (const command of entry.commands) {
-        existingCommands.add(command);
-      }
-      continue;
-    }
-
-    if (entry.commands.length > 0) {
-      const overlaps = entry.commands.filter((command) => existingCommands.has(command));
-      if (overlaps.length > 0) {
-        log.debug(
-          `plugin CLI register skipped (${entry.pluginId}): command already registered (${overlaps.join(
-            ", ",
-          )})`,
-        );
-        continue;
-      }
-    }
-
-    try {
-      if (mode === "lazy" && canRegisterPluginCliLazily(entry)) {
-        for (const descriptor of entry.descriptors) {
-          registerLazyCommand({
-            program,
-            name: descriptor.name,
-            description: descriptor.description,
-            removeNames: entry.commands,
-            register: async () => {
-              await registerEntry();
-            },
-          });
-        }
-      } else {
-        if (mode === "lazy" && entry.descriptors.length > 0) {
-          log.debug(
-            `plugin CLI lazy register fallback to eager (${entry.pluginId}): descriptors do not cover all command roots`,
-          );
-        }
-        await registerEntry();
-      }
-      for (const command of entry.commands) {
-        existingCommands.add(command);
-      }
-    } catch (err) {
-      log.warn(`plugin CLI register failed (${entry.pluginId}): ${String(err)}`);
-    }
-  }
+  await registerPluginCliCommandGroups(
+    program,
+    await loadPluginCliRegistrationEntriesWithDefaults({ cfg, env, loaderOptions }),
+    {
+      mode,
+      primary,
+      existingCommands: new Set(program.commands.map((cmd) => cmd.name())),
+      logger,
+    },
+  );
+}
+
+export async function registerPluginCliCommandsFromValidatedConfig(
+  program: Command,
+  env?: NodeJS.ProcessEnv,
+  loaderOptions?: PluginCliLoaderOptions,
+  options?: RegisterPluginCliOptions,
+): Promise<OpenClawConfig | null> {
+  const config = await loadValidatedConfigForPluginRegistration();
+  if (!config) {
+    return null;
+  }
+  await registerPluginCliCommands(program, config, env, loaderOptions, options);
+  return config;
 }

src/plugins/register-plugin-cli-command-groups.ts

@@ -0,0 +1,83 @@
+import type { Command } from "commander";
+import {
+  findCommandGroupEntry,
+  getCommandGroupNames,
+  registerLazyCommandGroup,
+  removeCommandGroupNames,
+  type CommandGroupEntry,
+} from "../cli/program/register-command-groups.js";
+import type { OpenClawPluginCliCommandDescriptor, PluginLogger } from "./types.js";
+
+export type PluginCliCommandGroupEntry = CommandGroupEntry & {
+  pluginId: string;
+};
+
+export type PluginCliCommandGroupMode = "eager" | "lazy";
+
+function canRegisterPluginCliLazily(entry: PluginCliCommandGroupEntry): boolean {
+  if (entry.placeholders.length === 0) {
+    return false;
+  }
+  const descriptorNames = new Set(
+    (entry.placeholders as readonly OpenClawPluginCliCommandDescriptor[]).map(
+      (descriptor) => descriptor.name,
+    ),
+  );
+  return getCommandGroupNames(entry).every((command) => descriptorNames.has(command));
+}
+
+export async function registerPluginCliCommandGroups(
+  program: Command,
+  entries: readonly PluginCliCommandGroupEntry[],
+  params: {
+    mode: PluginCliCommandGroupMode;
+    primary: string | null;
+    existingCommands: Set<string>;
+    logger: PluginLogger;
+  },
+) {
+  for (const entry of entries) {
+    const registerEntry = async () => {
+      await entry.register(program);
+      for (const command of getCommandGroupNames(entry)) {
+        params.existingCommands.add(command);
+      }
+    };
+
+    if (params.primary && findCommandGroupEntry([entry], params.primary)) {
+      removeCommandGroupNames(program, entry);
+      await registerEntry();
+      continue;
+    }
+
+    const overlaps = getCommandGroupNames(entry).filter((command) =>
+      params.existingCommands.has(command),
+    );
+    if (overlaps.length > 0) {
+      params.logger.debug?.(
+        `plugin CLI register skipped (${entry.pluginId}): command already registered (${overlaps.join(
+          ", ",
+        )})`,
+      );
+      continue;
+    }
+
+    try {
+      if (params.mode === "lazy" && canRegisterPluginCliLazily(entry)) {
+        for (const placeholder of entry.placeholders) {
+          registerLazyCommandGroup(program, entry, placeholder);
+        }
+        continue;
+      }
+
+      if (params.mode === "lazy" && entry.placeholders.length > 0) {
+        params.logger.debug?.(
+          `plugin CLI lazy register fallback to eager (${entry.pluginId}): descriptors do not cover all command roots`,
+        );
+      }
+      await registerEntry();
+    } catch (error) {
+      params.logger.warn(`plugin CLI register failed (${entry.pluginId}): ${String(error)}`);
+    }
+  }
+}