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

Ein Gateway einführen

Verteile die Konfiguration für die Codex-Gateway-Verbindung in deiner Organisation und prüfe, ob die Verbindung funktioniert.

Wenn du das Gateway administrierst, richte die Modellrouten ein und schalte eine Person für den Pilotversuch frei. Teste die Verbindung auf jedem unterstützten Client, bevor du die Einstellungen an dein Entwicklungsteam verteilst. Verwende für die Authentifizierung am Gateway natives Gateway-OAuth, API-Schlüssel oder Hilfsprogramme für Zugangsdaten. Wie du die Gateway-Authentifizierung mit der Anmeldung bei einem ChatGPT-Workspace kombinierst, erfährst du in der Anleitung Über ein Gateway mit ChatGPT anmelden.

Wenn du die Konfigurationswerte bereits erhalten hast und Codex auf deinem eigenen Rechner einrichten möchtest, folge der Anleitung Anbieter konfigurieren. Prüfe vor der Auswahl oder Einführung eines Gateways die Kompatibilitätsanforderungen für Gateways.

Voraussetzungen

Bevor du Codex für dein Entwicklungsteam bereitstellst, prüfe, ob Folgendes vorhanden ist:

  • Ein Gateway, das über HTTPS unter genau der Basis-URL erreichbar ist, die du verteilen wirst.
  • Zugangsdaten für den Upstream-Anbieter, die auf dem Gateway hinterlegt sind.
  • Freigegebene Modellaliase für Codex, die den vorgesehenen Upstream-Modellen zugeordnet sind.
  • Eine getestete Authentifizierungsmethode: natives Gateway-OAuth, Gateway-API-Schlüssel mit begrenztem Berechtigungsumfang oder ein Hilfsprogramm für Zugangsdaten.
  • Für OAuth: ein registrierter öffentlicher Client, freigeschaltete Testkonten und ein Gateway, das OAuth-Zugriffstoken validieren kann.
  • Für API-Schlüssel oder Hilfsprogramme: ein Verfahren zur sicheren Übermittlung von Zugangsdaten oder ein getestetes Hilfsprogramm.
  • Eine Möglichkeit, die Konfiguration, gegebenenfalls erforderliche Hilfsprogramme und Katalogdateien zu verteilen.

Anforderungen an das Gateway

Prüfe vor dem Verbinden von Codex, ob dein Gateway die folgenden Anforderungen erfüllt:

  • Es nimmt Anfragen von Codex an die Responses API unter POST /v1/responses entgegen.
  • Es leitet SSE-Ereignisse ohne Pufferung weiter und beendet den Stream mit response.completed.
  • Es ermöglicht Folgeanfragen, die den bisherigen Austausch mit erneut übermittelten Eingaben fortsetzen.
  • Es behält previous_response_id nur bei, wenn WebSocket oder der inkrementelle Transport aktiviert ist.
  • Es behält Funktionsaufrufe und die zugehörigen function_call_output-Elemente bei.
  • Es leitet Anfragen für jeden Modellalias in Codex an das vorgesehene Upstream-Modell weiter.
  • Es authentifiziert alle Personen einzeln und gibt aussagekräftige Fehlermeldungen zurück, aus denen die Ursache hervorgeht.

Ein Endpunkt für Zustandsprüfungen, /v1/models, eine Antwort der Chat Completions API oder eine einzelne Klartextantwort reichen als Nachweis der Kompatibilität nicht aus. Die genauen Vorgaben findest du in den Kompatibilitätsanforderungen für Gateways.

Suchst du einen Einstieg in die Implementierung? Das Repository zur Bereitstellung von Codex enthält ausgearbeitete Konfigurationsbeispiele für verschiedene LLM-Gateways. Nutze es als Referenz, nachdem du geprüft hast, dass dein Gateway die oben genannten Anforderungen erfüllt.

Gateway einführen

Sobald das Gateway bereitsteht, durchlaufe die folgenden fünf Schritte in der angegebenen Reihenfolge, um die Verbindung für dein Entwicklungsteam einzurichten und zu prüfen:

  1. Modellnamen auswählen und Routen prüfen.
  2. Authentifizierung auswählen.
  3. Codex über das Gateway testen.
  4. Konfiguration verteilen.
  5. Verbindung auf einem Rechner des Entwicklungsteams prüfen.

Modellnamen und Routen auswählen

Setze model in Codex auf den Modellnamen, den das Gateway verwendet. Konfiguriere das Gateway so, dass es Anfragen mit diesem Namen an das freigegebene Upstream-Modell weiterleitet.

Modellname im Gateway Codex-Konfiguration
Ein integrierter Modellname, den deine Codex-Version kennt Setze model in config.toml auf genau diesen Namen.
Ein eigener Alias, etwa company-coding-model Stelle einen Remote-Katalog oder einen lokalen Katalog bereit, der den Alias und die Metadaten des zugehörigen Modells enthält.

Einen Modellkatalog für eigene Namen verwenden

Verwende für einen lokalen Katalog das Beispiel für models.json als Ausgangspunkt.

Stelle einen Modellkatalog bereit, wenn dein Gateway einen Modellnamen verwendet, den Codex nicht kennt. Der Katalog gibt an, welche Anweisungen, Optionen für den Reasoning-Aufwand, Kontextgrenzen und Tool-Funktionen Codex für diesen Namen verwendet. Ohne passenden Eintrag kann eine Anfrage zwar das vorgesehene Upstream-Modell erreichen, Codex verwendet dann aber generische Einstellungen.

Stelle einen Remote-Katalog über model_providers.<id>.model_catalog_url bereit, um Modellmetadaten zentral zu aktualisieren, oder verteile eine lokale Datei und gib sie mit model_catalog_json an. Beide Einstellungen sind in der Konfigurationsreferenz beschrieben.

Lass dir von deinem Cloud- oder Gateway-Anbieter einen zu deiner Codex-Version passenden Katalogendpunkt oder eine entsprechende Katalogdatei geben. Prüfe, ob der Katalog alle freigegebenen Aliase und die jeweiligen Modellmetadaten enthält. Hinweise zur Implementierung findest du im Abschnitt Modellkataloge für Gateways und Clouds implementieren.

Einen Remote-Katalog bereitstellen

Verwende den HTTPS-Katalogendpunkt deines Anbieters. Verteile 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"

Stelle sicher, dass der Codex-Prozess auf CODEX_GATEWAY_API_KEY zugreifen kann. Setze base_url separat, damit Inferenzanfragen über das Gateway laufen. Ohne diese Angabe verwendet Codex den OpenAI-Standardendpunkt für den aktuellen Authentifizierungsmodus.

Wenn Gateway-OAuth die einzige Authentifizierungsmethode ist, gib die Katalog-URL ausdrücklich an. Schema, Host und Port müssen mit denen von base_url übereinstimmen. Codex verwendet die bestehende Gateway-Sitzung, ohne eine erneute Anmeldung anzufordern oder einen Katalogabruf per API-Schlüssel vorauszusetzen.

Stimme Katalogaktualisierungen mit deinem Anbieter ab, wenn sich die Liste der freigegebenen Modelle ändert. Starte den Client neu, nachdem du seine Konfiguration geändert hast.

Entferne 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.

Einen lokalen Katalog verteilen

Verwende model_catalog_json, damit Codex die Datei deines Anbieters beim Start lädt. Ein eigener lokaler Katalog ersetzt den mitgelieferten Katalog.

Setze den Gateway-Alias, das Katalogfeld slug und die Codex-Einstellung model auf company-coding-model. Füge die folgenden Einstellungen vor der ersten TOML-Tabelle in die Codex-Konfiguration ein, die du verteilst. Gib dabei den tatsächlichen absoluten Pfad der Datei an:

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

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

Modellrouten prüfen

Prüfe die Route für jedes Modell mit einer echten Anfrage an die Responses API und den zugehörigen Gateway-Protokollen. Eine Antwort von /v1/models kann dir helfen, Modellnamen zu ermitteln. Sie belegt aber nicht, dass ein Modell die erforderlichen Anfragen und Tool-Aufrufe wie vorgesehen verarbeitet.

Modellrouting und Zugriffsberechtigungen für Tools sind getrennte Teile der Einführung. Konfiguriere MCP-Verbindungen, die Verteilung von Plugins und die zugehörigen Richtlinien separat.

Authentifizierung auswählen

Natives Gateway-OAuth

  1. Registriere einen öffentlichen OAuth-Client, der den Authorization Code Flow mit PKCE unterstützt. Schalte die Personen oder Gruppen frei, die sich anmelden dürfen.
  2. Konfiguriere das Gateway so, dass es das ausgestellte Zugriffstoken im ausgewählten Cookie oder benutzerdefinierten Header validiert. Lege für jede Identität die freigegebenen Modelle, Ratenlimits und Budgets fest.
  3. Ermittle anhand der Anleitung für natives Gateway-OAuth die URLs für Autorisierung und Tokenabruf, die öffentliche Client-ID, die Scopes, die optionale Ressource, die Einstellungen zur Tokenübermittlung und gegebenenfalls den festen Port für die Weiterleitung. Registriere die passende Loopback-Weiterleitungs-URI bei deinem Identitätsanbieter. Unterstützt dein Identitätsanbieter die Geräteautorisierung, verteile zusätzlich device_authorization_url an alle, die die CLI auf einem entfernten Rechner nutzen.
  4. Teste mit einem Testkonto die Browseranmeldung, die Tokenerneuerung und den Widerruf des Zugriffs in der CLI oder Desktop-App, die du bereitstellen möchtest. Für die Nutzung der CLI auf einem entfernten Rechner teste die Anmeldung per Gerätecode oder prüfe, ob der Browser die Loopback-Callback-Adresse erreicht.

Jede Person meldet sich einzeln an. Verteile nur die OAuth-Konfiguration. Verteile weder ein Client-Secret noch einen Gateway-API-Schlüssel oder ein ausführbares Hilfsprogramm. Belasse die Zugangsdaten des Upstream-Anbieters auf dem Gateway.

API-Schlüssel oder Hilfsprogramme für Zugangsdaten

  1. Stelle für jede Person im Entwicklungsteam eigene Gateway-Zugangsdaten mit begrenztem Berechtigungsumfang aus. So kannst du die Nutzung zuordnen und den Zugriff einzeln widerrufen.
  2. Lege für alle Zugangsdaten jeweils die freigegebenen Modelle, Ratenlimits, das Budget, das Ablaufdatum und den Erneuerungszeitraum fest.
  3. Stelle Zugangsdaten über deine Geheimnisverwaltung oder ein installiertes Hilfsprogramm für Zugangsdaten bereit. Speichere weder die Zugangsdaten des Upstream-Anbieters noch die für die Gateway-Administration auf den Rechnern des Entwicklungsteams.
  4. Wenn ein Hilfsprogramm die primären Zugangsdaten für den Anbieter bereitstellt, beachte die Vorgaben für die befehlsgestützte Authentifizierung. Stellt es zusätzlich zur ChatGPT-Anmeldung Zugangsdaten für das Gateway bereit, konfiguriere einen Befehl zum Exportieren der Gateway-Zugangsdaten. Teste vor der Verteilung den Abruf und die Erneuerung von Token.
  5. Erkläre dem Entwicklungsteam, wie sich die Zugangsdaten erneuern lassen und an wen es sich bei Fragen wenden kann.

Codex über das Gateway testen

Bevor du etwas verteilst, richte anhand der Anleitung Anbieter konfigurieren ein isoliertes Testkonto ein. Verwende dafür den Anbieterblock und die Authentifizierungsmethode, die du verteilen möchtest.

Wenn das Gateway den Modellkatalog bereitstellt, prüfe, ob es ein Codex-kompatibles models-Array zurückgibt. Wenn für die Inferenz bei OpenAI persönliche Zugangsdaten verwendet werden, prüfe, ob das Gateway die erforderlichen ChatGPT-Header an das Codex-Backend weiterleitet.

Halte für den Pilotversuch die Clientversion, das Betriebssystem, die Anbieter-ID, den Modellalias und die Authentifizierungsmethode fest. Führe die folgenden Prüfungen in jeder CLI oder Desktop-App durch, die du unterstützen möchtest. Wenn du die Gateway-Authentifizierung sowohl allein als auch in Verbindung mit der ChatGPT-Anmeldung anbietest, teste beide Varianten getrennt.

Prüfung Vorgehen Erfolgskriterium
Wirksame Konfiguration Prüfe die Konfigurationsebenen und vergewissere dich, dass der vorgesehene Anbieter, das Modell und die verbindlichen Vorgaben aktiv sind. Das Testkonto verwendet die verteilten Einstellungen. Persönliche Standardwerte oder Profilvorgaben führen nicht zu einer anderen Route.
Verbindung Folge der Anleitung Verbindung prüfen. Der erwartete Anbieter und der erwartete Alias sind aktiv, der Test-Prompt wird erfolgreich beantwortet und die Gateway-Protokolle weisen das Testkonto aus.
Streaming Bitte um eine kurze Antwort mit mehreren Absätzen. Der Text erscheint nach und nach und der aktive Transport sendet response.completed. Teste HTTP separat, um zu prüfen, ob das Gateway SSE-Ereignisse ohne Pufferung weiterleitet.
Lokaler Tool-Aufruf mit Ergebnisrückgabe Bitte Codex in einem temporären Testordner ohne Schreibzugriff, die Dateien auf der obersten Ebene aufzulisten und ihren Inhalt zusammenzufassen. Codex ruft ein lokales Tool auf, gibt das Ergebnis zurück und formuliert eine abschließende Antwort, ohne Dateien zu ändern.
Folgeanfrage Stelle im selben Thread eine Rückfrage. Die Antwort knüpft an den vorherigen Austausch an. Das Gateway akzeptiert erneut übermittelte Eingaben. Wenn WebSocket oder der inkrementelle Transport aktiviert ist, behält es auch previous_response_id bei.
Fehler und Zuordnung Wiederhole den Test mit einem absichtlich ungültigen Testalias oder abgelaufenen Testzugangsdaten. Der Client erhält eine aussagekräftige Routing- oder Authentifizierungsfehlermeldung. Gültige Anfragen bleiben dem Testkonto zugeordnet.

Wenn die automatische Genehmigung aktiviert ist, löse in einem temporären Testordner eine Tool-Aktion aus, die nach der vorgesehenen Richtlinie überprüft werden muss. Prüfe, ob das Gateway die Prüfanforderung verarbeitet und der Client die Entscheidung über die Genehmigung umsetzt. Mit einem reinen Lesezugriff, der keine Genehmigung erfordert, lässt sich dieser Ablauf nicht testen. Dokumentiere alle nicht unterstützten Abläufe, bevor du den Pilotversuch ausweitest.

Wenn sich durch die Einführung der Anbieter für bestehende Konten ändert, teste auf jedem unterstützten Client sowohl eine neue als auch eine vor der Umstellung erstellte Unterhaltung. Halte fest, ob sich die bestehende Unterhaltung anzeigen, fortsetzen oder verzweigen lässt. Gib den betroffenen Personen für jeden blockierten Ablauf eine Anleitung zur Wiederherstellung. Setze nicht voraus, dass beim Wechsel des Standardanbieters auch der Unterhaltungsverlauf migriert wird.

Wenn alle Prüfungen erfolgreich waren, bereite die Übergabe an das Entwicklungsteam vor.

Konfiguration verteilen

Verteile die Gateway-Basis-URL, die Anbieter-ID, den freigegebenen Modellalias und die Authentifizierungseinstellungen, damit alle Rechner denselben Verbindungsweg nutzen.

Was du verteilen solltest

Verteile für natives Gateway-OAuth die Anbietertabelle und die Tabelle [model_providers.<id>.gateway_oauth] aus der Verbindungsanleitung. Trage die oben ermittelten Registrierungswerte ein. Behalte requires_openai_auth = false bei und lass env_key, experimental_bearer_token und die befehlsgestützte auth-Tabelle weg, wenn OAuth die einzige Authentifizierungsmethode für das Gateway ist.

Wenn ein Hilfsprogramm die primären Zugangsdaten für den Anbieter bereitstellt, verteile den folgenden config.toml-Block über die von dir gewählte Konfigurationsebene. Verwende ein Modell, das deine Codex-Version kennt, oder stelle wie oben beschrieben den passenden Katalog bereit. Installiere das Programm zum Tokenabruf unter dem für den Befehl konfigurierten Pfad:

Setze model und model_provider vor die erste TOML-Tabelle. Wenn du model_catalog_json verwendest, setze die Einstellung ebenfalls dorthin. TOML ordnet Schlüssel nach [model_providers...] dieser Tabelle zu. Sie gelten dann nicht für die oberste Ebene der Codex-Konfiguration.

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

Für einen kurzzeitig gültigen statischen Testschlüssel entfernst du den Authentifizierungsblock und trägst env_key = "CODEX_GATEWAY_API_KEY" in [model_providers.enterprise-gateway] ein. Setze die Umgebungsvariable außerhalb von TOML. Kombiniere env_key nicht mit befehlsgestützter Authentifizierung.

Standardwerte und verbindliche Vorgaben verteilen

Wenn sich dein Team ohne ChatGPT bei Codex anmeldet, kannst du Teameinstellungen über deinen eigenen Server verteilen. Codex ruft diese Einstellungen unabhängig davon ab, wie du Modellanfragen weiterleitest.

Entscheide anhand der Rangfolge der Konfigurationsebenen, auf welcher Ebene du Standardwerte verteilst. Informationen zu erzwungenen Einstellungen und MDM-Payloads für macOS findest du in der Anleitung Verwaltete Konfiguration.

Verwende unter macOS oder Linux /etc/codex/config.toml für systemweite Standardwerte. Lege unter Windows die Datei config.toml in %ProgramData%\OpenAI\Codex\ ab. Persönliche Einstellungen und Profile können diese Standardwerte überschreiben. In den verlinkten Referenzen findest du die unterstützten Vorgaben und die Speicherorte der zugehörigen Dateien.

Verteile alle in der Konfiguration angegebenen ausführbaren Hilfsprogramme und lokalen Katalogdateien separat.

Um eine Remote-Katalog-URL verbindlich vorzugeben, trage die vollständige Anbieterdefinition in requirements.toml unter [model_providers.<id>] ein. Eine verbindliche Anbieterdefinition ersetzt die entsprechende Anbietertabelle aus der regulären Konfiguration. Gib daher base_url, die Authentifizierungseinstellungen und alle weiteren erforderlichen Felder an. Verwende die Vorgabe model_provider, wenn du auch die Anbieterauswahl erzwingen musst.

model_catalog_json verweist auf eine lokale JSON-Datei. Wenn du die Einstellung über requirements.toml erzwingst, legst du damit nur den Pfad fest. Die Datei musst du separat verteilen. Lege den Katalog vor dem Start von Codex unter diesem absoluten Pfad ab.

Gib in TOML absolute Windows-Pfade mit bereits aufgelösten Umgebungsvariablen an. Codex löst %ProgramData% weder in model_catalog_json noch im Wert von command für die Anbieterauthentifizierung auf. Verwende die folgenden Beispielpfade nur, wenn du die Dateien dort bereitgestellt hast:

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 in WSL verwendet Linux-Pfade und den unter Linux gesetzten Wert von CODEX_HOME. Sie übernimmt die native Windows-Konfiguration nicht automatisch.

Routing-Header verteilen

Wenn dein Gateway Anfragen je nach Konfiguration oder Tool weiterleitet, ergänze in der verwalteten Datei requirements.toml beim Anbieter die vom Gateway erwarteten Header. Das folgende Beispiel übermittelt die ID der Routing-Konfiguration und gibt Codex als Client an:

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

Verwende env_http_headers für Header-Werte aus der Clientumgebung. Sende eine Testanfrage und prüfe in den Gateway-Protokollen, welche Route ausgewählt wurde. Die Optionen für Header findest du im Abschnitt Benutzerdefinierte Modellanbieter.

Konfigurationswerte an das Entwicklungsteam weitergeben

Gib dem Entwicklungsteam eine einheitliche Anleitung für die Einrichtung, die dem getesteten Vorgehen im Pilotversuch entspricht. Nimm die folgenden Angaben auch dann auf, wenn du die Konfiguration zentral verteilst:

Thema Erforderliche Angaben
Freigegebener Client Client, Version und Betriebssystem aus dem Pilotversuch sowie die dort verwendete Anleitung zur Installation oder Aktualisierung.
Bereitstellung der Konfiguration Gib an, ob die Einstellungen bereits zentral verwaltet werden oder lokal eingerichtet werden müssen. Nenne alle separat installierten Hilfsprogramme und Katalogdateien.
Erwartete Verbindung Anbieter-ID, Modellalias und Gateway-URL einschließlich API-Pfad. Erkläre, welche Werte das Team ändern darf.
Anmeldung Gib an, ob eine Anmeldung bei einem ChatGPT-Workspace, eine Authentifizierung am Gateway oder beides erforderlich ist. Nenne den erforderlichen Workspace und die Authentifizierungsmethode für das Gateway.
Zugangsdaten und Kataloge Je nach Methode die OAuth-Registrierungswerte, die Umgebungsvariable für die Zugangsdaten oder die Konfiguration des installierten Hilfsprogramms. Ergänze gegebenenfalls die Katalog-URL oder den aufgelösten lokalen Pfad. Übermittle geheime Werte über das dafür freigegebene Verfahren.
Prüfung und Support Der Verbindungstest, das erwartete Ergebnis, die Zuständigkeit für das Gateway und die erforderlichen Angaben für eine Fehlermeldung an den Support.

Verweise das Entwicklungsteam bei verwalteten Rechnern auf die Anleitung Auf eine vorhandene Konfiguration prüfen. Verweise für die manuelle Einrichtung auf Anbieter konfigurieren.

Wenn sich durch die Einführung der Anbieter ändert, füge die getestete Anleitung für bestehende Unterhaltungen bei. Stelle sicher, dass die für die Einführung verantwortliche Person auf die bisherige funktionierende Konfiguration zugreifen kann, falls im Pilotversuch ein Problem auftritt.

Mit einer manuellen Konfiguration kannst du Einstellungen nicht erzwingen. Die projektlokale Datei .codex/config.toml kann sicherheitsrelevante Schlüssel für das Anbieter- oder Authentifizierungsrouting nicht überschreiben.

Verbindung auf einem Rechner des Entwicklungsteams prüfen

So prüfst du, ob die verteilten Einstellungen auf einem Rechner des Entwicklungsteams angekommen sind:

  1. Prüfe, ob der freigegebene Client sowie alle erforderlichen Hilfsprogramme und Katalogdateien installiert sind. Starte Codex neu und führe die in der Anleitung für das Team vorgesehenen Anmeldungen durch.
  2. Prüfe, ob der erwartete Anbieter und das erwartete Modell aktiv sind. Verwende dazu in der CLI /status. Wenn die wirksamen Einstellungen von den Angaben für das Team abweichen, prüfe mit /debug-config die Konfigurationsebenen.
  3. Führe den kurzen Test aus der Anleitung Verbindung mit einem Gateway herstellen durch.
  4. Stelle eine Rückfrage, um zu prüfen, ob Codex an den bisherigen Austausch anknüpft. Suche anschließend in den Gateway-Protokollen nach der Anfrage der betreffenden Person.

Weite den Zugriff aus, sobald der Pilotversuch mit allen unterstützten Clients und Authentifizierungskombinationen erfolgreich war. Bewahre die getestete Konfiguration und die Ergebnisse zusammen mit der Anleitung zur Einführung auf. So kannst du die Prüfungen nach Aktualisierungen des Clients, des Gateways oder der Richtlinien wiederholen.

Fehler bei der Einführung beheben

Grenze anhand des Fehlerbilds ein, ob du die Konfiguration, die Zugangsdaten oder das Gateway prüfen musst:

Problem Abhilfe
Der erwartete Anbieter fehlt nach dem Neustart. Prüfe, welche Konfigurationsebene Vorrang hat. Persönliche Einstellungen oder Profileinstellungen können die Systemstandardwerte überschreiben.
Die Authentifizierung schlägt für alle fehl. Prüfe die Gateway-Authentifizierung und die Zugangsdaten des Upstream-Anbieters. Ermittle, welcher Dienst die Anfrage abgelehnt hat.
Die Authentifizierung schlägt für eine Person fehl. Prüfe den Zugriff dieser Person beim Identitätsanbieter, ihre Gateway-Zugangsdaten oder ihr Programm zum Tokenabruf.
Der Stream stockt. Prüfe, ob das Gateway Ereignisse puffert und ob es das abschließende Ereignis response.completed weiterleitet.
Ein Modell fehlt oder verwendet generische Funktionen. Prüfe bei einem eigenen Alias, ob der Gateway-Alias, die Codex-Einstellung model und das Katalogfeld slug übereinstimmen. Prüfe den Pfad zum Katalog und seine Kompatibilität mit der installierten Codex-Version. Starte Codex anschließend neu.
Ein Windows-Pfad funktioniert nicht. Verwende vollständig aufgelöste absolute Pfade. Setze Windows-Pfade mit einfachen Backslashes in TOML in einfache Anführungszeichen.

Eine bestehende Gateway-Bereitstellung weiterverwenden

Wenn deine Organisation Claude Code bereits über ein Gateway nutzt, kannst du möglicherweise das Gateway-Produkt, den Netzwerkpfad, die Protokollierung und den Bedrock-Zugriff weiterverwenden. Ergänze eine Responses-Route für Codex, Zugangsdaten, Modellaliase und eine config.toml, während das bestehende Setup weiterläuft. Mit den Claude-Client-Einstellungen und den Vorgaben für /v1/messages lässt sich Codex nicht konfigurieren.

Bestehende Claude-Bereitstellung Migration zu Codex
Gateway-Produkt, DNS, TLS, private Netzwerkverbindungen, Protokollierung, Maskierung sensibler Daten und Monitoring Verwende diese Dienste weiter. Ergänze eine Route für Codex, die die Kompatibilitätsanforderungen für Gateways erfüllt.
Bedrock-Konto, Anbieterzugangsdaten, IAM-Berechtigungsgrenze, Inferenzprofile und regelmäßiger Austausch der Zugangsdaten Behalte diese Komponenten nur bei, wenn sie den Zugriff auf die Upstream-Modelle hinter den neuen Codex-Aliasen erlauben. Die Zugangsdaten des Anbieters bleiben auf dem Gateway.
Claude-Route /v1/messages, Anfrageformat für Bedrock InvokeModel, Anthropic-Header und Claude-spezifische Wiederholungsversuche oder Fehlermeldungen Diese Eigenschaften reichen als Kompatibilitätsnachweis nicht aus. Codex benötigt POST /v1/responses, Responses-Streaming, die Fortsetzung des Austauschs bei Folgeanfragen, Tool-Aufrufe und aussagekräftige Fehlermeldungen.
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY oder apiKeyHelper Codex unterstützt apiKeyHelper nicht. Konfiguriere natives Gateway-OAuth, einen Schlüssel mit begrenztem Berechtigungsumfang über env_key oder den befehlsgestützten Tokenabruf für Codex.
Claude-Modellnamen, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides und Zuordnungen zu Bedrock-Profilen Lass dein Gateway-Team Modellnamen auswählen und gegebenenfalls eigene Aliase konfigurieren. Verwende den Modellnamen, den dir das Team nennt, und gegebenenfalls den mitgelieferten Modellkatalog im JSON-Format.
Claude-Dateien settings.json und managed-settings.json, JSON-Blöcke für env, plist oder Registry-Payloads Nutze denselben MDM-Kanal oder denselben Kanal für die Konfigurationsverwaltung. Verteile darüber die Codex-Datei config.toml und die unterstützten Werte für requirements.toml.

Gehe für eine sichere Migration in dieser Reihenfolge vor:

  1. Erfasse den aktuellen Verbindungsweg für Claude. Halte die Gateway-URL, die Quelle der Zugangsdaten, erforderliche Header, Modellaliase, Zuordnungen zu Bedrock-Profilen und den Kanal für die zentrale Verteilung fest.
  2. Ergänze parallel zur bestehenden Route eine Responses-Route für Codex und die Codex-Modellaliase.
  3. Wähle natives Gateway-OAuth, einen API-Schlüssel oder ein Hilfsprogramm für Zugangsdaten und schalte ein Testkonto frei. Stelle statische Zugangsdaten über env_key bereit. Wenn du ein Hilfsprogramm verwendest, implementiere und teste den Tokenabruf nach den Codex-Vorgaben für die befehlsgestützte Authentifizierung.
  4. Konfiguriere den Anbieter für die Person, die den Test durchführt. Verwende die in Schritt 3 ausgewählte Authentifizierungsmethode. Passe die Payload für eine zentrale Einführung an die Codex-Pfade und die Rangfolge der Konfigurationsebenen an, wie im Abschnitt Konfiguration verteilen beschrieben.
  5. Führe die kurze Verbindungsprüfung in der CLI oder Desktop-App durch, die diese Person tatsächlich nutzt. Führe anschließend alle Prüfungen für Streaming, Folgeanfragen, Tool-Aufrufe, Fehlermeldungen, Protokollierung und Routing anhand der Modellaliase aus, wie im Abschnitt Codex über das Gateway testen beschrieben.
  6. Wenn der Pilotversuch erfolgreich war, verteile die Konfiguration an das restliche Entwicklungsteam.

Referenz für Modellkataloge

Mit einer lokalen models.json-Datei beginnen

Konfiguriere zuerst deinen Gateway-Anbieter und wähle ihn aus. Führe diesen Schritt auf dem Rechner aus, auf dem Codex läuft.

Speichere den folgenden Katalog auf diesem Rechner als models.json. Ersetze gateway-model durch die genaue Modell-ID, die dein Gateway akzeptiert. Der Anzeigename erscheint in der Modellauswahl.

{
  "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 findest du im Modellkatalog von Codex.

Setze model_catalog_json in config.toml auf den absoluten Pfad der Datei. Starte Codex neu, wähle Gateway model aus und sende eine Anfrage. Prüfe, ob das Gateway die Modell-ID erhalten hat, die du in slug angegeben hast.

Wenn du einen Alias für ein mitgeliefertes Modell einrichtest, kopiere den vollständigen Katalogeintrag des Modells für deine Codex-Version und ändere slug und display_name. Hat der Alias kein Migrationsziel, setze upgrade auf null. So bleiben das Kontextfenster, die Optionen für den Reasoning-Aufwand und die Tool-Einstellungen des Modells erhalten.

Einen Katalog für Clients bereitstellen

Dieser Abschnitt richtet sich an alle, die das Format Codex Models implementieren. Es definiert den Modellkatalog und bildet die Grundlage für die Modellauswahl. Wenn du einen Inferenzanbieter wie ein Gateway oder einen Cloud-Dienst entwickelst, verwende diese Spezifikation. Damit können die Codex App und die CLI deine Modelle automatisch ermitteln und deren Anweisungen und Funktionseinstellungen verwenden.

Wenn du Codex in einem Unternehmen administrierst und den Modellkatalog vorgeben möchtest, folge der Konfigurationsanleitung für model_catalog_url.

Implementiere einen Katalogendpunkt mit Authentifizierung, um das Format zu unterstützen. Rufe für die anfragende Codex-Version die aktuellen Standardwerte deines Upstream-Anbieters ab, wende deine Anpassungen an und gib den daraus entstandenen Katalog zurück.

Den Katalogendpunkt implementieren

Der Standardendpunkt für den Katalog ist /models unter der base_url des Anbieters. Bei base_url = "https://gateway.example.com/v1" sendet Codex beispielsweise diese Anfrage:

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

Der automatische Katalogabruf am Standardpfad unterstützt die befehlsgestützte Authentifizierung und die Authentifizierung über das Codex-Backend, etwa mit ChatGPT. Wenn ein benutzerdefinierter Anbieter einen API-Schlüssel ohne befehlsgestützte Authentifizierung verwendet, setze model_providers.<id>.model_catalog_url ausdrücklich, um den Remote-Abruf zu aktivieren. Ein API-Schlüssel allein löst am Standardpfad keinen Katalogabruf aus.

Gib mit model_catalog_url eine vollständige Katalog-URL an, etwa https://gateway.example.com/codex/models. Sie kann auch auf den Standardendpunkt /v1/models verweisen. Codex verwendet diese URL direkt, ohne /models anzuhängen. Lass für den Katalogabruf per API-Schlüssel features.api_key_model_discovery aktiviert. Die Funktion ist standardmäßig eingeschaltet. Benutzerdefinierte Header allein aktivieren den Abruf nicht.

Codex übermittelt die Authentifizierungsdaten und die konfigurierten Header des ausgewählten Anbieters und hängt client_version sowie alle für den Anbieter festgelegten query_params an die URL an. Stelle den Katalog auf einem Dienst bereit, der diese Zugangsdaten empfangen darf.

Authentifiziere die anfragende Identität, rufe die zugehörigen Upstream-Standardwerte ab, wende deine Anpassungen an und gib das vollständige ModelsResponse-Objekt direkt als JSON zurück. Gib jedem Eintrag einen eindeutigen, nicht leeren Wert für slug. Wenn model_catalog_url ausdrücklich gesetzt ist, lehnt Codex Weiterleitungen ab. Setze die Zugriffsberechtigungen für Modelle weiterhin bei jeder Inferenzanfrage durch.

Entferne auf allen Clients, die den Endpunkt verwenden, jede wirksame Einstellung für model_catalog_json. Die lokale Datei hat Vorrang und verhindert den Remote-Abruf.

Das Schema des Clients verwenden

Lies den Abfrageparameter client_version aus der Kataloganfrage. Codex sendet seine CLI-Version im Format major.minor.patch und lässt etwaige Suffixe für Vorabversionen weg. Bei Desktop-Clients ist das die Version der mitgelieferten CLI.

Verwende im öffentlichen Codex-Repository das passende Tag rust-v<version> oder bei einem eigenen Build genau den Commit, aus dem er erstellt wurde. Die folgenden Links verweisen auf rust-v0.162.1. Wähle die Revision aus, die zu deinem Client passt:

Die mitgelieferte Datei gibt den Stand zum Zeitpunkt der Veröffentlichung wieder. Rufe die aktuellen Standardwerte ab, bevor du deinen Katalog erstellst.

Aktuelle Upstream-Standardwerte abrufen

Cloud-Anbieter, die OpenAI-Modelle bereitstellen, rufen die Standardwerte von OpenAI ab. Gateways lesen den Katalog ihres Cloud- oder Upstream-Anbieters. So übernehmen sie die Einstellungen der bereitgestellten Modelle und berücksichtigen deren Verfügbarkeit je nach Konto und Region. Gib die Version des anfragenden Codex-Clients bei jedem Schritt weiter und authentifiziere dich an jedem Endpunkt separat.

Um die Standardwerte direkt von OpenAI abzurufen, sende eine Anfrage mit derselben client_version an den Codex-Modellendpunkt. Das folgende Beispiel verwendet einen OpenAI-API-Schlüssel:

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

Verwende für eine ChatGPT-Integration das ChatGPT-Zugriffstoken der anfragenden Identität und gegebenenfalls den zugehörigen Header ChatGPT-Account-ID. Verwende Zugangsdaten, die für den Upstream-Endpunkt autorisiert sind. Mit dem eigenen API-Schlüssel deines Gateways ist keine Authentifizierung bei OpenAI möglich.

Verarbeite die gesamte Antwort einschließlich des models-Arrays auf der obersten Ebene. Dieser Endpunkt liefert Codex-Metadaten wie Anweisungen, Standardwerte für den Reasoning-Aufwand, Tool-Einstellungen, Kontextgrenzen und Servicestufen. Der öffentliche Endpunkt /v1/models liefert diesen Katalog nicht.

Aktualisiere die Standardwerte auch dann, wenn sich die Codex-Version nicht geändert hat. Beschränke Anfragen auf die vorgesehene Upstream-Identität und beachte die Cache-Vorgaben der Antwort. Der Inhalt des Katalogs kann von den Zugriffsrechten der anfragenden Identität abhängen. Speichere deine Anpassungen getrennt, damit du sie erneut auf aktualisierte Standardwerte anwenden kannst.

Anbieterspezifische Anpassungen vornehmen

Ändere die Feldwerte und behalte dabei die Antwortstruktur der jeweiligen Version bei:

  • Beschränke den Katalog auf Modelle, die die anfragende Identität verwenden darf. Ordne jeden slug einer unterstützten Inferenzroute zu und passe display_name, description oder priority an. Setze für einen Alias ohne Modellmigration upgrade auf null.
  • Wähle für den Reasoning-Aufwand, die Kontextgrenzen, die Eingabemodalitäten und die Servicestufen nur Werte, die dein Modell und deine Route unterstützen. Verwende auch als Standardwerte nur unterstützte Optionen. Leere bei einer Route ohne Servicestufen die Felder service_tiers und additional_speed_tiers und setze default_service_tier auf null.
  • Behalte die Anweisungen und Tool-Einstellungen des Upstream-Anbieters bei, sofern du keinen Ersatz getestet hast. Metadaten erweitern weder die Fähigkeiten eines Modells noch gewähren sie Zugriff auf die Inferenz.

Für einen Modellalias im Gateway findest du hier die Anleitung zum Bereitstellen von Modellmetadaten. Teste den resultierenden Katalog mit jeder unterstützten Codex-Version.

Die öffentlichen Rust-Typen verwenden

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

  • Verwende codex-protocol für codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Lies die Antwort mit serde_json::from_slice::<ModelsResponse>() ein, bearbeite catalog.models und serialisiere den gesamten Wrapper mit serde_json::to_vec(). Der Wrapper verarbeitet die Kompatibilitätsfelder für Modellanweisungen.
  • Verwende codex-models-manager::bundled_models_response(), um den statischen, mit dieser Revision ausgelieferten Katalog als ModelsResponse zu laden. Die Funktion ruft keine aktuellen Upstream-Standardwerte ab.

Weiterführende Dokumentation