openclaw onboard

Guided setup that establishes inference first: it detects existing AI access, waits for your provider choice, verifies that connection, persists only the working route, and then starts OpenClaw to configure the rest. openclaw setup reaches this flow on fresh systems or whenever an onboarding option is present; configured systems use bare openclaw setup for system-agent chat. openclaw setup --baseline only writes the baseline config/workspace.

Examples

openclaw onboardopenclaw onboard --tuiopenclaw onboard --classicopenclaw onboard --modernopenclaw onboard --flow quickstartopenclaw onboard --agent-name robbyopenclaw onboard --flow manualopenclaw onboard --flow importopenclaw onboard --import-from hermes --import-source ~/.hermesopenclaw onboard --skip-bootstrapopenclaw onboard recommendations --jsonopenclaw onboard recommendations --agent writer --jsonopenclaw onboard recommendations --agent writer acknowledgeopenclaw onboard recommendations acknowledge --agent writeropenclaw onboard recommendations refresh --agent writeropenclaw onboard recommendations acknowledgeopenclaw onboard recommendations acknowledge --retry "<failed-id>"openclaw onboard recommendations refreshopenclaw onboard --mode remote --remote-url wss://gateway-host:18789

openclaw onboard recommendations reads pending app-recommendation matches stored during onboarding. Add --json for the machine-readable list used by the first-run bootstrap. The command does not rescan installed apps or call a model. Its output contains only validated install IDs, source, and tier; it intentionally omits untrusted marketplace prose, model reasons, and local app labels. After the recommendation offer has been answered, the command returns an empty list and future onboarding runs skip the step entirely. openclaw onboard recommendations refresh clears the stored offer so the next onboarding run rescans installed apps and creates a new offer.

Pass --agent <id> to select a configured agent for reads, acknowledge, acknowledge --retry, or refresh. Place it before or after the subcommand; an explicit value on the subcommand takes precedence over a parent value. These operations use only that agent's workspace recommendations. Without the selector, the command keeps its existing default-agent behavior and asks you to select an agent when the owner is ambiguous. Blank or unknown agent IDs fail without changing the stored recommendations; use openclaw agents list to find configured IDs.

Fresh workspaces defer the recommendation choice to the bootstrap conversation. After that conversation handles the user's choices, openclaw onboard recommendations acknowledge marks the stored offer answered. The acknowledgement is idempotent. If a chosen install fails, pass each failed opaque ID with --retry <id...>; successful and declined matches are consumed, while failed matches remain pending for a later onboarding run. Unknown IDs fail without changing the stored offer. After an interrupted ClawHub skill install, an existing target counts as successful only when openclaw skills verify "@owner/slug" succeeds for the same publisher-qualified recommendation ID and its JSON output reports openclaw.resolution.source: "installed". Registry verification alone is not proof of a local install. Otherwise keep that ID pending with --retry and do not overwrite the existing skill.

Flags

• --classic: opens the full step-by-step wizard. It cannot be combined with --non-interactive; omit --classic for automated setup.
• --agent-name <name>: names the first agent when no roster exists. Interactive onboarding asks What should we call your first agent? and suggests main; non-interactive onboarding keeps main unless this flag is provided. The id main is not reserved: if you later recreate it beside a named agent, run openclaw doctor --fix first when creation reports legacy-session or shared-auth ownership still attached to the old main installation.
• --flow quickstart: opens the classic wizard with minimal prompts, uses a generated Gateway secret by default, without asking you to choose token or password. Existing password-mode configurations are preserved. Explicit local Gateway flags such as --gateway-port, --gateway-bind, --gateway-auth, and --tailscale override the corresponding stored or default quickstart values; omitted options keep their current values.
• --flow manual (alias advanced): opens the classic wizard's Manual setup flow with full prompts for port, bind, and secret storage. It generates the Gateway secret by default; use --gateway-auth password or --gateway-password <value> to choose your own password. Tailscale Funnel still requires password mode. The mode selects the configured secret; clients can send it in either auth.token or auth.password.
• --flow import: runs a detected migration provider (for example Hermes via --import-from hermes) against a fresh setup. After confirmation, onboarding stages config, credentials, workspace files, memory, and skills under private temporary targets; imported inference must pass a live completion before workspace and agent state are promoted and configuration is committed. Failure or cancellation before promotion leaves the live target untouched. External activation steps that cannot be rolled back, such as Codex plugin installation, run afterward and remain retryable from the migration report. Migration import options (--flow import, --import-from, --import-source, and --import-secrets) cannot be combined with --reset; run the import without --reset. Use openclaw migrate for dry-run plans, overwrite mode, verified backups, reports, and exact mappings.
• --remote-url, --remote-token, and --remote-password: prefill the classic remote Gateway step and override stored remote values for this run. Pass either a token or a password, not both. Changing the URL does not reuse stored credentials unless you also provide a new token or password. The interactive step asks for one Gateway secret, whether the remote Gateway calls it a token or password, and stores it as gateway.remote.token. Credentials stay masked and follow the plaintext or SecretRef storage choice. Leave the secret blank and confirm to keep an existing credential. To connect without a shared secret, leave it blank, decline keeping an existing credential if offered, then explicitly confirm Continue without a Gateway secret?. Reference storage offers the same confirmation before asking for the reference.
• --modern is a compatibility alias for the OpenClaw conversational setup assistant. It uses the same live-inference gate as openclaw setup and accepts only --workspace, --agent-name, --accept-risk, --non-interactive, and --json. Other setup flags are rejected instead of being silently ignored.

Guided flow

Plain openclaw onboard starts the guided flow. It shows the security notice, asks for the first agent's name when no roster exists, then asks one discovery question up front: full access (recommended — setup looks for AI apps, keys, and local runtimes automatically) or ask first (setup asks once before looking around, or lets you configure manually). The choice persists as wizard.accessMode. With discovery allowed, onboarding detects AI access already available through configured models, API-key environment variables, and supported local CLIs. Detection only presents choices; it does not run live inference, install plugins, choose a model, or persist credentials. Choose a detected connection or any supported provider in the shared picker. The selected connection runs a real completion. If it fails, the error is shown and the picker waits for your next choice. Cancellation stops the attempt without trying another provider.

The provider picker includes installed and installable official providers. Choose More… for additional provider groups; regions, plans, and auth methods then appear in a second menu. Supported browser or device sign-in and masked API-key or token methods use the same live completion path. OpenClaw persists only the verified model route and its credential after the test succeeds; a failed candidate does not replace the configured model or save the attempted credential. In local onboarding, Skip for now prepares the named agent's workspace and local Gateway configuration, then exits without starting the Gateway or AI chat. Rerun openclaw onboard when you are ready to connect AI; interrupted baseline setup resumes under its existing onboarding owner.

In guided mode, --workspace <dir> supplies OpenClaw's proposed workspace and the isolated inference context. It is not persisted until you approve the OpenClaw setup proposal. Classic and noninteractive onboarding persist their workspace through their normal setup flow. On a rerun with an existing agent roster, onboarding preserves the configured fleet workspace: the classic wizard shows both paths and requires explicit confirmation before moving it, while non-interactive setup warns and keeps the current value. For an explicitly managed multi-agent fleet, provider setup updates the configured system agent's model and aliases without replacing fleet-wide model defaults or another agent's model.

After inference passes, onboarding checks for memories from supported local AI tools: Claude Code auto-memory, Codex consolidated memories, and Hermes memory files. When it finds any, one page offers to copy them into the agent workspace under memory/imports/ for indexed recall. Nothing is imported without confirmation, previously imported files are skipped, and you can always import later from the Control UI Memory import page, which offers the same memory-only scope. (A full openclaw migrate run is broader: it can also import config, skills, and credentials.) The classic wizard shows the same page after it prepares the workspace.

After inference passes (and the memory-import offer), guided onboarding applies the standard setup automatically — workspace, Gateway, and sessions, the same plan the conversational openclaw setup chat would apply on "yes" — then offers plugin and skill recommendations from installed apps; app names are matched through your configured model and ClawHub search, and the step can be disabled with wizard.appRecommendations. When the platform has a supported browser opener, it then opens the authenticated Control UI dashboard and waits up to 60 seconds for the browser client to connect. The short-lived handoff gives that exact signed browser a durable administrator credential. This includes display-less WSL when wslview is installed. On headless Linux, WSL without an opener, or over SSH without a display, it prints a prominent copy-pasteable dashboard URL, including an SSH port-forward command for a loopback Gateway, and waits up to five minutes. A successful connection continues in the browser; an unreachable Gateway or a timeout falls back to the same terminal hatch as before. Pass --tui to skip the browser handoff and force that terminal hatch. If applying setup fails, onboarding falls back to the conversational OpenClaw chat to finish interactively. Channels, agents, plugins, and other optional features remain OpenClaw chat territory: run openclaw and use open channel wizard for <channel> to hand channel credential collection to a masked terminal wizard. To change the model provider or its authentication, exit OpenClaw and run openclaw onboard; OpenClaw does not open the guided or classic provider flows.

On a configured install, running openclaw onboard again offers the current default model in the detected-connections group. Choose it for a verification pass that does not re-apply setup, reinstall, or restart the Gateway service. If that check fails, the configured model stays unchanged and the picker waits for your next choice. The check runs outside your workspace, so a model provided by a workspace plugin can fail here while still working in the agent. Use openclaw onboard --classic for provider-specific auth, channels, skills, remote Gateway setup, imports, or full Gateway controls. For conversational non-inference setup and repair, run openclaw setup; openclaw onboard --modern is a compatibility alias through the same inference gate. The classic wizard can optionally verify the default model with a live completion, but OpenClaw will not start until its own live inference check passes.

In an interactive terminal, bare openclaw (no subcommand) routes by config state:

• If the active config file is missing or has no authored settings (empty or metadata-only), it starts guided onboarding.
• If the config file exists but fails validation, it starts the classic onboarding path with openclaw doctor guidance. OpenClaw needs working inference and is not used to repair this pre-inference state.
• If the config file is valid, it opens the normal agent TUI. A reachable configured Gateway with an agent and model goes directly to that UI without onboarding or OpenClaw. On a configured install, reach OpenClaw with /openclaw inside the TUI or openclaw setup.

Remote setup reuses device pairing for the selected Gateway, including a configured remote connection forwarded through loopback. Its readiness probes do not create new device pairings. Setup chat keeps a stable authenticated caller across replies, including on loopback connections.

When interactive remote setup activates inference and the Gateway requires a restart, onboarding waits up to 45 seconds for a new Gateway boot and a successful inference check before opening setup chat. A healthy connection to the old Gateway does not count. If the restart wait expires or boot identity is missing, onboarding reports that the settings were saved and stops rather than trying another provider. Check the remote Gateway, then rerun bare openclaw in the connected terminal. If the error says the Gateway did not provide a boot identity, update and restart that Gateway first.

Plaintext ws:// is accepted for loopback, private IP literals, .local, and Tailnet *.ts.net gateway URLs. For other trusted private-DNS names, set OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 in the onboarding process environment.

Reset

openclaw onboard --resetopenclaw onboard --reset --reset-scope full

--reset is a destructive pre-dispatch flag, not a choice in the classic wizard's Setup mode menu. --reset-scope controls how much it removes: config (config only), config+creds+sessions (default when --reset is passed without a scope), or full (also resets the workspace). Before moving state to Trash, onboarding validates TTY availability, the reset scope, auth and Gateway options, migration import options, and the workspace target for a full reset. Migration import options cannot be combined with --reset; run the

Interactive classic setup performs reset before showing its risk acknowledgement, so invoking --reset can move state to Trash before you can decline that prompt. After reset, the command runs guided, classic, or non-interactive onboarding according to the other flags.

Locale

Interactive onboarding uses the CLI wizard locale for fixed setup copy. It uses the first nonblank value in this order:

1. OPENCLAW_LOCALE
2. LC_ALL
3. LC_MESSAGES
4. LANG
5. English fallback

Supported wizard locales are en, zh-CN, and zh-TW. Locale values may use underscore or POSIX suffix forms such as zh_CN.UTF-8. Product names, command names, config keys, URLs, provider IDs, model IDs, and plugin/channel labels remain literal.

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

Non-interactive setup

--non-interactive requires --accept-risk (acknowledges that agents are powerful and full system access is risky). --mode defaults to local.

Required external plugins

--accept-risk does not approve plugin capabilities. If local setup needs an external provider or runtime plugin, non-interactive onboarding stops when that plugin requires a capability review. Review and preinstall the required plugin, then rerun the same onboarding command. For the official Codex runtime used by OpenAI setup:

# After reviewing the plugin and its declared capabilities:openclaw plugins install codex --accept-capabilitiesopenclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice openai-api-key \  --secret-input-mode ref

Set OPENAI_API_KEY before running this example. The codex selector uses OpenClaw's official plugin catalog. If the required plugin is already installed but needs approval to enable it, use openclaw plugins enable <plugin-id> --accept-capabilities instead. The flag approves only that plugin operation; it is not a global bypass. The same preinstall-and-rerun flow applies to external plugins required by openclaw channels add. Bundled plugins do not need this review. See Capability consent and the automation guide.

Provider setup examples

openclaw onboard --non-interactive --accept-risk --skip-health \  --agent-name robby \  --auth-choice custom-api-key \  --custom-base-url "https://llm.example.com/v1" \  --custom-model-id "foo-large" \  --custom-api-key "$CUSTOM_API_KEY" \  --secret-input-mode plaintext \  --custom-compatibility openai \  --custom-image-input

--custom-api-key is optional; if omitted, onboarding checks CUSTOM_API_KEY in env. OpenClaw marks common vision model IDs (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar) as image-capable automatically. Pass --custom-image-input for unknown custom vision IDs, or --custom-text-input to force text-only metadata. Use --custom-compatibility openai-responses for OpenAI-compatible endpoints that support /v1/responses but not /v1/chat/completions; valid values are openai (default), openai-responses, anthropic.

LM Studio also has a provider-specific key flag:

openclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice lmstudio \  --custom-base-url "http://localhost:1234/v1" \  --custom-model-id "qwen/qwen3.5-9b" \  --lmstudio-api-key "$LM_API_TOKEN"

Non-interactive Ollama:

openclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice ollama \  --custom-base-url "http://ollama-host:11434" \  --custom-model-id "qwen3.5:27b"

--custom-base-url defaults to http://127.0.0.1:11434. --custom-model-id is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as kimi-k2.5:cloud also work here.

Non-interactive llama.cpp against an existing llama-server:

openclaw onboard --non-interactive --accept-risk \  --auth-choice llama-cpp-existing-server \  --custom-base-url "http://127.0.0.1:8080/v1" \  --custom-model-id "my-model" \  --llama-server-api-key "$LLAMA_SERVER_API_KEY"

--auth-choice llama-cpp selects the managed local server instead. --llama-server-api-key is optional; if omitted, onboarding checks LLAMA_SERVER_API_KEY in env. See llama.cpp for endpoint-replacement and auth-profile behavior.

Store provider keys as refs instead of plaintext:

openclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice openai-api-key \  --secret-input-mode ref

With --secret-input-mode ref, onboarding stores new credentials as refs instead of plaintext: auth profiles use keyRef: { source: "env", provider: "default", id: <envVar> }, and custom providers use models.providers.<id>.apiKey (for example { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). Set the provider env var when adding a new credential; an inline key flag without its matching env var fails fast. Existing resolvable named auth profiles and their env, file, exec, or store references are reused unchanged, without a new apiKey or keyRef write or additional provider env var. Existing plaintext profile credentials are not migrated; run openclaw secrets configure --apply, then openclaw secrets audit --check. See Secrets management.

Gateway auth (non-interactive)

• Without auth flags or an existing credential, onboarding generates a Gateway secret and stores it as gateway.auth.token with gateway.auth.mode: "token". Quickstart keeps its existing plaintext storage default; --secret-input-mode ref explicitly requests a reference. Run openclaw dashboard to open the Control UI.
• --gateway-auth token --gateway-token <token> stores a supplied plaintext secret.
• --gateway-password <value> selects password mode without an auth-choice prompt; --gateway-auth password also explicitly selects password mode. An existing password-mode config stays in password mode on rerun.
• --gateway-auth token --gateway-token-ref-env <name> stores gateway.auth.token as an env SecretRef. Requires a non-empty env var of that name in the onboarding process environment.
• --gateway-token and --gateway-token-ref-env are mutually exclusive.
• Remote onboarding uses --remote-token <token> or --remote-password <password> for gateway.remote credentials. --gateway-token, --gateway-token-ref-env, and --gateway-password configure local Gateway auth and are not valid in remote mode. For remote token SecretRefs, set OPENCLAW_GATEWAY_TOKEN and use --remote-token with --secret-input-mode ref.
• With --secret-input-mode ref, non-interactive --gateway-password and --remote-password require a matching OPENCLAW_GATEWAY_PASSWORD, and --remote-token requires a matching OPENCLAW_GATEWAY_TOKEN; onboarding stores an env SecretRef and rejects missing or mismatched values before changing state. Interactive setup can also select configured file, exec, or store refs.
• With --install-daemon: a SecretRef-managed gateway.auth.token is validated but not persisted as resolved plaintext in supervisor service environment metadata; if the ref is unresolved, install fails closed with remediation guidance. If both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, install blocks until mode is set explicitly.
• Local onboarding writes gateway.mode="local" into the config. A later config file missing gateway.mode indicates config damage or an incomplete manual edit, not a valid local-mode shortcut.
• Local onboarding ensures the chosen setup path's required plugins are available (for example the Codex or Copilot runtime). Non-interactive setup cannot approve new capabilities; review and preinstall required external plugins, then rerun onboarding. Remote onboarding only writes connection info for the remote Gateway - it never installs local plugin packages.
• --allow-unconfigured is a separate openclaw gateway run escape hatch; it does not let onboarding skip gateway.mode.

export OPENAI_API_KEY="your-provider-key"export OPENCLAW_GATEWAY_TOKEN="your-token"openclaw onboard --non-interactive --accept-risk --skip-health \  --mode local \  --auth-choice openai-api-key \  --secret-input-mode ref \  --gateway-auth token \  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

Local gateway health

• Unless you pass --skip-health, onboarding waits for a reachable local gateway before exiting successfully.
• --install-daemon starts the managed gateway install path first. With no daemon flag, a local gateway must already be running (for example openclaw gateway run).
• Explicit --skip-daemon or --no-install-daemon still probes for an existing gateway. If none is listening, setup reports that the gateway was not started and exits successfully; a reachable but unhealthy gateway still fails the health check.
• --skip-health skips the wait if you only want config/workspace/bootstrap writes in automation.
• --skip-bootstrap sets agents.defaults.skipBootstrap: true and skips creating AGENTS.md, SOUL.md, IDENTITY.md, USER.md, and BOOTSTRAP.md.
• On native Windows, --install-daemon tries Scheduled Tasks first and falls back to a per-user Startup-folder login item if task creation is denied.

Interactive ref mode

• Choose Use secret reference when prompted, then either Environment variable or a configured secret provider (file or exec).
• Onboarding runs a fast preflight validation before saving the ref and lets you retry on failure.

Z.AI endpoint choices

# Promptless endpoint selectionopenclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice zai-coding-global \  --zai-api-key "$ZAI_API_KEY" # Other Z.AI endpoint choices: zai-coding-cn, zai-global, zai-cn

Mistral:

openclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice mistral-api-key \  --mistral-api-key "$MISTRAL_API_KEY"

Arcee AI. The arcee provider plugin supplies both choices and their flags, so install it before running onboarding non-interactively:

# Direct (chat.arcee.ai)openclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice arceeai-api-key \  --arceeai-api-key "$ARCEEAI_API_KEY" # Via OpenRouteropenclaw onboard --non-interactive --accept-risk --skip-health \  --auth-choice arceeai-openrouter \  --openrouter-api-key "$OPENROUTER_API_KEY"

Additional non-interactive flags

Token-based model auth (used with --auth-choice token):

Cloudflare AI Gateway: --cloudflare-ai-gateway-account-id <id>, --cloudflare-ai-gateway-gateway-id <id>.

Daemon install control: --no-install-daemon / --skip-daemon (aliases; skip gateway service install), --daemon-runtime <node|bun> (default: node). Bun 1.4+ with WAL-reset-safe node:sqlite is an explicit opt-in; Node remains recommended.

Skills: --node-manager <npm|pnpm|bun> (default npm), --skip-skills.

UI and hook setup: --skip-ui (skip Control UI/TUI prompts), --skip-hooks (skip webhook/hook setup), --skip-channels, --skip-search.

Output: --suppress-gateway-token-output disables the automatic Control UI handoff in guided onboarding. Classic onboarding never prints reusable Gateway token values or tokenized URLs; it still prints safe recovery commands.

Provider prefiltering

When an auth choice implies a preferred provider, onboarding prefilters the default-model and allowlist pickers to that provider's models. The filter also matches other providers owned by the same plugin, which covers coding-plan variants such as volcengine/volcengine-plan and byteplus/byteplus-plan. If the preferred-provider filter yields no loaded models, onboarding falls back to the unfiltered catalog instead of leaving the picker empty.

Web-search follow-ups

Some web-search providers trigger provider-specific follow-up prompts during onboarding:

• Grok can offer optional x_search setup with the same xAI auth and an x_search model choice.
• Kimi can ask for the Moonshot API region (api.moonshot.ai vs api.moonshot.cn) and the default Kimi web-search model.

Other behaviors

• Local onboarding DM scope behavior: CLI setup reference.
• Fastest first chat: openclaw dashboard (Control UI, no channel setup).
• Custom provider: connect any OpenAI- or Anthropic-compatible endpoint, including hosted providers not listed. Use Unknown compatibility to auto-detect via a live probe.
• If Hermes state is detected, onboarding offers a migration flow (see --flow import above).

Common follow-up commands

Use openclaw configure later for targeted non-inference changes and openclaw channels add for channel-only setup. For model provider or auth route changes, run openclaw onboard instead.

openclaw channels addopenclaw configureopenclaw agents add <name>

Related

• CLI reference
• openclaw setup — the system-agent entry point; bare setup is interactive, and falls through to guided onboarding on a fresh system