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. By default, Quick start uses the 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.

Choose one agent or a team

When guided onboarding creates the first agent, choose One agent (the default) or A small team: a chief of staff plus specialists. The team choice uses the same preset as openclaw agents team create: a chief of staff (coordinator), researcher, writer, and reviewer with separate workspaces, completed identities, and written role contracts. The chief of staff delegates suitable tasks and verifies specialist results before reporting to you.

Guided setup creates the team after the selected provider passes its connection check. A failed check returns to provider selection without creating team members. Choosing Skip creates the workspaces for later use and reports that AI access still needs configuration. Guided setup remembers the chosen coordinator across restarts, including an interruption after provider activation but before member creation.

For a team, --workspace is the parent directory; every member uses <workspace>/<agent-id>. After all members have been created, interrupted setup keeps that parent as its recovery workspace. Retry openclaw onboard --workspace <workspace> without --team to finish setup. Completion checks the full team roster and every member's workspace before closing the setup receipt; an incomplete or changed team stays pending with an error.

If member creation itself fails, already-created members are retained and are not recreated automatically. Inspect openclaw agents list and repair the incomplete roster before retrying setup.

Select the team directly in an interactive or non-interactive run with --team:

openclaw onboard --teamopenclaw onboard --non-interactive --team --accept-risk

The usual non-interactive provider and Gateway options still apply. Onboarding targets the coordinator explicitly for chat. It sets agents.defaults.systemAgent.agentId to the coordinator only when no ambient owner is configured; an existing owner is preserved and reported. A team does not introduce a universal default agent or change global delegation or tool policy. To address it later, use an explicit target:

openclaw agent --agent coordinator --message "Research a topic and prepare a draft."

--team is for local first-agent setup. It cannot be combined with remote, classic, or import onboarding. If an agent roster already exists, use openclaw agents team create instead.

See Team preset for the delegation config and agents team create to add a namespaced team to an existing installation.

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-6-astra. 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. When no command owner exists, completed channel setup offers a separate operator-account step for /update and other administration. Enter your own user ID and confirm it, or skip. This works in servers and groups without DM pairing and does not promote chat allowlists. See command owner setup.
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: --role, --model, --agent-dir, --bind, --non-interactive. With --role, --workspace can be omitted. See Role templates.

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