CLI: add root --help fast path and lazy channel option resolution (#30975)

* CLI argv: add strict root help invocation guard

* Entry: add root help fast-path bootstrap bypass

* CLI context: lazily resolve channel options

* CLI context tests: cover lazy channel option resolution

* CLI argv tests: cover root help invocation detection

* Changelog: note additional startup path optimizations

* Changelog: split startup follow-up into #30975 entry

* CLI channel options: load precomputed startup metadata

* CLI channel options tests: cover precomputed metadata path

* Build: generate CLI startup metadata during build

* Build script: invoke CLI startup metadata generator

* CLI routes: preload plugins for routed health

* CLI routes tests: assert health plugin preload

* CLI: add experimental bundled entry and snapshot helper

* Tools: compare CLI startup entries in benchmark script

* Docs: add startup tuning notes for Pi and VM hosts

* CLI: drop bundled entry runtime toggle

* Build: remove bundled and snapshot scripts

* Tools: remove bundled-entry benchmark shortcut

* Docs: remove bundled startup bench examples

* Docs: remove Pi bundled entry mention

* Docs: remove VM bundled entry mention

* Changelog: remove bundled startup follow-up claims

* Build: remove snapshot helper script

* Build: remove CLI bundle tsdown config

* Doctor: add low-power startup optimization hints

* Doctor: run startup optimization hint checks

* Doctor tests: cover startup optimization host targeting

* Doctor tests: mock startup optimization note export

* CLI argv: require strict root-only help fast path

* CLI argv tests: cover mixed root-help invocations

* CLI channel options: merge metadata with runtime catalog

* CLI channel options tests: assert dynamic catalog merge

* Changelog: align #30975 startup follow-up scope

* Docs tests: remove secondary-entry startup bench note

* Docs Pi: add systemd recovery reference link

* Docs VPS: add systemd recovery reference link

src/cli/argv.test.ts

@@ -8,6 +8,7 @@ import {
   getVerboseFlag,
   hasHelpOrVersion,
   hasFlag,
+  isRootHelpInvocation,
   isRootVersionInvocation,
   shouldMigrateState,
   shouldMigrateStateFromPath,
@@ -94,6 +95,51 @@ describe("argv helpers", () => {
     expect(isRootVersionInvocation(argv)).toBe(expected);
   });
 
+  it.each([
+    {
+      name: "root --help",
+      argv: ["node", "openclaw", "--help"],
+      expected: true,
+    },
+    {
+      name: "root -h",
+      argv: ["node", "openclaw", "-h"],
+      expected: true,
+    },
+    {
+      name: "root --help with profile",
+      argv: ["node", "openclaw", "--profile", "work", "--help"],
+      expected: true,
+    },
+    {
+      name: "subcommand --help",
+      argv: ["node", "openclaw", "status", "--help"],
+      expected: false,
+    },
+    {
+      name: "help before subcommand token",
+      argv: ["node", "openclaw", "--help", "status"],
+      expected: false,
+    },
+    {
+      name: "help after -- terminator",
+      argv: ["node", "openclaw", "nodes", "run", "--", "git", "--help"],
+      expected: false,
+    },
+    {
+      name: "unknown root flag before help",
+      argv: ["node", "openclaw", "--unknown", "--help"],
+      expected: false,
+    },
+    {
+      name: "unknown root flag after help",
+      argv: ["node", "openclaw", "--help", "--unknown"],
+      expected: false,
+    },
+  ])("detects root-only help invocations: $name", ({ argv, expected }) => {
+    expect(isRootHelpInvocation(argv)).toBe(expected);
+  });
+
   it.each([
     {
       name: "single command with trailing flag",

src/cli/argv.ts

@@ -119,6 +119,40 @@ export function isRootVersionInvocation(argv: string[]): boolean {
   return hasVersion;
 }
 
+export function isRootHelpInvocation(argv: string[]): boolean {
+  const args = argv.slice(2);
+  let hasHelp = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === FLAG_TERMINATOR) {
+      break;
+    }
+    if (HELP_FLAGS.has(arg)) {
+      hasHelp = true;
+      continue;
+    }
+    if (ROOT_BOOLEAN_FLAGS.has(arg)) {
+      continue;
+    }
+    if (arg.startsWith("--profile=") || arg.startsWith("--log-level=")) {
+      continue;
+    }
+    if (ROOT_VALUE_FLAGS.has(arg)) {
+      const next = args[i + 1];
+      if (isValueToken(next)) {
+        i += 1;
+      }
+      continue;
+    }
+    // Unknown flags and subcommand-scoped help should fall back to Commander.
+    return false;
+  }
+  return hasHelp;
+}
+
 export function getFlagValue(argv: string[], name: string): string | null | undefined {
   const args = argv.slice(2);
   for (let i = 0; i < args.length; i += 1) {

src/cli/channel-options.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const readFileSyncMock = vi.hoisted(() => vi.fn());
+const listCatalogMock = vi.hoisted(() => vi.fn());
+const listPluginsMock = vi.hoisted(() => vi.fn());
+const ensurePluginRegistryLoadedMock = vi.hoisted(() => vi.fn());
+
+vi.mock("node:fs", async () => {
+  const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
+  const base = ("default" in actual ? actual.default : actual) as Record<string, unknown>;
+  return {
+    ...actual,
+    default: {
+      ...base,
+      readFileSync: readFileSyncMock,
+    },
+    readFileSync: readFileSyncMock,
+  };
+});
+
+vi.mock("../channels/registry.js", () => ({
+  CHAT_CHANNEL_ORDER: ["telegram", "discord"],
+}));
+
+vi.mock("../channels/plugins/catalog.js", () => ({
+  listChannelPluginCatalogEntries: listCatalogMock,
+}));
+
+vi.mock("../channels/plugins/index.js", () => ({
+  listChannelPlugins: listPluginsMock,
+}));
+
+vi.mock("./plugin-registry.js", () => ({
+  ensurePluginRegistryLoaded: ensurePluginRegistryLoadedMock,
+}));
+
+async function loadModule() {
+  return await import("./channel-options.js");
+}
+
+describe("resolveCliChannelOptions", () => {
+  afterEach(() => {
+    delete process.env.OPENCLAW_EAGER_CHANNEL_OPTIONS;
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  it("uses precomputed startup metadata when available", async () => {
+    readFileSyncMock.mockReturnValue(
+      JSON.stringify({ channelOptions: ["cached", "telegram", "cached"] }),
+    );
+    listCatalogMock.mockReturnValue([{ id: "catalog-only" }]);
+
+    const mod = await loadModule();
+    expect(mod.resolveCliChannelOptions()).toEqual(["cached", "telegram", "catalog-only"]);
+    expect(listCatalogMock).toHaveBeenCalledOnce();
+  });
+
+  it("falls back to dynamic catalog resolution when metadata is missing", async () => {
+    readFileSyncMock.mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+    listCatalogMock.mockReturnValue([{ id: "feishu" }, { id: "telegram" }]);
+
+    const mod = await loadModule();
+    expect(mod.resolveCliChannelOptions()).toEqual(["telegram", "discord", "feishu"]);
+    expect(listCatalogMock).toHaveBeenCalledOnce();
+  });
+
+  it("respects eager mode and includes loaded plugin ids", async () => {
+    process.env.OPENCLAW_EAGER_CHANNEL_OPTIONS = "1";
+    readFileSyncMock.mockReturnValue(JSON.stringify({ channelOptions: ["cached"] }));
+    listCatalogMock.mockReturnValue([{ id: "zalo" }]);
+    listPluginsMock.mockReturnValue([{ id: "custom-a" }, { id: "custom-b" }]);
+
+    const mod = await loadModule();
+    expect(mod.resolveCliChannelOptions()).toEqual([
+      "telegram",
+      "discord",
+      "zalo",
+      "custom-a",
+      "custom-b",
+    ]);
+    expect(ensurePluginRegistryLoadedMock).toHaveBeenCalledOnce();
+    expect(listPluginsMock).toHaveBeenCalledOnce();
+  });
+
+  it("keeps dynamic catalog resolution when external catalog env is set", async () => {
+    process.env.OPENCLAW_PLUGIN_CATALOG_PATHS = "/tmp/plugins-catalog.json";
+    readFileSyncMock.mockReturnValue(JSON.stringify({ channelOptions: ["cached", "telegram"] }));
+    listCatalogMock.mockReturnValue([{ id: "custom-catalog" }]);
+
+    const mod = await loadModule();
+    expect(mod.resolveCliChannelOptions()).toEqual(["cached", "telegram", "custom-catalog"]);
+    expect(listCatalogMock).toHaveBeenCalledOnce();
+    delete process.env.OPENCLAW_PLUGIN_CATALOG_PATHS;
+  });
+});

src/cli/channel-options.ts

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { listChannelPluginCatalogEntries } from "../channels/plugins/catalog.js";
 import { listChannelPlugins } from "../channels/plugins/index.js";
 import { CHAT_CHANNEL_ORDER } from "../channels/registry.js";
@@ -17,14 +20,46 @@ function dedupe(values: string[]): string[] {
   return resolved;
 }
 
+let precomputedChannelOptions: string[] | null | undefined;
+
+function loadPrecomputedChannelOptions(): string[] | null {
+  if (precomputedChannelOptions !== undefined) {
+    return precomputedChannelOptions;
+  }
+  try {
+    const metadataPath = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "..",
+      "cli-startup-metadata.json",
+    );
+    const raw = fs.readFileSync(metadataPath, "utf8");
+    const parsed = JSON.parse(raw) as { channelOptions?: unknown };
+    if (Array.isArray(parsed.channelOptions)) {
+      precomputedChannelOptions = dedupe(
+        parsed.channelOptions.filter((value): value is string => typeof value === "string"),
+      );
+      return precomputedChannelOptions;
+    }
+  } catch {
+    // Fall back to dynamic catalog resolution.
+  }
+  precomputedChannelOptions = null;
+  return null;
+}
+
 export function resolveCliChannelOptions(): string[] {
-  const catalog = listChannelPluginCatalogEntries().map((entry) => entry.id);
-  const base = dedupe([...CHAT_CHANNEL_ORDER, ...catalog]);
   if (isTruthyEnvValue(process.env.OPENCLAW_EAGER_CHANNEL_OPTIONS)) {
+    const catalog = listChannelPluginCatalogEntries().map((entry) => entry.id);
+    const base = dedupe([...CHAT_CHANNEL_ORDER, ...catalog]);
     ensurePluginRegistryLoaded();
     const pluginIds = listChannelPlugins().map((plugin) => plugin.id);
     return dedupe([...base, ...pluginIds]);
   }
+  const precomputed = loadPrecomputedChannelOptions();
+  const catalog = listChannelPluginCatalogEntries().map((entry) => entry.id);
+  const base = precomputed
+    ? dedupe([...precomputed, ...catalog])
+    : dedupe([...CHAT_CHANNEL_ORDER, ...catalog]);
   return base;
 }
 

src/cli/program/context.test.ts

@@ -14,24 +14,48 @@ const { createProgramContext } = await import("./context.js");
 
 describe("createProgramContext", () => {
   it("builds program context from version and resolved channel options", () => {
-    resolveCliChannelOptionsMock.mockReturnValue(["telegram", "whatsapp"]);
-
-    expect(createProgramContext()).toEqual({
+    resolveCliChannelOptionsMock.mockClear().mockReturnValue(["telegram", "whatsapp"]);
+    const ctx = createProgramContext();
+    expect(ctx).toEqual({
       programVersion: "9.9.9-test",
       channelOptions: ["telegram", "whatsapp"],
       messageChannelOptions: "telegram|whatsapp",
       agentChannelOptions: "last|telegram|whatsapp",
     });
+    expect(resolveCliChannelOptionsMock).toHaveBeenCalledOnce();
   });
 
   it("handles empty channel options", () => {
-    resolveCliChannelOptionsMock.mockReturnValue([]);
-
-    expect(createProgramContext()).toEqual({
+    resolveCliChannelOptionsMock.mockClear().mockReturnValue([]);
+    const ctx = createProgramContext();
+    expect(ctx).toEqual({
       programVersion: "9.9.9-test",
       channelOptions: [],
       messageChannelOptions: "",
       agentChannelOptions: "last",
     });
+    expect(resolveCliChannelOptionsMock).toHaveBeenCalledOnce();
+  });
+
+  it("does not resolve channel options before access", () => {
+    resolveCliChannelOptionsMock.mockClear();
+    createProgramContext();
+    expect(resolveCliChannelOptionsMock).not.toHaveBeenCalled();
+  });
+
+  it("reuses one channel option resolution across all getters", () => {
+    resolveCliChannelOptionsMock.mockClear().mockReturnValue(["telegram"]);
+    const ctx = createProgramContext();
+    expect(ctx.channelOptions).toEqual(["telegram"]);
+    expect(ctx.messageChannelOptions).toBe("telegram");
+    expect(ctx.agentChannelOptions).toBe("last|telegram");
+    expect(resolveCliChannelOptionsMock).toHaveBeenCalledOnce();
+  });
+
+  it("reads program version without resolving channel options", () => {
+    resolveCliChannelOptionsMock.mockClear();
+    const ctx = createProgramContext();
+    expect(ctx.programVersion).toBe("9.9.9-test");
+    expect(resolveCliChannelOptionsMock).not.toHaveBeenCalled();
   });
 });

src/cli/program/context.ts

@@ -9,11 +9,24 @@ export type ProgramContext = {
 };
 
 export function createProgramContext(): ProgramContext {
-  const channelOptions = resolveCliChannelOptions();
+  let cachedChannelOptions: string[] | undefined;
+  const getChannelOptions = (): string[] => {
+    if (cachedChannelOptions === undefined) {
+      cachedChannelOptions = resolveCliChannelOptions();
+    }
+    return cachedChannelOptions;
+  };
+
   return {
     programVersion: VERSION,
-    channelOptions,
-    messageChannelOptions: channelOptions.join("|"),
-    agentChannelOptions: ["last", ...channelOptions].join("|"),
+    get channelOptions() {
+      return getChannelOptions();
+    },
+    get messageChannelOptions() {
+      return getChannelOptions().join("|");
+    },
+    get agentChannelOptions() {
+      return ["last", ...getChannelOptions()].join("|");
+    },
   };
 }

src/cli/program/routes.test.ts

@@ -18,9 +18,9 @@ describe("program routes", () => {
     expect(route?.loadPlugins).toBe(true);
   });
 
-  it("matches health route without eager plugin loading", () => {
+  it("matches health route and preloads plugins for channel diagnostics", () => {
     const route = expectRoute(["health"]);
-    expect(route?.loadPlugins).toBeUndefined();
+    expect(route?.loadPlugins).toBe(true);
   });
 
   it("returns false when status timeout flag value is missing", async () => {

src/cli/program/routes.ts

@@ -9,6 +9,9 @@ export type RouteSpec = {
 
 const routeHealth: RouteSpec = {
   match: (path) => path[0] === "health",
+  // Health output uses channel plugin metadata for account fallback/log details.
+  // Keep routed behavior aligned with non-routed command execution.
+  loadPlugins: true,
   run: async (argv) => {
     const json = hasFlag(argv, "--json");
     const verbose = getVerboseFlag(argv, { includeDebug: true });