Déployer Codex via une passerelle

Déployez Codex via la passerelle LLM de votre organisation. Configurez les routes des modèles, délivrez des identifiants aux développeurs et distribuez une configuration Codex vérifiée.

Prérequis

Avant de déployer Codex auprès des développeurs, vérifiez que vous disposez des éléments suivants :

• Une passerelle accessible en HTTPS à l’URL de base exacte que vous distribuerez.
• Un identifiant du fournisseur en amont, conservé par la passerelle.
• Des alias de modèles approuvés, exposés à Codex et associés aux modèles en amont prévus.
• Un identifiant de test pour la passerelle, avec des droits limités.
• Un mécanisme de transmission des secrets ou un utilitaire de gestion des identifiants testé.
• Un moyen de distribuer la configuration, les exécutables des utilitaires et les éventuels fichiers de catalogue.

Exigences relatives à la passerelle

Avant de connecter Codex, vérifiez que le produit de passerelle respecte les comportements requis suivants :

• Accepter les requêtes Codex à l’API Responses sur POST /v1/responses.
• Transmettre les événements SSE en continu, sans mise en mémoire tampon, et terminer par response.completed.
• Préserver la continuité des échanges avec les entrées rejouées.
• Préserver previous_response_id uniquement lorsque WebSocket ou le transport incrémental est activé.
• Préserver les appels de fonctions et les éléments function_call_output correspondants.
• Acheminer chaque alias de modèle exposé à Codex vers le modèle en amont prévu.
• Authentifier les utilisateurs séparément et renvoyer des erreurs utiles sans en masquer la cause.

Un point de terminaison de contrôle d’état, /v1/models, une réponse Chat Completions ou une simple réponse textuelle ne suffisent pas à valider la passerelle. Consultez les Exigences de compatibilité des passerelles pour connaître le contrat détaillé.

Déployer la passerelle

Pour passer d’une passerelle déployée à une expérience développeur vérifiée, effectuez ces cinq étapes de contrôle dans l’ordre :

1. Choisir les noms des modèles et vérifier les routes.
2. Délivrer les identifiants des développeurs.
3. Tester Codex via la passerelle.
4. Distribuer la configuration.
5. Vérifier depuis une machine de développeur.

Choisir les noms et les routes des modèles

Définissez model dans Codex sur le nom du modèle utilisé par la passerelle. Configurez la passerelle pour acheminer ce nom vers le modèle en amont approuvé.

Utiliser un catalogue de modèles pour les noms personnalisés

Utilisez model_catalog_json lorsque votre passerelle utilise un nom de modèle que Codex ne reconnaît pas. Le catalogue fournit les instructions, les options de raisonnement, les limites de contexte et les capacités des outils que Codex utilise pour ce nom. Sans entrée correspondante, une requête peut atteindre le modèle en amont prévu alors que Codex utilise des paramètres génériques.

Par exemple, pour utiliser company-coding-model comme alias de gpt-6-luna :

1. Créez l’alias company-coding-model sur la passerelle et acheminez-le vers le modèle en amont approuvé gpt-6-luna.
2. Téléchargez le catalogue de modèles Codex correspondant à votre version de Codex et enregistrez-en une copie sous le nom gateway-models.json. Utilisez ce fichier comme point de départ.
3. Modifiez l’entrée gpt-6-luna dans votre copie : définissez slug sur company-coding-model et vérifiez que les autres métadonnées correspondent au modèle en amont et aux capacités de la passerelle. Pour un alias sans migration de modèle, définissez upgrade sur null.
4. Conservez les entrées dans le tableau models de premier niveau et distribuez le fichier à chaque client. Un catalogue personnalisé remplace le catalogue fourni ; incluez donc tous les modèles que les utilisateurs doivent pouvoir sélectionner.

Pour Bedrock via LiteLLM, appliquez les modifications requises du catalogue.

Définissez l’alias de la passerelle, slug dans le catalogue et model dans Codex sur company-coding-model. Ajoutez ces paramètres avant la première table TOML dans la configuration Codex que vous distribuez, en utilisant le chemin absolu réel du fichier :

model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"

Redémarrez la CLI ou l’application de bureau après avoir modifié le catalogue, car Codex le charge au démarrage.

Vérifier les routes des modèles

Pour chaque modèle, vérifiez la route avec une véritable requête Responses et les journaux de la passerelle. Une réponse /v1/models peut aider à découvrir les noms, mais ne prouve pas qu’un modèle prend en charge le comportement requis pour les requêtes et les outils.

Le routage des modèles et l’autorisation des outils sont des volets distincts du déploiement. Configurez séparément les connexions MCP, la distribution des plugins et leurs politiques.

Délivrer les identifiants des développeurs

1. Délivrez à chaque développeur un identifiant de passerelle avec des droits limités afin de pouvoir lui attribuer l’utilisation et révoquer son accès individuellement.
2. Définissez les modèles approuvés, les limites de débit, le budget, l’expiration et la période de renouvellement pour chaque identifiant.
3. Transmettez les identifiants par votre gestionnaire de secrets ou un utilitaire de gestion des identifiants installé. Ne conservez pas les identifiants du fournisseur en amont ni ceux de l’administrateur de la passerelle sur les machines des développeurs.
4. Si vous utilisez un utilitaire, respectez le contrat d’authentification par commande et testez la récupération et le renouvellement des jetons avant la distribution.
5. Indiquez aux développeurs comment renouveler leurs identifiants et qui contacter pour obtenir de l’aide.

Tester Codex via la passerelle

Avant toute distribution, suivez la procédure Se connecter à une passerelle pour configurer un utilisateur de test isolé avec le bloc fournisseur et le mécanisme d’identification que vous prévoyez de distribuer.

Exécutez les vérifications ci-dessous depuis la même interface CLI ou de bureau que celle qu’utiliseront les développeurs :

Une fois ces vérifications réussies, orientez les développeurs vers Se connecter à une passerelle pour configurer et vérifier leur propre machine.

Distribuer la configuration

Pour fournir à chaque machine le même chemin de connexion, distribuez l’URL de base de la passerelle, l’identifiant du fournisseur, l’alias de modèle approuvé et le mécanisme d’identification.

Éléments à distribuer

Pour définir les paramètres par défaut du fournisseur, distribuez ce bloc config.toml via la couche de configuration que vous avez choisie. Utilisez un modèle reconnu par votre version de Codex, ou fournissez le catalogue correspondant décrit ci-dessus. Installez votre résolveur de jetons au chemin de commande configuré :

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"

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

Pour une clé de test statique à courte durée de validité, supprimez le bloc d’authentification, placez env_key = "CODEX_GATEWAY_API_KEY" dans [model_providers.enterprise-gateway] et définissez cette variable en dehors de TOML. Ne combinez pas env_key avec l’authentification par commande.

Distribuer les paramètres par défaut et les exigences

Consultez Priorité des configurations pour choisir où distribuer les paramètres par défaut. Pour les paramètres imposés et les charges utiles MDM de macOS, consultez Configuration gérée.

Pour les paramètres par défaut à l’échelle de la machine sur macOS ou Linux, utilisez /etc/codex/config.toml. Sur Windows, placez config.toml dans %ProgramData%\OpenAI\Codex\. Les utilisateurs et les profils peuvent remplacer ces valeurs par défaut. Les références liées décrivent les exigences prises en charge et l’emplacement de leurs fichiers.

Distribuez séparément les exécutables des utilitaires et les fichiers de catalogue référencés.

model_catalog_json pointe vers un fichier JSON local. Si vous l’imposez via requirements.toml, l’exigence fixe le chemin ; elle ne distribue pas le fichier. Placez le catalogue à ce chemin absolu avant le démarrage de Codex.

Écrivez les chemins Windows absolus résolus dans TOML. Codex ne développe pas %ProgramData% dans les valeurs de model_catalog_json ou de command pour l’authentification du fournisseur. Par exemple, utilisez ces chemins uniquement si votre déploiement y a placé les fichiers :

model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'

[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]

Une CLI dans WSL lit les chemins Linux et le fichier CODEX_HOME de Linux ; elle n’hérite pas automatiquement de la configuration native de Windows.

Fournir les valeurs de configuration aux développeurs

Si vous ne disposez pas d’une distribution gérée, fournissez à chaque développeur l’URL de la passerelle, l’identifiant du fournisseur, l’alias du modèle, la variable d’identification ou le résolveur, ainsi que tout chemin de catalogue. Orientez-les vers Se connecter à une passerelle pour configurer et vérifier leur propre machine.

La configuration manuelle n’est pas un mécanisme permettant d’imposer des paramètres. Un fichier .codex/config.toml local au projet ne peut pas remplacer les clés sensibles de routage du fournisseur ou d’authentification.

Vérifier depuis une machine de développeur

Pour confirmer que les paramètres distribués sont bien parvenus à une machine de développeur :

1. Redémarrez Codex et confirmez le fournisseur et le modèle attendus.
2. Exécutez le test court décrit dans Se connecter à une passerelle.
3. Posez une question de suivi pour confirmer la continuité, puis recherchez dans les journaux de la passerelle la requête de ce développeur.

Résoudre les échecs de déploiement

Utilisez le problème rencontré pour identifier la couche de configuration, d’identification ou de passerelle qui nécessite une intervention :

Réutiliser un déploiement de passerelle existant

Si votre organisation utilise déjà Claude Code via une passerelle, vous pourrez peut-être réutiliser le produit de passerelle, le chemin réseau, la journalisation et l’accès à Bedrock. Ajoutez une route Responses destinée à Codex, un identifiant, des alias de modèles et config.toml tout en conservant la configuration existante qui fonctionne. Les paramètres du client Claude et le contrat /v1/messages ne configurent pas Codex.

Pour migrer en toute sécurité, effectuez ces étapes dans l’ordre :

1. Inventoriez le chemin actuel de Claude : URL de la passerelle, source des identifiants, en-têtes requis, alias de modèles, correspondances de profils Bedrock et canal de distribution géré.
2. Ajoutez en parallèle une route Responses destinée à Codex et des alias de modèles Codex.
3. Délivrez un identifiant Codex avec des droits limités. Si Codex utilise un identifiant statique, exposez ce nouvel identifiant via env_key ; si Claude utilise un utilitaire de gestion des identifiants, implémentez et testez le contrat du résolveur Codex par commande.
4. Configurez le poste de ce développeur avec le bloc fournisseur. Pour un déploiement géré, adaptez la charge utile aux chemins et à l’ordre de priorité de Codex décrits dans Déployer Codex via une passerelle.
5. Exécutez la vérification rapide de connexion dans l’interface CLI ou de bureau réellement utilisée par le développeur, puis effectuez l’ensemble des vérifications de diffusion en continu, de continuité, d’appels d’outils, d’erreurs, de journalisation et de routage des alias décrites dans Tester Codex via la passerelle.
6. Une fois le pilote validé, distribuez la configuration aux autres développeurs.

Documentation connexe

• Se connecter à une passerelle
• MCP
• Plugins
• Configuration gérée