Onboarding (CLI)

openclaw onboard

CLI onboarding is the recommended terminal setup path on macOS, Linux, and Windows (native or WSL2). On a fresh install, Quick start detects available AI access, waits for you to choose a connection, verifies your choice with a real completion, and opens the web dashboard with a foreground Gateway. Custom setup preserves the full guided flow. openclaw setup runs the same flow (Setup covers the --baseline config-only variant). Windows desktop users can also start from Windows Hub.

Guided onboarding verifies your selected connection before starting the Gateway and AI chat. Detected connections and supported providers share the same picker; failure or cancellation never automatically selects another provider. In local onboarding, Skip for now prepares the named agent's workspace and local Gateway configuration, then exits without starting either. Interrupted baseline setup resumes on the next run.

The classic wizard remains available for remote Gateway setup, channel pairing, daemon controls, skills, and imports. Run it explicitly with openclaw onboard --classic; the guided inference picker does not delegate into it. After inference passes, OpenClaw can use open channel wizard for <channel> to hand channel setup that needs secrets to a masked terminal wizard. Workspace skills and web search are configured the same conversational way: configure skills and configure web search host those setup flows in the chat, and open search wizard hands credential entry to the masked terminal wizard. For a local Gateway, configure gateway guides port, bind, auth, and Tailscale settings but saves config without restarting; say restart gateway afterward, or use open gateway wizard for masked terminal credential entry and then run openclaw gateway restart. Remote Gateway mode remains an onboarding or openclaw configure choice rather than a hosted chat wizard.

After onboarding has created the default agent workspace, import memory can copy detected local memory into it. This conversational import does not change config or import credentials or skills, needs no Gateway restart, and reports per-source partial or failed copies honestly. To change the model provider or its authentication, exit OpenClaw and run openclaw onboard; OpenClaw does not open guided or classic provider flows.

Locale

The wizard localizes fixed onboarding copy. It uses the first nonblank value from OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES, and LANG, in that order, then falls back to English. Supported locales: en, zh-CN, zh-TW.

OPENCLAW_LOCALE=zh-CN openclaw onboardOPENCLAW_LOCALE=en openclaw onboard # Explicit English override

Product names, commands, config keys, URLs, provider IDs, model IDs, and plugin/channel labels stay in English regardless of locale.

To reconfigure non-inference settings later:

openclaw configureopenclaw agents add <name>

Guided default

Fresh local interactive onboarding offers Quick start and Custom setup after a one-line pointer to the security guide. Quick start records the security acknowledgment; Custom setup shows the full security note and asks for confirmation. Quick start uses the default agent name main and full access, leaves telemetry consent unset, and skips memory import and app recommendations. Custom setup keeps the telemetry choice, agent name, access mode, and optional setup prompts. Both lanes require an explicit provider choice before a live completion or any provider installation, model selection, or credential write.

Quick start follows this path:

1. Choose Quick start after the one-line security pointer.
2. Detect configured models, API-key environment variables, supported local AI CLIs, and already installed tool-capable models from reachable Ollama or LM Studio servers on the Gateway host. This read-only pass never downloads a model. Pi and OpenCode installs may also be reported for context when they cannot serve as the reusable inference route. Gemini CLI and Antigravity are not offered as detected setup routes.
3. Choose the detected connection you want, or select a supported provider. Only that connection is tested with a real completion. If it fails, review the error and choose whether to retry, select another provider, or skip.
4. Choose More… for additional provider groups, including installable official plugins. Each provider's regions, plans, and supported browser, device, API-key, or token methods appear in a second menu. Plugin installation requires its capability review before the selected provider's setup continues. For an unlisted endpoint, choose Custom Provider (under More… when shown) and enter its base URL, optional API key, compatibility, and model ID. Custom setup runs in the local CLI on the Gateway host and verifies a real reply before saving the provider or replacing the active model. Choose Skip for now to prepare the local baseline and exit without starting the Gateway or AI chat. Choosing a provider through its manual setup keeps the Quick start defaults: agent name main, full access, telemetry consent unset, and a foreground Gateway after verification.
5. Save the verified route, prepare the agent workspace, and persist Gateway settings.
6. Start the Gateway in the foreground and open the browser dashboard. Press Ctrl+C to stop it; config persists. Use openclaw gateway install later for background operation, openclaw for the TUI, or openclaw dashboard to reopen the web UI.

The Quick start choice is not offered for configured installs, remote Gateway chat setup, non-interactive runs, or runs with --skip-ui or --tui.

Re-running the command on a configured installation offers the current default model first. Select it for a verification and repair pass. A failed check never replaces the configured model automatically; onboarding waits for your next choice. Run openclaw channels add or openclaw configure for later non-inference additions; use openclaw onboard for provider or auth route changes.

Classic wizard setup modes

Run openclaw onboard --classic to open the full wizard. Its Setup mode menu is built from the current installation:

• With no configured default model, QuickStart (recommended) is selected by default, followed by Manual setup.
• With a configured default model, Keep existing model config appears first and is selected by default, followed by QuickStart (recommended) and Manual setup.
• When a migration provider is available, Import from another agent appears after the setup choices. Selecting it opens provider-specific entries such as Import from Claude, Import from Codex, and Import from Hermes. Detected sources appear first with their paths; other available providers ask for a source path. Use Back from the provider list to return to Setup mode before an import begins.

Pass --flow quickstart or --flow manual (alias advanced) to select a classic setup flow and skip that prompt. Import flags select the import flow directly instead of showing a menu that could discard the requested import.

Remote mode (--mode remote) always uses the manual flow; it only configures this machine to connect to a Gateway elsewhere and never installs or changes anything on the remote host.

What classic onboarding configures

Local mode (default) walks through these steps:

1. Workspace - directory for agent files (default ~/.openclaw/workspace). Seeds bootstrap files.
2. Model/Auth - pick a provider auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider (OpenAI-compatible, OpenAI Responses-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model. Fresh OpenAI API-key and ChatGPT/Codex setup default to openai/gpt-5.6-sol. The bare direct-API openai/gpt-5.6 alias remains supported and resolves to Sol. Re-running setup preserves an existing explicit model, including openai/gpt-5.5. Select openai/gpt-5.5 explicitly if the account does not expose GPT-5.6. Security note: if this agent will run tools or process webhook/hook content, prefer the strongest latest-generation model available and keep tool policy strict - weaker or older tiers are easier to prompt-inject. For non-interactive runs, --secret-input-mode ref stores new credentials as env-backed refs; set the provider env var when adding a credential. Existing resolvable named profiles and their env, file, exec, or store refs are reused unchanged without a new credential write or additional provider env var. Previously stored plaintext is not migrated; see Secrets management. Interactive secret reference mode can point at an environment variable or a configured provider ref (file or exec), with a fast preflight check before saving. After model/auth setup, the wizard offers an optional live completion test; a failure can return to model/auth setup once or be ignored without blocking the rest of the classic wizard. Ignoring it does not unlock OpenClaw; conversational setup still requires a passing inference check.
3. Gateway - port, bind address, secret storage, and Tailscale exposure. Generates a Gateway secret in token mode by default, without asking you to choose token or password. Existing password-mode configs are preserved; --gateway-auth password or --gateway-password <value> selects password mode explicitly. Tailscale Funnel still requires password mode. Choose plaintext secret storage (default) or opt into a SecretRef. Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
4. Channels - built-in and official plugin chat channels, including Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
5. Web search - configures an optional search provider.
6. Skills - installs recommended skills and their optional dependencies.
7. Daemon - installs a LaunchAgent (macOS), a systemd user unit (Linux/WSL2), or a native Windows Scheduled Task with a per-user Startup-folder fallback. If token auth is required and gateway.auth.token is SecretRef-managed, daemon install validates it but does not persist a resolved token into supervisor service environment metadata; an unresolved SecretRef blocks install with guidance. If both gateway.auth.token and gateway.auth.password are set while gateway.auth.mode is unset, install is blocked until you set the mode explicitly.
8. Health check - starts the Gateway and verifies it is reachable.

--flow import runs a detected migration flow (for example Hermes) in the classic wizard instead of fresh setup; see Migrate and the migration guides under Install. openclaw onboard --modern is a compatibility alias for OpenClaw. It uses the same inference gate as openclaw setup: verified inference starts the assistant, while an interactive failure returns to guided inference setup.

Add another agent

Use openclaw agents add <name> to create a separate agent with its own workspace, sessions, and auth profiles. Running without --workspace starts an interactive flow for name, workspace, auth, channels, and bindings - it is not the full openclaw onboard wizard.

What it sets:

• agents.entries.*.name
• agents.entries.*.workspace
• agents.entries.*.agentDir

Notes:

• Default workspace: ~/.openclaw/workspace-<agentId> (or under agents.defaults.workspace if that is set).
• Add bindings to route inbound messages to this agent (onboarding can do this for you).
• Non-interactive flags: --model, --agent-dir, --bind, --non-interactive.

Full reference

For detailed step-by-step behavior and config outputs, see CLI setup reference. For non-interactive examples, see CLI automation. For the full flag reference, see openclaw onboard.

Related docs

• CLI command reference: openclaw onboard
• Onboarding overview: Onboarding overview
• macOS app onboarding: Onboarding
• Agent first-run ritual: Agent Bootstrapping