Se connecter à une passerelle

Connectez Codex à une passerelle LLM à l’aide de l’URL de la passerelle, de l’alias du modèle et de l’identifiant d’authentification ou du résolveur de jetons fournis par votre organisation.

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

Avant d’ajouter quoi que ce soit, vérifiez si votre administrateur a déjà configuré Codex.

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, passez à Vérifier la connexion.

Obtenir les informations de connexion à votre passerelle

Installez la CLI Codex ou l’application de bureau approuvée par votre organisation. Pour configurer Codex vous-même, obtenez les valeurs suivantes auprès de votre équipe chargée de la passerelle :

L’URL de base HTTPS de la passerelle, avec son chemin d’API, par exemple https://gateway.example.com/v1.
Le nom du modèle et l’ID du fournisseur à utiliser.
Votre identifiant d’authentification de passerelle à portée limitée et sa variable d’environnement, ou un résolveur de jetons installé et sa configuration.
Tout fichier de catalogue de modèles requis 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"
env_key = "CODEX_GATEWAY_API_KEY"

Si votre administrateur fournit un catalogue de modèles, enregistrez-le localement 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.

enterprise-gateway est un ID de fournisseur donné à titre d’exemple. Utilisez le même ID dans model_provider, [model_providers.<id>] et [model_providers.<id>.auth]. 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.

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.

Utiliser un utilitaire d’authentification de l’organisation

Si votre administrateur fournit une authentification par commande, utilisez l’utilitaire installé et sa configuration à 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, remplacez le paramètre env_key de l’exemple par cette table, en utilisant le chemin du résolveur 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 = 300000

La 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.

Utilisez des chemins absolus résolus pour les exécutables des utilitaires et les fichiers de catalogue.

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

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.

Cela vérifie la connexion initiale. Les administrateurs doivent également effectuer les vérifications de déploiement pour le streaming, les outils et les tours de conversation suivants.

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. Confirmez que les clés de premier niveau ne se trouvent pas dans une table de fournisseur.
L’authentification échoue.	Vérifiez que la variable contenant l’identifiant d’authentification 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 service amont.
Le modèle est introuvable.	Confirmez le nom de 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 tours suivants échouent.	Demandez au responsable de la passerelle de vérifier la mise en tampon du proxy, l’événement final `response.completed` et la compatibilité des passerelles.
Un chemin de catalogue ou d’utilitaire ne fonctionne pas.	Confirmez que le fichier existe au chemin absolu configuré dans l’environnement qui exécute Codex.

Lorsque vous demandez de l’aide, joignez le message d’erreur après en avoir retiré les jetons et les prompts sensibles.

Utiliser un déploiement de passerelle existant

Si votre organisation utilise déjà une passerelle avec un autre outil de programmation, vous pourrez peut-être réutiliser son chemin réseau, sa journalisation et son accès aux fournisseurs. Collaborez avec votre équipe chargée de la passerelle pour configurer et tester une connexion Codex :

Identifiez l’URL de la passerelle existante, le mécanisme d’authentification, les en-têtes requis, les routes des modèles et la méthode de distribution de la configuration.
Demandez à votre équipe chargée de la passerelle de confirmer que celle-ci prend en charge le comportement de l’API requis par Codex et de configurer une route de modèle pour Codex.
Obtenez un identifiant d’authentification de passerelle à portée limitée ou un utilitaire d’authentification, le nom du modèle et tout catalogue de modèles requis auprès de votre équipe chargée de la passerelle.
Configurez Codex avec ces valeurs.
Vérifiez la connexion dans la CLI ou l’application de bureau que vous comptez utiliser. Demandez à votre équipe chargée de la passerelle d’effectuer les vérifications du streaming, des outils et des tours suivants.
Une fois la phase pilote validée, suivez Déployer Codex via une passerelle pour distribuer la configuration aux autres développeurs.

Pour la liste des vérifications de migration destinée aux administrateurs et la correspondance des configurations, consultez Réutiliser un déploiement de passerelle existant.

Recherches récentes

Recherches suggérées

Navigation de la documentation