Déployez une passerelle
Distribuez et vérifiez une connexion Codex via une passerelle pour votre organisation
En tant qu’administrateur de la passerelle, configurez les routes des modèles et autorisez un utilisateur pilote. Testez la connexion sur chaque client pris en charge avant de distribuer les paramètres aux développeurs. Utilisez OAuth natif de la passerelle, des API keys ou des assistants d’authentification pour vous authentifier auprès de la passerelle. Pour combiner l’authentification auprès de la passerelle et la connexion à un espace de travail ChatGPT, consultez Se connecter avec ChatGPT via une passerelle.
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.
- Des identifiants de fournisseur en amont conservés par la passerelle.
- Des alias de modèles approuvés, destinés à Codex et associés aux modèles en amont prévus.
- Une méthode d’authentification testée : OAuth natif de la passerelle, API keys de passerelle à portée limitée, ou utilitaire d’identification.
- Pour OAuth, un client public enregistré, des utilisateurs de test approuvés et une passerelle capable de valider les jetons d’accès OAuth.
- Pour les API keys ou les utilitaires, un mécanisme de distribution des secrets ou un utilitaire testé.
- Un moyen de distribuer la configuration, les éventuels utilitaires requis et les 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_iduniquement lorsque WebSocket ou le transport incrémental est activé. - Préserver les appels de fonctions et les éléments
function_call_outputcorrespondants. - 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 :
- Choisir les noms des modèles et vérifier les routes.
- Choisir l’authentification.
- Tester Codex via la passerelle.
- Distribuer la configuration.
- 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é.
| Nom du modèle de la passerelle | Configuration de Codex |
|---|---|
| Un nom de modèle intégré inclus dans votre version de Codex | Définissez model dans config.toml sur ce nom exact. |
Un alias personnalisé, tel que company-coding-model |
Fournissez un catalogue distant ou local contenant l’alias et les métadonnées du modèle correspondant. |
Utiliser un catalogue de modèles pour les noms personnalisés
Pour un catalogue local, commencez par l’exemple models.json.
Fournissez un catalogue de modèles 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 fonctionnalités d’outils que Codex utilise pour ce nom. Sans entrée correspondante, une requête peut parvenir au modèle en amont prévu tandis que Codex utilise des paramètres génériques.
Hébergez un catalogue distant avec model_providers.<id>.model_catalog_url pour mettre à jour les métadonnées des modèles de manière centralisée, ou distribuez un fichier local avec model_catalog_json. Utilisez un catalogue local lorsque l’authentification OAuth native de la passerelle est le seul moyen d’identification ; OAuth seul ne permet pas la découverte d’un catalogue distant. Consultez la référence de configuration pour ces deux paramètres.
Obtenez auprès de votre fournisseur cloud ou de passerelle un point de terminaison ou un fichier de catalogue compatible avec votre version de Codex. Assurez-vous qu’il contient chaque alias approuvé et les métadonnées du modèle correspondant. Pour la mise en œuvre du catalogue, consultez Mettre en œuvre des catalogues de modèles pour les passerelles et les clouds.
Diffuser un catalogue distant
Utilisez le point de terminaison HTTPS du catalogue fourni par votre fournisseur.
Distribuez l’URL complète du point de terminaison dans la table config.toml du fournisseur sélectionné :
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"Rendez CODEX_GATEWAY_API_KEY accessible au processus Codex. Définissez base_url
séparément pour acheminer l’inférence via la passerelle. Si vous l’omettez, Codex utilise le
point de terminaison OpenAI par défaut pour le mode d’authentification actuel.
La découverte nécessite une authentification par API key, par commande ou via le backend Codex. L’authentification OAuth native de la passerelle ou des en-têtes personnalisés seuls ne la déclenchent pas.
Coordonnez les mises à jour du catalogue avec votre fournisseur lorsque vos modèles approuvés changent. Redémarrez le client après avoir modifié sa configuration.
Supprimez tout paramètre model_catalog_json actif, y compris s’il est imposé via
requirements.toml. Il prévaut sur l’URL distante et empêche la récupération.
Distribuer un catalogue local
Utilisez model_catalog_json pour charger au démarrage le fichier fourni par le fournisseur. Un catalogue local
personnalisé remplace le catalogue intégré.
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.
Choisir l’authentification
OAuth natif de la passerelle
- Enregistrez un client OAuth public prenant en charge le flux de code d’autorisation avec PKCE, et approuvez les utilisateurs ou les groupes autorisés à se connecter.
- Configurez la passerelle pour valider le jeton d’accès émis dans le cookie ou l’en-tête personnalisé sélectionné. Appliquez les modèles approuvés, les limites de débit et les budgets à l’identité de chaque utilisateur.
- Suivez le guide OAuth natif de la passerelle pour recueillir les URL d’autorisation et de jeton, l’identifiant du client public, les portées, la ressource facultative, les paramètres de transmission du jeton et tout port de redirection fixe. Enregistrez l’URI de redirection de bouclage correspondante auprès de votre fournisseur d’identité.
- Testez la connexion dans le navigateur, le renouvellement du jeton et la révocation de l’accès avec un utilisateur de test dans la CLI ou l’application de bureau que vous comptez déployer. Assurez-vous que le navigateur peut atteindre l’URL de rappel, y compris pour les utilisateurs de la CLI à distance.
Les utilisateurs se connectent individuellement. Vous distribuez la configuration OAuth, et non un secret client, une API key de passerelle ou un exécutable d’utilitaire. Conservez les identifiants du fournisseur en amont sur la passerelle.
API keys ou utilitaires d’identification
- 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.
- 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.
- 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.
- 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.
- 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 le guide Configurer le fournisseur pour configurer un utilisateur de test isolé avec le bloc de fournisseur et la méthode d’authentification que vous comptez distribuer.
Si la passerelle fournit le catalogue de modèles, vérifiez qu’elle renvoie un tableau models compatible avec Codex. Pour l’inférence OpenAI utilisant les identifiants de l’utilisateur, vérifiez que la passerelle transmet les en-têtes ChatGPT requis au backend Codex.
Consignez la version du client, le système d’exploitation, l’ID du fournisseur, l’alias du modèle et la méthode d’authentification pour votre pilote. Effectuez les vérifications ci-dessous depuis chaque interface CLI ou application de bureau que vous prévoyez de prendre en charge. Si vous proposez à la fois une authentification uniquement auprès de la passerelle et une authentification auprès de la passerelle associée à une connexion à ChatGPT, testez chaque combinaison séparément.
| Vérification | Action | Critères de réussite |
|---|---|---|
| Configuration effective | Examinez les couches de configuration et confirmez le fournisseur, le modèle et les exigences prévus. | Le pilote utilise les paramètres distribués. Les valeurs par défaut de l’utilisateur ou du profil ne sélectionnent pas un autre itinéraire. |
| Connexion | Suivez les instructions de la section Vérifier la connexion. | Le fournisseur et l’alias attendus sont actifs, le prompt de test aboutit et les journaux de la passerelle identifient l’utilisateur de test. |
| Streaming | Demandez une réponse courte en plusieurs paragraphes. | Le texte arrive progressivement et le transport actif émet response.completed. Testez HTTP séparément pour vérifier que la passerelle transmet les événements SSE sans mise en mémoire tampon. |
| Boucle d’outils locaux | Dans un dossier temporaire avec des autorisations de lecture seule, demandez à Codex de répertorier les fichiers à la racine et de les résumer. | Codex effectue un appel d’outil local, renvoie le résultat et produit une réponse finale sans modification. |
| Suivi | Posez une question de suivi dans le même fil. | La réponse s’appuie sur l’échange précédent ; la passerelle accepte les données d’entrée rejouées. Si WebSocket ou le transport incrémentiel est activé, elle préserve également previous_response_id. |
| Erreurs et attribution | Répétez le test avec un alias de test volontairement invalide ou un identifiant de test expiré. | Le client reçoit une erreur de routage ou d’authentification utile, et les requêtes valides restent attribuées à l’utilisateur de test. |
Si l’approbation automatique est activée, utilisez un dossier de test temporaire pour déclencher une action d’outil qui nécessite un examen selon la politique prévue. Confirmez que la passerelle traite la demande d’examen et que le client applique la décision d’approbation. Un appel d’outil en lecture seule qui ne nécessite aucune approbation ne permet pas de tester ce parcours. Consignez tout workflow non pris en charge avant d’élargir le pilote.
Si le déploiement change le fournisseur des utilisateurs existants, testez une nouvelle conversation et une conversation créée avant le changement sur chaque client pris en charge. Consignez si les utilisateurs peuvent consulter, poursuivre ou créer une branche de la conversation existante, et fournissez-leur une procédure de récupération pour tout workflow bloqué. Ne supposez pas que le changement de fournisseur par défaut migre l’historique des conversations.
Une fois ces vérifications réussies, préparez les informations à transmettre aux développeurs.
Distribuer la configuration
Pour que chaque machine utilise 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 les paramètres d’authentification.
Éléments à distribuer
Pour l’authentification OAuth native de la passerelle, distribuez les tables du fournisseur et
[model_providers.<id>.gateway_oauth] figurant dans le guide de
connexion, avec les
valeurs d’enregistrement recueillies ci-dessus. Conservez requires_openai_auth = false et omettez
env_key, experimental_bearer_token et la table auth d’authentification par commande lorsque
OAuth est le seul moyen d’identification auprès de la passerelle.
Pour un utilitaire d’identification, distribuez le bloc config.toml suivant via la
couche de configuration choisie. Utilisez un modèle reconnu par votre version de Codex, ou
fournissez le catalogue correspondant décrit ci-dessus. Installez votre outil de résolution 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 = 300000Pour 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
Si vos utilisateurs ne se connectent pas à Codex avec ChatGPT, vous pouvez distribuer les paramètres d’équipe depuis votre propre serveur. Codex récupère ces paramètres indépendamment du routage de vos requêtes de modèle.
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 tous les exécutables auxiliaires et fichiers de catalogue locaux référencés.
Pour imposer une URL de catalogue distant, placez la définition complète du fournisseur dans
requirements.toml sous [model_providers.<id>]. Une définition de fournisseur
imposée remplace la table correspondante du fournisseur dans la configuration ordinaire ;
incluez son base_url, ses paramètres d’authentification et les autres champs requis.
Utilisez l’exigence model_provider lorsque vous devez également imposer la sélection du
fournisseur.
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.
Distribuer les en-têtes de routage
Si votre passerelle route les requêtes en fonction de la configuration ou de l’outil, ajoutez les en-têtes qu’elle attend au fournisseur dans votre fichier requirements.toml géré. L’exemple suivant fournit un identifiant de configuration de routage et identifie Codex comme client :
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Utilisez env_http_headers pour les valeurs d’en-tête fournies par l’environnement du client. Envoyez une requête de test et confirmez l’itinéraire sélectionné dans les journaux de la passerelle. Consultez Fournisseurs de modèles personnalisés pour connaître les options d’en-tête.
Fournir les valeurs de configuration aux développeurs
Fournissez aux développeurs une procédure de configuration unique correspondant au pilote que vous avez testé. Incluez les informations suivantes même si vous distribuez la configuration de manière centralisée :
| Élément à transmettre | Informations à fournir |
|---|---|
| Client approuvé | Le client, sa version, le système d’exploitation et les instructions d’installation ou de mise à jour utilisés pendant le pilote. |
| Distribution de la configuration | Indiquez si les paramètres sont déjà gérés ou nécessitent une configuration locale ; précisez tout assistant ou fichier de catalogue installé séparément. |
| Connexion attendue | L’identifiant du fournisseur, l’alias du modèle et l’URL de la passerelle, y compris son chemin d’API. Expliquez quelles valeurs les utilisateurs peuvent modifier. |
| Étapes de connexion | Indiquez si les utilisateurs doivent se connecter à un espace de travail ChatGPT, s’authentifier auprès de la passerelle ou faire les deux. Précisez l’espace de travail requis et la méthode d’authentification auprès de la passerelle. |
| Identifiants et catalogues | Les valeurs d’enregistrement OAuth, la variable d’environnement contenant l’identifiant ou la configuration de l’assistant installé, ainsi que toute URL de catalogue ou tout chemin local résolu. Transmettez les secrets via votre mécanisme approuvé de distribution des secrets. |
| Vérification et assistance | Le test de connexion, le résultat attendu, le responsable de la passerelle et les informations à inclure pour signaler un échec. |
Pour les machines gérées, orientez les développeurs vers Vérifier la présence d’une configuration existante. Pour une configuration manuelle, orientez-les vers Configurer le fournisseur.
Incluez vos instructions testées pour les conversations existantes si ce déploiement change le fournisseur. Gardez la configuration précédente qui fonctionnait à la disposition du responsable du déploiement, au cas où le pilote révélerait un problème.
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 :
- Confirmez que le client approuvé et tous les assistants ou fichiers de catalogue requis sont installés. Redémarrez Codex et effectuez les connexions indiquées dans les instructions transmises.
- Confirmez le fournisseur et le modèle attendus. Dans la CLI, utilisez
/status. Utilisez/debug-configpour examiner les couches de configuration lorsque les paramètres effectifs diffèrent des instructions transmises. - Exécutez le test rapide décrit dans Se connecter à une passerelle.
- Posez une question de suivi pour confirmer que la conversation peut se poursuivre, puis recherchez dans les journaux de la passerelle la requête de ce développeur.
Élargissez l’accès une fois le pilote validé sur les clients et les combinaisons d’authentification que vous prenez en charge. Conservez la configuration testée et les résultats avec vos instructions de déploiement afin de pouvoir répéter les vérifications après une mise à jour du client, de la passerelle ou de la politique.
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 :
| Problème | Solution |
|---|---|
| Le fournisseur attendu est absent après le redémarrage. | Examinez la couche de configuration qui a priorité. La configuration de l’utilisateur ou du profil peut remplacer les valeurs par défaut du système. |
| L’authentification échoue pour tous les utilisateurs. | Vérifiez l’authentification de la passerelle et les identifiants du fournisseur en amont ; identifiez le service qui a rejeté la requête. |
| L’authentification échoue pour un utilisateur. | Vérifiez l’accès de cet utilisateur auprès du fournisseur d’identité, ses identifiants de passerelle ou son outil de résolution de jetons. |
| Le streaming se bloque. | Examinez la mise en mémoire tampon de la passerelle et la transmission de l’événement final response.completed. |
| Un modèle est absent ou utilise des capacités génériques. | Pour un alias personnalisé, assurez-vous que l’alias de la passerelle, model dans Codex et slug dans le catalogue correspondent. Vérifiez le chemin du catalogue et sa compatibilité avec la version installée de Codex, puis redémarrez Codex. |
| Un chemin Windows ne fonctionne pas. | Utilisez des chemins absolus résolus. Dans TOML, utilisez des chaînes entre apostrophes pour les chemins Windows contenant des barres obliques inverses simples. |
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.
| Déploiement Claude existant | Migration vers Codex |
|---|---|
| Produit de passerelle, DNS, TLS, réseau privé, journalisation, masquage et supervision | Conservez ces services. Ajoutez une route destinée à Codex qui respecte les exigences de compatibilité de la passerelle. |
| Compte Bedrock, identifiants du fournisseur, périmètre IAM, profils d’inférence et rotation des identifiants | Conservez-les uniquement s’ils autorisent les modèles en amont désignés par les nouveaux alias Codex. Les identifiants du fournisseur restent sur la passerelle. |
Route Claude /v1/messages, format Bedrock InvokeModel, en-têtes Anthropic et nouvelles tentatives ou erreurs propres à Claude |
Ne les réutilisez pas comme preuve de compatibilité. Codex a besoin de POST /v1/responses, du streaming Responses, de la continuité des échanges, des appels d’outils et d’erreurs utiles. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY ou apiKeyHelper |
Codex ne prend pas en charge apiKeyHelper. Configurez l’authentification OAuth native de la passerelle, une clé à portée limitée avec env_key ou un outil de résolution de jetons Codex reposant sur une commande. |
Noms de modèles Claude, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides et correspondances des profils Bedrock |
Demandez à l’équipe chargée de la passerelle de choisir les noms des modèles et de configurer les éventuels alias personnalisés. Utilisez le nom du modèle et tout catalogue de modèles JSON qu’elle fournit. |
settings.json Claude, managed-settings.json, blocs JSON env, plist ou charges utiles du registre |
Conservez le même canal MDM ou de gestion de configuration, mais distribuez à la place config.toml de Codex et les valeurs requirements.toml prises en charge. |
Pour migrer en toute sécurité, effectuez ces étapes dans l’ordre :
- Inventoriez le parcours Claude actuel : URL de la passerelle, source des identifiants, en-têtes requis, alias de modèles, correspondances des profils Bedrock et canal de distribution géré.
- Ajoutez en parallèle un itinéraire Responses destiné à Codex et des alias de modèles Codex.
- Choisissez OAuth natif de la passerelle, une API key ou un assistant d’identifiants et autorisez un utilisateur de test. Pour un identifiant statique, exposez-le via
env_key; pour un assistant, implémentez et testez le contrat du résolveur Codex reposant sur une commande. - Configurez le fournisseur pour ce développeur avec la méthode d’authentification sélectionnée à l’étape 3. Pour un déploiement géré, adaptez la charge utile aux chemins Codex et à l’ordre de priorité décrits dans Déployer une passerelle.
- Exécutez la vérification rapide de la connexion dans la CLI ou l’interface de bureau réellement utilisée par le développeur, puis effectuez l’ensemble des vérifications de streaming, de poursuite de conversation, d’appels d’outils, d’erreurs, de journalisation et de routage des alias décrites dans Tester Codex via la passerelle.
- Une fois le pilote validé, distribuez la configuration aux autres développeurs.
Référence du catalogue de modèles
Commencer avec un fichier models.json local
Commencez par configurer et sélectionner votre fournisseur de passerelle sur la machine où vous exécutez Codex.
Enregistrez ce catalogue sous le nom models.json sur la machine qui exécute Codex. Remplacez
gateway-model par l’identifiant exact du modèle accepté par votre passerelle. Le nom d’affichage
est le libellé que les utilisateurs voient dans le sélecteur de modèles.
{
"models": [
{
"slug": "gateway-model",
"display_name": "Gateway model",
"base_instructions": "Help the user with their coding tasks.",
"supported_reasoning_levels": [],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 10000 },
"experimental_supported_tools": []
}
]
}Pour un exemple plus complet, consultez le catalogue de modèles de Codex.
Définissez model_catalog_json dans config.toml sur le chemin absolu du fichier.
Redémarrez Codex, sélectionnez Gateway model et envoyez une requête. Vérifiez que la
passerelle a reçu l’identifiant de modèle défini dans slug.
Pour un alias d’un modèle intégré, copiez son entrée de catalogue complète correspondant à votre version de Codex
et modifiez ses valeurs slug et display_name. Si l’alias n’a aucune cible de migration, définissez upgrade sur null. Cela préserve la fenêtre de contexte du modèle,
ses options de raisonnement et ses paramètres d’outils.
Mettre un catalogue à disposition des clients
Cette page s’adresse aux développeurs qui implémentent le format Codex Models, qui définit le catalogue de modèles et alimente le sélecteur de modèles. Si vous développez un fournisseur d’inférence, comme une passerelle ou un service cloud, utilisez cette spécification pour permettre à l’application de bureau Codex et à la CLI de découvrir vos modèles et d’utiliser leurs instructions et leurs paramètres de capacités.
Si vous administrez une entreprise et souhaitez contrôler le catalogue de modèles, consultez les
consignes de configuration de model_catalog_url.
Pour prendre en charge ce format, implémentez un point de terminaison de catalogue authentifié. Récupérez les valeurs par défaut actuelles de votre fournisseur en amont pour la version de Codex à l’origine de la requête, appliquez vos personnalisations et renvoyez le catalogue obtenu.
client_version Implémenter le point de terminaison du catalogue
Le point de terminaison du catalogue par défaut est /models sous base_url du fournisseur.
Par exemple, avec base_url = "https://gateway.example.com/v1", Codex envoie la requête suivante :
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>La découverte par défaut prend en charge l’authentification par commande et l’authentification via le backend de Codex,
comme ChatGPT. Pour un fournisseur personnalisé utilisant l’authentification par API key
sans authentification par commande, définissez model_providers.<id>.model_catalog_url
explicitement pour activer la découverte à distance. Une API key seule ne déclenche pas la découverte
sur le chemin par défaut.
Utilisez model_catalog_url pour choisir une URL complète de catalogue, par exemple
https://gateway.example.com/codex/models. Elle peut également pointer vers le point de terminaison par défaut
/v1/models. Codex utilise directement cette URL sans ajouter /models.
Pour la découverte par API key, laissez features.api_key_model_discovery activé ; il l’est
par défaut. Les en-têtes personnalisés seuls n’activent pas la découverte.
Codex envoie les informations d’authentification et les en-têtes configurés du fournisseur sélectionné, et
ajoute client_version ainsi que les éventuels query_params du fournisseur. Hébergez le catalogue sur un
service autorisé à recevoir ces informations d’identification.
Authentifiez l’appelant, récupérez les valeurs par défaut correspondantes en amont, appliquez vos
personnalisations et renvoyez directement le JSON ModelsResponse complet. Attribuez à chaque
entrée un slug unique et non vide. Pour un model_catalog_url explicite, Codex refuse
les redirections et les réponses de plus de 1 MiB. Continuez à contrôler l’accès aux modèles pour
les requêtes d’inférence.
Supprimez tout paramètre model_catalog_json effectif des clients utilisant le point de terminaison :
le fichier local est prioritaire et empêche la récupération à distance.
Respecter le schéma du client
Lisez le paramètre de requête client_version dans la requête de catalogue. Codex envoie sa
version de la CLI au format major.minor.patch, sans suffixe de préversion. Pour les clients de bureau,
il s’agit de la version de la CLI intégrée.
Utilisez le tag rust-v<version> correspondant dans le dépôt public de Codex, ou le
commit source exact pour une compilation personnalisée. Ces liens utilisent rust-v0.162.1 ; sélectionnez
la révision correspondant à votre client :
- Consultez les types de réponse
ModelsResponseetModelInfopour connaître le schéma. - Examinez le fichier
models.jsonintégré pour obtenir un exemple complet. Il s’agit de données de catalogue, et non d’un document JSON Schema.
Le fichier intégré est un instantané de la version publiée. Récupérez les valeurs par défaut actuelles avant de générer votre catalogue.
Récupérer les valeurs par défaut actuelles en amont
Les fournisseurs cloud proposant des modèles OpenAI récupèrent les valeurs par défaut auprès d’OpenAI. Les passerelles lisent le catalogue de leur fournisseur cloud ou en amont afin de conserver les paramètres du modèle déployé et sa disponibilité selon le compte et la région. Transmettez la version de Codex à l’origine de la requête à chaque étape et authentifiez-vous séparément auprès de chaque point de terminaison.
Pour récupérer les valeurs par défaut directement auprès d’OpenAI, appelez le point de terminaison des modèles Codex avec le
même client_version. Par exemple, avec une API key OpenAI :
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"Pour une intégration ChatGPT, utilisez le jeton d’accès ChatGPT de l’appelant et
l’en-tête ChatGPT-Account-ID, le cas échéant. Utilisez des informations d’identification autorisées pour le
point de terminaison en amont ; l’API key propre à votre passerelle ne permet pas de s’authentifier auprès d’OpenAI.
Analysez la réponse complète, y compris son tableau models de premier niveau. Ce point de terminaison
renvoie des métadonnées Codex telles que les instructions, les valeurs par défaut du raisonnement, les paramètres des outils,
les limites de contexte et les niveaux de service. Le point de terminaison public /v1/models ne
fournit pas ce catalogue.
Actualisez ces valeurs par défaut même si la version de Codex n’a pas changé. Limitez les requêtes à l’identité prévue en amont et respectez les directives de mise en cache des réponses : les catalogues peuvent dépendre des droits d’accès de l’appelant. Conservez vos personnalisations séparément pour pouvoir les réappliquer aux valeurs par défaut actualisées.
Appliquer les personnalisations du fournisseur
Modifiez les valeurs des champs tout en préservant la structure de réponse de la version :
- Filtrez les modèles pour ne conserver que ceux que l’appelant peut utiliser. Associez chaque
slugà une route d’inférence prise en charge et ajustezdisplay_name,descriptionoupriority. Pour un alias sans migration de modèle, définissezupgradesurnull. - Définissez les options de raisonnement, les limites de contexte, les modalités d’entrée et les niveaux de service sur des
valeurs prises en charge par votre modèle et votre route. Choisissez les valeurs par défaut parmi les options
prises en charge. Pour une route sans niveaux de service, videz
service_tiersetadditional_speed_tiers, puis définissezdefault_service_tiersurnull. - Préservez les instructions et les paramètres des outils en amont, sauf si vous avez testé une solution de remplacement. Les métadonnées n’ajoutent aucune capacité au modèle et n’accordent aucun accès à l’inférence.
Pour un alias de modèle sur une passerelle, découvrez comment fournir les métadonnées du modèle. Testez le catalogue obtenu avec chaque version de Codex prise en charge.
Utiliser les types Rust publics
Utilisez les crates du même tag ou commit Git public que le schéma du client :
- Utilisez
codex-protocolpourcodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Analysez les données avecserde_json::from_slice::<ModelsResponse>(), modifiezcatalog.modelset sérialisez toute la structure englobante avecserde_json::to_vec(). Cette structure gère les champs de compatibilité des instructions du modèle. - Utilisez
codex-models-manager::bundled_models_response()pour charger le catalogue statique intégré de cette révision sous la forme d’unModelsResponse. Cette fonction ne récupère pas les valeurs par défaut actuelles en amont.