96f0983a85
* fix(crestodian): keep onboarding RPCs restart-safe * fix(profiles): isolate approval state migrations * fix(crestodian): bypass configured gateway setup * test(crestodian): type onboarding mocks * fix(onboarding): require inference before Crestodian * fix(onboarding): enforce verified inference handoff * fix(macos): reset setup on gateway endpoint edits * chore(i18n): refresh native source inventory * fix(gateway): keep socket on request cancellation * test(packaging): require workspace templates * fix(onboarding): bind setup to verified inference * fix(onboarding): align inference gate contracts * fix(crestodian): classify concurrent policy rejection * test(crestodian): expect registry restoration * fix(onboarding): bind setup to configured gateways * fix(codex): preserve startup phase deadlines * test(crestodian): match fail-closed policy ordering * test(onboarding): assert bound gateway handoff * fix(codex): bind runtime resolution to spawn cwd * test(crestodian): assert policy rejection order * fix(cli): preserve gateway routing across restarts * fix(macos): fail closed during gateway edits * test(macos): cover gateway route generation races * chore: keep release notes out of onboarding PR * fix(ci): refresh onboarding generated checks * style(swift): align gateway channel formatting * fix(ci): refresh plugin SDK surface budgets * fix(ci): resync native string inventory * refactor(swift): split gateway channel support * test(doctor): isolate plugin compatibility registry * test(macos): isolate gateway onboarding fixtures * test(macos): assert gateway lease health ordering * fix(codex): reconcile computer-use startup changes
4.8 KiB
summary, read_when, title, sidebarTitle
| summary | read_when | title | sidebarTitle | ||
|---|---|---|---|---|---|
| Overview of OpenClaw onboarding options and flows |
|
Onboarding overview | Onboarding Overview |
OpenClaw has terminal and macOS app onboarding. Both establish inference first: they detect existing AI access, require a live completion, and only then start Crestodian to configure the remaining setup. A reachable, configured Gateway whose default agent already has a configured model skips onboarding and opens the normal agent UI. 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 | Inference setup, then Crestodian | Inference setup, then Crestodian |
| 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
The guided inference phase establishes only:
- Model provider and auth — detected access or a verified API key
- Verified inference — a real completion on the default agent's effective model
After that completion passes, Crestodian can configure the workspace, Gateway, Gateway service, channels, agents, plugins, and other optional features.
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, then starts Crestodian
to configure the workspace, Gateway, channels, agents, plugins, and other
optional features. There is no pre-inference Crestodian, skip-AI path, or
in-flow classic handoff. Exit and run openclaw onboard --classic when you
want the classic wizard instead.
After inference passes, Crestodian can hand channel setup to a masked terminal
wizard. It does not open guided or classic provider setup; exit Crestodian and
run openclaw onboard to change the model provider or its authentication.
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 crestodian for conversational non-inference setup and repair. openclaw onboard --modern is a compatibility alias that uses the same live-inference
gate.
Full reference: Onboarding (CLI)
CLI command docs: openclaw onboard
macOS app onboarding
Open the OpenClaw app. If its configured local or remote Gateway is reachable and the default agent already has a configured model, the app skips onboarding and Crestodian and opens the normal agent UI immediately.
For a fresh or incomplete Gateway, the first-run flow detects existing AI access (Claude Code, Codex, 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. Once inference passes, Crestodian starts and helps configure the rest.
Gemini CLI remains available for normal agents after setup, but it is not offered for this inference gate because it cannot enforce the tool-free probe.
Full reference: Onboarding (macOS App)
Custom or unlisted providers
If your provider is not listed, run openclaw onboard --classic, 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.