CLI Onboarding Wizard Reference: Step-by-Step Setup Guide

This page describes the step-by-step onboarding process, what it produces, and how it works internally.
For a guided example, check Onboarding (CLI). The complete CLI flag reference, covering every --flag, non-interactive usage examples, and provider-specific commands, is at openclaw onboard.

What the wizard does

Local mode (the default setting) guides you through:

• Model and authentication configuration (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and other provider-managed auth flows)
• Choosing a workspace location and generating bootstrap files
• Gateway configuration (port, bind address, authentication method, Tailscale)
• Channel and provider setup (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, plus other bundled or plugin channels)
• Optional web search provider selection
• Daemon installation (LaunchAgent, systemd user unit, or native Windows Scheduled Task with a Startup folder fallback)
• Health check execution
• Skills configuration

Remote mode prepares this machine to talk to a Gateway running elsewhere. Nothing is installed or changed on the remote host.

Local flow details

Existing config detection

• If ~/.openclaw/openclaw.json is found, you can pick Keep current values, Review and update, or Reset before setup.
• Running the wizard again will not delete anything unless you explicitly choose Reset or supply --reset.
• By default, the CLI --reset is set to config+creds+sessions; use --reset-scope full to also delete the workspace.
• When the configuration is invalid or contains legacy keys, the wizard stops and asks you to run openclaw doctor first.
• Reset moves data to Trash (never performs a direct delete) and offers these scopes:
  • Configuration only
  • Configuration plus credentials and sessions
  • Full reset (also removes the workspace)

Model and auth

• The complete options table is in Auth and model options.

Workspace

• Default value is ~/.openclaw/workspace (adjustable).
• Seeds the workspace with files needed for the first bootstrap run.
• On subsequent runs, an existing agent roster keeps its fleet-wide workspace unless you confirm the move. Non-interactive reruns issue a warning and keep the current value.
• Workspace structure: Agent workspace.

Gateway

• Asks for port, bind address, authentication mode, and Tailscale exposure.
• It is recommended to keep token authentication enabled even for loopback so local WebSocket clients must authenticate.
• In token mode, the interactive setup offers:
  • Generate and store plaintext token (default behavior)
  • Use SecretRef (opt in)
• In password mode, the interactive setup also supports plaintext or SecretRef storage.
• Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
  • Requires a non-empty environment variable in the onboarding process environment.
  • Cannot be used together with --gateway-token.
• Only disable authentication if you fully trust every process running locally.
• Non-loopback bind addresses still require authentication.

Channels

• WhatsApp: optional QR code login
• Telegram: bot token
• Discord: bot token
• Google Chat: service account JSON plus webhook audience
• Mattermost: bot token and base URL
• Signal: optional signal-cli installation and account configuration
• iMessage: imsg CLI path and Messages DB access; use an SSH wrapper when the Gateway is not on a Mac
• DM security: pairing is the default. The first DM sends a code; approve it with openclaw pairing approve <channel> <code> or use allowlists.

Web search

• Choose a provider (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily) or skip this step.
• Skip using --skip-search; reconfigure later with openclaw configure --section web.

Daemon install

• macOS: LaunchAgent
  • Requires a logged-in user session; for headless setups, use a custom LaunchDaemon (not provided).
• Linux and Windows via WSL2: systemd user unit
  • The wizard attempts loginctl enable-linger <user> so the gateway stays running after logout.
  • May ask for sudo (writes /var/lib/systemd/linger); it tries without sudo first.
• Native Windows: Scheduled Task is attempted first
  • If task creation is denied, OpenClaw falls back to a per-user Startup folder login item and starts the gateway immediately.
  • Scheduled Tasks are preferred because they offer better supervisor status.
• Runtime selection: Node is required because OpenClaw's canonical runtime state store uses node:sqlite.

Health check

• Starts the gateway if needed and runs openclaw health.
• openclaw status --deep adds the live gateway health probe to status output, including channel probes when supported.

Skills

• Reads available skills and checks their requirements.
• Lets you select a node manager: npm, pnpm, or bun.
• Installs optional dependencies for trusted bundled skills when the required installer is available.
• Skips unavailable Homebrew, uv, and Go installers, then groups the affected skills with manual setup instructions. Run openclaw doctor after installing the missing prerequisites.

Finish

• Summary and next steps, including options for iOS, Android, and macOS apps.

Note

When no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. If Control UI assets are missing, the wizard tries to build them; the fallback is pnpm ui:build (automatically installs UI dependencies).

Remote mode details

Remote mode prepares this machine to talk to a Gateway running elsewhere. Nothing is installed or changed on the remote host.

What you configure:

• Remote gateway URL (ws://... or wss://...)
• Token, password, or no authentication, matching the remote Gateway's settings

Discovery (optional)

If dns-sd (macOS) or avahi-browse (Linux) is available, onboarding offers to search for Bonjour/mDNS gateway beacons before falling back to manual URL entry. Wide-area DNS-SD discovery is also attempted when configured. Documentation: Gateway discovery, Bonjour.

Connection method

When a beacon is selected, choose direct WebSocket or an SSH tunnel:

• Direct: connects over wss:// and prompts to trust the discovered TLS fingerprint (trust-on-first-use pinning; only pinned if you accept).
• SSH tunnel: prints an ssh -N -L 18789:127.0.0.1:18789 <user>@<host> command to run first, then connects to the local tunnel endpoint.

Auth

Choose token (recommended), password, or no authentication, then optionally store it as a SecretRef instead of plaintext.

Note

When the gateway is loopback only and cannot be discovered, establish access manually through SSH tunneling or a tailnet. Plaintext ws:// is accepted for loopback, private IP literals, .local, and Tailnet *.ts.net URLs; other private DNS names require OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1.

Auth and model options

If a provider setup step fails during interactive onboarding (for instance, a CLI reuse option without a local sign in), the wizard displays the error and goes back to the provider picker rather than terminating. Explicit --auth-choice runs still fail quickly for automation purposes.

Anthropic API key

Uses ANTHROPIC_API_KEY if it exists, otherwise requests a key, then stores it for daemon use.

Anthropic Claude CLI

Preferred local path during interactive onboarding or configure; reuses an existing Claude CLI sign in when one is available.

OpenAI Code subscription (OAuth)

Browser based flow; paste code#state.

On a fresh setup with no primary model, agents.defaults.model is set to openai/gpt-5.6-sol via the Codex runtime.

OpenAI Code subscription (device pairing)

Browser pairing flow using a short lived device code.

On a fresh setup with no primary model, agents.defaults.model is set to openai/gpt-5.6-sol through the Codex runtime.

OpenAI API key

Uses OPENAI_API_KEY if present or asks for a key, then saves the credential in auth profiles.

On a fresh setup with no primary model, agents.defaults.model is set to openai/gpt-5.6; the bare direct API model ID resolves to the Sol tier.

Adding or reauthenticating OpenAI keeps an existing explicit primary model, including openai/gpt-5.5. If the account does not expose GPT 5.6, select openai/gpt-5.5 explicitly; OpenClaw does not silently downgrade it.

xAI (Grok) OAuth

Browser sign in for eligible SuperGrok or X Premium accounts. This is the recommended xAI path for most users. OpenClaw stores the resulting auth profile for Grok models, Grok web_search, x_search, and code_execution.

xAI (Grok) device code

Remote friendly browser sign in with a short code instead of a localhost callback. Use this from SSH, Docker, or VPS hosts.

xAI (Grok) API key

Prompts for XAI_API_KEY and sets up xAI as a model provider. Use this when you want an xAI Console API key instead of subscription OAuth.

OpenCode

Prompts for OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY) and lets you choose the Zen or Go catalog (a single API key covers both). Setup URL: opencode.ai/auth.

API key (generic)

Stores the key for you.

Vercel AI Gateway

Prompts for AI_GATEWAY_API_KEY. More detail: Vercel AI Gateway.

Cloudflare AI Gateway

Prompts for account ID, gateway ID, and CLOUDFLARE_AI_GATEWAY_API_KEY. More detail: Cloudflare AI Gateway.

MiniMax

Config is written automatically. The hosted default is MiniMax-M3; API key setup uses minimax/..., and OAuth setup uses minimax-portal/.... More detail: MiniMax.

StepFun

Config is written automatically for StepFun standard or Step Plan on China or global endpoints. Standard currently includes step-3.5-flash, and Step Plan also includes step-3.5-flash-2603. More detail: StepFun.

Synthetic (Anthropic-compatible)

Prompts for SYNTHETIC_API_KEY. More detail: Synthetic.

Ollama (Cloud and local open models)

The setup process first asks for Cloud + Local, Cloud only, or Local only. Cloud only relies on OLLAMA_API_KEY combined with https://ollama.com. When operating in host-backed mode, the system prompts for a base URL (defaulting to http://127.0.0.1:11434), lists the models it finds, and proposes defaults. Cloud + Local additionally verifies whether that Ollama host has a cloud sign-in. Further information is at Ollama.

Moonshot and Kimi Coding

Configuration files for Moonshot (Kimi K2) and Kimi Coding are generated automatically. See Moonshot AI (Kimi + Kimi Coding) for details.

Custom provider

Compatible with endpoints from OpenAI, OpenAI Responses, and Anthropic.

The interactive setup process uses the same API key storage options available in other provider key flows:

• Paste API key now (stored as plaintext)
• Use secret reference (an environment variable reference or a configured provider reference, validated beforehand)

During onboarding, image support is inferred for common vision model identifiers such as GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar. The system only prompts the user when the model name is not recognized.

Flags for non-interactive use:

• --auth-choice custom-api-key
• --custom-base-url
• --custom-model-id
• --custom-api-key (optional; defaults to CUSTOM_API_KEY)
• --custom-provider-id (optional)
• --custom-compatibility <openai|openai-responses|anthropic> (optional; default is openai)
• --custom-image-input / --custom-text-input (optional; overrides the inferred image input capability)

Skip

Authentication is left unconfigured.

How models behave:

• Either pick a default model from the detected options, or manually enter the provider and model.
• When onboarding starts from a provider authentication choice, the model selector automatically prioritizes that provider. For Volcengine and BytePlus, this preference also extends to their coding plan variants (volcengine-plan/*, byteplus-plan/*).
• If the filtered list for the preferred provider would be empty, the selector shows the full catalog instead of leaving the list blank.
• The wizard runs a model check and issues a warning when the configured model is unknown or lacks authentication.

Credential and profile locations:

• Authentication profiles (API keys plus OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Legacy OAuth import: ~/.openclaw/credentials/oauth.json

How credentials are stored:

• By default, onboarding saves API keys as plaintext values inside auth profiles.
• --secret-input-mode ref switches to reference mode instead of plaintext key storage. In interactive mode, you can pick between:
  • an environment variable reference (for instance keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • a configured provider reference (file or exec) using the provider alias and id
• Interactive reference mode runs a quick preflight check before saving.
  • Environment variable references: validates the variable name and that a non-empty value exists in the current onboarding environment.
  • Provider references: validates the provider configuration and resolves the requested id.
  • If the preflight check fails, onboarding shows the error and allows a retry.
• In non-interactive mode, --secret-input-mode ref only supports environment variable references.
  • Set the provider environment variable in the onboarding process environment.
  • Inline key flags (for example --openai-api-key) require that environment variable to be set; otherwise onboarding fails immediately.
  • For custom providers, non-interactive ref mode stores models.providers.<id>.apiKey as { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In that custom provider scenario, --custom-api-key requires CUSTOM_API_KEY to be set; otherwise onboarding fails immediately.
• Gateway authentication credentials support plaintext and SecretRef options during interactive setup:
  • Token mode: Generate/store plaintext token (default) or Use SecretRef.
  • Password mode: plaintext or SecretRef.
• Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
• Existing plaintext setups continue to work without changes.

Note

For headless and server environments: complete OAuth on a machine with a browser, then copy that agent's auth-profiles.json (for example ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, or the corresponding $OPENCLAW_STATE_DIR/... path) to the gateway host. credentials/oauth.json serves only as a legacy import source.

Outputs and internals

Common entries found in ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.skipBootstrap applies when --skip-bootstrap is supplied
• agents.defaults.model or models.providers (only with Minimax selected)
• tools.profile (local onboarding uses "coding" as default when nothing is set; any existing explicit values remain untouched)
• gateway.* (covers mode, bind, auth, tailscale)
• session.dmScope (onboarding keeps any explicit values and otherwise leaves the field empty, so the main default retains all direct messages across channels in the agent's ongoing primary session, which is the personal-agent default. For shared or multi-user inboxes, configure per-channel-peer; openclaw security audit suggests isolation when it identifies multi-user DM activity)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Channel allowlists (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) if you opt in during prompts; Discord and Slack also convert entered names into IDs
• skills.install.nodeManager
  • The setup --node-manager flag takes npm, pnpm, or bun.
  • Manual configuration can still set skills.install.nodeManager: "yarn" afterward.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

openclaw agents add writes agents.entries.* and, optionally, bindings.

WhatsApp credentials belong under ~/.openclaw/credentials/whatsapp/<accountId>/. Active sessions and transcripts live in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. The ~/.openclaw/agents/<agentId>/sessions/ directory holds legacy migration inputs and archive or support artifacts.

Note

Some channels ship as plugins. When you select them during setup, the wizard asks you to install the plugin (via npm or a local path) before configuring the channel.

Installed app recommendations

Once the model access check passes, classic interactive onboarding on macOS scans application names and bundle IDs without requesting macOS privacy permissions. It looks through the official plugin catalogs and ClawHub, then asks the configured model to discard false name matches and suggest relevant plugins or skills. Recommended matches are preselected; optional matches need an explicit pick.

The results screen lists the discovered applications and shows: "App names were matched using your configured model and ClawHub search." Set wizard.appRecommendations to false to turn off both this onboarding step and Gateway access to node app inventories. The scan does not run during quickstart or on non-macOS platforms.

Non-interactive setup

--non-interactive needs --accept-risk (acknowledging that agents are powerful and full system access carries risk):

openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

Complete flag reference and provider-specific examples: openclaw onboard, CLI automation.

Gateway wizard RPC

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Clients (the macOS app and Control UI) can render steps without needing to reimplement onboarding logic.

Signal setup behavior

• Pulls the correct release asset from the official signal-cli GitHub releases (native build, Linux x86-64 only)
• On other platforms (macOS, non-x64 Linux), uses Homebrew for installation instead
• Places the release-asset install under ~/.openclaw/tools/signal-cli/<version>/
• Creates channels.signal.transport.cliPath with kind: "managed-native" in the configuration
• Native Windows is not supported yet; run onboarding inside WSL2 to get the Linux install path

Related docs

• Onboarding hub: Onboarding (CLI)
• Automation and scripts: CLI Automation
• Command reference: openclaw onboard