Onboarding Wizard
Guidelines for using the onboarding wizard to configure OpenClaw manually or via guided flow.
The onboarding wizard is the **recommended** way to set up OpenClaw on macOS, Linux, or Windows (via WSL2; highly recommended). It guides you through configuring local or remote Gateway connections, channels, skills, and workspace defaults.
Main entry:
openclaw onboard
Fastest way to first chat: Open Control UI (no channel setup needed). Run
`openclaw dashboard` then chat in browser. Docs: Dashboard.
Subsequent reconfiguration:
openclaw configure
Recommended: Set Brave Search API key so agents can use `web_search`
(`web_fetch` works without key). Easiest way: `openclaw configure --section web`
It will store `tools.web.search.apiKey`. Docs: Web Tool.
Quick Start vs. Advanced Mode
The wizard starts in **Quick Start** (default settings) vs **Advanced** (full control).
**Quick Start** keeps defaults:
Local Gateway (loopback)
Default workspace (or existing)
Gateway port **18789**
Gateway auth **token** (auto-generated, even on loopback)
Tailscale exposure **off**
Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your number)
**Advanced** shows every step (mode, workspace, gateway, channels, daemon, skills).
What the Wizard Does
**Local Mode (Default)** guides you through:
Models/Auth (OpenAI Codex sub via OAuth, Anthropic API key (recommended) or setup-token (paste), plus options for MiniMax/GLM/Moonshot/AI Gateway)
Workspace location + bootstrap files
Gateway settings (port/bind/auth/Tailscale)
Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)
Daemon installation (LaunchAgent / systemd user unit)
Health checks
Skills (recommended)
**Remote Mode** only configures the local client to connect to a Gateway elsewhere. It **does not** install or change anything on the remote host.
To add more isolated agents (separate workspace + sessions + auth), use:
openclaw agents add '<name>'
Tip: `--json` does **not** mean non-interactive. Use `--non-interactive` (along with `--workspace`) for scripts.
Flow Details (Local)
1. Existing Config Detection
If `~/.openclaw/openclaw.json` exists, choose to **Keep / Modify / Reset**.
Rerunning the wizard **never** deletes anything unless you explicitly choose **Reset** (or pass `--reset`).
If the config is invalid or has 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 (removes workspace too)
2. Models/Auth
**Anthropic API Key (Recommended)**: Uses `ANTHROPIC_API_KEY` if present or prompts for key, then saves for daemon use.
**Anthropic OAuth (Claude Code CLI)**: On macOS, wizard checks keychain item "Claude Code-credentials" (choose "Always Allow" to avoid launchd block); on Linux/Windows, it reuses `~/.claude/.credentials.json` if present.
**Anthropic Token (Paste setup-token)**: Run `claude setup-token` on any machine and paste the token.
**OpenAI Codex Sub (Codex CLI)**: If `~/.codex/auth.json` exists, wizard can reuse it.
**OpenAI Codex Sub (OAuth)**: Browser flow; paste `code#state`.
Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when unset or `openai/*`.
**OpenAI API Key**: Uses `OPENAI_API_KEY` if present or prompts, saving to `~/.openclaw/.env` for launchd.
**OpenCode Zen (Multi-model proxy)**: Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at opencode.ia/auth).
**API Keys**: Stores keys for you.
**Vercel AI Gateway (Multi-model proxy)**: Prompts for `AI_GATEWAY_API_KEY`. More info: Vercel AI Gateway
**MiniMax M2.1**: Config written automatically. More info: MiniMax
**Synthetic (Anthropic-Compatible)**: Prompts for `SYNTHETIC_API_KEY`. More info: Synthetic
**Moonshot (Kimi K2)**: Config written automatically.
**Kimi Coding**: Config written automatically. More info: Moonshot AI
**Skip**: No auth configured yet.
Chooses default model from detected options (or manual entry).
Wizard runs model checks and warns if mode is unknown or auth is missing.
OAuth creds stored in `<code1>~/.openclaw/credentials/oauth.json</code1>`; Auth config in `<code2>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code2>`. More info: <link6>OAuth Concepts</link6>
3. Workspace
Defaults to `~/.openclaw/workspace` (configurable).
Generates workspace files for agent bootstrap launch ceremony.
Full workspace layout & backup guide: Agent Workspace
4. Gateway
Port, Bind, Auth Mode, Tailscale exposure.
Auth recommendation: Keep **token** even on loopback to ensure local WS clients must authenticate.
Only disable auth if you trust every local process.
Non-loopback binds require auth.
5. Channels
WhatsApp: Optional QR login.
Telegram: Bot token.
Discord: Bot token.
Google Chat: Service account JSON + webhook audience.
Mattermost (plugin): Bot token + Base URL.
Signal: Optional `signal-cli` install + account config.
iMessage: Local `imsg` CLI path + DB access.
DM Security: Defaults to Pairing mode. First DM sends a code; approve via `<code2>openclaw pairing approve <channel> <code>'</code2>` or use allowlist.
6. Daemon Installation
macOS: LaunchAgent. Requires logged-in user session; for headless, use custom LaunchDaemon.
Linux (and Windows via WSL2): systemd user unit. Wizard tries `<code1>loginctl enable-linger <user>'</code1>` to keep Gateway alive after logout.
May prompt for sudo (writing to `/var/lib/systemd/linger`); tries without sudo first.
**Runtime Choice:** Node (recommended; needed for WhatsApp/Telegram). Bun **not recommended**.
7. Health Checks
Starts Gateway (if needed) and runs `openclaw health`.
Tip: `openclaw status --deep` adds Gateway health probe to status output.
8. Skills (Recommended)
Reads available skills and checks prerequisites.
Choose a Node manager: **npm / pnpm** (Bun not recommended).
Installs optional dependencies (some via Homebrew on macOS).
9. Completion
Summary + Next steps, including iOS/Android/macOS apps.
If no GUI detected, wizard prints SSH port forwarding instructions for Control UI instead of opening browser.
If Control UI assets are missing, wizard tries to build them; fallback is `pnpm ui:build`.
Remote Mode
Remote mode configures the local client to connect to a Gateway elsewhere.
What you need to set:
Remote Gateway URL (`ws://...`)
Token if remote Gateway requires auth (recommended)
Notes:
No remote installation or daemon changes performed.
If Gateway is loopback-only, use SSH tunnel or tailnet.
Discovery tips: macOS: Bonjour (`dns-sd`); Linux: Avahi (`avahi-browse`)
Adding Another Agent
Use `<code1>openclaw agents add <name>'</code1>` to create a separate agent with its own workspace, sessions, and auth. Running without `<code2>--workspace</code2>` starts the wizard.
It sets:
`agents.list[].name`
`agents.list[].workspace`
`agents.list[].agentDir`
Notes:
Default workspace follows `<code1>~/.openclaw/workspace-<agentId>'</code1>`.
Add `bindings` to route inbound messages (wizard can do this).
Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
Non-Interactive Mode
Use `--non-interactive` for automation or scripted onboarding:
openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Add `--json` for machine-readable summary.
Z.AI Example:
openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$Z_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Vercel AI Gateway Example:
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
Moonshot Example:
openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Synthetic Example:
openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
OpenCode Zen Example:
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) Example:
openclaw agents add work \ --workspace ~/.openclaw/workspace-work \ --model openai/gpt-5.2 \ --bind whatsapp:biz \ --non-interactive \ --json
Gateway Wizard RPC
Gateway exposes the wizard flow via RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). Clients (macOS app, Control UI) can render steps without reimplementing onboarding logic.
Signal Setup (signal-cli)
Wizard can install `signal-cli` (from GitHub releases):
Downloads appropriate release asset.
Stores in `<code1>~/.openclaw/tools/signal-cli/<version>/</code1>`.
Writes `channels.signal.cliPath` to your config.
Notes:
JVM builds require **Java 21**.
Native builds preferred if available.
Windows uses WSL2; install follows Linux flow within WSL.
What the Wizard Writes
Typical fields in `~/.openclaw/openclaw.json`:
`agents.defaults.workspace`
`agents.defaults.model` / `models.providers` (if Minimax)
`gateway.*` (mode, bind, auth, Tailscale)
`channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
Channel allowlists (Slack/Discord/Matrix/Teams) when opted-in (names resolved to IDs where possible).
`skills.install.nodeManager`
`wizard.*` (lastRunAt, lastRunVersion, lastRunCommit, lastRunCommand, lastRunMode)
`openclaw agents add` writes `agents.list[]` and optional `bindings`.
WhatsApp creds in `<code1>~/.openclaw/credentials/whatsapp/<accountId>/</code1>`. Sessions in `<code2>~/.openclaw/agents/<agentId>/sessions/</code2>`.
Some channels provided as plugins. When selected, the wizard prompts to install (npm or local path) before configuring.