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/statuspour confirmer le modèle et le fournisseur actifs. - Pour l’application macOS, examinez
~/.codex/config.tomlou la configuration gérée fournie par votre organisation. - Pour l’application Windows, examinez
%USERPROFILE%\.codex\config.tomlou 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 = falseAjoutez 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
modelsur 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/modelsqui 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 = 43127Ajoutez 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@remoteDans 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.
Utiliser une API key
Utilisez ce paramètre lorsque la passerelle attend une API key dans l’en-tête Authorization.
Ajoutez le paramètre suivant dans la table existante
[model_providers.enterprise-gateway] :
env_key = "CODEX_GATEWAY_API_KEY"Rendez votre identifiant d’authentification de passerelle disponible sous la forme de CODEX_GATEWAY_API_KEY dans
l’environnement du processus qui lance Codex, à l’aide du mécanisme de distribution des secrets de votre
organisation. Ne placez pas cet identifiant dans le fichier TOML ni dans un dépôt. Une variable
définie dans un terminal peut ne pas être accessible à une application lancée depuis le bureau.
Utiliser un en-tête d’authentification personnalisé
Si votre passerelle nécessite un en-tête tel que X-API-Key au lieu d’un jeton bearer,
remplacez env_key dans la table du fournisseur par :
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Utilisez le nom exact de l’en-tête fourni par votre administrateur. Codex lit la valeur dans
la variable d’environnement nommée ; conservez l’identifiant d’authentification hors du fichier de configuration.
Consultez la référence de configuration pour
model_providers.<id>.env_http_headers.
Avec la connexion via ChatGPT, utilisez l’en-tête personnalisé pour la clé de la passerelle afin que Codex puisse envoyer les informations d’authentification OpenAI de l’utilisateur dans Authorization.
Si l’en-tête personnalisé est votre seul mécanisme d’authentification, utilisez
model_catalog_json ; la découverte du catalogue distant ne s’exécutera pas.
Utiliser un utilitaire d’authentification de l’organisation
Si votre administrateur fournit une authentification reposant sur une commande, utilisez l’utilitaire installé
et la configuration qu’il fournit à la place de env_key. Ne configurez pas les deux mécanismes.
L’utilitaire doit être présent sur votre machine ; Codex ne l’installe pas. Par exemple,
ajoutez cette table sans env_key, en utilisant le chemin du programme de résolution et
les arguments fournis par votre administrateur :
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000La référence de l’authentification des fournisseurs personnalisés définit la commande, les arguments, le délai d’expiration, l’intervalle d’actualisation et les exigences relatives à la sortie du jeton. Demandez à votre administrateur comment renouveler votre connexion si l’utilitaire ne peut plus récupérer de jeton.
Avec la connexion via ChatGPT, exécutez l’utilitaire avant de lancer Codex et transmettez sa sortie dans un en-tête de passerelle personnalisé au lieu de configurer la table auth. Lorsque la clé expire, obtenez une nouvelle clé et relancez Codex.
Utilisez des chemins absolus résolus pour les exécutables des utilitaires et les fichiers de catalogue.
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 :
- Définissez
requires_openai_auth = trueet laissezbase_urlpointer vers votre passerelle. Supprimez tous les paramètresenv_key,experimental_bearer_tokenetauthdu fournisseur afin que Codex utilise vos identifiants OpenAI pour l’authentification principale. - Envoyez les identifiants de la passerelle séparément. Pour OAuth natif de la passerelle, configurez
gateway_oauth.deliverypour 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éservezAuthorizationaux 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
/modelset/responsesvershttps://chatgpt.com/backend-api/codexet transmettreAuthorizationainsi que tout en-têteChatGPT-Account-IDsans 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-IDdans 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


Fonctionnement d’OAuth sur la passerelle avec la connexion via ChatGPT


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 = 300000Dans 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-okLa 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.