Implementation:Openclaw Openclaw RunOnboardingWizard
| Knowledge Sources | |
|---|---|
| Domains | CLI, Configuration, Onboarding |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Concrete interactive onboarding wizard for the OpenClaw gateway, provided by the runOnboardingWizard function in src/wizard/onboarding.ts.
Description
runOnboardingWizard orchestrates the full first-run (or re-run) setup experience for OpenClaw. It walks the user through risk acknowledgement, flow selection (QuickStart vs Advanced), existing config handling, AI provider authentication, model selection, gateway network configuration, messaging channel setup, skills installation, hook configuration, and finalization (daemon install, dashboard launch). The function accumulates all changes into an in-memory OpenClawConfig object and writes it to disk at defined checkpoints.
The wizard supports both interactive and semi-automated operation. Many settings can be pre-supplied via the OnboardOptions parameter (e.g., --flow quickstart, --auth-choice apiKey, --skip-channels), which bypasses the corresponding prompts. The WizardPrompter abstraction decouples all user interaction from the terminal library, making the full flow testable with mock prompters.
Usage
Invoked by the openclaw onboard CLI command. Can also be called programmatically in integration tests by passing a mock WizardPrompter and custom OnboardOptions.
Code Reference
Source Location
- Repository: openclaw
- File:
src/wizard/onboarding.ts - Lines: 89-470
Signature
export async function runOnboardingWizard(
opts: OnboardOptions,
runtime: RuntimeEnv = defaultRuntime,
prompter: WizardPrompter,
): Promise<void>
Import
import { runOnboardingWizard } from "../wizard/onboarding.js";
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| opts | OnboardOptions |
Yes | Controls wizard behavior: flow selection (quickstart / advanced), auth choice, workspace path, skip flags (skipChannels, skipSkills, skipHealth, skipUi), gateway settings, and more. See src/commands/onboard-types.ts for the full type. |
| runtime | RuntimeEnv |
No (defaults to defaultRuntime) | Provides log, error, and exit functions for output and process control. Inject a mock for testing. |
| prompter | WizardPrompter |
Yes | Abstraction over terminal prompts (select, confirm, text, note, intro, outro, progress). The default implementation uses @clack/prompts. |
Outputs
| Name | Type | Description |
|---|---|---|
| (return) | Promise<void> |
Resolves when onboarding completes. The config file has been written to disk. If the user cancelled, a WizardCancelledError is thrown. If the config was invalid, the function calls runtime.exit(1) and returns early. |
Internal Flow
- Header and risk acknowledgement -- prints the wizard header, shows a security warning, and requires explicit user consent.
- Config snapshot -- reads the existing config file. If it exists but is invalid, shows issues and exits with a suggestion to run openclaw doctor.
- Flow selection -- prompts for QuickStart vs Advanced (or uses opts.flow). Remote mode forces Advanced.
- Existing config handling -- if a config exists, offers keep / modify / reset. Reset can clear config only, config + credentials + sessions, or everything including the workspace.
- Gateway defaults -- computes QuickstartGatewayDefaults from the existing config (port, bind, auth mode, Tailscale mode).
- Gateway reachability probe -- checks whether a local (and optionally remote) gateway is already reachable via WebSocket.
- Mode selection -- local vs remote gateway. Remote mode delegates to promptRemoteGatewayConfig and returns early.
- Workspace directory -- prompts for or uses the default workspace path (
~/openclaw). - Auth provider -- prompts for authentication choice (OAuth, API key, Claude CLI, etc.) via promptAuthChoiceGrouped, then applies it via applyAuthChoice.
- Model selection -- prompts for a default model via promptDefaultModel if auth choice was interactive.
- Gateway configuration -- delegates to configureGatewayForOnboarding for port, bind, auth, and Tailscale settings.
- Channel setup -- delegates to setupChannels (see SetupChannels implementation).
- Config checkpoint -- writes the config file and ensures the workspace directory and session files exist.
- Skills setup -- delegates to setupSkills unless opts.skipSkills is true.
- Hooks setup -- configures internal hooks (e.g., session memory on /new) via setupInternalHooks.
- Finalization -- applies wizard metadata, writes the final config, and delegates to finalizeOnboardingWizard for daemon installation, dashboard launch, and optional TUI launch.
Usage Examples
Basic Usage
import { runOnboardingWizard } from "../wizard/onboarding.js";
import { createClackPrompter } from "../wizard/clack-prompter.js";
// Interactive onboarding with default options
await runOnboardingWizard(
{ flow: "quickstart" },
defaultRuntime,
createClackPrompter(),
);
Non-Interactive / CI Usage
import { runOnboardingWizard } from "../wizard/onboarding.js";
await runOnboardingWizard(
{
flow: "quickstart",
acceptRisk: true,
authChoice: "apiKey",
token: process.env.ANTHROPIC_API_KEY,
skipChannels: true,
skipSkills: true,
},
defaultRuntime,
nonInteractivePrompter,
);
Key Dependencies
| Dependency | Purpose |
|---|---|
| @clack/prompts | Default terminal UI for select, confirm, text, note prompts (via WizardPrompter) |
| src/config/config.js | Config file reading (readConfigFileSnapshot), writing (writeConfigFile), and port resolution |
| src/commands/auth-choice.js | Authentication provider selection and application |
| src/commands/onboard-channels.js | Channel setup delegation (setupChannels) |
| src/commands/onboard-helpers.js | Reset handling, gateway probing, wizard metadata |
| src/wizard/onboarding.finalize.js | Post-setup finalization (daemon, dashboard, TUI) |
| src/wizard/onboarding.gateway-config.js | Gateway network configuration prompts |