Use this file to discover all available pages before exploring further.

CLI setup reference

This page is the full reference for

text

openclaw onboard

. For the short guide, see Onboarding (CLI).

What the wizard does

Local mode (default) walks you through:

Model and auth setup (OpenAI Code subscription OAuth, Anthropic Claude CLI or API key, plus MiniMax, GLM, Ollama, Moonshot, StepFun, and AI Gateway options)
Workspace location and bootstrap files
Gateway settings (port, bind, auth, tailscale)
Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles, and other bundled channel plugins)
Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
Health check
Skills setup

Remote mode configures this machine to connect to a gateway elsewhere. It does not install or modify anything on the remote host.

Local flow details

Existing config detection

* If `~/.openclaw/openclaw.json` exists, choose Keep, Modify, or Reset. * Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`). * CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full` to also remove workspace. * If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing. * Reset uses `trash` and offers scopes: * Config only * Config + credentials + sessions * Full reset (also removes workspace)

Model and auth

* Full option matrix is in [Auth and model options](#auth-and-model-options).

Workspace

* Default `~/.openclaw/workspace` (configurable). * Seeds workspace files needed for first-run bootstrap ritual. * Workspace layout: [Agent workspace](/concepts/agent-workspace).

Gateway

* Prompts for port, bind, auth mode, and tailscale exposure. * Recommended: keep token auth enabled even for loopback so local WS clients must authenticate. * In token mode, interactive setup offers: * **Generate/store plaintext token** (default) * **Use SecretRef** (opt-in) * In password mode, interactive setup also supports plaintext or SecretRef storage. * Non-interactive token SecretRef path: `--gateway-token-ref-env `. * Requires a non-empty env var in the onboarding process environment. * Cannot be combined with `--gateway-token`. * Disable auth only if you fully trust every local process. * Non-loopback binds still require auth.

Channels

* [WhatsApp](/channels/whatsapp): optional QR login * [Telegram](/channels/telegram): bot token * [Discord](/channels/discord): bot token * [Google Chat](/channels/googlechat): service account JSON + webhook audience * [Mattermost](/channels/mattermost): bot token + base URL * [Signal](/channels/signal): optional `signal-cli` install + account config * [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook * [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access * DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve

text

` or use allowlists.

text


  
Daemon install

    * macOS: LaunchAgent
      * Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
    * Linux and Windows via WSL2: systemd user unit
      * Wizard attempts `loginctl enable-linger ` so gateway stays up after logout.
      * May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
    * Native Windows: Scheduled Task first
      * If task creation is denied, OpenClaw falls back to a per-user Startup-folder login item and starts the gateway immediately.
      * Scheduled Tasks remain preferred because they provide better supervisor status.
    * Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.
  
  
Health check

    * Starts 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 requirements.
    * Lets you choose node manager: npm, pnpm, or bun.
    * Installs optional dependencies (some use Homebrew on macOS).
  
  
Finish

    * Summary and next steps, including iOS, Android, and macOS app options.

text


note
  If 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 attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).

Remote mode details
Remote mode configures this machine to connect to a gateway elsewhere.
info
  Remote mode does not install or modify anything on the remote host.

What you set:

Remote gateway URL (
text
ws://...
)
Token if remote gateway auth is required (recommended)

note
  - If gateway is loopback-only, use SSH tunneling or a tailnet.
  - Discovery hints:
    * macOS: Bonjour (`dns-sd`)
    * Linux: Avahi (`avahi-browse`)

Auth and model options

  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  

Model behavior:

Pick default model from detected options, or enter provider and model manually.
Custom-provider onboarding infers image support for common model IDs and asks only when the model name is unknown.
When onboarding starts from a provider auth choice, the model picker prefers
that provider automatically. For Volcengine and BytePlus, the same preference
also matches their coding-plan variants (
text
volcengine-plan/*,
text
byteplus-plan/*
).
If that preferred-provider filter would be empty, the picker falls back to
the full catalog instead of showing no models.
Wizard runs a model check and warns if the configured model is unknown or missing auth.

Credential and profile paths:

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

Credential storage mode:

Default onboarding behavior persists API keys as plaintext values in auth profiles.
text
--secret-input-mode ref enables reference mode instead of plaintext key storage.
In interactive setup, you can choose either:

environment variable ref (for example 
text
keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }
)
configured provider ref (
text
file
 or 
text
exec
) with provider alias + id


Interactive reference mode runs a fast preflight validation before saving.

Env refs: validates variable name + non-empty value in the current onboarding environment.
Provider refs: validates provider config and resolves the requested id.
If preflight fails, onboarding shows the error and lets you retry.


In non-interactive mode, 
text
--secret-input-mode ref is env-backed only.

Set the provider env var in the onboarding process environment.
Inline key flags (for example 
text
--openai-api-key
) require that env var to be set; otherwise onboarding fails fast.
For custom providers, non-interactive 
text
ref
 mode stores 
text
models.providers.<id>.apiKey
 as 
text
{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }
.
In that custom-provider case, 
text
--custom-api-key
 requires 
text
CUSTOM_API_KEY
 to be set; otherwise onboarding fails fast.


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: 
text
--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//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 
text
~/.openclaw/openclaw.json
:

text
agents.defaults.workspace
text
agents.defaults.skipBootstrap
 when 
text
--skip-bootstrap
 is passed
text
agents.defaults.model
 / 
text
models.providers
 (if Minimax chosen)
text
tools.profile
 (local onboarding defaults to 
text
"coding"
 when unset; existing explicit values are preserved)
text
gateway.*
 (mode, bind, auth, tailscale)
text
session.dmScope
 (local onboarding defaults this to 
text
per-channel-peer
 when unset; existing explicit values are preserved)
text
channels.telegram.botToken
, 
text
channels.discord.token
, 
text
channels.matrix.*
, 
text
channels.signal.*
, 
text
channels.imessage.*
Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible)
text
skills.install.nodeManager

The 
text
setup --node-manager
 flag accepts 
text
npm
, 
text
pnpm
, or 
text
bun
.
Manual config can still set 
text
skills.install.nodeManager: "yarn"
 later.


text
wizard.lastRunAt
text
wizard.lastRunVersion
text
wizard.lastRunCommit
text
wizard.lastRunCommand
text
wizard.lastRunMode

text
openclaw agents add
 writes 
text
agents.list[]
 and optional 
text
bindings
.
WhatsApp credentials go under 
text
~/.openclaw/credentials/whatsapp/<accountId>/.
Sessions are stored under 
text
~/.openclaw/agents/<agentId>/sessions/
.
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.

Gateway wizard RPC:

text
wizard.start
text
wizard.next
text
wizard.cancel
text
wizard.status

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

Downloads the appropriate release asset
Stores it under 
text
~/.openclaw/tools/signal-cli/<version>/
Writes 
text
channels.signal.cliPath
 in config
JVM builds require Java 21
Native builds are used when available
Windows uses WSL2 and follows Linux signal-cli flow inside WSL

Related docs

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

OpenClaw Docs

CLI setup reference

What the wizard does

Local flow details

Existing config detection

Model and auth

Workspace

Gateway

Channels

Daemon install

Health check

Skills

Finish

note

Remote mode details

info

note

Auth and model options

note

Outputs and internals

note

Related docs