OpenAI Codex : coder avec un agent IA, de VS Code au fichier AGENTS.md

OpenAI Codex est l’agent de code d’OpenAI : vous lui décrivez une tâche en français, il explore votre projet, écrit ou modifie le code, lance les commandes et les tests, puis vous présente les changements à valider. Disponible dans le terminal, dans VS Code et dans le cloud via ChatGPT, il fait partie de la nouvelle génération d’outils qui ne se contentent plus de suggérer du code, mais l’exécutent.

Ce guide s’adresse aux développeurs, créateurs d’applications, makers et profils techniques qui veulent comprendre comment fonctionne un agent de code et comment l’utiliser sans perdre le contrôle de leur projet. Vous y verrez l’installation, la prise en main de l’interface et des sessions, la rédaction de prompts efficaces, le fichier AGENTS.md, la gestion du contexte avec Git, les skills et les serveurs MCP.

Qu’est-ce qu’OpenAI Codex ?

OpenAI Codex désigne aujourd’hui une famille d’outils de développement agentiques : une interface en ligne de commande open source (Codex CLI), une extension pour VS Code et les éditeurs compatibles, et un agent dans le cloud accessible depuis ChatGPT. Tous s’appuient sur des modèles d’OpenAI optimisés pour la programmation et partagent la même logique : comprendre une tâche, agir dans le code, vérifier, rendre compte.

Le nom a une histoire. En 2021, Codex était un modèle d’OpenAI entraîné sur du code, qui a alimenté les débuts de GitHub Copilot, avant d’être retiré. Depuis 2025, OpenAI a réutilisé ce nom pour ses outils d’agent de code. Si vous lisez un article ancien sur « l’API Codex », il parle très probablement de ce premier modèle, qui n’existe plus.

Comment fonctionne un agent de code

Un agent de code fonctionne en boucle :

1. Il lit la demande, le fichier AGENTS.md et les fichiers pertinents du projet.
2. Il planifie les modifications nécessaires.
3. Il agit : il crée ou modifie des fichiers, exécute des commandes (installation, tests, build).
4. Il vérifie le résultat, lit les erreurs éventuelles et corrige.
5. Il rend compte : résumé des changements, différences de code à relire.

La différence avec un assistant de chat tient aux étapes 3 et 4 : l’agent n’attend pas que vous copiiez son code et reveniez avec l’erreur, il la voit et la corrige lui-même, dans les limites des autorisations que vous lui donnez.

Pourquoi coder avec l’IA et un agent comme Codex ?

Un agent de code est particulièrement utile sur les tâches bien définies, où le résultat attendu est clair :

• Créer une application ou une fonctionnalité à partir d’une description fonctionnelle.
• Comprendre une base de code inconnue avant d’y intervenir.
• Corriger un bug à partir d’un message d’erreur ou d’un ticket.
• Écrire des tests pour sécuriser un code existant.
• Refactoriser : renommer, découper, moderniser une dépendance.
• Relire du code : repérer les bugs, les failles et les incohérences avant une fusion.
• Déléguer en parallèle : dans le cloud, plusieurs tâches peuvent tourner pendant que vous travaillez sur autre chose.

Le gain dépend de la qualité du cadrage. Un agent sans consignes produit du code générique, qui ignore vos conventions. Un agent bien configuré, avec un AGENTS.md précis et des demandes claires, devient un collaborateur fiable.

Comment utiliser OpenAI Codex : les étapes

Exemple fil rouge : une petite application web de gestion de tâches, construite puis enrichie avec Codex.

Étape 1 — Choisir son point d’entrée

Codex se présente sous plusieurs formes, qui partagent la même logique :

Interface	Où	Idéal pour
Extension VS Code	Dans l’éditeur (VS Code et éditeurs compatibles)	Travailler au quotidien en voyant le code et les différences
Codex CLI	Terminal	Développeurs à l’aise en ligne de commande, scripts, serveurs
Codex dans le cloud	Depuis ChatGPT, connecté à GitHub	Déléguer des tâches en arrière-plan, en parallèle

Pour débuter, l’extension VS Code est la plus confortable : vous voyez en temps réel les fichiers modifiés et pouvez relire chaque changement.

Étape 2 — Installer et se connecter

Pour l’extension, ouvrez le panneau Extensions de VS Code, recherchez l’extension officielle Codex d’OpenAI et installez-la. Connectez-vous ensuite avec votre compte ChatGPT ou une clé API.

Pour la ligne de commande, Codex CLI s’installe via npm (Node.js doit être installé), puis se lance dans le dossier du projet :

npm install -g @openai/codex
cd mon-projet
codex

Au premier lancement, Codex vous demande de vous authentifier. Vérifiez dans la documentation officielle d’OpenAI les autres méthodes d’installation disponibles pour votre système.

Étape 3 — Maîtriser l’interface et les sessions

Chaque conversation avec Codex est une session : elle garde en mémoire la demande, les fichiers consultés et les actions réalisées. Quelques commandes à connaître dans la CLI :

• /model pour choisir le modèle et son niveau de raisonnement ;
• /approvals pour régler le niveau d’autorisation ;
• /new pour démarrer une nouvelle conversation sans quitter Codex ;
• /compact pour résumer une session devenue longue ;
• /review pour demander une relecture des modifications en cours.

Les niveaux d’autorisation sont essentiels. En lecture seule, Codex analyse sans rien modifier. En mode automatique, il modifie les fichiers du dossier de travail et demande votre accord pour les actions sortant de ce cadre. L’accès complet supprime ces garde-fous : réservez-le aux environnements isolés.

Étape 4 — Écrire un premier prompt et créer une application

Un bon prompt pour un agent de code précise l’objectif, la stack, le périmètre et le critère de réussite :

Crée une application web de gestion de tâches en React + TypeScript avec Vite.
Fonctionnalités : ajouter une tâche, la marquer comme faite, la supprimer,
filtrer par statut (toutes, à faire, faites). Les tâches sont sauvegardées
dans le navigateur. Interface en français, sobre et utilisable sur mobile.
Quand c'est terminé : lance le build, corrige les erreurs éventuelles,
puis explique-moi comment démarrer l'application en local.

Le critère de fin (« lance le build et corrige ») est important : il pousse l’agent à vérifier son propre travail au lieu de s’arrêter à l’écriture du code.

Étape 5 — Visualiser et tester l’application dans VS Code

Ouvrez le dossier du projet dans VS Code, lancez le serveur de développement dans le terminal intégré et ouvrez l’adresse locale affichée dans votre navigateur. Testez chaque fonctionnalité comme un utilisateur. Si quelque chose ne fonctionne pas, décrivez précisément le problème :

Quand je coche une tâche puis que je recharge la page, elle redevient « à faire ».
Attendu : l'état coché est conservé. Trouve la cause, explique-la,
puis corrige sans modifier le reste de l'interface.

Étape 6 — Configurer le fichier AGENTS.md

Le fichier AGENTS.md, placé à la racine du dépôt, est lu par Codex au début de chaque tâche. La commande /init peut en générer une première version. Complétez-le avec vos règles :

Projet : application de gestion de tâches (React, TypeScript, Vite).

Commandes :
- Installer : npm install
- Développement : npm run dev
- Vérifier avant de terminer : npm run build puis npm run lint

Conventions :
- Composants dans src/components, un composant par fichier.
- Noms de variables en anglais, textes d'interface en français.
- Pas de nouvelle dépendance sans le justifier.

Règles :
- Ne jamais écrire de clé ou de secret dans le code.
- Pour une modification touchant plus de trois fichiers, proposer un plan d'abord.

Vous pouvez placer des fichiers AGENTS.md supplémentaires dans des sous-dossiers pour des règles propres à une partie du projet. Gardez-les courts et concrets : ce sont des consignes, pas une documentation exhaustive.

Étape 7 — Référencer les fichiers et demander un plan

Pour concentrer l’agent sur la bonne partie du code, mentionnez explicitement les fichiers concernés (dans la zone de saisie, le caractère @ permet de rechercher et d’insérer un fichier). Pour les modifications importantes, demandez un plan avant toute écriture :

Je veux ajouter des catégories aux tâches (Travail, Personnel, Courses),
avec un filtre par catégorie. Fichiers concernés : @src/App.tsx et
@src/components/TaskList.tsx. Propose d'abord un plan détaillé :
fichiers modifiés, nouveaux composants, impact sur les données existantes.
N'écris aucun code avant ma validation.

Étape 8 — Gérer le contexte et versionner avec Git

Initialisez Git dès le départ et faites un commit après chaque étape validée. Si Codex prend une mauvaise direction, vous revenez à la dernière version stable en une commande. Relisez les différences avant chaque commit : c’est le moment où l’on repère un fichier modifié par erreur.

Côté contexte, repartez d’une nouvelle session pour chaque tâche indépendante. Une session trop longue accumule des informations obsolètes et dégrade la précision des réponses. Si vous devez interrompre un travail, la CLI permet de reprendre une session précédente.

Étendre Codex avec les skills et le protocole MCP

Les skills (compétences)

Une skill est un ensemble d’instructions, éventuellement accompagné de scripts ou de modèles, que Codex charge quand la tâche le justifie. Elle se présente sous la forme d’un dossier contenant un fichier SKILL.md. Exemples utiles :

• une procédure de revue de code propre à votre équipe ;
• la façon de créer un nouveau composant selon vos conventions ;
• la génération d’un rapport de version à partir de l’historique Git.

La différence avec AGENTS.md : AGENTS.md contient les règles permanentes du projet, lues à chaque fois ; une skill contient un savoir-faire spécifique, chargé seulement quand il est pertinent. Cela garde le contexte léger.

Les serveurs MCP

Le Model Context Protocol (MCP), standard ouvert publié par Anthropic et adopté par de nombreux outils dont Codex, permet à l’agent d’accéder à des services externes : documentation à jour, base de données, navigateur, outils de gestion de projet. Dans Codex, les serveurs se déclarent dans le fichier de configuration de l’utilisateur (config.toml) ou via la commande dédiée de la CLI :

[mcp_servers.documentation]
command = "npx"
args = ["-y", "nom-du-serveur-mcp"]

Une fois le serveur déclaré, l’agent peut appeler ses outils au cours d’une tâche. Commencez par un seul serveur réellement utile, par exemple l’accès à la documentation de vos bibliothèques, puis ajoutez-en d’autres au fil des besoins : chaque serveur supplémentaire alourdit le contexte et multiplie les outils entre lesquels l’agent doit choisir. N’installez que des serveurs de confiance : ils s’exécutent sur votre machine avec les droits que vous leur donnez.

Bien rédiger ses prompts pour un agent de code

Les principes qui font la différence avec Codex :

1. Un objectif, un critère de réussite : « la fonctionnalité est terminée quand les tests passent et que le build réussit ».
2. Le périmètre explicite : quels fichiers toucher, lesquels ne pas modifier.
3. Le contexte métier : qui utilise l’application et pourquoi, ce qui guide les choix d’interface et de validation.
4. Un plan avant le code pour tout ce qui dépasse une petite modification.
5. Des bugs décrits précisément : étapes, résultat attendu, résultat obtenu, message d’erreur exact.
6. Une demande d’explication : faire expliquer les choix permet de repérer une incompréhension et d’apprendre.

Ces règles valent pour tous les agents. Pour une approche plus globale du développement piloté par l’IA, notre guide du vibe coding présente la méthode de l’idée au déploiement.

Les erreurs fréquentes avec Codex (et comment les éviter)

Erreur	Conséquence	Solution
Projet sans Git	Impossible d’annuler proprement une modification	git init et commit à chaque étape validée
Accès complet sur un projet réel	Commandes risquées exécutées sans contrôle	Garder un niveau d’autorisation avec validation
Demande vague (« améliore l’app »)	Modifications dispersées et imprévisibles	Objectif, périmètre et critère de réussite précis
Pas d’AGENTS.md	Conventions ignorées, dépendances ajoutées au hasard	Créer et maintenir un AGENTS.md court
Session unique pour tout le projet	Contexte saturé, erreurs de compréhension	Nouvelle session par tâche, résumé si besoin
Valider sans relire les différences	Fichiers modifiés par erreur, régressions	Relire chaque diff avant de commiter
Confondre l’ancien modèle Codex et l’outil actuel	Tutoriels obsolètes, commandes inexistantes	Se fier à la documentation officielle récente

Codex vs Claude Code et les autres agents de code

Critère	OpenAI Codex	Claude Code	Cursor	Bolt.new
Éditeur	OpenAI	Anthropic	Anysphere	StackBlitz
Forme	Agent : CLI, extension IDE, cloud	Agent : CLI, extensions IDE, application, web	Éditeur de code avec IA intégrée	Générateur d’applications dans le navigateur
Fichier de consignes	AGENTS.md	CLAUDE.md	Règles de projet	Instructions du projet
Extensions	MCP, skills	MCP, skills, hooks, plugins, sous-agents	MCP, règles	Intégrations intégrées (base de données, déploiement)
Idéal pour	Écosystème OpenAI, délégation dans le cloud	Tâches longues, workflow très personnalisable	Expérience d’édition intégrée	Prototyper sans installation

Dans la pratique, les agents se rapprochent : même logique de fichier de consignes, de MCP et de skills. Choisissez celui qui s’intègre le mieux à vos outils et à votre abonnement. Pour comparer en détail, consultez nos guides sur Claude Code et le protocole MCP, sur l’éditeur Cursor et sur Bolt.new pour le prototypage sans installation. Et si vous souhaitez aller vers des agents qui ne codent pas uniquement, voyez comment créer un agent IA.

Comment apprendre OpenAI Codex et progresser ?

La progression que nous recommandons :

1. Prise en main : interface, sessions, niveaux d’autorisation, premiers échanges en lecture seule sur un projet existant.
2. Premier projet : une petite application créée par prompt, testée dans VS Code.
3. Méthode : AGENTS.md, référencement des fichiers, plan avant exécution, Git systématique.
4. Extension : skills pour vos tâches récurrentes, serveurs MCP pour vos outils.

Pour avancer vite, la formation pour maîtriser Codex d’OpenAI et les agents de code d’EspritAcadémique condense ce parcours en une heure quarante-cinq de pratique, sans prérequis. Elle aborde notamment :

• le tour d’horizon de Codex et du protocole MCP, puis la maîtrise de l’interface et des sessions ;
• l’optimisation des prompts et la création d’une application pas à pas ;
• l’installation et la configuration de l’extension VS Code pour visualiser son application ;
• le fichier agents.md, la gestion du contexte de session et de Git ;
• le référencement des fichiers, le mode plan et les skills.

En résumé

OpenAI Codex est un agent de code qui travaille directement dans votre projet, depuis le terminal, VS Code ou le cloud. Pour en tirer le meilleur, cadrez-le : un AGENTS.md concis, des demandes avec objectif et critère de réussite, un plan avant les modifications importantes, Git à chaque étape et un niveau d’autorisation adapté. Les skills et les serveurs MCP viennent ensuite étendre ses capacités à vos propres méthodes et outils.