Use this file to discover all available pages before exploring further.
Onboarding (CLI)
CLI onboarding is the recommended way to set up OpenClaw on macOS,
Linux, or Windows (via WSL2; strongly recommended).
It configures a local Gateway or a remote Gateway connection, plus channels, skills,
and workspace defaults in one guided flow.
info
Fastest first chat: open the Control UI (no channel setup needed). Run
`openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
To reconfigure later:
openclaw configure
openclaw agents add <name>
note
`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
tip
CLI onboarding includes a web search step where you can pick a provider
such as Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search,
Ollama Web Search, Perplexity, SearXNG, or Tavily. Some providers require an
API key, while others are key-free. You can also configure this later with
`openclaw configure --section web`. Docs: [Web tools](/tools/web).
QuickStart vs Advanced
Onboarding starts with QuickStart (defaults) vs Advanced (full control).
* Local gateway (loopback)
* Workspace default (or existing workspace)
* Gateway port **18789**
* Gateway auth **Token** (auto‑generated, even on loopback)
* Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
* DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)
* Tailscale exposure **Off**
* Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
* Exposes every step (mode, workspace, gateway, channels, daemon, skills).
What onboarding configures
Local mode (default) walks you through these steps:
- Model/Auth — choose any supported provider/auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider
(OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
For non-interactive runs, stores env-backed refs in auth profiles instead of plaintext API key values.
In non-interactive mode, the provider env var must be set; passing inline key flags without that env var fails fast.
In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref ( or ), with a fast preflight validation before saving.
For Anthropic, interactive onboarding/configure offers Anthropic Claude CLI as the preferred local path and Anthropic API key as the recommended production path. Anthropic setup-token also remains available as a supported token-auth path.
- Workspace — Location for agent files (default ). Seeds bootstrap files.
- Gateway — Port, bind address, auth mode, Tailscale exposure.
In interactive token mode, choose default plaintext token storage or opt into SecretRef.
Non-interactive token SecretRef path:
--gateway-token-ref-env <ENV_VAR>
- Channels — built-in and bundled chat channels such as BlueBubbles, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
- Daemon — Installs a LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task with per-user Startup-folder fallback.
If token auth requires a token and is SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata.
If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
If both and are configured and is unset, daemon install is blocked until mode is set explicitly.
- Health check — Starts the Gateway and verifies it's running.
- Skills — Installs recommended skills and optional dependencies.
note
Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
If the config is invalid or contains legacy keys, onboarding asks you to run `openclaw doctor` first.
Remote mode only configures the local client to connect to a Gateway elsewhere.
It does not install or change anything on the remote host.
Add another agent
Use
openclaw agents add <name>
to create a separate agent with its own workspace,
sessions, and auth profiles. Running without
launches onboarding.
What it sets:
Notes:
- Default workspaces follow
~/.openclaw/workspace-<agentId>
- Add to route inbound messages (onboarding can do this).
- Non-interactive flags: , , , .
Full reference
For detailed step-by-step breakdowns and config outputs, see
CLI Setup Reference.
For non-interactive examples, see CLI Automation.
For the deeper technical reference, including RPC details, see
Onboarding Reference.
Related docs