openclaw onboard: CLI Wizard Referenz

Kennst du das? Du startest ein neues Projekt und verbringst die erste Stunde damit, Konfigurationsdateien zu wälzen und API-Keys zu suchen. Es nervt, wenn der Setup-Prozess den Flow bremst, bevor du überhaupt die erste Zeile Code geschrieben hast.

Manuelle Konfigurationen sind oft zeitfressend. Wir empfehlen dir, den automatisierten Weg zu gehen, um schneller mit der eigentlichen Entwicklung zu beginnen.

Voraussetzungen

• openclaw CLI
• Terminal-Zugriff

Schnellstart

Der openclaw onboard Wizard ist der schnellste Weg, um alles einzurichten. Führe einfach diesen Befehl in deinem Terminal aus:

openclaw onboard

Dieser Wizard führt dich durch die gesamte Konfiguration, sodass du dich nicht um Details in den Config-Dateien kümmern musst.

Fehlerbehebung

In der aktuellen Referenz sind keine spezifischen Probleme für diesen Befehl aufgeführt. Wenn etwas nicht wie erwartet funktioniert, überprüfe deine CLI-Version.

AI Setup Assistant

Nächste Schritte

• Onboarding Wizard

Kennst du das? Du willst nur kurz ein neues Tool ausprobieren, aber verbringst die erste Stunde damit, kryptische Config-Dateien zu biegen oder deine API-Keys zum zehnten Mal manuell einzutragen. Meistens scheitert es dann an einer Kleinigkeit wie einem fehlenden Token oder einer falschen Port-Bindung.

Wir haben den Setup-Prozess so gebaut, dass er dir die Arbeit abnimmt, ohne dich zu bevormunden. Hier erfährst du genau, was unter der Haube passiert, wenn du den Wizard im Local Mode startest.

Voraussetzungen

Bevor du loslegst, stelle sicher, dass du folgende Dinge bereit hast (basierend auf deinen Anforderungen):

• Ein Terminal mit Node.js (empfohlen; Bun wird nicht empfohlen)
• Deine API-Keys (z. B. Anthropic, OpenAI, xAI oder OpenCode Zen)
• Zugriff auf ~/.openclaw/ (für Config und Workspace)
• Unter macOS: Zugriff auf den Keychain für OAuth-Credentials

Quick Start: In 5 Minuten startklar

Der Wizard führt dich durch die wichtigsten Stationen. Hier ist der schnellste Weg zum laufenden System:

1. Config-Erkennung

Wenn eine ~/.openclaw/openclaw.json existiert, fragt dich der Wizard, ob du sie behalten, ändern oder zurücksetzen willst.

• Ein erneuter Durchlauf löscht nichts, außer du wählst Reset oder nutzt den CLI-Flag --reset.
• Mit --reset-scope full entfernst du zusätzlich den Workspace.
• Bei ungültigen Configs oder veralteten Keys stoppt der Wizard; führe dann openclaw doctor aus.
• Reset nutzt trash statt rm und bietet Scopes für Config, Credentials oder das volle Paket.

2. Model und Authentifizierung

Du hast die Wahl zwischen verschiedenen Providern. Wähle für die beste Qualität und geringeres Prompt-Injection-Risiko immer das stärkste Modell der neuesten Generation.

• Anthropic: Nutzt ANTHROPIC_API_KEY oder fragt den Key ab.
• Anthropic OAuth: Unter macOS wird das Keychain-Item “Claude Code-credentials” genutzt (wähle “Always Allow”). Unter Linux/Windows wird ~/.claude/.credentials.json verwendet.
• OpenAI API: Nutzt OPENAI_API_KEY oder speichert den Key in Auth-Profiles.
• OpenAI Code (Codex): Erkennt ~/.codex/auth.json oder nutzt den Browser-Flow (kopiere code#state). Setzt das Modell automatisch auf openai-codex/gpt-5.2.
• Spezial-Provider: Unterstützt xAI (Grok), Moonshot (Kimi K2), MiniMax M2.5 und Synthetic.
• Proxies: OpenCode Zen (OPENCODE_API_KEY), Vercel AI Gateway oder Cloudflare AI Gateway (Account ID + Gateway ID erforderlich).

Standardmäßig werden Keys im Plaintext gespeichert. Nutze --secret-input-mode ref, um stattdessen umgebungsbasierte Referenzen (z. B. keyRef) zu verwenden.

3. Gateway und Workspace

Der Workspace landet standardmäßig in ~/.openclaw/workspace. Hier werden alle Dateien für das Agent-Bootstrap-Ritual abgelegt.

Beim Gateway konfigurierst du Port und Auth-Modus:

• Auth-Empfehlung: Behalte den Token-Modus auch für Loopback-Verbindungen bei.
• SecretRef: Du kannst Token über Umgebungsvariablen (--gateway-token-ref-env <ENV_VAR>) einbinden.
• Deaktiviere die Authentifizierung nur, wenn du jedem lokalen Prozess absolut vertraust.

4. Channels und Skills

Verbinde OpenClaw mit deinen Kommunikationstools:

• Messenger: WhatsApp (QR-Login), Telegram (Bot Token) oder Discord.
• iMessage: Nutze BlueBubbles (empfohlen; Server URL + Passwort) oder den legacy imsg CLI-Pfad.
• Skills: Wähle einen Node-Manager (npm oder pnpm). Der Wizard installiert Abhängigkeiten und nutzt unter macOS teilweise Homebrew.

5. Daemon-Installation

Damit alles im Hintergrund läuft, installiert der Wizard einen Dienst:

• macOS: LaunchAgent (erfordert aktiven User-Login).
• Linux: systemd User-Unit. Der Wizard versucht loginctl enable-linger zu aktivieren, damit das Gateway nach dem Logout online bleibt.

Fehlerbehebung

Falls etwas hakt, sind das die häufigsten Szenarien aus der Dokumentation:

• Keine GUI erkannt: Wenn kein Browser geöffnet werden kann, gibt der Wizard Instruktionen für SSH-Port-Forwarding aus, um das Control UI zu erreichen.
• Fehlende UI-Assets: Der Wizard versucht diese mit pnpm ui:build selbst zu bauen.
• Daemon-Blockade: Wenn gateway.auth.token als SecretRef konfiguriert, aber nicht auflösbar ist, bricht die Installation mit einer Anleitung zur Fehlerbehebung ab.
• OAuth auf Headless-Servern: Schließe den OAuth-Flow auf einem Rechner mit Browser ab und kopiere die ~/.openclaw/credentials/oauth.json auf den Ziel-Host.

Du hast noch Fragen zum Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Vercel AI Gateway Guide
• Cloudflare AI Gateway Details
• Agent Workspace Konzepte
• OAuth Deep Dive
• WhatsApp Integration
• BlueBubbles für iMessage

Kennst du das? Du willst ein Tool auf mehreren Servern ausrollen oder in ein Skript einbauen, aber der Installer stellt dir ständig Fragen. Das nervt und hält den Workflow auf.

Wenn du Workflows automatisieren willst, brauchst du einen Weg, der ohne menschliches Zutun auskommt. Der Non-interactive mode ist hier die beste Lösung, um das Onboarding schnell und reproduzierbar zu machen.

Voraussetzungen

Bevor du startest, stelle sicher, dass du diese Dinge bereit hast:

• Die entsprechenden API Keys (z. B. Anthropic, Gemini)
• Node.js (falls du den Daemon-Runtime nutzt)
• Deine bevorzugten Port- und Bind-Konfigurationen

Schnellstart

Mit dem Flag --non-interactive überspringst du alle manuellen Abfragen. Hier ist der schnellste Weg, um openclaw mit Anthropic und einem installierten Daemon zu starten:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

Wenn du eine maschinenlesbare Zusammenfassung brauchst, hänge einfach --json an den Befehl an.

Gateway Token mit SecretRef

In automatisierten Umgebungen solltest du Token nicht direkt im Befehl übergeben. Nutze stattdessen Environment Variables:

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

Weitere Provider-Beispiele

Hier findest du die passenden Befehle für andere Provider:

Gemini example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice gemini-api-key \
      --gemini-api-key "$GEMINI_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Z.AI example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice zai-api-key \
      --zai-api-key "$ZAI_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Vercel AI Gateway example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice ai-gateway-api-key \
      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Cloudflare AI Gateway example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice cloudflare-ai-gateway-api-key \
      --cloudflare-ai-gateway-account-id "your-account-id" \
      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Moonshot example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice moonshot-api-key \
      --moonshot-api-key "$MOONSHOT_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Synthetic example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice synthetic-api-key \
      --synthetic-api-key "$SYNTHETIC_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

OpenCode Zen example

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice opencode-zen \
      --opencode-zen-api-key "$OPENCODE_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Agenten hinzufügen

Auch das Hinzufügen von Agenten funktioniert ohne Interaktion. Das ist ideal, um spezifische Workspaces vorzukonfigurieren:

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Fehlerbehebung

Hier sind zwei Dinge, auf die du achten musst, wenn deine Skripte fehlschlagen:

• Konflikt bei Gateway-Optionen: Die Flags --gateway-token und --gateway-token-ref-env schließen sich gegenseitig aus. Du darfst nur eines von beiden verwenden.
• JSON vs. Interaktivität: Das Flag --json aktiviert nicht automatisch den Non-interactive mode. Für Skripte musst du explizit --non-interactive (und oft auch --workspace) angeben.

Hast du Fragen zur Einrichtung? Unser AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Erfahre mehr über die Agenten-Konfiguration
• Details zum Gateway-Setup

Viel zu oft verbringen wir Zeit damit, komplexe Onboarding-Logik für jede Plattform einzeln zu bauen. Das nervt, ist fehleranfällig und führt dazu, dass sich die macOS App anders verhält als das Web-Interface.

Anstatt die Logik überall neu zu implementieren, solltest du sie direkt vom Gateway steuern lassen. Das spart Zeit und sorgt für eine konsistente Experience.

Voraussetzungen

• Java 21: Zwingend erforderlich für JVM builds.
• WSL2: Falls du auf Windows arbeitest, da die Installation dort dem Linux-Flow folgt.

Schnellstart

Das Gateway stellt den wizard flow direkt über RPC bereit. Das bedeutet, dass Clients wie die macOS App oder das Control UI die einzelnen Schritte einfach rendern können, ohne die zugrunde liegende Logik zu kennen.

Verwende diese RPC-Methoden für die Steuerung:

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

Signal setup mit signal-cli

Der Wizard übernimmt die Installation von signal-cli direkt aus den GitHub Releases. Das ist der empfohlene Weg, um schnell startklar zu sein:

1. Der Wizard lädt das passende Release-Asset herunter.
2. Die Dateien werden unter ~/.openclaw/tools/signal-cli/<version>/ gespeichert.
3. Der Pfad wird automatisch in deine Config als channels.signal.cliPath eingetragen.

Das Gateway bevorzugt native builds, sofern diese verfügbar sind. Wenn du auf Windows unterwegs bist, achte darauf, dass alles innerhalb von WSL2 läuft.

Fehlerbehebung

• JVM builds starten nicht: Überprüfe deine Java-Version. Du benötigst zwingend Java 21, damit die Builds korrekt ausgeführt werden.
• Fehler unter Windows: Die Installation von signal-cli folgt unter Windows dem Linux-Flow. Stelle sicher, dass dein WSL2 korrekt konfiguriert ist.

Du hast Fragen zu einem spezifischen Schritt? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Gateway RPC API Dokumentation
• Signal Channel Konfiguration
• CLI Referenz
• Environment Variablen

Kennst du das? Du startest ein neues Tool, lässt einen Setup-Wizard laufen und alles funktioniert sofort. Aber kurz darauf fragst du dich, was eigentlich im Hintergrund passiert ist und wo genau deine Daten gelandet sind. Wenn du die volle Kontrolle über deine Umgebung behalten willst, ist es wichtig, die erzeugten Konfigurationsdateien zu verstehen.

Es ist frustrierend, wenn Tools eine “Black Box” bleiben. Du möchtest wissen, welche API-Keys wo gespeichert wurden und wie die Verzeichnisstruktur aussieht, damit du Backups machen oder manuelle Anpassungen vornehmen kannst.

Voraussetzungen

• Eine installierte Version von OpenClaw
• Zugriff auf dein Home-Verzeichnis (~/.openclaw/)

Schnellstart

Der Wizard schreibt seine Daten primär in die Datei ~/.openclaw/openclaw.json. Hier ist eine Übersicht der Felder, die du dort findest:

• Allgemeine Agenten-Einstellungen: agents.defaults.workspace legt den Arbeitsbereich fest.
• Modell-Konfiguration: Unter agents.defaults.model oder models.providers (falls du Minimax nutzt) werden die KI-Modelle definiert.
• Tools: Das Feld tools.profile wird beim lokalen Onboarding standardmäßig auf "coding" gesetzt, sofern es nicht bereits definiert ist. Bestehende Werte bleiben erhalten.
• Gateway: Einstellungen zu gateway.* wie mode, bind, auth und tailscale.
• Session-Verhalten: session.dmScope steuert spezifische Verhaltensweisen. Details dazu findest du in der CLI Onboarding Reference.
• Channel-Credentials: Hier landen Tokens für channels.telegram.botToken, channels.discord.token, channels.signal.* oder channels.imessage.*.
• Allowlists: Wenn du dich während der Prompts dafür entscheidest, werden Allowlists für Slack, Discord, Matrix oder Microsoft Teams angelegt. Namen werden dabei nach Möglichkeit in IDs aufgelöst.
• System-Werte: skills.install.nodeManager sowie Metadaten zum Wizard-Lauf wie wizard.lastRunAt, wizard.lastRunVersion, wizard.lastRunCommit, wizard.lastRunCommand und wizard.lastRunMode.

Wenn du den Befehl openclaw agents add ausführst, werden Einträge in agents.list[] und optionale bindings geschrieben.

Für bestimmte Daten nutzt OpenClaw separate Pfade:

• WhatsApp: Deine Credentials liegen unter ~/.openclaw/credentials/whatsapp/<accountId>/.
• Sessions: Verlaufsdaten werden unter ~/.openclaw/agents/<agentId>/sessions/ gespeichert.

Einige Channels funktionieren als Plugins. Wenn du einen solchen Channel während des Onboardings auswählst, fordert dich der Wizard auf, diesen via npm oder über einen lokalen Pfad zu installieren, bevor die Konfiguration abgeschlossen werden kann.

Fehlerbehebung

• Fehlendes Profil: Wenn tools.profile nicht gesetzt ist, nutzt der Wizard automatisch den Wert "coding". Prüfe die Datei manuell, falls du ein anderes Profil erwartest.
• Plugin-Installation: Falls ein Channel nicht konfiguriert werden kann, stelle sicher, dass du der Aufforderung zur Installation (npm/lokaler Pfad) gefolgt bist. Ohne diesen Schritt kann der Wizard die Konfiguration nicht abschließen.

Du hast Fragen zu deinem spezifischen Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Erfahre mehr im Wizard overview
• Details zur macOS app onboarding
• Schau in die Gateway configuration
• Informationen zu Providern: WhatsApp, Telegram, Discord, Google Chat, Signal, BlueBubbles, iMessage
• Alles über Skills und die Skills config