openclaw onboard CLI reference: interactive setup guide

openclaw onboard

Guided setup establishes inference first by detecting existing AI access, requiring a live completion, saving only the working route, and launching OpenClaw to handle the remaining configuration. openclaw setup enters this workflow on new systems or whenever an onboarding option is present; configured systems use plain openclaw setup for system-agent chat. openclaw setup --baseline only writes the baseline config and workspace.

• CLI onboarding hub, A guided tour of the interactive CLI workflow.
• Onboarding overview, How the pieces of OpenClaw onboarding connect.
• CLI setup reference, Outputs, internals, and behavior for each step.
• CLI automation, Non-interactive flags and scripted configurations.
• macOS app onboarding, The onboarding flow for the macOS menu bar application.

Examples

openclaw onboard
openclaw onboard --tui
openclaw onboard --classic
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 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 stored during onboarding. Add --json for the machine-readable list used during first-run bootstrap. The command does not rescan installed applications or invoke a model. Its output contains only validated install IDs, source, and tier; it intentionally omits untrusted marketplace text, model reasoning, and local application labels. After the recommendation offer has been addressed, the command returns an empty list and future onboarding runs skip this step entirely. openclaw onboard recommendations refresh clears the stored offer so the next onboarding run rescans installed applications and generates a new offer.

Fresh workspaces defer the recommendation decision to the bootstrap conversation. After that conversation processes the user's selections, openclaw onboard recommendations acknowledge marks the stored offer as answered. The acknowledgement is idempotent. If a chosen installation 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 modifying the stored offer. After an interrupted ClawHub skill installation, 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 installation. Otherwise keep that ID pending with --retry and do not overwrite the existing skill.

• --classic: launches the complete step-by-step wizard. It cannot be combined with --non-interactive; omit --classic for automated setup.
• --flow quickstart: opens the classic wizard with minimal prompts, uses token authentication by default, and generates 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 with full prompts for port, bind, and authentication.
• --flow import: runs a detected migration provider (for example Hermes via --import-from hermes) against a fresh setup. After confirmation, onboarding stages configuration, 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. Reset configuration, credentials, sessions, and workspace state first if any exist. Use openclaw migrate for dry-run plans, overwrite mode, verified backups, reports, and exact mappings.
• --remote-url and --remote-token: prefill the classic remote Gateway step and override stored remote values for this run. Changing the URL does not reuse stored credentials unless you also pass a token. The token stays masked in prompts and follows the wizard's existing plaintext or SecretRef storage choice.
• --tailscale-reset-on-exit and --no-tailscale-reset-on-exit: explicitly control whether Tailscale Serve or Funnel configuration is reset when the Gateway exits. Omitting both preserves the current setting during non-interactive reruns.
• --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, --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 displays the security notice, then asks one question upfront: full access (recommended, setup automatically searches for AI applications, keys, and local runtimes) or ask first (setup asks once before searching, 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 authentication 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> provides 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.

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 configuration, 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 applications; application names are matched through your configured model and ClawHub search, and the step can be disabled with wizard.appRecommendations. In a macOS, Linux, or Windows desktop session, it then opens the authenticated Control UI dashboard and waits up to 60 seconds for the browser client to connect. On headless Linux or over SSH, 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 installation, running openclaw onboard again first checks the current default model, making the same process serve as both a verification and a repair step. It does not reapply setup, reinstall, or restart the Gateway service. When that verification fails, the configured model is never swapped automatically. Instead, onboarding halts and prompts for next steps. The check occurs outside your workspace, so a model from a workspace plugin may fail here while still functioning within the agent.

Use openclaw onboard --classic for provider-specific authentication, channels, skills, remote Gateway configuration, imports, or full Gateway management. For conversational non-inference setup and repair, run openclaw setup. openclaw onboard --modern acts as 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 (with no subcommand) routes based on config state:

• When the active config file is missing or contains 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 requires working inference and is not used to repair this pre-inference state.
• When the config file is valid, the normal agent TUI opens. 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.

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 clears state before running setup. --reset-scope controls the scope: config (config only), config+creds+sessions (the default when --reset is passed without a scope), or full (also resets the workspace). Workspace reset only occurs with --reset-scope full.

Locale

Interactive onboarding uses the CLI wizard locale for fixed setup text. It selects 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 or channel labels remain literal.

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

Non-interactive setup

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

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. When omitted, onboarding checks CUSTOM_API_KEY in the environment. OpenClaw automatically marks common vision model IDs (GPT-4o, 4.1, 5.x, Claude 3, 4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar) as image capable. 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 \
  --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. When 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 environment backed refs instead of plaintext key values. For auth profile backed providers this writes keyRef: { source: "env", provider: "default", id: <envVar> }. For custom providers it writes models.providers.<id>.apiKey the same way (for example { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). Contract: set the provider environment variable in the onboarding process environment (for example OPENAI_API_KEY) and do not also pass an inline key flag unless that environment variable is set. A flag value without the matching environment variable fails fast with guidance.

Gateway auth (non-interactive)

• --gateway-auth token --gateway-token <token> holds a token in plaintext. The default authentication mode is token.
• --gateway-auth token --gateway-token-ref-env <name> references gateway.auth.token as an env SecretRef. The environment variable of that name must be set and non-empty during the onboarding process.
• --gateway-token and --gateway-token-ref-env cannot be used together.
• When --install-daemon is active: a gateway.auth.token managed by a SecretRef gets validated but is not stored as a resolved plaintext value in the supervisor service environment metadata. If the reference cannot be resolved, installation stops with a failure and remediation instructions. If both gateway.auth.token and gateway.auth.password are set and gateway.auth.mode is not provided, installation pauses until you explicitly choose a mode.
• During local onboarding, gateway.mode="local" is written into the configuration. If a later config file is missing gateway.mode, that indicates either corruption or an incomplete manual edit, not a valid shortcut for local mode.
• Local onboarding installs any downloadable plugins required by the selected setup path (for instance, a Codex or Copilot runtime plugin based on your auth decisions). Remote onboarding only writes connection details for the remote Gateway and never installs local plugin packages.
• --allow-unconfigured serves as a separate openclaw gateway run emergency exit; 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 \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --accept-risk

Local gateway health

• Unless --skip-health is provided, onboarding will not exit successfully until a local gateway is reachable.
• --install-daemon triggers the managed gateway installation path first. Without it, a local gateway must already be running (for example openclaw gateway run).
• --skip-health avoids the wait when you only need config, workspace, or bootstrap writes in an automated context.
• --skip-bootstrap sets agents.defaults.skipBootstrap: true and omits creation of AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md.
• On native Windows, --install-daemon attempts Scheduled Tasks first; if task creation is denied, it falls back to a per-user Startup folder login item.

Interactive ref mode

• When prompted, select Use secret reference, then choose either Environment variable or a configured secret provider (file or exec).
• Before saving the reference, onboarding performs a quick preflight check and allows you to retry if it fails.

Z.AI endpoint choices

Note

--auth-choice zai-api-key automatically picks the best Z.AI endpoint and model for your key: Coding Plan endpoints prefer zai/glm-5.2 (with a fallback to glm-5.1 if unavailable); general API endpoints default to zai/glm-5.1. To force a Coding Plan endpoint, directly select zai-coding-global or zai-coding-cn.

# Promptless endpoint selection
openclaw onboard --non-interactive \
  --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 \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

Additional non-interactive flags

Token-based model authentication (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 (these are aliases that skip gateway service installation), --daemon-runtime <node>.

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

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

Output: --suppress-gateway-token-output suppresses Gateway/UI output that includes tokens (token hints, auto-login URL with embedded token, and automatic Control UI launch). This is helpful in shared terminals and CI environments.

Note

--json does not mean non-interactive mode during guided or classic onboarding. With --modern, JSON provides a one-shot OpenClaw overview and exits after that single result. For other scripts, use --non-interactive.

Provider prefiltering

When an auth choice implies a preferred provider, onboarding filters the default-model and allowlist pickers to that provider's models. The filter also includes other providers owned by the same plugin, covering coding-plan variants like volcengine/volcengine-plan and byteplus/byteplus-plan. If the preferred-provider filter results in no loaded models, onboarding falls back to the unfiltered catalog instead of leaving the picker empty.

Web-search follow-ups

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

• Grok can offer optional x_search setup using the same xAI auth and an x_search model selection.
• Kimi may request 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 endpoint compatible with OpenAI or Anthropic, 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 add
openclaw configure
openclaw agents add <name>