OpenClaw Onboarding Overview: Terminal and macOS App Flows
This page covers OpenClaw's onboarding options for both the terminal and macOS app, including the inference-first approach and CLI wizard. It helps users choose the best path based on their platform and control needs.
Read this when
- Choosing an onboarding path
- Setting up a new environment
OpenClaw provides onboarding for both the terminal and the macOS app. Both approaches prioritize inference first: they check for existing AI access, require a successful completion, and only then launch OpenClaw to handle the remaining configuration. If a reachable, configured Gateway already has a default agent with a configured model, onboarding is skipped and the normal agent UI opens directly. The terminal flow also includes the full classic wizard for more 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 OpenClaw | Inference setup, then OpenClaw |
| 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 begin with CLI onboarding, it works on all platforms and offers the most control.
What onboarding configures
The guided inference phase only sets up:
- Model provider and auth, detected access or a verified provider sign-in, API key, or token
- Verified inference, a real completion on the default agent's effective model
Once that completion succeeds, OpenClaw 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, and falls through on failure. If detection is exhausted, it shows OpenAI, Anthropic, xAI (Grok), Google, and OpenRouter first. More… contains the remaining providers in provider groups, with regions, plans, and supported browser, device, API-key, or token methods in a second menu. It saves the model and credential only after a passing completion, then starts OpenClaw to configure the workspace, Gateway, channels, agents, plugins, and other optional features. Skip for now exits without starting OpenClaw. There is no in-flow classic handoff; exit and run openclaw onboard --classic when you want the classic wizard instead.
After inference passes, OpenClaw can hand channel setup to a masked terminal wizard. It does not open guided or classic provider setup; exit OpenClaw 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 openclaw 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 OpenClaw 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, OpenClaw 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.