vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-07-09 15:59:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 22

feat(onboard): guided CLI onboarding with live AI verification and classic fallback (#101880)

Browse source 
* feat(onboard): guided CLI onboarding with live AI verification and classic fallback

Interactive `openclaw onboard` (and bare `openclaw` on a fresh install) now
runs a guided flow with macOS-app parity: detect existing AI access, live-test
candidates with a real completion before persisting anything, walk down the
ladder on failure with mapped reasons, and offer verified manual API-key entry
from installed provider manifests (masked input). In-flow escapes: classic
wizard, Crestodian chat, skip-AI. Classic wizard gains an optional post-auth
live verification step. `--classic`, `--modern`, and `--non-interactive`
contracts unchanged. Docs corrected for post-#99935 routing.

Closes #101851

* improve(onboard): quiet probe diagnostics in wizard TTY, carry risk ack into classic escape

Candidate live-tests during guided setup are probes: rename their run id and
lane to the existing probe conventions (logging/subsystem.ts console
suppression, command-queue quiet probe lanes) so expected failures stop
leaking raw diagnostics into the Clack UI; file diagnostics unchanged. The
classic-wizard escape now passes the already-collected risk acknowledgement
through instead of re-prompting in the same session.

* fix(onboard): quiet the session-derived setup-inference probe lane too

The live-test run enqueues on two lanes: the explicit probe lane and one
derived from its temp session key. Extend the shared quiet-probe predicate to
cover the derived lane so a failing candidate cannot leak lane-task
diagnostics into the wizard TTY.

* improve(onboard): suppress subsystem console output during wizard live tests

Provider-transport subsystem loggers (model-fetch start/response, transport
errors) carry no run id, so probe suppression cannot catch them and a failing
candidate printed raw log lines into the Clack TTY. Reuse the TUI console
subsystem-filter seam via a finally-safe scoped helper around guided
activation and the classic live-verify; file logging is unchanged and the
gateway (macOS app) surface is unaffected.

* fix(onboard): never auto-replace a configured model when its live check fails

The re-run verification probe executes outside the configured workspace (setup
never runs workspace plugins), so a workspace-backed current model can fail
the check while working fine in the agent. Stop the auto ladder on an
existing-model failure and hand the decision to the manual stage instead of
silently persisting a different candidate as the default. Docs note the
fail-safe and the workspace caveat.

* feat(onboard): two-way switching between Crestodian chat and the menu wizards

From the chat, `open setup wizard`, `open classic wizard`, and `open channel
wizard for <channel>` hand off to the guided flow, the classic wizard, or the
masked `channels add` wizard after the chat TUI tears down (mirrors the
open-tui handoff; gateway surface gets a text pointer instead). The hosted
channel wizard no longer dead-ends at sensitive steps — it offers the switch
and remembers the channel. New read-only `channel info <channel>` operation
and ring-zero action surface label, blurb, configured state, and the real
docs URL from channel-setup discovery so the assistant can explain Slack or
Telegram prerequisites instead of guessing; both prompts instruct it to use
them. `channels add --channel <id>` now preselects the channel. Docs cover
the interchangeable flows.

* fix(onboard): avoid param reassignment in open-setup handoff

* improve(onboard): separate ask-about vs connect intent in channel prompt guidance

Live test showed the agent detouring an explicit connect request through
channel_info because the guidance said to consult it first. Both prompts now
distinguish asking about a channel (channel info + docs link) from asking to
connect (connect right away).

* fix(channels): mark channel token entry as sensitive input

The shared single-token prompt lacked sensitive:true, so terminal wizards
echoed pasted channel tokens and the Crestodian chat bridge (which refuses
plain-text secrets based on this flag) hosted the Telegram token step in
visible chat. Found live-testing the chat-to-wizard switch; pre-existing on
main but load-bearing for the masked-wizard contract this PR documents.

* fix(onboard): restore terminal state around the guided flow's TUI launch

Mirror the classic finalize handoff so the chat TUI never inherits the wizard
prompter's raw/paused terminal state on the default first-run path.

* fix(channels): type the token prompter mock for the sensitive-flag assertion

* fix(gateway): map the TUI-only open-setup action to none for app clients

Engine-side surface gating already prevents open-setup replies on the gateway
surface; this keeps the client-visible action enum stable even if that gate
ever regresses. (Reviewed with the switching round; missed in its commit.)

* docs: regenerate docs map for onboarding page changes
This commit is contained in:
Peter Steinberger 2026-07-09 12:40:55 +01:00 • committed by GitHub
parent a0267273d0
commit e2a112a556
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
39 changed files with 2227 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/cli/crestodian.md
View file

@ -15,7 +15,7 @@ Crestodian is OpenClaw's local setup, repair, and configuration helper. It stays
Running `openclaw` with no subcommand routes based on config state:
- Config missing, or exists with no authored settings (empty, or only `$schema`/`meta` keys): starts classic onboarding.
- Config missing, or exists with no authored settings (empty, or only `$schema`/`meta` keys): starts guided onboarding with live AI verification.
- Config exists but fails validation: starts Crestodian.
- Config exists and is valid: opens the normal agent TUI (against a reachable configured Gateway, or locally if none is reachable). Use `/crestodian` inside the TUI, or run `openclaw crestodian` directly, to reach Crestodian.
@ -23,7 +23,9 @@ Running `openclaw crestodian` always starts Crestodian explicitly, regardless of
Noninteractive bare `openclaw` (no TTY) exits with a short message instead of printing root help: it points to non-interactive onboarding on a fresh install, to `openclaw crestodian --message "status"` when config is invalid, or to `openclaw agent --local ...` when config is valid.
`openclaw onboard --modern` starts Crestodian as the modern onboarding preview. Plain `openclaw onboard` keeps classic onboarding.
`openclaw onboard --modern` starts Crestodian directly. Plain `openclaw onboard`
starts guided onboarding; `openclaw onboard --classic` opens the full
step-by-step wizard.
## What Crestodian shows
@ -72,6 +74,12 @@ create agent work workspace ~/Projects/work
models
configure model provider
set default model openai/gpt-5.5
channels
channel info slack
connect slack
open setup wizard
open classic wizard
open channel wizard for slack
plugins list
plugins search slack
plugin install clawhub:openclaw-codex-app-server
@ -96,10 +104,27 @@ Approval is given in your own words: unambiguous replies ("yes", "sure", "go ahe
Applied writes are recorded in `~/.openclaw/audit/crestodian.jsonl`. Discovery is not audited; only applied operations and writes are.
Channel setup can run as a hosted conversation when the host supports masked
input. The local Crestodian TUI does not accept sensitive wizard answers;
instead it directs you to `openclaw channels add --channel <channel>`, whose
interactive prompts mask credentials.
Channel setup can run as a hosted conversation until it reaches a secret. The
local Crestodian TUI does not accept sensitive wizard answers because terminal
chat input is visible. It offers `open channel wizard` immediately, carrying
the selected channel into the masked terminal wizard; you can also run
`openclaw channels add --channel <channel>` later.
### Switching to the menu wizards
The local chat can hand control back to any terminal menu flow:
```text
open setup wizard
open classic wizard
open channel wizard for slack
channel info slack
```
`open setup wizard` opens guided onboarding. `open classic wizard` opens the
full classic setup. `open channel wizard for <channel>` opens masked channel
setup after the chat TUI closes. Use `channel info <channel>` first for the
channel label, setup state, prerequisites summary, and docs link.
Model-provider setup uses the same provider/auth and default-model steps as
`openclaw onboard`. In the local Crestodian TUI, approval exits the chat shell,

50
docs/cli/onboard.md
View file

@ -7,7 +7,10 @@ title: "Onboard"
# `openclaw onboard`
Guided setup for model auth, workspace, gateway, channels, skills, and health in one flow. `openclaw setup` is the same entry point; `openclaw setup --baseline` only writes the baseline config/workspace.
Guided setup that detects existing AI access, verifies it with a live completion,
and configures the workspace and local Gateway. `openclaw setup` is the same
entry point; `openclaw setup --baseline` only writes the baseline
config/workspace.
<CardGroup cols={2}>
<Card title="CLI onboarding hub" href="/start/wizard" icon="rocket">
@ -31,6 +34,7 @@ Guided setup for model auth, workspace, gateway, channels, skills, and health in
```bash
openclaw onboard
openclaw onboard --classic
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
@ -40,16 +44,52 @@ openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
- `--flow quickstart`: minimal prompts, auto-generates a gateway token.
- `--flow manual` (alias `advanced`): full prompts for port, bind, and auth.
- `--classic`: opens the full step-by-step wizard.
- `--flow quickstart`: opens the classic wizard with minimal prompts and
auto-generates a gateway token.
- `--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`), previews the plan, then applies after confirmation. Import only runs against a fresh OpenClaw setup - reset config, credentials, sessions, and workspace state first if any exist. Use [`openclaw migrate`](/cli/migrate) for dry-run plans, overwrite mode, reports, and exact mappings.
- `--modern` starts the Crestodian conversational setup/repair assistant instead of the classic flow.
- `--modern` starts the Crestodian conversational setup/repair assistant.
## Guided flow
Plain `openclaw onboard` starts the guided flow. It shows the security notice,
asks for a workspace, detects AI access already available through configured
models, API-key environment variables, and supported local CLIs, then tests the
recommended candidate with a real completion. If that candidate fails,
onboarding shows the reason and automatically tries the next usable candidate.
If automatic detection is exhausted, choose another detected candidate, enter
a provider API key in a masked prompt, open Crestodian chat, switch to the
classic wizard, or skip AI setup for now. A manual key is tested through the
same live completion path. OpenClaw persists the selected model, workspace, and
QuickStart Gateway settings only after the test succeeds; a failed candidate
does not replace the configured model or save the attempted credential.
Guided setup, the classic wizard, and Crestodian chat are interchangeable. The
guided flow offers chat and classic choices; inside Crestodian, use `open setup
wizard`, `open classic wizard`, or `open channel wizard for <channel>` to switch
back. Channel credentials are always collected in a masked terminal wizard.
On a configured install, running `openclaw onboard` again verifies the current
default model first, so the same flow acts as a verification and repair pass.
If that check fails, the configured model is never replaced automatically —
onboarding stops and asks how to continue. The check runs outside your
workspace, so a model provided by a workspace plugin can fail here while still
working in the agent.
Use `openclaw onboard --classic` for provider-specific auth, channels, skills,
remote Gateway setup, imports, or full Gateway controls. For conversational
setup and repair, run `openclaw crestodian`; `openclaw onboard --modern` opens
the same chat for onboarding. After configuring model/auth, the classic wizard
can optionally verify the default model with a live completion; verification
failure never blocks completion.
In an interactive terminal, bare `openclaw` (no subcommand) routes by config
state:
- If the active config file is missing or has no authored settings (empty or
metadata-only), it starts this classic onboarding flow.
metadata-only), it starts guided onboarding.
- If the config file exists but fails validation, it starts
[Crestodian](/cli/crestodian) for repair.
- If the config file is valid, it opens the normal agent TUI, either locally

7
docs/docs_map.md
View file

@ -1372,6 +1372,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- H2: What Crestodian shows
- H2: Examples
- H2: Operations and approval
- H3: Switching to the menu wizards
- H2: Setup bootstrap
- H2: AI conversation
- H3: CLI harness trust model
@ -1730,6 +1731,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- Headings:
- H1: openclaw onboard
- H2: Examples
- H2: Guided flow
- H2: Reset
- H2: Locale
- H2: Non-interactive setup
@ -8961,8 +8963,9 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- Route: /start/wizard
- Headings:
- H2: Locale
- H2: QuickStart vs Advanced
- H2: What onboarding configures
- H2: Guided default
- H2: Classic wizard: QuickStart vs Advanced
- H2: What classic onboarding configures
- H2: Add another agent
- H2: Full reference
- H2: Related docs

38
docs/start/onboarding-overview.md
View file

@ -7,15 +7,16 @@ title: "Onboarding overview"
sidebarTitle: "Onboarding Overview"
---
OpenClaw has two onboarding paths. Both configure auth, the Gateway, and
optional chat channels — they just differ in how you interact with the setup.
OpenClaw has terminal and macOS app onboarding. Both can detect existing AI
access, verify it with a live completion, and configure a workspace and Gateway.
The terminal flow also offers the full classic wizard for detailed setup.
## Which path should I use?
| | CLI onboarding | macOS app onboarding |
| -------------- | -------------------------------------- | --------------------------- |
| **Platforms** | macOS, Linux, Windows (native or WSL2) | macOS only |
| **Interface** | Terminal wizard | Guided UI + Crestodian chat |
| **Interface** | Guided, classic, and Crestodian chat | Guided UI + Crestodian chat |
| **Best for** | Servers, headless, full control | Desktop Mac, visual setup |
| **Automation** | `--non-interactive` for scripts | Manual only |
| **Command** | `openclaw onboard` | Launch the app |
@ -25,15 +26,19 @@ you the most control.
## What onboarding configures
Regardless of which path you choose, onboarding sets up:
Guided onboarding sets up:
1. **Model provider and auth** — API key, OAuth, or setup token for your chosen provider
1. **Model provider and auth** — detected access or a verified API key
2. **Workspace** — directory for agent files, bootstrap templates, and memory
3. **Gateway** — port, bind address, auth mode
4. **Channels** (optional) — built-in and bundled chat channels such as
4. **Gateway service** — installs, starts, and probes the local Gateway
The classic CLI wizard can additionally configure:
1. **Channels** (optional) — built-in and bundled chat channels such as
Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams,
Telegram, WhatsApp, and more
5. **Daemon** (optional) — background service so the Gateway starts automatically
2. **Advanced Gateway controls** — remote mode, network settings, and daemon choices
## CLI onboarding
@ -43,7 +48,20 @@ Run in any terminal:
openclaw onboard
```
Add `--install-daemon` to also install the background service in one step.
The guided flow detects existing AI access, live-tests candidates in order,
falls through on failure, and offers masked manual key entry. It saves the
model and credential only after a passing completion. From the same flow you
can open Crestodian chat, switch to `openclaw onboard --classic`, or skip AI
setup for now.
These CLI interfaces switch both ways: guided onboarding offers Crestodian and
the classic wizard, while Crestodian can open guided setup, classic setup, or a
masked channel wizard without making you restart the command manually.
Use `openclaw onboard --classic` for detailed model/auth, channel, skill,
remote Gateway, or import setup. Adding `--install-daemon` also selects the
classic flow and installs the background service in one step. Use `openclaw
onboard --modern` or `openclaw crestodian` for conversational setup and repair.
Full reference: [Onboarding (CLI)](/start/wizard)
CLI command docs: [`openclaw onboard`](/cli/onboard)
@ -62,8 +80,8 @@ Full reference: [Onboarding (macOS App)](/start/onboarding)
## Custom or unlisted providers
If your provider is not listed in onboarding, choose **Custom Provider** and
enter:
If your provider is not listed, open the classic wizard, choose **Custom
Provider**, and enter:
- Endpoint compatibility: OpenAI-compatible (`/chat/completions`), OpenAI Responses-compatible (`/responses`), Anthropic-compatible (`/messages`), or unknown (probes all three and auto-detects)
- Base URL and API key (API key is optional if the endpoint does not require one)

73
docs/start/wizard.md
View file

@ -12,19 +12,25 @@ openclaw onboard
```
CLI onboarding is the recommended terminal setup path on macOS, Linux, and
Windows (native or WSL2). It configures a local Gateway (or a connection to a
remote Gateway), plus channels, skills, and workspace defaults in one guided
flow. `openclaw setup` runs the same flow ([Setup](/cli/setup) covers the
`--baseline` config-only variant). Windows desktop users can also start from
[Windows Hub](/platforms/windows).
Windows (native or WSL2). By default it detects AI access already available on
the machine, verifies it with a real completion, and configures a workspace and
local Gateway. `openclaw setup` runs the same flow ([Setup](/cli/setup) covers
the `--baseline` config-only variant). Windows desktop users can also start
from [Windows Hub](/platforms/windows).
Provider sign-in, channel pairing, daemon install, and skill downloads can
extend a quick setup; optional steps can be skipped and revisited later with
`openclaw configure`.
The guided flow offers the classic wizard for provider sign-in, remote Gateway
setup, channel pairing, daemon controls, skills, and imports. You can also open
Crestodian chat or skip AI setup and return later.
Guided setup, the classic wizard, and Crestodian chat are interchangeable. The
guided flow offers chat and classic choices; inside Crestodian, use `open setup
wizard`, `open classic wizard`, or `open channel wizard for <channel>` to switch
back. Channel setup that needs secrets always continues in a masked terminal
wizard.
<Info>
Fastest first chat: skip channel setup entirely. Run `openclaw dashboard` and
chat in the browser through the Control UI. Docs: [Dashboard](/web/dashboard).
Fastest first chat: finish guided setup, run `openclaw dashboard`, and chat in
the browser through the Control UI. Docs: [Dashboard](/web/dashboard).
</Info>
## Locale
@ -52,18 +58,41 @@ openclaw agents add <name>
</Note>
<Tip>
Onboarding includes a web search step where you can pick a provider: Brave,
The classic wizard includes a web search step where you can pick a provider: Brave,
DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web
Search, Perplexity, SearXNG, or Tavily. Some need an API key; others are
key-free. Configure this later with `openclaw configure --section web`. Docs:
[Web tools](/tools/web).
</Tip>
## QuickStart vs Advanced
## Guided default
Onboarding opens with a choice between **QuickStart** (defaults) and
**Advanced** (full control). Pass `--flow quickstart` or `--flow advanced`
(alias `manual`) to skip the prompt.
Plain `openclaw onboard` follows this path:
1. Accept the security notice and choose the workspace.
2. Detect configured models, API-key environment variables, and supported local
AI CLIs.
3. Test the recommended candidate with a real completion. On failure, show the
reason and continue to the next usable candidate.
4. If detection is exhausted, try another detected candidate, enter a provider
API key in a masked prompt, open Crestodian chat, use the classic wizard, or
skip AI setup.
5. Persist the model, credential, workspace, and QuickStart Gateway settings
only after a passing test. Then install/start the Gateway service and probe
it for reachability.
Re-running the command on a configured installation tests the current default
model first, making the guided flow a verification and repair pass. A failing
check never replaces the configured model automatically; onboarding stops and
asks how to continue. Run `openclaw channels add` or `openclaw configure` for
later additions.
## Classic wizard: QuickStart vs Advanced
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.
<Tabs>
<Tab title="QuickStart (defaults)">
@ -87,7 +116,7 @@ Remote mode (`--mode remote`) always uses the advanced flow; it only
configures this machine to connect to a Gateway elsewhere and never installs
or changes anything on the remote host.
## What onboarding configures
## What classic onboarding configures
Local mode (default) walks through these steps:
@ -102,7 +131,9 @@ Local mode (default) walks through these steps:
instead of plaintext API key values; the referenced env var must already
be set, or onboarding fails fast. Interactive secret reference mode can
point at an environment variable or a configured provider ref (`file` or
`exec`), with a fast preflight check before saving.
`exec`), with a fast preflight check before saving. After model/auth setup,
the wizard offers an optional live completion test; a failure can return to
model/auth setup once or be ignored without blocking the rest of onboarding.
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
@ -130,11 +161,11 @@ config is invalid or contains legacy keys, onboarding asks you to run
`openclaw doctor` first.
</Note>
`--flow import` runs a detected migration flow (for example Hermes) instead of
fresh setup; see [Migrate](/cli/migrate) and the migration guides under
`--flow import` runs a detected migration flow (for example Hermes) in the
classic wizard instead of fresh setup; see [Migrate](/cli/migrate) and the migration guides under
[Install](/install/migrating-hermes). `openclaw onboard --modern` starts
[Crestodian](/cli/crestodian), a conversational setup/repair assistant, in
place of the classic wizard.
[Crestodian](/cli/crestodian), a conversational setup/repair assistant.
`openclaw crestodian` opens the same assistant directly.
## Add another agent