Hermes Agent und Codex-Abonnement: OAuth-Einrichtung, Quoten und API

Die Integration von Hermes Agent ermöglicht es Entwicklern, Anfragen an OpenAI-Modelle über ein ChatGPT- oder Codex-Endkundenabonnement mittels des OAuth Device Code Flows weiterzuleiten. Dieser Ansatz macht statische API-Schlüssel überflüssig, bringt jedoch technische und finanzielle Unklarheiten mit sich. Ein erfolgreich abgeschlossener Authentifizierungs-Handshake bestätigt lediglich die technische Gültigkeit der Kontozugangsdaten – er definiert oder garantiert jedoch nicht die zugrunde liegende Abrechnungslogik für nachfolgende Anfragen.

Rahmenbedingungen: Bestätigte Fakten, Dokumentationslücken und Verifizierung

Beim Einsatz von Hermes Agent mit Codex-Konten lassen sich die Interaktionen in drei eindeutige Kategorien unterteilen:

Kategorie	Status in der Dokumentation	Technische Umsetzung und Kontrollbereich
Bestätigt	Offiziell dokumentiert	Autorisierung über den Device Code Flow. Lokale Token-Speicherung in ~/.hermes/auth.json. Import von Anmeldedaten aus ~/.codex/auth.json (ohne separate Installation der Codex CLI erforderlich). Automatische Quarantäne für widerrufene Token.
Nicht dokumentiert	Offiziell nicht offengelegt	Unterstützte Abonnement-Tarife und Regeln zum Quotenverbrauch. Die offizielle Dokumentation nennt weder zugelassene Tarife noch Details zum Abzug von Limits.
Erfordert Überprüfung	Verantwortung des Nutzers	Abgleich der Metriken im Dashboard des Anbieters vor und nach dem Start des Agenten, Berücksichtigung möglicher Telemetrieverzögerungen und Trennung zwischen Abonnement-Abrechnung und unabhängigen API-Schlüsseln.

Die Dokumentation von Nous Research beschreibt lediglich das Netzwerkprotokoll des Handshakes und die Mechanismen zur Sitzungserneuerung. Offizielle Quellen legen weder dar, welche Abonnementstufen qualifiziert sind, noch wie Nutzungskontingente abgezogen werden; Entwickler müssen Kontodaten und Metriken im Dashboard des Anbieters vor der Ausführung produktiver Aufgaben eigenständig überprüfen. Jegliche Behauptung, dass die Nutzung von Codex-Modellen über den Agenten „kostenlos“, „unbegrenzt“ oder uneingeschränkt in Basistarifen für Endkunden enthalten sei, entbehrt jeder technischen Grundlage.

Konfigurationsprozess und Sitzungsverwaltung

Die Architektur von Hermes trennt die dauerhafte Umgebungskonfiguration strikt vom Modellwechsel während der Laufzeit:

• hermes model — Wird direkt im Terminal außerhalb einer aktiven Agentensitzung ausgeführt. Dieser Einrichtungsassistent übernimmt die Registrierung neuer Anbieter, startet die browserbasierte OAuth-Autorisierung und speichert grundlegende Konfigurationsparameter.
• /model — Ein Befehl innerhalb der interaktiven Chat-Sitzung. Er dient ausschließlich dem Wechsel zwischen bereits konfigurierten Anbietern und Modellen. Das Hinzufügen neuer Anbieter oder das Starten von OAuth-Flows innerhalb des Chats ist nicht möglich.

Die Ersteinrichtung des Anbieters beginnt im Terminal durch Auswahl von ChatGPT or Codex Subscription im Konfigurationsmenü:

hermes model

Nach Auswahl dieser Option gibt die Konsole eine einmalige Verifizierungs-URL zusammen mit einem eindeutigen alphanumerischen Gerätecode aus. Öffnen Sie den Link im Browser, melden Sie sich bei Ihrem OpenAI-Konto an und bestätigen Sie die Verbindung. Nach erfolgreicher Bestätigung speichert Hermes die zurückgegebenen Zugriffs- und Refresh-Token lokal unter ~/.hermes/auth.json. Falls auf dem Rechner bereits aktive Anmeldedaten der Codex CLI vorhanden sind, importiert der Agent diese automatisch aus ~/.codex/auth.json, sodass eine separate Paketinstallation der Codex CLI nicht notwendig ist.

Fehlerbehandlung bei der Authentifizierung und Token-Quarantäne

Gibt der Autorisierungsserver einen schwerwiegenden Authentifizierungsfehler zurück (wie eine HTTP-4xx-Antwort, den Status invalid_grant oder widerrufene Zugriffsrechte), bricht Hermes Wiederholungsversuche ab, um endlose Protokollmeldungen im Terminal zu verhindern. Das ungültige Refresh-Token wird umgehend in einen lokalen Quarantänestatus versetzt. Bei nachfolgenden Versuchen, den Agenten aufzurufen, gibt das System eine typisierte Meldung aus, die zur erneuten Anmeldung auffordert.

Um den Quarantänestatus zurückzusetzen und den Anmeldevorgang erneut zu durchlaufen, führen Sie folgenden Befehl aus:

hermes auth add openai-codex

Alternativ können Sie den Einrichtungsassistenten hermes model erneut starten und den Abonnement-Anbieter erneut auswählen. Eine erfolgreiche Aktualisierung der Anmeldedaten hebt den Quarantänestatus automatisch auf.

Dedizierte API versus Abonnement-Zugang

Die OAuth-Verbindung über ein Endkunden-Abonnement und direkte API-Verbindungen über statische Schlüssel operieren in vollständig voneinander getrennten finanziellen und infrastrukturellen Umgebungen:

1. Abonnement: Direkt an ein ChatGPT-Endkundenkonto gebunden. Die offizielle Dokumentation definiert weder die unterstützten Abonnementmodelle noch die genauen Mechanismen, nach denen OAuth-Aufrufe vom Kontingent abgezogen werden. Vor dem Start von Agentenaufgaben müssen Kontostatus und Zählerstände eigenständig überprüft werden.
2. API-Schlüssel: Wird bei Auswahl des Anbieters openai-api (über OPENAI_API_KEY in ~/.hermes/.env) oder bei Drittanbieter-Gateways verwendet. Die anfallenden Kosten richten sich nach dem Gebührenmodell des ausgewählten Anbieters und beschränken sich nicht zwingend auf das reine Token-Volumen.

Wenn ein Agenten-Deployment transparente Abrechnung mit detaillierter Aufschlüsselung pro Anfrage oder Zugriff auf alternative Open-Weights-Modelle erfordert, kann die Abonnementverbindung durch ein eigenständiges Gateway ergänzt oder ersetzt werden. Als Referenz für eine unabhängige Architektur dient die BetterToken-Dokumentation, die Standard-OpenAI-kompatible Endpunkte, persönliche Zugriffsschlüssel und eine Verbrauchsüberwachung im Dashboard bereitstellt. Ein externer API-Zugang arbeitet als isolierter Kanal: Er wandelt ein bestehendes ChatGPT/Codex-Abonnement nicht um, übernimmt dessen Kontingente nicht und garantiert nicht die Verfügbarkeit derselben Modelle.

Verifizierungs-Checkliste und Fehlerbehebung

Da die genauen Mechanismen des Quotenabzugs bei Endkunden-Abonnements von den Entwicklern nicht dokumentiert sind, wird vor der regelmäßigen Nutzung die Erstellung einer empirischen Baseline anhand des folgenden Prüfprotokolls dringend empfohlen:

1. Kontoparameter: Ermitteln und notieren Sie Ihren aktuellen Abonnement-Tarif und das verfügbare Kontingent in der Webkonsole des Anbieters (offizielle Angaben zu unterstützten Tarifen fehlen).
2. Zeitstempel und Ausgangswert: Erfassen Sie die anfänglichen Zählerstände für Nachrichten sowie den exakten Startzeitpunkt (Timestamp) Ihres Tests.
3. Minimale Anfrage: Starten Sie eine Agentensitzung und senden Sie eine kurze Testanfrage ohne externe Werkzeugaufrufe (beispielsweise: Berechne 256 * 4).
4. Guthabenabgleich: Prüfen Sie die Rechnungsübersicht Ihres Kontos nach einer angemessenen Wartezeit, da die genaue Telemetrieverzögerung unbekannt ist. Ein Zähler, der sich nicht sofort aktualisiert, ist kein Beleg für einen kostenlosen Aufruf.
5. Sicherheitsvorkehrungen: Geben Sie den Inhalt von ~/.hermes/auth.json keinesfalls an Dritte weiter und veröffentlichen Sie keine Terminal-Logs mit Token-Fragmenten.

Gibt Hermes nach erfolgreicher Anmeldung einen Fehler vom Typ HTTP 403 aus oder meldet unzureichende Berechtigungen, ist die genaue Ursache für Codex in der Dokumentation nicht definiert. Prüfen Sie den Wortlaut der Fehlermeldung, die Berechtigungen und den Status des Kontos sowie die gewählte Route und Modell-ID, und ziehen Sie die offizielle Dokumentation oder den Support des Anbieters zu Rate. Bei Bedarf bietet der Wechsel zu einem unabhängigen API-Anbieter mit eigenem Zugriffsschlüssel eine Alternative.