Onboard

`openclaw onboard`

Full guided onboarding for local or remote Gateway setup. Use this when you want OpenClaw to walk through model auth, workspace, gateway, channels, skills, and health in one flow.

CLI onboarding hub

Walkthrough of the interactive CLI flow.

Onboarding overview

How OpenClaw onboarding fits together.

CLI setup reference

Outputs, internals, and per-step behavior.

CLI automation

Non-interactive flags and scripted setups.

macOS app onboarding

Onboarding flow for the macOS menu bar app.

Examples

openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import uses plugin-owned migration providers such as Hermes. It only runs against a fresh OpenClaw setup; if existing config, credentials, sessions, or workspace memory/identity files are present, reset or choose a fresh setup before importing.

--modern starts the Crestodian conversational onboarding preview. Without --modern, openclaw onboard keeps the classic onboarding flow.

On a fresh install where the active config file is missing or has no authored settings (empty or metadata-only), bare openclaw also starts the classic onboarding flow. Once a config file has authored settings, bare openclaw opens Crestodian instead.

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.

Locale

Interactive onboarding uses the CLI wizard locale for fixed setup copy. Resolve order is:

OPENCLAW_LOCALE
LC_ALL
LC_MESSAGES
LANG
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.

Example:

OPENCLAW_LOCALE=zh-CN openclaw onboard

Non-interactive custom provider:

openclaw onboard --non-interactive \
  --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 in non-interactive mode. If omitted, onboarding checks CUSTOM_API_KEY. OpenClaw marks common vision model IDs as image-capable automatically. Pass --custom-image-input for unknown custom vision IDs, or --custom-text-input to force text-only metadata.

LM Studio also supports a provider-specific key flag in non-interactive mode:

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

Non-interactive Ollama:

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

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

Store provider keys as refs instead of plaintext:

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

With --secret-input-mode ref, onboarding writes env-backed refs instead of plaintext key values. For auth-profile backed providers this writes keyRef entries; for custom providers this writes models.providers.<id>.apiKey as an env ref (for example { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

Non-interactive ref mode contract:

Set the provider env var in the onboarding process environment (for example OPENAI_API_KEY).
Do not pass inline key flags (for example --openai-api-key) unless that env var is also set.
If an inline key flag is passed without the required env var, onboarding fails fast with guidance.

Gateway token options in non-interactive mode:

--gateway-auth token --gateway-token <token> stores a plaintext token.
--gateway-auth token --gateway-token-ref-env <name> stores gateway.auth.token as an env SecretRef.
--gateway-token and --gateway-token-ref-env are mutually exclusive.
--gateway-token-ref-env requires a non-empty env var in the onboarding process environment.
With --install-daemon, when token auth requires a token, SecretRef-managed gateway tokens are validated but not persisted as resolved plaintext in supervisor service environment metadata.
With --install-daemon, if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
With --install-daemon, if both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, onboarding blocks install until mode is set explicitly.
Local onboarding writes gateway.mode="local" into the config. If a later config file is missing gateway.mode, treat that as config damage or an incomplete manual edit, not as a valid local-mode shortcut.
Local onboarding installs selected downloadable plugins when the chosen setup path requires them.
Remote onboarding only writes connection info for the remote Gateway and does not install local plugin packages.
--allow-unconfigured is a separate gateway runtime escape hatch. It does not mean onboarding may omit gateway.mode.

Example:

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --accept-risk

Non-interactive local gateway health:

Unless you pass --skip-health, onboarding waits for a reachable local gateway before it exits successfully.
--install-daemon starts the managed gateway install path first. Without it, you must already have a local gateway running, for example openclaw gateway run.
If you only want config/workspace/bootstrap writes in automation, use --skip-health.
If you manage workspace files yourself, pass --skip-bootstrap to set agents.defaults.skipBootstrap: true and skip creating AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.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 onboarding behavior with reference mode:

Choose Use secret reference when prompted.
Then choose either:
- Environment variable
- Configured secret provider (file or exec)
Onboarding performs a fast preflight validation before saving the ref.
- If validation fails, onboarding shows the error and lets you retry.

Non-interactive Z.AI endpoint choices

# Promptless endpoint selection
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# Other Z.AI endpoint choices:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn

Non-interactive Mistral example:

openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

Flow notes

Flow types

quickstart: minimal prompts, auto-generates a gateway token.
manual: full prompts for port, bind, and auth (alias of advanced).
import: runs a detected migration provider, previews the plan, then applies after confirmation.

Provider prefiltering

When an auth choice implies a preferred provider, onboarding prefilters the default-model and allowlist pickers to that provider. For Volcengine and BytePlus, this also matches the coding-plan variants (volcengine-plan/*, byteplus-plan/*).

If the preferred-provider filter yields no loaded models yet, 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:

Grok can offer optional x_search setup with the same xAI OAuth profile or API key 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 to auto-detect.
If Hermes state is detected, onboarding offers a migration flow. Use Migrate for dry-run plans, overwrite mode, reports, and exact mappings.

Common follow-up commands

openclaw channels add
openclaw configure
openclaw agents add <name>

Use openclaw setup instead when you only need the baseline config/workspace. Use openclaw configure later for targeted changes and openclaw channels add for channel-only setup.