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

Codex mit einem Gateway verbinden

Konfiguriere ein Modell-Gateway und authentifiziere dich mit nativem Gateway-OAuth, einem API-Schlüssel oder einem Credential Helper.

Verbinde Codex mit dem Modell-Gateway deiner Organisation. Verwende dafür die Anbietereinstellungen und die Authentifizierungsmethode, die dir dein Gateway-Team vorgibt. Das Gateway leitet Modellanfragen an dein Backend weiter, etwa an Amazon Bedrock.

Wie du ein Gateway in der gesamten Organisation einführst, erfährst du in Gateway ausrollen. Welche Anforderungen die API erfüllen muss, beschreibt Gateway-Kompatibilität. Eine Anleitung zur direkten Verbindung mit Bedrock ohne Gateway findest du auf der Seite zu Amazon Bedrock.

Vorhandene Konfiguration prüfen

Installiere den Codex-Client in der Version, die dein Administrationsteam getestet hat. Wenn deine Organisation die Einstellungen verwaltet, öffne diesen Client und folge der Anmeldeanleitung deines Administrationsteams. In diesem Fall kannst du die folgenden Beispiele zur Anbieterkonfiguration überspringen.

  • Prüfe für die CLI das ausgewählte Profil und führe codex doctor aus. Prüfe nach dem Start mit /status, welches Modell und welcher Anbieter aktiv sind.
  • Prüfe für die macOS-App ~/.codex/config.toml oder die verwaltete Konfiguration, die deine Organisation bereitstellt.
  • Prüfe für die Windows-App %USERPROFILE%\.codex\config.toml oder die Systemkonfiguration, die deine Organisation bereitstellt.

Wenn der erwartete Gateway-Anbieter und das erwartete Modell bereits aktiv sind, führe die gegebenenfalls vom Administrationsteam vorgegebenen Anmeldeschritte aus. Fahre dann mit dem Abschnitt Verbindung überprüfen fort. Vermeide es, auf einem verwalteten Rechner eine zweite Anbieterkonfiguration anzulegen. Weichen die Einstellungen von den Angaben deines Administrationsteams ab, kläre vor dem Bearbeiten lokaler Dateien, auf welcher Konfigurationsebene sie festgelegt werden sollen.

Verbindungsdaten für das Gateway einholen

Kläre bei der manuellen Einrichtung, ob du dich beim ChatGPT-Workspace anmelden, dich am Gateway authentifizieren oder beides tun musst.

Wenn du Codex selbst konfigurierst, benötigst du von deinem Gateway-Team folgende Angaben:

  • Die HTTPS-Basis-URL des Gateways einschließlich API-Pfad, etwa https://gateway.example.com/v1.
  • Den Modellnamen und die Anbieter-ID, die du verwenden sollst.
  • Die Authentifizierungsmethode: natives Gateway-OAuth, einen API-Schlüssel mit begrenzten Berechtigungen und die zugehörige Umgebungsvariable oder einen installierten Credential Helper.
  • Für OAuth die Autorisierungs-URL, die Token-URL, die öffentliche Client-ID und gegebenenfalls erforderliche Scopes. Wenn das Gateway ein Cookie oder einen benutzerdefinierten Header verwendet, benötigst du auch dessen Namen.
  • Falls ein Modellkatalog erforderlich ist, dessen URL oder die Katalogdatei mit ihrem absoluten lokalen Pfad.

Anbieter konfigurieren

Führe in der interaktiven CLI /config aus und öffne Sessions > Model providers. Wähle Create a custom provider or gateway und gib den Namen, die Basis-URL und bei Bedarf den Namen der Umgebungsvariablen an, die den API-Schlüssel enthält. Um einen bearbeitbaren Anbieter zu ändern, öffne seine Detailansicht und wähle Edit configuration. Wenn du den Standardanbieter ändern kannst, markiere den gewünschten Anbieter, drücke die Leertaste und starte mit /new einen Chat.

Um ein Gateway bei der CLI-Anmeldung einzurichten, starte codex --enable gateway_setup_wizard und wähle Sign in another way > Use a custom provider or gateway. Dieses optionale Anmeldeverfahren ist standardmäßig deaktiviert. Es wird angezeigt, wenn du in der CLI abgemeldet bist, die CLI den eingebetteten App Server verwendet, OpenAI der Standardanbieter ist, die Anmeldung per API-Schlüssel zulässig ist und weder eine verwaltete Einstellung noch eine beim Start übergebene Option einen Anbieter vorgibt.

Öffne für die manuelle Einrichtung oder für zusätzliche Authentifizierungseinstellungen config.toml. Unter macOS oder Linux findest du die Datei unter ~/.codex/config.toml, unter Windows unter %USERPROFILE%\.codex\config.toml.

Übernimm dieses Beispiel in deine bestehende Konfiguration. Ersetze die URL und den Modellnamen durch die Angaben deines Administrationsteams. Definiere vorhandene Schlüssel und Tabellen kein zweites Mal. Das Beispiel verwendet gpt-6-sol. Verwende dieses Modell nur dann ohne benutzerdefinierten Katalog, wenn dein Administrationsteam bestätigt, dass deine Codex-Version das Modell erkennt und die mitgelieferten Modellmetadaten zum Gateway passen.

Platziere model, model_provider, model_catalog_json und web_search vor der ersten TOML-Tabelle. Schlüssel nach einem Tabellenkopf gehören zur jeweiligen Tabelle. Codex liest sie daher nicht als Einstellungen der obersten Ebene.

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"
requires_openai_auth = false

Ergänze anschließend die Authentifizierungseinstellungen, die dir dein Gateway-Team vorgibt.

enterprise-gateway ist eine beispielhafte Anbieter-ID. Verwende in model_provider und in den zugehörigen Anbieter- und Authentifizierungstabellen dieselbe ID. In diesem Beispiel ist die Websuche für den ersten Verbindungstest deaktiviert. Bevor dein Administrationsteam sie aktiviert, sollte es prüfen, ob sie unterstützt wird.

Modellkatalog konfigurieren

Kläre mit deinem Gateway-Team, woher Codex die Angaben zum Funktionsumfang und die Anweisungen für dein ausgewähltes Modell bezieht:

  • Mitgelieferter Modellname: Wenn das Gateway den genauen Modellnamen aus deiner Codex-Version akzeptiert und Anfragen an das entsprechende Modell weiterleitet, setze model auf diesen Namen. Die Metadaten für dieses Modell liegen Codex bereits vor.
  • Katalogendpunkt: Wenn das Gateway Codex-kompatible Metadaten bereitstellt, verwende die vollständige Katalog-URL. Das kann ein /v1/models-Endpunkt sein, der die von Codex erwartete Katalogantwort liefert. Eine Antwort, die nur Modell-IDs auflistet, reicht für benutzerdefinierte Aliasse nicht aus.
  • Katalogdatei: Wenn dein Gateway benutzerdefinierte Aliasse verwendet und dein Administrationsteam eine Datei bereitstellt, folge dem Beispiel für eine lokale models.json.

Wenn dein Administrationsteam eine Katalog-URL bereitstellt, füge sie der vorhandenen Tabelle [model_providers.enterprise-gateway] hinzu:

model_catalog_url = "https://gateway.example.com/codex/models.json"

Wenn du dich ausschließlich per Gateway-OAuth authentifizierst, müssen Schema, Host und Port der Katalog-URL mit denen von base_url übereinstimmen. Melde dich zuerst beim Gateway an. Codex verwendet deine bestehende Gateway-Sitzung, um den Katalog abzurufen.

Entferne alle wirksamen Einstellungen für model_catalog_json, da sie Vorrang vor der URL haben. Die Anforderungen an den Endpunkt findet dein Administrationsteam in der Anleitung zum Bereitstellen eines Remotekatalogs.

Wenn dein Administrationsteam einen lokalen Modellkatalog bereitstellt, speichere die Datei und füge model_catalog_json vor der ersten TOML-Tabelle ein. Gib den absoluten Pfad der Datei an. Benutzerdefinierte Aliasse benötigen passende Katalogmetadaten. Beispiel:

model_catalog_json = "/etc/codex/gateway-models.json"

Verwende den Modellnamen und den Katalog, die dir dein Administrationsteam zusammen bereitstellt. Gib nur dann einen Katalogpfad an, wenn die Datei an diesem Speicherort vorhanden ist.

Authentifizierungsmethode auswählen

Verwende natives Gateway-OAuth für die Anmeldung im Browser oder per Gerätecode, einen API-Schlüssel für den Zugriff mit begrenzten Berechtigungen oder einen Credential Helper, wenn deine Organisation einen entsprechenden Befehl bereitstellt.

Authentifizierungsmethode für das Gateway

Natives Gateway-OAuth verwenden

Gateway-OAuth funktioniert unabhängig von der ChatGPT-Anmeldung. Verwende es, wenn dein Gateway Zugriffstoken akzeptiert, die der Identitätsanbieter deiner Organisation ausstellt, etwa Microsoft Entra ID. Codex übernimmt die Anmeldung im Browser und speichert die Zugangsdaten verschlüsselt. Wenn der Autorisierungsserver ein Refresh-Token ausstellt, erneuert Codex das Zugriffstoken automatisch.

Wenn du dich ausschließlich am Gateway authentifizierst, sendet die Codex CLI ab Version 0.166.0 das Zugriffstoken standardmäßig in Authorization: Bearer <gateway access token>. Entferne alle Authorization-Einträge aus http_headers oder env_http_headers dieses Anbieters.

Dein Gateway-Team muss einen öffentlichen OAuth-Client registrieren, der den Authorization Code Flow mit PKCE unterstützt. Füge der Anbieterkonfiguration in config.toml die folgende Tabelle hinzu. Ersetze die URLs und die Client-ID durch die Angaben deines Gateway-Teams:

[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127
# device_authorization_url = "https://login.example.com/oauth/device"

Ergänze in dieser Tabelle scopes und bei Bedarf resource. Verwende die Werte, die dein Identitätsanbieter und dein Gateway verlangen. Falls dein Anbieter für Refresh-Token bestimmte Scopes voraussetzt, fordere diese an. Codex verwendet standardmäßig einen freien Loopback-Port. Wenn dein Identitätsanbieter eine feste Weiterleitungs-URI verlangt, lege redirect_port fest und registriere für dieses Beispiel http://127.0.0.1:43127/callback.

Wenn dein Gateway ein Cookie oder einen benutzerdefinierten Header erwartet, setze das optionale Feld delivery in der OAuth-Tabelle. Wähle die Übermittlungsmethode, für die dein Gateway das Token prüft:

delivery = { kind = "cookie", name = "auth-openid" }
delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }

Wenn deine Bereitstellung zusätzlich die ChatGPT-Anmeldung erfordert, verwende wie oben gezeigt das Cookie oder einen separaten Gateway-Header. Weitere Informationen findest du im Abschnitt ChatGPT-Anmeldung aktivieren.

Akzeptiert ein Gateway bisher nur einen statischen API-Schlüssel, muss es zunächst das OAuth-Token und dessen Übermittlungsmethode unterstützen, bevor du dieses Verfahren nutzen kannst. Das Gateway verwaltet weiterhin seine eigenen Zugangsdaten für nachgelagerte Dienste, etwa seine AWS-Zugangsdaten für Bedrock.

Wenn du dich ausschließlich per OAuth authentifizierst, behalte requires_openai_auth = false bei und entferne die bisherigen Einstellungen env_key, experimental_bearer_token oder auth für die Gateway-Zugangsdaten.

Starte die Desktop-App neu und folge der Aufforderung zur Gateway-Anmeldung, um den Browser zu öffnen. Wenn du die CLI verwendest, starte codex und folge der Anmeldeaufforderung. Schließe die Anmeldung und die MFA deiner Organisation ab und kehre zu Codex zurück. Wenn die Autorisierung abläuft oder Codex sie nicht erneuern kann, melde dich erneut an, sobald du dazu aufgefordert wirst.

Wenn du SSH oder ein Terminal ohne Browser verwendest, setze device_authorization_url auf den Endpunkt für die Geräteautorisierung, den dein Identitätsanbieter bereitstellt. Sobald du dich anmelden musst, zeigt die interaktive CLI eine Verifizierungs-URL und einen Einmalcode an. Öffne die URL in einem Browser und gib den Code ein. Dieses Verfahren kommt ohne Portweiterleitung aus.

Wenn dein Anbieter nur die Anmeldung im Browser unterstützt und du die CLI über SSH ausführst, setze redirect_port = 43127 und registriere die passende Weiterleitungs-URI. Richte auf dem Rechner mit deinem Browser die Portweiterleitung ein, bevor du Codex startest:

ssh -L 43127:127.0.0.1:43127 user@remote

Starte codex in dieser SSH-Sitzung und öffne die URL für die Gateway-Anmeldung in deinem lokalen Browser. Auch bei der Browseranmeldung aus einem Container muss der Callback vom Browser aus erreichbar sein. Ist er nicht erreichbar, verwende die Geräteautorisierung, einen API-Schlüssel oder einen Credential Helper.

ChatGPT-Anmeldung aktivieren (empfohlen)

Wenn deine Organisation einen ChatGPT-Workspace nutzt, erhalten angemeldete Personen Zugriff auf die für sie verfügbaren Funktionen, etwa Plug-ins von OpenAI. Die Vorgaben deines Workspace gelten weiterhin, und dein Gateway verarbeitet nach wie vor die Modellanfragen. Verfügbarkeit der Funktionen vergleichen.

Aktualisiere bei der manuellen Einrichtung vor der Anmeldung die vorhandene Tabelle [model_providers.enterprise-gateway]:

  1. Setze requires_openai_auth = true und achte darauf, dass base_url weiterhin auf dein Gateway verweist. Entferne die Einstellungen env_key, experimental_bearer_token und auth für diesen Anbieter, sofern sie vorhanden sind. So verwendet Codex deine OpenAI-Zugangsdaten für die primäre Authentifizierung.
  2. Übermittle die Gateway-Zugangsdaten separat. Konfiguriere für natives Gateway-OAuth oder einen Befehl zum Exportieren der Gateway-Zugangsdaten das Feld gateway_oauth.delivery so, dass Codex das vom Gateway akzeptierte Cookie oder den entsprechenden benutzerdefinierten Header verwendet. Verwende für einen statischen API-Schlüssel einen benutzerdefinierten Authentifizierungsheader. Halte Authorization für die OpenAI-Zugangsdaten frei.

Melde dich bei dem ChatGPT-Workspace an, den dein Administrationsteam angegeben hat. Melde dich auch beim Gateway an, wenn du dazu aufgefordert wirst, und überprüfe anschließend die Verbindung.

Dein Administrationsteam kann verwaltete Anbietereinstellungen verteilen und die Weiterleitung der Zugangsdaten überprüfen.

Zugangsdaten am Gateway verarbeiten

Das Gateway erhält bei jeder Modellanfrage zwei Sätze von Zugangsdaten. Wenn Codex das OAuth-Token für das Gateway in einem Cookie sendet, sieht die Anfrage beispielsweise so aus:

POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>

Prüfe die Gateway-Zugangsdaten und entferne das zugehörige Cookie oder den benutzerdefinierten Header aus der Anfrage. Mache Zugangsdaten und sensible Anfrageinhalte in den Protokollen unkenntlich. Wähle aus, welche Zugangsdaten das Gateway für die Weiterleitung verwendet:

  • Leite für die direkte Inferenz bei OpenAI die Zugangsdaten der angemeldeten Person weiter (empfohlen). So kann OpenAI die Nutzung dieser Person zuordnen und ihre Inferenzeinstellungen anwenden. Für diese Route muss das Gateway Anfragen an /models und /responses als Proxy an https://chatgpt.com/backend-api/codex weiterleiten. Dabei muss es Authorization und einen gegebenenfalls vorhandenen ChatGPT-Account-ID-Header unverändert übermitteln.
  • Lass das Gateway die Authentifizierung beim Inferenzanbieter übernehmen. Verwende die Zugangsdaten, die auf dem Gateway für diesen Anbieter konfiguriert sind. Sende weder das OpenAI-Token der angemeldeten Person noch einen gegebenenfalls vorhandenen ChatGPT-Account-ID-Header an den Inferenzanbieter.

Die folgenden Diagramme zeigen die empfohlene Route für die Inferenz bei OpenAI.

So funktioniert ein Gateway-Schlüssel mit der ChatGPT-Anmeldung
So funktioniert Gateway-OAuth mit der ChatGPT-Anmeldung

Routing-Header hinzufügen (optional)

Verwende die Routing-Einstellungen deines Administrationsteams. Das für den Gateway-Betrieb zuständige Team kann diese Einstellungen verteilen und in den Gateway-Protokollen prüfen, welche Route gewählt wurde.

Nur Anfragen an den Modellanbieter laufen über diese Gateway-Route. Sprachsitzungen verwenden eine separate Route. Auch die Workspace-Anmeldung, MCP-Server und Plug-ins können andere Netzwerkpfade nutzen.

Client starten

Wenn du die ChatGPT-Anmeldung verwendest, starte den Client und melde dich bei dem Workspace an, der die verwaltete Konfiguration bereitstellt. Wenn du natives Gateway-OAuth verwendest, melde dich nach Aufforderung zusätzlich beim Gateway deiner Organisation an. Überprüfe anschließend die Verbindung.

Wenn du den Anbieter lokal konfigurierst, folge der Anleitung für deinen Client.

CLI konfigurieren

Unter macOS oder Linux liest die CLI standardmäßig ~/.codex/config.toml. Speichere die Anbietereinstellungen und führe codex aus. Verwende in WSL die Linux-Konfiguration und die Linux-Pfade, sofern CODEX_HOME nicht auf einen anderen Speicherort verweist.

macOS-App konfigurieren

Die macOS-App liest dieselbe Datei ~/.codex/config.toml. Speichere die Anbietereinstellungen und starte die App neu. Wenn du die Zugangsdaten über eine Umgebungsvariable bereitstellst, stelle sicher, dass der App-Prozess auf die Variable zugreifen kann.

Windows-App konfigurieren

Trage die Anbietereinstellungen in %USERPROFILE%\.codex\config.toml ein und starte die App neu. Verwende für die Authentifizierung per Befehl das Programm zum Abrufen des Tokens, das dein Administrationsteam installiert hat. Ersetze zum Beispiel die Authentifizierungstabelle für Unix durch folgende Tabelle:

[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

In TOML-Dateien unter Windows bleiben Backslashes in Zeichenfolgen mit einfachen Anführungszeichen erhalten. Ersetze auch die Unix-Pfade für Katalogdateien durch die tatsächlichen Pfade, die dir dein Administrationsteam nennt, zum Beispiel durch 'C:\ProgramData\OpenAI\Codex\models.json'.

Konfiguriere MCP-Server und Plug-ins separat. Die Zugangsdaten für das Modell-Gateway berechtigen nicht zum Zugriff auf deine Tools oder angebundenen Systeme.

Verbindung überprüfen

Verwende die Anbieter-ID und den Modellalias, die dir dein Administrationsteam genannt hat. Die Anbieter-ID bezeichnet die konfigurierte Verbindung. Der Modellalias bezeichnet ein Modell, an das Anfragen über diese Verbindung weitergeleitet werden. Die ChatGPT-Anmeldung und die Gateway-Authentifizierung regeln den Zugriff. Unter Umständen ist beides erforderlich.

Starte den Client nach einer Konfigurationsänderung neu. Starte in der CLI codex und prüfe mit /status, welches Modell und welcher Anbieter aktiv sind. Prüfe in der Desktop-App das ausgewählte Modell und die Konfiguration.

Sende diesen Prompt in einer neuen Aufgabe:

Reply with exactly: gateway-ok

Als Antwort solltest du gateway-ok erhalten. Die Antwort allein zeigt nicht, über welche Route die Anfrage lief. Lass dir von deinem Administrationsteam bestätigen, dass das Gateway dein Benutzerkonto, den Modellalias und die vorgesehene Route zum Inferenzanbieter protokolliert hat. Frage das Modell nicht nach seinem Namen, um es zu identifizieren.

Verbindungsprobleme beheben

Symptom Was du prüfen solltest
Der erwartete Anbieter ist nicht aktiv. Prüfe das ausgewählte Profil und die Rangfolge der Konfigurationseinstellungen. Stelle sicher, dass Schlüssel der obersten Ebene außerhalb der Anbietertabellen stehen.
Die OAuth-Anmeldung oder die Tokenübermittlung schlägt fehl. Prüfe die Registrierung des öffentlichen Clients, die Weiterleitungs-URI, die Scopes und je nach Konfiguration das Cookie oder den Header. Stelle sicher, dass das Gateway das ausgestellte Zugriffstoken akzeptiert.
Die Authentifizierung per API-Schlüssel oder Credential Helper schlägt fehl. Prüfe, ob die Umgebungsvariable mit den Zugangsdaten für den Client-Prozess verfügbar ist oder ob der installierte Credential Helper ein aktuelles Token abrufen kann. Bitte dein Administrationsteam zu klären, ob die Authentifizierung am Gateway oder beim nachgelagerten Anbieter fehlschlägt.
Das Modell wird nicht gefunden. Prüfe den angegebenen Modellnamen und bitte dein Administrationsteam, die Route für dieses Modell zu prüfen.
Das Modell verwendet unerwartete Funktionen. Bitte dein Administrationsteam zu prüfen, ob die Katalogmetadaten zu dem Modell passen, auf das der Alias verweist.
Das Streaming stockt oder Folgeanfragen schlagen fehl. Bitte das zuständige Gateway-Team, die Pufferung im Proxy, das abschließende Ereignis response.completed und die Gateway-Kompatibilität zu prüfen.
Der Pfad zum Katalog oder Credential Helper funktioniert nicht. Prüfe, ob die Datei in der Umgebung, in der Codex läuft, unter dem konfigurierten absoluten Pfad vorhanden ist.

Wenn du um Hilfe bittest, nenne die Client-Version, das Betriebssystem, den erwarteten Anbieter und Modellalias sowie die Authentifizierungsmethode. Gib an, welcher Schritt fehlgeschlagen ist. Füge die Fehlermeldung und den Zeitpunkt der Anfrage hinzu, damit das Gateway-Team die Anfrage finden kann. Entferne vor dem Senden alle Token, Cookies, Autorisierungsheader und sensiblen Prompts. Sende weder Dateien mit Zugangsdaten noch Konfigurationsauszüge, die Secrets enthalten.

Vorhandenes Gateway verwenden

Bitte dein Gateway-Team um die Anbietereinstellungen für Codex und den freigegebenen Modellalias. Wenn das Team noch eine Route für Codex freischalten muss, teile die Migrationscheckliste für das Administrationsteam mit ihm.

Weiterführende Dokumentation