Connectez Codex à une passerelle

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

Vérifiez si Codex est déjà configuré

Installez le client Codex dans la version testée par votre administrateur. Si votre organisation gère les paramètres, ouvrez ce client et suivez les étapes de connexion que votre administrateur vous a communiquées. Vous pouvez alors passer les exemples de configuration du fournisseur ci-dessous.

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

Si le fournisseur de passerelle et le modèle attendus sont déjà actifs, suivez les éventuelles étapes de connexion indiquées par votre administrateur, puis passez à la section Vérifiez la connexion. Évitez d’ajouter une deuxième configuration de fournisseur sur une machine gérée. Si les paramètres diffèrent de ceux indiqués par votre administrateur, demandez-lui quelle couche de configuration doit les fournir avant de modifier les fichiers locaux.

Récupérez les paramètres de connexion à la passerelle

Pour une configuration manuelle, vérifiez si vous devez vous connecter à l’espace de travail ChatGPT, vous authentifier auprès de la passerelle ou faire les deux.

Pour configurer Codex vous-même, demandez les éléments suivants à l’équipe qui gère la passerelle :

• L’URL de base HTTPS de la passerelle, avec le chemin de son API, par exemple https://gateway.example.com/v1.
• Le nom du modèle et l’identifiant du fournisseur à utiliser.
• La méthode d’authentification : le mécanisme OAuth natif de la passerelle, une clé API à portée limitée avec sa variable d’environnement, ou un utilitaire d’authentification déjà installé.
• Pour OAuth, l’URL d’autorisation, l’URL d’obtention des jetons, l’identifiant du client public et les éventuelles portées requises. Si la passerelle utilise un cookie ou un en-tête personnalisé, demandez également son nom.
• Si un catalogue de modèles est requis, son URL ou le fichier de catalogue et son chemin local absolu.

Configurez le fournisseur

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

Intégrez cet exemple à votre configuration existante en remplaçant l’URL et le modèle par les valeurs fournies par votre administrateur. Ne définissez pas deux fois une même clé ou table. L’exemple utilise gpt-6-sol. Utilisez ce modèle sans catalogue personnalisé uniquement si votre administrateur confirme que votre version de Codex le reconnaît et que les métadonnées intégrées correspondent à celles de 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 qui gère la passerelle.

enterprise-gateway est un exemple d’identifiant de fournisseur. Utilisez le même identifiant dans model_provider et dans les tables de configuration et d’authentification du fournisseur. Cet exemple désactive la recherche web pour le premier test de connexion. Avant de l’activer, votre administrateur doit vérifier que la passerelle prend en charge cette fonctionnalité.

Configurez votre catalogue de modèles

Vérifiez auprès de l’équipe qui gère la 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 fourni avec votre version de Codex et achemine les requêtes vers le modèle correspondant, attribuez ce nom à model. Codex dispose déjà des métadonnées du modèle.
• 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 renvoie la réponse de catalogue attendue par Codex. Pour les alias personnalisés, une réponse qui contient uniquement la liste des identifiants de modèles ne suffit pas.
• Fichier de catalogue : si votre passerelle utilise des alias personnalisés et que votre administrateur distribue un fichier, suivez l’exemple de fichier models.json local. Utilisez un fichier local si le mécanisme OAuth natif de la passerelle est votre seul moyen d’authentification et que vous avez besoin de métadonnées personnalisées.

Si vous utilisez une clé API ou un utilitaire d’authentification et que votre administrateur vous fournit une URL de catalogue, ajoutez-la à la table [model_providers.enterprise-gateway] existante :

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

Supprimez tout paramètre model_catalog_json en vigueur, car il a priorité sur l’URL. Les administrateurs trouveront les exigences relatives au point de terminaison dans la section sur la configuration d’un catalogue distant.

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

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

Utilisez le nom de modèle et le catalogue que votre administrateur vous a fournis ensemble. N’ajoutez un chemin de catalogue que si le fichier existe à cet emplacement.

Choisissez une méthode d’authentification

Utilisez le mécanisme OAuth natif de la passerelle pour vous connecter dans le navigateur, une clé API pour limiter la portée des accès, ou un utilitaire d’authentification si votre organisation fournit une commande.

[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

delivery = { kind = "cookie", name = "auth-openid" }

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

ssh -L 43127:127.0.0.1:43127 user@remote

env_key = "CODEX_GATEWAY_API_KEY"

env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }

[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

Activez la connexion à ChatGPT (recommandé)

Si votre organisation utilise un espace de travail ChatGPT, les utilisateurs qui s’y connectent ont accès aux fonctionnalités auxquelles ils ont droit, par exemple les plugins d’OpenAI. Les règles 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 vérifiez que base_url pointe toujours vers votre passerelle. Supprimez les paramètres env_key, experimental_bearer_token et auth du fournisseur s’ils sont présents, afin que Codex utilise votre jeton OpenAI pour l’authentification principale.
2. Transmettez séparément les informations d’authentification de la passerelle. Pour le mécanisme 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 clé API ou un utilitaire d’authentification, utilisez un en-tête d’authentification personnalisé. Réservez Authorization au jeton OpenAI.

Connectez-vous à l’espace de travail ChatGPT indiqué par votre administrateur. Si vous y êtes invité, connectez-vous à la passerelle. Dans tous les cas, vérifiez ensuite votre connexion.

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

Traitez les informations d’authentification sur la passerelle

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

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, puis retirez 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 le jeton de l’utilisateur pour exécuter l’inférence directement chez OpenAI (recommandé). OpenAI peut ainsi attribuer l’utilisation à cet utilisateur et appliquer ses paramètres d’inférence. Pour cette route, la passerelle doit relayer les requêtes /models et /responses vers https://chatgpt.com/backend-api/codex et transmettre sans modification l’en-tête Authorization ainsi que l’en-tête ChatGPT-Account-ID s’il est présent.
• 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. Excluez de la requête en amont le jeton OpenAI de l’utilisateur et tout en-tête ChatGPT-Account-ID.

Ces schémas illustrent la route recommandée pour l’inférence chez OpenAI.

Fonctionnement d’une clé de passerelle avec la connexion à ChatGPT

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

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

Utilisez les paramètres de routage fournis par votre administrateur. Les responsables 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 adressé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 serveurs MCP et les plugins peuvent également emprunter d’autres chemins réseau.

Démarrez le client

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

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

Configurez la CLI

Sur macOS ou Linux, la CLI lit ~/.codex/config.toml par défaut. 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 vers un autre emplacement.

Configurez 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’authentification, vérifiez que le processus de l’application y a accès.

Configurez l’application Windows

Ajoutez les paramètres du fournisseur dans %USERPROFILE%\.codex\config.toml, puis redémarrez l’application. Pour l’authentification par commande, utilisez l’utilitaire 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 sur Windows, les chaînes littérales entre apostrophes conservent les barres obliques inverses. Remplacez également les chemins de catalogue Unix par le chemin Windows fourni par votre administrateur, par exemple 'C:\ProgramData\OpenAI\Codex\models.json'.

Configurez les serveurs MCP et les plugins séparément. Les informations d’authentification d’une passerelle de modèles ne donnent pas accès à vos outils ni à vos systèmes connectés.

Vérifiez la connexion

Utilisez l’identifiant du fournisseur et l’alias du modèle communiqués par votre administrateur. L’identifiant du fournisseur désigne la connexion configurée. L’alias du modèle désigne le modèle vers lequel cette connexion achemine les requêtes. 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 vérifier 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 :

Répondez exactement par : gateway-ok

La réponse attendue est gateway-ok. La réponse seule ne permet pas de déterminer la route empruntée. Demandez à votre administrateur de vérifier que la passerelle a bien enregistré votre identifiant utilisateur, l’alias du modèle et la route amont prévue. Ne cherchez pas à identifier le modèle en lui demandant son nom.

Résolvez les problèmes de connexion

Si vous demandez de l’aide, indiquez la version de votre client, votre système d’exploitation, le fournisseur et l’alias de modèle attendus, la méthode d’authentification et l’étape qui a échoué. Joignez le message d’erreur et précisez l’heure de la requête pour que le responsable de la passerelle puisse la retrouver. Retirez les jetons, les cookies, les en-têtes d’autorisation et les prompts sensibles. N’envoyez aucun fichier d’identifiants ni aucune copie de la configuration contenant des secrets.

Utilisez une passerelle déjà déployée

Demandez à l’équipe qui gère la passerelle les paramètres du fournisseur à utiliser dans Codex et l’alias de modèle approuvé. Si l’équipe doit encore activer une route pour Codex, transmettez-lui la liste des vérifications de migration destinée aux administrateurs.

Documentation associée

• CLI de Codex
• Serveurs MCP
• Plugins