perf(cli): speed up onboarding help startup (#84488)

frankekn · web-flow · commit 2c0c9c92f485 · 2026-05-21T11:21:58.000+08:00
Merged via squash. Prepared head SHA: b3b086e Co-authored-by: frankekn <4488090+frankekn@users.noreply.github.com> Co-authored-by: frankekn <4488090+frankekn@users.noreply.github.com> Reviewed-by: @frankekn
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,10 @@ Docs: https://docs.openclaw.ai
 
 - Tests/perf: isolate doctor core health check unit coverage from real skills/workspace discovery so `doctor-core-checks` no longer dominates unit perf while keeping one real skills-readiness smoke. (#84493) Thanks @frankekn.
 
+### Fixes
+
+- CLI/perf: keep `setup --help`, `onboard --help`, and `configure --help` out of the full wizard runtime while preserving the existing help output. (#84488) Thanks @frankekn.
+
 ## 2026.5.20
 
 ### Changes
diff --git a/src/cli/help-cold-imports.test.ts b/src/cli/help-cold-imports.test.ts
@@ -40,6 +40,19 @@ vi.mock("./progress.js", () => {
   };
 });
 
+vi.mock("../runtime.js", () => {
+  loaded.mark("default-runtime");
+  return {
+    defaultRuntime: {
+      error: vi.fn(),
+      exit: vi.fn(),
+      log: vi.fn(),
+      writeJson: vi.fn(),
+      writeStdout: vi.fn(),
+    },
+  };
+});
+
 vi.mock("../commands/doctor.js", () => {
   loaded.mark("doctor-command");
   return { doctorCommand: vi.fn(async () => {}) };
@@ -117,6 +130,26 @@ vi.mock("../commands/flows.js", () => {
   };
 });
 
+vi.mock("../commands/configure.commands.js", () => {
+  loaded.mark("configure-command");
+  return { configureCommandFromSectionsArg: vi.fn(async () => {}) };
+});
+
+vi.mock("../commands/configure.wizard.js", () => {
+  loaded.mark("configure-wizard");
+  return { runConfigureWizard: vi.fn(async () => {}) };
+});
+
+vi.mock("../commands/onboard.js", () => {
+  loaded.mark("onboard-command");
+  return { setupWizardCommand: vi.fn(async () => {}) };
+});
+
+vi.mock("../commands/setup.js", () => {
+  loaded.mark("setup-command");
+  return { setupCommand: vi.fn(async () => {}) };
+});
+
 function makeProgram(): Command {
   const program = new Command();
   program.name("openclaw");
@@ -180,4 +213,39 @@ describe("subcommand help cold imports", () => {
     expect(loaded.modules).not.toContain("tasks-command");
     expect(loaded.modules).not.toContain("flows-command");
   });
+
+  it("keeps configure help out of configure action/wizard modules", async () => {
+    const { registerConfigureCommand } = await import("./program/register.configure.js");
+    const program = makeProgram();
+
+    registerConfigureCommand(program);
+    await expectHelpExit(program, ["configure", "--help"]);
+
+    expect(loaded.modules).not.toContain("configure-command");
+    expect(loaded.modules).not.toContain("configure-wizard");
+    expect(loaded.modules).not.toContain("default-runtime");
+  });
+
+  it("keeps setup help out of setup and onboard action modules", async () => {
+    const { registerSetupCommand } = await import("./program/register.setup.js");
+    const program = makeProgram();
+
+    registerSetupCommand(program);
+    await expectHelpExit(program, ["setup", "--help"]);
+
+    expect(loaded.modules).not.toContain("setup-command");
+    expect(loaded.modules).not.toContain("onboard-command");
+    expect(loaded.modules).not.toContain("default-runtime");
+  });
+
+  it("keeps onboard help out of onboard action modules", async () => {
+    const { registerOnboardCommand } = await import("./program/register.onboard.js");
+    const program = makeProgram();
+
+    registerOnboardCommand(program);
+    await expectHelpExit(program, ["onboard", "--help"]);
+
+    expect(loaded.modules).not.toContain("onboard-command");
+    expect(loaded.modules).not.toContain("default-runtime");
+  });
 });
diff --git a/src/cli/program/register.configure.test.ts b/src/cli/program/register.configure.test.ts
@@ -13,8 +13,11 @@ const mocks = vi.hoisted(() => ({
 
 const { configureCommandFromSectionsArgMock, runtime } = mocks;
 
-vi.mock("../../commands/configure.js", () => ({
+vi.mock("../../commands/configure.shared.js", () => ({
   CONFIGURE_WIZARD_SECTIONS: ["auth", "channels", "gateway", "agent"],
+}));
+
+vi.mock("../../commands/configure.commands.js", () => ({
   configureCommandFromSectionsArg: mocks.configureCommandFromSectionsArgMock,
 }));
 
diff --git a/src/cli/program/register.configure.ts b/src/cli/program/register.configure.ts
@@ -1,14 +1,10 @@
 import type { Command } from "commander";
-import {
-  CONFIGURE_WIZARD_SECTIONS,
-  configureCommandFromSectionsArg,
-} from "../../commands/configure.js";
-import { defaultRuntime } from "../../runtime.js";
+import { CONFIGURE_WIZARD_SECTIONS } from "../../commands/configure.shared.js";
 import { formatDocsLink } from "../../terminal/links.js";
 import { theme } from "../../terminal/theme.js";
 import { runCommandWithRuntime } from "../cli-utils.js";
 
-export function registerConfigureCommand(program: Command) {
+export function registerConfigureCommand(program: Command): void {
   program
     .command("configure")
     .description("Interactive configuration for credentials, channels, gateway, and agent defaults")
@@ -24,7 +20,10 @@ export function registerConfigureCommand(program: Command) {
       [] as string[],
     )
     .action(async (opts) => {
+      const { defaultRuntime } = await import("../../runtime.js");
       await runCommandWithRuntime(defaultRuntime, async () => {
+        const { configureCommandFromSectionsArg } =
+          await import("../../commands/configure.commands.js");
         await configureCommandFromSectionsArg(opts.section, defaultRuntime);
       });
     });
diff --git a/src/cli/program/register.onboard.ts b/src/cli/program/register.onboard.ts
@@ -11,9 +11,7 @@ import type {
   SecretInputMode,
   TailscaleMode,
 } from "../../commands/onboard-types.js";
-import { setupWizardCommand } from "../../commands/onboard.js";
 import { resolveManifestProviderOnboardAuthFlags } from "../../plugins/provider-auth-choices.js";
-import { defaultRuntime } from "../../runtime.js";
 import { formatDocsLink } from "../../terminal/links.js";
 import { theme } from "../../terminal/theme.js";
 import { runCommandWithRuntime } from "../cli-utils.js";
@@ -89,7 +87,7 @@ function pickOnboardProviderAuthOptionValues(
   );
 }
 
-export function registerOnboardCommand(program: Command) {
+export function registerOnboardCommand(program: Command): void {
   const command = program
     .command("onboard")
     .description("Guided setup for auth, models, Gateway, workspace, channels, and skills")
@@ -177,6 +175,7 @@ export function registerOnboardCommand(program: Command) {
     .option("--json", "Output JSON summary", false);
 
   command.action(async (opts, commandRuntime) => {
+    const { defaultRuntime } = await import("../../runtime.js");
     await runCommandWithRuntime(defaultRuntime, async () => {
       if (opts.modern) {
         const { runCrestodian } = await import("../../crestodian/crestodian.js");
@@ -196,6 +195,7 @@ export function registerOnboardCommand(program: Command) {
       const providerAuthOptionValues = pickOnboardProviderAuthOptionValues(
         opts as Record<string, unknown>,
       );
+      const { setupWizardCommand } = await import("../../commands/onboard.js");
       await setupWizardCommand(
         {
           workspace: opts.workspace as string | undefined,
diff --git a/src/cli/program/register.setup.ts b/src/cli/program/register.setup.ts
@@ -1,13 +1,10 @@
 import type { Command } from "commander";
-import { setupWizardCommand } from "../../commands/onboard.js";
-import { setupCommand } from "../../commands/setup.js";
-import { defaultRuntime } from "../../runtime.js";
 import { formatDocsLink } from "../../terminal/links.js";
 import { theme } from "../../terminal/theme.js";
 import { runCommandWithRuntime } from "../cli-utils.js";
 import { hasExplicitOptions } from "../command-options.js";
 
-export function registerSetupCommand(program: Command) {
+export function registerSetupCommand(program: Command): void {
   program
     .command("setup")
     .description("Create baseline config/workspace files; use --wizard for full onboarding")
@@ -34,6 +31,7 @@ export function registerSetupCommand(program: Command) {
     .option("--remote-url <url>", "Remote Gateway WebSocket URL")
     .option("--remote-token <token>", "Remote Gateway token (optional)")
     .action(async (opts, command) => {
+      const { defaultRuntime } = await import("../../runtime.js");
       await runCommandWithRuntime(defaultRuntime, async () => {
         const hasWizardFlags = hasExplicitOptions(command, [
           "wizard",
@@ -46,6 +44,7 @@ export function registerSetupCommand(program: Command) {
           "remoteToken",
         ]);
         if (opts.wizard || hasWizardFlags) {
+          const { setupWizardCommand } = await import("../../commands/onboard.js");
           await setupWizardCommand(
             {
               workspace: opts.workspace as string | undefined,
@@ -61,6 +60,7 @@ export function registerSetupCommand(program: Command) {
           );
           return;
         }
+        const { setupCommand } = await import("../../commands/setup.js");
         await setupCommand({ workspace: opts.workspace as string | undefined }, defaultRuntime);
       });
     });
diff --git a/src/cli/run-main-policy.ts b/src/cli/run-main-policy.ts
@@ -20,6 +20,7 @@ import { getCoreCliParentDefaultHelpCommands } from "./program/core-command-desc
 import { getSubCliParentDefaultHelpCommands } from "./program/subcli-descriptors.js";
 
 const ROOT_HELP_ALIASES = new Set(["tools"]);
+const SETUP_ONBOARD_CONFIGURE_HELP_COMMANDS = new Set(["setup", "onboard", "configure"]);
 const BARE_PARENT_DEFAULT_HELP_COMMANDS = new Set([
   ...getCoreCliParentDefaultHelpCommands(),
   ...getSubCliParentDefaultHelpCommands(),
@@ -88,6 +89,21 @@ export function shouldUseBrowserHelpFastPath(
   );
 }
 
+export function shouldUseSetupOnboardConfigureHelpFastPath(
+  argv: string[],
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (env.OPENCLAW_DISABLE_CLI_STARTUP_HELP_FAST_PATH === "1") {
+    return false;
+  }
+  const invocation = resolveCliArgvInvocation(argv);
+  return (
+    invocation.commandPath.length === 1 &&
+    SETUP_ONBOARD_CONFIGURE_HELP_COMMANDS.has(invocation.commandPath[0] ?? "") &&
+    invocation.hasHelpOrVersion
+  );
+}
+
 export function shouldStartCrestodianForBareRoot(argv: string[]): boolean {
   const invocation = resolveCliArgvInvocation(argv);
   return invocation.commandPath.length === 0 && !invocation.hasHelpOrVersion;
diff --git a/src/cli/run-main.exit.test.ts b/src/cli/run-main.exit.test.ts
@@ -22,6 +22,7 @@ const outputPrecomputedBrowserHelpTextMock = vi.hoisted(() => vi.fn(() => false)
 const loadRootHelpRenderOptionsForConfigSensitivePluginsMock = vi.hoisted(() =>
   vi.fn<() => Promise<RootHelpRenderOptions | null>>(async () => null),
 );
+const tryOutputSetupOnboardConfigureHelpMock = vi.hoisted(() => vi.fn(async () => true));
 const buildProgramMock = vi.hoisted(() => vi.fn());
 const getProgramContextMock = vi.hoisted(() => vi.fn(() => null));
 const registerCoreCliByNameMock = vi.hoisted(() => vi.fn());
@@ -177,6 +178,10 @@ vi.mock("./root-help-live-config.js", () => ({
     loadRootHelpRenderOptionsForConfigSensitivePluginsMock,
 }));
 
+vi.mock("./setup-onboard-configure-help-fast-path.js", () => ({
+  tryOutputSetupOnboardConfigureHelp: tryOutputSetupOnboardConfigureHelpMock,
+}));
+
 vi.mock("./program.js", () => ({
   buildProgram: buildProgramMock,
 }));
@@ -252,6 +257,7 @@ describe("runCli exit behavior", () => {
     outputPrecomputedBrowserHelpTextMock.mockReturnValue(false);
     outputPrecomputedRootHelpTextMock.mockReturnValue(false);
     loadRootHelpRenderOptionsForConfigSensitivePluginsMock.mockResolvedValue(null);
+    tryOutputSetupOnboardConfigureHelpMock.mockResolvedValue(true);
     hasEnvHttpProxyAgentConfiguredMock.mockReturnValue(false);
     loadConfigMock.mockReturnValue({});
     startProxyMock.mockResolvedValue(null);
@@ -418,6 +424,20 @@ describe("runCli exit behavior", () => {
     expect(runCrestodianMock).not.toHaveBeenCalled();
   });
 
+  it("renders setup/onboard/configure help without building the full program", async () => {
+    await runCli(["node", "openclaw", "setup", "--help"]);
+
+    expect(tryOutputSetupOnboardConfigureHelpMock).toHaveBeenCalledWith([
+      "node",
+      "openclaw",
+      "setup",
+      "--help",
+    ]);
+    expect(tryRouteCliMock).not.toHaveBeenCalled();
+    expect(buildProgramMock).not.toHaveBeenCalled();
+    expect(registerPluginCliCommandsFromValidatedConfigMock).not.toHaveBeenCalled();
+  });
+
   it("renders root help without building the full program", async () => {
     const exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
       throw new Error(`unexpected process.exit(${String(code)})`);
diff --git a/src/cli/run-main.test.ts b/src/cli/run-main.test.ts
@@ -9,6 +9,7 @@ import {
   shouldStartProxyForCli,
   shouldUseBrowserHelpFastPath,
   shouldUseRootHelpFastPath,
+  shouldUseSetupOnboardConfigureHelpFastPath,
 } from "./run-main-policy.js";
 import { isGatewayRunFastPathArgv } from "./run-main.js";
 
@@ -212,6 +213,39 @@ describe("shouldUseBrowserHelpFastPath", () => {
   });
 });
 
+describe("shouldUseSetupOnboardConfigureHelpFastPath", () => {
+  it("uses the fast path only for setup, onboard, and configure help", () => {
+    expect(
+      shouldUseSetupOnboardConfigureHelpFastPath(["node", "openclaw", "setup", "--help"]),
+    ).toBe(true);
+    expect(shouldUseSetupOnboardConfigureHelpFastPath(["node", "openclaw", "onboard", "-h"])).toBe(
+      true,
+    );
+    expect(
+      shouldUseSetupOnboardConfigureHelpFastPath([
+        "node",
+        "openclaw",
+        "--profile",
+        "work",
+        "configure",
+        "-h",
+      ]),
+    ).toBe(true);
+    expect(
+      shouldUseSetupOnboardConfigureHelpFastPath([
+        "node",
+        "openclaw",
+        "onboard",
+        "status",
+        "--help",
+      ]),
+    ).toBe(false);
+    expect(
+      shouldUseSetupOnboardConfigureHelpFastPath(["node", "openclaw", "status", "--help"]),
+    ).toBe(false);
+  });
+});
+
 describe("resolveMissingPluginCommandMessage", () => {
   it("explains plugins.allow misses for a bundled plugin command", () => {
     expect(
diff --git a/src/cli/run-main.ts b/src/cli/run-main.ts
@@ -38,6 +38,7 @@ import {
   shouldStartProxyForCli,
   shouldUseBrowserHelpFastPath,
   shouldUseRootHelpFastPath,
+  shouldUseSetupOnboardConfigureHelpFastPath,
 } from "./run-main-policy.js";
 import { normalizeWindowsArgv } from "./windows-argv.js";
 
@@ -49,6 +50,7 @@ export {
   shouldStartProxyForCli,
   shouldUseBrowserHelpFastPath,
   shouldUseRootHelpFastPath,
+  shouldUseSetupOnboardConfigureHelpFastPath,
 } from "./run-main-policy.js";
 
 type Awaitable<T> = T | Promise<T>;
@@ -549,6 +551,14 @@ export async function runCli(argv: string[] = process.argv) {
       }
     }
 
+    if (shouldUseSetupOnboardConfigureHelpFastPath(normalizedArgv)) {
+      const { tryOutputSetupOnboardConfigureHelp } =
+        await import("./setup-onboard-configure-help-fast-path.js");
+      if (await tryOutputSetupOnboardConfigureHelp(normalizedArgv)) {
+        return;
+      }
+    }
+
     const shouldRunBareRootCrestodian = shouldStartCrestodianForBareRoot(normalizedArgv);
     const shouldRunModernOnboardCrestodian = shouldStartCrestodianForModernOnboard(normalizedArgv);
     if (shouldRunBareRootCrestodian || shouldRunModernOnboardCrestodian) {
diff --git a/src/cli/setup-onboard-configure-help-fast-path.ts b/src/cli/setup-onboard-configure-help-fast-path.ts
