vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-07-15 11:46:05 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
75dfd3dc0972cd5eb4b869aae6158be427cdfd07
openclaw/docs/start/wizard.md
Peter Steinberger e2a112a556 feat(onboard): guided CLI onboarding with live AI verification and classic fallback (#101880) 
* 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
2026-07-09 12:40:55 +01:00

203 lines
8.8 KiB
Markdown
Raw Blame History

---
summary: "CLI onboarding: guided setup for gateway, workspace, channels, and skills"
read_when:
- Running or configuring CLI onboarding
- Setting up a new machine
title: "Onboarding (CLI)"
sidebarTitle: "Onboarding: CLI"
---
```bash
openclaw onboard
```
CLI onboarding is the recommended terminal setup path on macOS, Linux, and
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).
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: finish guided setup, run `openclaw dashboard`, and chat in
the browser through the Control UI. Docs: [Dashboard](/web/dashboard).
</Info>
## Locale
The wizard localizes fixed onboarding copy. Resolve order: `OPENCLAW_LOCALE`,
`LC_ALL`, `LC_MESSAGES`, `LANG`, then English. Supported locales: `en`,
`zh-CN`, `zh-TW`.
```bash
OPENCLAW_LOCALE=zh-CN openclaw onboard
```
Product names, commands, config keys, URLs, provider IDs, model IDs, and
plugin/channel labels stay in English regardless of locale.
To reconfigure later:
```bash
openclaw configure
openclaw agents add <name>
```
<Note>
`--json` does not imply non-interactive mode. For scripts, use `--non-interactive` (see [CLI automation](/start/wizard-cli-automation)).
</Note>
<Tip>
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>
## Guided default
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)">
- Local gateway, loopback bind
- Workspace default (or existing workspace)
- Gateway port **18789**
- Gateway auth **Token** (auto-generated, even on loopback)
- Tool policy: `tools.profile: "coding"` for new setups (an existing explicit profile is preserved)
- DM isolation: `session.dmScope: "per-channel-peer"` for new setups. Details: [CLI setup reference](/start/wizard-cli-reference#outputs-and-internals)
- Tailscale exposure **Off**
- 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)">
- Exposes every step: mode, workspace, gateway, channels, daemon, skills
</Tab>
</Tabs>
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 classic onboarding configures
Local mode (default) walks through these steps:
1. **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.
Security note: if this agent will run tools or process webhook/hook
content, prefer the strongest latest-generation model available and keep
tool policy strict - weaker or older tiers are easier to prompt-inject.
For non-interactive runs, `--secret-input-mode ref` stores env-backed refs
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. 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
into a SecretRef. Non-interactive SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
4. **Channels** - built-in and official plugin chat channels, including
Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams,
QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
5. **Daemon** - installs a LaunchAgent (macOS), a systemd user unit
(Linux/WSL2), or a native Windows Scheduled Task with a per-user
Startup-folder fallback.
If token auth is required and `gateway.auth.token` is SecretRef-managed,
daemon install validates it but does not persist a resolved token into
supervisor service environment metadata; an unresolved SecretRef blocks
install with guidance. If both `gateway.auth.token` and
`gateway.auth.password` are set while `gateway.auth.mode` is unset, install
is blocked until you set the mode explicitly.
6. **Health check** - starts the Gateway and verifies it is reachable.
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.
</Note>
`--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.
`openclaw crestodian` opens the same assistant directly.
## Add another agent
Use `openclaw agents add <name>` to create a separate agent with its own
workspace, sessions, and auth profiles. Running without `--workspace` starts
an interactive flow for name, workspace, auth, channels, and bindings - it is
not the full `openclaw onboard` wizard.
What it sets:
- `agents.list[].name`
- `agents.list[].workspace`
- `agents.list[].agentDir`
Notes:
- Default workspace: `~/.openclaw/workspace-<agentId>` (or under
`agents.defaults.workspace` if that is set).
- Add `bindings` to route inbound messages to this agent (onboarding can do this for you).
- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
## Full reference
For detailed step-by-step behavior and config outputs, see
[CLI setup reference](/start/wizard-cli-reference).
For non-interactive examples, see [CLI automation](/start/wizard-cli-automation).
For the full flag reference, see [`openclaw onboard`](/cli/onboard).
## Related docs
- CLI command reference: [`openclaw onboard`](/cli/onboard)
- Onboarding overview: [Onboarding overview](/start/onboarding-overview)
- macOS app onboarding: [Onboarding](/start/onboarding)
- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)
Reference in New Issue View Git Blame Copy Permalink