Codex est le produit d'agent de programmation d'OpenAI, disponible notamment en outil de ligne de commande (Codex CLI), en extension d'IDE et en tâches cloud. Beaucoup d'équipes veulent le connecter à leur propre point d'entrée API, pour une clé et une facturation unifiées, ou pour utiliser les modèles d'une passerelle. Il faut d'abord préciser une chose : il n'existe pas d'« API Codex » indépendante. Codex CLI appelle l'interface Responses d'OpenAI ; l'« API personnalisée » consiste donc à remplacer l'URL de base, la clé et le nom de modèle par un point de terminaison compatible.

Cet article prend les versions courantes d'octobre 2026 comme référence et couvre trois points : installer Codex CLI, écrire config.toml, puis vérifier et dépanner après connexion à une passerelle personnalisée.

Remarque : OpenAI et Codex sont des marques de leurs détenteurs ; cet article est purement technique. Les exigences de protocole, les interfaces et les noms de modèles pris en charge peuvent évoluer ; la documentation de l'éditeur et la page Tarifs des modèles font foi.

1. Distinguer les trois formes de Codex

Forme Entrée Clé personnalisée possible
Codex CLI Commande codex dans le terminal Oui, via config.toml
Extension IDE Barre latérale de l'éditeur Selon la version, généralement liée au compte
Tâches cloud Interface web Généralement via un compte ChatGPT

Pour la plupart des développeurs, Codex CLI est le terrain principal de l'API personnalisée. Il lit le code, modifie les fichiers et exécute les commandes ; le modèle ne fait que raisonner. En changeant le point de terminaison du modèle, la chaîne d'outils reste exécutée localement.

2. Clé API et URL de base de Codex

Le fournisseur personnalisé de Codex CLI demande trois paramètres : URL de base, clé API et nom de modèle. L'adresse par défaut d'OpenAI est https://api.openai.com/v1 ; avec ZSQH AI Gateway, l'adresse est https://ai.zhongshangqihang.com/v1.

Élément Valeur par défaut Passerelle ZSQH
URL de base https://api.openai.com/v1 https://ai.zhongshangqihang.com/v1
Authentification Clé API OpenAI Clé créée dans la console de la passerelle
Protocole Responses API Entrée /v1/responses ; modèles pris en charge selon la documentation
Nom de modèle ID OpenAI Selon la page tarifs du site

Un changement important en 2026 : le fournisseur personnalisé de Codex CLI n'accepte actuellement que wire_api = "responses" ; l'ancien wire_api = "chat" a été retiré. La passerelle doit donc relayer le protocole Responses. Si elle ne fournit que Chat Completions, il faut une couche de conversion de protocole ou un autre client. ZSQH AI Gateway expose /v1/responses ; les modèles compatibles sont indiqués dans la documentation et la page tarifs.

3. Installer Codex CLI

Choisissez la méthode adaptée à votre système :

# npm
npm install -g @openai/codex

# macOS Homebrew
brew install --cask codex

# Vérifier la version après installation
codex --version

Après installation, ne modifiez pas encore la configuration. Connectez-vous d'abord avec un compte OpenAI pour vérifier que l'outil fonctionne :

  1. Exécutez codex dans le terminal.
  2. Choisissez le mode de connexion proposé.
  3. Créez un répertoire de test et faites-lui lire un fichier.
  4. Confirmez que la réponse est normale avant de basculer vers un fournisseur personnalisé.

4. Écrire config.toml

La configuration utilisateur de Codex CLI se trouve dans ~/.codex/config.toml. Un fichier .codex/config.toml placé dans le projet ne remplace pas la définition du fournisseur, ce qui laisse souvent croire que la configuration n'a pas été prise en compte.

# ~/.codex/config.toml
model = "votre-id-modele"
model_provider = "zsqh"

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
env_key = "ZSQH_API_KEY"
wire_api = "responses"

Signification des champs :

  • model : ID du modèle à appeler, identique à celui de la page tarifs de la passerelle.
  • model_provider : nom du fournisseur défini plus bas ; les deux doivent correspondre.
  • base_url : racine compatible OpenAI, généralement terminée par /v1.
  • env_key : nom de la variable d'environnement qui contient la clé ; n'écrivez pas la clé dans le fichier.
  • wire_api : responses pour la version actuelle.

Exportez ensuite la clé dans le shell :

export ZSQH_API_KEY="sk-votre-cle"

Sous Windows PowerShell, utilisez $env:ZSQH_API_KEY="sk-votre-cle". Pour un effet permanent, ajoutez la variable au profil du shell ou aux variables système, sans la committer dans le dépôt.

5. Vérifier la première requête

En mode interactif, lancez codex dans le répertoire du projet et posez une question en lecture seule, par exemple « explique le fichier d'entrée de ce répertoire ». Pour une vérification non interactive unique, utilisez codex exec si la sous-commande existe dans votre version (vérifiez d'abord avec codex exec --help) :

cd /path/to/your-project
codex exec "Explique en trois points la structure du projet, sans modifier de fichier"

Pour suivre le chemin de la requête, activez les journaux de débogage :

codex --log-level debug

Vérifiez que l'URL pointe vers votre URL de base, que le chemin est bien /responses et que le nom du modèle est envoyé tel quel. Beaucoup de « configurations qui ne prennent pas effet » viennent d'un terminal qui n'a pas rechargé les variables ou d'un mauvais emplacement de fichier.

6. Choisir le modèle

Les tâches de Codex relèvent surtout de la compréhension de code, de la génération de patchs et de l'exécution de commandes. Trois critères priment : longueur de contexte, stabilité des appels d'outils et respect des instructions sur les tâches longues. Ne regardez pas seulement le prix unitaire.

Scénario Recommandation Attention
Modifications quotidiennes Modèle généraliste ou de code Vérifier le streaming
Lecture de grands dépôts Modèle à long contexte Plus le contexte est long, plus l'appel coûte
Tâches multi-étapes Modèle stable en appels d'outils Valider sur une petite tâche
Scripts par lots Modèle économique Limiter les nouvelles tentatives

Les ID de modèles sont ceux de la page tarifs. Recopier un nom d'affichage dans model est l'une des erreurs les plus fréquentes : nom d'affichage et identifiant API sont souvent différents.

7. Erreurs courantes et traitement

Symptôme Cause fréquente Traitement
401 Unauthorized Clé non exportée ou erronée Rouvrir le terminal, vérifier la variable pointée par env_key
404 Not Found /v1 en trop ou manquant, ou passerelle sans /responses Vérifier l'adresse et le périmètre d'interface
Erreur wire_api = "chat" Ancienne configuration Passer à responses ou mettre Codex à jour
model not found ID différent de la page tarifs Copier l'identifiant exact
Requête interrompue Réseau ou timeout de streaming Vérifier proxy, délais et tentatives
429 Limitation de débit ou quota insuffisant Consulter l'usage de la passerelle, réduire la concurrence

Si la passerelle ne prend en charge que Chat Completions et que la version actuelle de Codex n'accepte que Responses, la solution la plus sûre est d'ajouter une couche de conversion de protocole (par exemple une passerelle comme LiteLLM), plutôt que de chercher une ancienne version. Les anciennes versions finissent par ne plus être maintenues.

8. Liste de contrôle sécurité et coûts

  1. La clé reste dans les variables d'environnement ou un gestionnaire de secrets, jamais dans Git.
  2. Émettre une clé dédiée à Codex, pour faciliter quotas et révocation.
  3. Fixer budget et limite de concurrence côté passerelle, pour éviter qu'une boucle d'agent consomme le quota.
  4. Sur un grand dépôt, exclure les artefacts de build, les dépendances et les fichiers de secrets.
  5. Consulter régulièrement les rapports d'usage et ventiler les coûts par projet.
  6. Ne pas coller de clés de production, de données clients ou de journaux non pseudonymisés dans les prompts.

Questions fréquentes

Codex API et l'abonnement ChatGPT sont-ils la même chose ?

Non. L'abonnement ChatGPT concerne les produits web et client ; Codex CLI peut utiliser une connexion au compte ou une clé API facturée à l'usage. Les modes de facturation diffèrent et doivent être calculés séparément lors d'un achat d'équipe.

Codex CLI peut-il utiliser l'interface Chat Completions ?

Le fournisseur personnalisé de la version actuelle ne prend en charge que le protocole Responses ; wire_api = "chat" a été retiré. Un point de terminaison uniquement Chat Completions nécessite une couche de conversion.

Pourquoi config.toml ne prend-il pas effet ?

Vérifiez d'abord que vous modifiez ~/.codex/config.toml et non un fichier du projet ; que model_provider correspond au nom de [model_providers.xxx] ; puis rouvrez le terminal pour recharger les variables.

Faut-il saisir le nom d'affichage ou l'identifiant API comme nom de modèle ?

L'identifiant API. Le nom d'affichage ne sert qu'à l'interface et provoque généralement une erreur model not found. La référence exacte est la page Tarifs des modèles.

Une équipe peut-elle partager une seule clé ?

Ce n'est pas recommandé. Émettez des clés par personne, projet ou environnement : le diagnostic est plus simple et la révocation reste possible en cas de départ ou de fuite.

Pour aller plus loin

La difficulté de l'intégration Codex n'est pas l'installation, mais la correspondance de protocole : vérifiez d'abord que la passerelle prend en charge Responses, puis alignez URL de base, clé et modèle. Pour une entrée et une gestion d'usage unifiées, vous pouvez créer un compte ZSQH AI Gateway ; modèles et périmètre d'interface sont sur la page Tarifs des modèles.

Lectures associées :