Onboarding (macOS-App)

Dieses Dokument beschreibt den aktuellen Ersteinrichtungs-Flow. Das Ziel ist ein reibungsloser Start am ersten Tag: Gateway-Standort wählen, Authentifizierung einrichten, den Wizard durchlaufen und den Agent sich selbst initialisieren lassen.

Ablauf der Seiten (aktuell)

  1. Willkommen + Sicherheitshinweis
  2. Gateway-Auswahl (Lokal / Remote / Später konfigurieren)
  3. Authentifizierung (Anthropic OAuth) — nur lokal
  4. Setup Wizard (Gateway-gesteuert)
  5. Berechtigungen (TCC-Abfragen)
  6. CLI (optional)
  7. Onboarding-Chat (dedizierte Session)
  8. Fertig

1) Willkommen + Sicherheitshinweis

Lies den angezeigten Sicherheitshinweis und entscheide entsprechend.

2) Lokal vs. Remote

Wo soll das Gateway laufen?

  • Lokal (dieser Mac): Das Onboarding kann OAuth-Flows ausführen und Zugangsdaten lokal speichern.
  • Remote (über SSH/Tailnet): Das Onboarding führt OAuth nicht lokal aus; die Zugangsdaten müssen auf dem Gateway-Host vorhanden sein.
  • Später konfigurieren: Setup überspringen und die App unkonfiguriert lassen.

Gateway-Auth-Tipp:

  • Der Wizard generiert jetzt auch für Loopback einen Token, sodass lokale WS-Clients sich authentifizieren müssen.
  • Wenn du die Authentifizierung deaktivierst, kann jeder lokale Prozess sich verbinden; nutze das nur auf vollständig vertrauenswürdigen Rechnern.
  • Verwende einen Token für Multi-Machine-Zugriff oder Nicht-Loopback-Bindings.

3) Nur-lokale Authentifizierung (Anthropic OAuth)

Die macOS-App unterstützt Anthropic OAuth (Claude Pro/Max). Der Ablauf:

  • Öffnet den Browser für OAuth (PKCE)
  • Fordert dich auf, den code#state-Wert einzufügen
  • Schreibt die Zugangsdaten nach ~/.openclaw/credentials/oauth.json

Andere Provider (OpenAI, Custom APIs) werden derzeit über Umgebungsvariablen oder Config-Dateien konfiguriert.

4) Setup Wizard (Gateway-gesteuert)

Die App kann denselben Setup Wizard wie die CLI ausführen. Dadurch bleibt das Onboarding mit dem Gateway-seitigen Verhalten synchron und vermeidet doppelte Logik in SwiftUI.

5) Berechtigungen

Das Onboarding fordert TCC-Berechtigungen an für:

  • Benachrichtigungen
  • Bedienungshilfen
  • Bildschirmaufnahme
  • Mikrofon / Spracherkennung
  • Automation (AppleScript)

6) CLI (optional)

Die App kann die globale openclaw-CLI über npm/pnpm installieren, damit Terminal-Workflows und launchd-Tasks sofort funktionieren.

7) Onboarding-Chat (dedizierte Session)

Nach dem Setup öffnet die App eine dedizierte Onboarding-Chat-Session, damit sich der Agent vorstellen und die nächsten Schritte erklären kann. So bleibt die Ersteinrichtungs-Anleitung von deinen normalen Gesprächen getrennt.

Agent Bootstrap Ritual

Beim ersten Agent-Start bootstrapped OpenClaw einen Workspace (Standard: ~/.openclaw/workspace):

  • Erstellt AGENTS.md, BOOTSTRAP.md, IDENTITY.md, USER.md
  • Führt ein kurzes Q&A-Ritual durch (eine Frage nach der anderen)
  • Schreibt Identität + Präferenzen in IDENTITY.md, USER.md, SOUL.md
  • Entfernt BOOTSTRAP.md nach Abschluss, damit es nur einmal läuft

Optional: Gmail Hooks (manuell)

Das Gmail Pub/Sub-Setup ist derzeit ein manueller Schritt. Verwende:

openclaw webhooks gmail setup --account [email protected]

Details findest du unter /automation/gmail-pubsub.

Remote-Modus-Hinweise

Wenn das Gateway auf einem anderen Rechner läuft, befinden sich Zugangsdaten und Workspace-Dateien auf diesem Host. Wenn du OAuth im Remote-Modus brauchst, erstelle:

  • ~/.openclaw/credentials/oauth.json
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

auf dem Gateway-Host.