Streamline OpenClaw onboarding (#98218)

* feat: streamline onboarding setup flow

* fix: harden onboarding preflight installs

* test: isolate gateway preflight safety env

* fix: keep local gateway probes on loopback

* fix: honor onboarding node manager installs

* docs: align setup onboarding reference

* fix: harden bare gateway probe fallback

* fix: honor env gateway auth in bare TUI probe

* test: isolate wizard TUI hatch mocks

src/cli/program/register.onboard.ts

@@ -10,6 +10,7 @@ import type {
   GatewayAuthChoice,
   GatewayBind,
   NodeManagerChoice,
+  OnboardOptions,
   ResetScope,
   SecretInputMode,
   TailscaleMode,
@@ -90,6 +91,70 @@ function pickOnboardProviderAuthOptionValues(
   );
 }
 
+export function registerOnboardAuthOptions(command: Command): Command {
+  command
+    .option("--auth-choice <choice>", `Auth: ${AUTH_CHOICE_HELP}`)
+    .option(
+      "--token-provider <id>",
+      "Token provider id (non-interactive; used with --auth-choice token)",
+    )
+    .option("--token <token>", "Token value (non-interactive; used with --auth-choice token)")
+    .option(
+      "--token-profile-id <id>",
+      "Auth profile id (non-interactive; default: <provider>:manual)",
+    )
+    .option("--token-expires-in <duration>", "Optional token expiry duration (e.g. 365d, 12h)")
+    .option(
+      "--secret-input-mode <mode>",
+      "API key persistence mode: plaintext|ref (default: plaintext)",
+    )
+    .option("--cloudflare-ai-gateway-account-id <id>", "Cloudflare Account ID")
+    .option("--cloudflare-ai-gateway-gateway-id <id>", "Cloudflare AI Gateway ID");
+
+  for (const providerFlag of ONBOARD_AUTH_FLAGS) {
+    command.option(providerFlag.cliOption, providerFlag.description);
+  }
+
+  return command
+    .option("--custom-base-url <url>", "Custom provider base URL")
+    .option("--custom-api-key <key>", "Custom provider API key (optional)")
+    .option("--custom-model-id <id>", "Custom provider model ID")
+    .option("--custom-provider-id <id>", "Custom provider ID (optional; auto-derived by default)")
+    .option(
+      "--custom-compatibility <mode>",
+      "Custom provider API compatibility: openai|openai-responses|anthropic (default: openai)",
+    )
+    .option("--custom-image-input", "Mark the custom provider model as image-capable")
+    .option("--custom-text-input", "Mark the custom provider model as text-only");
+}
+
+export function pickOnboardAuthOptionValues(
+  opts: Record<string, unknown>,
+): Partial<OnboardOptions> {
+  const customTextInput = opts.customTextInput === true;
+  return {
+    authChoice: opts.authChoice as AuthChoice | undefined,
+    tokenProvider: opts.tokenProvider as string | undefined,
+    token: opts.token as string | undefined,
+    tokenProfileId: opts.tokenProfileId as string | undefined,
+    tokenExpiresIn: opts.tokenExpiresIn as string | undefined,
+    secretInputMode: opts.secretInputMode as SecretInputMode | undefined,
+    ...pickOnboardProviderAuthOptionValues(opts),
+    cloudflareAiGatewayAccountId: opts.cloudflareAiGatewayAccountId as string | undefined,
+    cloudflareAiGatewayGatewayId: opts.cloudflareAiGatewayGatewayId as string | undefined,
+    customBaseUrl: opts.customBaseUrl as string | undefined,
+    customApiKey: opts.customApiKey as string | undefined,
+    customModelId: opts.customModelId as string | undefined,
+    customProviderId: opts.customProviderId as string | undefined,
+    customCompatibility: opts.customCompatibility as
+      | "openai"
+      | "openai-responses"
+      | "anthropic"
+      | undefined,
+    customImageInput: customTextInput ? false : opts.customImageInput === true ? true : undefined,
+  };
+}
+
 export function registerOnboardCommand(program: Command): void {
   const command = program
     .command("onboard")
@@ -113,40 +178,11 @@ export function registerOnboardCommand(program: Command): void {
       false,
     )
     .option("--flow <flow>", "Onboard flow: quickstart|advanced|manual|import")
-    .option("--mode <mode>", "Onboard mode: local|remote")
-    .option("--auth-choice <choice>", `Auth: ${AUTH_CHOICE_HELP}`)
-    .option(
-      "--token-provider <id>",
-      "Token provider id (non-interactive; used with --auth-choice token)",
-    )
-    .option("--token <token>", "Token value (non-interactive; used with --auth-choice token)")
-    .option(
-      "--token-profile-id <id>",
-      "Auth profile id (non-interactive; default: <provider>:manual)",
-    )
-    .option("--token-expires-in <duration>", "Optional token expiry duration (e.g. 365d, 12h)")
-    .option(
-      "--secret-input-mode <mode>",
-      "API key persistence mode: plaintext|ref (default: plaintext)",
-    )
-    .option("--cloudflare-ai-gateway-account-id <id>", "Cloudflare Account ID")
-    .option("--cloudflare-ai-gateway-gateway-id <id>", "Cloudflare AI Gateway ID");
+    .option("--mode <mode>", "Onboard mode: local|remote");
 
-  for (const providerFlag of ONBOARD_AUTH_FLAGS) {
-    command.option(providerFlag.cliOption, providerFlag.description);
-  }
+  registerOnboardAuthOptions(command);
 
   command
-    .option("--custom-base-url <url>", "Custom provider base URL")
-    .option("--custom-api-key <key>", "Custom provider API key (optional)")
-    .option("--custom-model-id <id>", "Custom provider model ID")
-    .option("--custom-provider-id <id>", "Custom provider ID (optional; auto-derived by default)")
-    .option(
-      "--custom-compatibility <mode>",
-      "Custom provider API compatibility: openai|openai-responses|anthropic (default: openai)",
-    )
-    .option("--custom-image-input", "Mark the custom provider model as image-capable")
-    .option("--custom-text-input", "Mark the custom provider model as text-only")
     .option("--gateway-port <port>", "Gateway port")
     .option("--gateway-bind <mode>", "Gateway bind: loopback|tailnet|lan|auto|custom")
     .option("--gateway-auth <mode>", "Gateway auth: token|password")
@@ -195,9 +231,6 @@ export function registerOnboardCommand(program: Command): void {
         installDaemon: Boolean(opts.installDaemon),
       });
       const gatewayPort = parsePort(opts.gatewayPort);
-      const providerAuthOptionValues = pickOnboardProviderAuthOptionValues(
-        opts as Record<string, unknown>,
-      );
       const { setupWizardCommand } = await import("../../commands/onboard.js");
       await setupWizardCommand(
         {
@@ -206,30 +239,7 @@ export function registerOnboardCommand(program: Command): void {
           acceptRisk: Boolean(opts.acceptRisk),
           flow: opts.flow as "quickstart" | "advanced" | "manual" | "import" | undefined,
           mode: opts.mode as "local" | "remote" | undefined,
-          authChoice: opts.authChoice as AuthChoice | undefined,
-          tokenProvider: opts.tokenProvider as string | undefined,
-          token: opts.token as string | undefined,
-          tokenProfileId: opts.tokenProfileId as string | undefined,
-          tokenExpiresIn: opts.tokenExpiresIn as string | undefined,
-          secretInputMode: opts.secretInputMode as SecretInputMode | undefined,
-          ...providerAuthOptionValues,
-          cloudflareAiGatewayAccountId: opts.cloudflareAiGatewayAccountId as string | undefined,
-          cloudflareAiGatewayGatewayId: opts.cloudflareAiGatewayGatewayId as string | undefined,
-          customBaseUrl: opts.customBaseUrl as string | undefined,
-          customApiKey: opts.customApiKey as string | undefined,
-          customModelId: opts.customModelId as string | undefined,
-          customProviderId: opts.customProviderId as string | undefined,
-          customCompatibility: opts.customCompatibility as
-            | "openai"
-            | "openai-responses"
-            | "anthropic"
-            | undefined,
-          customImageInput:
-            opts.customTextInput === true
-              ? false
-              : opts.customImageInput === true
-                ? true
-                : undefined,
+          ...pickOnboardAuthOptionValues(opts as Record<string, unknown>),
           gatewayPort: gatewayPort ?? undefined,
           gatewayBind: opts.gatewayBind as GatewayBind | undefined,
           gatewayAuth: opts.gatewayAuth as GatewayAuthChoice | undefined,

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

@@ -52,9 +52,17 @@ describe("registerSetupCommand", () => {
     setupWizardCommandMock.mockResolvedValue(undefined);
   });
 
-  it("runs setup command by default", async () => {
+  it("runs setup wizard command by default", async () => {
     await runCli(["setup", "--workspace", "/tmp/ws"]);
 
+    expect(setupWizardCommandMock).toHaveBeenCalledWith(lastWizardOptions(), runtime);
+    expect(lastWizardOptions()?.workspace).toBe("/tmp/ws");
+    expect(setupCommandMock).not.toHaveBeenCalled();
+  });
+
+  it("runs baseline setup command when --baseline is set", async () => {
+    await runCli(["setup", "--baseline", "--workspace", "/tmp/ws"]);
+
     expect(setupCommandMock).toHaveBeenCalledWith(lastSetupOptions(), runtime);
     expect(lastSetupOptions()?.workspace).toBe("/tmp/ws");
     expect(setupWizardCommandMock).not.toHaveBeenCalled();
@@ -79,6 +87,106 @@ describe("registerSetupCommand", () => {
     expect(setupCommandMock).not.toHaveBeenCalled();
   });
 
+  it("forwards scripted onboarding controls", async () => {
+    await runCli([
+      "setup",
+      "--non-interactive",
+      "--accept-risk",
+      "--flow",
+      "advanced",
+      "--gateway-port",
+      "18789",
+      "--install-daemon",
+      "--skip-daemon",
+      "--skip-health",
+      "--skip-ui",
+      "--skip-channels",
+      "--skip-search",
+      "--skip-skills",
+      "--skip-bootstrap",
+      "--node-manager",
+      "pnpm",
+      "--json",
+    ]);
+
+    expect(setupWizardCommandMock).toHaveBeenCalledWith(lastWizardOptions(), runtime);
+    expect(lastWizardOptions()).toMatchObject({
+      nonInteractive: true,
+      acceptRisk: true,
+      flow: "advanced",
+      gatewayPort: 18789,
+      installDaemon: false,
+      skipHealth: true,
+      skipUi: true,
+      skipChannels: true,
+      skipSearch: true,
+      skipSkills: true,
+      skipBootstrap: true,
+      nodeManager: "pnpm",
+      json: true,
+    });
+    expect(setupCommandMock).not.toHaveBeenCalled();
+  });
+
+  it("forwards onboard auth flags through the setup alias", async () => {
+    await runCli([
+      "setup",
+      "--non-interactive",
+      "--accept-risk",
+      "--auth-choice",
+      "token",
+      "--token-provider",
+      "openai",
+      "--token",
+      "test-token",
+      "--token-profile-id",
+      "openai:manual",
+      "--token-expires-in",
+      "1d",
+      "--secret-input-mode",
+      "ref",
+      "--openai-api-key",
+      "test-openai-api-key",
+      "--cloudflare-ai-gateway-account-id",
+      "account-id",
+      "--cloudflare-ai-gateway-gateway-id",
+      "gateway-id",
+      "--custom-base-url",
+      "https://example.test/v1",
+      "--custom-api-key",
+      "test-custom-api-key",
+      "--custom-model-id",
+      "custom-model",
+      "--custom-provider-id",
+      "custom-provider",
+      "--custom-compatibility",
+      "anthropic",
+      "--custom-text-input",
+    ]);
+
+    expect(setupWizardCommandMock).toHaveBeenCalledWith(lastWizardOptions(), runtime);
+    expect(lastWizardOptions()).toMatchObject({
+      nonInteractive: true,
+      acceptRisk: true,
+      authChoice: "token",
+      tokenProvider: "openai",
+      token: "test-token",
+      tokenProfileId: "openai:manual",
+      tokenExpiresIn: "1d",
+      secretInputMode: "ref",
+      openaiApiKey: "test-openai-api-key",
+      cloudflareAiGatewayAccountId: "account-id",
+      cloudflareAiGatewayGatewayId: "gateway-id",
+      customBaseUrl: "https://example.test/v1",
+      customApiKey: "test-custom-api-key",
+      customModelId: "custom-model",
+      customProviderId: "custom-provider",
+      customCompatibility: "anthropic",
+      customImageInput: false,
+    });
+    expect(setupCommandMock).not.toHaveBeenCalled();
+  });
+
   it("runs setup wizard command for migration import flags", async () => {
     await runCli([
       "setup",
@@ -97,7 +205,7 @@ describe("registerSetupCommand", () => {
   });
 
   it("reports setup errors through runtime", async () => {
-    setupCommandMock.mockRejectedValueOnce(new Error("setup failed"));
+    setupWizardCommandMock.mockRejectedValueOnce(new Error("setup failed"));
 
     await runCli(["setup"]);
 

src/cli/program/register.setup.ts

@@ -2,21 +2,50 @@
 import type { Command } from "commander";
 import { formatDocsLink } from "../../../packages/terminal-core/src/links.js";
 import { theme } from "../../../packages/terminal-core/src/theme.js";
+import type { GatewayDaemonRuntime } from "../../commands/daemon-runtime.js";
+import type {
+  GatewayAuthChoice,
+  GatewayBind,
+  NodeManagerChoice,
+  ResetScope,
+  TailscaleMode,
+} from "../../commands/onboard-types.js";
 import { runCommandWithRuntime } from "../cli-utils.js";
-import { hasExplicitOptions } from "../command-options.js";
+import { parsePort } from "../shared/parse-port.js";
+import { pickOnboardAuthOptionValues, registerOnboardAuthOptions } from "./register.onboard.js";
 
-/** Register the `setup` command and route wizard-style invocations to onboarding. */
+function resolveInstallDaemonFlag(
+  command: unknown,
+  opts: { installDaemon?: boolean },
+): boolean | undefined {
+  if (!command || typeof command !== "object") {
+    return undefined;
+  }
+  const getOptionValueSource =
+    "getOptionValueSource" in command ? command.getOptionValueSource : undefined;
+  if (typeof getOptionValueSource !== "function") {
+    return undefined;
+  }
+
+  if (getOptionValueSource.call(command, "skipDaemon") === "cli") {
+    return false;
+  }
+  if (getOptionValueSource.call(command, "installDaemon") === "cli") {
+    return Boolean(opts.installDaemon);
+  }
+  return undefined;
+}
+
+/** Register the `setup` command as an onboarding alias. */
 export function registerSetupCommand(program: Command): void {
-  program
+  const command = program
     .command("setup")
-    .description("Create baseline config/workspace files; use --wizard for full onboarding")
+    .description("Alias for openclaw onboard")
     .addHelpText(
       "after",
       () =>
         `\n${theme.heading("Examples:")}\n` +
         `  ${theme.command("openclaw setup")}\n` +
-        `    ${theme.muted("Create config, workspace, and session folders.")}\n` +
-        `  ${theme.command("openclaw setup --wizard")}\n` +
         `    ${theme.muted("Run full onboarding for auth, models, Gateway, and channels.")}\n\n` +
         `${theme.muted("Docs:")} ${formatDocsLink("/cli/setup", "docs.openclaw.ai/cli/setup")}\n`,
     )
@@ -25,53 +54,109 @@ export function registerSetupCommand(program: Command): void {
       "Agent workspace directory (default: ~/.openclaw/workspace; stored as agents.defaults.workspace)",
     )
     .option("--wizard", "Run interactive onboarding", false)
+    .option(
+      "--baseline",
+      "Create baseline config/workspace/session folders without onboarding",
+      false,
+    )
+    .option(
+      "--reset",
+      "Reset config + credentials + sessions before running onboarding (workspace only with --reset-scope full)",
+    )
+    .option("--reset-scope <scope>", "Reset scope: config|config+creds+sessions|full")
     .option("--non-interactive", "Run onboarding without prompts", false)
     .option(
       "--accept-risk",
       "Acknowledge that agents are powerful and full system access is risky (required for --non-interactive)",
       false,
     )
-    .option("--mode <mode>", "Onboard mode: local|remote")
+    .option("--flow <flow>", "Onboard flow: quickstart|advanced|manual|import")
+    .option("--mode <mode>", "Onboard mode: local|remote");
+
+  registerOnboardAuthOptions(command);
+
+  command
+    .option("--gateway-port <port>", "Gateway port")
+    .option("--gateway-bind <mode>", "Gateway bind: loopback|tailnet|lan|auto|custom")
+    .option("--gateway-auth <mode>", "Gateway auth: token|password")
+    .option("--gateway-token <token>", "Gateway token (token auth)")
+    .option(
+      "--gateway-token-ref-env <name>",
+      "Gateway token SecretRef env var name (token auth; e.g. OPENCLAW_GATEWAY_TOKEN)",
+    )
+    .option("--gateway-password <password>", "Gateway password (password auth)")
+    .option("--tailscale <mode>", "Tailscale: off|serve|funnel")
+    .option("--tailscale-reset-on-exit", "Reset tailscale serve/funnel on exit")
+    .option("--install-daemon", "Install gateway service")
+    .option("--no-install-daemon", "Skip gateway service install")
+    .option("--skip-daemon", "Skip gateway service install")
+    .option("--daemon-runtime <runtime>", "Daemon runtime: node|bun")
+    .option("--skip-channels", "Skip channel setup")
+    .option("--skip-skills", "Skip skills setup")
+    .option("--skip-bootstrap", "Skip creating default agent workspace files")
+    .option("--skip-search", "Skip search provider setup")
+    .option("--skip-health", "Skip health check")
+    .option("--skip-ui", "Skip Control UI/TUI launch")
+    .option("--suppress-gateway-token-output", "Suppress token-bearing Gateway/UI output")
+    .option("--skip-hooks", "Accepted for onboard compatibility; hooks setup is skipped")
+    .option("--node-manager <name>", "Node manager for skills: npm|pnpm|bun")
     .option("--import-from <provider>", "Migration provider to run during onboarding")
     .option("--import-source <path>", "Source agent home for --import-from")
     .option("--import-secrets", "Import supported secrets during onboarding migration", false)
     .option("--remote-url <url>", "Remote Gateway WebSocket URL")
     .option("--remote-token <token>", "Remote Gateway token (optional)")
-    .action(async (opts, command) => {
+    .option("--json", "Output JSON summary", false)
+    .action(async (opts, commandRuntime) => {
       const { defaultRuntime } = await import("../../runtime.js");
       await runCommandWithRuntime(defaultRuntime, async () => {
-        const hasWizardFlags = hasExplicitOptions(command, [
-          "wizard",
-          "nonInteractive",
-          "acceptRisk",
-          "mode",
-          "importFrom",
-          "importSource",
-          "importSecrets",
-          "remoteUrl",
-          "remoteToken",
-        ]);
-        // Any onboarding-only flag means the user intended the wizard path even without --wizard.
-        if (opts.wizard || hasWizardFlags) {
-          const { setupWizardCommand } = await import("../../commands/onboard.js");
-          await setupWizardCommand(
-            {
-              workspace: opts.workspace as string | undefined,
-              nonInteractive: Boolean(opts.nonInteractive),
-              acceptRisk: Boolean(opts.acceptRisk),
-              mode: opts.mode as "local" | "remote" | undefined,
-              importFrom: opts.importFrom as string | undefined,
-              importSource: opts.importSource as string | undefined,
-              importSecrets: Boolean(opts.importSecrets),
-              remoteUrl: opts.remoteUrl as string | undefined,
-              remoteToken: opts.remoteToken as string | undefined,
-            },
-            defaultRuntime,
-          );
+        if (opts.baseline) {
+          const { setupCommand } = await import("../../commands/setup.js");
+          await setupCommand({ workspace: opts.workspace as string | undefined }, defaultRuntime);
           return;
         }
-        const { setupCommand } = await import("../../commands/setup.js");
-        await setupCommand({ workspace: opts.workspace as string | undefined }, defaultRuntime);
+        const installDaemon = resolveInstallDaemonFlag(commandRuntime, {
+          installDaemon: Boolean(opts.installDaemon),
+        });
+        const gatewayPort = parsePort(opts.gatewayPort);
+        const { setupWizardCommand } = await import("../../commands/onboard.js");
+        await setupWizardCommand(
+          {
+            workspace: opts.workspace as string | undefined,
+            nonInteractive: Boolean(opts.nonInteractive),
+            acceptRisk: Boolean(opts.acceptRisk),
+            flow: opts.flow as "quickstart" | "advanced" | "manual" | "import" | undefined,
+            mode: opts.mode as "local" | "remote" | undefined,
+            ...pickOnboardAuthOptionValues(opts as Record<string, unknown>),
+            reset: Boolean(opts.reset),
+            resetScope: opts.resetScope as ResetScope | undefined,
+            gatewayPort: gatewayPort ?? undefined,
+            gatewayBind: opts.gatewayBind as GatewayBind | undefined,
+            gatewayAuth: opts.gatewayAuth as GatewayAuthChoice | undefined,
+            gatewayToken: opts.gatewayToken as string | undefined,
+            gatewayTokenRefEnv: opts.gatewayTokenRefEnv as string | undefined,
+            gatewayPassword: opts.gatewayPassword as string | undefined,
+            tailscale: opts.tailscale as TailscaleMode | undefined,
+            tailscaleResetOnExit: Boolean(opts.tailscaleResetOnExit),
+            installDaemon,
+            daemonRuntime: opts.daemonRuntime as GatewayDaemonRuntime | undefined,
+            skipChannels: Boolean(opts.skipChannels),
+            skipSkills: Boolean(opts.skipSkills),
+            skipBootstrap: Boolean(opts.skipBootstrap),
+            skipSearch: Boolean(opts.skipSearch),
+            skipHealth: Boolean(opts.skipHealth),
+            skipUi: Boolean(opts.skipUi),
+            suppressGatewayTokenOutput: Boolean(opts.suppressGatewayTokenOutput),
+            skipHooks: Boolean(opts.skipHooks),
+            nodeManager: opts.nodeManager as NodeManagerChoice | undefined,
+            importFrom: opts.importFrom as string | undefined,
+            importSource: opts.importSource as string | undefined,
+            importSecrets: Boolean(opts.importSecrets),
+            remoteUrl: opts.remoteUrl as string | undefined,
+            remoteToken: opts.remoteToken as string | undefined,
+            json: Boolean(opts.json),
+          },
+          defaultRuntime,
+        );
       });
     });
 }