e2a112a556
* 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
4 KiB
| summary | read_when | title | sidebarTitle | ||
|---|---|---|---|---|---|
| Overview of OpenClaw onboarding options and flows |
|
Onboarding overview | Onboarding Overview |
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 | 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 |
Most users should start with CLI onboarding — it works everywhere and gives you the most control.
What onboarding configures
Guided onboarding sets up:
- Model provider and auth — detected access or a verified API key
- Workspace — directory for agent files, bootstrap templates, and memory
- Gateway — port, bind address, auth mode
- Gateway service — installs, starts, and probes the local Gateway
The classic CLI wizard can additionally configure:
- Channels (optional) — built-in and bundled chat channels such as Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, Telegram, WhatsApp, and more
- Advanced Gateway controls — remote mode, network settings, and daemon choices
CLI onboarding
Run in any terminal:
openclaw onboard
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)
CLI command docs: openclaw onboard
macOS app onboarding
Open the OpenClaw app. For local setup, the first-run flow starts the Gateway, detects existing AI access (Claude Code, Codex, Gemini CLI, or API keys), live-tests the best option, and saves it only after a real reply — falling back automatically and offering a verified manual API-key step when nothing is found. Sensitive credentials use masked input. Remote setup connects to an already-configured Gateway instead, and the same AI check runs against that Gateway.
Full reference: Onboarding (macOS App)
Custom or unlisted providers
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)
- Model ID and optional model alias
Multiple custom endpoints can coexist — each gets its own endpoint ID.