openclaw onboard CLI Reference | Interactive Onboarding

openclaw onboard

This guided setup prioritizes inference from the start. It checks for existing AI access, demands a working completion, saves only the functional route, and then launches OpenClaw to handle the remaining configuration. openclaw setup triggers this process on new systems or whenever an onboarding option is present; systems that are already configured rely on plain openclaw setup for system-agent chat. openclaw setup --baseline writes only the base config and workspace.

• CLI onboarding hub, Guided tour of the interactive CLI process.

• Onboarding overview, How the pieces of OpenClaw onboarding fit together.

• CLI setup reference, Outputs, internals, and behavior for each step.

• CLI automation, Non-interactive flags and scripted configurations.

• macOS app onboarding, Onboarding process for the macOS menu bar app.

Examples

openclaw onboard
openclaw onboard --tui
openclaw onboard --classic
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --agent-name robby
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard recommendations --json
openclaw onboard recommendations acknowledge
openclaw onboard recommendations acknowledge --retry "<failed-id>"
openclaw onboard recommendations refresh
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

openclaw onboard recommendations reads pending app-recommendation matches that were saved during onboarding. Add --json for the machine-readable list that the first-run bootstrap uses. The command never rescans installed apps or invokes a model. Its output is limited to validated install IDs, source, and tier; untrusted marketplace prose, model reasons, and local app labels are deliberately excluded. Once the recommendation offer has been responded to, the command yields an empty list and later onboarding runs bypass this step entirely. openclaw onboard recommendations refresh removes the stored offer so the next onboarding run rescans installed apps and generates a fresh offer.

Fresh workspaces defer the recommendation decision to the bootstrap conversation. After that conversation processes the user's selections, openclaw onboard recommendations acknowledge flags the stored offer as 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 ones stay pending for a subsequent onboarding run. Unknown IDs cause a failure without altering 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 does not prove a local install. Otherwise keep that ID pending with --retry and avoid overwriting the existing skill.

• --classic: launches the complete step-by-step wizard. It cannot be used with --non-interactive; drop --classic for automated setup.
• --agent-name <name>: assigns a name to the first agent when no roster exists. Interactive onboarding prompts What should we call your first agent? and suggests main; non-interactive onboarding keeps main unless this flag is supplied. The id main is not reserved: if you later recreate it next to 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, defaults to token auth, and creates a token when no stored or explicit credential applies. Explicit local Gateway flags such as --gateway-port, --gateway-bind, --gateway-auth, and --tailscale override the corresponding stored or default quickstart values; omitted options retain their current values.
• --flow manual (alias advanced): opens the classic wizard's Manual setup flow with full prompts for port, bind, and auth.
• --flow import: executes 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. Credentials stay masked in prompts and follow the wizard's existing plaintext or SecretRef storage choice.
• --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, then tests the recommended candidate with a real completion. If a candidate fails, onboarding quietly tries the next usable one and summarizes anything that did not respond in a single line; the working route is announced with a one-keystroke option to see everything else instead.

If automatic detection is exhausted, the provider picker shows OpenAI, Anthropic, xAI (Grok), Google, and OpenRouter first. Choose More… for every other supported provider, grouped by provider; 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. Choose Skip for now to exit without starting OpenClaw and rerun openclaw onboard when you are ready. Workspace and Gateway setup remain unchanged until OpenClaw starts.

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 completes, onboarding scans for memories produced by supported local AI tools: Claude Code auto-memory, Codex consolidated memories, and Hermes memory files. If any are detected, a single page offers to copy them into the agent workspace under memory/imports/ for indexed recall. Imports never happen without explicit consent, files brought in previously are skipped, and you retain the option to import later via the Control UI Memory import page, which provides the same memory-only scope. (A complete openclaw migrate run casts a wider net: it may also bring in config, skills, and credentials.) The classic wizard presents this same page once the workspace has been prepared.

Following inference and the memory-import offer, guided onboarding automatically executes the standard configuration: workspace, Gateway, and sessions, mirroring what the conversational openclaw setup chat would do on a "yes" response. It then suggests plugins and skills drawn from installed applications; app names are resolved through your configured model and ClawHub search, and this step can be turned off with wizard.appRecommendations. If the platform includes a supported browser opener, the authenticated Control UI dashboard launches next, with up to 60 seconds allowed for the browser client to connect. This brief handoff grants that specific signed browser a persistent administrator credential. Display-less WSL is covered when wslview is present. On headless Linux, WSL lacking an opener, or SSH sessions without a display, a prominent dashboard URL is printed for copy-paste, complete with an SSH port-forward command for a loopback Gateway, and the wait extends to five minutes. A successful connection carries on in the browser; an unreachable Gateway or a timeout reverts to the earlier terminal hatch. Supplying --tui bypasses the browser handoff and forces that terminal hatch. When setup application fails, onboarding falls back to the conversational OpenClaw chat for interactive completion. Channels, agents, plugins, and other optional features stay within OpenClaw chat's domain: execute openclaw and use open channel wizard for <channel> to route channel credential collection through a masked terminal wizard. To switch the model provider or its authentication, exit OpenClaw and run openclaw onboard; the guided and classic provider flows are not opened by OpenClaw.

On an already-configured install, re-running openclaw onboard first checks the current default model, turning the same flow into a verification and repair pass. It does not re-apply setup, reinstall, or restart the Gateway service. If that check fails, the configured model is never swapped automatically; onboarding halts and asks for direction. The check operates outside your workspace, so a model supplied by a workspace plugin may fail here yet still function within the agent. For provider-specific auth, channels, skills, remote Gateway setup, imports, or full Gateway controls, use openclaw onboard --classic. For conversational non-inference setup and repair, run openclaw setup; openclaw onboard --modern serves as a compatibility alias passing through the same inference gate. The classic wizard can optionally validate the default model with a live completion, but OpenClaw refuses to start until its own live inference check succeeds.

In an interactive terminal, bare openclaw (with no subcommand) branches based on config state:

• When the active config file is absent or holds no authored settings (empty or metadata-only), guided onboarding begins.
• When the config file exists but fails validation, the classic onboarding path starts with openclaw doctor guidance. OpenClaw depends on working inference and is not used to fix this pre-inference state.
• When the config file validates, the normal agent TUI opens. A reachable configured Gateway with an agent and model goes straight to that UI, skipping onboarding and OpenClaw. On a configured install, reach OpenClaw via /openclaw inside the TUI or openclaw setup.

Remote setup reuses device pairing for the chosen Gateway, including a configured remote connection forwarded through loopback. Its readiness probes never generate new device pairings. Setup chat maintains a stable authenticated caller across replies, loopback connections included.

When interactive remote setup activates inference and the Gateway needs a restart, onboarding waits up to 45 seconds for a fresh Gateway boot and a successful inference check before opening setup chat. A healthy connection to the old Gateway is irrelevant. If the restart wait lapses or boot identity is absent, onboarding reports that the settings were saved and stops, rather than attempting another provider. Inspect the remote Gateway, then rerun bare openclaw in the connected terminal. If the error indicates the Gateway supplied no 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 --reset
openclaw onboard --reset --reset-scope full

--reset is a destructive pre-dispatch flag, not an option in the classic wizard's Setup mode menu. --reset-scope dictates the removal extent: config (config only), config+creds+sessions (default when --reset is passed without a scope), or full (also clears the workspace). Before moving state to Trash, onboarding verifies 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 paired with --reset; run the import without --reset. Non-interactive setup also demands --accept-risk before reset. Interactive classic setup executes reset before its risk acknowledgement appears, so invoking --reset can relocate state to Trash before you can reject that prompt. After reset, the command runs guided, classic, or non-interactive onboarding per the other flags.

Locale

Interactive onboarding draws fixed setup copy from the CLI wizard locale. It picks the first nonblank value in this sequence:

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 stay literal.

OPENCLAW_LOCALE=zh-CN openclaw onboard
OPENCLAW_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-capabilities
openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice openai-api-key \
  --secret-input-mode ref

Set OPENAI_API_KEY before executing this example. The codex selector pulls from OpenClaw's official plugin catalog. When the needed plugin is already present but requires approval to activate, switch to openclaw plugins enable <plugin-id> --accept-capabilities. That flag grants permission solely for that plugin's operation, not as a system-wide override. External plugins needed by openclaw channels add follow the same preinstall-then-rerun procedure. Bundled plugins skip this approval step. Refer to 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 not required; when left out, onboarding checks CUSTOM_API_KEY in the environment. OpenClaw automatically tags common vision model IDs (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar) as image-capable. For custom vision IDs that are unknown, pass --custom-image-input, or use --custom-text-input to force text-only metadata. For OpenAI-compatible endpoints that support /v1/responses but lack /v1/chat/completions, apply --custom-compatibility openai-responses; accepted values are openai (the default), openai-responses, and anthropic.

LM Studio offers its own 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"

Ollama without interaction:

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 comes preset to http://127.0.0.1:11434. --custom-model-id is optional; when absent, onboarding relies on Ollama's suggested defaults. Cloud model IDs such as kimi-k2.5:cloud are also accepted here.

Keep provider keys as refs rather than plaintext:

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

Using --secret-input-mode ref, onboarding saves new credentials as refs instead of plaintext: auth profiles rely on keyRef: { source: "env", provider: "default", id: <envVar> }, while custom providers use models.providers.<id>.apiKey (for instance { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). When adding a new credential, set the provider env var; an inline key flag without its matching env var fails immediately. Existing resolvable named auth profiles and their env, file, exec, or store references stay unchanged, with no fresh apiKey or keyRef write and no extra provider env var. Plaintext profile credentials are not converted automatically; execute openclaw secrets configure --apply, then openclaw secrets audit --check. See Secrets management.

Gateway auth (non-interactive)

• --gateway-auth token --gateway-token <token> holds a plaintext token, while token serves as the default authentication mode.
• --gateway-auth token --gateway-token-ref-env <name> saves gateway.auth.token through an env SecretRef, which requires a non-empty environment variable with that name to be present during onboarding.
• --gateway-token and --gateway-token-ref-env cannot be used together.
• For remote onboarding, --remote-token <token> or --remote-password <password> supply gateway.remote credentials. Local Gateway authentication is configured via --gateway-token, --gateway-token-ref-env, and --gateway-password, none of which apply in remote mode. When using a remote token SecretRef, specify OPENCLAW_GATEWAY_TOKEN and pair it with --remote-token alongside --secret-input-mode ref.
• Under --secret-input-mode ref, non-interactive --gateway-password and --remote-password each demand a corresponding OPENCLAW_GATEWAY_PASSWORD, and --remote-token needs a matching OPENCLAW_GATEWAY_TOKEN; onboarding stores an env SecretRef and refuses to proceed if values are absent or don't match, before any state changes occur. Interactive setup can also pick from configured file, exec, or store refs.
• With --install-daemon: a gateway.auth.token managed by a SecretRef gets validated but is not kept as resolved plaintext in the supervisor service environment metadata; an unresolved ref causes installation to fail closed with remediation instructions. When both gateway.auth.token and gateway.auth.password are set and gateway.auth.mode remains unspecified, installation halts until the mode is explicitly chosen.
• Local onboarding places gateway.mode="local" in the config. If a later config file omits gateway.mode, that signals damaged configuration or an incomplete manual edit, not a valid local-mode alternative.
• Local onboarding verifies that required plugins for the chosen setup path are present, such as the Codex or Copilot runtime. Non-interactive setup lacks the ability to approve new capabilities; review and preinstall required external plugins beforehand, then run onboarding again. Remote onboarding only records connection details for the remote Gateway, and it never installs local plugin packages.
• --allow-unconfigured acts as a separate openclaw gateway run escape hatch; it does not allow onboarding to bypass 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

• Without passing --skip-health, onboarding will not report success until a reachable local gateway is detected.
• --install-daemon triggers the managed gateway install path first. If no daemon flag is given, a local gateway must already be active, for instance openclaw gateway run.
• Explicitly setting --skip-daemon or --no-install-daemon still checks for an existing gateway. When nothing is listening, setup notes that the gateway wasn't started and exits successfully; a gateway that is reachable but unhealthy still causes the health check to fail.
• --skip-health bypasses the wait when only config, workspace, or bootstrap writes are needed in automation.
• --skip-bootstrap defines agents.defaults.skipBootstrap: true and avoids creating AGENTS.md, SOUL.md, IDENTITY.md, USER.md, and BOOTSTRAP.md.
• On native Windows, --install-daemon attempts Scheduled Tasks first, then falls back to a per-user Startup-folder login item if task creation is denied.

Interactive ref mode

• At the prompt, select Use secret reference, then pick either Environment variable or a configured secret provider (file or exec).
• Before saving the ref, onboarding runs a quick preflight validation and allows a retry if it fails.

Z.AI endpoint choices

Note

--auth-choice zai-api-key automatically picks the optimal Z.AI endpoint and model for your key: Coding Plan endpoints favor zai/glm-5.2, with glm-5.1 as a fallback when unavailable; general API endpoints default to zai/glm-5.1. To force a Coding Plan endpoint, choose zai-coding-global or zai-coding-cn directly.

# Promptless endpoint selection
openclaw 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"

Additional non-interactive flags

Token-based model authentication, paired with --auth-choice token, relies on these flags:

Cloudflare AI Gateway is configured through --cloudflare-ai-gateway-account-id <id> and --cloudflare-ai-gateway-gateway-id <id>.

Daemon installation is controlled by --no-install-daemon and --skip-daemon, which are aliases that skip the gateway service install, along with --daemon-runtime <node|bun>, whose default is node. Bun 1.4+ paired with WAL-reset-safe node:sqlite requires an explicit opt-in; Node stays the recommended runtime.

Skills are managed with --node-manager <npm|pnpm|bun>, defaulting to npm, and --skip-skills.

UI and hook configuration: --skip-ui bypasses Control UI/TUI prompts, --skip-hooks skips webhook/hook setup, plus --skip-channels and --skip-search.

For output, --suppress-gateway-token-output turns off the automatic Control UI handoff during guided onboarding. Classic onboarding never exposes reusable Gateway token values or tokenized URLs, though it does print safe recovery commands.

Note

Setting --json does not force non-interactive behavior in either guided or classic onboarding. When no interactive terminal is present, both onboarding modes return a structured JSON error; to automate, add --non-interactive --accept-risk. With --modern, JSON yields a one-shot OpenClaw overview and terminates after that single result. For other scripts, rely on --non-interactive. Invalid existing configuration likewise produces a single JSON failure, with repair guidance sent to stderr.

Provider prefiltering

When the chosen auth implies a preferred provider, onboarding narrows the default-model and allowlist pickers to that provider's models. Other providers owned by the same plugin also match the filter, covering coding-plan variants like volcengine/volcengine-plan and byteplus/byteplus-plan. Should the preferred-provider filter return no loaded models, onboarding uses the full unfiltered catalog rather than leaving the picker empty.

Web-search follow-ups

Certain web-search providers add provider-specific follow-up prompts during onboarding:

• Grok may offer optional x_search setup sharing the same xAI auth, along with an x_search model choice.
• Kimi may request the Moonshot API region (api.moonshot.ai versus api.moonshot.cn) and the default Kimi web-search model.

Other behaviors

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

Common follow-up commands

Later, use openclaw configure for targeted non-inference changes and openclaw channels add for channel-only setup. To alter model providers or auth routes, run openclaw onboard instead.

openclaw channels add
openclaw configure
openclaw agents add <name>