Ein Gateway einführen

Verteilen und überprüfen Sie eine Codex-Gateway-Verbindung für Ihre Organisation

Konfigurieren Sie als Gateway-Administrator die Modellrouten und autorisieren Sie einen Pilotbenutzer. Testen Sie die Verbindung auf jedem unterstützten Client, bevor Sie Einstellungen an Entwickler verteilen. Verwenden Sie natives Gateway-OAuth, API keys oder Hilfsprogramme für Zugangsdaten zur Gateway-Authentifizierung. Wie Sie die Gateway-Authentifizierung mit der Anmeldung bei einem ChatGPT-Arbeitsbereich kombinieren, erfahren Sie unter Mit ChatGPT über ein Gateway anmelden.

Voraussetzungen

Vergewissern Sie sich vor der Bereitstellung von Codex für Entwickler, dass Folgendes vorhanden ist:

  • Ein Gateway, das HTTPS unter genau der Basis-URL bereitstellt, die Sie verteilen werden.
  • Zugangsdaten für den Upstream-Anbieter, die auf dem Gateway hinterlegt sind.
  • Genehmigte, für Codex sichtbare Modellaliase, die den vorgesehenen Upstream-Modellen zugeordnet sind.
  • Eine getestete Authentifizierungsmethode: natives Gateway-OAuth, Gateway-API keys mit eingeschränkten Berechtigungen oder ein Zugangsdaten-Hilfsprogramm.
  • Für OAuth: einen registrierten öffentlichen Client, genehmigte Testbenutzer und Gateway-Unterstützung für die Validierung von OAuth-Zugriffstokens.
  • Für API keys oder Hilfsprogramme: einen Mechanismus zur Bereitstellung von Geheimnissen oder ein getestetes Hilfsprogramm.
  • Eine Möglichkeit, die Konfiguration, gegebenenfalls erforderliche Hilfsprogramme und Katalogdateien zu verteilen.

Gateway-Anforderungen

Prüfen Sie vor dem Verbinden von Codex, ob das Gateway-Produkt diese erforderlichen Verhaltensweisen beibehält:

  • Codex-Anfragen an die Responses API unter POST /v1/responses akzeptieren.
  • SSE-Ereignisse ohne Pufferung streamen und mit response.completed abschließen.
  • Die Fortsetzung in Folgerunden mit erneut übermittelten Eingaben beibehalten.
  • previous_response_id nur dann beibehalten, wenn WebSocket oder inkrementeller Transport aktiviert ist.
  • Funktionsaufrufe und die zugehörigen function_call_output-Elemente beibehalten.
  • Jeden für Codex sichtbaren Modellalias an das vorgesehene Upstream-Modell weiterleiten.
  • Benutzer separat authentifizieren und aussagekräftige Fehler zurückgeben, ohne die Ursache zu verbergen.

Ein Endpunkt zur Zustandsprüfung, /v1/models, eine Chat-Completions-Antwort oder eine einzelne reine Textantwort weist die Eignung des Gateways nicht nach. Die detaillierten Vorgaben finden Sie unter Anforderungen an die Gateway-Kompatibilität.

Das Gateway einführen

Durchlaufen Sie diese fünf Prüfpunkte in der angegebenen Reihenfolge, um von einem bereitgestellten Gateway zu einer überprüften Entwicklerumgebung zu gelangen:

  1. Modellnamen wählen und Routen überprüfen.
  2. Authentifizierung auswählen.
  3. Codex über das Gateway testen.
  4. Die Konfiguration verteilen.
  5. Auf einem Entwicklerrechner überprüfen.

Modellnamen und Routen wählen

Setzen Sie model in Codex auf den Modellnamen des Gateways. Konfigurieren Sie das Gateway so, dass es diesen Namen an das genehmigte Upstream-Modell weiterleitet.

Gateway-Modellname Codex-Konfiguration
Ein in Ihrer Codex-Version enthaltener integrierter Modellname Legen Sie model in config.toml auf genau diesen Namen fest.
Ein benutzerdefinierter Alias wie company-coding-model Stellen Sie einen Remote- oder lokalen Katalog bereit, der den Alias und die Metadaten des entsprechenden Modells enthält.

Einen Modellkatalog für benutzerdefinierte Namen verwenden

Verwenden Sie für einen lokalen Katalog das models.json-Beispiel als Ausgangspunkt.

Stellen Sie einen Modellkatalog bereit, wenn Ihr Gateway einen Modellnamen verwendet, den Codex nicht erkennt. Der Katalog stellt die Anweisungen, Optionen für Schlussfolgerungen, Kontextgrenzen und Tool-Funktionen bereit, die Codex für diesen Namen verwendet. Ohne einen passenden Eintrag kann eine Anfrage das vorgesehene Upstream-Modell erreichen, während Codex generische Einstellungen verwendet.

Hosten Sie mit model_providers.<id>.model_catalog_url einen Remotekatalog, um Modellmetadaten zentral zu aktualisieren, oder verteilen Sie mit model_catalog_json eine lokale Datei. Verwenden Sie einen lokalen Katalog, wenn natives Gateway-OAuth die einzige Authentifizierungsmethode ist; OAuth allein ermöglicht keine automatische Erkennung von Remotekatalogen. Informationen zu beiden Einstellungen finden Sie in der Konfigurationsreferenz.

Beziehen Sie von Ihrem Cloud- oder Gateway-Anbieter einen Katalogendpunkt oder eine Katalogdatei, der bzw. die mit Ihrer Codex-Version kompatibel ist. Stellen Sie sicher, dass alle freigegebenen Aliase und die zugehörigen Modellmetadaten enthalten sind. Informationen zur Katalogimplementierung finden Sie unter Modellkataloge für Gateways und Clouds implementieren.

Remote-Katalog bereitstellen

Verwenden Sie den von Ihrem Anbieter bereitgestellten HTTPS-Katalogendpunkt. Verteilen Sie die vollständige Endpunkt-URL in der config.toml-Tabelle des ausgewählten Anbieters:

model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"

Stellen Sie CODEX_GATEWAY_API_KEY dem Codex-Prozess zur Verfügung. Legen Sie base_url separat fest, um die Inferenz über das Gateway zu leiten. Wenn Sie die Einstellung weglassen, verwendet Codex den standardmäßigen OpenAI-Endpunkt für den aktuellen Authentifizierungsmodus.

Die automatische Erkennung erfordert eine Authentifizierung per API key, per Befehl oder über das Codex-Backend. Natives Gateway-OAuth oder benutzerdefinierte Header allein lösen sie nicht aus.

Stimmen Sie Katalogaktualisierungen mit Ihrem Anbieter ab, wenn sich Ihre genehmigten Modelle ändern. Starten Sie den Client neu, nachdem Sie seine Konfiguration geändert haben.

Entfernen Sie jede wirksame Einstellung für model_catalog_json, auch wenn sie über requirements.toml erzwungen wird. Sie hat Vorrang vor der Remote-URL und verhindert den Abruf.

Lokalen Katalog verteilen

Verwenden Sie model_catalog_json, um die vom Anbieter bereitgestellte Datei beim Start zu laden. Ein lokaler benutzerdefinierter Katalog ersetzt den mitgelieferten Katalog.

Setzen Sie den Gateway-Alias, slug im Katalog und model in Codex auf company-coding-model. Fügen Sie diese Einstellungen vor der ersten TOML-Tabelle in der zu verteilenden Codex-Konfiguration ein und verwenden Sie dabei den tatsächlichen absoluten Pfad der Datei:

model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"

Starten Sie die CLI oder Desktop-App nach einer Katalogänderung neu, da Codex den Katalog beim Start lädt.

Modellrouten überprüfen

Überprüfen Sie für jedes Modell die Route mit einer echten Responses-Anfrage und den Gateway-Protokollen. Eine /v1/models-Antwort kann beim Ermitteln von Namen helfen, belegt aber nicht, dass ein Modell das erforderliche Anfrage- und Tool-Verhalten unterstützt.

Modellrouting und Tool-Autorisierung sind getrennte Bestandteile der Einführung. Konfigurieren Sie MCP-Verbindungen, die Plugin-Verteilung und deren Richtlinien separat.

Authentifizierung auswählen

Natives Gateway-OAuth

  1. Registrieren Sie einen öffentlichen OAuth-Client, der den Autorisierungscode-Flow mit PKCE unterstützt, und genehmigen Sie die Benutzer oder Gruppen, die sich anmelden dürfen.
  2. Konfigurieren Sie das Gateway so, dass es das ausgestellte Zugriffstoken im ausgewählten Cookie oder benutzerdefinierten Header validiert. Wenden Sie die genehmigten Modelle, Ratenlimits und Budgets auf die Identität jedes Benutzers an.
  3. Folgen Sie der Anleitung zu nativem Gateway-OAuth, um die Autorisierungs- und Token-URLs, die öffentliche Client-ID, Scopes, eine optionale Ressource, Einstellungen zur Token-Übermittlung und einen gegebenenfalls festen Redirect-Port zusammenzustellen. Registrieren Sie die passende Loopback-Redirect-URI bei Ihrem Identitätsanbieter.
  4. Testen Sie Browseranmeldung, Token-Aktualisierung und Zugriffsentzug mit einem Testbenutzer in der CLI oder Desktop-App, die Sie bereitstellen möchten. Stellen Sie sicher, dass der Browser den Callback erreichen kann, auch bei Benutzern einer Remote-CLI.

Benutzer melden sich einzeln an. Sie verteilen die OAuth-Konfiguration, kein Client-Secret, keinen Gateway-API key und keine ausführbare Hilfsprogrammdatei. Belassen Sie die Zugangsdaten des Upstream-Anbieters auf dem Gateway.

API keys oder Zugangsdaten-Hilfsprogramme

  1. Stellen Sie für jeden Entwickler eigene Gateway-Zugangsdaten mit eingeschränktem Berechtigungsumfang aus, damit Sie die Nutzung zuordnen und den Zugriff individuell widerrufen können.
  2. Legen Sie die genehmigten Modelle, Ratenbegrenzungen, das Budget, den Ablaufzeitpunkt und den Erneuerungszeitraum für jeden Zugang fest.
  3. Stellen Sie Zugangsdaten über Ihre Geheimnisverwaltung oder ein installiertes Hilfsprogramm für Zugangsdaten bereit. Speichern Sie Zugangsdaten für Upstream-Anbieter und Gateway-Administratoren nicht auf Entwicklerrechnern.
  4. Wenn Sie ein Hilfsprogramm verwenden, halten Sie sich an die Vorgaben für befehlsbasierte Authentifizierung und testen Sie den Abruf und die Aktualisierung von Tokens vor der Verteilung.
  5. Erklären Sie Entwicklern, wie sie ihre Zugangsdaten erneuern und an wen sie sich bei Fragen wenden können.

Codex über das Gateway testen

Bevor Sie etwas verteilen, richten Sie anhand von Anbieter konfigurieren einen isolierten Testbenutzer mit dem Anbieterblock und der Authentifizierungsmethode ein, die Sie verteilen möchten.

Wenn das Gateway den Modellkatalog bereitstellt, vergewissern Sie sich, dass es ein Codex-kompatibles models-Array zurückgibt. Vergewissern Sie sich bei OpenAI-Inferenz mit dem Zugangsnachweis des Benutzers, dass das Gateway die erforderlichen ChatGPT-Header an das Codex-Backend weiterleitet.

Dokumentieren Sie für Ihren Pilottest die Client-Version, das Betriebssystem, die Anbieter-ID, den Modellalias und die Authentifizierungsmethode. Führen Sie die folgenden Prüfungen in jeder CLI- oder Desktop-Oberfläche aus, die Sie unterstützen möchten. Wenn Sie sowohl eine ausschließliche Gateway-Authentifizierung als auch eine Gateway-Authentifizierung zusammen mit der ChatGPT-Anmeldung anbieten, testen Sie jede Kombination separat.

Prüfung Aktion Erfolgskriterium
Wirksame Konfiguration Prüfen Sie die Konfigurationsebenen und bestätigen Sie den vorgesehenen Anbieter, das Modell und die Anforderungen. Im Pilotbetrieb werden die verteilten Einstellungen verwendet. Benutzer- oder Profilstandardwerte wählen keine andere Route aus.
Verbindung Folgen Sie Verbindung überprüfen. Der erwartete Anbieter und Alias sind aktiv, der Testprompt wird erfolgreich ausgeführt und die Gateway-Protokolle identifizieren den Testbenutzer.
Streaming Fordern Sie eine kurze Antwort mit mehreren Absätzen an. Der Text trifft schrittweise ein und der aktive Transport gibt response.completed aus. Testen Sie HTTP separat, um sicherzustellen, dass das Gateway SSE-Ereignisse ohne Pufferung weiterleitet.
Lokale Tool-Schleife Bitten Sie Codex in einem temporären Ordner mit ausschließlich Leseberechtigungen, die Dateien auf der obersten Ebene aufzulisten und zusammenzufassen. Codex führt einen lokalen Tool-Aufruf aus, gibt das Ergebnis zurück und erstellt eine abschließende Antwort ohne Änderungen.
Folgefrage Stellen Sie im selben Thread eine Folgefrage. Die Antwort greift auf den vorherigen Gesprächsschritt zurück; das Gateway akzeptiert erneut übermittelte Eingaben. Wenn WebSocket oder inkrementeller Transport aktiviert ist, bleibt außerdem previous_response_id erhalten.
Fehler und Zuordnung Wiederholen Sie den Test mit einem absichtlich ungültigen Testalias oder abgelaufenen Testzugangsdaten. Der Client erhält eine aussagekräftige Routing- oder Authentifizierungsfehlermeldung, und gültige Anfragen bleiben dem Testbenutzer zugeordnet.

Wenn die automatische Genehmigung aktiviert ist, lösen Sie in einem temporären Testordner eine Tool-Aktion aus, die gemäß Ihrer vorgesehenen Richtlinie überprüft werden muss. Bestätigen Sie, dass das Gateway die Überprüfungsanfrage verarbeitet und der Client die Genehmigungsentscheidung anwendet. Ein schreibgeschützter Tool-Aufruf, der keine Genehmigung benötigt, testet diesen Ablauf nicht. Dokumentieren Sie alle nicht unterstützten Arbeitsabläufe, bevor Sie den Pilotbetrieb ausweiten.

Wenn der Rollout den Anbieter für bestehende Benutzer ändert, testen Sie auf jedem unterstützten Client eine neue Unterhaltung sowie eine Unterhaltung, die vor der Änderung erstellt wurde. Dokumentieren Sie, ob Benutzer die bestehende Unterhaltung anzeigen, fortsetzen oder verzweigen können, und stellen Sie ihnen für jeden blockierten Arbeitsablauf ein Wiederherstellungsverfahren bereit. Gehen Sie nicht davon aus, dass eine Änderung des Standardanbieters den Unterhaltungsverlauf migriert.

Bereiten Sie nach erfolgreichem Abschluss dieser Prüfungen die Übergabe an die Entwickler vor.

Die Konfiguration verteilen

Verteilen Sie die Gateway-Basis-URL, die Anbieter-ID, den genehmigten Modellalias und die Authentifizierungseinstellungen, um auf jedem Rechner denselben Verbindungsweg einzurichten.

Was Sie verteilen sollten

Verteilen Sie für natives Gateway-OAuth die Anbietertabelle und die [model_providers.<id>.gateway_oauth]-Tabellen aus der Verbindungsanleitung mit den oben zusammengestellten Registrierungswerten. Behalten Sie requires_openai_auth = false bei und lassen Sie env_key, experimental_bearer_token und die befehlsgestützte auth-Tabelle weg, wenn OAuth die einzige Authentifizierungsmethode für das Gateway ist.

Verteilen Sie für ein Zugangsdaten-Hilfsprogramm den folgenden config.toml-Block über die von Ihnen gewählte Konfigurationsebene. Verwenden Sie ein Modell, das Ihre Codex-Version erkennt, oder stellen Sie den oben beschriebenen passenden Katalog bereit. Installieren Sie Ihren Token-Resolver unter dem konfigurierten Befehlspfad:

model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"

[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

Entfernen Sie für einen kurzlebigen statischen Testschlüssel den Authentifizierungsblock, platzieren Sie env_key = "CODEX_GATEWAY_API_KEY" innerhalb von [model_providers.enterprise-gateway] und setzen Sie diese Variable außerhalb von TOML. Kombinieren Sie env_key nicht mit befehlsbasierter Authentifizierung.

Standardwerte und Anforderungen verteilen

Wenn sich Ihre Benutzer nicht mit ChatGPT bei Codex anmelden, können Sie Teameinstellungen von Ihrem eigenen Server verteilen. Codex ruft diese Einstellungen unabhängig davon ab, wie Sie Modellanfragen weiterleiten.

Entscheiden Sie anhand von Konfigurationspriorität, wo Sie Standardwerte verteilen. Informationen zu erzwungenen Einstellungen und macOS-MDM- Payloads finden Sie unter Verwaltete Konfiguration.

Verwenden Sie für rechnerweite Standardwerte unter macOS oder Linux /etc/codex/config.toml. Platzieren Sie unter Windows config.toml in %ProgramData%\OpenAI\Codex\. Benutzer und Profile können diese Standardwerte überschreiben. Die verlinkten Referenzen beschreiben unterstützte Anforderungen und ihre Dateispeicherorte.

Verteilen Sie alle referenzierten Hilfsprogramme und lokalen Katalogdateien separat.

Um eine Remote-Katalog-URL zu erzwingen, tragen Sie die vollständige Anbieterdefinition in requirements.toml unter [model_providers.<id>] ein. Eine erzwungene Anbieterdefinition ersetzt die entsprechende Anbietertabelle aus der regulären Konfiguration; nehmen Sie base_url, Authentifizierungseinstellungen und andere erforderliche Felder auf. Verwenden Sie die Anforderung model_provider, wenn Sie zusätzlich die Auswahl des Anbieters erzwingen müssen.

model_catalog_json verweist auf eine lokale JSON-Datei. Wenn Sie dies über requirements.toml erzwingen, legt die Anforderung den Pfad fest; sie verteilt die Datei nicht. Legen Sie den Katalog unter diesem absoluten Pfad ab, bevor Codex startet.

Tragen Sie in TOML aufgelöste absolute Windows-Pfade ein. Codex löst %ProgramData% innerhalb von model_catalog_json oder in command-Werten der Anbieterauthentifizierung nicht auf. Verwenden Sie beispielsweise diese Pfade nur, wenn Ihre Bereitstellung die Dateien dort abgelegt hat:

model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'

[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]

Eine CLI innerhalb von WSL liest Linux-Pfade und das Linux-Verzeichnis CODEX_HOME; sie übernimmt nicht automatisch die native Windows-Konfiguration.

Routing-Header verteilen

Wenn Ihr Gateway Anfragen nach Konfiguration oder Tool weiterleitet, fügen Sie dem Anbieter in Ihrer verwalteten requirements.toml die erwarteten Header hinzu. Das folgende Beispiel übergibt eine Routing-Konfigurations-ID und identifiziert Codex als Client:

[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'

Verwenden Sie env_http_headers für Header-Werte, die von der Clientumgebung bereitgestellt werden. Senden Sie eine Testanfrage und bestätigen Sie die ausgewählte Route in den Gateway-Protokollen. Informationen zu Header-Optionen finden Sie unter Benutzerdefinierte Modellanbieter.

Entwicklern die Konfigurationswerte übergeben

Geben Sie Entwicklern einen Einrichtungsweg vor, der dem getesteten Pilotbetrieb entspricht. Stellen Sie die folgenden Informationen auch dann bereit, wenn Sie die Konfiguration zentral verteilen:

Übergabepunkt Bereitzustellende Informationen
Freigegebener Client Der im Pilotbetrieb verwendete Client, seine Version, das Betriebssystem und die Installations- oder Aktualisierungsanleitung.
Konfigurationsverteilung Ob die Einstellungen bereits verwaltet werden oder eine lokale Einrichtung erfordern; nennen Sie alle separat installierten Hilfsprogramme oder Katalogdateien.
Erwartete Verbindung Die Anbieter-ID, der Modellalias und die Gateway-URL einschließlich ihres API-Pfads. Erläutern Sie, welche Werte Benutzer ändern dürfen.
Anmeldeschritte Ob sich Benutzer bei einem ChatGPT-Workspace anmelden, beim Gateway authentifizieren oder beides tun müssen. Nennen Sie den erforderlichen Workspace und die Authentifizierungsmethode des Gateways.
Zugangsdaten und Kataloge Die OAuth-Registrierungswerte, die Umgebungsvariable für Zugangsdaten oder die installierte Hilfsprogrammkonfiguration sowie alle Katalog-URLs oder aufgelösten lokalen Pfade. Übermitteln Sie Geheimnisse über Ihr freigegebenes Verfahren zur Verteilung von Geheimnissen.
Überprüfung und Support Der Verbindungstest, das erwartete Ergebnis, die für das Gateway verantwortliche Person und die Informationen, die bei einer Fehlermeldung anzugeben sind.

Verweisen Sie Entwickler bei verwalteten Rechnern auf Auf eine vorhandene Konfiguration prüfen. Verweisen Sie sie bei manueller Einrichtung auf Anbieter konfigurieren.

Fügen Sie Ihre getesteten Anweisungen für bestehende Unterhaltungen bei, wenn dieser Rollout den Anbieter ändert. Halten Sie die bisherige funktionierende Konfiguration für die für den Rollout verantwortliche Person bereit, falls im Pilotbetrieb ein Problem auftritt.

Die manuelle Einrichtung ist kein Kanal zur Durchsetzung von Vorgaben. Eine projektlokale .codex/config.toml kann sensible Schlüssel für Anbieter- oder Authentifizierungsrouting nicht überschreiben.

Auf einem Entwicklerrechner überprüfen

So bestätigen Sie, dass die verteilten Einstellungen einen Entwicklerrechner erreicht haben:

  1. Bestätigen Sie, dass der freigegebene Client und alle erforderlichen Hilfsprogramme oder Katalogdateien installiert sind. Starten Sie Codex neu und führen Sie die in Ihren Übergabeunterlagen beschriebenen Anmeldungen durch.
  2. Bestätigen Sie den erwarteten Anbieter und das Modell. Verwenden Sie in der CLI /status. Prüfen Sie mit /debug-config die Konfigurationsebenen, wenn die wirksamen Einstellungen von den Übergabeunterlagen abweichen.
  3. Führen Sie den kurzen Test unter Mit einem Gateway verbinden aus.
  4. Stellen Sie eine Folgefrage, um die Fortsetzung zu bestätigen, und prüfen Sie dann die Gateway-Protokolle auf die Anfrage des betreffenden Entwicklers.

Erweitern Sie den Zugriff, nachdem der Pilotbetrieb mit den von Ihnen unterstützten Clients und Authentifizierungskombinationen erfolgreich abgeschlossen wurde. Bewahren Sie die getestete Konfiguration und die Ergebnisse zusammen mit Ihren Rollout-Anweisungen auf, damit Sie die Prüfungen nach Aktualisierungen des Clients, des Gateways oder der Richtlinien wiederholen können.

Fehler bei der Einführung beheben

Ermitteln Sie anhand des Problems, welche Konfigurations-, Zugangsdaten- oder Gateway-Ebene überprüft werden muss:

Problem Abhilfe
Der erwartete Anbieter fehlt nach dem Neustart. Prüfen Sie die Konfigurationsebene mit der höchsten wirksamen Priorität. Benutzer- oder Profilkonfigurationen können Systemvorgaben überschreiben.
Die Authentifizierung schlägt für alle Benutzer fehl. Prüfen Sie die Gateway-Authentifizierung und die Zugangsdaten des Upstream-Anbieters; ermitteln Sie, welcher Dienst die Anfrage abgelehnt hat.
Die Authentifizierung schlägt für einen Benutzer fehl. Prüfen Sie den Zugriff dieses Benutzers beim Identitätsanbieter, seine Gateway-Zugangsdaten oder seinen Token-Resolver.
Das Streaming stockt. Prüfen Sie die Gateway-Pufferung und die Weiterleitung des abschließenden response.completed.
Ein Modell fehlt oder verwendet allgemeine Funktionen. Bestätigen Sie bei einem benutzerdefinierten Alias, dass Gateway-Alias, Codex-model und Katalog-slug übereinstimmen. Prüfen Sie den Katalogpfad und die Kompatibilität mit der installierten Codex-Version und starten Sie Codex anschließend neu.
Ein Windows-Pfad funktioniert nicht. Verwenden Sie aufgelöste absolute Pfade. Verwenden Sie in TOML Zeichenfolgen in einfachen Anführungszeichen für Windows-Pfade mit einzelnen umgekehrten Schrägstrichen.

Eine bestehende Gateway-Bereitstellung wiederverwenden

Wenn Ihre Organisation Claude Code bereits über ein Gateway verwendet, können Sie möglicherweise das Gateway-Produkt, den Netzwerkpfad, die Protokollierung und den Bedrock-Zugriff wiederverwenden. Fügen Sie eine für Codex zugängliche Responses-Route, Zugangsdaten, Modellaliase und config.toml hinzu und behalten Sie die bestehende funktionierende Einrichtung bei. Claude-Clienteinstellungen und die Vorgaben für /v1/messages konfigurieren Codex nicht.

Bestehende Claude-Bereitstellung Codex-Migration
Gateway-Produkt, DNS, TLS, private Vernetzung, Protokollierung, Schwärzung und Überwachung Behalten Sie diese Dienste bei. Fügen Sie eine für Codex zugängliche Route hinzu, die die Anforderungen an die Gateway-Kompatibilität erfüllt.
Bedrock-Konto, Anbieterzugangsdaten, IAM-Berechtigungsgrenze, Inferenzprofile und Rotation der Zugangsdaten Behalten Sie diese nur bei, wenn sie die Upstream-Modelle hinter den neuen Codex-Aliasen autorisieren. Die Anbieterzugangsdaten verbleiben auf dem Gateway.
Claude-Route /v1/messages, Bedrock-InvokeModel-Format, Anthropic-Header und Claude-spezifische Wiederholungsversuche oder Fehler Verwenden Sie diese nicht als Kompatibilitätsnachweis. Codex benötigt POST /v1/responses, Responses-Streaming, Fortsetzung, Tool-Aufrufe und aussagekräftige Fehler.
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY oder apiKeyHelper Codex unterstützt apiKeyHelper nicht. Konfigurieren Sie natives Gateway-OAuth, einen Schlüssel mit eingeschränkten Berechtigungen über env_key oder einen befehlsgestützten Token-Resolver für Codex.
Claude-Modellnamen, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides und Bedrock-Profilzuordnungen Lassen Sie Ihr Gateway-Team Modellnamen wählen und gegebenenfalls benutzerdefinierte Aliase konfigurieren. Verwenden Sie den bereitgestellten Modellnamen und gegebenenfalls die Modellkatalog-JSON-Datei.
Claude-settings.json, managed-settings.json, JSON-env-Blöcke, plist oder Registry-Payloads Behalten Sie denselben MDM- oder Konfigurationsverwaltungskanal bei, verteilen Sie darüber jedoch Codex-config.toml und unterstützte requirements.toml-Werte.

Führen Sie für eine sichere Migration diese Schritte in der angegebenen Reihenfolge aus:

  1. Erfassen Sie den aktuellen Claude-Verbindungsweg: Gateway-URL, Quelle der Zugangsdaten, erforderliche Header, Modellaliase, Bedrock-Profilzuordnungen und verwalteter Verteilungskanal.
  2. Fügen Sie eine parallele Responses-Route für Codex und Codex-Modellaliase hinzu.
  3. Wählen Sie natives Gateway-OAuth, einen API key oder ein Hilfsprogramm für Zugangsdaten und autorisieren Sie einen Testbenutzer. Stellen Sie statische Zugangsdaten über env_key bereit; implementieren und testen Sie bei einem Hilfsprogramm die Schnittstellenvorgaben für den befehlsbasierten Codex-Resolver.
  4. Konfigurieren Sie den Anbieter für diesen Entwickler mit der in Schritt 3 ausgewählten Authentifizierungsmethode. Übertragen Sie bei einem verwalteten Rollout die Nutzlast in die unter Gateway ausrollen beschriebenen Codex-Pfade und Vorrangregeln.
  5. Führen Sie die kurze Verbindungsprüfung in der tatsächlich verwendeten CLI- oder Desktop-Oberfläche des Entwicklers aus. Führen Sie anschließend alle Prüfungen zu Streaming, Fortsetzung, Tool-Aufrufen, Fehlern, Protokollierung und Alias-Routing unter Codex über das Gateway testen durch.
  6. Verteilen Sie die Konfiguration nach erfolgreichem Pilotbetrieb an die übrigen Entwickler.

Modellkatalogreferenz

Mit einer lokalen models.json-Datei beginnen

Konfigurieren Sie zunächst Ihren Gateway-Anbieter und wählen Sie ihn aus, und zwar auf dem Rechner, auf dem Sie Codex ausführen.

Speichern Sie diesen Katalog als models.json auf dem Rechner, auf dem Codex ausgeführt wird. Ersetzen Sie gateway-model durch die genaue Modell-ID, die Ihr Gateway akzeptiert. Der Anzeigename ist die Bezeichnung, die Benutzer in der Modellauswahl sehen.

{
  "models": [
    {
      "slug": "gateway-model",
      "display_name": "Gateway model",
      "base_instructions": "Help the user with their coding tasks.",
      "supported_reasoning_levels": [],
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 0,
      "support_verbosity": false,
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "experimental_supported_tools": []
    }
  ]
}

Ein umfangreicheres Beispiel finden Sie im Modellkatalog von Codex.

Setzen Sie model_catalog_json in config.toml auf den absoluten Pfad der Datei. Starten Sie Codex neu, wählen Sie Gateway model aus und senden Sie eine Anfrage. Prüfen Sie, ob das Gateway die Modell-ID erhalten hat, die Sie in slug festgelegt haben.

Kopieren Sie für einen Alias eines mitgelieferten Modells dessen vollständigen Katalogeintrag für Ihre Codex-Version und ändern Sie slug und display_name. Wenn der Alias kein Migrationsziel hat, setzen Sie upgrade auf null. Dadurch bleiben das Kontextfenster, die Reasoning-Optionen und die Tool-Einstellungen des Modells erhalten.

Einen Katalog für Clients bereitstellen

Diese Seite richtet sich an Entwickler, die das Codex Models-Format implementieren. Es definiert den Modellkatalog und bildet die Grundlage für die Modellauswahl. Wenn Sie einen Inferenzanbieter wie ein Gateway oder einen Cloud-Dienst entwickeln, verwenden Sie diese Spezifikation, damit die Codex-Desktop-App und die CLI Ihre Modelle erkennen und deren Anweisungen sowie Funktionseinstellungen verwenden können.

Wenn Sie ein Unternehmen administrieren und den Modellkatalog steuern möchten, lesen Sie die Konfigurationshinweise zu model_catalog_url.

Um das Format zu unterstützen, implementieren Sie einen Katalogendpunkt mit Authentifizierung. Rufen Sie die aktuellen Standardwerte Ihres vorgelagerten Anbieters für die anfragende Codex-Version ab, wenden Sie Ihre Überschreibungen an und geben Sie den resultierenden Katalog zurück.

Katalogendpunkt implementieren

Der standardmäßige Katalogendpunkt ist /models unter der base_url des Anbieters. Bei base_url = "https://gateway.example.com/v1" sendet Codex beispielsweise folgende Anfrage:

GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>

Die standardmäßige Erkennung unterstützt befehlsgestützte Authentifizierung und die Authentifizierung über das Codex-Backend, beispielsweise über ChatGPT. Für einen benutzerdefinierten Anbieter mit API key-Authentifizierung ohne befehlsgestützte Authentifizierung legen Sie model_providers.<id>.model_catalog_url explizit fest, um die Remote-Erkennung zu aktivieren. Ein API key allein löst keine Erkennung unter dem Standardpfad aus.

Verwenden Sie model_catalog_url, um eine vollständige Katalog-URL festzulegen, beispielsweise https://gateway.example.com/codex/models. Sie kann auch auf den standardmäßigen Endpunkt /v1/models verweisen. Codex verwendet diese URL direkt, ohne /models anzuhängen. Lassen Sie für die Erkennung per API key features.api_key_model_discovery aktiviert; diese Einstellung ist standardmäßig aktiv. Benutzerdefinierte Header allein aktivieren die Erkennung nicht.

Codex sendet die Authentifizierungsdaten und die konfigurierten Header des ausgewählten Anbieters und hängt client_version sowie etwaige query_params des Anbieters an. Hosten Sie den Katalog auf einem Dienst, der zum Empfang dieser Zugangsdaten berechtigt ist.

Authentifizieren Sie den Aufrufer, rufen Sie die entsprechenden vorgelagerten Standardwerte ab, wenden Sie Ihre Überschreibungen an und geben Sie das vollständige ModelsResponse-JSON direkt zurück. Geben Sie jedem Eintrag einen eindeutigen, nicht leeren slug. Bei einer expliziten model_catalog_url lehnt Codex Weiterleitungen und Antworten ab, die größer als 1 MiB sind. Setzen Sie die Modellzugriffskontrolle auch weiterhin bei Inferenzanfragen durch.

Entfernen Sie jede wirksame model_catalog_json-Einstellung von Clients, die den Endpunkt verwenden: Die lokale Datei hat Vorrang und verhindert den Remote-Abruf.

Schema des Clients einhalten

Lesen Sie den Abfrageparameter client_version in der Kataloganfrage aus. Codex sendet seine CLI-Version als major.minor.patch, wobei ein etwaiges Vorabversionssuffix entfernt wird. Bei Desktop- Clients ist dies die mitgelieferte CLI-Version.

Verwenden Sie das passende rust-v<version>-Tag im öffentlichen Codex-Repository oder den exakten Quellcode-Commit für einen benutzerdefinierten Build. Diese Links verwenden rust-v0.162.1; wählen Sie die zu Ihrem Client passende Revision:

Die mitgelieferte Datei ist eine Momentaufnahme einer Veröffentlichung. Rufen Sie aktuelle Standardwerte ab, bevor Sie Ihren Katalog erstellen.

Aktuelle vorgelagerte Standardwerte abrufen

Cloud-Anbieter, die OpenAI-Modelle bereitstellen, rufen Standardwerte von OpenAI ab. Gateways lesen den Katalog ihres Cloud-Anbieters oder vorgelagerten Anbieters, damit die Einstellungen des bereitgestellten Modells sowie dessen Verfügbarkeit nach Konto und Region erhalten bleiben. Übergeben Sie die anfragende Codex-Version bei jedem Schritt und authentifizieren Sie sich bei jedem Endpunkt separat.

Um Standardwerte direkt von OpenAI abzurufen, rufen Sie den Codex-Modellendpunkt mit demselben client_version auf. Beispielsweise mit einem OpenAI API key:

curl --fail --silent --show-error \
  'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Verwenden Sie für eine ChatGPT-Integration das ChatGPT-Zugriffstoken des Aufrufers und gegebenenfalls den Header ChatGPT-Account-ID. Verwenden Sie Zugangsdaten, die für den vorgelagerten Endpunkt autorisiert sind; der eigene API key Ihres Gateways authentifiziert nicht bei OpenAI.

Parsen Sie die vollständige Antwort einschließlich des Arrays models auf oberster Ebene. Dieser Endpunkt liefert Codex-Metadaten wie Anweisungen, Standardwerte für das Reasoning, Werkzeugeinstellungen, Kontextlimits und Service-Tiers. Der öffentliche Endpunkt /v1/models stellt diesen Katalog nicht bereit.

Aktualisieren Sie diese Standardwerte auch dann, wenn sich die Codex-Version nicht geändert hat. Beschränken Sie Anfragen auf die vorgesehene Identität beim vorgelagerten Anbieter und beachten Sie die Cache-Steuerung der Antworten: Kataloge können von den Zugriffsrechten des Aufrufers abhängen. Halten Sie Ihre Überschreibungen separat, damit Sie sie erneut auf aktuelle Standardwerte anwenden können.

Anbieterüberschreibungen anwenden

Ändern Sie Feldwerte unter Beibehaltung der Antwortstruktur der jeweiligen Version:

  • Filtern Sie die Modelle so, dass nur diejenigen enthalten sind, die der Aufrufer verwenden kann. Ordnen Sie jeden slug einer unterstützten Inferenzroute zu und passen Sie display_name, description oder priority an. Setzen Sie für einen Alias ohne Modellmigration upgrade auf null.
  • Legen Sie für Reasoning-Optionen, Kontextlimits, Eingabemodalitäten und Service-Tiers Werte fest, die Ihr Modell und Ihre Route unterstützen. Wählen Sie Standardwerte aus den unterstützten Optionen. Leeren Sie für eine Route ohne Service-Tiers service_tiers und additional_speed_tiers und setzen Sie default_service_tier auf null.
  • Behalten Sie vorgelagerte Anweisungen und Werkzeugeinstellungen bei, sofern Sie keinen Ersatz getestet haben. Metadaten erweitern weder die Modellfähigkeiten noch gewähren sie Zugriff auf die Inferenz.

Für einen Modellalias im Gateway erfahren Sie hier, wie Sie Modellmetadaten bereitstellen. Testen Sie den resultierenden Katalog mit jeder unterstützten Codex-Version.

Öffentliche Rust-Typen verwenden

Verwenden Sie Crates aus demselben öffentlichen Git-Tag oder Commit wie das Schema des Clients:

  • Verwenden Sie codex-protocol für codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Parsen Sie mit serde_json::from_slice::<ModelsResponse>(), bearbeiten Sie catalog.models und serialisieren Sie den gesamten Wrapper mit serde_json::to_vec(). Der Wrapper verarbeitet Kompatibilitätsfelder für Modellanweisungen.
  • Verwenden Sie codex-models-manager::bundled_models_response(), um den statischen, mitgelieferten Katalog dieser Revision als ModelsResponse zu laden. Dabei werden keine aktuellen vorgelagerten Standardwerte abgerufen.

Weiterführende Dokumentation