Codex CLI est l'agent de programmation en terminal d'OpenAI : il lit le code, modifie des fichiers et exécute des commandes. Beaucoup d'équipes souhaitent le brancher sur une passerelle auto-hébergée ou un point d'entrée tiers compatible OpenAI, afin d'unifier clés, facturation et gestion des quotas. « Connecter une API personnalisée » se résume en configuration à trois points : où envoyer la requête (URL de base), avec quelle identité s'authentifier (clé) et quel modèle appeler (nom du modèle). Ce qui pose réellement problème, ce sont le mode d'authentification, la correspondance des protocoles et les frontières de permissions.

Cet article suit les versions courantes d'octobre 2026, dans l'ordre installation, authentification, configuration, vérification, sandbox et approbations, déploiement d'équipe et sécurité. Codex évolue vite : les commandes et options de configuration font foi selon codex --help et la documentation de l'éditeur.

Remarque : OpenAI, Codex et ChatGPT sont des marques ou marques déposées d'OpenAI. Cet article est purement technique, sans lien d'affiliation avec OpenAI. Les exigences d'interface, les identifiants de modèles et les modes de facturation peuvent évoluer avec les versions ; référez-vous à la documentation de l'éditeur et à la page tarifs des modèles du site.

1. Vérifier d'abord le protocole et l'authentification

Le provider personnalisé de Codex CLI utilise le protocole Responses ; wire_api n'accepte actuellement que responses. L'ancienne valeur chat est abandonnée et provoque directement une erreur dans plusieurs versions. La passerelle doit au minimum remplir deux conditions : exposer un point d'entrée /v1/responses compatible ; prendre en charge la sortie en flux et renvoyer l'événement de terminaison response.completed. Une passerelle qui ne propose que Chat Completions nécessite une couche de conversion de protocole ; on ne peut pas simplement y inscrire son adresse.

Trois voies d'authentification existent, choisissez-en une :

Mode Commande ou configuration typique Cas adapté Remarques
Connexion au compte ChatGPT codex login Essai personnel, usage temporaire Consomme le quota du compte, inadapté à la CI
Connexion par clé API codex login --with-api-key (clé lue sur stdin) Usage personnel à la consommation L'identifiant est stocké dans auth.json ou le trousseau système
Provider personnalisé env_key pointant vers une variable d'environnement Passerelle d'équipe, facturation unifiée Clé hors du TOML, quotas et révocation facilités

Utilisez codex login status pour voir l'état de connexion courant et codex logout pour effacer les identifiants locaux. Si plusieurs identifiants coexistent, déterminez d'abord lequel est réellement actif avant de diagnostiquer la configuration.

2. Installer Codex CLI

Choisissez une méthode selon le système, puis vérifiez la version :

# Script d'installation pour macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Gestionnaires de paquets possibles, selon la documentation actuelle de l'éditeur
npm install -g @openai/codex
brew install --cask codex

codex --version

Pour le premier lancement, préférez un dépôt de test vide ; n'expérimentez pas directement dans un répertoire contenant des clés de production, des données clients ou une configuration non anonymisée. Codex lit le contexte du répertoire courant : plus il est propre, plus le diagnostic est simple.

3. Configurer l'URL de base, la clé et le modèle

La configuration utilisateur se trouve dans ~/.codex/config.toml, ou %USERPROFILE%\.codex\config.toml sous Windows. Un piège fréquent : les clés de premier niveau doivent précéder le premier en-tête de table ; si model et model_provider sont placés après [model_providers.xxx], ils deviennent des champs de cette table et la configuration semble « ne pas s'appliquer ».

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"
web_search = "disabled"

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

Signification des champs :

  • model : l'identifiant API, pas le nom affiché sur le site ; il doit correspondre exactement à la page de tarifs du site.
  • model_provider : identique à l'ID du provider ci-dessous ; n'utilisez pas les noms réservés openai, ollama ou lmstudio.
  • base_url : inclut le chemin API, généralement terminé par /v1, sans concaténation supplémentaire.
  • wire_api : responses.
  • env_key : le nom de la variable d'environnement, pas la clé elle-même.
  • web_search : mettez disabled si la passerelle ne prend pas en charge la recherche web, pour éviter d'appeler une capacité non ouverte.

Exportez ensuite la clé dans le même shell que celui qui lance Codex :

export ZSQH_API_KEY="sk-votre-cle"

Sous Windows PowerShell : $env:ZSQH_API_KEY="sk-votre-cle". Pour une persistance durable, écrivez la variable dans la configuration du shell ou dans les variables système, et vérifiez que les éditeurs lancés depuis l'interface graphique la lisent aussi.

Si la passerelle exige un en-tête personnalisé, utilisez env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" } ; ce mode ne passe pas par la découverte de catalogue distante et requiert un catalogue local model_catalog_json. Si la clé est émise dynamiquement par un gestionnaire de secrets, command dans [model_providers.zsqh.auth] peut récupérer un jeton auprès d'un programme externe, mais reste incompatible avec env_key. En présence de nombreux alias de modèles, envisagez model_catalog_url ou model_catalog_json ; sans ce besoin, n'ajoutez pas de complexité.

À retenir également : un projet de confiance charge .codex/config.toml, mais les définitions model_provider, model_providers et profile y sont ignorées. Le provider doit impérativement être défini dans la configuration utilisateur.

4. Vérifier que la connexion fonctionne réellement

Procédez dans l'ordre pour distinguer rapidement « outil mal configuré » et « passerelle non joignable » :

  1. Exécutez codex login status pour confirmer le mode d'authentification, puis vérifiez que la variable pointée par env_key est non vide dans l'environnement de lancement. N'affichez pas la clé complète dans un terminal partagé.
  2. Exécutez codex doctor pour contrôler l'emplacement du fichier de configuration, les variables d'environnement et les conflits courants.
  3. Dans le dépôt de test, exécutez codex exec "Reply with exactly: gateway-ok" ; si gateway-ok revient, la chaîne de base fonctionne. codex exec utilise par défaut un sandbox en lecture seule, adapté au test de fumée.
  4. En mode interactif, exécutez /status pour vérifier que le modèle et le provider actuels correspondent à votre configuration.
  5. Consultez les journaux de requêtes de la console de la passerelle : utilisateur, alias de modèle et routage amont. Une réponse côté client ne suffit pas ; elle peut venir du cache ou d'une ancienne configuration.
  6. En cas d'échec persistant, vérifiez le /v1 et le chemin /responses de l'URL de base, puis si un proxy réécrit ou supprime l'en-tête Authorization.

5. Sandbox et approbations : deux interrupteurs distincts

Beaucoup confondent « exécution automatique » et « quels fichiers peuvent être modifiés ». Codex les sépare : la politique d'approbation décide quand le processus s'arrête pour vous demander, le sandbox décide quels fichiers et réseaux le processus peut toucher.

Dans la version actuelle, approval_policy prend couramment on-request, adapté au développement quotidien ; never n'est conseillé que dans un environnement automatisé isolé. L'ancienne valeur untrusted n'est plus prise en charge et on-failure est abandonnée : copier un ancien tutoriel provoque souvent une erreur de configuration.

sandbox_mode accepte trois valeurs : read-only, workspace-write et danger-full-access. Commencez par le lecture seule ; pour modifier du code, utilisez workspace-write en limitant les répertoires inscriptibles via sandbox_workspace_write.writable_roots ; danger-full-access ne doit apparaître que dans un conteneur ou un runner jetable. Pour l'accès réseau, activez séparément sandbox_workspace_write.network_access plutôt que d'élargir toutes les permissions.

En mode non interactif, codex exec --sandbox workspace-write fixe le sandbox ; si l'organisation permet la revue automatique, ajoutez --approve-for-me. Notez que --full-auto n'est plus pris en charge : les anciens scripts doivent être adaptés. En mode interactif, /permissions permet de consulter et d'ajuster les permissions courantes.

6. Déploiement d'équipe : commencer petit, puis uniformiser

Commencez par deux ou trois personnes sur un dépôt non critique, puis généralisez après validation. L'enjeu n'est pas le nombre d'installations, mais la reproductibilité de la configuration et la capacité à localiser les pannes.

  • Une clé par personne, éventuellement scindée par projet ou environnement ; pas de clé commune à toute l'équipe.
  • Côté passerelle, fixez budget, concurrence et liste blanche de modèles pour éviter qu'une boucle d'Agent consomme tout le quota.
  • Uniformisez approval_policy, sandbox_mode et cli_auth_credentials_store via une configuration d'entreprise ; requirements.toml peut interdire les combinaisons à risque comme never et danger-full-access.
  • Pour imposer un mode de connexion, utilisez forced_login_method = "chatgpt" ou "api", afin d'éviter le mélange d'identifiants entre membres.
  • Tenez un modèle de configuration sans secret, précisant l'URL de base, l'identifiant de modèle et les commandes de diagnostic.
  • Vérifiez chaque mois l'usage de la passerelle selon trois axes : personne, projet et modèle.

7. Liste de sécurité

  • La clé reste dans les variables d'environnement, le trousseau système ou un service de gestion de secrets ; jamais dans config.toml ni dans Git. experimental_bearer_token existe dans la configuration, mais n'est pas recommandé par l'éditeur.
  • Codex utilise une clé dédiée, facilitant quota, expiration et révocation séparée.
  • Sandbox en lecture seule par défaut ; pour écrire, limitez au répertoire du dépôt concerné et retirez la permission à la fin de la tâche.
  • Ne placez pas .env, auth.json, la configuration de production ou des données clients dans le contexte ; excluez les artefacts de build et les dépendances des grands dépôts.
  • Relisez les commandes et correctifs générés par Codex, en particulier les suppressions, requêtes réseau et élévations de privilèges.
  • Figez la version de Codex dans l'image d'équipe et validez la compatibilité de la configuration en environnement de test avant mise à jour.
  • Activez les alertes d'usage de la passerelle : en cas d'appel anormal, coupez d'abord la clé, puis consultez les journaux.

Questions fréquentes

Codex CLI impose-t-il le protocole Responses ?

Le wire_api du provider personnalisé n'accepte actuellement que responses, et l'ancienne valeur chat est abandonnée. Si la passerelle ne propose que Chat Completions, il faut une couche de conversion de protocole ou un point d'entrée compatible Responses.

La configuration est écrite, pourquoi les requêtes passent-elles par l'adresse par défaut ?

Vérifiez d'abord que vous modifiez bien ~/.codex/config.toml, puis que les clés de premier niveau précèdent les en-têtes de table et que model_provider correspond exactement à l'ID du provider. Les définitions de provider dans la configuration de projet sont ignorées : c'est une cause fréquente.

Peut-on écrire la clé directement dans config.toml ?

Ce n'est pas recommandé. Utilisez env_key pour référencer une variable d'environnement, ou [model_providers.xxx.auth] pour appeler une commande externe. Une clé en clair fuit facilement via les sauvegardes, captures ou dépôts.

La connexion ChatGPT et la clé API ont-elles la même facturation ?

Non. La connexion ChatGPT relève du compte, la clé API est facturée à l'usage. Quotas, factures et permissions diffèrent : une équipe doit les suivre séparément.

Une équipe peut-elle partager une clé ?

Ce n'est pas conseillé. Une clé partagée ne permet pas d'identifier l'appelant ni de la révoquer individuellement en cas de fuite ou de départ. Des clés par personne et par environnement, avec quotas et expiration, sont plus contrôlables.

Pour aller plus loin

La difficulté de l'intégration Codex n'est pas l'installation, mais la correspondance des protocoles et les frontières de permissions : vérifiez que la passerelle prend en charge Responses et l'événement de fin de flux, configurez l'URL de base, la clé et le modèle, puis faites un test de fumée en sandbox lecture seule. Pour un point d'entrée et une gestion d'usage unifiés, vous pouvez créer un compte ZSQH AI Gateway ; le périmètre des modèles et des interfaces est indiqué sur la page tarifs des modèles.

Lectures associées :