OpenClaw Onboarding Overview: CLI and macOS App Paths

OpenClaw offers two onboarding paths: one for the terminal and one for the macOS app. Both put inference first. They check for existing AI access, demand a successful completion, and only afterward launch OpenClaw to handle the rest of the setup. If a Gateway is reachable, properly configured, and its default agent already has a model assigned, onboarding is bypassed entirely and the standard agent UI loads. The terminal path additionally includes the full classic wizard for those who want granular configuration.

Which path should I use?

For most users, CLI onboarding is the recommended starting point. It runs on every platform and provides maximum control.

What onboarding configures

The guided inference stage covers exactly two things:

1. Model provider and auth, either detected access or a verified provider sign-in, API key, or token
2. Verified inference, a genuine completion on the effective model of the default agent

Once that completion succeeds, OpenClaw is free to set up the workspace, Gateway, Gateway service, channels, agents, plugins, and any other optional components.

The classic CLI wizard can also handle:

1. Channels (optional), built-in and bundled chat channels like Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, Telegram, WhatsApp, and others
2. Advanced Gateway controls, remote mode, network settings, and daemon options

CLI onboarding

Execute this in any terminal:

openclaw onboard

The guided flow looks for existing AI access, tests candidates in priority order, and moves on when one fails. When detection runs out, it surfaces OpenAI, Anthropic, xAI (Grok), Google, and OpenRouter first. More… lists the remaining providers grouped by category, with a secondary menu for regions, plans, and supported browser, device, API-key, or token methods. The model and credential are stored only after a successful completion, at which point OpenClaw starts to configure the workspace, Gateway, channels, agents, plugins, and other optional features. Skip for now ends the process without launching OpenClaw. There is no handoff to the classic flow within this path; exit and run openclaw onboard --classic whenever you prefer the classic wizard.

After inference succeeds, OpenClaw may pass channel configuration to a masked terminal wizard. It does not open guided or classic provider setup; exit OpenClaw and run openclaw onboard to switch the model provider or its authentication.

For comprehensive model/auth, channel, skill, remote Gateway, or import configuration, use openclaw onboard --classic. Appending --install-daemon also picks the classic flow and installs the background service in a single step. For conversational non-inference setup and repair, use openclaw openclaw. openclaw onboard --modern acts as a compatibility alias that goes through the same live-inference gate.

Full reference: Onboarding (CLI) CLI command docs: openclaw onboard

macOS app onboarding

Grab the macOS app from here and open it. When its local or remote Gateway is reachable and the default agent already has a model configured, onboarding is skipped, OpenClaw starts, and the standard agent UI appears right away.

For a new or incomplete Gateway, the first-run flow checks for existing AI access (Claude Code, Codex, or API keys), live-tests the most promising option, and commits it only after a genuine reply. If nothing is found, it falls back automatically and presents a verified manual API-key step. Sensitive credentials are entered with masked input. Once inference passes, OpenClaw launches and assists with the remaining configuration.

After setup, Gemini CLI remains available as an explicitly configured runtime, but Gemini CLI and Antigravity are not offered as detected inference routes. For guided setup, use Google AI Studio API-key or Vertex AI. The optional Gemini CLI runtime specifically demands an AI Studio API-key profile.

Full reference: Onboarding (macOS App)

Custom or unlisted providers

When your provider is absent from the list, run openclaw onboard --classic, select Custom Provider, and provide:

• 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 run side by side, each with its own endpoint ID.

Related

• Getting started
• CLI setup reference