OpenClaw Auth-Credentials: Fehler sicher beheben

Hast du dich schon mal über kryptische Fehlermeldungen bei der Authentifizierung geärgert? Es ist frustrierend, wenn du nicht weißt, ob dein Token abgelaufen ist oder ob das System ihn einfach nicht finden kann. Eine klare Logik für Credentials spart dir beim Debugging extrem viel Zeit und Nerven.

Dieses Dokument definiert die kanonische Eignung von Credentials und die Semantik zur Auflösung, die in den folgenden Tools verwendet wird:

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

Das Ziel ist es, das Verhalten bei der Auswahl und zur Laufzeit konsistent zu halten.

Stabile Reason Codes

• ok
• missing_credential
• invalid_expires
• expired
• unresolved_ref

Token-Credentials

Token-Credentials (type: "token") unterstützen inline token und/oder tokenRef.

Regeln für die Eignung

1. Ein Token-Profil ist nicht geeignet, wenn sowohl token als auch tokenRef fehlen.
2. expires ist optional.
3. Wenn expires vorhanden ist, muss es eine endliche Zahl größer als 0 sein.
4. Falls expires ungültig ist (NaN, 0, negativ, nicht-endlich oder falscher Typ), ist das Profil mit dem Code invalid_expires nicht geeignet.
5. Wenn expires in der Vergangenheit liegt, ist das Profil mit dem Code expired nicht geeignet.
6. tokenRef umgeht die Validierung von expires nicht.

Regeln für die Auflösung

1. Die Resolver-Semantik entspricht bei expires der Eignungsprüfung.
2. Für geeignete Profile wird das Token-Material entweder aus dem Inline-Wert oder über tokenRef aufgelöst.
3. Referenzen, die nicht aufgelöst werden können, führen in der Ausgabe von models status --probe zu unresolved_ref.

OAuth SecretRef Policy Guard

• SecretRef-Inputs sind nur für statische Credentials vorgesehen.
• Wenn ein Profil-Credential vom Typ type: "oauth" ist, werden SecretRef-Objekte für dieses Material nicht unterstützt.
• Falls auth.profiles.<id>.mode auf "oauth" gesetzt ist, wird ein SecretRef-basierter keyRef/tokenRef Input für dieses Profil abgelehnt.
• Verstöße führen zu harten Fehlern in den Pfaden der Auth-Auflösung beim Startup oder Reload.

Legacy-kompatible Nachrichten

Um die Kompatibilität mit Skripten zu gewährleisten, bleibt die erste Zeile von Probe-Fehlern unverändert:

Auth profile credentials are missing or expired.

Benutzerfreundliche Details und stabile Reason Codes können in den folgenden Zeilen hinzugefügt werden.

Nächste Schritte

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status —probe
• doctor-auth

AI Setup Assistant