Neura Market Logo

OpenClaw Onboard CLI Reference: Step-by-Step Setup

Detailed reference for the openclaw onboard CLI wizard, covering each step, config outputs, and internals. For developers and admins automating or understanding CLI-based onboarding.

Read this when

  • You need detailed behavior for a specific openclaw onboard step
  • You are debugging onboarding results or integrating onboarding clients

This page describes the step-by-step onboarding flow, its outputs, and internal workings. For a guided example, refer to Onboarding (CLI). The complete CLI flag reference, covering every --flag, non-interactive usage examples, and provider-specific commands, is available at openclaw onboard.

What the wizard does

The default local mode guides you through:

  • Model and authentication configuration (Anthropic, OpenAI Code subscription OAuth, xAI, OpenCode, custom endpoints, and other provider-owned auth flows)
  • Choosing the workspace location and bootstrap files
  • Gateway settings, including port, bind, auth, and Tailscale
  • Channel and provider setup (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and 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 reach a Gateway hosted elsewhere. Nothing is installed or altered on the remote host.

Local flow details

Existing config detection

  • When ~/.openclaw/openclaw.json is present, you can pick Keep current values, Review and update, or Reset before setup.
  • Running the wizard again leaves everything intact unless you explicitly select Reset or supply --reset.
  • The CLI's --reset setting defaults to config+creds+sessions; adding --reset-scope full also deletes the workspace.
  • Invalid configuration or legacy keys halt the wizard, which then directs you to run openclaw doctor before proceeding.
  • Reset moves state to Trash (direct deletion never happens) and offers these scopes:
    • Config only
    • Config plus credentials and sessions
    • Full reset, which additionally removes the workspace

Model and auth

Workspace

  • Defaults to ~/.openclaw/workspace, which you can change.
  • Seeds the workspace files needed for first-run bootstrap.
  • On a rerun, an existing agent roster keeps its fleet-wide workspace unless you explicitly confirm the move. Non-interactive reruns issue a warning and retain the current value.
  • Workspace structure is documented in Agent workspace.

Gateway

  • Asks for port, bind, auth mode, and Tailscale exposure.
  • Recommended practice: keep token auth enabled even on loopback so local WS clients must authenticate.
  • In token mode, the interactive flow offers:
    • Generate/store plaintext token (default)
    • Use SecretRef (opt-in)
  • Password mode also supports plaintext or SecretRef storage during interactive setup.
  • The non-interactive token SecretRef path is --gateway-token-ref-env <ENV_VAR>.
    • A non-empty env var must exist in the onboarding process environment.
    • Combining it with --gateway-token is not allowed.
  • Disable auth only when you trust every local process completely.
  • Non-loopback binds still enforce auth.

Channels

  • WhatsApp: QR login is optional
  • Telegram: requires a bot token
  • Discord: requires a bot token
  • Google Chat: service account JSON plus webhook audience
  • Mattermost: bot token plus base URL
  • Signal: optional signal-cli install plus account config
  • iMessage: imsg CLI path plus Messages DB access; use an SSH wrapper when the Gateway runs off-Mac
  • DM security defaults to pairing. The first DM carries a code; approve it via openclaw pairing approve <channel> <code> or rely on allowlists.
  • Choose a provider (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily) or skip entirely.
  • Use --skip-search to skip this step; reconfigure later with openclaw configure --section web.

Daemon install

  • macOS: LaunchAgent
    • A logged-in user session is required; for headless setups, use a custom LaunchDaemon (not shipped).
  • Linux and Windows via WSL2: systemd user unit
    • The wizard attempts loginctl enable-linger <user> so the gateway survives logout.
    • It may prompt for sudo to write /var/lib/systemd/linger; the sudo-free path is tried first.
  • Native Windows: Scheduled Task takes priority
    • If task creation is denied, OpenClaw falls back to a per-user Startup-folder login item and launches the gateway immediately.
    • Scheduled Tasks remain the preferred option because they offer better supervisor status.
  • Runtime selection: Node is mandatory because OpenClaw's canonical runtime state store relies on node:sqlite.

Health check

  • Starts the gateway if it isn't running, then executes openclaw health.
  • openclaw status --deep appends the live gateway health probe to status output, including channel probes where supported.

Skills

  • Scans available skills and verifies their requirements.
  • Lets you select a node manager: npm, pnpm, or bun.
  • Installs optional dependencies for trusted bundled skills when the needed installer is present.
  • Unavailable Homebrew, uv, and Go installers are skipped, and the affected skills are grouped with manual setup instructions. After installing the missing prerequisites, run openclaw doctor.

Finish

  • Presents a summary and next steps, covering iOS, Android, and macOS app options.

Note

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

Remote mode details

Remote mode prepares this machine to reach a Gateway hosted elsewhere. Nothing is installed or altered on the remote host.

What you configure:

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

Discovery (optional)

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

Connection method

After selecting a beacon, choose between direct WebSocket or an SSH tunnel:

  • Direct: connects over wss:// and prompts you 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

Select token (recommended), password, or no auth, then optionally store it as a SecretRef rather than plaintext.

Note

When the gateway is restricted to loopback and can't be found on the network, set up SSH tunneling or a tailnet by hand. For loopback, private IP literals, .local, and Tailnet *.ts.net URLs, plaintext ws:// is allowed; other private-DNS names require OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1.

Auth and model options

During interactive onboarding, if a provider setup step fails (such as 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, however, still stop immediately for automation purposes.

Anthropic API key

When ANTHROPIC_API_KEY is available it gets used, otherwise a key is requested; the key is then stored for daemon use.

Anthropic Claude CLI

The preferred local path during interactive onboarding or configure; an existing Claude CLI sign-in gets reused when one is available.

OpenAI Code subscription (OAuth)

Browser-based flow; paste code#state.

On a system with no primary model configured, agents.defaults.model gets set to openai/gpt-5.6-sol via the Codex runtime.

OpenAI Code subscription (device pairing)

Browser pairing flow that uses a device code with a short lifespan.

If no primary model exists on a fresh setup, agents.defaults.model is assigned to openai/gpt-5.6-sol through the Codex runtime.

OpenAI API key

Uses OPENAI_API_KEY if it's there, otherwise a key is prompted for; the credential ends up saved in auth profiles.

When no primary model is set on a fresh setup, agents.defaults.model becomes openai/gpt-5.6-sol. The bare direct-API openai/gpt-5.6 alias is still supported and maps to the same tier.

When adding or re-authenticating OpenAI, an existing explicit primary model, including openai/gpt-5.5, is kept intact. If GPT-5.6 isn't exposed by the account, pick openai/gpt-5.5 manually; OpenClaw won't quietly downgrade it.

xAI (Grok) OAuth

Browser sign-in designed for eligible SuperGrok or X Premium accounts. For most users this is the recommended xAI route. OpenClaw saves the resulting auth profile for Grok models, Grok web_search, x_search, and code_execution.

xAI (Grok) device code

Browser sign-in that works remotely, using a short code rather than a localhost callback. From SSH, Docker, or VPS hosts, use this option.

xAI (Grok) API key

Asks for XAI_API_KEY and sets up xAI as a model provider. Choose this when an xAI Console API key is preferred over subscription OAuth.

OpenCode

Requests OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY) and gives you the choice between the Zen or Go catalog, with one API key covering both. Setup URL: opencode.ai/auth.

API key (generic)

The key gets stored on your behalf.

Vercel AI Gateway

Asks for AI_GATEWAY_API_KEY. Further reading: Vercel AI Gateway.

Cloudflare AI Gateway

Prompts for account ID, gateway ID, and CLOUDFLARE_AI_GATEWAY_API_KEY. Further reading: Cloudflare AI Gateway.

MiniMax

Configuration is written automatically. The hosted default is MiniMax-M3; with an API key it's minimax/..., and with OAuth it's minimax-portal/.... Further reading: MiniMax.

StepFun

Config gets written automatically for StepFun standard or Step Plan on either China or global endpoints. Standard presently includes step-3.5-flash, while Step Plan adds step-3.5-flash-2603. Further reading: StepFun.

Synthetic (Anthropic-compatible)

Prompts for SYNTHETIC_API_KEY. Further reading: Synthetic.

Ollama (Cloud and local open models)

Prompts for Cloud + Local, Cloud only, or Local only come first. Cloud only relies on OLLAMA_API_KEY combined with https://ollama.com. In host-backed modes, you are prompted for a base URL (defaulting to http://127.0.0.1:11434), then available models are discovered and defaults are suggested. Cloud + Local additionally verifies whether that Ollama host is signed in for cloud access. Further details: Ollama.

Moonshot and Kimi Coding

Configurations for Moonshot (Kimi K2) and Kimi Coding are written automatically. Further details: Moonshot AI (Kimi + Kimi Coding).

Custom provider

Compatible with OpenAI-compatible, OpenAI Responses-compatible, and Anthropic-compatible endpoints.

Interactive onboarding offers the same API key storage options as other provider API key flows:

  • Paste API key now (plaintext)
  • Use secret reference (env ref or configured provider ref, with preflight validation)

Image support is inferred during onboarding for common vision model IDs (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar); the question is only asked when the model name is not recognized.

Non-interactive flags:

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

Skip

Auth is left unconfigured.

Model behavior:

  • Either pick a default model from the detected options, or manually enter provider and model.
  • When onboarding begins from a provider auth choice, the model picker automatically prefers that provider. For Volcengine and BytePlus, that preference also covers their coding-plan variants (volcengine-plan/*, byteplus-plan/*).
  • If the preferred-provider filter would come up empty, the picker falls back to the full catalog rather than showing no models.
  • A model check runs during the wizard, warning when the configured model is unknown or lacks auth.

Credential and profile paths:

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

Credential storage mode:

  • Default onboarding behavior stores API keys as plaintext values in auth profiles.
  • --secret-input-mode ref switches to reference mode instead of plaintext key storage. In interactive setup, either choice is available:
    • environment variable ref (for example keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
    • configured provider ref (file or exec) with provider alias + id
  • Interactive reference mode runs a quick preflight validation before saving.
    • Env refs: variable name plus non-empty value are validated in the current onboarding environment.
    • Provider refs: provider config is validated and the requested id is resolved.
    • A failed preflight shows the error in onboarding and allows a retry.
  • In non-interactive mode, --secret-input-mode ref writes only env-backed references for new credentials.
    • Set the provider env var in the onboarding process environment when adding a new credential.
    • Inline key flags (for example --openai-api-key) require that env var to be set; otherwise onboarding fails fast.
    • Existing resolvable named auth profiles are reused unchanged, including existing env, file, exec, and store references; no new apiKey or keyRef is written and no additional provider env var is required.
    • For new custom-provider credentials, non-interactive ref mode stores models.providers.<id>.apiKey as { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
    • In that custom-provider case, --custom-api-key requires CUSTOM_API_KEY to be set; otherwise onboarding fails fast.
    • Existing plaintext profile credentials remain unchanged; reference mode does not migrate them. Run openclaw secrets configure --apply, then openclaw secrets audit --check. See Secrets management.
  • Gateway auth credentials support plaintext and SecretRef choices in 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 unchanged.

Note

Headless and server tip: 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 matching $OPENCLAW_STATE_DIR/... path) to the gateway host. credentials/oauth.json is only a legacy import source.

Outputs and internals

Typical fields in ~/.openclaw/openclaw.json:

  • agents.defaults.workspace
  • agents.defaults.skipBootstrap when --skip-bootstrap is passed
  • agents.defaults.model / models.providers (if Minimax chosen)
  • tools.profile (local onboarding defaults to "coding" when unset; existing explicit values are preserved)
  • gateway.* (mode, bind, auth, tailscale)
  • session.dmScope (onboarding preserves explicit values 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)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Channel allowlists (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) when you opt in during prompts; Discord and Slack also resolve entered names to IDs
  • skills.install.nodeManager
    • The setup --node-manager flag accepts npm, pnpm, or bun.
    • Manual config can still set skills.install.nodeManager: "yarn" later.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
  • wizard.securityAcknowledgedAt

openclaw agents add writes agents.entries.* and optional bindings.

WhatsApp credentials go under ~/.openclaw/credentials/whatsapp/<accountId>/. Active sessions and transcripts are stored in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. The ~/.openclaw/agents/<agentId>/sessions/ directory is used for legacy migration inputs and archive/support artifacts.

Note

Some channels are delivered as plugins. When selected during setup, the wizard prompts to install the plugin (npm or local path) before channel configuration.

Installed app recommendations

After the model access check succeeds, classic interactive onboarding on macOS scans application names and bundle IDs without requesting macOS privacy permissions. It searches the official plugin catalogs and ClawHub, then asks the configured model to reject false name matches and recommend relevant plugins or skills. Recommended matches are selected by default; optional matches require an explicit selection.

The results screen lists the detected applications and shows: "App names were matched using your configured model and ClawHub search." Set wizard.appRecommendations to false to disable both this onboarding step and Gateway access to node app inventories. The scan is not used in quickstart or non-macOS onboarding.

Non-interactive setup

--non-interactive requires --accept-risk (acknowledges that agents are powerful and full system access is risky):

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

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

Gateway wizard RPC

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

Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic.

Signal setup behavior

  • Downloads the appropriate release asset from the official signal-cli GitHub releases (native build, Linux x86-64 only)
  • On other platforms (macOS, non-x64 Linux), installs via Homebrew instead
  • Stores the release-asset install under ~/.openclaw/tools/signal-cli/<version>/
  • Writes channels.signal.transport.cliPath with kind: "managed-native" in config
  • Native Windows is not supported yet; run onboarding inside WSL2 to get the Linux install path
2,630 words · updated Aug 17, 2026