Neura Market Logo

CLI Onboarding: Verify Inference, Then Let OpenClaw Finish

Learn the recommended CLI onboarding path for macOS, Linux, and Windows. It checks AI access, confirms with a real completion, then launches OpenClaw to set up your workspace and Gateway.

Read this when

  • Running or configuring CLI onboarding
  • Setting up a new machine
openclaw onboard

On macOS, Linux, and Windows (native or WSL2), the CLI onboarding path is the recommended way to get started from the terminal. It first checks for AI access already present on the machine, confirms it with an actual completion, and then launches OpenClaw to set up the workspace, Gateway, and any optional features. The same flow is executed by openclaw setup (Setup documents the --baseline config-only variant). Users on Windows desktop can alternatively begin from Windows Hub.

Inference is established first during guided onboarding. Available AI access gets detected, a real completion is required, and only after that does OpenClaw start to handle the remaining configuration. Selecting Skip for now leaves onboarding without launching OpenClaw.

For custom providers, remote Gateway configuration, channel pairing, daemon controls, skills, and imports, the classic wizard is still there. Invoke it explicitly with openclaw onboard --classic; the guided inference picker does not hand off to it. Once inference succeeds, open channel wizard for <channel> lets OpenClaw pass channel setup that involves secrets to a masked terminal wizard. Workspace skills and web search follow the same conversational pattern: configure skills and configure web search run those setup flows within the chat, while open search wizard routes credential entry to the masked terminal wizard. When running a local Gateway, configure gateway walks through port, bind, auth, and Tailscale settings but writes config without restarting; afterwards say restart gateway, or opt for open gateway wizard to handle masked terminal credential entry and then execute openclaw gateway restart. Remote Gateway mode stays an onboarding or openclaw configure selection rather than a hosted chat wizard.

Once onboarding has generated the default agent workspace, import memory can transfer detected local memory into it. This conversational import leaves config untouched, brings in no credentials or skills, requires no Gateway restart, and gives truthful per-source reports of partial or failed copies. To swap the model provider or its authentication, quit OpenClaw and run openclaw onboard; guided or classic provider flows are not opened by OpenClaw.

Info

To chat quickly: complete guided setup, run openclaw dashboard, and use the browser via the Control UI. Docs: Dashboard.

Locale

Fixed onboarding copy gets localized by the wizard. It pulls the first nonblank value from OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES, and LANG, in that sequence, defaulting to English when none are set. Supported locales: en, zh-CN, zh-TW.

OPENCLAW_LOCALE=zh-CN openclaw onboard
OPENCLAW_LOCALE=en openclaw onboard # Explicit English override

Regardless of locale, product names, commands, config keys, URLs, provider IDs, model IDs, and plugin/channel labels remain in English.

To adjust non-inference settings at a later time:

openclaw configure
openclaw agents add <name>

Note

Non-interactive mode is not implied by --json. For scripting, use --non-interactive (see CLI automation).

Tip

A web search step appears in the classic wizard, letting you choose a provider: Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, or Tavily. Some demand an API key; others work without one. Set this up later via openclaw configure --section web, or type configure web search in the OpenClaw chat to launch the same provider setup conversationally. Docs: Web tools.

Guided default

The path for plain openclaw onboard is as follows:

  1. Acknowledge the security notice.
  2. Look for configured models, API-key environment variables, supported local AI CLIs, and already installed tool-capable models from reachable Ollama or LM Studio servers on the Gateway host. This read-only pass downloads no model. Pi and OpenCode installs may also show up for context when they cannot act as the reusable inference route. Gemini CLI and Antigravity are not presented as detected setup routes.
  3. Run a real completion against the first detected candidate. If it fails, display the reason and move to the next usable candidate.
  4. When detection runs out, pick OpenAI, Anthropic, xAI (Grok), Google, or OpenRouter, or select More… for the rest. A second menu shows each provider's regions, plans, and supported browser, device, API-key, or token methods, all tested with the same real completion. Choose Skip for now to leave without launching OpenClaw.
  5. Save only the verified model route and any credential/plugin state it needs. Workspace and Gateway settings stay unchanged.
  6. Start OpenClaw with the verified model so it can handle workspace, Gateway, channels, agents, plugins, and the remaining optional setup.

On an already configured installation, re-running the command tests the current default model first, turning the guided flow into a verification and repair pass. A failed check never swaps the configured model automatically; onboarding halts and asks for direction. For later non-inference additions, run openclaw channels add or openclaw configure; use openclaw onboard for provider or auth route changes.

Classic wizard: QuickStart vs Advanced

Launch the full wizard with openclaw onboard --classic. It opens with a pick between QuickStart (defaults) and Advanced (full control). Pass --flow quickstart or --flow advanced (alias manual) to choose the classic flow and bypass that prompt.

QuickStart (defaults)

  • Local gateway, loopback bind
  • Workspace default (or existing workspace)
  • Gateway port 18789
  • Gateway auth Token (auto-generated, even on loopback)
  • Tool policy: tools.profile: "coding" for new setups (an existing explicit profile is preserved)
  • DM sessions: onboarding preserves an explicit session.dmScope and otherwise leaves it unset, so the "main" default keeps all direct messages across channels in the agent's rolling main session, the personal-agent default. For shared or multi-user inboxes, use "per-channel-peer"; openclaw security audit recommends isolation when it detects multi-user DM traffic. Details: CLI setup reference
  • Tailscale exposure Off
  • Telegram and WhatsApp DMs default to allowlist: Telegram asks for a numeric Telegram user ID, WhatsApp asks for a phone number

Advanced (full control)

  • Exposes every step: mode, workspace, gateway, channels, daemon, skills

Remote mode (--mode remote) always uses the advanced flow; it only configures this machine to connect to a Gateway elsewhere and never installs or changes anything on the remote host.

What classic onboarding configures

Local mode (default) walks through these steps:

  1. Model/Auth - choose how the provider handles authentication (API key, OAuth, or provider-specific manual auth), with Custom Provider available (OpenAI-compatible, OpenAI Responses-compatible, Anthropic-compatible, or Unknown auto-detect). Set a default model. Fresh OpenAI API-key and ChatGPT/Codex setups use openai/gpt-5.6-sol as the default. The bare direct-API openai/gpt-5.6 alias is still supported and maps to Sol. If you rerun setup, an existing explicit model is kept, including openai/gpt-5.5. When the account lacks GPT-5.6, select openai/gpt-5.5 explicitly. Security note: when this agent will execute tools or handle webhook/hook content, opt for the strongest latest-generation model you can and enforce strict tool policy, since weaker or older tiers are more vulnerable to prompt injection. For non-interactive runs, --secret-input-mode ref saves new credentials as env-backed refs; set the provider env var when adding a credential. Existing resolvable named profiles and their env, file, exec, or store refs are reused as-is without a new credential write or extra provider env var. Previously stored plaintext is not migrated; refer to Secrets management. Interactive secret reference mode can target an environment variable or a configured provider ref (file or exec), with a quick preflight check before saving. After model/auth setup, the wizard offers an optional live completion test; a failure can return to model/auth setup once or be ignored without blocking the rest of the classic wizard. Ignoring it does not enable OpenClaw; conversational setup still needs a passing inference check.
  2. Workspace - directory for agent files (default ~/.openclaw/workspace). Seeds bootstrap files.
  3. Gateway - port, bind address, auth mode, Tailscale exposure. In interactive token mode, choose plaintext token storage (default) or opt into a SecretRef. Non-interactive SecretRef path: --gateway-token-ref-env <ENV_VAR>.
  4. Channels - built-in and official plugin chat channels, including Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
  5. Daemon - installs a LaunchAgent (macOS), a systemd user unit (Linux/WSL2), or a native Windows Scheduled Task with a per-user Startup-folder fallback. If token auth is required and gateway.auth.token is SecretRef-managed, daemon install validates it but does not persist a resolved token into supervisor service environment metadata; an unresolved SecretRef blocks install with guidance. If both gateway.auth.token and gateway.auth.password are set while gateway.auth.mode is unset, install is blocked until you set the mode explicitly.
  6. Health check - starts the Gateway and verifies it is reachable.
  7. Skills - installs recommended skills and their optional dependencies.

Note

Re-running onboarding does not wipe anything unless you explicitly choose Reset (or pass --reset). CLI --reset defaults to config, credentials, and sessions; use --reset-scope full to also remove the workspace. If the config is invalid or contains legacy keys, onboarding asks you to run openclaw doctor first.

--flow import runs a detected migration flow (for example Hermes) in the classic wizard instead of fresh setup; see Migrate and the migration guides under Install. openclaw onboard --modern is a compatibility alias for OpenClaw. It uses the same inference gate as openclaw setup: verified inference starts the assistant, while an interactive failure returns to guided inference setup.

Add another agent

Use openclaw agents add <name> to create a separate agent with its own workspace, sessions, and auth profiles. Running without --workspace starts an interactive flow for name, workspace, auth, channels, and bindings - it is not the full openclaw onboard wizard.

What it sets:

  • agents.entries.*.name
  • agents.entries.*.workspace
  • agents.entries.*.agentDir

Notes:

  • Default workspace: ~/.openclaw/workspace-<agentId> (or under agents.defaults.workspace if that is set).
  • Add bindings to route inbound messages to this agent (onboarding can do this for you).
  • Non-interactive flags: --model, --agent-dir, --bind, --non-interactive.

Full reference

For detailed step-by-step behavior and config outputs, see CLI setup reference. For non-interactive examples, see CLI automation. For the full flag reference, see openclaw onboard.

1,651 words · updated Aug 17, 2026