PAA — Pourquoi Codex CLI ne trouve pas ma clé API OpenAI ?

Pourquoi Codex CLI ne trouve pas ma clé API OpenAI ? (Dépannage rapide)

Tu lances Codex CLI, tu tapes ta commande, tu te vois déjà en mode mage du terminal… et là, patatras, message du genre “API key not found”. Classique. La bonne nouvelle, c’est que 90% du temps ce n’est pas une “panne OpenAI” ni un bug mystique, c’est juste une clé au mauvais endroit, dans le mauvais shell, ou invisible pour le bon utilisateur.

Cette page est pensée comme un guide de terrain, actionnable, avec des commandes concrètes, des pièges par OS, et un tableau de symptômes. Objectif: faire apparaître où Codex CLI cherche la clé, pourquoi il ne la voit pas, puis te donner une méthode propre pour corriger sans Transformer-son-vieux-pc-en-machine-de-geek-usages-retro-et-open-source-qui-donnent-une-seconde-vie-a-votre-materiel/ »>Transformer ton poste en sapin de variables d’environnement.

Comprendre le fonctionnement de la clé API avec Codex CLI

Rôle de la clé API dans Codex CLI

Codex CLI doit s’authentifier auprès de l’API OpenAI pour envoyer des requêtes. La clé API sert de “badge d’accès” lié à ton compte et à tes droits. Sans elle, l’outil ne peut pas appeler l’API, donc il s’arrête très tôt, parfois avant même d’afficher un prompt utile.

Petit rappel sécurité: une clé API, c’est un secret. Elle ne doit pas finir dans un dépôt Git, un screenshot, un log partagé ou une commande copiée dans un ticket public. Si tu penses l’avoir exposée, rotation immédiate côté OpenAI.

comment-linux-peut-optimiser-la-consommation-de-votre-maison-en-2026/ »>comment Codex CLI recherche la clé API OpenAI

Dans la pratique, Codex CLI récupère la clé via ton environnement d’exécution. Le scénario le plus courant est la variable d’environnement OPENAI_API_KEY. Si elle n’existe pas dans le contexte du processus qui lance Codex CLI, l’outil te dira qu’elle est introuvable.

Le détail qui pique: “ton environnement” n’est pas un bloc unique. Il change selon le terminal, le shell, le profil utilisateur, la session, le mode admin, et parfois la manière dont l’appli a été installée. Un export fait dans un onglet ne s’applique pas forcément ailleurs. Un lancement depuis un IDE n’hérite pas toujours des mêmes variables que ton Terminal.

Vérifier l’emplacement de la variable OPENAI_API_KEY

Définir la clé API selon votre système d’exploitation (Windows, macOS, Linux)

Avant d’ajouter quoi que ce soit, commence par vérifier si la variable est déjà définie dans le shell qui pose problème. Les commandes ci-dessous servent à confirmer la présence (ou l’absence) de la variable, puis à la définir correctement.

macOS / Linux (bash, zsh)

• Vérifier dans le shell actuel: echo $OPENAI_API_KEY
• Définir pour la session en cours (temporaire): export OPENAI_API_KEY= »votre_cle »
• Rendre persistant (selon shell):

• zsh (fréquent sur macOS): ajoute dans ~/.zshrc une ligne export OPENAI_API_KEY= »votre_cle »
• bash: ajoute dans ~/.bashrc ou ~/.bash_profile selon ton système

Après modification, recharge le profil: source ~/.zshrc (ou le fichier correspondant), puis relance ton terminal si tu veux éviter les états bizarres.

Windows PowerShell

• Vérifier: echo $env:OPENAI_API_KEY
• Définir temporairement (session): $env:OPENAI_API_KEY= »votre_cle »
• Définir au niveau utilisateur (persistant): [Environment]::SetEnvironmentVariable(« OPENAI_API_KEY », »votre_cle », »User »)

Ferme puis rouvre PowerShell après un set persistant, sinon tu risques de vérifier une ancienne session.

Windows Command Prompt (cmd.exe)

• Vérifier: echo %OPENAI_API_KEY%
• Définir temporairement (session): set OPENAI_API_KEY=votre_cle
• Définir persistant (utilisateur): setx OPENAI_API_KEY « votre_cle »

Attention avec setx: il n’affecte pas la fenêtre courante, seulement les prochaines sessions.

Erreurs fréquentes de syntaxe ou d’emplacement

• Tu as défini la variable dans un shell, mais tu lances Codex CLI dans un autre (ex: export dans zsh, exécution dans un terminal intégré qui démarre en bash).
• Tu as mis la ligne dans le mauvais fichier de profil (ex: macOS zsh, mais tu modifies .bashrc).
• Tu as des guillemets “typographiques” copiés d’un doc (les guillemets courbes). Ton shell les digère mal.
• La variable existe, mais contient des espaces invisibles, un retour chariot, ou une copie partielle.
• Windows: confusion entre PowerShell et cmd, les syntaxes ne sont pas interchangeables.

Problèmes courants : pourquoi la clé API est introuvable ?

Problèmes de variable d’environnement

Le cas numéro 1, c’est la variable définie au mauvais endroit. Exemple typique: tu fais export OPENAI_API_KEY=… dans un onglet, puis tu lances Codex CLI depuis un raccourci, un autre terminal, ou un IDE. Résultat: la variable n’est pas héritée.

Autre cas vicieux: tu as bien une variable, mais tu l’as nommée différemment (faute de frappe, casse, préfixe). Codex CLI ne va pas “deviner”. Il cherche la variable attendue, point.

Conflits de configuration ou doublons

Tu peux te retrouver avec plusieurs définitions concurrentes. Sur macOS/Linux, une clé peut être exportée dans ~/.zshrc, puis surchargée dans ~/.zprofile, puis encore remplacée par un Gestionnaire de secrets, et au final tu ne sais même plus quelle valeur est active.

Sur Windows, certaines configurations se retrouvent en double entre variables “User” et “System”. Selon comment tu lances le terminal (et si tu lances en admin), tu peux lire une valeur différente de celle que tu croyais utiliser.

Permissions/Accès au système

Le piège “permission” arrive quand la variable est définie pour un utilisateur, mais Codex CLI est lancé sous un autre contexte:

• Lancement en administrateur sur Windows, alors que la variable est au niveau utilisateur standard.
• Exécution via un service, une tâche planifiée, ou un terminal distant, qui ne charge pas ton profil habituel.
• macOS/Linux: exécution via sudo, qui peut nettoyer l’environnement ou ne pas transmettre la variable.

Mon avis: évite de “résoudre” ça en mettant la clé en variable système globale si tu n’en as pas besoin. Tu augmentes la surface d’exposition. Mieux vaut comprendre quel contexte exécute réellement Codex CLI et y injecter la variable proprement.

Méthodes de dépannage : étape par étape

Vérifier si la clé API est active et valide

Deux choses différentes se mélangent souvent: clé introuvable, et clé refusée. Pour la détection, tu veux d’abord confirmer que la variable existe dans le même shell que celui qui lance Codex CLI.

• Étape 1: ouvre le terminal où tu exécutes Codex CLI.
• Étape 2: affiche la variable (commande selon ton shell, voir plus haut).
• Étape 3: si c’est vide, définis-la temporairement dans cette session, puis relance Codex CLI.

Si la clé est bien visible mais l’accès échoue, tu bascules dans un scénario “auth” (clé invalide, révoquée, droits, compte, organisation). Dans ce cas, va plutôt lire notre guide dédié à l’authentification: erreur authentification codex cli.

Commands Shell pour diagnostiquer la configuration

Objectif: savoir quel binaire tu exécutes, quel shell est actif, et si la variable est bien transmise au processus.

• macOS/Linux, afficher le shell: echo $SHELL
• macOS/Linux, vérifier le chemin de codex: which codex
• macOS/Linux, voir l’environnement d’un processus lancé à la volée:

• Lance Codex CLI en préfixant la variable, sans rien rendre persistant: OPENAI_API_KEY= »votre_cle » codex …

• PowerShell, vérifier la commande résolue: Get-Command codex
• PowerShell, vérifier la variable: Get-ChildItem Env:OPENAI_API_KEY

Ce test “préfixé” (ou assignation dans la session) est mon outil préféré: si ça marche comme ça, tu sais que Codex CLI fonctionne, et que ton problème est juste la persistance ou le profil chargé.

Tester l’accès à l’API hors Codex CLI

Quand tu veux séparer “variable introuvable” de “clé refusée”, un test minimal en dehors de Codex CLI aide beaucoup. Sans entrer dans des commandes trop spécifiques, l’idée est simple: utiliser un client HTTP (par exemple cURL) ou un petit script pour envoyer une requête authentifiée avec le header Bearer.

• Si ton test externe échoue avec une erreur d’authentification, la clé est probablement invalide, expirée, supprimée, ou sans les droits nécessaires.
• Si ton test externe fonctionne, mais Codex CLI échoue, tu es presque sûrement sur un souci d’environnement: variable non héritée, shell différent, exécution via un autre utilisateur, ou conflit de config.

Pour la méthode complète de setup des variables (avec explications sur les profils et les shells), tu peux passer par notre guide “variables d’environnement” dans le cocon, surtout si tu débutes et que tu ne veux pas bricoler à l’aveugle.

Cas pratiques et exemples d’erreur (messages d’erreur typiques)

Les messages exacts varient selon versions et wrappers, mais les symptômes se ressemblent. Voici une table pratique pour mapper “ce que tu vois” à “ce que tu dois vérifier”, sans jouer au loto dans tes fichiers de config.

Symptôme / message typique	Cause probable	Correctif rapide
API key not found / OPENAI_API_KEY is not set	Variable non définie dans le shell qui lance Codex CLI	Définir la variable dans la session, puis rendre persistant dans le bon profil
Ça marche dans un terminal, pas dans l’IDE	L’IDE ne charge pas ton profil shell, ou lance un shell différent	Définir la variable dans la config de l’IDE, ou lancer l’IDE depuis un terminal déjà configuré
Ça marche en PowerShell, pas en cmd (ou l’inverse)	Syntaxe différente, variable non créée dans l’autre shell	Définir la variable dans le shell réellement utilisé
Ça marche en utilisateur normal, pas en admin	Variable définie au niveau “User”, session admin ne la voit pas selon config	Éviter le mode admin, ou définir correctement l’environnement pour ce contexte
Variable visible, mais authentification refusée	Clé invalide/révoquée, mauvais compte, droits insuffisants	Vérifier la clé côté OpenAI, régénérer si besoin, puis lire le guide auth
La variable s’affiche, mais avec une valeur tronquée	Copie partielle, caractères cachés, mauvais guillemets	Retaper la clé proprement, éviter les guillemets typographiques

Et si Codex CLI te sort un message d’erreur plus général (du style “cannot authenticate” ou “authentication failed”), tu gagneras du temps en bifurquant vers: erreur authentification codex cli. Cette page-ci se concentre sur la détection de la clé, pas sur les raisons côté serveur.

Ressources et liens utiles

Pages liées du cocon sémantique (installation, variables d’environnement, erreur d’authentification, sécurité)

• erreurs codex cli, pour identifier rapidement si ton blocage vient d’une config, d’un réseau, d’un proxy, ou d’un souci d’exécution
• erreur authentification codex cli, si la clé est trouvée mais refusée

• Guide interne “Variables d’environnement” (mise en place propre sur chaque OS, profils shell, persistance)
• Guide interne “Sécuriser sa clé API” (rotation, secrets managers, éviter les fuites dans Git)
• Guide interne “Installation Codex CLI par plateforme” (quand le problème est en réalité un binaire lancé différent de celui que tu crois)

Documentation officielle OpenAI et Codex CLI

• Documentation OpenAI sur l’authentification et la gestion des clés API
• Documentation officielle de Codex CLI sur la configuration via variables d’environnement

En février 2026, les workflows “CLI + variables d’environnement + rotation régulière” restent la norme côté dev, même si les gestionnaires de secrets et l’intégration dans les CI/CD sont devenus plus courants. Les bases n’ont pas changé: si l’environnement ne contient pas la variable attendue, l’outil ne peut rien faire.

FAQ : Questions associées sur la clé API et le Codex CLI

Comment déclarer correctement OPENAI_API_KEY pour Codex CLI ?

La méthode dépend du shell. Sur macOS/Linux, le plus simple est de l’exporter dans le fichier de profil du shell utilisé (souvent ~/.zshrc sur macOS) et de recharger le profil. Sur Windows, définis-la dans PowerShell via une variable d’environnement utilisateur persistante, puis rouvre le terminal.

Le point à surveiller: définir la variable dans le contexte qui lance réellement Codex CLI, pas “quelque part sur la machine”.

Pourquoi ma clé API fonctionne-t-elle via Python/cURL mais pas avec Codex CLI ?

Python ou cURL peuvent lire la clé depuis un autre mécanisme: un fichier .env chargé par ton projet, une variable définie dans l’IDE, ou une session de terminal différente. Codex CLI, lui, dépend de l’environnement du processus qui le lance.

Un test simple: dans le même terminal que Codex CLI, affiche OPENAI_API_KEY. Si c’est vide, tu as trouvé le coupable. Si ce n’est pas vide, regarde ensuite les conflits de config et le contexte utilisateur.

Quels sont les messages d’erreur spécifiques à une clé API non trouvée dans Codex CLI ?

Le vocabulaire varie, mais les formulations tournent autour de “key not found”, “environment variable not set”, “missing API key”, parfois en mentionnant explicitement OPENAI_API_KEY. Quand le message parle plutôt d’authentification refusée, on est déjà dans une autre catégorie de problème.

Comment diagnostiquer un problème de permission ou de profil utilisateur avec Codex CLI et la clé API ?

Commence par vérifier quel utilisateur exécute la commande et comment Codex CLI est lancé. Sur Windows, test classique: compare une session PowerShell normale et une session “Run as administrator”, puis affiche la variable dans chaque contexte. Sur macOS/Linux, méfie-toi de sudo, qui peut modifier l’environnement transmis.

La stratégie la plus propre consiste à éviter les exécutions en admin si elles ne sont pas nécessaires, et à définir la variable au bon niveau (souvent utilisateur) plutôt que de la propager partout.

Si tu veux, colle le message exact que tu obtiens (sans ta clé, évidemment), ton OS et le terminal utilisé (PowerShell, cmd, bash, zsh), et je te dirai quelle piste est la plus crédible, profil chargé, contexte utilisateur, ou conflit de configuration ?