mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-24 03:15:46 -06:00
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 <amp@ampcode.com>
This commit is contained in:
Peter Steinberger
committed by
GitHub
GitHub
parent
3bf3acbee5
commit
4f715eb37b
+15
-4
@@ -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
|
||||
|
||||
|
||||
+1
-1
@@ -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-<profile>`). 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-<profile>`). Dev-only reset: `openclaw gateway --dev --reset` wipes dev config, credentials, sessions, and workspace.
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
+18
-11
@@ -16,14 +16,21 @@ behavior and outputs, see [CLI setup reference](/start/wizard-cli-reference).
|
||||
|
||||
<Steps>
|
||||
<Step title="Reset (optional)">
|
||||
- `--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.
|
||||
|
||||
</Step>
|
||||
<Step title="Risk acknowledgement">
|
||||
@@ -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.
|
||||
|
||||
</Step>
|
||||
<Step title="Workspace">
|
||||
- Default `~/.openclaw/workspace` (configurable).
|
||||
- Seeds the workspace files needed for the agent bootstrap ritual.
|
||||
- Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
|
||||
|
||||
</Step>
|
||||
<Step title="Model/Auth">
|
||||
- **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.
|
||||
</Note>
|
||||
</Step>
|
||||
<Step title="Workspace">
|
||||
- Default `~/.openclaw/workspace` (configurable).
|
||||
- Seeds the workspace files needed for the agent bootstrap ritual.
|
||||
- Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
|
||||
|
||||
</Step>
|
||||
<Step title="Gateway">
|
||||
- Port (default **18789**), bind, auth mode, tailscale exposure.
|
||||
- Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
|
||||
|
||||
@@ -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
|
||||
|
||||
<Steps>
|
||||
<Step title="Existing config detection">
|
||||
- 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)
|
||||
|
||||
</Step>
|
||||
<Step title="Model and auth">
|
||||
- Full option matrix is in [Auth and model options](#auth-and-model-options).
|
||||
<Step title="Setup mode">
|
||||
- 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.
|
||||
|
||||
</Step>
|
||||
<Step title="Workspace">
|
||||
@@ -54,6 +63,10 @@ not install or modify anything on the remote host.
|
||||
the current value.
|
||||
- Workspace layout: [Agent workspace](/concepts/agent-workspace).
|
||||
|
||||
</Step>
|
||||
<Step title="Model and auth">
|
||||
- Full option matrix is in [Auth and model options](#auth-and-model-options).
|
||||
|
||||
</Step>
|
||||
<Step title="Gateway">
|
||||
- Prompts for port, bind, auth mode, and Tailscale exposure.
|
||||
|
||||
+31
-14
@@ -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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="QuickStart (defaults)">
|
||||
@@ -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
|
||||
|
||||
</Tab>
|
||||
<Tab title="Advanced (full control)">
|
||||
<Tab title="Manual setup (full control)">
|
||||
- Exposes every step: mode, workspace, gateway, channels, daemon, skills
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
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 <ENV_VAR>`.
|
||||
@@ -191,11 +201,18 @@ Local mode (default) walks through these steps:
|
||||
7. **Skills** - installs recommended skills and their optional dependencies.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
`--flow import` runs a detected migration flow (for example Hermes) in the
|
||||
|
||||
Reference in New Issue
Block a user