docs/start/wizard-cli-reference.md
This page covers step-by-step onboarding behavior, outputs, and internals.
For a walkthrough, see Onboarding (CLI). For the full CLI flag
reference (every --flag, non-interactive examples, provider-specific
commands), see openclaw onboard.
Local mode (default) walks you through:
Remote mode configures this machine to connect to a Gateway elsewhere. It does not install or modify anything on the remote host.
Remote mode configures this machine to connect to a Gateway elsewhere. It does not install or modify anything on the remote host.
What you set:
ws://... or wss://...)If a provider setup step fails in interactive onboarding (for example a CLI reuse option
without a local sign-in), the wizard shows the error and returns to the provider picker
instead of exiting. Explicit --auth-choice runs still fail fast for automation.
On a fresh setup with no primary model, sets `agents.defaults.model` to
`openai/gpt-5.6-sol` through the Codex runtime.
On a fresh setup with no primary model, sets `agents.defaults.model` to
`openai/gpt-5.6-sol` through the Codex runtime.
On a fresh setup with no primary model, sets `agents.defaults.model` to
`openai/gpt-5.6`; the bare direct-API model id resolves to the Sol tier.
Adding or reauthenticating OpenAI preserves 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.
Interactive onboarding supports the same API key storage choices as other provider API key flows:
- **Paste API key now** (plaintext)
- **Use secret reference** (env ref or configured provider ref, with preflight validation)
Onboarding infers image support for common vision model IDs (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar) and only asks when the model name is unknown.
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)
Model behavior:
volcengine-plan/*,
byteplus-plan/*).Credential and profile paths:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json~/.openclaw/credentials/oauth.jsonCredential storage mode:
--secret-input-mode ref enables reference mode instead of plaintext key storage.
In interactive setup, you can choose either:
keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })file or exec) with provider alias + id--secret-input-mode ref is env-backed only.
--openai-api-key) require that env var to be set; otherwise onboarding fails fast.ref mode stores models.providers.<id>.apiKey as { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.--custom-api-key requires CUSTOM_API_KEY to be set; otherwise onboarding fails fast.--gateway-token-ref-env <ENV_VAR>.Typical fields in ~/.openclaw/openclaw.json:
agents.defaults.workspaceagents.defaults.skipBootstrap when --skip-bootstrap is passedagents.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 (local onboarding defaults this to per-channel-peer when unset; existing explicit values are preserved)channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*skills.install.nodeManager
setup --node-manager flag accepts npm, pnpm, or bun.skills.install.nodeManager: "yarn" later.wizard.lastRunAtwizard.lastRunVersionwizard.lastRunCommitwizard.lastRunCommandwizard.lastRunModewizard.securityAcknowledgedAtopenclaw agents add writes agents.list[] and optional bindings.
WhatsApp credentials go under ~/.openclaw/credentials/whatsapp/<accountId>/.
Sessions are stored under ~/.openclaw/agents/<agentId>/sessions/.
--non-interactive requires --accept-risk (acknowledges that agents are
powerful and full system access is risky):
openclaw onboard --non-interactive --accept-risk \
--auth-choice apiKey \
--anthropic-api-key "$ANTHROPIC_API_KEY"
Full flag reference and provider-specific examples: openclaw onboard, CLI automation.
wizard.startwizard.nextwizard.cancelwizard.statusClients (macOS app and Control UI) can render steps without re-implementing onboarding logic.
signal-cli GitHub releases (native build, Linux x86-64 only)~/.openclaw/tools/signal-cli/<version>/channels.signal.cliPath in configopenclaw onboard