Codex ist das Programmieragent-Produkt von OpenAI und tritt unter anderem als Kommandozeilenwerkzeug Codex CLI, als IDE-Erweiterung und als Cloud-Aufgabe auf. Viele Teams möchten es an den eigenen API-Einstiegspunkt anbinden, um einen einheitlichen Key und eine einheitliche Abrechnung zu nutzen oder Modelle aus einem Gateway zu verwenden. Vorab eine Klarstellung: Es gibt keine eigenständige „Codex API“. Codex CLI ruft die Responses-Schnittstelle von OpenAI auf; eine eigene API bedeutet im Kern, Base URL, Key und Modellname auf einen kompatiblen Endpunkt umzustellen.

Dieser Artikel bezieht sich auf die verbreitete Version von Oktober 2026 und behandelt drei Dinge: Installation der Codex CLI, Aufbau der config.toml sowie Prüfung und Fehlersuche nach der Anbindung an ein eigenes Gateway.

Hinweis: OpenAI und Codex sind Marken ihrer jeweiligen Inhaber; dieser Artikel dient ausschließlich der technischen Anleitung. Protokollanforderungen von Codex sowie unterstützte Schnittstellen und Modellnamen können sich mit Versionen ändern; maßgeblich sind die offizielle Dokumentation und die Modellpreise.

1. Die drei Erscheinungsformen von Codex unterscheiden

Form Einstieg Eigener Key möglich
Codex CLI Befehl codex im Terminal Ja, über config.toml
IDE-Erweiterung Seitenleiste des Editors Versionsabhängig, meist an das Kontosystem gebunden
Cloud-Aufgabe Weboberfläche Meist über ein ChatGPT-Konto

Für die meisten Entwickler ist Codex CLI der wichtigste Weg für eine eigene API. Das Werkzeug liest Code, ändert Dateien und führt Befehle aus; das Modell übernimmt nur die Inferenz. Wird der Modellendpunkt ausgetauscht, läuft die Werkzeugkette weiterhin lokal.

2. API Key und Base URL von Codex

Ein eigener Provider in der Codex CLI benötigt drei Parameter: Base URL, API Key und Modellname. Die offizielle Standardadresse ist https://api.openai.com/v1; beim ZSQH AI Gateway lautet sie https://ai.zhongshangqihang.com/v1.

Konfiguration Offizieller Standard ZSQH-Gateway
Base URL https://api.openai.com/v1 https://ai.zhongshangqihang.com/v1
Authentifizierung OpenAI API Key Key aus der Gateway-Konsole
Protokoll Responses API /v1/responses wird bereitgestellt; unterstützte Modelle laut Dokumentation
Modellname Offizielle Modell-ID Laut Preisseite

Eine wichtige Änderung im Jahr 2026: Der eigene Provider der Codex CLI akzeptiert derzeit nur wire_api = "responses"; das ältere wire_api = "chat" wurde entfernt. Das Gateway muss also das Responses-Protokoll weiterleiten können. Bietet es nur Chat Completions, ist eine Zwischenschicht zur Protokollübersetzung nötig oder ein anderer Client. Das ZSQH AI Gateway stellt /v1/responses bereit; welche Modelle Responses unterstützen, entnehmen Sie der Dokumentation und der Preisseite.

3. Codex CLI installieren

Wählen Sie eine Methode passend zum System:

# npm
npm install -g @openai/codex

# macOS Homebrew
brew install --cask codex

# Installierte Version prüfen
codex --version

Ändern Sie nach der Installation noch nicht die Konfiguration. Melden Sie sich zuerst mit dem offiziellen Konto an und führen Sie einen Durchlauf aus, um das Werkzeug selbst zu prüfen:

  1. codex im Terminal starten.
  2. Der Anleitung zur Anmeldung folgen.
  3. Ein Testverzeichnis anlegen und eine Datei einlesen lassen.
  4. Erst nach einer erfolgreichen Antwort auf den eigenen Provider wechseln.

4. config.toml schreiben

Die benutzerspezifische Konfiguration der Codex CLI liegt in ~/.codex/config.toml. Eine .codex/config.toml im Projektverzeichnis überschreibt die Provider-Definition nicht; das führt leicht zu der Annahme, die Konfiguration sei wirkungslos.

# ~/.codex/config.toml
model = "ihre-modell-id"
model_provider = "zsqh"

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

Bedeutung der Felder:

  • model: Die aufzurufende Modell-ID, exakt wie auf der Preisseite des Gateways angegeben.
  • model_provider: Verweist auf den unten definierten Provider-Namen; beide Angaben müssen übereinstimmen.
  • base_url: OpenAI-kompatible Wurzeladresse, üblicherweise mit /v1 am Ende.
  • env_key: Name der Umgebungsvariablen mit dem Key; schreiben Sie den Key nicht direkt in die Konfigurationsdatei.
  • wire_api: In der aktuellen Version responses.

Exportieren Sie den Key anschließend in der Shell:

export ZSQH_API_KEY="sk-ihr-schluessel"

Unter Windows PowerShell lautet der Befehl $env:ZSQH_API_KEY="sk-ihr-schluessel". Für dauerhafte Gültigkeit tragen Sie die Variable in die Shell-Konfiguration oder die Systemumgebung ein und committen Sie sie nicht ins Repository.

5. Die erste Anfrage prüfen

Starten Sie im interaktiven Modus einfach codex und stellen Sie im Projektverzeichnis eine reine Lesefrage, etwa „Erkläre die Einstiegsdatei dieses Verzeichnisses“. Für eine einmalige nicht-interaktive Prüfung können Sie codex exec verwenden, sofern die aktuelle Version diesen Unterbefehl anbietet; prüfen Sie ihn zuerst mit codex exec --help:

cd /pfad/zu/ihrem-projekt
codex exec "Erkläre die Verzeichnisstruktur dieses Projekts in drei Punkten, ohne Dateien zu ändern"

Zur Nachverfolgung des Anfragewegs können Sie Debug-Logs aktivieren:

codex --log-level debug

Achten Sie darauf, ob die Anfrage-URL auf Ihre Base URL zeigt, ob der Pfad /responses lautet und ob der Modellname unverändert gesendet wird. Viele Fälle von „Konfiguration wirkt nicht“ beruhen darauf, dass das Terminal die Umgebungsvariablen nicht neu geladen hat oder die Konfigurationsdatei an der falschen Stelle liegt.

6. Modell auswählen

Codex-Aufgaben betreffen vor allem Codeverständnis, Patcherstellung und Befehlsausführung. Priorisieren Sie bei der Modellwahl drei Punkte: Kontextlänge, Stabilität von Tool-Aufrufen und Befehlsbefolgung bei langen Aufgaben. Der Stückpreis allein ist kein gutes Kriterium.

Szenario Empfehlung Hinweis
Tägliche Codeänderungen Allgemeines Dialog- oder Codemodell Streaming-Unterstützung bestätigen
Große Repositories lesen Modell mit langem Kontext Längerer Kontext erhöht die Kosten pro Aufruf
Mehrstufige Aufgaben Modell mit stabilen Tool-Aufrufen Zuerst mit kleinen Aufgaben testen
Batch-Skripte Kostengünstigeres Modell Wiederholungsversuche begrenzen

Modell-IDs entnehmen Sie der Preisseite. Den Anzeigenamen von der Webseite direkt in model einzutragen ist einer der häufigsten Fehler; Anzeigename und API-Kennung sind oft nicht identisch.

7. Häufige Fehler und Behandlung

Symptom Häufige Ursache Behandlung
401 Unauthorized Key nicht exportiert oder falsch Terminal neu öffnen und prüfen, ob die Variable hinter env_key gesetzt ist
404 Not Found /v1 fehlt oder ist doppelt, oder das Gateway unterstützt /responses nicht Adresse und Schnittstellenumfang prüfen
Fehler bei wire_api = "chat" Alte Konfiguration Auf responses ändern oder Codex aktualisieren
model not found Modell-ID weicht von der Preisseite ab Exakte Kennung von der Preisseite kopieren
Anfrage bricht ab Netzwerk- oder Streaming-Timeout Proxy, Timeout und Retry-Einstellungen prüfen
429 Ratenlimit oder Kontingent erreicht Verbrauchsseite des Gateways prüfen, Parallelität senken

Wenn das Gateway nur Chat Completions unterstützt, die aktuelle Codex-Version aber nur Responses akzeptiert, ist eine Protokollübersetzungsschicht die stabilste Lösung, etwa ein Gateway wie LiteLLM, statt nach einer alten Codex-Version zu suchen. Alte Versionen verlieren über kurz oder lang die Wartung.

8. Checkliste für Sicherheit und Kosten

  1. Den Key ausschließlich in Umgebungsvariablen oder einem Secret-Manager halten, nie in Git.
  2. Für Codex einen eigenen Key ausstellen, um Limits und Widerruf zu vereinfachen.
  3. Im Gateway Budget und Parallelitätsgrenze setzen, damit Agent-Schleifen das Kontingent nicht aufbrauchen.
  4. Bei großen Repositories Build-Artefakte, Abhängigkeitsverzeichnisse und Schlüsseldateien ausschließen.
  5. Regelmäßig den Verbrauchsbericht prüfen und Kosten nach Projekt aufteilen.
  6. Keine Produktionsschlüssel, Kundendaten oder unmaskierten Logs in Prompts einfügen.

Häufige Fragen

Sind Codex API und ein ChatGPT-Abo dasselbe?

Nein. Ein ChatGPT-Abo gilt für Web- und Clientprodukte; die Codex CLI kann sich per Konto anmelden oder einen API Key mit nutzungsabhängiger Abrechnung verwenden. Die Abrechnungslogik unterscheidet sich, daher sollten Teams beide Wege getrennt kalkulieren.

Kann die Codex CLI die Chat-Completions-Schnittstelle verwenden?

Der eigene Provider der aktuellen Version unterstützt nur das Responses-Protokoll; wire_api = "chat" wurde entfernt. Endpunkte, die ausschließlich Chat Completions anbieten, benötigen eine Protokollübersetzungsschicht.

Warum wirkt eine Änderung an config.toml nicht?

Prüfen Sie zuerst, ob Sie ~/.codex/config.toml geändert haben und nicht eine Datei im Projekt. Kontrollieren Sie dann, ob model_provider und der Name in [model_providers.xxx] übereinstimmen. Öffnen Sie zuletzt das Terminal neu, damit die Umgebungsvariablen wirksam werden.

Anzeigename oder API-Kennung als Modellname eintragen?

Die API-Kennung. Der Anzeigename dient nur der Darstellung; eine falsche Eingabe führt meist zu model not found. Die genaue Schreibweise steht auf der Seite Modellpreise.

Kann ein Team einen gemeinsamen Key verwenden?

Nicht empfohlen. Vergeben Sie Keys pro Person, Projekt oder Umgebung, damit sich Probleme zuordnen und Keys bei Austritt oder Offenlegung einzeln widerrufen lassen.

Nächste Schritte

Die Schwierigkeit bei der Codex-Anbindung liegt nicht in der Installation, sondern im passenden Protokoll: Prüfen Sie zuerst, ob das Gateway Responses unterstützt, und stimmen Sie dann Base URL, Key und Modell ab. Für einen einheitlichen Einstieg und Verbrauchsverwaltung können Sie sich im ZSQH AI Gateway registrieren; Modelle und unterstützte Schnittstellen entnehmen Sie der Seite Modellpreise.

Weiterlesen: