OAuth

OpenClaw unterstützt “Subscription Auth” via OAuth (Drittanbieter-Anmeldung) bei Providern, die das anbieten (vor allem OpenAI Codex (ChatGPT OAuth)). Für Anthropic-Abos nutze den setup-token-Flow. Diese Seite erklärt:

  • wie der OAuth Token-Austausch funktioniert (PKCE)
  • wo Tokens gespeichert werden (und warum)
  • wie du mehrere Accounts verwaltest (Profile + Session-Overrides)

OpenClaw unterstützt auch Provider-Plugins, die eigene OAuth- oder API-Key-Flows mitbringen. Starte sie mit:

openclaw models auth login --provider <id>

Der Token-Sink (warum er existiert)

OAuth-Provider erstellen beim Login/Refresh oft einen neuen Refresh-Token. Manche Provider (oder OAuth-Clients) invalidieren dabei ältere Refresh-Tokens, wenn ein neuer für denselben User/App ausgestellt wird.

Das praktische Symptom:

  • du loggst dich via OpenClaw und via Claude Code / Codex CLI ein → einer von beiden wird später zufällig “ausgeloggt”

Um das zu vermeiden, behandelt OpenClaw auth-profiles.json als Token-Sink:

  • die Runtime liest Credentials von einer Stelle
  • wir können mehrere Profile halten und deterministisch routen

Speicherung (wo Tokens liegen)

Secrets werden pro Agent gespeichert:

  • Auth-Profile (OAuth + API-Keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Runtime-Cache (wird automatisch verwaltet; nicht bearbeiten): ~/.openclaw/agents/<agentId>/agent/auth.json

Legacy-Import-Datei (wird noch unterstützt, aber nicht als Hauptspeicher):

  • ~/.openclaw/credentials/oauth.json (wird bei erster Nutzung in auth-profiles.json importiert)

Alle oben genannten Pfade respektieren auch $OPENCLAW_STATE_DIR (State-Verzeichnis-Override). Vollständige Referenz: /gateway/configuration

Anthropic setup-token (Subscription Auth)

Führe claude setup-token auf einem beliebigen Rechner aus und füge ihn dann in OpenClaw ein:

openclaw models auth setup-token --provider anthropic

Falls du den Token woanders generiert hast, füge ihn manuell ein:

openclaw models auth paste-token --provider anthropic

Prüfen:

openclaw models status

OAuth-Austausch (wie Login funktioniert)

Die interaktiven Login-Flows von OpenClaw sind in @mariozechner/pi-ai implementiert und in die Wizards/Commands eingebunden.

Anthropic (Claude Pro/Max) setup-token

Flow-Ablauf:

  1. führe claude setup-token aus
  2. füge den Token in OpenClaw ein
  3. speichere als Token-Auth-Profil (kein Refresh)

Der Wizard-Pfad ist openclaw onboard → Auth-Auswahl setup-token (Anthropic).

OpenAI Codex (ChatGPT OAuth)

Flow-Ablauf (PKCE):

  1. generiere PKCE-Verifier/Challenge + zufälligen state
  2. öffne https://auth.openai.com/oauth/authorize?...
  3. versuche Callback auf http://127.0.0.1:1455/auth/callback zu empfangen
  4. falls Callback nicht binden kann (oder du remote/headless bist), füge die Redirect-URL/Code ein
  5. tausche bei https://auth.openai.com/oauth/token aus
  6. extrahiere accountId aus dem Access-Token und speichere { access, refresh, expires, accountId }

Wizard-Pfad ist openclaw onboard → Auth-Auswahl openai-codex.

Refresh + Ablauf

Profile speichern einen expires-Timestamp.

Zur Laufzeit:

  • falls expires in der Zukunft liegt → nutze den gespeicherten Access-Token
  • falls abgelaufen → refresh (mit File-Lock) und überschreibe die gespeicherten Credentials

Der Refresh-Flow läuft automatisch; du musst Tokens normalerweise nicht manuell verwalten.

Mehrere Accounts (Profile) + Routing

Zwei Muster:

1) Empfohlen: separate Agents

Wenn “privat” und “arbeit” nie interagieren sollen, nutze isolierte Agents (separate Sessions + Credentials + Workspace):

openclaw agents add work
openclaw agents add personal

Dann konfiguriere Auth pro Agent (Wizard) und route Chats zum richtigen Agent.

2) Fortgeschritten: mehrere Profile in einem Agent

auth-profiles.json unterstützt mehrere Profile-IDs für denselben Provider.

Wähle welches Profil genutzt wird:

  • global via Config-Reihenfolge (auth.order)
  • pro Session via /model ...@<profileId>

Beispiel (Session-Override):

  • /model Opus@anthropic:work

So siehst du welche Profile-IDs existieren:

  • openclaw channels list --json (zeigt auth[])

Verwandte Docs: