ContextQMD
Back to Openclaw

Onboarding overview

docs/start/onboarding-overview.md

2026.7.12.8 KB
Original Source

OpenClaw has two onboarding paths. Both configure auth, the Gateway, and optional chat channels — they just differ in how you interact with the setup.

Which path should I use?

CLI onboardingmacOS app onboarding
PlatformsmacOS, Linux, Windows (native or WSL2)macOS only
InterfaceTerminal wizardGuided UI + Crestodian chat
Best forServers, headless, full controlDesktop Mac, visual setup
Automation--non-interactive for scriptsManual only
Commandopenclaw onboardLaunch the app

Most users should start with CLI onboarding — it works everywhere and gives you the most control.

What onboarding configures

Regardless of which path you choose, onboarding sets up:

  1. Model provider and auth — API key, OAuth, or setup token for your chosen provider
  2. Workspace — directory for agent files, bootstrap templates, and memory
  3. Gateway — port, bind address, auth mode
  4. Channels (optional) — built-in and bundled chat channels such as Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, Telegram, WhatsApp, and more
  5. Daemon (optional) — background service so the Gateway starts automatically

CLI onboarding

Run in any terminal:

bash
openclaw onboard

Add --install-daemon to also install the background service in one step.

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 in onboarding, 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.