Configurer la clé API OpenAI (variables d’environnement) pour Codex CLI

Une clé API, c’est le badge d’accès de Codex CLI

Codex CLI, c’est un peu le droïde protocolaire de ton terminal, il comprend ce que tu veux faire, puis va chercher l’intelligence côté OpenAI pour t’aider à générer, modifier ou expliquer du code. Sauf qu’en 2026, ce genre de service ne se lance pas “en roue libre” : il faut prouver qui tu es et à quel compte rattacher l’usage. Cette preuve, c’est ta clé API OpenAI, généralement fournie via une variable d’environnement nommée OPENAI_API_KEY.

Dans ce guide, on va faire ça proprement, multi-OS, avec des méthodes réalistes pour les devs solo comme pour les équipes. Et surtout, on va éviter le piège classique, “j’ai mis la clé quelque part, mais Codex CLI ne la voit pas”.

Pourquoi une clé API est-elle nécessaire avec Codex CLI ?

Codex CLI ne “contient” pas l’IA en local, il s’appuie sur des API distantes. La clé API sert à trois choses très concrètes :

Authentification : l’API vérifie que la requête vient d’un utilisateur autorisé.
Facturation et quotas : l’usage est associé à ton compte, avec des limites éventuelles.
Traçabilité : en cas de souci (abuse, fuite, anomalie), tu peux identifier et révoquer une clé.

Sans clé, Codex CLI ne peut pas appeler l’API, donc tu te heurtes à des erreurs de type “authentication” ou “unauthorized”. La bonne nouvelle, c’est que la configuration est simple une fois que tu sais où poser la variable et comment vérifier qu’elle est visible par ton terminal.

Où et comment obtenir votre clé API OpenAI ?

Tu récupères ta clé depuis le tableau de bord OpenAI, dans la section de gestion des clés API. L’interface a évolué au fil des années, mais la logique reste la même : tu crées une clé, tu la copies une seule fois (souvent), et tu la stockes dans un endroit sûr.

Connecte-toi à ton compte OpenAI.
Va dans les paramètres ou la section “API keys”.
Crée une nouvelle clé API.
Copie-la immédiatement, puis colle-la dans un gestionnaire de mots de passe ou un coffre de secrets.

Je te conseille de créer une clé dédiée à Codex CLI, au lieu d’utiliser une clé “fourre-tout” que tu colles dans dix projets. Quand tu dois révoquer une clé après une fuite, tu es content de ne pas tout casser en même temps.

Comprendre les variables d’environnement, principes et sécurité

Une variable d’environnement, c’est une paire “nom = valeur” que ton OS fournit aux programmes. L’intérêt, c’est de ne pas écrire tes secrets en dur dans le code. Pour Codex CLI, l’idée est simple : le CLI lit OPENAI_API_KEY au lancement, et l’utilise pour authentifier ses requêtes.

Les trois niveaux classiques

Session : tu définis la variable dans un terminal, elle disparaît quand tu fermes la fenêtre.
Utilisateur : la variable est persistante pour ton compte, dans ton OS.
Système : la variable est visible pour tous les utilisateurs (utile sur serveur, plus risqué sur poste partagé).

Le piège n°1 : définir la variable au mauvais endroit

Si tu mets la variable dans PowerShell mais que tu lances Codex CLI depuis un autre terminal, ou si tu modifies un fichier de shell sans recharger la session, Codex CLI ne verra rien. La plupart des “ça marche pas” viennent de là.

Le piège n°2 : confondre .env et variables d’environnement

Un fichier .env n’est pas magique. C’est un simple fichier texte. Il faut un outil (ou ton appli) qui le lit et exporte les valeurs. Codex CLI, selon ta manière de l’invoquer, ne chargera pas forcément un .env tout seul. On va couvrir une méthode fiable plus bas.

Méthodes pour configurer OPENAI_API_KEY selon votre OS

Objectif : que OPENAI_API_KEY soit disponible dans le terminal qui lance Codex CLI. Je te donne plusieurs méthodes par OS, parce que tout le monde n’a pas le même setup, ni la même tolérance au “persistant”.

Sous Windows : méthodes et bonnes pratiques

Windows, c’est souvent un trio PowerShell, CMD, et parfois Git Bash ou le terminal intégré de VS Code. Avant de choisir, repère ton terminal “principal”.

Option A, PowerShell, variable pour la session (rapide)

À utiliser pour tester, ou quand tu es sur une machine temporaire.

Ouvre PowerShell.
Définis la variable dans la session.
Lance Codex CLI dans la même fenêtre.

commande à saisir (en remplaçant par ta clé) :

$env:OPENAI_API_KEY = « votre_cle_api »

Si tu fermes la fenêtre, c’est perdu. Avantage : zéro trace persistante dans le système.

Option B, PowerShell, variable persistante au niveau utilisateur

Plus confortable au quotidien, tout en restant limité à ton compte Windows.

Ouvre PowerShell.
Crée la variable pour l’utilisateur.
Ferme et rouvre ton terminal (ou redémarre VS Code si tu lances le CLI dedans).

Commande :

[Environment]::SetEnvironmentVariable(« OPENAI_API_KEY », »votre_cle_api », »User »)

Option C, Paramètres Windows (UI), variable d’environnement

Si tu préfères cliquer plutôt que taper des commandes :

Recherche “Variables d’environnement” dans Windows.
Ouvre la fenêtre des variables utilisateur.
Ajoute OPENAI_API_KEY avec la valeur de ta clé.
Valide, puis rouvre tes terminaux.

Je recommande cette méthode sur des postes dev Windows partagés en entreprise, parce que tu peux auditer plus facilement “où c’est stocké”, sans dépendre d’un script oublié.

Bonnes pratiques Windows

Évite de poser la clé au niveau “Système” sur une machine multi-utilisateurs.
Si tu utilises VS Code, rouvre la fenêtre du terminal intégré après modification.
Si tu passes par Git Bash, garde en tête qu’il lit plutôt les fichiers de shell type .bashrc, pas les profils PowerShell.

Sous macOS et Linux : export, fichiers de configuration et automatisation

Sur macOS et Linux, la logique dépend du shell, souvent zsh sur macOS récent, bash sur beaucoup de Linux, parfois fish chez les gens qui aiment nager à contre-courant. L’objectif reste : exporter OPENAI_API_KEY dans l’environnement de la session qui lance Codex CLI.

Option A, export dans la session (test rapide)

Ouvre ton terminal.
Exporte la variable.
Lance Codex CLI dans le même terminal.

Commande :

export OPENAI_API_KEY= »votre_cle_api »

Quand tu fermes le terminal, la variable disparaît. C’est pratique pour vérifier que tout fonctionne avant d’automatiser.

Option B, persistance dans le profil du shell (zsh, bash)

Ici tu ajoutes l’export dans un fichier chargé au démarrage du shell. Le bon fichier dépend de ton environnement :

macOS zsh : souvent ~/.zshrc
bash : souvent ~/.bashrc ou ~/.bash_profile selon les distros

Ajoute une ligne :

export OPENAI_API_KEY= »votre_cle_api »

Ensuite, recharge la config sans fermer le terminal :

source ~/.zshrc

ou :

source ~/.bashrc

Ça marche, mais je suis mitigé : écrire un secret en clair dans un fichier de config de shell, c’est pratique, mais ça augmente les risques de fuite si ton home est sauvegardé, synchronisé, ou consultable.

Option C, utiliser un fichier .env pour un projet (propre en équipe)

Le .env est très utile quand tu veux un setup par projet. Le principe : tu stockes la clé localement, tu ignores ce fichier dans Git, puis tu charges les variables au moment d’exécuter Codex CLI.

Dans ton dossier projet, crée un fichier nommé .env.
Ajoute la ligne : OPENAI_API_KEY=… (sans guillemets si possible).
Ajoute .env à ton .gitignore.

Ensuite, tu as deux approches :

Charger manuellement le .env dans la session avant de lancer Codex CLI.
Utiliser un outil de chargement de variables d’environnement adapté à ton stack (par exemple via scripts npm), sans inventer une mécanique fragile.

Pour une méthode simple et portable, beaucoup d’équipes passent par un script de lancement qui exporte la variable, puis exécute Codex CLI dans le même processus. L’important : éviter de “cat .env” n’importe comment si tu ne sais pas ce que tu exécutes.

Vérifier la bonne prise en compte de la clé API dans Codex CLI

Avant de blâmer Codex CLI, vérifie que la variable est visible dans le terminal courant. Selon ton environnement :

Windows

PowerShell : affiche la variable avec $env:OPENAI_API_KEY
CMD : affiche la variable avec echo %OPENAI_API_KEY%

Si ça affiche une valeur vide, Codex CLI ne peut pas la deviner. Si ça affiche ta clé, attention à l’historique et aux captures d’écran, évite de la laisser traîner à l’écran.

macOS / Linux

Affiche la variable avec : echo $OPENAI_API_KEY
Liste les variables (bruyant) : env | grep OPENAI

Vérifier côté Codex CLI

Ensuite, lance une commande simple de Codex CLI qui nécessite un appel API. Le résultat attendu n’est pas “ça marche”, c’est plutôt l’absence d’erreur d’authentification. Si tu obtiens une erreur liée à la clé, passe à la section dépannage.

Sécuriser sa clé API : erreurs fréquentes, rotation et gestion des secrets

Une clé API, c’est un secret. Pas un “paramètre”. La traiter comme un secret t’évite un futur weekend pourri à chercher pourquoi ton quota a explosé après un push sur un repo public.

Erreurs fréquentes que je vois tout le temps

Mettre la clé dans un fichier versionné (README, script, commit de test).
Copier la clé dans une capture d’écran envoyée sur un ticket support.
Coller la clé dans l’historique du shell, puis partager l’historique via dotfiles.
Utiliser la même clé partout, puis la révoquer en urgence et casser tous les outils.

Rotation de clé : quand et comment

En 2026, la rotation n’est plus un “truc d’ops parano”. C’est une hygiène de base :

Après une suspicion de fuite, rotation immédiate.
Quand un membre quitte une équipe, rotation des secrets partagés.
À intervalle régulier si ton contexte l’exige (projets pro, environnements sensibles).

La stratégie simple : tu crées une nouvelle clé, tu mets à jour l’environnement, tu testes Codex CLI, puis tu révoques l’ancienne. Évite la révocation “d’abord”, sauf si tu es en mode incident.

Gestion des secrets en équipe

Un coffre de secrets (au sens large) vaut mieux qu’un .env partagé par mail.
Les droits doivent être minimaux : chacun sa clé, ou des clés séparées par projet.
Trace qui a accès à quoi, même dans une petite équipe. Les ennuis adorent les zones grises.

Dépannage : résoudre les problèmes liés à la configuration de la clé API

Quand Codex CLI “ne reconnaît pas” la clé, ça se joue souvent sur des détails bêtes. Bonne nouvelle, on peut diagnostiquer méthodiquement.

Symptôme : erreur d’authentification

Vérifie que la variable s’appelle exactement OPENAI_API_KEY (pas d’espace, pas de tiret, pas de faute).
Vérifie que la valeur n’a pas de caractères invisibles, parfois copiés depuis un navigateur ou un PDF.
Teste dans le même terminal qui lance Codex CLI, pas dans un autre onglet.

Symptôme : la variable est définie, mais Codex CLI ne la voit pas

Si tu utilises VS Code, rouvre le terminal intégré, voire la fenêtre VS Code.
Si tu utilises Windows, ne mélange pas PowerShell et CMD en supposant que tout est partagé.
Sur macOS/Linux, recharge ton profil (source), ou ouvre un nouveau terminal.

Symptôme : ça marche dans un terminal, pas dans un autre

Tu as probablement défini la variable au niveau session. C’est normal : chaque terminal est un processus distinct. Passe à une méthode persistante (niveau utilisateur) ou à un script de projet.

Symptôme : tu utilises un .env, mais rien ne se charge

Rappel : un .env est un fichier, pas une variable d’environnement. Pour valider, affiche OPENAI_API_KEY avant d’exécuter Codex CLI. Si c’est vide, ton chargement ne s’est pas produit. La solution la plus robuste reste un script de lancement qui exporte la variable, puis exécute Codex CLI dans le même contexte.

Symptôme : “permission denied” ou comportement étrange sur machine pro

Sur un poste verrouillé, tu n’as peut-être pas le droit d’écrire des variables persistantes au niveau système. Utilise le niveau utilisateur, ou demande à ton équipe IT une méthode validée, via un gestionnaire de secrets ou un profil standardisé.

Bonnes pratiques pour automatiser et partager la configuration (exemples pour équipes et projets)

Mon avis : le meilleur setup, c’est celui qui évite les manip à la main, sans transformer ton onboarding en rituel occulte. Voilà des patterns qui marchent bien.

Pattern 1 : onboarding avec .env.example

Ajoute un fichier .env.example dans le repo, sans secret.
Documente les variables attendues, dont OPENAI_API_KEY.
Chaque dev copie en .env local, puis colle sa clé.
Le .env reste ignoré par Git.

Ça évite le “c’est quoi le nom de la variable déjà ?” et ça réduit le risque qu’un nouveau colle la clé au mauvais endroit.

Pattern 2 : scripts de projet (npm, make, ou scripts shell)

Si ton projet tourne autour de Node, tu peux centraliser l’exécution de Codex CLI via un script unique, qui charge l’environnement puis lance le CLI. L’avantage, c’est que tout le monde lance la même commande, avec le même comportement. C’est aussi plus simple à expliquer dans un README.

Côté Linux/macOS, un script shell peut charger un .env, exporter les variables, puis exécuter Codex CLI. Côté Windows, tu peux faire la même chose avec un script PowerShell. Garde juste une règle : ne construis pas un loader .env “maison” qui exécute des trucs non maîtrisés.

Pattern 3 : CI et environnements automatisés

En CI, la clé ne devrait jamais être dans le repo. Elle est injectée via des variables de pipeline, ou via un système de secrets. C’est le même principe que local, mais géré par l’infra. Tu réduis fortement le risque de fuite et tu peux révoquer rapidement.

Partager sans partager la clé

Partage la procédure, pas le secret.
Préfère des clés par personne ou par service.
Documente où la variable doit être définie, et comment la vérifier.

FAQ rapide et liens utiles

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

Windows : définis OPENAI_API_KEY via PowerShell (session ou utilisateur) ou via l’interface des variables d’environnement, puis rouvre ton terminal. macOS/Linux : export dans la session pour tester, puis persistance via ton fichier de profil (zshrc, bashrc) ou un chargement par projet via .env et script.

Que faire si Codex CLI ne reconnaît pas ma clé API OpenAI ?

Commence par vérifier que la variable est visible dans le même terminal que celui qui lance Codex CLI. Ensuite, cherche les fautes de frappe dans le nom, les espaces, les caractères invisibles, et pense à recharger ton shell ou redémarrer ton terminal intégré.

Peut-on stocker la clé API dans un fichier .env, et comment sécuriser cette méthode ?

Oui, à condition de ne jamais versionner le .env, de l’ajouter à .gitignore, et de le charger explicitement avant l’exécution de Codex CLI. Pour sécuriser, limite les permissions du fichier sur macOS/Linux, évite de copier la clé dans des logs, et privilégie une clé dédiée par projet ou par personne.

Liens internes du cocon (pour aller plus loin)

Installer Codex CLI OpenAI
Prérequis Codex CLI : Node, npm, Git
Installer Codex CLI sur Windows, macOS, Linux

Lien cross-cluster

Apprendre à définir correctement OPENAI_API_KEY dans votre environnement

Derniers réflexes avant de coder avec Codex CLI

Si tu veux une routine simple, fais comme ça : une clé dédiée à Codex CLI, une méthode de configuration adaptée à ton OS, une vérification “echo de la variable” quand tu changes de terminal, et une rotation quand tu sens que le secret a trop voyagé. Une fois ces bases posées, tu peux te concentrer sur le fun, coder plus vite, refactor plus sereinement, et laisser ton terminal jouer au copilote sans te tendre un piège de sécurité. Prochaine étape logique : dans ton équipe, qui “possède” la procédure de rotation et d’onboarding, toi, le lead, ou personne ?