Onboard

text

Copy

openclaw onboard

Interactive onboarding for local or remote Gateway setup.

Related guides

Examples

bash
Copy
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

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.

starts the Crestodian conversational onboarding preview. Without , keeps the classic onboarding flow.

For plaintext private-network

targets (trusted networks only), set in the onboarding process environment. There is no equivalent for this client-side transport break-glass.

Non-interactive custom provider:

bash
Copy
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

is optional in non-interactive mode. If omitted, onboarding checks . OpenClaw marks common vision model IDs as image-capable automatically. Pass for unknown custom vision IDs, or to force text-only metadata.

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

bash
Copy
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:

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

defaults to . is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as also work here.

Store provider keys as refs instead of plaintext:

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

With

, onboarding writes env-backed refs instead of plaintext key values. For auth-profile backed providers this writes entries; for custom providers this writes as an env ref (for example ).

Non-interactive

mode contract:

• Set the provider env var in the onboarding process environment (for example
  text

  Copy

  OPENAI_API_KEY
  ).
• Do not pass inline key flags (for example
  text

  Copy

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

• text

  Copy

  --gateway-auth token --gateway-token <token>
  stores a plaintext token.
• text

  Copy

  --gateway-auth token --gateway-token-ref-env <name>
  stores
  text

  Copy

  gateway.auth.token
  as an env SecretRef.
• text

  Copy

  --gateway-token
  and
  text

  Copy

  --gateway-token-ref-env
  are mutually exclusive.
• text

  Copy

  --gateway-token-ref-env
  requires a non-empty env var in the onboarding process environment.
• With
  text

  Copy

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

  Copy

  --install-daemon
  , if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
• With
  text

  Copy

  --install-daemon
  , if both
  text

  Copy

  gateway.auth.token
  and
  text

  Copy

  gateway.auth.password
  are configured and
  text

  Copy

  gateway.auth.mode
  is unset, onboarding blocks install until mode is set explicitly.
• Local onboarding writes
  text

  Copy

  gateway.mode="local"
  into the config. If a later config file is missing
  text

  Copy

  gateway.mode
  , treat that as config damage or an incomplete manual edit, not as a valid local-mode shortcut.
• text

  Copy

  --allow-unconfigured
  is a separate gateway runtime escape hatch. It does not mean onboarding may omit
  text

  Copy

  gateway.mode
  .

Example:

bash
Copy
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
  text

  Copy

  --skip-health
  , onboarding waits for a reachable local gateway before it exits successfully.
• text

  Copy

  --install-daemon
  starts the managed gateway install path first. Without it, you must already have a local gateway running, for example
  text

  Copy

  openclaw gateway run
  .
• If you only want config/workspace/bootstrap writes in automation, use
  text

  Copy

  --skip-health
  .
• If you manage workspace files yourself, pass
  text

  Copy

  --skip-bootstrap
  to set
  text

  Copy

  agents.defaults.skipBootstrap: true
  and skip creating
  text

  Copy

  AGENTS.md
  ,
  text

  Copy

  SOUL.md
  ,
  text

  Copy

  TOOLS.md
  ,
  text

  Copy

  IDENTITY.md
  ,
  text

  Copy

  USER.md
  ,
  text

  Copy

  HEARTBEAT.md
  , and
  text

  Copy

  BOOTSTRAP.md
  .
• On native Windows,
  text

  Copy

  --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 (
    text

    Copy

    file
    or
    text

    Copy

    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

bash
Copy
# 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:

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

Flow notes

Flow types

Provider prefiltering

Web-search follow-ups

Other behaviors

Common follow-up commands

bash
Copy
openclaw configure
openclaw agents add <name>