Pourquoi votre config Codex ne fonctionne pas : le problème du dossier .codex/

Ma config Codex ne s’appliquait pas. J’ai modifié config.toml, ajouté des règles dans AGENTS.md, relu la documentation deux fois. Rien ne changeait. L’agent ignorait tout.

J’ai fini par décortiquer toute la structure des dossiers. Le problème ne venait pas de ce que j’avais écrit dans les fichiers. Il venait de là où ces fichiers étaient placés.

Deux objectifs dans un seul dépôt

Codex cherche à résoudre deux choses en même temps. D’un côté, l’expérimentation rapide avec ses propres fonctionnalités en bêta. De l’autre, la compatibilité multi-agents, un standard partagé que des outils comme Claude Code ou OpenCode peuvent également lire.

Cette séparation produit deux dossiers.

.codex/ est l’espace de configuration propre à Codex. Les politiques de sandbox, les règles d’approbation et les garde-fous d’exécution s’y trouvent. .agents/ est le format partagé. Les skills, les plugins et le registre du marketplace vivent de ce côté, lisibles par tout agent qui suit ce standard.

Je n’étais pas au courant de cette séparation au départ. J’ai glissé un fichier SKILL.md dans .codex/ et le skill n’a jamais chargé. Le déplacer dans .agents/skills/ a réglé le problème immédiatement. La frontière est stricte : si un autre agent doit pouvoir le lire, ça va dans .agents/. Tout le reste va dans .codex/.

Les deux dossiers bénéficient d’une protection en lecture seule en mode workspace-write, au même titre que .git/.

La config projet et la config utilisateur portent le même nom

Il y a un .codex/ à la racine de votre projet et un ~/.codex/ dans votre répertoire personnel. Ils font des choses complètement différentes.

Le .codex/ du projet contient les paramètres que vous partagez avec votre équipe : politiques de sandbox, workflows d’approbation, définitions d’agents. ~/.codex/ contient votre état personnel : tokens d’authentification, historique des commandes, fichiers de gestion des worktrees.

J’ai créé un agent reviewer dans ~/.codex/agents/ et je ne comprenais pas pourquoi mes collègues ne l’avaient pas. Il n’existait que sur ma machine. Déplacer le fichier vers .codex/agents/reviewer.toml dans le projet a suffi pour qu’il voyage avec le dépôt à chaque clone.

La confusion s’accentue parce que Codex est encore en bêta. Les fichiers de worktree de l’application desktop, les données de session et les credentials d’authentification s’accumulent tous dans ~/.codex/ sans séparation claire. La frontière entre “mes affaires” et “les affaires du projet” est plus floue qu’elle ne devrait l’être.

La priorité des configs suit un ordre précis : la config managée prime sur les overrides de session, qui priment sur la config utilisateur. Quand quelque chose ne s’applique pas, vérifiez à quel niveau vous éditez.

Le niveau de confiance est le vrai verrou

C’est là que la plupart des gens restent bloqués, et j’y ai perdu un temps considérable avant de comprendre pourquoi.

Codex ne charge pas le .codex/ d’un projet depuis des dépôts non fiables. Pas du tout. Vous pouvez modifier config.toml autant que vous voulez dans un dépôt fraîchement cloné, rien ne s’appliquera. Le fichier est là, la syntaxe est correcte, et Codex ignore tout en silence.

La raison fait sens une fois qu’on la comprend. .agents/ ouvre une voie pour que des skills externes entrent dans votre environnement. N’importe quel dépôt pourrait embarquer une config malveillante. Codex a donc fait ce compromis : une compatibilité plus large avec l’écosystème d’agents, mais une vérification de confiance plus stricte pour les paramètres fournis par les dépôts. Vous devez explicitement marquer un projet comme fiable avant que sa config .codex/ s’active.

Définissez projects.<path>.trust_level = "trusted" dans votre config utilisateur. L’accès réseau est aussi bloqué par défaut, avec la recherche web proposant trois modes : cached, live ou disabled. Même en mode workspace-write, .git/ et .codex/ restent protégés en écriture.

J’ai passé environ une heure à modifier un config.toml de projet qui était complètement ignoré parce que je n’avais pas défini le niveau de confiance. Aucun message d’erreur, aucun avertissement. Juste le silence. C’est probablement la source de frustration la plus fréquente lors de la configuration de Codex, et de meilleures indications ici feraient gagner beaucoup de temps à beaucoup de personnes.

La complexité n’est pas accidentelle

La structure des dossiers est désordonnée, mais pas au hasard. Codex poursuit deux objectifs qui tirent dans des directions opposées.

L’itération rapide en bêta signifie que .codex/ accumule des fichiers de config, des définitions de règles, des hooks et des artefacts de gestion d’application à un rythme qui dépasse la documentation. La compatibilité multi-agents signifie que .agents/ a besoin d’une structure séparée et portable pour les skills et le contenu du marketplace. Et parce que .agents/ ouvre la porte à du code externe, la couche de vérification de confiance devait nécessairement exister.

Quand vous ne savez pas où mettre un fichier, posez-vous une seule question : est-ce spécifique à Codex, ou d’autres agents doivent-ils le lire aussi ? La première réponse pointe vers .codex/. La seconde pointe vers .agents/.

Quand votre config ne fonctionne pas, ne commencez pas par modifier le contenu du fichier. Vérifiez dans quel dossier il se trouve et si le dépôt est marqué comme fiable. C’est presque toujours là que se trouve le problème.