openclaw/docs/reference/wizard.md

summary, read_when, title, sidebarTitle

summary	read_when	title	sidebarTitle
Full reference for the CLI onboarding wizard: every step, flag, and config field	Looking up a specific wizard step or flag Automating onboarding with non-interactive mode Debugging wizard behavior	Onboarding Wizard Reference	Wizard Reference

Onboarding Wizard Reference

This is the full reference for the openclaw onboard CLI wizard. For a high-level overview, see Onboarding Wizard.

Flow details (local mode)

- If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**. - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`). - If the config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing. - Reset uses `trash` (never `rm`) and offers scopes: - Config only - Config + credentials + sessions - Full reset (also removes workspace) - **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present. - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default). - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it. - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`. - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it. - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider. - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth). - **API key**: stores the key for you. - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`. - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) - **MiniMax M2.1**: config is auto-written. - More detail: [MiniMax](/providers/minimax) - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. - More detail: [Synthetic](/providers/synthetic) - **Moonshot (Kimi K2)**: config is auto-written. - **Kimi Coding**: config is auto-written. - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) - **Skip**: no auth configured yet. - Pick a default model from detected options (or enter provider/model manually). - Wizard runs a model check and warns if the configured model is unknown or missing auth. - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). - More detail: [/concepts/oauth](/concepts/oauth) Headless/server tip: complete OAuth on a machine with a browser, then copy `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) to the gateway host. - Default `~/.openclaw/workspace` (configurable). - Seeds the workspace files needed for the agent bootstrap ritual. - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) - Port, bind, auth mode, tailscale exposure. - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate. - Disable auth only if you fully trust every local process. - Non‑loopback binds still require auth. - [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) (plugin): 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 ` or use allowlists. - macOS: LaunchAgent - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped). - Linux (and Windows via WSL2): systemd user unit - Wizard attempts to enable lingering via `loginctl enable-linger ` so the Gateway stays up after logout. - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first. - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**. - Starts the Gateway (if needed) and runs `openclaw health`. - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway). - Reads the available skills and checks requirements. - Lets you choose a node manager: **npm / pnpm** (bun not recommended). - Installs optional dependencies (some use Homebrew on macOS). - Summary + next steps, including iOS/Android/macOS apps for extra features. If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).

Non-interactive mode

Use --non-interactive to automate or script onboarding:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

Add --json for a machine‑readable summary.

`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$ZAI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice ai-gateway-api-key \ --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice cloudflare-ai-gateway-api-key \ --cloudflare-ai-gateway-account-id "your-account-id" \ --cloudflare-ai-gateway-gateway-id "your-gateway-id" \ --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` ```bash openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ```

Add agent (non-interactive)

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway wizard RPC

The Gateway exposes the wizard flow over RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.

Signal setup (signal-cli)

The wizard can install signal-cli from GitHub releases:

• Downloads the appropriate release asset.
• Stores it under ~/.openclaw/tools/signal-cli/<version>/.
• Writes channels.signal.cliPath to your config.

Notes:

• JVM builds require Java 21.
• Native builds are used when available.
• Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.

What the wizard writes

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

• agents.defaults.workspace
• agents.defaults.model / models.providers (if Minimax chosen)
• gateway.* (mode, bind, auth, tailscale)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add writes agents.list[] and optional bindings.

WhatsApp credentials go under ~/.openclaw/credentials/whatsapp/<accountId>/. Sessions are stored under ~/.openclaw/agents/<agentId>/sessions/.

Some channels are delivered as plugins. When you pick one during onboarding, the wizard will prompt to install it (npm or a local path) before it can be configured.

Related docs

• Wizard overview: Onboarding Wizard
• macOS app onboarding: Onboarding
• Config reference: Gateway configuration
• Providers: WhatsApp, Telegram, Discord, Google Chat, Signal, BlueBubbles (iMessage), iMessage (legacy)
• Skills: Skills, Skills config