Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Zusammenarbeiten und teilen

Anforderungen an die Gateway-Kompatibilität

Prüfe, welche Anforderungen ein Gateway für Codex erfüllen muss

Diese Anforderungen gelten, wenn Codex über ein Gateway auf ein Modell zugreift und dafür API- oder Anbieterzugangsdaten verwendet. Wenn dein Gateway Anfragen aus einem ChatGPT-Workspace weiterleitet, siehe Über ein Gateway mit ChatGPT anmelden.

Beim Zugriff mit API- oder Anbieterzugangsdaten muss das Gateway das hier beschriebene Verhalten der Responses API beibehalten. Das umfasst Endpunkte, Streaming, die Fortsetzung von Gesprächen, Tool-Aufrufe, Authentifizierung, Routing und aussagekräftige Fehlermeldungen.

Wie du ein Gateway einführst, erfährst du in der Anleitung Gateway einführen. Wie du einen Entwicklungsrechner konfigurierst, erklärt die Anleitung API- oder Anbieterzugangsdaten verwenden.

Anfragen und Endpunkte

Konfiguriere einen Gateway-Anbieter mit wire_api = "responses". Bei einer Basis-URL wie https://gateway.example.com/v1 muss das Gateway POST /v1/responses akzeptieren und die Anfrage- und Antwortfelder beibehalten, die der Client verwendet. Ein funktionierender Endpunkt für Chat Completions oder Anthropic Messages belegt noch keine Kompatibilität mit der Responses API.

Endpunkte für Statusprüfungen und Modelllisten sind im Betrieb optional. Damit testest du weder ein Gespräch mit Codex noch die Unterstützung von Tools.

Streaming

Leite Server-Sent Events (SSE) fortlaufend weiter, ohne die gesamte Antwort zwischenzuspeichern. Behalte die Ereignistypen und ihre Nutzdaten bei, einschließlich des Ereignisses response.completed, das den erfolgreichen Abschluss signalisiert. Leite auch Ereignisse weiter, die einen Fehler oder Fehlschlag melden. So kann der Client unterscheiden, ob eine Antwort fehlgeschlagen ist oder die Verbindung hängt.

Prüfe den gesamten Stream über das Gateway sowie über alle beteiligten Load Balancer und Reverse Proxys. Eine Textantwort allein reicht nicht aus, wenn der Stream nicht vollständig abgeschlossen wurde.

Gespräche fortsetzen

Wenn der Client in späteren Gesprächsrunden frühere Eingaben erneut sendet, muss das Gateway sie unverändert übernehmen. Es muss die bisherigen Nachrichten, Tool-Aufrufe und Tool-Ergebnisse akzeptieren, die für die nächste Runde erforderlich sind.

Wenn du WebSocket oder eine inkrementelle Übertragung aktivierst, prüfe auch, wie die gewählte Übertragungsart mit previous_response_id umgeht. Bei zustandslosem Zugriff auf die Responses API über HTTP lassen sich frühere Eingaben erneut senden, ohne dass dieser Mechanismus zur Fortsetzung erforderlich ist.

Tools

Behalte die Elemente für Funktionsaufrufe und die zugehörigen function_call_output-Elemente bei. Dazu gehören auch die Kennungen, die Aufrufe und Ergebnisse einander zuordnen. Der gesamte Ablauf muss funktionieren. Codex empfängt einen Aufruf, führt das Tool aus, sendet dessen Ergebnis und erhält eine abschließende Antwort.

Eine erfolgreiche Textanfrage belegt nicht, dass dieser Ablauf funktioniert. Teste die Modelle und Clientfunktionen, die du tatsächlich aktivieren möchtest. Wenn das Gateway ein Anfragefeld akzeptiert, ist damit noch nicht belegt, dass das dahinterliegende Modell die entsprechende Funktion unterstützt.

Authentifizierung und Header

Das Gateway muss das für die Bereitstellung gewählte Verfahren zur Clientauthentifizierung unterstützen. Dafür kommen env_key oder per Befehl abgerufene Bearer-Token infrage. Für Zugangsdaten, die in einem benutzerdefinierten Header gesendet werden, verwende env_http_headers. Hinterlege geheime Header-Werte in Umgebungsvariablen und schreibe sie nicht direkt in die Konfiguration. Die Referenz für benutzerdefinierte Anbieter beschreibt die Konfiguration und die Schnittstelle für Hilfsprogramme, die Zugangsdaten bereitstellen.

Authentifiziere die einzelnen Mitglieder des Entwicklungsteams getrennt von der Identität, mit der sich das Gateway beim Modellanbieter ausweist. Bewahre Administratorschlüssel und Zugangsdaten für den Modellanbieter auf dem Gateway auf. Behalte die Header bei, die du für das Routing und die Zuordnung von Anfragen benötigst. Teste, was passiert, wenn Zugangsdaten ablaufen, erneuert oder widerrufen werden.

Modellrouting und Metadaten

Für jeden Modellnamen, den Codex verwendet, muss das Gateway die Anfragen an das vorgesehene Modell beim Anbieter weiterleiten. Prüfe die Route anhand der Gateway-Protokolle. Verlass dich dabei nicht auf die Selbstauskunft des Modells.

Verwende einen Namen, den die eingesetzte Codex-Version erkennt, oder stelle für einen eigenen Alias einen passenden Katalog bereit. Prüfe auch die Modellverfügbarkeit und die Metadaten zur Migration. Anfragen an jedes Ersatzmodell müssen über das Gateway laufen. Wenn für einen Alias deiner Organisation keine Migration vorgesehen ist, setze im Katalogeintrag upgrade auf null. Die Katalogmetadaten beeinflussen das Verhalten des Clients. Sie erweitern weder den Funktionsumfang eines Modells noch legen sie Routen im Gateway an. Prüfe die Kontextgrenzen, die Reasoning-Optionen und die Tools anhand des tatsächlich verwendeten Modells und Anbieters. Bei einer generischen Gateway-Verbindung werden die Metadaten nicht automatisch so angepasst wie bei den in Codex integrierten Anbieteranbindungen.

Erkannte Modellnamen

Verwende den exakten Modellnamen, den deine eingesetzte Codex-Version erkennt, sowohl als Gateway-Alias als auch als Wert für model in Codex. Vergewissere dich, dass der Modellanbieter das Modell unterstützt und deine Organisation es freigegeben hat.

Ermittle die Version mit codex --version und wähle das passende Tag rust-v<version> im Codex-Modellkatalog. Verwende bei einem eigenen Build den Commit, aus dem er erstellt wurde. Bei Desktop-Bereitstellungen ist die mitgelieferte CLI-Version maßgeblich. Die slug-Werte der Einträge zeigen dir, welche Namen diese Version erkennt. Wenn das Gateway den Funktionsumfang des Modells verändert, stelle Katalogmetadaten bereit, die diese Unterschiede abbilden. Das gilt auch dann, wenn Codex den Namen erkennt.

Fehler

Fehler bei der Clientauthentifizierung, unbekannte Modellrouten, überschrittene Ratenlimits und Fehler beim Modellanbieter müssen unterscheidbar bleiben. Gib nicht für jeden Fehler pauschal eine 500-Antwort zurück. Liefere genügend Informationen, um festzustellen, auf welcher Ebene der Fehler auftritt, ohne Token, Anbieterzugangsdaten oder vertrauliche Anfrageinhalte offenzulegen.

Datenverkehr und Zugriffsgrenzen bei Tools

Der Datenverkehr mit dem Modell nimmt folgenden Weg:

Codex client -> LLM gateway -> model provider

Der Client authentifiziert sich mit den persönlichen Zugangsdaten der entwickelnden Person beim Gateway. Das Gateway greift mit seinen eigenen Zugangsdaten beim Anbieter auf das Modell zu. Prompts, Quelltextauszüge, Tool-Argumente und Tool-Ergebnisse können über das Gateway laufen, wenn sie in Modellanfragen enthalten sind. Lege entsprechend fest, was protokolliert wird, wie lange Daten aufbewahrt werden, welche Inhalte unkenntlich gemacht werden und wer Daten einsehen oder exportieren darf.

Nur ein Teil der Verbindungen, die Codex herstellt, läuft über das Modell-Gateway. Lokale Befehle laufen in der Ausführungsumgebung des Clients. MCP-Server, Plugin-Dienste, Interaktionen mit Browsern und Apps sowie andere aktivierte Dienste können eigene Netzwerkpfade und Zugangsdaten verwenden. Die Konfiguration des Modellanbieters erteilt keine Berechtigungen für diese Zugriffe und ersetzt keine der dafür geltenden Netzwerkkontrollen. Mehr zu diesen Grenzen erfährst du in Genehmigungen und Sicherheit für Agenten und MCP.

Checkliste zur Kompatibilitätsprüfung

Dokumentiere für jede eingesetzte Kombination aus Client, Gateway und Modell die Ergebnisse der folgenden Prüfungen:

  • Anfrage- und Antwortfelder der Responses API.
  • Fortlaufende Übermittlung von SSE-Ereignissen und erfolgreicher Abschluss des Streams.
  • Fortsetzung des Gesprächs mit erneut gesendeten Eingaben.
  • previous_response_id, wenn die gewählte Übertragungsart dieses Feld verwendet.
  • Funktionsaufrufe, zugehörige Ergebnisse und eine abschließende Antwort.
  • Korrektes Modellrouting und passende Metadaten.
  • Zuordnung von Anfragen zu einzelnen Personen sowie Erneuerung und Widerruf ihrer Zugangsdaten.
  • Aussagekräftige Fehlermeldungen bei Authentifizierungs- und Routingproblemen, überschrittenen Ratenlimits und Fehlern beim Modellanbieter.
  • Diagnosedaten mit unkenntlich gemachten vertraulichen Inhalten und Einhaltung der vorgesehenen Protokollierungsrichtlinie.

Erhebe diese Nachweise mit dem Testverfahren für die Gateway-Einführung, bevor du die Konfiguration verteilst.