Principle:Openclaw Openclaw Onboarding Wizard
| Knowledge Sources | |
|---|---|
| Domains | CLI, Configuration, Onboarding |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
An onboarding wizard is an interactive, guided setup flow that collects configuration from the user through sequential prompts, validates each input, and writes a complete configuration file at the end.
Description
First-run setup for a multi-channel AI gateway involves dozens of configuration decisions: which AI provider to authenticate with, what model to use, how to bind the gateway network interface, which messaging channels to connect, and how to manage workspace directories. Presenting all of these as raw flags or manual file edits would overwhelm new users and invite misconfiguration. An onboarding wizard solves this by walking the user through each decision in a logical sequence, offering sensible defaults, and validating inputs before persisting them.
The wizard pattern used here is built around a WizardPrompter abstraction that provides select, confirm, text, note, intro, and outro primitives. This abstraction decouples the wizard logic from any specific terminal UI library (the default implementation uses @clack/prompts), making the flow testable with mock prompters. The wizard accumulates configuration changes in an in-memory OpenClawConfig object and only writes it to disk at defined checkpoints, ensuring atomicity.
A key design feature is the dual-flow architecture: users choose between a QuickStart flow (which applies sensible defaults and asks minimal questions) and an Advanced/Manual flow (which exposes every configuration knob). Both flows share the same underlying logic; the QuickStart simply pre-fills answers and skips optional prompts. The wizard also handles existing configurations gracefully, offering to keep, modify, or reset previous values when a config file already exists. Security acknowledgement is required before proceeding, ensuring the user understands the implications of running an AI agent gateway.
Usage
Use the onboarding wizard pattern when:
- A CLI tool has a complex initial configuration with many interrelated settings.
- Users range from beginners (who want one-click setup) to experts (who need full control).
- Configuration must be validated before being persisted, not after.
- The setup flow needs to be testable without a real terminal (via prompter injection).
Theoretical Basis
The wizard follows a phased pipeline with conditional branching:
Phase 1 - Preamble:
print header -> intro -> require risk acknowledgement
read existing config snapshot
if invalid -> note issues, suggest `openclaw doctor`, exit
Phase 2 - Flow Selection:
prompt: QuickStart vs Advanced
if remote mode + quickstart -> force advanced
Phase 3 - Existing Config Handling:
if config exists -> prompt: keep / modify / reset
if reset -> clear config + optionally wipe creds/sessions/workspace
Phase 4 - Core Configuration:
prompt workspace directory
prompt auth provider (OAuth, API key, skip)
apply auth choice -> update config
prompt default model
configure gateway (port, bind, auth, Tailscale)
Phase 5 - Channel Setup:
delegate to setupChannels() (see Channel_Setup principle)
write config checkpoint
Phase 6 - Skills and Hooks:
prompt skills setup
configure internal hooks (e.g., session memory)
Phase 7 - Finalization:
apply wizard metadata
write final config
finalize (install daemon, open dashboard, launch TUI)
Key design decisions:
- Prompter abstraction: The WizardPrompter interface allows substituting the real terminal UI with a mock in tests, enabling full wizard flow testing without human interaction.
- Config accumulation: Configuration is built incrementally in memory rather than written after each prompt. This avoids partial config files if the user cancels midway.
- WizardCancelledError: If the user presses Ctrl-C or declines the risk acknowledgement, a typed WizardCancelledError is thrown, giving callers a clean way to distinguish cancellation from other errors.
- Checkpoint writes: The config is written to disk at two points (after channel setup and after finalization) to balance atomicity with recovery from late failures.