Verbindung zu einem Gateway herstellen

Konfigurieren Sie ein Modell-Gateway und authentifizieren Sie sich mit nativem Gateway-OAuth, einem API key oder einem Hilfsprogramm für Zugangsdaten.

Verbinden Sie Codex mit dem Modell-Gateway Ihrer Organisation. Verwenden Sie dazu die Anbietereinstellungen und die Authentifizierungsmethode, die Ihr Gateway-Team bereitstellt. Das Gateway leitet Modellanfragen an Ihr Backend weiter, beispielsweise Amazon Bedrock.

Auf eine vorhandene Konfiguration prüfen

Installieren Sie den Codex-Client in der Version, die Ihr Administrator getestet hat. Wenn Ihre Organisation die Einstellungen verwaltet, öffnen Sie diesen Client und führen Sie die Anmeldeschritte aus Ihren Übergabeunterlagen aus. Sie können die folgenden Beispiele zur Anbieterkonfiguration überspringen.

  • Prüfen Sie für die CLI das ausgewählte Profil und führen Sie codex doctor aus. Verwenden Sie nach dem Start /status, um das aktive Modell und den aktiven Anbieter zu bestätigen.
  • Prüfen Sie für die macOS-App ~/.codex/config.toml oder die verwaltete Konfiguration, die Ihre Organisation bereitstellt.
  • Prüfen Sie für die Windows-App %USERPROFILE%\.codex\config.toml oder die Systemkonfiguration, die Ihre Organisation bereitstellt.

Wenn der erwartete Gateway-Anbieter und das erwartete Modell bereits aktiv sind, führen Sie alle von Ihrem Administrator bereitgestellten Anmeldeschritte aus und fahren Sie dann mit Verbindung überprüfen fort. Vermeiden Sie es, auf einem verwalteten Computer eine zweite Anbieterkonfiguration hinzuzufügen. Wenn die Einstellungen von den Übergabeunterlagen Ihres Administrators abweichen, fragen Sie vor dem Bearbeiten lokaler Dateien nach, welche Konfigurationsebene sie bereitstellen soll.

Gateway-Verbindungsdaten einholen

Klären Sie bei der manuellen Einrichtung, ob Sie eine Anmeldung im ChatGPT-Workspace, eine Gateway-Authentifizierung oder beides benötigen.

Um Codex selbst zu konfigurieren, lassen Sie sich von Ihrem Gateway-Team diese Werte geben:

  • Die HTTPS-Basis-URL des Gateways einschließlich des API-Pfads, zum Beispiel https://gateway.example.com/v1.
  • Den zu verwendenden Modellnamen und die Anbieter-ID.
  • Die Authentifizierungsmethode: natives Gateway-OAuth, einen API key mit eingeschränktem Berechtigungsumfang und dessen Umgebungsvariable oder ein installiertes Hilfsprogramm für Zugangsdaten.
  • Für OAuth die Autorisierungs-URL, Token-URL, öffentliche Client-ID und alle erforderlichen Berechtigungsbereiche. Bei Gateways, die ein Cookie oder einen benutzerdefinierten Header verwenden, dessen Namen.
  • Eine gegebenenfalls erforderliche Modellkatalog-URL oder eine Katalogdatei und deren absoluten lokalen Pfad.

Anbieter konfigurieren

Öffnen Sie config.toml unter ~/.codex/config.toml auf macOS oder Linux beziehungsweise unter %USERPROFILE%\.codex\config.toml auf Windows.

Fügen Sie dieses Beispiel in Ihre vorhandene Konfiguration ein und ersetzen Sie URL und Modell durch die Werte Ihres Administrators. Fügen Sie keine zweite Definition eines vorhandenen Schlüssels oder einer vorhandenen Tabelle hinzu. Dieses Beispiel verwendet gpt-6-sol; verwenden Sie es ohne benutzerdefinierten Katalog nur, wenn Ihr Administrator bestätigt, dass Ihre Codex-Version das Modell erkennt und dessen mitgelieferte Metadaten zum Gateway passen.

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

Fügen Sie anschließend die Authentifizierungseinstellungen hinzu, die Ihr Gateway-Team bereitstellt.

enterprise-gateway ist eine beispielhafte Anbieter-ID. Verwenden Sie dieselbe ID in model_provider und den zugehörigen Anbieter- und Authentifizierungstabellen. Dieses Beispiel deaktiviert die Websuche für den ersten Verbindungstest; Ihr Administrator sollte die Unterstützung der Funktion überprüfen, bevor er sie aktiviert.

Ihren Modellkatalog konfigurieren

Klären Sie mit Ihrem Gateway-Team, wie Codex die Fähigkeiten und Anweisungen für Ihr ausgewähltes Modell erhält:

  • Integrierter Name: Wenn das Gateway den genauen, mit Ihrer Codex-Version ausgelieferten Modellnamen akzeptiert und an das passende Modell weiterleitet, setzen Sie model auf diesen Namen. Codex verfügt bereits über dessen Metadaten.
  • Katalogendpunkt: Wenn das Gateway Codex-kompatible Metadaten bereitstellt, verwenden Sie die vollständige Katalog-URL. Dies kann ein /v1/models-Endpunkt sein, der die Codex-Katalogantwort implementiert. Eine Antwort, die nur Modell-IDs auflistet, reicht für benutzerdefinierte Aliasse nicht aus.
  • Katalogdatei: Wenn Ihr Gateway benutzerdefinierte Aliasse verwendet und Ihr Administrator eine Datei verteilt, verwenden Sie das Beispiel für eine lokale models.json-Datei. Verwenden Sie eine lokale Datei, wenn natives Gateway-OAuth Ihre einzige Anmeldemethode ist und Sie benutzerdefinierte Metadaten benötigen.

Wenn Ihr Administrator für die Authentifizierung per API key oder Hilfsprogramm eine Katalog-URL bereitstellt, fügen Sie diese der vorhandenen Tabelle [model_providers.enterprise-gateway] hinzu:

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

Entfernen Sie jede wirksame Einstellung für model_catalog_json; sie hat Vorrang vor der URL. Die Anforderungen an den Endpunkt finden Administratoren unter Einrichtung eines Remote-Katalogs.

Wenn Ihr Administrator eine lokale Modellkatalogdatei bereitstellt, speichern Sie sie und fügen Sie model_catalog_json vor der ersten TOML-Tabelle hinzu. Verwenden Sie dabei den absoluten Pfad der Datei. Benutzerdefinierte Aliasse benötigen passende Katalogmetadaten. Beispiel:

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

Verwenden Sie den Modellnamen und den Katalog, die Ihr Administrator zusammen bereitstellt. Fügen Sie nur dann einen Katalogpfad hinzu, wenn die Datei an diesem Speicherort vorhanden ist.

Authentifizierungsmethode auswählen

Verwenden Sie natives Gateway-OAuth für die Anmeldung im Browser, einen API key für Zugangsdaten mit eingeschränkten Berechtigungen oder ein Hilfsprogramm für Zugangsdaten, wenn Ihre Organisation einen entsprechenden Befehl bereitstellt.

{/* prettier-ignore */}

Natives Gateway-OAuth verwenden

Gateway-OAuth funktioniert unabhängig von der ChatGPT-Anmeldung. Verwenden Sie es, wenn Ihr Gateway Zugriffstoken akzeptiert, die vom Identitätsanbieter Ihrer Organisation ausgestellt werden, beispielsweise Microsoft Entra ID. Codex übernimmt die Anmeldung im Browser, die verschlüsselte Speicherung der Zugangsdaten und die Token-Aktualisierung, wenn der Autorisierungsserver ein Aktualisierungstoken ausstellt.

Bei ausschließlicher Gateway-Authentifizierung sendet Codex CLI ab Version 0.166.0 das Zugriffstoken standardmäßig in Authorization: Bearer <gateway access token>. Entfernen Sie alle Authorization-Einträge aus http_headers oder env_http_headers dieses Anbieters.

Ihr Gateway-Team muss einen öffentlichen OAuth-Client registrieren, der den Autorisierungscode-Flow mit PKCE unterstützt. Fügen Sie diese Tabelle zur Anbieterkonfiguration in config.toml hinzu und ersetzen Sie die URLs und die Client-ID durch die entsprechenden Werte:

[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

Fügen Sie dieser Tabelle scopes und bei Bedarf resource mit den Werten hinzu, die Ihr Identitätsanbieter und Ihr Gateway benötigen. Fordern Sie die für Aktualisierungstoken erforderlichen Scopes an, sofern Ihr Anbieter diese verlangt. Codex verwendet standardmäßig einen verfügbaren Loopback-Port. Wenn Ihr Identitätsanbieter eine feste Weiterleitungs-URI verlangt, legen Sie redirect_port fest und registrieren Sie für dieses Beispiel http://127.0.0.1:43127/callback.

Wenn Ihr Gateway ein Cookie oder einen benutzerdefinierten Header erwartet, legen Sie das optionale Feld delivery in der OAuth-Tabelle fest. Wählen Sie die Methode, die Ihr Gateway validiert:

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

Wenn Ihre Bereitstellung zusätzlich eine ChatGPT-Anmeldung erfordert, verwenden Sie das Cookie oder einen separaten Gateway-Header wie oben gezeigt. Siehe ChatGPT-Anmeldung aktivieren.

Ein Gateway, das nur einen statischen API key akzeptiert, muss das OAuth-Token und dessen Übermittlungsmethode unterstützen, bevor Sie diesen Flow verwenden können. Das Gateway verwaltet weiterhin seine eigenen Zugangsdaten für vorgelagerte Dienste, beispielsweise seine AWS-Zugangsdaten für Bedrock.

Wenn OAuth Ihr einziger Zugangsnachweis ist, behalten Sie requires_openai_auth = false bei und entfernen Sie die bisherigen Einstellungen env_key, experimental_bearer_token oder auth für den Gateway-Zugangsnachweis. Verwenden Sie einen lokalen Modellkatalog, wenn Sie benutzerdefinierte Modellmetadaten benötigen; OAuth allein ermöglicht keine Erkennung eines Remote-Katalogs.

Starten Sie die Desktop-App neu und folgen Sie der Aufforderung zur Gateway-Anmeldung, um den Browser zu öffnen. Starten Sie in der CLI codex und folgen Sie der Anmeldung im Browser, wenn Codex erstmals auf das Gateway zugreift. Schließen Sie die Anmeldung und MFA Ihrer Organisation ab und kehren Sie anschließend zum Client zurück. Wenn die Autorisierung abläuft oder Codex sie nicht erneuern kann, melden Sie sich bei Aufforderung erneut an.

Natives Gateway-OAuth erfordert einen Browser und einen erreichbaren Loopback-Callback. Es bietet keine Ausweichmöglichkeit per Gerätecode. Wenn die CLI über SSH ausgeführt wird, legen Sie redirect_port = 43127 in der OAuth-Tabelle fest und registrieren Sie die oben beschriebene passende Weiterleitungs-URI. Richten Sie auf dem Rechner mit Ihrem Browser eine Weiterleitung dieses Ports ein, bevor Sie Codex starten:

ssh -L 43127:127.0.0.1:43127 user@remote

Starten Sie in dieser SSH-Sitzung codex und öffnen Sie die Gateway-Anmelde-URL in Ihrem lokalen Browser. Auch eine CLI innerhalb eines Containers benötigt einen Callback, der vom Browser aus erreichbar ist. Wenn Sie den Callback nicht erreichbar machen können, verwenden Sie stattdessen einen API key oder ein Hilfsprogramm für Zugangsdaten.

Anmeldung mit ChatGPT aktivieren (empfohlen)

Wenn Ihre Organisation einen ChatGPT-Arbeitsbereich verwendet, erhalten Benutzer durch die Anmeldung Zugriff auf die für sie verfügbaren Funktionen, etwa Plugins von OpenAI. Die Steuerungseinstellungen Ihres Arbeitsbereichs gelten weiterhin, und Ihr Gateway verarbeitet nach wie vor die Modellanfragen. Funktionsverfügbarkeit vergleichen.

Aktualisieren Sie bei manueller Einrichtung vor der Anmeldung die vorhandene Tabelle [model_providers.enterprise-gateway]:

  1. Legen Sie requires_openai_auth = true fest und lassen Sie base_url weiterhin auf Ihr Gateway verweisen. Entfernen Sie alle Einstellungen für env_key, experimental_bearer_token und auth des Anbieters, damit Codex Ihren OpenAI-Zugangsnachweis für die primäre Authentifizierung verwendet.
  2. Senden Sie den Gateway-Zugangsnachweis separat. Konfigurieren Sie für natives Gateway-OAuth die Einstellung gateway_oauth.delivery so, dass sie das Cookie oder den benutzerdefinierten Header verwendet, das bzw. den Ihr Gateway akzeptiert. Verwenden Sie für einen API key oder ein Hilfsprogramm für Zugangsdaten einen benutzerdefinierten Authentifizierungsheader. Reservieren Sie Authorization für den OpenAI-Zugangsnachweis.

Melden Sie sich bei dem von Ihrem Administrator genannten ChatGPT-Arbeitsbereich an. Schließen Sie bei entsprechender Aufforderung die Gateway-Anmeldung ab und überprüfen Sie anschließend Ihre Verbindung.

Administratoren können verwaltete Anbietereinstellungen verteilen und die Weiterleitung von Zugangsdaten überprüfen.

Anmeldedaten am Gateway verarbeiten

Das Gateway erhält bei jeder Modellanfrage zwei Authentifizierungsnachweise. Ein Beispiel, bei dem Codex das OAuth-Token des Gateways in einem Cookie sendet:

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

Validieren Sie die Gateway-Anmeldedaten und entfernen Sie das zugehörige Cookie oder den benutzerdefinierten Header. Machen Sie Anmeldedaten und sensible Anfragedaten in Protokollen unkenntlich. Wählen Sie aus, welche Anmeldedaten Sie für die Upstream-Anfrage verwenden möchten:

  • Leiten Sie die Anmeldedaten des Benutzers für direkte OpenAI-Inferenz weiter (empfohlen). Dadurch kann OpenAI die Nutzung zuordnen und die Inferenzeinstellungen für diesen Benutzer anwenden. Für diese Route muss das Gateway /models und /responses per Proxy an https://chatgpt.com/backend-api/codex weiterleiten und Authorization sowie einen gegebenenfalls vorhandenen Header ChatGPT-Account-ID unverändert übermitteln.
  • Lassen Sie das Gateway sich beim Inferenzanbieter authentifizieren. Verwenden Sie die auf dem Gateway für diesen Anbieter konfigurierten Anmeldedaten. Lassen Sie das OpenAI-Token des Benutzers und einen gegebenenfalls vorhandenen Header ChatGPT-Account-ID in der Upstream-Anfrage weg.

Diese Diagramme zeigen die empfohlene Route für OpenAI-Inferenz.

So funktioniert ein Gateway-Schlüssel mit der Anmeldung über ChatGPT
Verwenden Sie den Befehl zum Abrufen der Anmeldedaten über ein Starthilfsprogramm erneut. Derselbe Gateway-Schlüssel wechselt von Authorization zu X-Gateway-Key, während die Anmeldung mit ChatGPT Authorization bereitstellt.
Das Gateway validiert und entfernt X-Gateway-Key und leitet anschließend den Authorization-Header von ChatGPT und eine gegebenenfalls vorhandene Konto-ID unverändert an das Codex-Backend weiter.
So funktioniert Gateway-OAuth mit der Anmeldung über ChatGPT
Ersetzen Sie die Gateway-Authentifizierung per API key durch natives Gateway-OAuth in Kombination mit der Anmeldung über ChatGPT.
Das Gateway verarbeitet und entfernt sein OAuth-Cookie und leitet die ChatGPT-Anmeldedaten an das Codex-Backend weiter.

Routing-Header hinzufügen (optional)

Verwenden Sie die von Ihrem Administrator bereitgestellten Routing-Einstellungen. Gateway-Betreiber können diese Einstellungen verteilen und die ausgewählte Route in den Gateway-Protokollen prüfen.

Nur Anfragen an Modellanbieter verwenden diese Gateway-Route. Sprachsitzungen verwenden eine separate Route. Die Anmeldung beim Arbeitsbereich, MCP server und Plugins können ebenfalls andere Netzwerkpfade verwenden.

Den Client starten

Starten Sie bei Verwendung der Anmeldung mit ChatGPT den Client und melden Sie sich bei dem Arbeitsbereich an, der die verwaltete Konfiguration bereitstellt. Wenn Sie natives Gateway-OAuth verwenden, führen Sie bei Aufforderung auch die Gateway-Anmeldung Ihrer Organisation durch. Anschließend überprüfen Sie die Verbindung.

Befolgen Sie bei einem lokal konfigurierten Anbieter die Anweisungen für Ihren Client.

CLI konfigurieren

Die CLI liest unter macOS oder Linux standardmäßig ~/.codex/config.toml. Führen Sie nach dem Speichern der Anbietereinstellungen codex aus. Verwenden Sie innerhalb von WSL die Linux-Konfiguration und Linux-Pfade, sofern CODEX_HOME nicht auf einen anderen Speicherort verweist.

macOS-App konfigurieren

Die macOS-App liest dieselbe ~/.codex/config.toml. Starten Sie nach dem Speichern der Anbietereinstellungen die App neu. Wenn Sie für die Zugangsdaten eine Umgebungsvariable verwenden, stellen Sie sicher, dass sie für den App-Prozess verfügbar ist.

Windows-App konfigurieren

Tragen Sie die Anbietereinstellungen in %USERPROFILE%\.codex\config.toml ein und starten Sie anschließend die App neu. Verwenden Sie für die befehlsbasierte Authentifizierung den von Ihrem Administrator installierten Resolver. Ersetzen Sie beispielsweise die Unix-Authentifizierungstabelle durch:

[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 unter Windows bleiben Backslashes in literalen Zeichenfolgen mit einfachen Anführungszeichen erhalten. Ersetzen Sie auch Unix-Katalogpfade, beispielsweise durch 'C:\ProgramData\OpenAI\Codex\models.json', und verwenden Sie dabei den tatsächlichen Pfad, den Ihr Administrator bereitgestellt hat.

Konfigurieren Sie MCP server und Plugins separat. Zugangsdaten für ein Modell-Gateway berechtigen nicht zum Zugriff auf Ihre Tools oder verbundenen Systeme.

Verbindung überprüfen

Verwenden Sie die Anbieter-ID und den Modellalias aus den Übergabeinformationen Ihres Administrators. Der Anbieter identifiziert die konfigurierte Verbindung; der Modellalias identifiziert ein Modell, das über diese Verbindung angesprochen wird. Die ChatGPT-Anmeldung und die Gateway-Authentifizierung steuern den Zugriff und können beide erforderlich sein.

Starten Sie den Client nach Änderungen an der Konfiguration neu. Starten Sie in der CLI codex und prüfen Sie mit /status das aktive Modell und den aktiven Anbieter. Prüfen Sie in der Desktop-App das ausgewählte Modell und die Konfiguration.

Senden Sie diesen Prompt in einer neuen Aufgabe:

Reply with exactly: gateway-ok

Die erwartete Antwort ist gateway-ok. Eine Antwort allein belegt nicht, über welche Route sie verarbeitet wurde: Bitten Sie Ihren Administrator zu bestätigen, dass das Gateway Ihren Nutzer, den Modellalias und die vorgesehene Upstream-Route protokolliert hat. Identifizieren Sie das Modell nicht, indem Sie es nach seinem Namen fragen.

Verbindungsprobleme beheben

Symptom Was Sie prüfen sollten
Der erwartete Anbieter ist nicht aktiv. Prüfen Sie das ausgewählte Profil und die Rangfolge der Konfigurationen. Stellen Sie sicher, dass sich Schlüssel der obersten Ebene nicht innerhalb einer Anbietertabelle befinden.
Die OAuth-Anmeldung oder Token-Übermittlung schlägt fehl. Prüfen Sie die Registrierung des öffentlichen Clients, die Redirect-URI, die Scopes und das konfigurierte Cookie oder den Header. Stellen Sie sicher, dass das Gateway das ausgestellte Zugriffstoken akzeptiert.
Die Authentifizierung mit API key oder Hilfsprogramm schlägt fehl. Prüfen Sie, ob die Zugangsdatenvariable im Clientprozess verfügbar ist oder das installierte Hilfsprogramm ein aktuelles Token abrufen kann. Bitten Sie den Administrator, zwischen Gateway-Authentifizierung und Upstream-Authentifizierung zu unterscheiden.
Das Modell wird nicht gefunden. Bestätigen Sie den bereitgestellten Modellnamen und bitten Sie den Administrator, dessen Route zu prüfen.
Das Modell verwendet unerwartete Fähigkeiten. Bitten Sie den Administrator zu prüfen, ob die Katalogmetadaten zum Modell hinter dem Alias passen.
Streaming stockt oder Folgerunden schlagen fehl. Bitten Sie den Gateway-Verantwortlichen, die Proxy-Pufferung, das abschließende response.completed-Ereignis und die Gateway-Kompatibilität zu prüfen.
Ein Katalog- oder Helferpfad funktioniert nicht. Stellen Sie sicher, dass die Datei unter dem konfigurierten absoluten Pfad in der Umgebung vorhanden ist, in der Codex ausgeführt wird.

Geben Sie bei Supportanfragen Ihre Client-Version, Ihr Betriebssystem, den erwarteten Anbieter und Modellalias, die Authentifizierungsmethode und den fehlgeschlagenen Schritt an. Fügen Sie die Fehlermeldung und den Zeitpunkt der Anfrage hinzu, damit der Gateway-Verantwortliche die Anfrage finden kann. Entfernen Sie Token, Cookies, Autorisierungsheader und vertrauliche Prompts. Senden Sie keine Dateien mit Zugangsdaten oder Konfigurationsauszüge, die Geheimnisse enthalten.

Eine vorhandene Gateway-Bereitstellung verwenden

Bitten Sie Ihr Gateway-Team um die Codex-Anbietereinstellungen und den freigegebenen Modellalias. Falls das Team noch eine Codex-Route aktivieren muss, teilen Sie die Migrationscheckliste für Administratoren.

Weiterführende Dokumentation