From 4f715eb37befc03ec1df463f3cddff5287dac93c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 16 Aug 2026 21:15:39 -0700 Subject: [PATCH] docs: align classic onboarding setup flow (#124712) * docs(onboarding): align classic setup flow Amp-Thread-ID: https://ampcode.com/threads/T-01a00ae0-190d-718b-8a76-b75f3e8d1fae * docs(onboard): clarify import reset incompatibility Amp-Thread-ID: https://ampcode.com/threads/T-01a00ae0-190d-718b-8a76-b75f3e8d1fae --------- Co-authored-by: Amp --- docs/cli/onboard.md | 19 ++++++++++--- docs/help/faq.md | 2 +- docs/reference/wizard.md | 29 +++++++++++-------- docs/start/wizard-cli-reference.md | 41 +++++++++++++++++---------- docs/start/wizard.md | 45 ++++++++++++++++++++---------- 5 files changed, 92 insertions(+), 44 deletions(-) diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md index aa2b1bc0ec07..54620cc2f204 100644 --- a/docs/cli/onboard.md +++ b/docs/cli/onboard.md @@ -90,9 +90,9 @@ not overwrite the existing skill. `--gateway-port`, `--gateway-bind`, `--gateway-auth`, and `--tailscale` override the corresponding stored or default quickstart values; omitted options keep their current values. -- `--flow manual` (alias `advanced`): opens the classic wizard with full prompts - for port, bind, and auth. -- `--flow import`: runs a detected migration provider (for example Hermes via `--import-from hermes`) against a fresh setup. After confirmation, onboarding stages config, credentials, workspace files, memory, and skills under private temporary targets; imported inference must pass a live completion before workspace and agent state are promoted and configuration is committed. Failure or cancellation before promotion leaves the live target untouched. External activation steps that cannot be rolled back, such as Codex plugin installation, run afterward and remain retryable from the migration report. Reset config, credentials, sessions, and workspace state first if any exist. Use [`openclaw migrate`](/cli/migrate) for dry-run plans, overwrite mode, verified backups, reports, and exact mappings. +- `--flow manual` (alias `advanced`): opens the classic wizard's **Manual + setup** flow with full prompts for port, bind, and auth. +- `--flow import`: runs a detected migration provider (for example Hermes via `--import-from hermes`) against a fresh setup. After confirmation, onboarding stages config, credentials, workspace files, memory, and skills under private temporary targets; imported inference must pass a live completion before workspace and agent state are promoted and configuration is committed. Failure or cancellation before promotion leaves the live target untouched. External activation steps that cannot be rolled back, such as Codex plugin installation, run afterward and remain retryable from the migration report. Migration import options (`--flow import`, `--import-from`, `--import-source`, and `--import-secrets`) cannot be combined with `--reset`; run the import without `--reset`. Use [`openclaw migrate`](/cli/migrate) for dry-run plans, overwrite mode, verified backups, reports, and exact mappings. - `--remote-url` and `--remote-token`: prefill the classic remote Gateway step and override stored remote values for this run. Changing the URL does not reuse stored credentials unless you also pass a token. The token stays masked in prompts and follows the wizard's existing plaintext or SecretRef storage choice. - `--modern` is a compatibility alias for the OpenClaw conversational setup assistant. It uses the same live-inference gate as `openclaw setup` and @@ -203,7 +203,18 @@ openclaw onboard --reset openclaw onboard --reset --reset-scope full ``` -`--reset` wipes state before running setup. `--reset-scope` controls how much: `config` (config only), `config+creds+sessions` (default when `--reset` is passed without a scope), or `full` (also resets the workspace). Workspace reset only happens with `--reset-scope full`. +`--reset` is a destructive pre-dispatch flag, not a choice in the classic +wizard's **Setup mode** menu. `--reset-scope` controls how much it removes: +`config` (config only), `config+creds+sessions` (default when `--reset` is +passed without a scope), or `full` (also resets the workspace). Before moving +state to Trash, onboarding validates TTY availability, the reset scope, auth +and Gateway options, migration import options, and the workspace target for a +full reset. Migration import options cannot be combined with `--reset`; run the +import without `--reset`. Non-interactive setup also requires `--accept-risk` before reset. +Interactive classic setup performs reset before showing its risk +acknowledgement, so invoking `--reset` can move state to Trash before you can +decline that prompt. After reset, the command runs guided, classic, or +non-interactive onboarding according to the other flags. ## Locale diff --git a/docs/help/faq.md b/docs/help/faq.md index 6feecc839035..3cb8a84b9427 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1003,7 +1003,7 @@ First-run Q&A - install, onboard, auth routes, subscriptions, initial failures - openclaw onboard --install-daemon ``` - Onboarding also offers **Reset** if it detects an existing config; see [Onboarding (CLI)](/start/wizard). If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (default `~/.openclaw-`). Dev-only reset: `openclaw gateway --dev --reset` wipes dev config, credentials, sessions, and workspace. + To reset and immediately re-run onboarding, pass `openclaw onboard --reset`; reset is a command flag, not a **Setup mode** menu choice. See [Onboarding (CLI)](/start/wizard). If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (default `~/.openclaw-`). Dev-only reset: `openclaw gateway --dev --reset` wipes dev config, credentials, sessions, and workspace. diff --git a/docs/reference/wizard.md b/docs/reference/wizard.md index 86a59eb6222b..97194fe0ab12 100644 --- a/docs/reference/wizard.md +++ b/docs/reference/wizard.md @@ -16,14 +16,21 @@ behavior and outputs, see [CLI setup reference](/start/wizard-cli-reference). - - `--reset` resets state before setup runs; without it, re-running onboarding - keeps existing config and reuses it as defaults. + - Reset is owned by the `--reset` command flag, not by the interactive + **Setup mode** menu. Without it, re-running onboarding keeps existing + config and reuses it as defaults. - `--reset-scope` controls what `--reset` removes: `config` (config file only), `config+creds+sessions` (default), or `full` (also removes the workspace). - - If the config file is invalid, onboarding stops and tells you to run - `openclaw doctor` first, then re-run setup. - - Reset moves state to Trash (never deletes directly). + - Before reset, the command validates TTY availability and rejectable CLI + options, including the full-reset workspace target. Non-interactive setup + also requires `--accept-risk` at this point. + - Migration import options (`--flow import`, `--import-from`, + `--import-source`, and `--import-secrets`) cannot be combined with + `--reset`; run the import without `--reset`. + - Interactive classic setup moves state to Trash (never deletes directly) + before showing its risk acknowledgement. Declining that later prompt + cancels setup but does not undo the reset. @@ -35,6 +42,12 @@ behavior and outputs, see [CLI setup reference](/start/wizard-cli-reference). - Interactive runs get a confirm prompt instead of the flag; declining cancels setup. + + + - Default `~/.openclaw/workspace` (configurable). + - Seeds the workspace files needed for the agent bootstrap ritual. + - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) + - **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. @@ -84,12 +97,6 @@ behavior and outputs, see [CLI setup reference](/start/wizard-cli-reference). is only a legacy import source. - - - Default `~/.openclaw/workspace` (configurable). - - Seeds the workspace files needed for the agent bootstrap ritual. - - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) - - - Port (default **18789**), bind, auth mode, tailscale exposure. - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate. diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md index c08e61b4a90b..71aaf8dcda18 100644 --- a/docs/start/wizard-cli-reference.md +++ b/docs/start/wizard-cli-reference.md @@ -16,8 +16,8 @@ commands), see [`openclaw onboard`](/cli/onboard). Local mode (default) walks you through: -- Model and auth setup (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and more provider-owned auth flows) - Workspace location and bootstrap files +- Model and auth setup (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and more provider-owned auth flows) - Gateway settings (port, bind, auth, Tailscale) - Channels and providers (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and other bundled or plugin channels) - Web search provider (optional) @@ -31,19 +31,28 @@ not install or modify anything on the remote host. ## Local flow details - - - If `~/.openclaw/openclaw.json` exists, choose **Keep current values**, **Review and update**, or **Reset before setup**. - - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`). - - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove the workspace. - - If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing. - - Reset moves state to Trash (never deletes directly) and offers scopes: - - Config only - - Config + credentials + sessions - - Full reset (also removes the workspace) - - - - - Full option matrix is in [Auth and model options](#auth-and-model-options). + + - With no configured default model, the menu contains **QuickStart + (recommended)** (default) followed by **Manual setup**. + - With a configured default model, **Keep existing model config** appears + first and becomes the default, followed by **QuickStart (recommended)** + and **Manual setup**. + - Each detected migration source adds an **Import from <source>** choice + after those setup choices. Explicit import flags dispatch the import + directly and skip this menu. + - Re-running the wizard does not wipe anything unless you pass `--reset`. + Reset is a command flag, not a setup-mode choice. + - `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to + also remove the workspace. Before moving state to Trash, the command + validates TTY availability and rejectable CLI options. Non-interactive + setup also requires `--accept-risk` before reset. Interactive classic + setup performs reset before showing its risk acknowledgement; declining + that prompt does not undo the reset. + - Migration import options (`--flow import`, `--import-from`, + `--import-source`, and `--import-secrets`) cannot be combined with + `--reset`; run the import without `--reset`. + - Without `--reset`, invalid config or legacy keys stop the wizard and ask + you to run `openclaw doctor` before continuing. @@ -54,6 +63,10 @@ not install or modify anything on the remote host. the current value. - Workspace layout: [Agent workspace](/concepts/agent-workspace). + + + - Full option matrix is in [Auth and model options](#auth-and-model-options). + - Prompts for port, bind, auth mode, and Tailscale exposure. diff --git a/docs/start/wizard.md b/docs/start/wizard.md index 31fd64412e9a..3f5abaeefe81 100644 --- a/docs/start/wizard.md +++ b/docs/start/wizard.md @@ -114,12 +114,22 @@ asks how to continue. Run `openclaw channels add` or `openclaw configure` for later non-inference additions; use `openclaw onboard` for provider or auth route changes. -## Classic wizard: QuickStart vs Advanced +## Classic wizard setup modes -Run `openclaw onboard --classic` to open the full wizard. It starts with a -choice between **QuickStart** (defaults) and **Advanced** (full control). Pass -`--flow quickstart` or `--flow advanced` (alias `manual`) to select the classic -flow and skip that prompt. +Run `openclaw onboard --classic` to open the full wizard. Its **Setup mode** +menu is built from the current installation: + +- With no configured default model, **QuickStart (recommended)** is selected by + default, followed by **Manual setup**. +- With a configured default model, **Keep existing model config** appears first + and is selected by default, followed by **QuickStart (recommended)** and + **Manual setup**. +- Each detected migration source adds an **Import from <source>** choice + after the setup choices. + +Pass `--flow quickstart` or `--flow manual` (alias `advanced`) to select a +classic setup flow and skip that prompt. Import flags select the import flow +directly instead of showing a menu that could discard the requested import. @@ -133,13 +143,13 @@ flow and skip that prompt. - Telegram and WhatsApp DMs default to **allowlist**: Telegram asks for a numeric Telegram user ID, WhatsApp asks for a phone number - + - Exposes every step: mode, workspace, gateway, channels, daemon, skills -Remote mode (`--mode remote`) always uses the advanced flow; it only +Remote mode (`--mode remote`) always uses the manual flow; it only configures this machine to connect to a Gateway elsewhere and never installs or changes anything on the remote host. @@ -147,7 +157,8 @@ or changes anything on the remote host. Local mode (default) walks through these steps: -1. **Model/Auth** - pick a provider auth flow (API key, OAuth, or +1. **Workspace** - directory for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files. +2. **Model/Auth** - pick a provider auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider (OpenAI-compatible, OpenAI Responses-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model. @@ -171,7 +182,6 @@ Local mode (default) walks through these steps: model/auth setup once or be ignored without blocking the rest of the classic wizard. Ignoring it does not unlock OpenClaw; conversational setup still requires a passing inference check. -2. **Workspace** - directory for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files. 3. **Gateway** - port, bind address, auth mode, Tailscale exposure. In interactive token mode, choose plaintext token storage (default) or opt into a SecretRef. Non-interactive SecretRef path: `--gateway-token-ref-env `. @@ -191,11 +201,18 @@ Local mode (default) walks through these steps: 7. **Skills** - installs recommended skills and their optional dependencies. -Re-running onboarding does **not** wipe anything unless you explicitly choose -**Reset** (or pass `--reset`). CLI `--reset` defaults to config, credentials, -and sessions; use `--reset-scope full` to also remove the workspace. If the -config is invalid or contains legacy keys, onboarding asks you to run -`openclaw doctor` first. +Re-running onboarding does **not** wipe anything unless you pass `--reset`. +Reset is a command flag, not a **Setup mode** menu choice. It defaults to +config, credentials, and sessions; use `--reset-scope full` to also remove the +workspace. The command validates TTY availability and rejectable CLI options +before moving state to Trash; non-interactive setup also requires +`--accept-risk` first. Interactive classic setup performs reset before showing +its risk acknowledgement, and declining that prompt does not undo the reset. +Migration import options (`--flow import`, `--import-from`, `--import-source`, +and `--import-secrets`) cannot be combined with `--reset`; run the import +without `--reset`. +Without `--reset`, an invalid config or legacy keys make onboarding ask you to +run `openclaw doctor` first. `--flow import` runs a detected migration flow (for example Hermes) in the