Définir OPENAI_API_KEY pour Codex CLI : variables d’environnement sur Windows, macOS et Linux

Introduction

Codex CLI, c’est un peu le compagnon de party pour ton terminal, il ne parle pas beaucoup, mais quand il parle, il code. Sauf qu’avant de lui confier ta base de code, il lui faut un sésame : ta clé API OpenAI, exposée au bon endroit via la variable d’environnement OPENAI_API_KEY. En février 2026, la plupart des soucis que je vois passer ne viennent pas de la clé elle-même, mais du “où” et du “comment-securiser-sa-maison-en-2026-guide-legal-diy/ »>comment” on la déclare, surtout quand on jongle entre PowerShell, un terminal intégré d’IDE, WSL, SSH, ou une CI.

Objectif de cette page leaf : te donner une méthode propre, reproductible et raisonnablement sécurisée pour définir OPENAI_API_KEY sur Windows, macOS et Linux, puis te débloquer quand Codex CLI fait comme s’il ne voyait rien. Mot clé du jour, et on va le mériter : codex cli openai variable d environnement OPENAI_API_KEY.

Pourquoi définir OPENAI_API_KEY pour Codex CLI ?

Codex CLI n’a pas de pouvoirs mystiques. Pour appeler l’API, il doit s’authentifier. La voie la plus simple, c’est une variable d’environnement nommée OPENAI_API_KEY. L’outil la lit au lancement, l’utilise pour signer les requêtes, puis c’est parti.

• Sans OPENAI_API_KEY, Codex CLI ne peut pas s’authentifier, ou bascule vers un autre mécanisme si tu en as configuré un (selon ton setup).
• Une variable d’environnement évite d’écrire la clé en dur dans un fichier de code, ce qui finit tôt ou tard sur Git, dans un zip, ou dans un copier-coller malheureux.
• Tu peux gérer des contextes différents : perso, boulot, sandbox, CI, en changeant l’environnement plutôt que le code.

Si tu pars de zéro avec l’outil, garde sous le coude le guide codex cli openai debutant, il remet tout à plat, install, premiers prompts, ergonomie terminal.

Comprendre les variables d’environnement : bases et enjeux de sécurité

Une variable d’environnement, c’est une paire clé-valeur attachée à un processus. Ton shell (PowerShell, bash, zsh) en transmet une partie aux programmes qu’il lance. L’idée clé : si tu changes une variable dans un terminal, ça ne modifie pas magiquement tous les terminaux déjà ouverts, ni forcément le système entier.

• Temporaire : valable pour la session en cours (le terminal actuel) et les programmes lancés depuis celle-ci.
• Persistant : écrit dans un endroit que ton OS ou ton shell recharge au prochain lancement.
• Portée : utilisateur (toi), système (tous les comptes), session (juste ce terminal), pipeline CI (juste ce job).

Côté sécurité, une API key en variable d’environnement, c’est bien, mais pas magique. Elle peut fuiter via :

• l’historique du shell si tu la tapes en clair dans une commande enregistrée,
• des logs d’outils qui dumpent l’environnement,
• un process listing ou un rapport de debug trop bavard,
• des scripts partagés dans une équipe.

La bonne approche : limiter la portée, éviter l’historique, et préférer un stockage secret quand tu passes en environnement partagé.

Définir OPENAI_API_KEY sur Windows

Windows est le royaume des “ça dépend du terminal”. Entre PowerShell, CMD, Windows Terminal, et parfois WSL, on peut se tirer une balle dans le pied sans s’en rendre compte. Voilà deux méthodes solides.

Méthode 1 : Variable d’environnement système

Cette méthode rend la variable persistante. Pratique si tu veux que Codex CLI la voie peu importe le terminal, tant que tu es dans Windows (pas WSL).

• Ouvre le menu Démarrer et cherche “variables d’environnement”.
• Choisis “Modifier les variables d’environnement système”.
• Dans “Variables d’environnement…”, crée une variable OPENAI_API_KEY.
• Décide si tu la mets en “Variables utilisateur” (recommandé sur un PC perso) ou “Variables système” (plus large, donc plus risqué).
• Colle la clé, valide, puis ferme.

Point qui surprend : les terminaux déjà ouverts ne verront pas la nouvelle variable. Ferme et rouvre ton terminal, ou redémarre ta session.

Méthode 2 : Fichier .env ou via Powershell/CMD

Si tu veux une portée courte, par projet, ou éviter de polluer l’environnement global, tu as deux approches.

Option A, temporaire dans PowerShell (valable pour la session) :

• Dans PowerShell, définis la variable au niveau du processus en cours.
• Lance Codex CLI depuis ce même terminal.

Attention à l’historique : si tu tapes la clé en clair, elle risque d’être enregistrée. Dans un contexte sensible, préfère copier-coller avec l’historique désactivé, ou utilise un Gestionnaire de secrets (voir plus bas).

Option B, fichier .env (par dossier) :

• Crée un fichier nommé .env à la racine du projet.
• Ajoute une ligne du style OPENAI_API_KEY=….
• Ajoute .env au .gitignore pour ne jamais le committer.

Important : Codex CLI ne charge pas forcément les fichiers .env tout seul selon la façon dont tu l’exécutes. La logique générale, c’est : soit ton outil lit .env, soit tu le “sources” via un wrapper, soit ton IDE le charge. Si tu veux un guide global, va lire configurer codex cli openai api key, il couvre les pièges de configuration plus larges.

Vérifier la disponibilité de la variable sous Windows

Avant d’accuser Codex CLI, vérifie que Windows ou ton shell voit la variable.

• Dans PowerShell, affiche la variable d’environnement et confirme qu’elle est non vide.
• Dans CMD, utilise la commande de lecture des variables.
• Relance le terminal si tu viens de créer la variable via l’interface Windows.

Si tu utilises WSL : Windows et WSL ne partagent pas automatiquement les variables. Dans WSL, il faudra la définir côté Linux (section Linux ci-dessous).

Définir OPENAI_API_KEY sur macOS

Sur macOS, le point clé, c’est ton shell. Depuis quelques années, zsh est souvent le défaut, mais bash existe encore, et les terminaux intégrés d’IDE ont parfois leurs propres subtilités.

Méthode 1 : Export temporaire dans le terminal

Parfait pour tester, ou pour un “one shot” où tu ne veux pas laisser la clé traîner partout.

• Ouvre ton terminal.
• Définis la variable dans la session en cours (export).
• Lance Codex CLI dans ce même terminal.

Ce que j’aime avec cette méthode : tu peux avoir une clé “sandbox” pour un repo, puis fermer le terminal, et pouf, plus rien. Le revers : tu vas le refaire souvent.

Méthode 2 : Export permanent dans .bash_profile, .zshrc, etc.

Pour une config persistante, tu ajoutes l’export dans le fichier de config de ton shell.

• Si tu es en zsh : ~/.zshrc est l’endroit classique.
• Si tu es en bash : ~/.bash_profile ou ~/.bashrc selon ton setup.
• Ajoute une ligne d’export de OPENAI_API_KEY.
• Recharge la config (nouveau terminal, ou rechargement du fichier), puis vérifie que la variable est visible.

Mon avis de nerd pragmatique : écrire une clé en clair dans un fichier de dotfiles, c’est correct sur une machine perso chiffrée avec un compte bien protégé. Sur un Mac partagé, un poste d’entreprise supervisé, ou une machine où tes dotfiles partent sur GitHub, je passe en mode “secrets” plutôt que “rc files”.

Astuce : utiliser un gestionnaire de secrets ou .env

Deux pistes populaires :

• Gestionnaire de secrets : tu stockes la clé dans un coffre, puis tu l’injectes au moment d’exécuter Codex CLI. C’est plus clean pour éviter le bazar dans les fichiers de shell.
• .env : pratique par projet, surtout si tu as plusieurs clés selon les environnements. Mais il faut une discipline de fer : .gitignore, pas de partage, pas de zip envoyé sur Slack avec le fichier dedans.

Définir OPENAI_API_KEY sur Linux

Linux ressemble beaucoup à macOS sur la logique “export dans le shell”, mais il y a un monde entre un laptop de dev et un serveur multi-utilisateurs. Sur serveur, le mot clé, c’est séparation des responsabilités.

Méthodes similaires à macOS : export et fichiers de configuration

• Export temporaire dans le shell pour une session.
• Ajout dans ~/.bashrc, ~/.profile, ~/.zshrc, selon ton shell.
• Vérification avec une commande simple qui affiche la variable.

Piège fréquent : tu ajoutes la variable dans un fichier qui n’est pas chargé par ton type de session. Exemple classique : une session non interactive n’exécute pas forcément les mêmes fichiers qu’un shell interactif. Dans ce cas, tu crois l’avoir définie, mais Codex CLI lancé par un script ne la voit jamais.

Gestion sécurisée sur serveurs et CI

Sur serveur ou en CI, je déconseille de “hardcoder” la clé dans un fichier de profil global. Préfère :

• Variables de secrets du système CI (elles sont injectées au job, masquées dans les logs si bien configurées).
• Gestionnaires de secrets côté infra, puis injection au runtime (service, conteneur, job).
• Un compte de service dédié, avec permissions limitées.

Et si tu fais tourner Codex CLI dans un conteneur, pense à la méthode d’injection : variable d’environnement au lancement du container, secret monté en fichier, ou intégration à un vault. Le choix dépend de ton outillage, mais la règle reste : pas de clé en clair dans une image construite et poussée dans un registry.

Bonnes pratiques de gestion de la clé API (tous OS)

Une clé API, c’est une carte d’accès. Elle doit être gérée comme telle. Voilà ce que je recommande dans un usage quotidien, sans Transformer-son-vieux-pc-en-machine-de-geek-usages-retro-et-open-source-qui-donnent-une-seconde-vie-a-votre-materiel/ »>Transformer ta vie en audit permanent.

Ne jamais inclure la clé dans le code ou un repository

• Pas de clé dans un fichier source, même “temporairement”.
• Pas de clé dans un README, une issue, un paste, une capture d’écran.
• Ajoute .env (et variantes) au .gitignore.
• Vérifie tes scripts : un echo mal placé peut exposer une variable dans des logs.

Oui, même dans un repo privé. Les repos privés fuitent aussi, juste avec plus de style.

Rotation, révocation et permissions minimales

Si tu suspectes une fuite, tu révoques et tu regénères. Sans débat. Ensuite, tu corriges la cause. Dans un usage plus avancé, tu peux séparer les clés par contexte (dev local, CI, projet sensible) et limiter les permissions selon le besoin.

Pour comprendre ce qui se joue derrière “permissions” et “scopes”, je te conseille codex cli openai permissions token et scopes, ça évite les configurations trop larges, ou les erreurs où tu as “une clé”, mais pas les droits attendus.

Dépannage : Codex CLI ne détecte pas OPENAI_API_KEY ?

Quand Codex CLI “ne voit pas” OPENAI_API_KEY, ce n’est pas toujours la variable qui manque. Souvent, c’est la portée, le mauvais terminal, ou une config concurrente. Voilà une checklist de debug, pas à pas.

• Étape 1 : vérifie que la variable existe dans le même terminal qui lance Codex CLI. Un IDE peut lancer un terminal avec un environnement différent de ton terminal système.
• Étape 2 : ferme et rouvre le terminal après une modification persistante (Windows le fait souvent payer comptant).
• Étape 3 : attention aux espaces, guillemets, retours à la ligne cachés. Un copier-coller depuis un gestionnaire de mots de passe peut ajouter un caractère invisible.
• Étape 4 : si tu es sous WSL, la variable doit être définie dans l’environnement Linux, pas seulement dans Windows.
• Étape 5 : cherche une variable vide, écrasée par un script ou un profil shell. Une exportation à vide dans un fichier de config peut “effacer” la valeur.
• Étape 6 : si l’erreur ressemble à un problème d’authentification plutôt qu’à une variable manquante, va lire codex cli openai erreur authentication failed, les causes sont parfois contre-intuitives.

Un détail qui revient en équipe : plusieurs méthodes de config en même temps. Une clé dans un profil, une autre dans un .env, une autre injectée par l’IDE. Résultat : tu changes la “mauvaise” clé et rien ne bouge. Simplifie, puis réintroduis de la complexité si tu en as une vraie raison.

FAQ – OPENAI_API_KEY pour Codex CLI

Comment définir OPENAI_API_KEY pour Codex CLI sous Windows, macOS et Linux ?

Windows : via les variables d’environnement utilisateur/système, ou dans une session PowerShell/CMD, ou via un .env géré par ton environnement d’exécution. macOS et Linux : export temporaire dans le terminal, ou export permanent dans le fichier de config du shell (zshrc, bashrc), ou injection via un gestionnaire de secrets.

Pourquoi ma variable d’environnement OPENAI_API_KEY n’est-elle pas reconnue par Codex CLI ?

Cas les plus fréquents : tu l’as définie dans un terminal, puis tu lances Codex CLI depuis un autre (IDE, autre session), tu as défini la variable côté Windows mais tu exécutes Codex CLI dans WSL, tu as modifié une variable persistante mais ton terminal n’a pas été relancé, ou un fichier de config écrase la valeur par une valeur vide.

Peut-on sécuriser OPENAI_API_KEY avec un fichier .env ou un vault ?

Oui. Le .env est pratique par projet, mais il exige une hygiène stricte (gitignore, pas de partage, pas de sauvegarde publique). Un vault ou gestionnaire de secrets est plus adapté dès que tu touches à de la CI, à un serveur, ou à une machine partagée, car il réduit les fuites accidentelles et centralise la rotation.

Que faire si ma clé API OpenAI a été exposée sur mon poste ?

Révoque la clé depuis l’endroit où tu la gères, génère-en une nouvelle, puis remplace-la partout où elle est utilisée. Ensuite, cherche la source de fuite : historique de shell, commit Git, fichier .env oublié, logs. Si la clé a été poussée sur un dépôt, considère qu’elle est compromise même si tu l’as supprimée du commit suivant, l’historique existe encore.

Ressources, liens et pages utiles

Pour aller plus loin dans le cocon, et éviter les erreurs de config qui coûtent du temps :

• configurer codex cli openai api key, la vue d’ensemble multi-OS, avec les pièges classiques de sécurité.
• codex cli openai erreur authentication failed, quand la clé est là mais que l’auth refuse quand même.
• codex cli openai permissions token et scopes, pour comprendre la logique d’autorisations sans tout ouvrir “par confort”.
• codex cli openai debutant, si tu démarres et que tu veux un parcours complet depuis le terminal.

Conclusion

Définir OPENAI_API_KEY pour Codex CLI, c’est le rite de passage : simple en apparence, mais avec assez de subtilités pour te faire perdre une heure si tu mélanges portées, shells et environnements. Caler une méthode claire, session temporaire pour tester, persistante pour le quotidien, secrets pour la CI, te donne un setup stable et nettement moins stressant.

Prochaine étape sympa : tu veux une config “propre” qui marche à la fois dans ton terminal, ton IDE et tes scripts, sans dupliquer la clé partout. Tu pars plutôt sur un .env par projet, ou tu passes directement à un gestionnaire de secrets pour tout unifier ?