Utiliser Codex CLI : le guide pas à pas

Pour utiliser Codex CLI, installez-le avec une seule commande, lancez codex dans un dossier de projet, connectez-vous avec votre compte ChatGPT, puis décrivez la modification voulue en langage courant. Codex lit le code, modifie des fichiers et lance des commandes dans votre projet, et demande avant de sortir du dossier ou d’accéder au réseau.

Voilà la boucle de base. Ce guide couvre le reste : les modes d’approbation et de sandbox, le fichier AGENTS.md, config.toml, les serveurs MCP, les commandes du quotidien, la reprise de sessions et quelques habitudes qui rendent Codex plus fiable. Tout ce qui suit s’appuie sur la documentation officielle de Codex publiée par OpenAI, telle qu’elle était en octobre 2026.

Ce qu’est Codex CLI

Codex CLI est l’agent de code d’OpenAI pour le terminal. Il tourne en local, travaille sur le dossier depuis lequel vous le lancez et peut exécuter vos tests, vos linters et git. Le même Codex existe aussi en extension d’IDE, en application de bureau et en version cloud, et tous partagent votre connexion. Si vous hésitez entre plusieurs agents, Claude Code vs Codex et Codex vs Gemini CLI les comparent en détail. En bref, Codex est un agent de code et non un outil d’autocomplétion : vous lui confiez une tâche, il la planifie et la mène à bien.

Étape 1 : installer Codex CLI

OpenAI fournit un script d’installation pour chaque plateforme, et le CLI est aussi disponible sur npm et Homebrew.

Pour mettre à jour, relancez le même script, exécutez codex update ou passez par votre gestionnaire de paquets (brew upgrade --cask codex). Vérifiez que tout fonctionne :

codex --version

Étape 2 : se connecter

Placez-vous dans un projet et lancez Codex :

cd mon-projet
codex

Au premier lancement, Codex vous demande comment vous connecter :

• Sign in with ChatGPT : utilise votre offre ChatGPT, et l’usage est décompté de ses limites. C’est le choix habituel, et le seul qui donne aussi accès à Codex cloud.
• Clé API : utilise une clé API OpenAI, facturée au token. Pratique pour la CI ou si vous préférez payer à l’usage.

Vous pouvez aussi gérer cela depuis le shell. codex login ouvre la connexion dans le navigateur, codex login --device-auth fournit un code d’appareil pour une machine distante ou sans écran, codex login status indique si vous êtes connecté, et codex logout efface les identifiants enregistrés. Pour vous connecter avec une clé sans la taper, transmettez-la par un pipe : printenv OPENAI_API_KEY | codex login --with-api-key.

Au moment où nous écrivons, Codex est inclus dans ChatGPT Free, Go, Plus, Pro, Business, Edu et Enterprise. Les offres supérieures donnent des limites plus élevées ; consultez la page de tarifs Codex d’OpenAI pour les chiffres à jour. Dans une session, /status ou /usage vous montre à tout moment où vous en êtes.

Étape 3 : votre première tâche

Commencez par quelque chose de petit mais réel, pour observer comment Codex travaille :

Explique comment fonctionne l’authentification dans ce projet, puis ajoute
un test pour la réinitialisation du mot de passe. Lance la suite de tests à la fin.

Codex lit les fichiers utiles, annonce ce qu’il compte faire, modifie le code et lance les tests. Quelques réflexes rendent cela plus fluide :

• Tapez @ pour chercher un fichier et le joindre à votre prompt.
• Commencez une ligne par ! pour lancer vous-même une commande shell, par exemple !git status.
• Pendant que Codex travaille, Entrée ajoute des instructions au tour en cours, et Tab met en file un message à envoyer une fois qu’il a fini.
• Échap deux fois avec un champ vide permet de modifier votre message précédent et de repartir de là.
• /diff montre ce qui a changé, fichiers non suivis compris.

Pour des captures d’écran ou des maquettes, joignez des images avec codex --image chemin/fichier.png ou collez-les dans le prompt.

Étape 4 : modes d’approbation et sandbox

C’est la partie à bien comprendre avant de confier de plus gros chantiers à Codex. Codex combine deux réglages : un sandbox qui limite ce que les commandes peuvent techniquement faire, et une politique d’approbation qui décide quand Codex s’arrête pour vous demander.

Dans une session, /permissions bascule entre Auto et Read Only. L’accès réseau est coupé par défaut dans le sandbox workspace-write ; vous pouvez l’activer dans config.toml (voir plus bas) si vos tests en ont besoin.

Si Codex doit écrire dans un second dossier, par exemple une bibliothèque partagée à côté de votre projet, utilisez --add-dir plutôt que de passer en accès complet. OpenAI déconseille explicitement --dangerously-bypass-approvals-and-sandbox (alias --yolo) en dehors d’une VM dédiée et isolée.

Le sandbox repose sur une vraie isolation au niveau du système : Seatbelt sur macOS, bubblewrap avec seccomp sur Linux et un sandbox natif sur Windows. Dans WSL2, Codex utilise le sandbox Linux. Pour une vue d’ensemble de ce qui peut mal tourner avec les agents et de la façon de le limiter, lisez la sécurité des agents de code IA.

Étape 5 : écrire un AGENTS.md

AGENTS.md est un fichier Markdown d’instructions que Codex lit avant de se mettre au travail. Vous y mettez ce que vous répéteriez sinon dans chaque prompt : comment builder et tester, le style de code, les dossiers à ne pas toucher.

Lancez /init dans une session et Codex en génère une première version. Un bon fichier est court et précis :

# AGENTS.md

## Commandes
- Installation : pnpm install
- Tests : pnpm test (à lancer avant de dire qu’une tâche est finie)
- Lint : pnpm lint

## Conventions
- TypeScript en mode strict, pas de any.
- Les nouvelles routes d’API vont dans src/routes et ont besoin d’un test.

## À ne pas faire
- Ne pas modifier les fichiers de src/generated.
- Ne pas ajouter de dépendances sans demander.

Codex cherche ces fichiers dans un ordre précis :

1. Global : ~/.codex/AGENTS.md (ou AGENTS.override.md pour le remplacer temporairement). C’est l’endroit pour vos préférences personnelles.
2. Projet : de la racine git jusqu’au dossier où vous êtes, Codex prend au plus un fichier par répertoire, en regardant d’abord AGENTS.override.md, puis AGENTS.md.

Les fichiers sont assemblés de la racine vers le bas : les instructions d’un sous-dossier arrivent en dernier et l’emportent sur les règles générales. La taille totale est plafonnée à 32 Kio par défaut (project_doc_max_bytes), une raison de plus de rester concis. Comme AGENTS.md est un format partagé, d’autres agents le lisent aussi ; CLAUDE.md vs AGENTS.md explique comment garder un seul jeu de règles pour plusieurs outils.

Étape 6 : config.toml

Les réglages de Codex se trouvent dans des fichiers TOML :

• ~/.codex/config.toml pour vos réglages utilisateur ;
• .codex/config.toml dans un projet, que Codex ne charge qu’une fois le projet marqué comme fiable.

Un petit exemple :

model_reasoning_effort = "medium"
web_search = "cached"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true

model définit le modèle par défaut (lancez /model dans une session pour voir ce que votre compte propose). model_reasoning_effort règle le temps de réflexion du modèle. web_search accepte cached (par défaut), live ou disabled ; l’option --search active la recherche en direct pour une exécution.

Les réglages s’appliquent dans cet ordre, du plus fort au plus faible : options en ligne de commande et -c clé=valeur, configuration du projet, profil nommé choisi avec --profile, configuration utilisateur, et enfin configuration système. Ainsi, codex -c model_reasoning_effort="high" change l’effort pour une exécution sans toucher à vos fichiers. Si vous ne savez plus quelle valeur l’emporte, /debug-config affiche les différentes couches.

Étape 7 : connecter des serveurs MCP

MCP permet à Codex d’utiliser des outils externes : recherche dans la documentation, navigateur, gestionnaire de tickets, base de données. Ajoutez un serveur en une commande :

codex mcp add context7 -- npx -y @upstash/context7-mcp

Tout ce qui suit -- est la commande qui démarre le serveur. Passez des variables d’environnement avec --env VAR=valeur. Pour un serveur distant, utilisez codex mcp add <nom> --url https://..., et s’il utilise OAuth, connectez-vous avec codex mcp login <nom>. codex mcp list affiche ce qui est configuré.

Les mêmes serveurs peuvent être écrits à la main dans config.toml :

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Dans une session, /mcp liste les serveurs actifs et leurs outils. Si le sujet est nouveau pour vous, qu’est-ce qu’un serveur MCP est une bonne introduction. Gardez la liste courte : chaque serveur ajoute des descriptions d’outils à la fenêtre de contexte.

Étape 8 : les commandes à connaître

Les commandes slash s’utilisent dans une session :

Et quelques sous-commandes depuis le shell :

Pour l’automatisation, retenez codex exec. Il affiche le résultat puis s’arrête, accepte --json pour une sortie lisible par une machine et --output-last-message pour enregistrer la réponse finale dans un fichier. En CI, associez-le à un sandbox, par exemple codex exec --sandbox workspace-write "corrige les erreurs de lint".

Étape 9 : reprendre et dupliquer des sessions

Codex enregistre vos conversations en local : fermer le terminal ne fait rien perdre.

• codex resume ouvre une liste des sessions précédentes.
• codex resume --last reprend directement la plus récente du dossier courant ; ajoutez --all pour chercher dans tous les dossiers.
• codex fork (ou /fork dans une session) copie une conversation dans une nouvelle, pour essayer une autre approche sans perdre l’originale.
• Pour les exécutions non interactives, codex exec resume --last reprend la dernière session exec.

Le fork est pratique quand Codex a accumulé un bon contexte sur un problème et que vous voulez tester deux solutions à partir du même point de départ.

Conseils pour de meilleurs résultats

• Commitez avant et après. OpenAI recommande lui-même un point de sauvegarde git avant et après chaque tâche. Si un changement tourne mal, git restore est plus rapide que de discuter avec l’agent.
• Dites comment vérifier. « Lance pnpm test et corrige les échecs » donne de meilleurs résultats que « fais que ça marche ».
• Planifiez les gros changements. Utilisez /plan dès qu’une tâche touche plus de deux ou trois fichiers, et lisez le plan avant que Codex ne commence à modifier.
• Une tâche par conversation. Repartez de zéro avec /new entre des tâches sans rapport ; l’ancien contexte coûte des tokens et embrouille le modèle.
• Compactez les longues sessions. /compact garde l’essentiel et laisse tomber le reste.
• Un worktree pour le travail en parallèle. Deux agents dans le même dossier s’écrasent mutuellement. Les git worktrees donnent à chacun sa propre copie.

Quand un seul terminal ne suffit plus

Une fois Codex installé dans votre quotidien, vous voudrez plusieurs sessions en même temps : une qui corrige un bug, une autre qui écrit des tests, peut-être un second compte quand le premier atteint sa limite. C’est là qu’un seul terminal devient malcommode.

AgentVera est une application de bureau pour macOS, Windows et Linux qui exécute Codex (et d’autres agents CLI) dans de vrais terminaux, côte à côte. Elle utilise la connexion Codex que vous avez déjà. Les détails sont sur la page Codex dans AgentVera.

• Workspace : une grille d’agents par projet, de 1×1 à 5×4. Choisissez le modèle et l’effort par agent ; la liste est lue en direct depuis Codex. Les agents retrouvent leur conversation après un redémarrage.
• Permissions par agent : dans la boîte New agent, choisissez Ask, Auto ou Full access au lieu de retenir des options.
• Worktrees : créez un worktree depuis le panneau Git et lancez-y un agent en un clic.
• Changement de compte : chaque compte Codex a son propre dossier personnel, les limites restantes s’affichent dans la barre d’état, et avec Pro et Team une chaîne de comptes passe au compte suivant quand la limite de 5 heures ou la limite hebdomadaire est atteinte.
• MCP manager : configurez vos serveurs MCP une fois ; ils se branchent sur Codex à chaque lancement.
• Code review : faites relire par un autre agent ce que Codex a modifié avant de fusionner.

La grille, les worktrees, la code review et le MCP manager sont dans l’offre gratuite. Téléchargez AgentVera et essayez-le sur votre propre dépôt.

En résumé

Installez Codex, lancez codex, connectez-vous avec ChatGPT et commencez par une petite tâche réelle. Restez en mode Auto et passez en lecture seule avec /permissions quand vous ne voulez que des réponses. Mettez les règles du projet dans AGENTS.md, vos valeurs par défaut dans config.toml, et n’ajoutez des serveurs MCP que lorsque vous en avez besoin. Commitez avant et après chaque tâche, et utilisez codex resume pour reprendre là où vous en étiez. Si vous voulez aussi essayer l’agent de Google, lisez comment utiliser Gemini CLI.