Authentifizierung

OpenClaw unterstützt OAuth und API-Schlüssel für Modellanbieter. Für dauerhaft laufende Gateway-Hosts sind API-Schlüssel in der Regel die zuverlässigste Option. Subscription/OAuth-Flows werden ebenfalls unterstützt, sofern sie zu deinem Anbieter-Kontotyp passen.

Unter /concepts/oauth findest du den vollständigen OAuth-Flow und das Speicherlayout. Für SecretRef-basierte Authentifizierung (env/file/exec-Provider) siehe Secrets Management. Für die Credential-Eligibility- und Reason-Code-Regeln von models status --probe siehe Auth Credential Semantics.

Empfohlenes Setup (API-Schlüssel, beliebiger Anbieter)

Wenn du ein dauerhaft laufendes Gateway betreibst, starte am besten mit einem API-Schlüssel deines gewählten Anbieters. Speziell für Anthropic ist API-Schlüssel-Authentifizierung der sichere Weg und wird gegenüber Subscription-Setup-Token-Auth empfohlen.

  1. Erstelle einen API-Schlüssel in der Anbieterkonsole.
  2. Hinterlege ihn auf dem Gateway-Host (der Maschine, auf der openclaw gateway läuft).
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. Falls das Gateway unter systemd/launchd läuft, hinterlege den Schlüssel bevorzugt in ~/.openclaw/.env, damit der Daemon ihn lesen kann:
cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

Starte anschließend den Daemon (oder deinen Gateway-Prozess) neu und prüfe erneut:

openclaw models status
openclaw doctor

Wenn du Umgebungsvariablen nicht selbst verwalten möchtest, kann der Onboarding-Assistent API-Schlüssel für die Daemon-Nutzung speichern: openclaw onboard.

Unter Help findest du Details zur Env-Vererbung (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: Setup-Token (Subscription-Auth)

Wenn du ein Claude-Abonnement nutzt, wird der Setup-Token-Flow unterstützt. Führe ihn auf dem Gateway-Host aus:

claude setup-token

Füge ihn dann in OpenClaw ein:

openclaw models auth setup-token --provider anthropic

Wurde der Token auf einem anderen Rechner erstellt, füge ihn manuell ein:

openclaw models auth paste-token --provider anthropic

Falls du einen Anthropic-Fehler wie diesen siehst:

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

…verwende stattdessen einen Anthropic-API-Schlüssel.

Warnung: Die Setup-Token-Unterstützung für Anthropic ist rein technische Kompatibilität. Anthropic hat in der Vergangenheit einige Subscription-Nutzung außerhalb von Claude Code eingeschränkt. Verwende es nur, wenn du das Policy-Risiko akzeptierst, und prüfe die aktuellen Anthropic-Nutzungsbedingungen selbst.

Manueller Token-Eintrag (beliebiger Anbieter; schreibt auth-profiles.json und aktualisiert die Konfiguration):

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

Auth-Profil-Referenzen werden auch für statische Anmeldedaten unterstützt:

  • api_key-Credentials können keyRef: { source, provider, id } verwenden
  • token-Credentials können tokenRef: { source, provider, id } verwenden

Automatisierungsfreundliche Prüfung (Exit 1 bei abgelaufen/fehlend, 2 bei ablaufend):

openclaw models status --check

Optionale Ops-Skripte (systemd/Termux) sind hier dokumentiert: /automation/auth-monitoring

claude setup-token erfordert ein interaktives TTY.

Auth-Status der Modelle prüfen

openclaw models status
openclaw doctor

API-Schlüssel-Rotation (Gateway)

Einige Anbieter unterstützen das erneute Versuchen einer Anfrage mit alternativen Schlüsseln, wenn ein API-Aufruf ein Provider-Rate-Limit erreicht.

  • Prioritätsreihenfolge:
    • OPENCLAW_LIVE_<PROVIDER>_KEY (einzelner Override)
    • <PROVIDER>_API_KEYS
    • <PROVIDER>_API_KEY
    • <PROVIDER>_API_KEY_*
  • Google-Anbieter verwenden zusätzlich GOOGLE_API_KEY als weiteren Fallback.
  • Die Schlüsselliste wird vor der Verwendung dedupliziert.
  • OpenClaw versucht den nächsten Schlüssel nur bei Rate-Limit-Fehlern (z. B. 429, rate_limit, quota, resource exhausted).
  • Fehler, die kein Rate-Limit betreffen, werden nicht mit alternativen Schlüsseln wiederholt.
  • Wenn alle Schlüssel fehlschlagen, wird der letzte Fehler des letzten Versuchs zurückgegeben.

Steuern, welches Credential verwendet wird

Pro Sitzung (Chat-Befehl)

Verwende /model <alias-oder-id>@<profileId>, um ein bestimmtes Anbieter-Credential für die aktuelle Sitzung festzulegen (Beispiel-Profil-IDs: anthropic:default, anthropic:work).

Verwende /model (oder /model list) für einen kompakten Auswahlbildschirm; verwende /model status für die vollständige Ansicht (Kandidaten + nächstes Auth-Profil sowie Anbieter-Endpoint-Details, wenn konfiguriert).

Pro Agent (CLI-Override)

Setze eine explizite Auth-Profil-Reihenfolge als Override für einen Agenten (wird in der auth-profiles.json des Agenten gespeichert):

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

Verwende --agent <id>, um einen bestimmten Agenten anzusprechen; ohne diesen Parameter wird der konfigurierte Standard-Agent verwendet.

Fehlerbehebung

”No credentials found”

Wenn das Anthropic-Token-Profil fehlt, führe claude setup-token auf dem Gateway-Host aus und prüfe erneut:

openclaw models status

Token läuft ab / abgelaufen

Führe openclaw models status aus, um zu bestätigen, welches Profil abläuft. Falls das Profil fehlt, führe claude setup-token erneut aus und füge den Token nochmals ein.

Voraussetzungen

  • Anthropic-Abonnementkonto (für claude setup-token)
  • Claude Code CLI installiert (claude-Befehl verfügbar)
arrow_back
Zurück
Configuration Examples
Weiter
Auth Credential Semantics
arrow_forward