Onboarding Wizard (CLI)

Der Onboarding Wizard ist die empfohlene Methode, um OpenClaw auf macOS, Linux oder Windows (via WSL2; dringend empfohlen) einzurichten. Er konfiguriert ein lokales Gateway oder eine Remote-Gateway-Verbindung, plus Channels, Skills und Workspace-Standardeinstellungen in einem geführten Ablauf.

Haupteinstiegspunkt:

openclaw onboard

Schnellster erster Chat: Öffne die Control UI (kein Channel-Setup nötig). Führe openclaw dashboard aus und chatte im Browser. Docs: Dashboard.

Nachträgliche Neukonfiguration:

openclaw configure

Empfohlen: Richte einen Brave Search API Key ein, damit der Agent web_search nutzen kann (web_fetch funktioniert ohne Key). Einfachster Weg: openclaw configure --section web, das speichert tools.web.search.apiKey. Docs: Web tools.

QuickStart vs Advanced

Der Wizard startet mit QuickStart (Standardwerte) vs Advanced (volle Kontrolle).

QuickStart behält die Standardwerte:

  • Lokales Gateway (loopback)
  • Workspace-Standard (oder vorhandener Workspace)
  • Gateway-Port 18789
  • Gateway-Auth Token (automatisch generiert, auch bei loopback)
  • Tailscale-Freigabe Aus
  • Telegram + WhatsApp DMs nutzen standardmäßig Allowlist (du wirst nach deiner Telefonnummer gefragt)

Advanced zeigt jeden Schritt (Modus, Workspace, Gateway, Channels, Daemon, Skills).

Was der Wizard macht

Local mode (Standard) führt dich durch:

  • Model/Auth (OpenAI Code (Codex) Subscription OAuth, Anthropic API Key (empfohlen) oder setup-token (einfügen), plus MiniMax/GLM/Moonshot/AI Gateway Optionen)
  • Workspace-Speicherort + Bootstrap-Dateien
  • Gateway-Einstellungen (Port/Bind/Auth/Tailscale)
  • Provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost (Plugin), Signal)
  • Daemon-Installation (LaunchAgent / systemd user unit)
  • Health Check
  • Skills (empfohlen)

Remote mode konfiguriert nur den lokalen Client, um sich mit einem Gateway woanders zu verbinden. Er installiert oder ändert nichts auf dem Remote-Host.

Um weitere isolierte Agents hinzuzufügen (separater Workspace + Sessions + Auth), nutze:

openclaw agents add <name>

Tipp: --json bedeutet nicht non-interactive mode. Nutze --non-interactive (und --workspace) für Skripte.

Flow-Details (lokal)

  1. Erkennung vorhandener Config

    • Falls ~/.openclaw/openclaw.json existiert, wähle Keep / Modify / Reset.
    • Erneutes Ausführen des Wizards löscht nichts, außer du wählst explizit Reset (oder übergibst --reset).
    • Falls die Config ungültig ist oder Legacy-Keys enthält, stoppt der Wizard und bittet dich, openclaw doctor auszuführen, bevor es weitergeht.
    • Reset nutzt trash (niemals rm) und bietet Bereiche an:
      • Nur Config
      • Config + Credentials + Sessions
      • Vollständiger Reset (entfernt auch Workspace)

  2. Model/Auth

    • Anthropic API Key (empfohlen): nutzt ANTHROPIC_API_KEY falls vorhanden oder fragt nach einem Key, speichert ihn dann für Daemon-Nutzung.
    • Anthropic OAuth (Claude Code CLI): auf macOS prüft der Wizard das Keychain-Item “Claude Code-credentials” (wähle “Always Allow”, damit launchd-Starts nicht blockieren); auf Linux/Windows wird ~/.claude/.credentials.json wiederverwendet, falls vorhanden.
    • Anthropic Token (setup-token einfügen): führe claude setup-token auf einem beliebigen Rechner aus, dann füge den Token ein (du kannst ihn benennen; leer = default).
    • OpenAI Code (Codex) Subscription (Codex CLI): falls ~/.codex/auth.json existiert, kann der Wizard es wiederverwenden.
    • OpenAI Code (Codex) Subscription (OAuth): Browser-Flow; füge den code#state ein.
      • Setzt agents.defaults.model auf openai-codex/gpt-5.2, wenn das Modell nicht gesetzt ist oder openai/*.
    • OpenAI API Key: nutzt OPENAI_API_KEY falls vorhanden oder fragt nach einem Key, speichert ihn dann in ~/.openclaw/.env, damit launchd ihn lesen kann.
    • OpenCode Zen (Multi-Model-Proxy): fragt nach OPENCODE_API_KEY (oder OPENCODE_ZEN_API_KEY, erhältlich unter https://opencode.ai/auth).
    • API Key: speichert den Key für dich.
    • Vercel AI Gateway (Multi-Model-Proxy): fragt nach AI_GATEWAY_API_KEY.
    • Mehr Details: Vercel AI Gateway
    • MiniMax M2.1: Config wird automatisch geschrieben.
    • Mehr Details: MiniMax
    • Synthetic (Anthropic-kompatibel): fragt nach SYNTHETIC_API_KEY.
    • Mehr Details: Synthetic
    • Moonshot (Kimi K2): Config wird automatisch geschrieben.
    • Kimi Coding: Config wird automatisch geschrieben.
    • Mehr Details: Moonshot AI (Kimi + Kimi Coding)
    • Skip: noch keine Auth konfiguriert.
    • Wähle ein Standardmodell aus den erkannten Optionen (oder gib Provider/Modell manuell ein).
    • Der Wizard führt einen Modell-Check durch und warnt, falls das konfigurierte Modell unbekannt ist oder Auth fehlt.
  • OAuth-Credentials liegen in ~/.openclaw/credentials/oauth.json; Auth-Profile liegen in ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (API Keys + OAuth).
  • Mehr Details: /concepts/oauth

  1. Workspace

    • Standard ~/.openclaw/workspace (konfigurierbar).
    • Erstellt die Workspace-Dateien, die für das Agent-Bootstrap-Ritual benötigt werden.
    • Vollständiges Workspace-Layout + Backup-Guide: Agent Workspace

  2. Gateway

    • Port, Bind, Auth-Modus, Tailscale-Freigabe.
    • Auth-Empfehlung: behalte Token auch für loopback, damit lokale WS-Clients sich authentifizieren müssen.
    • Deaktiviere Auth nur, wenn du jedem lokalen Prozess vollständig vertraust.
    • Non-loopback-Binds erfordern weiterhin Auth.

  3. Channels

    • WhatsApp: optionaler QR-Login.
    • Telegram: Bot-Token.
    • Discord: Bot-Token.
    • Google Chat: Service-Account-JSON + Webhook-Audience.
    • Mattermost (Plugin): Bot-Token + Base-URL.
    • Signal: optionale signal-cli-Installation + Account-Config.
    • iMessage: lokaler imsg CLI-Pfad + DB-Zugriff.
    • DM-Sicherheit: Standard ist Pairing. Die erste DM sendet einen Code; genehmige via openclaw pairing approve <channel> <code> oder nutze Allowlists.

  4. Daemon-Installation

    • macOS: LaunchAgent
      • Erfordert eine angemeldete User-Session; für Headless nutze einen eigenen LaunchDaemon (nicht mitgeliefert).
    • Linux (und Windows via WSL2): systemd user unit
      • Der Wizard versucht, Lingering via loginctl enable-linger <user> zu aktivieren, damit das Gateway nach dem Logout aktiv bleibt.
      • Kann nach sudo fragen (schreibt /var/lib/systemd/linger); versucht es zuerst ohne sudo.
    • Runtime-Auswahl: Node (empfohlen; erforderlich für WhatsApp/Telegram). Bun ist nicht empfohlen.

  5. Health Check

    • Startet das Gateway (falls nötig) und führt openclaw health aus.
    • Tipp: openclaw status --deep fügt Gateway-Health-Probes zur Status-Ausgabe hinzu (erfordert ein erreichbares Gateway).

  6. Skills (empfohlen)

    • Liest die verfügbaren Skills und prüft Anforderungen.
    • Lässt dich einen Node-Manager wählen: npm / pnpm (bun nicht empfohlen).
    • Installiert optionale Abhängigkeiten (einige nutzen Homebrew auf macOS).

  7. Fertig

    • Zusammenfassung + nächste Schritte, einschließlich iOS/Android/macOS-Apps für zusätzliche Features.
  • Falls keine GUI erkannt wird, druckt der Wizard SSH-Port-Forward-Anweisungen für die Control UI, anstatt einen Browser zu öffnen.
  • Falls die Control-UI-Assets fehlen, versucht der Wizard, sie zu bauen; Fallback ist pnpm ui:build (installiert UI-Deps automatisch).

Remote mode

Remote mode konfiguriert einen lokalen Client, um sich mit einem Gateway woanders zu verbinden.

Was du einstellst:

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

Hinweise:

  • Keine Remote-Installationen oder Daemon-Änderungen werden durchgeführt.
  • Falls das Gateway nur loopback ist, nutze SSH-Tunneling oder ein Tailnet.
  • Discovery-Hinweise:
    • macOS: Bonjour (dns-sd)
    • Linux: Avahi (avahi-browse)

Weiteren Agent hinzufügen

Nutze openclaw agents add <name>, um einen separaten Agent mit eigenem Workspace, Sessions und Auth-Profilen zu erstellen. Ausführen ohne --workspace startet den Wizard.

Was es setzt:

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

Hinweise:

  • Standard-Workspaces folgen ~/.openclaw/workspace-<agentId>.
  • Füge bindings hinzu, um eingehende Nachrichten zu routen (der Wizard kann das machen).
  • Non-interactive-Flags: --model, --agent-dir, --bind, --non-interactive.

Non-interactive mode

Nutze --non-interactive, um Onboarding zu automatisieren oder zu skripten:

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

Füge --json für eine maschinenlesbare Zusammenfassung hinzu.

Gemini-Beispiel:

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

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

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

Moonshot-Beispiel:

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

Synthetic-Beispiel:

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

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

Agent hinzufügen (non-interactive) Beispiel:

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

Gateway Wizard RPC

Das Gateway stellt den Wizard-Flow über RPC bereit (wizard.start, wizard.next, wizard.cancel, wizard.status). Clients (macOS-App, Control UI) können Schritte rendern, ohne die Onboarding-Logik neu zu implementieren.

Signal-Setup (signal-cli)

Der Wizard kann signal-cli von GitHub-Releases installieren:

  • Lädt das passende Release-Asset herunter.
  • Speichert es unter ~/.openclaw/tools/signal-cli/<version>/.
  • Schreibt channels.signal.cliPath in deine Config.

Hinweise:

  • JVM-Builds erfordern Java 21.
  • Native Builds werden verwendet, wenn verfügbar.
  • Windows nutzt WSL2; signal-cli-Installation folgt dem Linux-Flow innerhalb von WSL.

Was der Wizard schreibt

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers (falls Minimax gewählt)
  • gateway.* (mode, bind, auth, tailscale)
  • channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
  • Channel-Allowlists (Slack/Discord/Matrix/Microsoft Teams), wenn du während der Prompts zustimmst (Namen werden zu IDs aufgelöst, wenn möglich).
  • 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.

Einige Channels werden als Plugins ausgeliefert. Wenn du während des Onboardings einen auswählst, wird der Wizard dich auffordern, ihn zu installieren (npm oder ein lokaler Pfad), bevor er konfiguriert werden kann.

Verwandte Docs