Skip to main content

​
openclaw onboard

Interactive onboarding wizard (local or remote Gateway setup).

​
Examples

openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url ws://gateway-host:18789
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-api-key is optional in non-interactive mode. If omitted, onboarding checks CUSTOM_API_KEY. 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.
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: Note: --auth-choice zai-api-key now auto-detects the best Z.AI endpoint for your key (prefers the general API with zai/glm-5). If you specifically want the GLM Coding Plan endpoints, pick 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:
# --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:
  • quickstart: minimal prompts, auto-generates a gateway token.
  • manual: full prompts for port/bind/auth (alias of advanced).
  • Local onboarding DM scope behavior: CLI Onboarding 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.

​
Common follow-up commands

openclaw configure
openclaw agents add <name>
--json does not imply non-interactive mode. Use --non-interactive for scripts.