Nach der Anbindung einer eigenen API an Codex CLI treten Fehler vor allem auf sechs Ebenen auf: Zugangsdaten, Pfad, Modell, Rate Limits, Kontext und lokale Sandbox. Wer bei jeder roten Meldung das Modell wechselt oder das Werkzeug neu installiert, zieht aus einem Zehn-Minuten-Problem oft einen halben Tag. Effektiver ist, die Variablen festzuhalten: gleicher Key, gleiche Base URL, gleiche Modell-ID – jeweils nur eine Änderung pro Versuch. Dieser Beitrag gliedert nach Statuscodes und nennt Logpfade, Diagnosebefehle sowie ein Beispiel für Fehlerbehandlung.

Hinweis: OpenAI und Codex sind Marken von OpenAI, Inc. Dieser Beitrag dient der technischen Erläuterung und steht in keiner Zugehörigkeits- oder Partnerschaftsbeziehung zu den genannten Unternehmen. Konfiguration und Texte ändern sich mit Versionen; maßgeblich sind die offizielle Dokumentation und die aktuelle Version. Modelle und Preise entrichten sich nach den Modellpreisen dieser Website.

1. Zuerst den Statuscode ansehen, dann die Konfiguration ändern

Symptom Häufige Bedeutung Zuerst prüfen Wiederholen?
401 Key fehlt, falsch oder ungültig env_key-Variable, Key-Status, Guthaben Nein
403 Key ohne Recht oder durch Richtlinie blockiert Modellrechte, Kontostatus, Teamrichtlinie Nein
404 Falscher Pfad oder Schnittstelle nicht vorhanden Base URL, Unterstützung von /responses Nein
model not found Modell-ID falsch oder nicht freigeschaltet Modellkennung, Kontorechte Nein
429 Frequenz, Parallelität oder Kontingent überschritten Verbrauch, gemeinsame Keys, Retry-Einstellungen Nach Backoff
400 context_length_exceeded Kontext über Modelllimit Eingabegröße, Werkzeugausgaben, Komprimierung Nach Anpassung
Sandbox- oder Freigabefehler Lokale Berechtigungsgrenze blockiert Sandbox-Modus, beschreibbare Verzeichnisse, Freigaberichtlinie Nach Anpassung
Timeout oder Stream-Abbruch Proxy, TLS, Idle-Timeout, Serverüberlastung Netzwerkpfad, Timeout- und Retry-Parameter Je nach Fall

Empfohlene Reihenfolge:

  1. Im Projektverzeichnis codex doctor ausführen und Installation, Konfiguration, Authentifizierung und Laufzeitumgebung prüfen.
  2. In der Sitzung mit /status Modell, Freigaberichtlinie, beschreibbare Verzeichnisse und Token-Verbrauch ansehen.
  3. Mit /debug-config die tatsächlich wirksamen Werte prüfen und bestätigen, dass nicht eine nicht geladene Datei geändert wurde.
  4. Mit einer minimalen Anfrage Base URL, Key und Modell verifizieren.
  5. Erst danach Modell, Kontext oder Sandbox-Richtlinie anpassen.

2. 401 und 403: der Key erreicht den Prozess nicht

Der eigene Provider von Codex benennt die Umgebungsvariable über env_key, zum Beispiel:

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
env_key = "ZSQH_API_KEY"
wire_api = "responses"

Eine korrekte Konfiguration bedeutet nicht, dass der Prozess den Key lesen kann. Häufige Ursachen: Der in der Shell exportierte Variablenname weicht von env_key ab; die Variable wurde in Terminal A exportiert, Codex aber in Terminal B gestartet; eine aus der grafischen Oberfläche gestartete Anwendung hat die Umgebung nicht geerbt; der Key enthält Leerzeichen, Zeilenumbrüche oder Anführungszeichen; der Key gehört zu einer anderen Plattform oder Umgebung; der Key wurde gelöscht, deaktiviert oder hat kein Guthaben.

In Headless-Umgebungen kann CODEX_API_KEY den Key übergeben; mehrere Quellen gleichzeitig sollten jedoch vermieden werden, sonst ist schwer feststellbar, welche tatsächlich verwendet wird. 403 ist eher ein Rechte- oder Richtlinienproblem: zuerst den Antwortkörper und dann die Gateway-Konsole prüfen, nicht wiederholt blind senden.

3. 404 und model not found: Adresse, Protokoll und Modell-ID

Der aktuelle eigene Provider von Codex akzeptiert nur wire_api = "responses"; Anfragen gehen an /v1/responses. Daraus entstehen mehrere häufige 404-Fälle:

  • base_url enthält /v1 nicht, die Anfrage trifft eine Web-Route.
  • base_url enthält bereits /responses, der Client hängt den Pfad erneut an, der Pfad verdoppelt sich.
  • Das Gateway bietet nur /v1/chat/completions und implementiert das Responses-Protokoll nicht.
  • Die Domain ist falsch geschrieben, oder die Konsolenadresse wurde für die API-Adresse gehalten.

base_url wird in der Regel bis /v1 angegeben; den vollständigen Schnittstellenpfad nicht selbst anhängen. Existiert ein Modell nicht, geben manche Gateways 404, andere 400 zurück; das Fehlercode-Feld heißt häufig model_not_found, maßgeblich ist der Antwortkörper. Die Modell-ID muss exakt der API-Kennung auf der Seite Modellpreise entsprechen, einschließlich Groß-/Kleinschreibung, Bindestrichen und Versions-Suffix.

codex debug models exportiert einen lokalen oder eingebauten Katalog und belegt nicht, welche Modelle das Gateway tatsächlich anbietet. Außerdem prüfen, ob model_provider exakt dem Namen in [model_providers.xxx] entspricht; bei Abweichung fällt Codex möglicherweise auf den Standard-Provider zurück, was wie „Konfiguration wirkt nicht“ aussieht.

4. 429: zuerst Parallelität senken, dann über Retries sprechen

429 bedeutet, dass Anfragen das Rate-, Parallelitäts- oder Token-Kontingent überschreiten. Codex liest Dateien kontinuierlich und führt Befehle aus, wodurch dies leichter ausgelöst wird als bei normalem Chat. Häufige Szenarien: Anfragen oder Token pro Minute überschritten; mehrere Personen nutzen denselben Key; in einem großen Repository werden viele Dateien nacheinander gelesen; Wiederholungen ohne Backoff erzeugen einen Sturm; lange Kontextanfragen belegen Parallelitätsplätze.

In der Provider-Konfiguration von Codex gibt es request_max_retries (Standard 4) und stream_max_retries (Standard 5). Sie erhöhen die Stabilität, vervielfachen bei anhaltendem 429 jedoch die Anfragemenge; während der Diagnose können sie vorübergehend gesenkt werden.

Außerdem zwischen Rate Limit und fehlendem Guthaben unterscheiden: Enthält der Fehlerkörper ein Feld wie insufficient_quota, sind Wiederholungen sinnlos; dann in der Konsole Guthaben oder Kontingent prüfen. Bei echtem Rate Limit Retry-After beachten; fehlt der Header, exponentielles Backoff mit Jitter verwenden. Keys nach Projekt oder Person aufzuteilen erleichtert die Zuordnung gegenüber einem gemeinsamen Team-Key.

5. Kontextlimit: zuerst Eingaben reduzieren, dann über ein anderes Modell nachdenken

Der übliche Fehlercode ist context_length_exceeded, im Text kann „maximum context length“ auftauchen. Die Anfrage von Codex enthält nicht nur Ihre Frage, sondern auch Systemprompt, AGENTS.md, gelesene Dateien, Werkzeugausgaben und Verlauf. Bei langen Aufgaben bleibt die Ausgabe jedes früheren Schritts im Kontext.

Empfohlene Reihenfolge:

  1. Das Arbeitsverzeichnis verkleinern und Codex nur relevante Module lesen lassen.
  2. Im Prompt den Dateiumfang begrenzen und einen Scan des gesamten Repositories vermeiden.
  3. Build-Artefakte, Abhängigkeitsverzeichnisse, Logs und Schlüsseldateien ausschließen.
  4. Mit tool_output_token_limit die Tokenzahl einer einzelnen Werkzeugausgabe begrenzen.
  5. Eine neue Sitzung beginnen und abgeschlossene Ergebnisse als kurze Zusammenfassung mitnehmen.
  6. Nur wenn wirklich nötig, auf ein Modell mit längerem Kontext wechseln.

model_context_window muss dem echten Fenster entsprechen; auch ein größerer Wert wird vom Server abgelehnt. Ein zu hoch gesetztes model_auto_compact_token_limit kann zuerst an die harte Obergrenze stoßen. Maßgeblich sind das tatsächliche Fenster laut offizieller Dokumentation und Preisseite.

6. Sandbox- und Freigabefehler: das ist kein API-Fehler

Codex kennt drei Sandbox-Modi: read-only, workspace-write und danger-full-access. read-only erlaubt keine Dateiänderungen; workspace-write erlaubt Änderungen nur innerhalb beschreibbarer Wurzelverzeichnisse und kann Netzwerkzugriff konfigurieren; danger-full-access hebt Datei- und Netzwerkgrenzen auf und ist nur für kontrollierte Umgebungen geeignet.

Typische Erscheinungen sind Operation not permitted, Permission denied oder eine Freigabeanfrage mitten in der Befehlsausführung. Zuerst im /status den Modus und die beschreibbaren Verzeichnisse prüfen, dann ob das Projekt außerhalb dieser Verzeichnisse liegt, ob der Befehl Netzwerk benötigt und ob das nicht interaktive codex exec überhaupt einen Freigabeeingang hat.

Bei den Freigaberichtlinien unterstützt die aktuelle Version on-request, never und granular. Das alte approval_policy = "untrusted" wird nicht mehr unterstützt und kann Codex am Start hindern; on-failure ist ebenfalls veraltet. In CI lässt sich codex exec --sandbox workspace-write explizit angeben; für reine Leseaufgaben ist --sandbox read-only --ask-for-approval never möglich. Aus Bequemlichkeit nicht direkt danger-full-access verwenden.

7. Timeouts und Stream-Abbrüche: Proxy, TLS und Idle-Timeout

Streaming-Anfragen reagieren empfindlicher auf den Netzwerkpfad. Unternehmens-Proxys, TLS-Interception, VPN-Wechsel und instabile Ausgänge können dazu führen, dass „die Anfrage rausgeht, aber lange kein erstes Token kommt“ oder der Stream mittendrin abbricht.

stream_idle_timeout_ms beträgt standardmäßig 300000 Millisekunden (fünf Minuten). Reasoning-Modelle brauchen beim ersten Token länger; ein zu niedriger Wert schadet. Trennt ein Proxy die Leerlaufverbindung nach 60 Sekunden, hilft ein größerer Client-Timeout allein nicht – die Kette muss mit geprüft werden.

Für selbstsignierte CAs oder TLS-Interception kann CODEX_CA_CERTIFICATE ein PEM-Zertifikatspaket angeben; nur wenn es nicht gesetzt ist, wird auf SSL_CERT_FILE zurückgefallen. Die Zertifikatsprüfung nicht vollständig abschalten. Nach einem Timeout zuerst eine minimale, nicht gestreamte Anfrage senden, um die API zu bestätigen, und dann den Fehler in Codex reproduzieren.

8. Logs und Diagnose: zuerst Belege, dann Konfiguration ändern

Das Log-Verzeichnis von Codex wird über log_dir gesteuert, standardmäßig $CODEX_HOME/log. Nur wenn log_dir ausdrücklich gesetzt ist, wird zusätzlich ein Klartext-Log codex-tui.log erzeugt; für die Diagnose empfiehlt es sich, dies in der Benutzerkonfiguration zu aktivieren.

Häufige Diagnosezugänge:

  • codex doctor: Bericht zu Installation, Konfiguration, Authentifizierung, Laufzeit und Terminalzustand.
  • /status: Modell, Freigaberichtlinie, beschreibbare Verzeichnisse und Token-Verbrauch in der Sitzung.
  • /debug-config: Konfigurationsquellen, Priorität und endgültig wirksame Werte.
  • codex exec --json: nicht interaktive Ausführung als JSON-Ereignisstrom.
  • RUST_LOG: Detailgrad der Logs, etwa codex_core=debug,codex_tui=debug; codex exec zeigt standardmäßig nur die Stufe error.

Bei der Diagnose die endgültigen Konfigurationswerte mit der tatsächlichen Anfrage abgleichen: Base URL, /responses-Pfad, Modellname und Freigaberichtlinie. Viele Fälle von „Konfiguration wirkt nicht“ beruhen auf einem falschen Dateispeicherort oder nicht neu geladenen Umgebungsvariablen.

9. Ein wiederverwendbares Beispiel für Fehlerbehandlung

Das folgende Beispiel richtet sich an eigene Skripte, die das Gateway aufrufen, und ersetzt nicht die eingebauten Wiederholungen von Codex CLI. Grundsatz: Authentifizierungs- und Pfadfehler nicht wiederholen, Rate Limits und 5xx mit Backoff wiederholen, Kontextfehler direkt durch Anpassen der Anfrage behandeln.

import random
import time

import httpx

RETRYABLE = {429, 500, 502, 503, 504}


def call_gateway(payload: dict, key: str, url: str):
    for attempt in range(4):
        try:
            resp = httpx.post(
                url,
                json=payload,
                headers={"Authorization": f"Bearer {key}"},
                timeout=httpx.Timeout(180.0, connect=10.0),
            )
        except httpx.TimeoutException:
            if attempt == 3:
                raise
            time.sleep(min(30, 2 ** attempt) + random.random())
            continue

        # Authentifizierung, Rechte, Pfad, Modell: Konfiguration aendern, nicht wiederholen
        if resp.status_code in (401, 403, 404):
            raise RuntimeError(f"{resp.status_code}: {resp.text[:300]}")

        if resp.status_code == 400:
            body = resp.text.lower()
            if "context" in body or "maximum context" in body:
                raise RuntimeError("Kontextlimit erreicht: Eingabe verkleinern oder neue Sitzung beginnen")
            raise RuntimeError(f"Fehlerhaftes Anfrageformat: {resp.text[:300]}")

        if resp.status_code in RETRYABLE:
            if "insufficient_quota" in resp.text:
                raise RuntimeError("Kontingent erschoepft: Guthaben pruefen, nicht wiederholen")
            retry_after = float(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(min(30, retry_after) + random.random())
            continue

        resp.raise_for_status()
        return resp.json()

    raise RuntimeError("Maximale Anzahl Wiederholungen erreicht")

Der Code behandelt weder Sandbox noch Freigaben – das gehört zur lokalen Ausführungsebene. API-Fehler und lokale Berechtigungsfehler getrennt zu betrachten beschleunigt die Diagnose erheblich.

Häufige Fragen

Der Key funktioniert im Web-Test, Codex meldet aber 401?

Zuerst den von Codex gelesenen Variablennamen bestätigen und die Variable in derselben Shell exportieren, in der Codex startet. Aus der grafischen Oberfläche gestartete Anwendungen lesen frisch gesetzte Variablen oft nicht; Anwendung neu öffnen oder die Authentifizierung mit codex doctor prüfen.

Bedeutet 404 immer, dass das Modell abgeschaltet wurde?

Nein. Codex verwendet das Responses-Protokoll; ein falscher Pfad oder ein Gateway ohne /v1/responses-Eingang führt ebenfalls zu 404. Zuerst prüfen, ob die Adresse bis /v1 reicht, dann die Modell-ID abgleichen.

Sollte man bei 429 die Zahl der Wiederholungen erhöhen?

Nicht empfehlenswert. Anhaltende 429 zeigen, dass das Limit bereits überschritten ist; mehr Wiederholungen erhöhen nur die Anfragemenge. Zuerst Parallelität senken, Keys aufteilen und Retry-After prüfen, um Rate Limit von fehlendem Guthaben zu unterscheiden.

Kann Codex die Chat-Completions-Schnittstelle verwenden?

Derzeit wird nur wire_api = "responses" akzeptiert. Endpunkte mit ausschließlich Chat Completions benötigen eine Konvertierungsschicht oder einen anderen Client; nicht durch Installieren einer alten Version umgehen.

Lassen sich Sandbox-Fehler einfach abschalten?

Der Modus kann auf workspace-write mit konfigurierten beschreibbaren Verzeichnissen geändert werden, oder in kontrollierten Umgebungen auf einen Modus mit mehr Rechten; danger-full-access sollte jedoch nicht Standard sein. Zuerst mit /status die Grenzen prüfen.

Nächster Schritt

Bei der Codex-Fehlerdiagnose ist die Reihenfolge wichtiger als einzelne Kniffe: zuerst Statuscode und Antwortkörper, dann mit codex doctor und /debug-config die Konfiguration bestätigen und erst zuletzt Modell oder Sandbox ändern. Für einheitliche Keys, Verbrauch und Modelleingänge können Sie sich im ZSQH AI Gateway registrieren; Modell- und Schnittstellenumfang entnehmen Sie den Modellpreisen.

Weiterführende Beiträge: