Se connecter à une passerelle

Configurez une passerelle de modèles et authentifiez-vous avec l’authentification OAuth native de la passerelle, une API key ou un utilitaire d’identification.

Connectez Codex à la passerelle de modèles de votre organisation en utilisant les paramètres du fournisseur et la méthode d’authentification fournis par l’équipe responsable de votre passerelle. La passerelle achemine les requêtes destinées aux modèles vers votre backend, par exemple Amazon Bedrock.

Vérifier s’il existe déjà une configuration

Installez le client Codex et la version testés par votre administrateur. Si votre organisation gère les paramètres, ouvrez ce client et suivez les étapes de connexion qui vous ont été transmises. Vous pouvez ignorer les exemples de configuration du fournisseur ci-dessous.

  • Pour la CLI, examinez le profil sélectionné et exécutez codex doctor. Après le démarrage, utilisez /status pour confirmer le modèle et le fournisseur actifs.
  • Pour l’application macOS, examinez ~/.codex/config.toml ou la configuration gérée fournie par votre organisation.
  • Pour l’application Windows, examinez %USERPROFILE%\.codex\config.toml ou la configuration système fournie par votre organisation.

Si le fournisseur de passerelle et le modèle attendus sont déjà actifs, suivez les éventuelles étapes de connexion fournies par votre administrateur, puis passez à Vérifier la connexion. Évitez d’ajouter une seconde configuration de fournisseur sur une machine gérée. Si les paramètres diffèrent des consignes transmises par votre administrateur, demandez quelle couche de configuration doit les fournir avant de modifier les fichiers locaux.

Obtenir les informations de connexion à votre passerelle

Pour une configuration manuelle, confirmez si vous avez besoin d’une connexion à l’espace de travail ChatGPT, d’une authentification auprès de la passerelle ou des deux.

Pour configurer Codex vous-même, obtenez les valeurs suivantes auprès de l’équipe chargée de votre passerelle :

  • L’URL de base HTTPS de la passerelle, y compris son chemin d’API, par exemple https://gateway.example.com/v1.
  • Le nom du modèle et l’identifiant du fournisseur à utiliser.
  • La méthode d’authentification : OAuth natif de la passerelle, une API key à portée limitée et sa variable d’environnement, ou un utilitaire d’identification installé.
  • Pour OAuth, l’URL d’autorisation, l’URL de jeton, l’identifiant client public et les portées requises. Pour les passerelles qui utilisent un cookie ou un en-tête personnalisé, son nom.
  • Toute URL de catalogue de modèles requise, ou un fichier de catalogue et son chemin local absolu.

Configurer le fournisseur

Ouvrez config.toml à l’emplacement ~/.codex/config.toml sous macOS ou Linux, ou %USERPROFILE%\.codex\config.toml sous Windows.

Intégrez cet exemple à votre configuration existante, en remplaçant l’URL et le modèle par les valeurs fournies par votre administrateur. N’ajoutez pas de seconde définition d’une clé ou d’une table existante. Cet exemple utilise gpt-6-sol ; utilisez-le sans catalogue personnalisé uniquement si votre administrateur confirme que votre version de Codex reconnaît le modèle et que ses métadonnées intégrées correspondent à la passerelle.

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

Ajoutez ensuite les paramètres d’authentification fournis par l’équipe responsable de votre passerelle.

enterprise-gateway est un exemple d’identifiant de fournisseur. Utilisez le même identifiant dans model_provider et dans les tables de fournisseur et d’authentification correspondantes. Cet exemple désactive la recherche web pour le test de connexion initial ; votre administrateur doit vérifier la prise en charge de cette fonctionnalité avant de l’activer.

Configurez votre catalogue de modèles

Confirmez auprès de l’équipe chargée de votre passerelle comment Codex obtient les capacités et les instructions du modèle sélectionné :

  • Nom intégré : si la passerelle accepte le nom exact du modèle inclus dans votre version de Codex et achemine les requêtes vers le modèle correspondant, définissez model sur ce nom. Codex dispose déjà de ses métadonnées.
  • Point de terminaison du catalogue : si la passerelle fournit des métadonnées compatibles avec Codex, utilisez l’URL complète de son catalogue. Il peut s’agir d’un point de terminaison /v1/models qui implémente la réponse de catalogue Codex. Une réponse qui répertorie uniquement les identifiants des modèles ne suffit pas pour les alias personnalisés.
  • Fichier de catalogue : si votre passerelle utilise des alias personnalisés et que votre administrateur distribue un fichier, utilisez l’exemple de fichier models.json local. Utilisez un fichier local lorsque l’authentification OAuth native de la passerelle est votre seul moyen d’authentification et que vous avez besoin de métadonnées personnalisées.

Pour l’authentification par API key ou par utilitaire, si votre administrateur fournit une URL de catalogue, ajoutez-la à la table existante [model_providers.enterprise-gateway] :

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

Supprimez tout paramètre model_catalog_json actif ; il prévaut sur l’URL. Les administrateurs trouveront les exigences relatives au point de terminaison dans la section configuration d’un catalogue distant.

Si votre administrateur fournit un fichier de catalogue de modèles local, enregistrez-le et ajoutez model_catalog_json avant la première table TOML, en utilisant le chemin absolu du fichier. Les alias personnalisés nécessitent des métadonnées de catalogue correspondantes. Par exemple :

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

Utilisez le nom du modèle et le catalogue fournis ensemble par votre administrateur. N’ajoutez pas de chemin de catalogue si le fichier n’existe pas à cet emplacement.

Choisir une méthode d’authentification

Utilisez l’authentification OAuth native de la passerelle pour vous connecter via le navigateur, une API key pour disposer d’un identifiant à portée limitée, ou un utilitaire d’identification si votre organisation fournit une commande.

{/* prettier-ignore */}

Utiliser l’authentification OAuth native de la passerelle

L’authentification OAuth de la passerelle fonctionne indépendamment de la connexion à ChatGPT. Utilisez-la lorsque votre passerelle accepte les jetons d’accès émis par le fournisseur d’identité de votre organisation, par exemple Microsoft Entra ID. Codex gère la connexion via le navigateur, le stockage chiffré des identifiants et le renouvellement des jetons lorsque le serveur d’autorisation émet un jeton de renouvellement.

Pour l’authentification uniquement auprès de la passerelle, Codex CLI 0.166.0 et les versions ultérieures envoient par défaut le jeton d’accès dans Authorization: Bearer <gateway access token>. Supprimez toute entrée Authorization des paramètres http_headers ou env_http_headers de ce fournisseur.

L’équipe responsable de votre passerelle doit enregistrer un client OAuth public prenant en charge le flux de code d’autorisation avec PKCE. Ajoutez cette table à la configuration du fournisseur dans config.toml, en remplaçant les URL et l’ID du client par les valeurs correspondantes :

[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

Ajoutez scopes et, si nécessaire, resource à cette table avec les valeurs requises par votre fournisseur d’identité et votre passerelle. Demandez les portées nécessaires aux jetons de renouvellement si votre fournisseur les exige. Codex utilise par défaut un port de bouclage disponible. Si votre fournisseur d’identité exige une URI de redirection fixe, définissez redirect_port et enregistrez http://127.0.0.1:43127/callback pour cet exemple.

Si votre passerelle attend un cookie ou un en-tête personnalisé, définissez le champ facultatif delivery dans la table OAuth. Choisissez la méthode que votre passerelle valide :

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

Si votre déploiement nécessite également une connexion à ChatGPT, utilisez le cookie ou un en-tête distinct pour la passerelle, comme indiqué ci-dessus. Consultez Activer la connexion à ChatGPT.

Une passerelle qui accepte uniquement une API key statique doit prendre en charge le jeton OAuth et son mode de transmission avant que vous puissiez utiliser ce flux. La passerelle continue de gérer ses propres identifiants en amont, tels que ses identifiants AWS pour Bedrock.

Lorsque OAuth est votre seul moyen d’authentification, conservez requires_openai_auth = false et supprimez les anciens paramètres env_key, experimental_bearer_token ou auth utilisés pour les identifiants de la passerelle. Utilisez un catalogue de modèles local si vous avez besoin de métadonnées de modèles personnalisées ; OAuth seul ne permet pas la découverte d’un catalogue distant.

Redémarrez l’application de bureau et suivez l’invite de connexion à la passerelle pour ouvrir le navigateur. Dans la CLI, lancez codex et suivez la procédure de connexion via le navigateur lorsque Codex accède pour la première fois à la passerelle. Terminez la connexion et l’authentification multifacteur de votre organisation, puis revenez au client. Si l’autorisation expire ou si Codex ne peut pas la renouveler, reconnectez-vous lorsque vous y êtes invité.

L’authentification OAuth native de la passerelle nécessite un navigateur et une URL de rappel accessible sur l’interface de bouclage. Elle ne propose aucune solution de repli par code d’appareil. Si la CLI s’exécute via SSH, définissez redirect_port = 43127 dans la table OAuth et enregistrez l’URI de redirection correspondante décrite ci-dessus. Depuis la machine où se trouve votre navigateur, redirigez ce port avant de lancer Codex :

ssh -L 43127:127.0.0.1:43127 user@remote

Dans cette session SSH, lancez codex et ouvrez l’URL de connexion à la passerelle dans votre navigateur local. Une CLI exécutée dans un conteneur a également besoin d’une URL de rappel accessible depuis le navigateur. Si vous ne pouvez pas rendre cette URL accessible, utilisez une API key ou un utilitaire d’identification à la place.

Activer la connexion via ChatGPT (recommandé)

Si votre organisation utilise un espace de travail ChatGPT, la connexion donne aux utilisateurs accès aux fonctionnalités auxquelles ils sont éligibles, telles que les plugins fournis par OpenAI. Les contrôles de votre espace de travail s’appliquent, et votre passerelle continue de traiter les requêtes destinées aux modèles. Comparez la disponibilité des fonctionnalités.

Pour une configuration manuelle, mettez à jour la table [model_providers.enterprise-gateway] existante avant de vous connecter :

  1. Définissez requires_openai_auth = true et laissez base_url pointer vers votre passerelle. Supprimez tous les paramètres env_key, experimental_bearer_token et auth du fournisseur afin que Codex utilise vos identifiants OpenAI pour l’authentification principale.
  2. Envoyez les identifiants de la passerelle séparément. Pour OAuth natif de la passerelle, configurez gateway_oauth.delivery pour utiliser le cookie ou l’en-tête personnalisé accepté par votre passerelle. Pour une API key ou un assistant d’authentification, utilisez un en-tête d’authentification personnalisé. Réservez Authorization aux identifiants OpenAI.

Connectez-vous à l’espace de travail ChatGPT indiqué par votre administrateur. Connectez-vous à la passerelle si vous y êtes invité, puis vérifiez votre connexion.

Les administrateurs peuvent distribuer les paramètres gérés du fournisseur et vérifier la transmission des identifiants.

Gérer les informations d’authentification au niveau de la passerelle

La passerelle reçoit deux éléments d’authentification à chaque requête destinée à un modèle. Par exemple, lorsque Codex envoie le jeton OAuth de la passerelle dans un cookie :

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

Validez les informations d’authentification de la passerelle et supprimez le cookie ou l’en-tête personnalisé qui les contient. Masquez les informations d’authentification et les données sensibles des requêtes dans les journaux. Choisissez les informations d’authentification à utiliser en amont :

  • Transmettez les informations d’authentification de l’utilisateur pour une inférence directe auprès d’OpenAI (recommandé). Cela permet à OpenAI d’attribuer l’utilisation à cet utilisateur et d’appliquer ses paramètres d’inférence. Pour cette route, la passerelle doit relayer /models et /responses vers https://chatgpt.com/backend-api/codex et transmettre Authorization ainsi que tout en-tête ChatGPT-Account-ID sans les modifier.
  • Laissez la passerelle s’authentifier auprès du fournisseur d’inférence. Utilisez les informations d’authentification configurées sur la passerelle pour ce fournisseur. N’incluez ni le jeton OpenAI de l’utilisateur ni aucun en-tête ChatGPT-Account-ID dans la requête en amont.

Ces schémas illustrent la route recommandée pour l’inférence auprès d’OpenAI.

Fonctionnement d’une clé de passerelle avec la connexion via ChatGPT
Réutilisez la commande d’authentification au moyen d’un utilitaire de lancement. La même clé de passerelle passe de Authorization à X-Gateway-Key, tandis que la connexion via ChatGPT fournit Authorization.
La passerelle valide et supprime X-Gateway-Key, puis transmet l’en-tête Authorization de ChatGPT et tout identifiant de compte au backend Codex sans les modifier.
Fonctionnement d’OAuth sur la passerelle avec la connexion via ChatGPT
Remplacez l’authentification de la passerelle par API key par l’authentification OAuth native de la passerelle, en complément de la connexion via ChatGPT.
La passerelle traite son cookie OAuth et transmet les informations d’authentification ChatGPT au backend Codex.

Ajouter des en-têtes de routage (facultatif)

Utilisez les paramètres de routage fournis par votre administrateur. Les opérateurs de la passerelle peuvent distribuer ces paramètres et vérifier la route sélectionnée dans les journaux de la passerelle.

Seules les requêtes destinées au fournisseur de modèles empruntent cette route via la passerelle. Les sessions vocales empruntent une route distincte. La connexion à l’espace de travail, les MCP servers et les plugins peuvent également emprunter d’autres chemins réseau.

Démarrer le client

Avec la connexion via ChatGPT, démarrez le client et connectez-vous à l’espace de travail qui fournit la configuration gérée. Si vous utilisez l’authentification OAuth native de la passerelle, connectez-vous également à la passerelle de votre organisation lorsque vous y êtes invité. Ensuite, vérifiez la connexion.

Pour un fournisseur configuré localement, suivez les instructions propres à votre client.

Configurer la CLI

La CLI lit ~/.codex/config.toml par défaut sous macOS ou Linux. Après avoir enregistré les paramètres du fournisseur, exécutez codex. Dans WSL, utilisez la configuration et les chemins Linux, sauf si CODEX_HOME pointe ailleurs.

Configurer l’application macOS

L’application macOS lit le même fichier ~/.codex/config.toml. Après avoir enregistré les paramètres du fournisseur, redémarrez l’application. Si vous utilisez une variable d’environnement pour l’identifiant d’authentification, assurez-vous qu’elle est accessible au processus de l’application.

Configurer l’application Windows

Placez les paramètres du fournisseur dans %USERPROFILE%\.codex\config.toml, puis redémarrez l’application. Pour l’authentification par commande, utilisez le résolveur installé par votre administrateur. Par exemple, remplacez la table d’authentification Unix par :

[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

Dans les fichiers TOML sous Windows, les chaînes littérales entre guillemets simples conservent les barres obliques inverses. Remplacez également les chemins de catalogue Unix, par exemple par 'C:\ProgramData\OpenAI\Codex\models.json', en utilisant le chemin réel fourni par votre administrateur.

Configurez les MCP servers et les plugins séparément. Un identifiant d’authentification de passerelle de modèles ne donne pas accès à vos outils ni à vos systèmes connectés.

Vérifier la connexion

Utilisez l’ID du fournisseur et l’alias du modèle communiqués par votre administrateur. Le fournisseur identifie la connexion configurée ; l’alias du modèle identifie un modèle acheminé via cette connexion. La connexion à ChatGPT et l’authentification auprès de la passerelle contrôlent l’accès et peuvent toutes deux être requises.

Redémarrez le client après avoir modifié la configuration. Dans la CLI, lancez codex et utilisez /status pour examiner le modèle et le fournisseur actifs. Dans l’application de bureau, vérifiez le modèle sélectionné et la configuration.

Envoyez ce prompt dans une nouvelle tâche :

Reply with exactly: gateway-ok

La réponse attendue est gateway-ok. Une réponse seule ne prouve pas quelle route l’a traitée : demandez à votre administrateur de confirmer que la passerelle a enregistré votre utilisateur, l’alias du modèle et la route amont prévue. N’identifiez pas le modèle en lui demandant son nom.

Résoudre les problèmes de connexion

Symptôme Points à vérifier
Le fournisseur attendu n’est pas actif. Vérifiez le profil sélectionné et l’ordre de priorité des configurations. Assurez-vous que les clés de premier niveau ne se trouvent pas dans une table de fournisseur.
La connexion OAuth ou la transmission du jeton échoue. Vérifiez l’enregistrement du client public, l’URI de redirection, les portées et le cookie ou l’en-tête configuré. Assurez-vous que la passerelle accepte le jeton d’accès émis.
L’authentification par API key ou par utilitaire échoue. Vérifiez que la variable contenant les identifiants est accessible au processus client, ou que l’utilitaire installé peut récupérer un jeton valide. Demandez à l’administrateur de distinguer l’authentification auprès de la passerelle de celle auprès du fournisseur en amont.
Le modèle est introuvable. Confirmez le nom du modèle fourni et demandez à l’administrateur de vérifier sa route.
Le modèle utilise des capacités inattendues. Demandez à l’administrateur de vérifier que les métadonnées du catalogue correspondent au modèle désigné par l’alias.
Le streaming se bloque ou les échanges suivants échouent. Demandez au responsable de la passerelle de vérifier la mise en mémoire tampon du proxy, l’événement final response.completed et la compatibilité de la passerelle.
Un chemin de catalogue ou d’utilitaire ne fonctionne pas. Assurez-vous que le fichier existe au chemin absolu configuré dans l’environnement où s’exécute Codex.

Lorsque vous demandez de l’aide, précisez la version de votre client, votre système d’exploitation, le fournisseur et l’alias du modèle attendus, la méthode d’authentification et l’étape qui a échoué. Incluez le message d’erreur et l’heure de la requête afin que le responsable de la passerelle puisse la retrouver. Supprimez les jetons, les cookies, les en-têtes d’autorisation et les prompts sensibles. N’envoyez pas de fichiers d’identifiants ni d’export de configuration contenant des secrets.

Utiliser un déploiement de passerelle existant

Demandez à l’équipe responsable de votre passerelle les paramètres du fournisseur Codex et l’alias du modèle approuvé. Si l’équipe doit encore activer une route Codex, partagez la liste de vérification de migration destinée aux administrateurs.

Documentation connexe