Anforderungen an die Gateway-Kompatibilität

Codex-Gateways müssen das hier beschriebene Verhalten der Responses API beibehalten: Endpunkte, Streaming, Fortsetzung, Tool-Aufrufe, Authentifizierung, Routing und aussagekräftige Fehler.

Anfragen und Endpunkte

Konfigurieren Sie 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 vom Client verwendeten Anfrage- und Antwortfelder beibehalten. Ein funktionierender Chat-Completions- oder Anthropic-Messages-Endpunkt belegt keine Responses-Kompatibilität.

Endpunkte zur Zustandsprüfung und Modelllistenendpunkte sind optionale Betriebshilfen. Sie führen keine Codex-Unterhaltung durch und weisen keine Tool-Unterstützung nach.

Streaming

Leiten Sie Server-Sent Events (SSE) schrittweise weiter, anstatt die gesamte Antwort zu puffern. Behalten Sie Ereignistypen und Payloads bei, einschließlich des erfolgreichen abschließenden Ereignisses response.completed. Leiten Sie Fehler- und Fehlschlagereignisse weiter, damit der Client eine fehlgeschlagene Antwort von einer ins Stocken geratenen Verbindung unterscheiden kann.

Überprüfen Sie den vollständigen Stream auch über Load Balancer und Reverse Proxys sowie das Gateway. Eine Textantwort ohne abgeschlossenen Stream reicht nicht aus.

Fortsetzung von Unterhaltungen

Behalten Sie erneut übermittelte Unterhaltungseingaben über Folgerunden hinweg bei. Das Gateway muss die vorherigen Nachrichten, Tool-Aufrufe und Tool-Ergebnisse akzeptieren, die für die nächste Runde benötigt werden.

Wenn Sie WebSocket oder inkrementellen Transport aktivieren, überprüfen Sie auch das Verhalten von previous_response_id. Ein zustandsloser HTTP-Responses-Verbindungsweg kann erneut übermittelte Eingaben verwenden, ohne diesen Fortsetzungsmechanismus zu benötigen.

Tools

Behalten Sie Funktionsaufrufelemente und die zugehörigen function_call_output-Elemente bei, einschließlich der Kennungen, die Aufrufe mit Ergebnissen verknüpfen. Der vollständige Zyklus muss funktionieren: Codex erhält einen Aufruf, führt das Tool aus, übermittelt dessen Ergebnis und erhält eine abschließende Antwort.

Eine erfolgreiche Textanfrage überprüft diesen Zyklus nicht. Testen Sie die tatsächlichen Modelle und Clientfunktionen, die Sie aktivieren möchten. Wenn ein Gateway ein Anfragefeld akzeptiert, belegt das nicht, dass sein Upstream-Modell die entsprechende Funktion implementiert.

Authentifizierung und Header

Unterstützen Sie den für die Bereitstellung gewählten Mechanismus zur Clientauthentifizierung: env_key oder befehlsbasierte Bearer-Tokens oder env_http_headers für Zugangsdaten, die in einem benutzerdefinierten Header gesendet werden. Verwenden Sie Umgebungsvariablen für geheime Headerwerte; hinterlegen Sie diese nicht fest in der Konfiguration. Die Referenz für benutzerdefinierte Anbieter beschreibt die Konfiguration und die Vorgaben für Hilfsprogramme für Zugangsdaten.

Authentifizieren Sie Entwickler getrennt von der Identität des Upstream-Anbieters des Gateways. Belassen Sie Administratorschlüssel und Upstream-Zugangsdaten auf dem Gateway. Behalten Sie die Header bei, von denen Ihr Routing und Ihre Zuordnung abhängen, und testen Sie Ablauf, Erneuerung und Widerruf der Zugangsdaten.

Modellrouting und Metadaten

Jeder für Codex sichtbare Modellname muss an das vorgesehene Upstream-Modell weiterleiten. Überprüfen Sie die Route anhand der Gateway-Protokolle, anstatt sich auf die Selbstbeschreibung des Modells zu verlassen.

Verwenden Sie einen Namen, den die bereitgestellte Codex-Version erkennt, oder stellen Sie einen passenden Katalog für einen benutzerdefinierten Alias bereit. Prüfen Sie auch die Modellverfügbarkeit und die Migrationsmetadaten: Jedes Ersatzmodell muss über das Gateway geroutet werden. Setzen Sie bei einem organisationseigenen Alias ohne Migration upgrade in seinem Katalogeintrag auf null. Katalogmetadaten steuern das Clientverhalten; sie erweitern nicht die Funktionen eines Modells und erstellen keine Gateway-Routen. Überprüfen Sie Kontextgrenzen, Reasoning-Optionen und Tools anhand des tatsächlichen Upstream-Modells und Anbieters. Eine allgemeine Gateway-Verbindung erhält nicht automatisch die Metadatenanpassungen, die von den integrierten Anbieterintegrationen in Codex vorgenommen werden.

Erkannte Modellnamen

Verwenden Sie genau den Modellnamen, den Ihre bereitgestellte Codex-Version erkennt, als Gateway- Alias und für model in Codex. Bestätigen Sie, dass der Upstream-Anbieter das Modell unterstützt und Ihre Organisation es genehmigt.

Prüfen Sie codex --version und wählen Sie das passende Tag rust-v<version> im Codex-Modellkatalog aus. Verwenden Sie bei einem benutzerdefinierten Build dessen Quellcode-Commit; richten Sie sich bei Desktop-Bereitstellungen nach der mitgelieferten CLI-Version. Prüfen Sie die slug-Werte der Einträge, um die Namen zu ermitteln, die diese Version erkennt. Wenn das Gateway die Funktionen des Modells verändert, stellen Sie Katalogmetadaten bereit, die diese Unterschiede abbilden, auch wenn der Name erkannt wird.

Fehler

Behalten Sie aussagekräftige Unterscheidungen zwischen Fehlern bei der Clientauthentifizierung, unbekannten Modellrouten, Ratenbegrenzungen und Upstream-Fehlern bei. Fassen Sie nicht alle Fehler in einer allgemeinen 500-Antwort zusammen. Geben Sie genügend Informationen zurück, um die fehlerhafte Ebene zu diagnostizieren, ohne Tokens, Anbieterzugangsdaten oder sensible Anfrageinhalte offenzulegen.

Daten- und Tool-Grenzen

Der Modellverkehr folgt diesem Pfad:

Codex client -> LLM gateway -> model provider

Der Client authentifiziert sich mit Entwicklerzugangsdaten beim Gateway. Das Gateway verwendet seine Zugangsdaten für den Upstream-Anbieter, um auf das Modell zuzugreifen. Prompts, Quellcodeauszüge, Tool-Argumente und Tool-Ergebnisse, die in Modellanfragen enthalten sind, können das Gateway passieren. Legen Sie die Regeln für Protokollierung, Aufbewahrung, Schwärzung, Zugriff und Export entsprechend fest.

Das Modellgateway leitet nicht jede von Codex hergestellte Verbindung weiter. Lokale Befehle werden in der Ausführungsumgebung des Clients ausgeführt. MCP server, Plugin-Dienste, Browser- und App-Interaktionen sowie andere aktivierte Dienste können separate Netzwerkpfade und Zugangsdaten haben. Die Modellanbieterkonfiguration gewährt diese Berechtigungen nicht und ersetzt auch nicht deren Netzwerkkontrollen. Informationen zu diesen Grenzen finden Sie unter Agent-Genehmigungen und Sicherheit und MCP.

Checkliste zur Eignungsprüfung

Dokumentieren Sie Nachweise für jede bereitgestellte Kombination aus Client, Gateway und Modell:

• Responses-Anfrage- und Antwortfelder.
• Schrittweise SSE-Übertragung und erfolgreicher endgültiger Abschluss.
• Folgerunden mit erneut übermittelten Eingaben.
• previous_response_id, wenn der gewählte Transport dies verwendet.
• Funktionsaufrufe, zugehörige Ergebnisse und eine abschließende Antwort.
• Korrektes Modellrouting und passende Metadaten.
• Benutzerbezogene Zuordnung, Erneuerung und Widerruf.
• Aussagekräftige Authentifizierungs-, Routing-, Ratenbegrenzungs- und Upstream-Fehler.
• Diagnosedaten mit geschwärzten sensiblen Inhalten und die vorgesehene Protokollierungsrichtlinie.

Verwenden Sie das Testverfahren für die Einführung, um diese Nachweise vor der Verteilung der Konfiguration zu sammeln.