La clé API de Codex n'est pas une simple chaîne de caractères. Elle détermine l'identité sous laquelle les requêtes sont facturées, les modèles accessibles et l'impact d'une fuite. Les 401 rencontrés ne viennent souvent pas d'une clé invalide, mais d'un nom de variable incohérent, d'un en-tête réécrit, d'un mauvais niveau de configuration ou d'un identifiant local obsolète.

Cet article suit l'ordre « types de clés, création, variables d'environnement et fichier de configuration, profils, rotation, moindre privilège, CI, diagnostic 401 » et fournit une méthode directement applicable. Les commandes et options font foi selon la version actuelle de Codex et la documentation de la passerelle utilisée.

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 permissions de clé, le périmètre d'interface et la facturation font foi selon la documentation de chaque plateforme et les pages du site.

1. Distinguer trois types de clés et deux mécanismes de stockage

Les identifiants liés à Codex prêtent à confusion ; séparez-les d'abord par usage :

Nom Usage typique Emplacement Remarques
Clé API OpenAI Platform Connexion via codex login --with-api-key auth.json ou trousseau système Facturation au tarif standard de l'interface
CODEX_API_KEY codex exec, SDK, exécution ponctuelle Environnement du processus uniquement Non persisté, adapté à la CI
Clé de provider personnalisé Variable pointée par env_key Environnement shell ou gestionnaire de secrets Courant pour une passerelle d'équipe, quotas facilités

Le premier mécanisme est celui des « identifiants de connexion », contrôlé par cli_auth_credentials_store : file écrit auth.json sous CODEX_HOME, keyring utilise le trousseau système, auto tente le trousseau puis revient au fichier, ephemeral garde tout en mémoire du processus. Le second est celui de la « clé de provider », dont env_key désigne le nom de variable, lue à chaque requête. Attention : env_key est un nom de variable, pas la variable elle-même.

CODEX_HOME vaut ~/.codex par défaut et peut être déplacé vers un répertoire contrôlé. OPENAI_API_KEY est la variable lue par la commande de connexion ; CODEX_API_KEY est l'identifiant ponctuel des exécutions non interactives. Les noms se ressemblent, les usages diffèrent.

2. Créer une clé en cinq étapes

  1. Ouvrez ZSQH AI Gateway ou la plateforme utilisée, créez un compte et connectez-vous à la console.
  2. Dans la page « Clés API », créez une clé dont le nom précise l'environnement et l'usage, par exemple codex-work-mac.
  3. Fixez plafond et expiration. Donnez d'abord un quota faible à une clé de test, puis ajustez après avoir observé la consommation réelle.
  4. Si la plateforme permet une liste blanche de modèles ou un périmètre par projet, ne cochez que les modèles nécessaires à Codex.
  5. Copiez la clé complète et stockez-la immédiatement dans un gestionnaire de mots de passe ou de secrets. La plupart des consoles ne l'affichent qu'une fois.

La clé commence souvent par sk-, mais ce préfixe ne prouve ni son authenticité ni ses permissions. À la copie, surveillez espaces, sauts de ligne et guillemets superflus : c'est une cause fréquente de 401. Après création, validez avec une requête minimale avant de distribuer aux membres.

3. Faire coopérer variables d'environnement et config.toml

La pratique recommandée : le fichier de configuration ne contient que le nom de variable, la clé réelle reste dans l'environnement ou un gestionnaire de secrets. Exemple de ~/.codex/config.toml :

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

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_API_KEY"
env_key_instructions = "Créer une clé dans la console de la passerelle puis l'exporter en variable d'environnement"

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

export ZSQH_API_KEY="sk-votre-cle"

Sous macOS et Linux, placez cette ligne dans un fichier privé comme ~/.zshrc.local, le fichier principal se contentant de référencer la variable. Sous Windows PowerShell : $env:ZSQH_API_KEY="sk-votre-cle". Les processus lancés depuis le Dock, un IDE ou une application de bureau peuvent ne pas hériter des variables du shell ; injectez-les alors dans le script de lancement ou les variables système.

Si la passerelle exige un en-tête personnalisé, remplacez env_key par env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" } et configurez le catalogue local de modèles. Si la clé est émise dynamiquement par Vault, KMS ou équivalent, command dans [model_providers.zsqh.auth] peut récupérer un jeton, mais reste incompatible avec env_key. experimental_bearer_token accepte une clé en clair, mais n'est pas recommandé par l'éditeur : évitez-le en équipe.

Un particulier peut aussi passer par la connexion : printenv OPENAI_API_KEY | codex login --with-api-key, l'identifiant allant dans auth.json ou le trousseau ; codex logout l'efface. Pour une passerelle d'équipe, env_key reste préférable : quotas, permissions de modèles et révocation se gèrent au même endroit.

4. Configurations multiples et profils

Prévoyez au moins trois jeux d'identifiants : quotidien personnel, projet dédié, automatisation. Leurs quotas, permissions et cycles de rotation diffèrent ; les mélanger rend usage et pannes difficiles à localiser.

Les versions récentes de Codex séparent les profils dans des fichiers dédiés. Définissez deux providers dans la configuration principale, lisant chacun une variable différente :

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh_work"

[model_providers.zsqh_work]
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_WORK_KEY"

[model_providers.zsqh_test]
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_TEST_KEY"

Créez ensuite ~/.codex/test.config.toml avec seulement les clés de premier niveau à remplacer :

model = "your-test-model-id"
model_provider = "zsqh_test"

Lancez codex --profile test pour basculer. Attention : depuis 0.134.0, l'ancienne table [profiles.xxx] et la clé de premier niveau profile = "..." ne sont plus lues ; n'imbriquez pas non plus [profiles.xxx] dans le fichier de profil, utilisez directement les clés de premier niveau. Les anciennes versions peuvent encore accepter l'ancien format ; lisez les notes de version avant de mettre à jour.

Le .codex/config.toml d'un projet de confiance ne doit contenir que des conventions non sensibles ; ses model_provider, model_providers et profils sont ignorés, et aucune clé ne doit y être validée.

5. Rotation des clés : quand et comment

La rotation ne sert pas à remplir une procédure, mais à réduire la fenêtre d'exposition après une fuite. Départ d'un employé, perte d'appareil, suspicion de fuite, exigence d'un fournisseur et périodicité fixe (par exemple tous les 90 jours) justifient une rotation.

  1. Créez une nouvelle clé dans la console, avec la date dans le nom, par exemple codex-prod-2026-10.
  2. Écrivez d'abord la nouvelle clé dans le gestionnaire de secrets ou l'environnement, en conservant provisoirement l'ancienne.
  3. Validez avec codex exec et une requête minimale : modèle, quota et permissions doivent être normaux.
  4. Observez les journaux d'usage de l'ancienne clé pour vérifier qu'aucun script ni membre ne l'utilise encore.
  5. Désactivez l'ancienne clé, puis surveillez un à deux jours le taux d'erreur et les requêtes en échec.
  6. Notez la date de rotation, le responsable et le périmètre affecté, pour la passation et l'audit.

N'effectuez pas de rotation en pleine pointe de production. Faire coexister deux clés un temps est plus sûr que « supprimer puis recréer ». En mode connexion seule, exécutez codex logout puis reconnectez-vous après rotation, pour éviter un ancien identifiant résiduel dans auth.json. auth.json doit être protégé comme un mot de passe et ne jamais être synchronisé vers un cloud public ou un dépôt.

6. Moindre privilège et prévention des fuites

  • Une clé par personne, puis par environnement ; une clé dédiée à la CI, avec un quota séparé.
  • Définissez expiration, budget et limite de concurrence ; n'ouvrez que les modèles nécessaires.
  • Si la plateforme gère une liste blanche IP, limitez au réseau du bureau ou à la sortie du runner ; sinon, comptez sur quotas et alertes.
  • En entreprise, forced_login_method = "api" ou "chatgpt" impose un mode de connexion unique et évite le mélange d'identifiants.
  • Sur une machine personnelle, préférez cli_auth_credentials_store = "keyring" ; sur une machine partagée ou en CI, utilisez ephemeral pour limiter l'écriture disque.
  • .gitignore doit couvrir .env, .env.*, auth.json, *.pem, etc. ; avant validation, utilisez un scan de secrets ou un hook pre-commit pour détecter le motif sk-.
  • N'écrivez pas de clé par défaut dans le code, ne déboguez pas avec echo $ZSQH_API_KEY, et masquez l'en-tête Authorization dans les journaux.

En cas de fuite confirmée, l'ordre est : désactiver ou supprimer la clé, créer une nouvelle clé, puis examiner journaux d'usage et historique du dépôt. Supprimer un fichier ne suffit pas : l'ancienne clé a peut-être déjà été copiée ailleurs.

7. CI et usage non interactif

Le principe en CI : « la clé n'entre ni dans le code, ni dans l'image, ni dans les journaux ».

  • Pour une exécution ponctuelle : CODEX_API_KEY=<key> codex exec --json "...", injectée devant la commande uniquement, pas en variable d'environnement de job.
  • GitHub Actions : privilégiez l'Action Codex de l'éditeur plutôt que d'insérer la clé dans une étape shell.
  • La CI utilise une clé dédiée, à faible quota et permissions étroites, disponible seulement sur les branches protégées ou les workflows de confiance.
  • Utilisez --ephemeral pour éviter l'écriture de fichiers de session ; hors dépôt Git, ajoutez --skip-git-repo-check si nécessaire.
  • N'utilisez pas d'identifiants ChatGPT hébergés sur un dépôt public ou un runner non fiable.

8. Diagnostic 401 : dans cet ordre

Un 401 signale un échec d'authentification, pas nécessairement une clé erronée. Procédez dans l'ordre :

  1. Exécutez codex login status pour confirmer le mode d'authentification réellement actif.
  2. Vérifiez que le nom pointé par env_key est exactement orthographié et non vide dans le processus courant ; contrôlez la longueur sans afficher la valeur.
  3. Vérifiez depuis quel environnement Codex est lancé. Le terminal intégré d'un IDE, Docker, systemd ou launchd peuvent ne pas hériter des variables du shell.
  4. Recopiez la clé depuis la console pour écarter espaces, sauts de ligne et guillemets.
  5. En mode identifiants de connexion, exécutez codex logout puis reconnectez-vous, pour écarter un résidu dans auth.json.
  6. Vérifiez que forced_login_method n'entre pas en conflit avec le type d'identifiant courant ; en cas d'incompatibilité, Codex peut quitter ou refuser la requête.
  7. Vérifiez que la clé n'est pas expirée, désactivée, sans solde, ou sans permission sur ce modèle.
  8. Confirmez l'URL de base et le chemin /v1, et que le proxy ne supprime ni ne réécrit Authorization ; au besoin, recoupez avec les journaux de la passerelle.

Tableau des erreurs courantes :

Symptôme Cause fréquente Traitement
401 Unauthorized Variable non exportée, nom incohérent, identifiant expiré Vérifier env_key ; rouvrir le terminal ; se reconnecter
403 Forbidden Pas de permission modèle, restriction IP, quota gelé Vérifier permissions et liste blanche dans la console
404 Not Found /v1 en trop ou manquant dans l'URL de base, chemin incorrect Vérifier l'adresse et le périmètre d'interface segment par segment
429 Too Many Requests Concurrence ou quota dépassés Réduire la concurrence, vérifier le quota de la clé
model not found Identifiant de modèle erroné Copier l'identifiant exact depuis la page de tarifs

Questions fréquentes

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

Non. L'abonnement ChatGPT concerne les produits web et clients ; Codex peut utiliser la connexion au compte ou une clé API facturée à l'usage. Quotas, factures et permissions diffèrent : une équipe doit les suivre séparément.

Quel rapport entre env_key et OPENAI_API_KEY ?

env_key est une option de configuration dont la valeur est un nom de variable ; OPENAI_API_KEY est l'un des noms courants, également lu par codex login --with-api-key. Vous pouvez définir env_key = "OPENAI_API_KEY", mais mieux vaut un nom dédié à la passerelle pour éviter le mélange avec les identifiants de connexion.

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

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

Faut-il arrêter le service pour renouveler une clé ?

Non. Créez et validez la nouvelle clé, basculez la configuration, puis désactivez l'ancienne ; faire coexister les deux un temps évite les interruptions.

Pourquoi codex login status est-il normal alors que les requêtes renvoient 401 ?

Un état de connexion normal indique seulement que des identifiants locaux existent, pas que la clé du provider personnalisé fonctionne. Vérifiez la variable env_key, l'URL de base, le solde de la passerelle et les permissions du modèle ; si un proxy intervient, vérifiez aussi la réécriture des en-têtes.

Pour aller plus loin

Si vous n'avez pas encore de clé, créez-en une à faible quota depuis la page d'inscription, puis configurez et validez dans l'ordre de cet article. Modèles, quotas et facturation figurent sur la page tarifs des modèles ; les prix évoluent avec les versions de modèles et les politiques amont, les informations en temps réel de la page font foi.

Lectures associées :