Installation et connexion (Mac / Windows / Linux)

📚 Navigation de la série : Le chapitre précédent 02 · Aperçu des concepts clés de Codex a explicité les notions clés de Codex (agent, sandbox, approbation, local/cloud). Ce chapitre détaille sa mise en œuvre pratique — en couvrant l'application de bureau et l'interface en ligne de commande (CLI), les procédures d'authentification, les spécificités par plateforme et la résolution des pannes courantes. La tarification est abordée au chapitre 04 · Tarification et facturation.

OpenAI propose quatre interfaces d'accès pour Codex : l'interface web, l'application de bureau, la ligne de commande (CLI) et les extensions pour IDE. L'expérience pratique montre que les procédures d'installation documentées dans les tutoriels obsolètes diffèrent fréquemment des recommandations officielles.

L'installation de Codex est simple, à condition de suivre la procédure officielle. Ce chapitre documente les étapes recommandées pour chaque système afin de vous éviter les erreurs classiques.

À la fin de ce chapitre, vous obtiendrez :

• Le flux d'installation de l'application de bureau et de la CLI pour macOS, Windows et Linux, avec les validations correspondantes
• Un comparatif des trois méthodes d'installation de la CLI (script officiel, Homebrew et npm)
• La distinction entre les deux modes d'authentification (compte ChatGPT et clé API) et la résolution des blocages en environnement distant
• Un tableau de diagnostic rapide pour résoudre les erreurs d'installation les plus fréquentes

---

01 Trois prérequis indispensables avant l'installation

Prenez le temps de valider ces trois points avant de lancer les commandes pour éviter des blocages ultérieurs.

1. Le choix de l'interface d'accès

L'installation technique s'oriente selon deux axes :

• L'application de bureau : interface graphique simple. Note : disponible uniquement pour macOS et Windows ; une liste d'attente est privée pour les environnements Linux.
• La CLI (Ligne de commande) : agent d'exécution intégré au terminal, supporté sur macOS, Windows et Linux, privilégié par les développeurs.

Recommandation : privilégiez la CLI pour sa flexibilité interplateforme. Ce guide se concentre sur l'interface en ligne de commande, l'application de bureau faisant l'objet d'un paragraphe dédié. Note : l'authentification est partagée entre la CLI et les extensions IDE (l'application de bureau disposant de sa propre session, voir section 06).

2. Un compte utilisateur actif

Point critique souvent omis : Codex est indexé sur votre formule ChatGPT.

La documentation précise que les abonnements Plus, Pro, Business, Edu et Enterprise de ChatGPT intègrent le volume d'usage de Codex. Il est également possible d'utiliser une clé API OpenAI facturée à la consommation — dans ce cas, certaines fonctionnalités dépendant de l'espace de travail ChatGPT ne seront pas disponibles (la version cloud de Codex exigeant une connexion ChatGPT).

用 API key 跑本地 CLI 是 OK 的，OpenAI 按标准 API 价格从你的 Platform 账户扣费，跟套餐里那份额度是两本账。

La facturation est détaillée au chapitre 04 · Tarification et facturation. Nous supposons ici que vous disposez d'un accès actif.

3. La connexion réseau aux serveurs OpenAI

Les requêtes de Codex s'exécutent en ligne sur les serveurs d'OpenAI. Assurez-vous de disposer d'un accès réseau stable aux domaines chatgpt.com ou platform.openai.com sous peine d'erreurs de timeout ou d'échecs de connexion.

💡 En résumé : Avant de démarrer, validez ces trois points — choix de la CLI (compatibilité maximale), disposer d'un compte actif (ChatGPT ou clé API) et d'un accès réseau stable aux services d'OpenAI.

---

02 Option 1 : L'application de bureau (macOS / Windows)

L'application graphique évite l'usage du terminal.

Analogie : ChatGPT intégré à votre répertoire de projet. L'utilisation s'apparente à l'interface web classique, à la différence près que l'application de bureau se connecte à un répertoire local pour y analyser les fichiers, éditer le code et exécuter les commandes — réunissant la discussion, l'arborescence projet et la mémoire locale.

Cas d'usage types :

• Profils produit ou design souhaitant analyser un projet ou déléguer de petites retouches sans manipuler la console.
• Gestion de projets parallèles — lancer des tests sur un projet A tout en poursuivant les prompts sur un projet B.
• Suivi graphique des modifications ligne à ligne (panneau de revue) avant approbation.

Téléchargement et installation

Rendez-vous sur https://chatgpt.com/codex pour télécharger l'installateur :

Système cible	Option de téléchargement
macOS (Apple Silicon)	Télécharger la version standard par défaut
macOS (Intel)	Sélectionner la version Intel build
Windows	Télécharger l'installateur Windows officiel
Linux	Non disponible, s'inscrire sur la liste d'attente ; utiliser la CLI

Note pour macOS : Vérifiez l'architecture de votre processeur dans le menu Pomme → « À propos de ce Mac ». Si la mention « Puce Apple M... » apparaît, téléchargez la version Apple Silicon, sinon optez pour la version Intel. Une mauvaise version empêchera l'installation ou provoquera un crash au lancement.

Première connexion et sélection de projet

Lancez l'application et suivez ces trois étapes :

1. Authentification : Connectez-vous avec votre compte ChatGPT ou votre clé API OpenAI.
2. Sélection de répertoire : Indiquez le dossier de travail dans lequel Codex doit intervenir. Vos répertoires récents y seront listés.
3. Premier message : Une fois le dossier ouvert, vérifiez que la mention « Local » est active dans l'angle inférieur gauche (pour autoriser l'exécution sur votre machine locale) et saisissez votre premier prompt.

Pour démarrer, concentrez-vous sur les concepts d'échange (chat) et d'espace de travail (projet) : les discussions s'apparentent au fonctionnement web classique, tandis que le projet active l'accès de Codex à un répertoire spécifique de votre machine.

La configuration de la langue est accessible dans les paramètres. Les volets de contrôle latéraux s'activent depuis l'angle supérieur droit. L'interface se présente ainsi :

💡 En résumé : L'application de bureau cible macOS et Windows (veillez à choisir l'architecture de processeur correcte sous Mac) ; connectez-vous, ouvrez un répertoire et validez l'accès Local avant d'échanger.

---

03 Option 2 : La CLI (Ligne de commande interplateforme)

En synthèse : privilégiez systématiquement le script d'installation officiel (standalone installer). Il déploie un exécutable binaire autonome ne dépendant pas de Node.js.

Analogie : L'installateur autonome. C'est l'équivalent d'un assistant d'installation en un clic qui télécharge et configure le binaire directement, sans affecter le reste de votre système. L'ancienne méthode via npm exige de déployer au préalable un interpréteur (Node.js), ce qui multiplie les dépendances et risques de conflits.

macOS / Linux

Saisissez la commande suivante dans votre terminal :

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Note : Assurez-vous d'avoir accès au domaine chatgpt.com pour éviter les timeouts lors du téléchargement.

Pour les scripts d'automatisation ou les environnements de CI (sans confirmation interactive), déclarez la variable d'environnement suivante :

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

Windows (natif, hors WSL)

Saisissez dans votre console PowerShell :

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Version automatisée (CI ou script) :

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

L'option -ExecutionPolicy ByPass lève temporairement les restrictions d'exécution de scripts de la session active ; la commande irm (Invoke-RestMethod) télécharge le fichier d'installation qui est ensuite interprété par iex (Invoke-Expression). Si le terminal renvoie une erreur sur irm, assurez-vous d'utiliser une session PowerShell et non CMD.

Alternatives d'installation : Homebrew ou npm

Voici un comparatif des différentes options d'installation :

Méthode d'installation	Commande	Prérequis	Recommandation
Script officiel	curl ... | sh (ou irm sous Win)	Aucun	Recommandé, exécutable autonome et propre
Homebrew (macOS)	brew install --cask codex	Gestionnaire Homebrew installé	Adapté aux utilisateurs réguliers de brew. Mises à jour légèrement décalées par rapport au canal officiel
npm	npm install -g @openai/codex	Environnement Node.js actif	Réservé aux développeurs gérant leurs utilitaires via npm

Les paquets Homebrew dépendent des revues de l'équipe de maintenance Cask, entraînant un décalage de quelques jours par rapport aux publications officielles ; cela offre cependant une version stabilisée.

Installation via Homebrew (macOS) :

brew install --cask codex

Installation via npm (nécessite Node.js) :

npm install -g @openai/codex

Recommandations de sécurité :

• Évitez l'usage de sudo avec npm. De nombreux guides recommandent l'installation globale via sudo npm install -g, au risque d'altérer les permissions système. Privilégiez l'usage d'un gestionnaire de versions (comme nvm ou Volta) pour isoler Node.js dans votre répertoire utilisateur, ou optez pour la méthode d'installation par le script officiel pour éviter les problématiques de droits npm.
• L'installation Homebrew s'appuie sur l'option --cask pour déployer l'utilitaire codex. Ne l'omettez pas.

💡 En résumé : Privilégiez le script officiel pour la CLI — curl ... | sh sous macOS/Linux, et irm sous Windows ; l'exécutable autonome est indépendant de Node.js.

Voici le schéma comparatif des deux canaux d'installation :

---

04 Spécificités Windows : environnement natif ou WSL ?

La configuration sous Windows s'accompagne de contraintes de sécurité et d'environnement.

Trois modes d'exécution sont supportés :

• Windows natif avec sandbox elevated (privilégié) : Option recommandée. Utilise un profil utilisateur restreint dédié à la sandbox, des limites de fichiers système et des règles de pare-feu pour isoler l'agent.
• Windows natif avec sandbox unelevated (non privilégié) : Option secondaire. À utiliser si les politiques de sécurité de votre poste empêchent la configuration du profil d'administration requis pour le mode elevated.
• WSL2 (Windows Subsystem for Linux) : Exécution au sein de la couche Linux native. Recommandé si vos outils de développement ou vos dépôts sont déjà hébergés sous WSL2.

Tableau de comparaison officiel :

Mode d'exécution	Prérequis	Cas d'usage
Natif + elevated	Droits d'administration pour la sandbox	Option recommandée par défaut, performances et sécurité optimales
Natif + unelevated	Aucun droit d'administration requis	Alternative si le mode elevated est bloqué par des politiques système
WSL2	Couche WSL2 active	Nécessite des outils Linux ou dépôt sous WSL2

Contraintes techniques :

• Système d'exploitation : Windows 11 est recommandé. Windows 10 est supporté à partir de la version 1809 (nécessaire pour l'usage de ConPTY), les versions antérieures n'étant pas compatibles.
• winget doit être disponible sur le système pour le déploiement des dépendances.
• WSL1 n'est plus supporté. Depuis la version 0.115 de Codex, la sandbox Linux s'appuie sur bubblewrap, excluant les environnements WSL1. Migrez vers WSL2.

Pour configurer WSL2, lancez l'installation depuis une console PowerShell en mode administrateur :

wsl --install
wsl

Une fois dans le shell de la distribution Linux :

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Recommandation de performances WSL : évitez de stocker vos projets dans le répertoire d'accès Windows /mnt/c/..., sous peine de ralentissements importants et de conflits de liens symboliques ou de droits. Privilégiez votre répertoire personnel Linux (ex. ~/code/my-app). Les fichiers restent accessibles depuis Windows via le chemin réseau \\wsl$.

Voici la logique de décision sous Windows :

💡 En résumé : Sous Windows, privilégiez le mode natif avec sandbox elevated ; basculez sur le mode unelevated en cas de restriction de droits, ou vers WSL2 si vous travaillez dans un environnement Linux (WSL1 n'étant pas supporté).

---

05 Valider la conformité de l'installation

Une fois le déploiement finalisé, ouvrez une nouvelle session de terminal et saisissez :

codex --version

La console doit retourner le numéro de version de l'utilitaire :

codex-cli 0.139.0

L'affichage de la version valide l'installation. Si le terminal retourne command not found: codex (ou 'codex' is not recognized sous Windows), le chemin de l'exécutable ne figure pas dans votre variable d'environnement PATH (voir résolution à la section 08).

Note : Les arguments de mise à jour et de gestion de version étant sujets à modifications, référez-vous systématiquement à la commande codex --help pour en vérifier la syntaxe active.

Pour l'application de bureau, le numéro de version figure dans les préférences d'affichage de l'interface.

💡 En résumé : Valisez l'installation de la CLI avec codex --version ; référez-vous à codex --help pour les commandes de mise à jour.

---

06 Connexion et authentification

Pour lier Codex à votre compte utilisateur, lancez l'application depuis votre répertoire de projet :

codex

En l'absence de session active, Codex ouvre votre navigateur pour lancer la procédure d'authentification ChatGPT. Le jeton d'accès (access token) est ensuite transmis à l'utilitaire pour valider la connexion.

Choix du mode d'authentification

Mode d'authentification	Procédure	Public cible	Contraintes
Compte ChatGPT (recommandé)	Sélectionner Sign in with ChatGPT et valider dans le navigateur	Usage standard, accès aux services cloud	Consommation déduite de votre abonnement ChatGPT
Clé API	Saisir la clé générée sur la Console OpenAI	Pipelines CI/CD, exécutions automatisées	Facturation à la consommation ; incompatible avec les fonctionnalités d'espace de travail ChatGPT

L'authentification via compte ChatGPT est recommandée pour le développement interactif quotidien, l'abonnement couvrant les besoins courants. Réservez l'usage des clés API aux scripts automatisés et environnements d'intégration continue (CI/CD) qui excluent les validations par navigateur. Veillez à ne pas exposer ces clés dans des dépôts publics.

Stockage des identifiants et persistance

Les jetons de connexion sont conservés localement pour éviter les demandes d'authentification répétées. Notez deux règles de gestion :

• La session est partagée entre la CLI et les extensions d'IDE — se déconnecter de l'une invalide l'accès pour l'autre.
• Les jetons sont stockés au format texte dans ~/.codex/auth.json ou dans le gestionnaire de clés du système (Keychain sous macOS). Le comportement est configurable via le paramètre cli_auth_credentials_store (options file, keyring ou auto ; voir chapitre 18).

⚠️ Le fichier ~/.codex/auth.json contient vos secrets de connexion. Traitez-le comme un mot de passe : ne le versionnez pas dans git et ne l'affichez pas publiquement.

Les sessions basées sur un compte ChatGPT font l'objet d'un renouvellement de token automatique avant expiration.

Connexion en environnement distant (Headless, SSH, WSL)

Si vous opérez sur un serveur distant, un environnement sans interface graphique (headless) ou si les redirections locales sont bloquées, l'authentification par navigateur standard échouera. Privilégiez alors la connexion par code d'appareil (Device Code Login).

Sélectionnez l'option Sign in with Device Code ou lancez :

codex login --device-auth

Cette option affiche un lien et un code d'activation à usage unique. Ouvrez l'adresse depuis n'importe quel navigateur actif et saisissez le code pour valider la session sur votre terminal distant.

Note : Cette fonction exige d'être activée dans les paramètres de sécurité ChatGPT de votre compte. En cas d'indisponibilité, deux alternatives existent :

1. Transfert du fichier de session : Réalisez la connexion depuis un poste disposant d'un navigateur graphique, récupérez le fichier ~/.codex/auth.json généré et copiez-le sur le serveur cible. Exemple en ligne de commande :

ssh user@remote 'mkdir -p ~/.codex'
scp ~/.codex/auth.json user@remote:~/.codex/auth.json

2. Redirection de port SSH : Redirigez le port de connexion local (par défaut localhost:1455) du serveur vers votre machine locale pour intercepter le jeton :

ssh -L 1455:localhost:1455 user@remote

Exécutez ensuite la commande codex login dans cette session SSH et suivez la procédure d'ouverture du navigateur.

💡 En résumé : L'accès par compte ChatGPT est privilégié (secrets stockés dans ~/.codex/auth.json) ; en environnement distant, utilisez codex login --device-auth pour valider l'accès via un code d'appareil.

---

07 Exercice pratique : initialisation et premier test

Voici un exercice simple pour valider le fonctionnement de la CLI dans un répertoire temporaire vide :

Étape 1 : Créer le dossier et lancer Codex

mkdir -p ~/codex-demo && cd ~/codex-demo
codex

Valisez la phase d'authentification si c'est le premier lancement, pour ouvrir l'interface console.

Étape 2 : Formuler une consigne simple en langage naturel

在 test.py 里写一个打印 hello world 的函数

Comportement attendu : Codex affiche les modifications projetées et attend votre validation (sélectionnez Yes) avant d'écrire sur le disque. C'est le flux de sécurité par défaut de l'agent.

Une fois l'action validée, le fichier test.py est créé. Quittez la session avec Ctrl + C ou en saisissant /exit.

Étape 3 : Prendre un point de contrôle git (recommandé)

git init
git add -A && git commit -m "codex 动手前的检查点"

Ces étapes valident le bon fonctionnement de la chaîne de création et de validation sécurisée de l'agent.

Le flux d'exécution se résume ainsi :

💡 En résumé : Initialisez le projet dans un dossier vide — lancez codex, formulez votre demande et validez l'action proposée (Yes) ; l'usage de points de contrôle git sécurise vos développements.

---

08 Résolution des pannes courantes

Voici une synthèse des anomalies fréquentes lors de l'installation de l'utilitaire :

Symptôme constaté	Cause probable	Résolution
command not found: codex	L'exécutable ne figure pas dans le PATH	Ajouter le dossier d'installation dans la variable PATH (voir ci-dessous)
'codex' is not recognized (Windows)	PATH non configuré ou terminal non redémarré	Configurer le PATH puis redémarrer la console
irm is not recognized	Commande PowerShell lancée dans CMD	Ouvrir une session PowerShell pour exécuter l'appel irm
Attente de connexion infinie ou échec de retour	Blocage des connexions locales ou serveur distant	Utiliser codex login --device-auth (voir section 06)
Échec de téléchargement du script d'installation	Problème d'accès réseau	Vérifier la connexion ou utiliser le canal Homebrew
Fonctionnalités restreintes avec une clé API	Contrainte inhérente à l'usage des clés API	Utiliser l'authentification par compte ChatGPT
Erreurs Windows 1385 (échec de sandbox)	Droits d'accès restreints sur la machine	Contacter l'administrateur système ou basculer en mode sandbox unelevated
codex reste actif après désinstallation	Présence d'installations multiples en conflit	Identifier les chemins avec which -a codex et nettoyer les binaires

1. command not found: codex (le plus fréquent)

Cette erreur indique que le chemin d'accès au binaire ne figure pas dans la liste des répertoires de recherche de votre terminal (variable PATH).

Analogie : L'index d'adresses du système. La variable PATH répertorie les dossiers contenant des programmes exécutables. Si l'adresse de Codex n'y est pas enregistrée, le système ne peut pas localiser l'application.

Résolution (sous macOS avec Zsh, configurez le profil shell pour y ajouter le dossier d'installation de Codex) :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Note : Cet exemple s'appuie sur le chemin d'installation par défaut ~/.local/bin ; adaptez-le selon le retour affiché par le script d'installation. Sous Linux (Bash), modifiez le fichier ~/.bashrc. Sous Windows, ajoutez le dossier aux variables d'environnement utilisateur et redémarrez votre console.

Vérification :

codex --version

2. Installations multiples en conflit

La coexistence de versions déployées via npm et par script d'installation peut générer des comportements incohérents. Identifiez les exécutables actifs :

which -a codex

Supprimez les binaires obsolètes pour ne conserver que la version officielle. Exemple de désinstallation npm :

npm uninstall -g @openai/codex

💡 En résumé : Identifiez la cause de l'erreur avant d'envisager une réinstallation ; l'erreur command not found est liée à la variable PATH, tandis que les conflits de versions proviennent d'installations multiples (à contrôler avec which -a codex).

---

09 Résumé

Ce chapitre a couvert la mise en œuvre de Codex :

• Prérequis : choix de la CLI interplateforme, compte actif et accès réseau aux serveurs OpenAI.
• Canaux d'installation : application de bureau (macOS / Windows) ou CLI (macOS, Windows, Linux) via le script d'installation officiel autonome.
• Spécificités Windows : usage privilégié de la sandbox native elevated, alternative unelevated ou support WSL2 (WSL1 n'étant pas supporté).
• Authentification : liaison par compte ChatGPT privilégiée (secrets stockés dans ~/.codex/auth.json) ou code d'appareil (codex login --device-auth) en environnement distant.
• Résolution des anomalies : variable PATH pour les binaires introuvables, multi-installations pour les conflits.

Vous disposez des compétences requises pour installer, connecter et valider le fonctionnement de Codex.

Le chapitre suivant 04 · Tarification et facturation détaille les aspects financiers : quotas des formules d'abonnements ChatGPT, tarification à l'usage des clés API et comparaison avec les offres alternatives.

---

Lectures recommandées

• Règles et hooks (Rules & Hooks) : automatiser des actions
• Windows : environnement natif vs WSL
• Skills : enrichir les compétences de Codex