Neura Market Logo

CLI Onboarding: Verify Inference and Set Up OpenClaw

This page explains the CLI onboarding process for macOS, Linux, and Windows users. It covers verifying AI inference and launching OpenClaw for workspace and Gateway setup.

Read this when

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

On macOS, Linux, and Windows (both native and WSL2), the recommended terminal setup method is CLI onboarding. It automatically finds any AI access already present on the system, confirms it works with an actual completion, then launches OpenClaw to set up the workspace, Gateway, and optional features. The same flow is executed by openclaw setup (see Setup for the --baseline configuration-only version). Windows desktop users can alternatively begin from Windows Hub.

The guided process prioritizes inference first. It locates existing AI access, demands a successful completion, and only afterwards starts OpenClaw to handle the remaining OpenClaw configuration. Selecting Skip for now ends onboarding without launching OpenClaw.

For custom providers, remote Gateway configuration, channel pairing, daemon controls, skills, and imports, the classic wizard is still available. Run it explicitly with openclaw onboard --classic; the guided inference picker does not forward to it. Once inference succeeds, OpenClaw can use open channel wizard for <channel> to delegate channel setup requiring secrets to a masked terminal wizard. To switch model providers or update authentication, quit OpenClaw and run openclaw onboard; OpenClaw does not start guided or classic provider flows.

Info

Quickest way to your first chat: complete guided setup, run openclaw dashboard, then talk in the browser via the Control UI. Documentation: Dashboard.

Locale

Fixed onboarding text is localized by the wizard. It takes the first non-empty value from OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES, and LANG in that sequence, defaulting to English. Supported locales are en, zh-CN, and zh-TW.

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

Product names, commands, configuration keys, URLs, provider IDs, model IDs, and plugin or channel labels remain in English regardless of locale.

To adjust non-inference settings later:

openclaw configure
openclaw agents add <name>

Note

--json does not mean non-interactive mode. For scripting, use --non-interactive (refer to CLI automation).

Tip

The classic wizard contains a web search step where you can select a provider: Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, or Tavily. Some require an API key; others are key-free. Configure this later with openclaw configure --section web. Documentation: Web tools.

Guided default

A plain openclaw onboard command follows this sequence:

  1. Acknowledge the security notice.
  2. Scan 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 scan never downloads a model. Gemini CLI, Antigravity, Pi, and OpenCode installations are also reported when they cannot serve as the reusable inference route for guided setup. Gemini and Antigravity cannot enforce the tool-free probe; Pi and OpenCode are whole-agent harnesses rather than setup inference routes.
  3. Test the first candidate found with an actual completion. On failure, display the reason and move to the next viable candidate.
  4. If no candidates remain, choose OpenAI, Anthropic, xAI (Grok), Google, or OpenRouter, or pick More… for the rest. Each provider's regions, plans, and supported browser, device, API-key, or token methods appear in a second menu and are tested with the same real completion. Select Skip for now to exit without launching OpenClaw.
  5. Persist only the verified model route and any credential or plugin state it requires. Workspace and Gateway settings stay unchanged.
  6. Launch OpenClaw with the verified model so it can configure the workspace, Gateway, channels, agents, plugins, and remaining optional setup.

Running the command again on an already configured installation tests the current default model first, turning the guided flow into a verification and repair pass. A failing check never automatically replaces the configured model; onboarding stops and asks for your next action. Use openclaw channels add or openclaw configure for later non-inference additions; use openclaw onboard for provider or auth route changes.

Classic wizard: QuickStart vs Advanced

Run openclaw onboard --classic to open the full wizard. It begins with a choice between QuickStart (defaults) and Advanced (full control). Pass --flow quickstart or --flow advanced (alias manual) to select 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 - pick a provider auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider (OpenAI-compatible, OpenAI Responses-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model. Fresh OpenAI API-key setup defaults to openai/gpt-5.6 (the bare direct-API id resolves to Sol); fresh ChatGPT/Codex setup defaults to openai/gpt-5.6-sol. Re-running setup preserves an existing explicit model, including openai/gpt-5.5. Select openai/gpt-5.5 explicitly if the account does not expose GPT-5.6. Security note: if this agent will run tools or process webhook/hook content, prefer the strongest latest-generation model available and keep tool policy strict - weaker or older tiers are easier to prompt-inject. For non-interactive runs, --secret-input-mode ref stores env-backed refs instead of plaintext API key values; the referenced env var must already be set, or onboarding fails fast. Interactive secret reference mode can point at an environment variable or a configured provider ref (file or exec), with a fast 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 unlock OpenClaw; conversational setup still requires 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

Running the onboarding process again will not delete any data unless you specifically pick Reset or provide --reset. By default, CLI --reset removes configuration, credentials, and sessions; to also delete the workspace, add --reset-scope full. When the configuration is corrupted or has outdated keys, onboarding will prompt you to execute openclaw doctor first.

When --flow import is used, a detected migration path (such as Hermes) runs inside the standard wizard rather than a clean configuration; refer to Migrate and the migration documentation under Install. The command openclaw onboard --modern acts as a backward-compatible alias for OpenClaw. It employs the same inference gate as openclaw setup: when verified inference succeeds, the assistant starts, and when it fails interactively, the process returns to guided inference setup.

Add another agent

To create a separate agent with its own workspace, sessions, and authentication profiles, run openclaw agents add <name>. If you omit --workspace, an interactive process begins that asks for a name, workspace, authentication, channels, and bindings, which is not the complete openclaw onboard wizard.

What gets configured:

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

Points to keep in mind:

  • The default workspace is ~/.openclaw/workspace-<agentId> (or located under agents.defaults.workspace if that variable is defined).
  • To have inbound messages sent to this agent, include bindings (the onboarding tool can handle this automatically).
  • Non-interactive flags available: --model, --agent-dir, --bind, --non-interactive.

Full reference

For a thorough explanation of each step and the resulting configuration, check the CLI setup reference. For examples of non-interactive usage, see CLI automation. The complete list of flags is documented in openclaw onboard.