FAQ et résolution des problèmes : installation, connexion, permissions et modification de fichiers

📚 Navigation de la série : Le chapitre précédent 〔36 Bonnes pratiques〕 expliquait comment structurer vos développements pour optimiser votre productivité. Ce chapitre s'intéresse aux résolutions d'anomalies courantes : échecs d'installation, erreurs de connexion, refus de modification des fichiers projet, ou baisse de pertinence des réponses du modèle. Le chapitre suivant 〔38 Glossaire〕 servira de lexique de référence pour l'ensemble de la section Codex.

« J'ai lancé l'installation par npm, mais la commande codex renvoie command not found, que faire ? »

« L'authentification tourne en boucle et le navigateur ne s'ouvre pas, s'agit-il d'un problème réseau ? »

« Codex lit mon code sans problème, mais refuse d'enregistrer les modifications de fichiers en indiquant un blocage de la sandbox, alors que je n'ai rien configuré de particulier. »

Ces trois questions représentent les difficultés d'initialisation les plus fréquentes constatées au sein de la communauté des utilisateurs. Dans 90 % des cas, le dysfonctionnement n'est pas lié à un bug de l'outil, mais à la configuration par défaut (défaut d'authentification, permissions restrictives ou saturation de la fenêtre de contexte). Ce chapitre détaille chaque anomalie sous la forme d'un tableau synthétique Symptôme → Cause → Solution pour vous permettre de résoudre rapidement les blocages.

Ce que vous obtiendrez après avoir lu ce chapitre :

• Les solutions de diagnostic pour dix dysfonctionnements courants, classés par fréquence constatée.
• La résolution des erreurs d'installation, d'authentification et de routage réseau.
• La configuration des permissions de la sandbox pour autoriser l'écriture dans les fichiers.
• Les critères de choix entre les commandes slash /compact et /new lors de la saturation de la fenêtre de contexte.
• Une liste de vérification universelle en trois points pour aborder tout nouveau diagnostic d'erreur.

⚠️ Les commandes, configurations et comportements décrits se réfèrent à la documentation officielle de Codex. Les noms de modèles et versions de l'outil pouvant évoluer, fiez-vous aux retours de vos commandes locales codex --version et du sélecteur /model. Ce guide s'appuie sur les documentations officielles de gestion des authentifications et des permissions. Notez que la configuration des profils de permissions est actuellement en version Beta et sujette à modification.

---

01 Diagnostic de premier niveau : la règle des trois points

Pour résoudre efficacement un dysfonctionnement de Codex, validez ces trois aspects dans l'ordre suivant : la version, la connexion et les permissions d'accès. La majorité des blocages se situent à ce niveau.

Analogie : Le diagnostic médical préliminaire. Lors d'une urgence, les premières mesures concernent la prise de température, la tension et les symptômes généraux pour écarter les causes majeures. De la même manière, relevez ces trois caractéristiques de Codex avant d'entreprendre des modifications de configuration complexes :

# 1. Validation de l'installation et de la version active
codex --version

# 2. Vérification du statut de la connexion
codex login status

# 3. Affichage des permissions de la session courante (dans la TUI active)
/status

La première commande valide la présence de l'outil et sa version ; la deuxième s'assure de la validité de vos jetons d'authentification ; la troisième affiche les droits de lecture/écriture de la sandbox et la politique d'approbation.

Prenez l'habitude de relever ces trois retours lors de chaque diagnostic d'anomalie. La cause de l'erreur (un jeton expiré ou une sandbox configurée par erreur en lecture seule) est ainsi identifiée rapidement.

💡 Résumé en une phrase : Avant d'entamer une réinstallation, validez les trois paramètres de base : la version installée, le statut de connexion et le profil de permissions.

---

02 Commandes non détectées après l'installation

Il s'agit de la première difficulté rencontrée par les nouveaux utilisateurs lors de la configuration initiale de l'environnement de développement.

Symptôme : après avoir lancé l'installation avec npm install, l'exécution de la commande codex renvoie le message d'erreur command not found: codex ou génère des erreurs système dans la console.

Cause : le répertoire d'installation globale de npm n'est pas déclaré dans votre variable d'environnement PATH, votre version de Node.js est obsolète, ou l'installation requiert des droits d'administration d'écriture sur les répertoires système de npm.

Résolution (à tester par ordre de priorité) :

• Vérifier la version de Node.js : la commande node --version doit indiquer une version compatible (les anciennes versions obsolètes bloquent l'installation des dépendances de Codex). Mettez à jour Node.js si nécessaire.
• Ajouter le répertoire npm au PATH : la commande npm config get prefix renvoie le dossier d'installation globale. Vérifiez que le sous-répertoire bin associé est bien déclaré dans votre variable système PATH.
• Résoudre les erreurs d'accès EACCES : évitez d'installer le package en forçant les droits d'administration avec sudo npm install -g (cela génère des conflits d'accès lors des futures exécutions). Modifiez le répertoire global par défaut de npm pour le situer dans votre espace utilisateur, ou utilisez un gestionnaire de versions de Node.js comme nvm.
• Utiliser les modes d'installation alternatifs : si l'installation par npm échoue, référez-vous au guide d'installation officiel de la plateforme pour utiliser les installateurs natifs (macOS / Linux / Windows). En cas de blocage persistant des permissions de npm, l'utilisation de l'installateur natif résout généralement le problème en quelques minutes.

Remarque : pour les utilisateurs de Windows, les blocages d'installation découlent fréquemment de l'absence de WSL ou de configurations de chemins spécifiques. Ces anomalies sont détaillées au chapitre 33 Utilisation sous Windows.

💡 Résumé en une phrase : L'erreur command not found est généralement causée par l'absence du répertoire bin de npm dans la variable PATH. Évitez de forcer l'installation globale avec sudo.

---

03 Échecs d'authentification et de connexion

Une fois l'installation validée, l'authentification est l'étape suivante.

Symptôme : la commande codex login ne parvient pas à ouvrir le navigateur internet, ou l'authentification se valide dans le navigateur mais le terminal reste bloqué en attente. Une session active peut également s'interrompre brutalement en indiquant un jeton expiré.

Cause : Codex initie un service web temporaire sur le port local localhost:1455 pour intercepter le jeton de sécurité envoyé par le navigateur. Cette interception échoue si le port local est bloqué par un pare-feu, si aucun navigateur n'est installé (cas des serveurs distants) ou si le cache d'authentification local est corrompu.

Résolution :

• Dans un environnement avec navigateur : vérifiez que la validation s'est effectuée de bout en bout dans le navigateur et que le port local 1455 n'est pas utilisé par une autre application ou bloqué par les règles de sécurité locales.
• Dans un environnement sans navigateur (serveur distant, conteneur Docker ou session SSH) : utilisez la commande de connexion par code d'appareil (device auth, Beta) :

codex login --device-auth

Le CLI affiche une URL de validation associée à un code unique à usage temporaire. Ouvrez ce lien depuis un équipement connecté disposant d'un navigateur (par exemple, votre smartphone ou votre poste de travail local), saisissez le code et validez. Le terminal distant valide l'accès automatiquement.

• Solution de secours par copie de fichier : si la connexion par code d'appareil échoue, vous pouvez vous connecter sur votre poste de travail et copier le fichier d'authentification généré dans ~/.codex/auth.json vers le même répertoire de la machine distante. Attention : ce fichier contient vos clés de session et doit être protégé comme un mot de passe (ne pas le commiter sur Git ou le partager dans les rapports de diagnostic).
• Expiration de session en cours de travail : Codex actualise automatiquement le jeton de connexion avant son expiration. Si la déconnexion survient de manière répétée, validez le statut de connexion avec codex login status et relancez le cycle complet à l'aide des commandes codex logout puis codex login. Les logs de connexion sont consignés dans codex-login.log pour analyse.

Environnement de travail	Méthode d'authentification recommandée
Poste de travail local avec navigateur	Commande par défaut codex login
Serveur distant / session SSH / Conteneur	Connexion par code d'appareil codex login --device-auth
Blocage réseau sur code d'appareil	Copie manuelle sécurisée du fichier ~/.codex/auth.json
Proxy SSL d'entreprise / Autorité CA privée	Déclarer la variable CODEX_CA_CERTIFICATE pointant sur le certificat PEM

💡 Résumé en une phrase : Pour les sessions distantes sans interface graphique, privilégiez la connexion par code d'appareil codex login --device-auth pour éviter les blocages de redirection.

---

04 Erreurs réseau et proxies d'entreprise

Symptôme : les requêtes restent bloquées en attente et renvoient des erreurs de délai d'attente dépassé (timeout) ou d'échec de négociation SSL.

Cause : l'accès aux API d'OpenAI hébergeant les modèles requis est bloqué par des restrictions réseau locales. L'utilisation de proxies d'entreprise réalisant une relecture TLS (déchiffrement SSL) bloque également l'établissement des connexions sécurisées de Codex.

Résolution :

• Configuration réseau requise : l'accès aux API d'OpenAI doit être fonctionnel. Assurez-vous que les routes réseau vers les domaines requis sont autorisées dans la configuration globale de vos accès. Une connexion active dans le navigateur ne garantit pas que les requêtes lancées depuis le terminal soient autorisées.
• Configuration des proxies dans le terminal : configurez les variables d'environnement standard HTTP_PROXY et HTTPS_PROXY pour que les requêtes lancées par Codex soient routées correctement.
• Gestion des certificats de sécurité d'entreprise : si votre pare-feu d'entreprise s'interpose dans la liaison sécurisée sous forme de proxy TLS déchiffrant, importez le certificat d'autorité de l'entreprise (format PEM) en renseignant la variable d'environnement dédiée :

export CODEX_CA_CERTIFICATE=/chemin/certificat-corporate-ca.pem
codex login

Codex prend en compte ce certificat personnalisé pour l'ensemble des liaisons HTTPS et WebSocket associées à la session. À défaut de cette variable, l'outil utilise la variable standard SSL_CERT_FILE.

Si votre connexion internet fonctionne sur votre navigateur mais que Codex échoue à s'authentifier, l'incident découle généralement d'un certificat système d'entreprise non reconnu par les requêtes du CLI. Déclarer la variable CODEX_CA_CERTIFICATE résout ce type de blocage.

💡 Résumé en une phrase : Assurez-vous du bon routage des flux dans votre terminal et déclarez le certificat de sécurité de votre pare-feu d'entreprise via la variable CODEX_CA_CERTIFICATE en cas d'erreur de négociation SSL.

---

05 Modèles non disponibles ou erreurs de chargement

Symptôme : le sélecteur /model n'affiche pas le modèle recherché, ou l'exécution d'une commande renvoie une erreur indiquant que le modèle configuré n'est pas disponible.

Cause : la liste des modèles accessibles dépend de votre type d'authentification (compte ChatGPT avec abonnement ou clé API standard), de la couverture de votre formule, du statut d'expérimentation des modèles ou de l'obsolescence de la version configurée.

Résolution :

• Se référer à la liste retournée par la session : n'utilisez pas de noms de modèles obsolètes. Le modèle de référence actuel est gpt-5.5 (phare), secondé par gpt-5.4-mini (tâches courantes et sous-agents). Ces modèles sont accessibles par défaut.
• Accès au modèle gpt-5.3-codex-spark : ce modèle de test instantané est actuellement restreint aux formules d'abonnement ChatGPT Pro. Son absence de l'interface indique simplement que votre compte ne dispose pas des droits requis.
• Vérifier les configurations de modèles obsolètes : si la commande de lancement échoue, validez la valeur déclarée dans votre fichier de configuration ~/.codex/config.toml ou dans les paramètres --model du CLI. Assurez-vous de ne plus faire référence aux versions obsolètes gpt-5.2 ou gpt-5.3-codex qui ont été retirées des accès standards.
• Vérifier le modèle actif : lancez la commande slash /status en cours de session pour valider le modèle en cours d'utilisation.

💡 Résumé en une phrase : La liste des modèles varie selon les comptes de facturation. Fiez-vous aux choix proposés dans le sélecteur /model et supprimez les configurations faisant référence aux modèles obsolètes.

---

06 Refus de modification de fichiers par la sandbox

Il s'agit de la principale difficulté d'appropriation du fonctionnement sécurisé de Codex.

Symptôme : Codex affiche des analyses ou résout des questions, mais renvoie une erreur d'écriture ou demande une confirmation de validation pour chaque écriture de fichier ou exécution de script.

Cause : ce comportement est normal et garantit la sécurité de votre système. Par défaut, Codex limite les droits d'écriture sur votre espace disque local. La sandbox bloque les modifications de fichiers en dehors du répertoire du projet, interdit les accès réseau et requiert votre validation pour l'exécution des commandes sensibles.

Analogie : L'accès aux répertoires partagés d'entreprise. Par défaut, un utilisateur dispose d'accès en lecture seule sur les projets tiers. Pour appliquer des modifications de code ou lancer des scripts d'initialisation, il doit disposer d'un rôle avec accès en écriture sur le répertoire de travail. La sandbox de Codex applique ce même principe d'isolation.

Résolution (deux options selon vos besoins) :

• Modification ponctuelle par option du CLI : utilisez les options --sandbox (raccourci -s) et --ask-for-approval (raccourci -a) au lancement de la session. Pour un développement local standard, utilisez la combinaison suivante (modifications locales autorisées, demandes de confirmation limitées aux actions hors projet) :

  codex --sandbox workspace-write --ask-for-approval on-request

  Les détails des différents niveaux de permissions sont présentés au chapitre 15 Permissions, sandbox et approbation.

• Configuration permanente dans le fichier de configuration : configurez la clé d'accès globale dans ~/.codex/config.toml à l'aide des nouveaux profils de permissions (Beta) :

Profil de permissions	Droits d'écriture	Usage recommandé
:read-only	Modifications interdites	Analyse et diagnostic sans altération de code
:workspace	Écriture autorisée dans le projet et les dossiers temporaires	Développement local standard au quotidien
:danger-full-access	Droits d'écriture complets sans restrictions	À réserver aux conteneurs ou aux serveurs de test isolés

Déclarez le profil souhaité à l'aide de la clé default_permissions. Attention : n'associez pas les deux méthodes de configuration dans vos fichiers. Si la clé historique sandbox_mode ou l'option --sandbox est déclarée, Codex utilise la logique de configuration standard et ignore les nouveaux profils de permissions.

Évitez de configurer le mode de sandbox global de votre poste de travail sur danger-full-access. Si vous lancez une commande de nettoyage dans un répertoire non suivi par Git, l'agent peut modifier ou supprimer des fichiers personnels situés en dehors de votre espace de travail. Conservez la protection par défaut du profil :workspace.

💡 Résumé en une phrase : La sandbox bloque par défaut les écritures. Activez le profil de permissions :workspace dans votre configuration pour autoriser les modifications locales de manière sécurisée.

---

07 Échecs de connexion des connecteurs MCP

Symptôme : après configuration d'un serveur MCP, ses outils ne sont pas visibles par Codex ou la liaison renvoie une erreur de connexion au démarrage.

Cause : les serveurs MCP s'exécutent dans des processus isolés. Les échecs découlent d'une erreur de syntaxe dans la déclaration de la commande, de dépendances manquantes au sein du processus serveur, de l'absence de variables d'environnement requises (ex. : clés API de service) ou du blocage réseau de la sandbox sur les appels externes.

Résolution :

• Valider l'exécution autonome du processus : ouvrez un terminal indépendant et lancez directement la commande de démarrage du serveur MCP pour analyser ses logs de console. La majorité des erreurs (chemin d'accès erroné, dépendance npm manquante, absence d'option système) sont identifiées à cette étape.
• Vérifier la configuration du fichier config.toml : assurez-vous que les arguments de lancement, les chemins d'accès et les variables d'environnement déclarés dans la section [mcp_servers.<nom>] correspondent précisément aux spécifications du serveur MCP.
• Autoriser les accès réseau de la sandbox : si le service MCP doit interroger des API réseau externes, vérifiez que les règles de la sandbox autorisent les flux de communication réseau.
• Analyser les logs de Codex : consultez les fichiers de trace système pour identifier si l'erreur survient lors du démarrage du processus ou lors de la phase de négociation de protocole.

💡 Résumé en une phrase : Pour résoudre un échec MCP, exécutez d'abord le processus serveur dans un terminal séparé afin de lire les messages d'erreur et de valider les dépendances.

---

08 Perte de pertinence des réponses en fin de session

Symptôme : après une session prolongée, le modèle commence à commettre des erreurs de syntaxe simples, ignore les consignes déclarées précédemment ou reproduit des anomalies déjà résolues.

Cause : la fenêtre de contexte (la mémoire de travail de la session active) est saturée. L'accumulation de l'historique des échanges élimine les consignes d'initialisation les plus anciennes du contexte de traitement.

Analogie : La capacité de mémorisation lors d'une réunion. Si la discussion se prolonge sur plusieurs heures en abordant de nombreux sujets techniques, les participants finissent par oublier les décisions prises en début de séance. C'est le cas pour la mémoire de Codex.

Résolution (choisir la commande selon l'objectif) :

• Pour poursuivre la tâche en cours : utilisez la commande slash /compact. Codex génère un résumé synthétique de l'historique pour libérer de l'espace de contexte tout en conservant les informations importantes du développement.
• Pour démarrer une nouvelle tâche : utilisez la commande slash /new pour ouvrir un fil de discussion vide sans interférences avec les sujets précédents, ou /clear pour réinitialiser l'affichage de l'interface.
• Vérifier l'état de la mémoire : lancez la commande slash /status en cours de session pour évaluer la capacité restante et anticiper les baisses de performance. Prenez l'habitude de compresser le contexte avant que le modèle ne commence à perdre en précision.

Type d'action	Commande de session	Impact sur le contexte
Poursuivre le travail en cours	/compact	Compresse l'historique et libère des ressources
Commencer une nouvelle tâche	/new	Ouvre une session vide sans pollution de contexte
Réinitialiser l'interface de travail	/clear	Vider l'affichage et démarrer une nouvelle session
Diagnostiquer la mémoire disponible	/status	Affiche l'espace de contexte restant

💡 Résumé en une phrase : Si le modèle perd en précision, compressez la session avec /compact pour libérer la mémoire de travail, ou ouvrez une session vide avec /new pour débuter une autre tâche.

---

09 Facturation et consommation de crédits élevées

Symptôme : votre formule d'abonnement indique une consommation excessive de quotas ou vos rapports de facturation par clé API sont plus élevés que prévu.

Cause : l'utilisation systématique des modèles les plus lourds associés à des niveaux d'intensité de raisonnement élevés pour des tâches triviales (comme le formatage de fichiers ou les petits commits) consomme vos crédits inutilement.

Résolution :

• Gérer les quotas d'abonnement : réservez le modèle principal gpt-5.5 et les intensités de raisonnement élevées aux développements d'architecture ou aux tâches complexes. Utilisez le modèle gpt-5.4-mini et des intensités plus faibles pour le travail courant.
• Optimiser les coûts de facturation de l'API : vérifiez la valeur de la clé model_reasoning_effort configurée par défaut dans votre fichier ~/.codex/config.toml (par exemple, la forcer à xhigh génère des coûts de calcul importants pour des corrections de fautes de frappe). Utilisez une intensité intermédiaire medium ou low au quotidien.
• Déléguer les exécutions de routine : configurez vos sous-agents pour qu'ils exécutent le modèle léger gpt-5.4-mini lors des phases d'analyse préliminaire ou d'écriture des tests.

💡 Résumé en une phrase : Adaptez la configuration du modèle et l'intensité du raisonnement selon la complexité des tâches pour optimiser votre consommation de crédits et maîtriser vos coûts.

---

10 Gestion des erreurs de modification de fichiers sous Windows

Symptôme : les chemins absolus ne sont pas reconnus par l'interface, les sandbox génèrent des blocages inattendus ou des erreurs de fin de ligne altèrent la structure de vos fichiers de code.

Cause : l'implémentation de la sandbox et la gestion des chemins diffèrent entre Windows et les systèmes Unix (macOS / Linux). Les conversions de fins de lignes par Git sous Windows génèrent également des diffs illisibles pour Codex.

Résolution :

• Environnement d'exécution recommandé : pour obtenir des comportements cohérents avec les guides Unix, utilisez WSL2 de bout en bout et clonez vos projets directement au sein du répertoire de l'environnement Linux (~/).
• Résolution des anomalies Windows : l'installation de Codex, la gestion de la sandbox et les techniques pour fixer les fins de lignes en LF sont présentées en détail au chapitre 33 Utilisation sous Windows.
• Restauration de fichiers modifiés : Codex applique ses modifications directement sur vos fichiers système. Pour pouvoir annuler une modification erronée, effectuez un commit propre de votre dépôt avec Git avant de confier une tâche de modification à Codex. Vous pourrez ainsi restaurer l'état précédent à l'aide de la commande git restore.

💡 Résumé en une phrase : Pour les anomalies propres à Windows (sauts de ligne, sandbox, chemins), référez-vous au chapitre 33. Assurez-vous d'effectuer un commit de votre projet avant chaque tâche pour pouvoir annuler les modifications en cas d'erreur.

---

Synthèse

Ce chapitre a listé les solutions aux incidents d'utilisation les plus fréquents :

• Le diagnostic de premier niveau : validation systématique de la version, du statut de connexion et des permissions actives avec les commandes codex --version, codex login status et /status.
• L'installation et la connexion : configuration des variables PATH de npm, authentification par code d'appareil (--device-auth) pour les sessions distantes et résolution des proxies de sécurité d'entreprise avec CODEX_CA_CERTIFICATE.
• La sécurité : activation du profil de permissions :workspace pour lever les refus d'écriture de la sandbox sur votre projet.
• La gestion de la mémoire : utilisation de /compact pour libérer la fenêtre de contexte en cours de tâche, et de /new pour démarrer un nouveau sujet.
• La maîtrise des coûts : sélection du modèle et de l'intensité de raisonnement adaptés à la complexité des développements.

Vous disposez maintenant de la méthodologie de diagnostic pour identifier et corriger les blocages techniques courants. Appliquer ces étapes de vérification structurées vous permet de maintenir votre environnement de développement fonctionnel.

---

Le chapitre suivant 〔38 Glossaire〕 regroupe les définitions des principaux concepts de Codex (sandbox, MCP, sous-agents, etc.) pour servir de dictionnaire de référence.

---

Lectures recommandées

• Bonnes pratiques : optimiser son flux de travail avec l'IA
• Introduction à Codex et modes d'accès
• Les quatre flux de travail types : exploration, correction, refactorisation, tests