mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-16 12:16:37 +00:00
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
111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
---
|
|
summary: "Overview of OpenClaw onboarding options and flows"
|
|
read_when:
|
|
- Choosing an onboarding path
|
|
- Setting up a new environment
|
|
title: "Onboarding overview"
|
|
sidebarTitle: "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:
|
|
|
|
1. **Model provider and auth** — detected access or a verified API key
|
|
2. **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:
|
|
|
|
1. **Channels** (optional) — built-in and bundled chat channels such as
|
|
Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams,
|
|
Telegram, WhatsApp, and more
|
|
2. **Advanced Gateway controls** — remote mode, network settings, and daemon choices
|
|
|
|
## CLI onboarding
|
|
|
|
Run in any terminal:
|
|
|
|
```bash
|
|
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)](/start/wizard)
|
|
CLI command docs: [`openclaw onboard`](/cli/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)](/start/onboarding)
|
|
|
|
## 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.
|
|
|
|
## Related
|
|
|
|
- [Getting started](/start/getting-started)
|
|
- [CLI setup reference](/start/wizard-cli-reference)
|