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/responsesakzeptieren. - SSE-Ereignisse ohne Pufferung streamen und mit
response.completedabschließen. - Die Fortsetzung in Folgerunden mit erneut übermittelten Eingaben beibehalten.
previous_response_idnur 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:
- Modellnamen wählen und Routen überprüfen.
- Authentifizierung auswählen.
- Codex über das Gateway testen.
- Die Konfiguration verteilen.
- 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
- 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.
- 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.
- 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.
- 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
- 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.
- Legen Sie die genehmigten Modelle, Ratenbegrenzungen, das Budget, den Ablaufzeitpunkt und den Erneuerungszeitraum für jeden Zugang fest.
- 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.
- 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.
- 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 = 300000Entfernen 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:
- 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.
- Bestätigen Sie den erwarteten Anbieter und das Modell. Verwenden Sie in der CLI
/status. Prüfen Sie mit/debug-configdie Konfigurationsebenen, wenn die wirksamen Einstellungen von den Übergabeunterlagen abweichen. - Führen Sie den kurzen Test unter Mit einem Gateway verbinden aus.
- 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:
- Erfassen Sie den aktuellen Claude-Verbindungsweg: Gateway-URL, Quelle der Zugangsdaten, erforderliche Header, Modellaliase, Bedrock-Profilzuordnungen und verwalteter Verteilungskanal.
- Fügen Sie eine parallele Responses-Route für Codex und Codex-Modellaliase hinzu.
- 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_keybereit; implementieren und testen Sie bei einem Hilfsprogramm die Schnittstellenvorgaben für den befehlsbasierten Codex-Resolver. - 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.
- 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.
- 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.
client_version 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:
- Lesen Sie die Antworttypen
ModelsResponseundModelInfo, um das Schema nachzuvollziehen. - Ein vollständiges Beispiel finden Sie in der mitgelieferten Datei
models.json. Sie enthält Katalogdaten und ist kein JSON-Schema-Dokument.
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
slugeiner unterstützten Inferenzroute zu und passen Siedisplay_name,descriptionoderpriorityan. Setzen Sie für einen Alias ohne Modellmigrationupgradeaufnull. - 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_tiersundadditional_speed_tiersund setzen Siedefault_service_tieraufnull. - 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-protocolfürcodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Parsen Sie mitserde_json::from_slice::<ModelsResponse>(), bearbeiten Siecatalog.modelsund serialisieren Sie den gesamten Wrapper mitserde_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 alsModelsResponsezu laden. Dabei werden keine aktuellen vorgelagerten Standardwerte abgerufen.