Codex über ein Gateway bereitstellen

Stellen Sie Codex über das LLM-Gateway Ihrer Organisation bereit. Konfigurieren Sie Modellrouten, stellen Sie Zugangsdaten für Entwickler aus und verteilen Sie eine überprüfte Codex-Konfiguration.

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.
• Gateway-Testzugangsdaten mit eingeschränktem Berechtigungsumfang.
• Ein Mechanismus zur Bereitstellung von Geheimnissen oder ein getestetes Hilfsprogramm für Zugangsdaten.
• Eine Möglichkeit, Konfiguration, ausführbare Hilfsprogramme und gegebenenfalls 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. Zugangsdaten für Entwickler ausstellen.
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.

Einen Modellkatalog für benutzerdefinierte Namen verwenden

Verwenden Sie model_catalog_json, wenn Ihr Gateway einen Modellnamen verwendet, den Codex nicht erkennt. Der Katalog liefert die Anweisungen, Reasoning-Optionen, Kontextgrenzen und Tool-Funktionen, die Codex für diesen Namen verwendet. Ohne passenden Eintrag kann eine Anfrage das vorgesehene Upstream-Modell erreichen, während Codex allgemeine Einstellungen verwendet.

So verwenden Sie beispielsweise company-coding-model als Alias für gpt-6-luna:

1. Erstellen Sie den Alias company-coding-model auf dem Gateway und leiten Sie ihn an das genehmigte Upstream-Modell gpt-6-luna weiter.
2. Laden Sie den Codex-Modellkatalog für Ihre Codex-Version herunter und speichern Sie eine Kopie als gateway-models.json. Verwenden Sie diese Datei als Ausgangspunkt.
3. Bearbeiten Sie den Eintrag gpt-6-luna in Ihrer Kopie: Setzen Sie slug auf company-coding-model und prüfen Sie, ob die übrigen Metadaten zum Upstream-Modell und den Gateway-Funktionen passen. Setzen Sie bei einem Alias ohne Modellmigration upgrade auf null.
4. Belassen Sie die Einträge im Array models auf oberster Ebene und verteilen Sie die Datei an jeden Client. Ein benutzerdefinierter Katalog ersetzt den mitgelieferten Katalog. Nehmen Sie daher jedes Modell auf, das Benutzer auswählen können müssen.

Wenden Sie für Bedrock über LiteLLM die erforderlichen Katalogänderungen an.

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.

Zugangsdaten für Entwickler ausstellen

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, konfigurieren Sie gemäß Verbindung mit einem Gateway herstellen einen isolierten Testbenutzer mit dem Anbieterblock und dem Mechanismus für Zugangsdaten, die Sie verteilen möchten.

Führen Sie die folgenden Prüfungen in derselben CLI- oder Desktop-Oberfläche durch, die Entwickler verwenden werden:

Verweisen Sie Entwickler nach erfolgreichen Prüfungen auf Verbindung mit einem Gateway herstellen, damit sie ihren eigenen Rechner konfigurieren und überprüfen können.

Die Konfiguration verteilen

Verteilen Sie die Gateway-Basis-URL, die Anbieter-ID, den genehmigten Modellalias und den Mechanismus für Zugangsdaten, um auf jedem Rechner denselben Verbindungsweg einzurichten.

Was Sie verteilen sollten

Verteilen Sie diesen config.toml-Block über die von Ihnen gewählte Konfigurationsebene, um Anbietervorgaben festzulegen. 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

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 ausführbaren Hilfsprogramme und Katalogdateien separat.

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.

Entwicklern die Konfigurationswerte übergeben

Wenn Sie keine verwaltete Verteilung haben, geben Sie jedem Entwickler die Gateway-URL, die Anbieter-ID, den Modellalias, die Zugangsdatenvariable oder den Resolver sowie gegebenenfalls den Katalogpfad. Verweisen Sie auf Verbindung mit einem Gateway herstellen, damit Entwickler ihren eigenen Rechner konfigurieren und überprüfen können.

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. Starten Sie Codex neu und bestätigen Sie den erwarteten Anbieter und das erwartete Modell.
2. Führen Sie den kurzen Test unter Verbindung mit einem Gateway herstellen aus.
3. Stellen Sie eine Folgefrage, um die Fortsetzung zu bestätigen, und prüfen Sie anschließend die Gateway-Protokolle auf die Anfrage dieses Entwicklers.

Fehler bei der Einführung beheben

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

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.

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 Bereitstellungskanal.
2. Fügen Sie eine parallele, für Codex zugängliche Responses-Route und Codex-Modellaliase hinzu.
3. Stellen Sie einen Codex-Zugang mit eingeschränktem Berechtigungsumfang aus. Wenn Codex statische Zugangsdaten verwenden soll, stellen Sie diese neuen Zugangsdaten über env_key bereit; wenn Claude ein Hilfsprogramm für Zugangsdaten verwendet, implementieren und testen Sie die Vorgaben für den befehlsbasierten Codex-Resolver.
4. Konfigurieren Sie diesen Entwickler mit dem Anbieterblock. Passen Sie bei einer verwalteten Einführung die Payload an die Codex-Pfade und Prioritäten an, die unter Codex über ein Gateway bereitstellen beschrieben sind.
5. Führen Sie die kurze Verbindungsprüfung in der tatsächlich vom Entwickler verwendeten CLI- oder Desktop-Oberfläche aus und anschließend die vollständigen Prüfungen für Streaming, Fortsetzung, Tool-Aufrufe, Fehler, Protokollierung und Alias-Routing unter Codex über das Gateway testen.
6. Verteilen Sie die Konfiguration nach einem erfolgreichen Pilotversuch an die übrigen Entwickler.

Weiterführende Dokumentation

• Verbindung mit einem Gateway herstellen
• MCP
• Plugins
• Verwaltete Konfiguration