Codex CLI ist OpenAIs Programmieragent für das Terminal; er liest Code, ändert Dateien und führt Befehle aus. Viele Teams möchten ihn an ein selbst betriebenes Gateway oder einen OpenAI-kompatiblen Drittanbieter-Eingang anschließen, um Keys, Abrechnung und Limits zentral zu verwalten. Hinter „eigene API anbinden“ stehen konfigurationstechnisch nur drei Stellen: wohin die Anfrage geht (Base URL), womit sie sich authentifiziert (Key) und welches Modell aufgerufen wird (Modellname). Fehleranfällig sind vor allem Authentifizierungsart, Protokollübereinstimmung und Berechtigungsgrenzen.

Dieser Beitrag beschreibt den üblichen Versionsstand von Oktober 2026 und folgt der Reihenfolge Installation, Authentifizierung, Konfiguration, Verifikation, Sandbox-Freigaben, Team-Rollout und Sicherheit. Codex entwickelt sich schnell; Befehle und Konfigurationsoptionen richten sich nach codex --help und der offiziellen Dokumentation.

Hinweis: OpenAI, Codex und ChatGPT sind Marken oder eingetragene Marken von OpenAI. Dieser Beitrag dient der technischen Anbindung und steht in keiner Zugehörigkeitsbeziehung zu OpenAI. Schnittstellenanforderungen, Modellbezeichnungen und Abrechnung können sich mit Versionen ändern; maßgeblich sind die offizielle Dokumentation und die Modellpreise auf dieser Seite.

1. Zuerst Protokoll und Authentifizierungsart klären

Der eigene Provider von Codex CLI verwendet das Responses-Protokoll; wire_api akzeptiert derzeit nur responses. Die alte Schreibweise chat ist veraltet und führt in vielen Versionen direkt zu einem Fehler. Das Gateway muss mindestens zwei Bedingungen erfüllen: einen kompatiblen /v1/responses-Eingang bereitstellen und Streaming mit dem Abschlussereignis response.completed unterstützen. Ein Eingang, der nur Chat Completions anbietet, benötigt eine Zwischenschicht zur Protokollkonvertierung; die Adresse lässt sich nicht einfach eintragen.

Für die Authentifizierung gibt es drei Wege; einer genügt:

Methode Typischer Befehl oder Eintrag Geeignetes Szenario Hinweis
ChatGPT-Kontoanmeldung codex login Persönlicher Test, temporäre Nutzung Nutzt das Kontokontingent, nicht für CI geeignet
API-Key-Anmeldung codex login --with-api-key (Key aus stdin) Persönliche Nutzung nach Verbrauch Zugangsdaten landen in auth.json oder im Systemschlüsselbund
Eigener Provider env_key verweist auf eine Umgebungsvariable Team-Gateway, zentrale Abrechnung Key steht nicht in der TOML, erleichtert Limits und Widerruf

Der aktuelle Anmeldestatus lässt sich mit codex login status prüfen, lokale Zugangsdaten mit codex logout entfernen. Existieren mehrere Zugangsdaten gleichzeitig, zuerst feststellen, welche tatsächlich wirkt, und dann die Konfiguration prüfen.

2. Codex CLI installieren

Je nach System einen Weg wählen und nach der Installation die Version prüfen:

# Offizielles Installationsskript fuer macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Alternativ ein Paketmanager; massgeblich ist die aktuelle offizielle Dokumentation
npm install -g @openai/codex
brew install --cask codex

codex --version

Der erste Start sollte in einem leeren Test-Repository erfolgen, nicht in einem Verzeichnis mit Produktionsschlüsseln, Kundendaten oder unbereinigter Konfiguration. Codex liest den Kontext des aktuellen Verzeichnisses; je sauberer das Verzeichnis, desto einfacher die Fehlersuche.

3. Base URL, Key und Modell konfigurieren

Die Benutzerkonfiguration liegt in ~/.codex/config.toml, unter Windows in %USERPROFILE%\.codex\config.toml. Eine häufige Falle: Top-Level-Schlüssel müssen vor der ersten Tabellenüberschrift stehen. Werden model und model_provider hinter [model_providers.xxx] geschrieben, gelten sie als Felder dieser Tabelle – die Konfiguration scheint dann „nicht zu wirken“.

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"
web_search = "disabled"

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

Bedeutung der Felder:

  • model: die API-Kennung eintragen, nicht den Anzeigenamen auf der Website; sie muss exakt mit der Preisseite übereinstimmen.
  • model_provider: muss der Provider-ID unten entsprechen; keine reservierten Namen wie openai, ollama oder lmstudio verwenden.
  • base_url: enthält den API-Pfad und endet üblicherweise auf /v1; nicht doppelt anhängen.
  • wire_api: responses eintragen.
  • env_key: den Namen der Umgebungsvariablen eintragen, nicht den Key selbst.
  • web_search: auf disabled setzen, solange das Gateway keine Websuche unterstützt, damit Anfragen nicht auf nicht freigeschaltete Fähigkeiten treffen.

Danach den Key in derselben Shell exportieren, in der Codex gestartet wird:

export ZSQH_API_KEY="sk-Ihr-Schluessel"

Unter Windows PowerShell lautet die Zeile $env:ZSQH_API_KEY="sk-Ihr-Schluessel". Für dauerhafte Gültigkeit die Variable in die Shell-Konfiguration oder die Systemumgebung schreiben und prüfen, ob auch aus der grafischen Oberfläche gestartete Editoren sie lesen.

Verlangt das Gateway eigene Anfrage-Header, kann stattdessen env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" } verwendet werden; dieser Weg nutzt keine entfernte Katalogerkennung und erfordert zusätzlich einen lokalen Modellkatalog model_catalog_json. Werden Keys von einem Secret-Management-Werkzeug dynamisch ausgestellt, lässt sich über command in [model_providers.zsqh.auth] ein Token von einem externen Programm beziehen; dies ist nicht gleichzeitig mit env_key möglich. Bei vielen Modell-Aliasen kommen model_catalog_url oder ein lokales model_catalog_json infrage; ohne diesen Bedarf ist keine zusätzliche Komplexität nötig.

Wichtig außerdem: Vertrauenswürdige Projekte laden .codex/config.toml, ignorieren darin jedoch model_provider, model_providers und Profildefinitionen. Der Provider muss daher in der Benutzerkonfiguration stehen.

4. Prüfen, ob die Anbindung tatsächlich greift

In dieser Reihenfolge lässt sich schnell unterscheiden, ob das Werkzeug oder das Gateway das Problem ist:

  1. codex login status ausführen und die aktuelle Authentifizierungsart bestätigen; dann prüfen, ob die von env_key referenzierte Variable in der Startumgebung nicht leer ist. Den Key nicht vollständig in einem gemeinsam genutzten Terminal ausgeben.
  2. codex doctor ausführen und Speicherort der Konfiguration, Umgebungsvariablen und häufige Konflikte prüfen.
  3. Im Test-Repository codex exec "Reply with exactly: gateway-ok" ausführen. Kommt gateway-ok zurück, ist die Basiskette intakt. codex exec nutzt standardmäßig eine schreibgeschützte Sandbox und eignet sich für einen Smoke-Test.
  4. Den interaktiven Modus starten und /status ausführen; Modell und Provider mit den konfigurierten Werten abgleichen.
  5. In der Gateway-Konsole das Anfrageprotokoll prüfen und Nutzer, Modell-Alias und Upstream-Route bestätigen. Eine Antwort im Client allein genügt nicht – sie kann aus einem Cache oder einer alten Konfiguration stammen.
  6. Bei weiterhin bestehendem Fehler zuerst /v1 und /responses in der Base URL prüfen und dann kontrollieren, ob ein Proxy den Authorization-Header verändert oder entfernt.

5. Sandbox und Freigaben: zwei unabhängige Schalter

Viele verwechseln „automatisch ausführen“ mit „welche Dateien geändert werden dürfen“. Codex trennt beides: Die Freigaberichtlinie bestimmt, wann nachgefragt wird, die Sandbox bestimmt, auf welche Dateien und Netzwerke der Prozess zugreifen darf.

Der übliche Wert für approval_policy ist derzeit on-request und passt für die meisten Alltagsentwicklungen; never sollte nur in isolierten Automatisierungsumgebungen verwendet werden. Das alte untrusted wird nicht mehr unterstützt, on-failure ist ebenfalls veraltet; wer alte Anleitungen kopiert, erhält leicht einen Konfigurationsfehler.

sandbox_mode kennt drei Werte: read-only, workspace-write und danger-full-access. Standardmäßig mit schreibgeschützt beginnen; für Codeänderungen workspace-write verwenden und mit sandbox_workspace_write.writable_roots die beschreibbaren Verzeichnisse begrenzen. danger-full-access gehört nur in Container oder einmalige Runner. Wird Netzwerkzugriff benötigt, separat sandbox_workspace_write.network_access aktivieren und nicht pauschal alle Rechte erweitern.

Im nicht interaktiven Modus lässt sich die Sandbox mit codex exec --sandbox workspace-write festlegen; erlaubt die Organisation automatische Prüfungen, kann --approve-for-me ergänzt werden. --full-auto wird nicht mehr unterstützt und muss in alten Skripten ersetzt werden. Im interaktiven Modus zeigt und ändert /permissions die aktuellen Rechte.

6. Team-Rollout: erst kleiner Kreis, dann einheitliche Konfiguration

Zunächst mit zwei oder drei Personen und einem nicht kritischen Repository pilotieren, dann ausweiten. Entscheidend ist nicht, wie viele Personen installiert haben, sondern ob die Konfiguration reproduzierbar und ein Fehler lokalisierbar ist.

  • Ein Key pro Person, bei Bedarf nach Projekt oder Umgebung getrennt; keinen gemeinsamen Key für die ganze Gruppe.
  • Im Gateway Budget, Parallelität und Modell-Whitelist setzen, damit Agent-Schleifen das Kontingent nicht aufbrauchen.
  • Unternehmensverwaltete Konfiguration für approval_policy, sandbox_mode und cli_auth_credentials_store nutzen; requirements.toml kann riskante Kombinationen wie never und danger-full-access sperren.
  • Soll die Anmeldeart erzwungen werden, forced_login_method = "chatgpt" oder "api" setzen, damit Mitglieder keine Zugangsdaten mischen.
  • Eine Konfigurationsvorlage ohne Schlüssel pflegen, mit Base URL, Modellkennung und Diagnosebefehlen.
  • Monatlich den Gateway-Verbrauch nach Person, Projekt und Modell prüfen.

7. Sicherheitscheckliste

  • Keys nur in Umgebungsvariablen, im Systemschlüsselbund oder in einem Secret-Management-Dienst halten, nicht in config.toml und nicht in Git. Das Feld experimental_bearer_token existiert, wird offiziell aber nicht empfohlen.
  • Für Codex einen eigenen Key verwenden, damit Limit, Ablaufdatum und Widerruf getrennt möglich sind.
  • Standardmäßig schreibgeschützte Sandbox; Schreibrechte auf konkrete Repository-Verzeichnisse begrenzen und nach der Aufgabe zurücknehmen.
  • .env, auth.json, Produktionskonfiguration und Kundendaten nicht in den Kontext aufnehmen; bei großen Repositories Build-Artefakte und Abhängigkeitsverzeichnisse ausschließen.
  • Von Codex erzeugte Befehle und Patches prüfen, besonders Löschungen, Netzwerkanfragen und Rechteausweitungen.
  • Im Team-Image eine feste Codex-Version verwenden und vor dem Upgrade die Konfigurationskompatibilität in einer Testumgebung prüfen.
  • Verbrauchsalarme im Gateway aktivieren; bei ungewöhnlichen Aufrufen zuerst den Key stoppen und dann die Logs untersuchen.

Häufige Fragen

Muss Codex CLI zwingend das Responses-Protokoll verwenden?

Der eigene Provider akzeptiert für wire_api derzeit nur responses; die alte chat-Schreibweise ist veraltet. Bietet das Gateway nur Chat Completions, ist eine Konvertierungsschicht oder ein Eingang mit Responses-Unterstützung erforderlich.

Die Konfiguration ist geschrieben – warum geht die Anfrage trotzdem an die Standardadresse?

Zuerst prüfen, ob ~/.codex/config.toml bearbeitet wurde, dann ob die Top-Level-Schlüssel vor der Tabellenüberschrift stehen und model_provider exakt der Provider-ID entspricht. Providerdefinitionen in Projektkonfigurationen werden ignoriert – das ist eine häufige Ursache.

Darf der Key direkt in config.toml stehen?

Nicht empfehlenswert. env_key für eine Umgebungsvariable verwenden oder über [model_providers.xxx.auth] ein externes Token-Kommando aufrufen. Klartext-Keys geraten leicht über Konfigurationsbackups, Screenshots oder Repositories nach außen.

Werden ChatGPT-Anmeldung und API-Key gleich abgerechnet?

Nein. Die ChatGPT-Anmeldung nutzt das Kontosystem, der API-Key wird nach Verbrauch über die Schnittstelle abgerechnet. Limits, Rechnungen und Rechte unterscheiden sich; im Team-Einkauf getrennt kalkulieren.

Kann ein Team denselben Key gemeinsam verwenden?

Nicht empfehlenswert. Bei einem gemeinsamen Key lässt sich nicht feststellen, wer aufruft, und bei Offenlegung oder Austritt einer Person ist kein gezielter Widerruf möglich. Keys pro Person und Umgebung mit Limit und Ablaufdatum sind kontrollierbarer.

Nächster Schritt

Die Schwierigkeit bei Codex liegt weniger in der Installation als in Protokollübereinstimmung und Berechtigungsgrenzen: zuerst bestätigen, dass das Gateway Responses und das Streaming-Abschlussereignis unterstützt, dann Base URL, Key und Modell konfigurieren und schließlich mit einer schreibgeschützten Sandbox einen Smoke-Test durchführen. Für einen einheitlichen Eingang und Verbrauchsverwaltung können Sie sich im ZSQH AI Gateway registrieren; Modell- und Schnittstellenumfang entnehmen Sie den Modellpreisen.

Weiterführende Beiträge: