English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Guides

CLI-Einrichtungsreferenz

This page is the full reference for openclaw onboard. For the short guide, see Onboarding (CLI).

What the wizard does

Local mode (default) walks you through:

  • Model and auth setup (OpenAI Code subscription OAuth, Anthropic Claude CLI or API key, plus MiniMax, GLM, Ollama, Moonshot, StepFun, and AI Gateway options)
  • Workspace location and bootstrap files
  • Gateway settings (port, bind, auth, tailscale)
  • Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage, and other bundled channel plugins)
  • Daemon install (LaunchAgent, systemd user unit, or native Windows Scheduled Task with Startup-folder fallback)
  • Health check
  • Skills setup

Remote mode configures this machine to connect to a gateway elsewhere. It does not install or modify anything on the remote host.

Local flow details

  • Existing config detection

    • If ~/.openclaw/openclaw.json exists, choose Keep, Modify, or Reset.
    • Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass --reset).
    • CLI --reset defaults to config+creds+sessions; use --reset-scope full to also remove workspace.
    • If config is invalid or contains legacy keys, the wizard stops and asks you to run openclaw doctor before continuing.
    • Reset uses trash and offers scopes:
      • Config only
      • Config + credentials + sessions
      • Full reset (also removes workspace)

  • Model and auth

  • Workspace

    • Default ~/.openclaw/workspace (configurable).
    • Seeds workspace files needed for first-run bootstrap ritual.
    • Workspace layout: Agent workspace.

  • Gateway

    • Prompts for port, bind, auth mode, and tailscale exposure.
    • Recommended: keep token auth enabled even for loopback so local WS clients must authenticate.
    • In token mode, interactive setup offers:
      • Generate/store plaintext token (default)
      • Use SecretRef (opt-in)
    • In password mode, interactive setup also supports plaintext or SecretRef storage.
    • Non-interactive token SecretRef path: --gateway-token-ref-env <ENV_VAR>.
      • Requires a non-empty env var in the onboarding process environment.
      • Cannot be combined with --gateway-token.
    • Disable auth only if you fully trust every local process.
    • Non-loopback binds still require auth.

  • Channels

    • WhatsApp: optional QR login
    • Telegram: bot token
    • Discord: bot token
    • Google Chat: service account JSON + webhook audience
    • Mattermost: bot token + base URL
    • Signal: optional signal-cli install + account config
    • iMessage: imsg CLI path + Messages DB access; use an SSH wrapper when the Gateway runs off-Mac
    • DM security: default is pairing. First DM sends a code; approve via openclaw pairing approve <channel> <code> or use allowlists.

  • Daemon install

    • macOS: LaunchAgent
      • Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
    • Linux and Windows via WSL2: systemd user unit
      • Wizard attempts loginctl enable-linger <user> so gateway stays up after logout.
      • May prompt for sudo (writes /var/lib/systemd/linger); it tries without sudo first.
    • Native Windows: Scheduled Task first
      • If task creation is denied, OpenClaw falls back to a per-user Startup-folder login item and starts the gateway immediately.
      • Scheduled Tasks remain preferred because they provide better supervisor status.
    • Runtime selection: Node (recommended; required for WhatsApp and Telegram). Bun is not recommended.

  • Health check

    • Starts gateway (if needed) and runs openclaw health.
    • openclaw status --deep adds the live gateway health probe to status output, including channel probes when supported.

  • Skills

    • Reads available skills and checks requirements.
    • Lets you choose node manager: npm, pnpm, or bun.
    • Installs optional dependencies for trusted bundled skills when the required installer is available.
    • Skips unavailable Homebrew, uv, and Go installers, then groups the affected skills with manual setup guidance. Run openclaw doctor after installing the missing prerequisites.

  • Finish

    • Summary and next steps, including iOS, Android, and macOS app options.

    • Remote mode details

    Remote mode configures this machine to connect to a gateway elsewhere.

    What you set:

    • Remote gateway URL (ws://...)
    • Token if remote gateway auth is required (recommended)

    Auth and model options

    Anthropic API key

    Uses ANTHROPIC_API_KEY if present or prompts for a key, then saves it for daemon use.

    OpenAI Code subscription (OAuth)

    Browser flow; paste code#state.

    Sets agents.defaults.model to openai/gpt-5.5 through the Codex runtime when model is unset or already OpenAI-family.

    OpenAI Code subscription (device pairing)

    Browser pairing flow with a short-lived device code.

    Sets agents.defaults.model to openai/gpt-5.5 through the Codex runtime when model is unset or already OpenAI-family.

    OpenAI API key

    Uses OPENAI_API_KEY if present or prompts for a key, then stores the credential in auth profiles.

    Sets agents.defaults.model to openai/gpt-5.5 when model is unset, openai/*, or legacy Codex model refs.

    xAI (Grok) OAuth

    Browser sign-in for eligible SuperGrok or X Premium accounts. This is the recommended xAI path for most users. OpenClaw stores the resulting auth profile for Grok models, Grok web_search, x_search, and code_execution.

    xAI (Grok) device code

    Remote-friendly browser sign-in with a short code instead of a localhost callback. Use this from SSH, Docker, or VPS hosts.

    xAI (Grok) API key

    Prompts for XAI_API_KEY and configures xAI as a model provider. Use this when you want an xAI Console API key instead of subscription OAuth.

    OpenCode

    Prompts for OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY) and lets you choose the Zen or Go catalog. Setup URL: opencode.ai/auth.

    API key (generic)

    Stores the key for you.

    Vercel AI Gateway

    Prompts for AI_GATEWAY_API_KEY. More detail: Vercel AI Gateway.

    Cloudflare AI Gateway

    Prompts for account ID, gateway ID, and CLOUDFLARE_AI_GATEWAY_API_KEY. More detail: Cloudflare AI Gateway.

    MiniMax

    Config is auto-written. Hosted default is MiniMax-M3; API-key setup uses minimax/..., and OAuth setup uses minimax-portal/.... More detail: MiniMax.

    StepFun

    Config is auto-written for StepFun standard or Step Plan on China or global endpoints. Standard currently includes step-3.5-flash, and Step Plan also includes step-3.5-flash-2603. More detail: StepFun.

    Synthetic (Anthropic-compatible)

    Prompts for SYNTHETIC_API_KEY. More detail: Synthetic.

    Ollama (Cloud and local open models)

    Prompts for Cloud + Local, Cloud only, or Local only first. Cloud only uses OLLAMA_API_KEY with https://ollama.com. The host-backed modes prompt for base URL (default http://127.0.0.1:11434), discover available models, and suggest defaults. Cloud + Local also checks whether that Ollama host is signed in for cloud access. More detail: Ollama.

    Moonshot and Kimi Coding

    Moonshot (Kimi K2) and Kimi Coding configs are auto-written. More detail: Moonshot AI (Kimi + Kimi Coding).

    Custom provider

    Works with OpenAI-compatible and Anthropic-compatible endpoints.

    Interactive onboarding supports the same API key storage choices as other provider API key flows:

    • Paste API key now (plaintext)
    • Use secret reference (env ref or configured provider ref, with preflight validation)

    Non-interactive flags:

    • --auth-choice custom-api-key
    • --custom-base-url
    • --custom-model-id
    • --custom-api-key (optional; falls back to CUSTOM_API_KEY)
    • --custom-provider-id (optional)
    • --custom-compatibility <openai|openai-responses|anthropic> (optional; default openai)
    • --custom-image-input / --custom-text-input (optional; override inferred model input capability)
    Skip

    Leaves auth unconfigured.

    Model behavior:

    • Pick default model from detected options, or enter provider and model manually.
    • Custom-provider onboarding infers image support for common model IDs and asks only when the model name is unknown.
    • When onboarding starts from a provider auth choice, the model picker prefers that provider automatically. For Volcengine and BytePlus, the same preference also matches their coding-plan variants (volcengine-plan/*, byteplus-plan/*).
    • If that preferred-provider filter would be empty, the picker falls back to the full catalog instead of showing no models.
    • Wizard runs a model check and warns if the configured model is unknown or missing auth.

    Credential and profile paths:

    • Auth profiles (API keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Legacy OAuth import: ~/.openclaw/credentials/oauth.json

    Credential storage mode:

    • Das standardmäßige Onboarding-Verhalten speichert API-Schlüssel als Klartextwerte in Auth-Profilen.
    • --secret-input-mode ref aktiviert den Referenzmodus anstelle der Speicherung von Klartextschlüsseln. In der interaktiven Einrichtung können Sie eine der folgenden Optionen wählen:
      • Umgebungsvariablen-Ref (zum Beispiel keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
      • konfigurierte Provider-Ref (file oder exec) mit Provider-Alias + ID
    • Der interaktive Referenzmodus führt vor dem Speichern eine schnelle Preflight-Validierung aus.
      • Env-Refs: validiert Variablenname + nicht leeren Wert in der aktuellen Onboarding-Umgebung.
      • Provider-Refs: validiert die Provider-Konfiguration und löst die angeforderte ID auf.
      • Wenn der Preflight fehlschlägt, zeigt das Onboarding den Fehler an und lässt Sie es erneut versuchen.
    • Im nicht interaktiven Modus ist --secret-input-mode ref ausschließlich env-gestützt.
      • Setzen Sie die Provider-Umgebungsvariable in der Prozessumgebung des Onboardings.
      • Inline-Schlüsselflags (zum Beispiel --openai-api-key) erfordern, dass diese Umgebungsvariable gesetzt ist; andernfalls schlägt das Onboarding schnell fehl.
      • Für benutzerdefinierte Provider speichert der nicht interaktive ref-Modus models.providers.<id>.apiKey als { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
      • In diesem Fall mit benutzerdefiniertem Provider erfordert --custom-api-key, dass CUSTOM_API_KEY gesetzt ist; andernfalls schlägt das Onboarding schnell fehl.
    • Gateway-Auth-Anmeldedaten unterstützen in der interaktiven Einrichtung die Auswahl zwischen Klartext und SecretRef:
      • Token-Modus: Klartext-Token generieren/speichern (Standard) oder SecretRef verwenden.
      • Passwortmodus: Klartext oder SecretRef.
    • Nicht interaktiver Token-SecretRef-Pfad: --gateway-token-ref-env &lt;ENV_VAR&gt;.
    • Vorhandene Klartext-Setups funktionieren unverändert weiter.

    Ausgaben und Interna

    Typische Felder in ~/.openclaw/openclaw.json:

    • agents.defaults.workspace
    • agents.defaults.skipBootstrap, wenn --skip-bootstrap übergeben wird
    • agents.defaults.model / models.providers (wenn Minimax ausgewählt wurde)
    • tools.profile (lokales Onboarding verwendet standardmäßig "coding", wenn nicht gesetzt; vorhandene explizite Werte bleiben erhalten)
    • gateway.* (Modus, Bind-Adresse, Auth, tailscale)
    • session.dmScope (lokales Onboarding setzt dies standardmäßig auf per-channel-peer, wenn nicht gesetzt; vorhandene explizite Werte bleiben erhalten)
    • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
    • Kanal-Zulassungslisten (Slack, Discord, Matrix, Microsoft Teams), wenn Sie sich während der Eingabeaufforderungen dafür entscheiden (Namen werden nach Möglichkeit zu IDs aufgelöst)
    • skills.install.nodeManager
      • Das Flag setup --node-manager akzeptiert npm, pnpm oder bun.
      • Die manuelle Konfiguration kann später weiterhin skills.install.nodeManager: "yarn" setzen.
    • wizard.lastRunAt
    • wizard.lastRunVersion
    • wizard.lastRunCommit
    • wizard.lastRunCommand
    • wizard.lastRunMode
    • wizard.securityAcknowledgedAt

    openclaw agents add schreibt agents.list[] und optionale bindings.

    WhatsApp-Anmeldedaten werden unter ~/.openclaw/credentials/whatsapp/<accountId>/ abgelegt. Sitzungen werden unter ~/.openclaw/agents/<agentId>/sessions/ gespeichert.

    Gateway-Assistent-RPC:

    • wizard.start
    • wizard.next
    • wizard.cancel
    • wizard.status

    Clients (macOS-App und Control UI) können Schritte rendern, ohne die Onboarding-Logik neu zu implementieren.

    Verhalten der Signal-Einrichtung:

    • Lädt das passende Release-Asset herunter
    • Speichert es unter ~/.openclaw/tools/signal-cli/<version>/
    • Schreibt channels.signal.cliPath in die Konfiguration
    • JVM-Builds erfordern Java 21
    • Native Builds werden verwendet, wenn verfügbar
    • Windows verwendet WSL2 und folgt dem Linux-signal-cli-Ablauf innerhalb von WSL

    Zugehörige Dokumentation

    Was this useful?
    On this page

    On this page