CLI-Onboarding-Referenz

Diese Seite ist die vollstandige Referenz fur openclaw onboard. Fur die Kurzanleitung siehe Onboarding-Wizard (CLI).

Was der Wizard macht

Lokaler Modus (Standard) fuhrt dich durch:

• Model- und Auth-Setup (OpenAI Code Subscription OAuth, Anthropic API Key oder Setup-Token, dazu MiniMax, GLM, Ollama, Moonshot und AI-Gateway-Optionen)
• Workspace-Speicherort und Bootstrap-Dateien
• Gateway-Einstellungen (Port, Bind, Auth, Tailscale)
• Channels und Provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost-Plugin, Signal)
• Daemon-Installation (LaunchAgent oder systemd-User-Unit)
• Health Check
• Skills-Setup

Remote-Modus konfiguriert diese Maschine, um sich mit einem Gateway anderswo zu verbinden. Er installiert oder andert nichts auf dem Remote-Host.

Lokaler Flow im Detail

Schritt 1: Erkennung vorhandener Config

- Wenn `~/.openclaw/openclaw.json` existiert: Behalten, Andern oder Zurucksetzen.
- Ein erneuter Wizard-Durchlauf loscht nichts, es sei denn, du wahlst explizit Zurucksetzen (oder ubergibst `--reset`).
- CLI `--reset` setzt standardmassig `config+creds+sessions` zuruck; mit `--reset-scope full` wird auch der Workspace einbezogen.
- Ist die Config ungultig oder enthalt Legacy-Keys, stoppt der Wizard und fordert dich auf, `openclaw doctor` auszufuhren, bevor es weitergeht.
- Reset nutzt `trash` und bietet Scopes:
  - Nur Config
  - Config + Credentials + Sessions
  - Vollstandiger Reset (entfernt auch Workspace)

Schritt 2: Model und Auth

- Die vollstandige Optionsmatrix findest du unter [Auth- und Model-Optionen](#auth--und-model-optionen).

Schritt 3: Workspace

- Standard `~/.openclaw/workspace` (konfigurierbar).
- Legt Workspace-Dateien fur das First-Run-Bootstrap-Ritual an.
- Workspace-Layout: [Agent Workspace](/docs/concepts/agent-workspace).

Schritt 4: Gateway

- Fragt nach Port, Bind, Auth-Modus und Tailscale-Exposure.
- Empfehlung: Token-Auth auch fur Loopback aktiviert lassen, damit sich lokale WS-Clients authentifizieren mussen.
- Im Token-Modus bietet das interaktive Onboarding:
  - **Klartext-Token generieren/speichern** (Standard)
  - **SecretRef verwenden** (Opt-in)
- Im Passwort-Modus unterstutzt das interaktive Onboarding ebenfalls Klartext- oder SecretRef-Speicherung.
- Non-Interactive Token-SecretRef-Pfad: `--gateway-token-ref-env <ENV_VAR>`.
  - Erfordert eine nicht-leere Env-Variable in der Onboarding-Prozessumgebung.
  - Kann nicht mit `--gateway-token` kombiniert werden.
- Auth nur deaktivieren, wenn du jedem lokalen Prozess vollstandig vertraust.
- Non-Loopback-Binds erfordern weiterhin Auth.

Schritt 5: Channels

- [WhatsApp](/docs/channels/whatsapp): optionaler QR-Login
- [Telegram](/docs/channels/telegram): Bot-Token
- [Discord](/docs/channels/discord): Bot-Token
- [Google Chat](/docs/channels/googlechat): Service-Account-JSON + Webhook-Audience
- [Mattermost](/docs/channels/mattermost)-Plugin: Bot-Token + Base-URL
- [Signal](/docs/channels/signal): optionale `signal-cli`-Installation + Account-Config
- [BlueBubbles](/docs/channels/bluebubbles): empfohlen fur iMessage; Server-URL + Passwort + Webhook
- [iMessage](/docs/channels/imessage): Legacy-`imsg`-CLI-Pfad + DB-Zugriff
- DM-Sicherheit: Standard ist Pairing. Die erste DM sendet einen Code; Freigabe via
  `openclaw pairing approve <channel> <code>` oder uber Allowlists.

Schritt 6: Daemon-Installation

- macOS: LaunchAgent
  - Erfordert eingeloggte User-Session; fur Headless einen eigenen LaunchDaemon verwenden (wird nicht mitgeliefert).
- Linux und Windows via WSL2: systemd-User-Unit
  - Der Wizard versucht `loginctl enable-linger <user>`, damit das Gateway nach dem Logout weiterlauft.
  - Kann nach sudo fragen (schreibt `/var/lib/systemd/linger`); versucht es zuerst ohne sudo.
- Runtime-Auswahl: Node (empfohlen; erforderlich fur WhatsApp und Telegram). Bun wird nicht empfohlen.

Schritt 7: Health Check

- Startet das Gateway (falls notig) und fuhrt `openclaw health` aus.
- `openclaw status --deep` fugt Gateway-Health-Probes zur Status-Ausgabe hinzu.

Schritt 8: Skills

- Liest verfugbare Skills und pruft Anforderungen.
- Lasst dich den Node-Manager wahlen: npm oder pnpm (Bun nicht empfohlen).
- Installiert optionale Abhangigkeiten (manche nutzen Homebrew auf macOS).

Schritt 9: Abschluss

- Zusammenfassung und nachste Schritte, inklusive iOS-, Android- und macOS-App-Optionen.

Hinweis: Wird keine GUI erkannt, gibt der Wizard SSH-Port-Forward-Anweisungen fur die Control UI aus, statt einen Browser zu offnen. Fehlen die Control-UI-Assets, versucht der Wizard sie zu bauen; Fallback ist pnpm ui:build (installiert UI-Deps automatisch).

Remote-Modus im Detail

Remote-Modus konfiguriert diese Maschine, um sich mit einem Gateway anderswo zu verbinden.

Info: Der Remote-Modus installiert oder andert nichts auf dem Remote-Host.

Was du einstellst:

• Remote-Gateway-URL (ws://...)
• Token, falls Remote-Gateway-Auth erforderlich ist (empfohlen)

Hinweis:

• Ist das Gateway nur auf Loopback gebunden, verwende SSH-Tunneling oder ein Tailnet.
• Discovery-Hinweise:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Auth- und Model-Optionen

Nutzt `ANTHROPIC_API_KEY`, falls vorhanden, oder fragt nach einem Key und speichert ihn fur den Daemon-Betrieb.

- macOS: Pruft Keychain-Eintrag "Claude Code-credentials"
- Linux und Windows: Nutzt `~/.claude/.credentials.json`, falls vorhanden

Auf macOS "Immer erlauben" wahlen, damit launchd-Starts nicht blockiert werden.

Fuhre `claude setup-token` auf einer beliebigen Maschine aus und fuge den Token ein.
Du kannst ihm einen Namen geben; leer lassen fur den Standard.

Wenn `~/.codex/auth.json` existiert, kann der Wizard sie wiederverwenden.

Browser-Flow; `code#state` einfugen.

Setzt `agents.defaults.model` auf `openai-codex/gpt-5.4`, wenn das Model ungesetzt oder `openai/*` ist.

Nutzt `OPENAI_API_KEY`, falls vorhanden, oder fragt nach einem Key und speichert den Credential in Auth-Profilen.

Setzt `agents.defaults.model` auf `openai/gpt-5.1-codex`, wenn das Model ungesetzt, `openai/*` oder `openai-codex/*` ist.

Fragt nach `XAI_API_KEY` und konfiguriert xAI als Model-Provider.

Fragt nach `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`) und lasst dich zwischen Zen- und Go-Katalog wahlen.
Setup-URL: [opencode.ai/auth](https://opencode.ai/auth).

Speichert den Key fur dich.

Fragt nach `AI_GATEWAY_API_KEY`.
Mehr dazu: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Fragt nach Account-ID, Gateway-ID und `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Mehr dazu: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

Config wird automatisch geschrieben.
Mehr dazu: [MiniMax](/docs/providers/minimax).

Fragt nach `SYNTHETIC_API_KEY`.
Mehr dazu: [Synthetic](/docs/providers/synthetic).

Fragt nach Base-URL (Standard `http://127.0.0.1:11434`), bietet dann Cloud + Local oder Local-Modus an.
Erkennt verfugbare Modelle und schlagt Defaults vor.
Mehr dazu: [Ollama](/docs/providers/ollama).

Moonshot (Kimi K2) und Kimi-Coding-Configs werden automatisch geschrieben.
Mehr dazu: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Funktioniert mit OpenAI-kompatiblen und Anthropic-kompatiblen Endpoints.

Das interaktive Onboarding unterstutzt dieselben API-Key-Speicheroptionen wie andere Provider-API-Key-Flows:
- **API Key jetzt einfugen** (Klartext)
- **Secret Reference verwenden** (Env-Ref oder konfigurierte Provider-Ref, mit Preflight-Validierung)

Non-Interactive-Flags:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (optional; Fallback auf `CUSTOM_API_KEY`)
- `--custom-provider-id` (optional)
- `--custom-compatibility <openai|anthropic>` (optional; Standard `openai`)

Lasst Auth unkonfiguriert.

Model-Verhalten:

• Standard-Model aus erkannten Optionen wahlen oder Provider und Model manuell eingeben.
• Der Wizard fuhrt einen Model-Check durch und warnt, falls das konfigurierte Model unbekannt ist oder Auth fehlt.

Credential- und Profil-Pfade:

• OAuth-Credentials: ~/.openclaw/credentials/oauth.json
• Auth-Profile (API Keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Credential-Speichermodus:

• Standard-Onboarding speichert API Keys als Klartext-Werte in Auth-Profilen.
• --secret-input-mode ref aktiviert den Reference-Modus statt Klartext-Speicherung. Im interaktiven Onboarding kannst du wahlen zwischen:
  • Umgebungsvariablen-Ref (z. B. keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • Konfigurierter Provider-Ref (file oder exec) mit Provider-Alias + ID
• Im interaktiven Reference-Modus lauft eine schnelle Preflight-Validierung vor dem Speichern.
  • Env-Refs: Validiert Variablenname + nicht-leeren Wert in der aktuellen Onboarding-Umgebung.
  • Provider-Refs: Validiert Provider-Config und lost die angefragte ID auf.
  • Schlagt die Preflight-Prufung fehl, zeigt das Onboarding den Fehler an und lasst dich erneut versuchen.
• Im Non-Interactive-Modus ist --secret-input-mode ref nur Env-basiert.
  • Setze die Provider-Env-Variable in der Onboarding-Prozessumgebung.
  • Inline-Key-Flags (z. B. --openai-api-key) erfordern, dass diese Env-Variable gesetzt ist; andernfalls scheitert das Onboarding sofort.
  • Fur Custom Provider speichert der Non-Interactive ref-Modus models.providers.<id>.apiKey als { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • In diesem Custom-Provider-Fall erfordert --custom-api-key, dass CUSTOM_API_KEY gesetzt ist; andernfalls scheitert das Onboarding sofort.
• Gateway-Auth-Credentials unterstutzen Klartext- und SecretRef-Optionen im interaktiven Onboarding:
  • Token-Modus: Klartext-Token generieren/speichern (Standard) oder SecretRef verwenden.
  • Passwort-Modus: Klartext oder SecretRef.
• Non-Interactive Token-SecretRef-Pfad: --gateway-token-ref-env <ENV_VAR>.
• Bestehende Klartext-Setups funktionieren unverandert weiter.

Hinweis: Headless- und Server-Tipp: Schliesse OAuth auf einer Maschine mit Browser ab und kopiere dann ~/.openclaw/credentials/oauth.json (oder $OPENCLAW_STATE_DIR/credentials/oauth.json) auf den Gateway-Host.

Outputs und Interna

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

• agents.defaults.workspace
• agents.defaults.model / models.providers (falls Minimax gewahlt)
• tools.profile (lokales Onboarding setzt standardmassig "coding", wenn nicht gesetzt; vorhandene explizite Werte bleiben erhalten)
• gateway.* (Mode, Bind, Auth, Tailscale)
• session.dmScope (lokales Onboarding setzt standardmassig per-channel-peer, wenn nicht gesetzt; vorhandene explizite Werte bleiben erhalten)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Channel-Allowlists (Slack, Discord, Matrix, Microsoft Teams), wenn du bei den Prompts zustimmst (Namen werden wenn moglich zu IDs aufgelost)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

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

WhatsApp-Credentials liegen unter ~/.openclaw/credentials/whatsapp/<accountId>/. Sessions werden unter ~/.openclaw/agents/<agentId>/sessions/ gespeichert.

Hinweis: Manche Channels werden als Plugins ausgeliefert. Werden sie wahrend des Onboardings ausgewahlt, fordert der Wizard zur Plugin-Installation auf (npm oder lokaler Pfad), bevor die Channel-Konfiguration beginnt.

Gateway-Wizard-RPC:

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

Clients (macOS-App und Control UI) konnen Steps rendern, ohne die Onboarding-Logik nachbauen zu mussen.

Signal-Setup-Verhalten:

• Ladt das passende Release-Asset herunter
• Speichert es unter ~/.openclaw/tools/signal-cli/<version>/
• Schreibt channels.signal.cliPath in die Config
• JVM-Builds erfordern Java 21
• Native Builds werden verwendet, wenn verfugbar
• Windows nutzt WSL2 und folgt dem Linux-signal-cli-Flow innerhalb von WSL

Verwandte Docs

• Onboarding-Hub: Onboarding-Wizard (CLI)
• Automatisierung und Skripte: CLI-Automatisierung
• Befehlsreferenz: openclaw onboard