Codex CLI : la référence technique définitive

TL;DR : Codex est un agent de codage multi-surface qui lit votre base de code, exécute des commandes dans un sandbox au niveau du système d’exploitation, modifie des fichiers et délègue des tâches au cloud. Maîtrisez cinq systèmes essentiels (config.toml, modèle sandbox/approval, AGENTS.md, MCP et skills) et Codex devient un multiplicateur de force. Utilisez les profils pour le changement de contexte, /compact pour gérer le budget de contexte, /goal pour les objectifs de travail persistés, et AGENTS.md pour les instructions de projet inter-outils qui fonctionnent dans Codex, Cursor, Amp et plus encore. GPT-5.5 (lancé le 23 avril 2026) est la valeur par défaut recommandée dans Codex — fenêtre de contexte de 400K dans Codex (1M dans le API), 5 $/30 $ par MTok, SOTA Terminal-Bench 2.0 à 82,7 %.⁸³ Depuis CLI v0.130.0 (8 mai 2026), Codex livre une commande de premier niveau codex remote-control pour le contrôle headless de l’app-server, la résolution view_image multi-environnement, l’authentification Bedrock via les identifiants console-login aws login d’AWS, la pagination des threads de l’app-server, la visibilité des détails de plugin pour les hooks bundlés avec métadonnées de share-link et contrôles de discoverability, le rafraîchissement live de la configuration sur les threads en cours, des métadonnées de trace OpenTelemetry configurables, et un durcissement continu du sandbox sous Linux et Windows. La v0.129.0 (7 mai 2026) a ajouté l’édition modale Vim (/vim), un sélecteur de workflow repensé, un navigateur /hooks dans la TUI, une barre d’état adaptée au thème, le partage d’espace de travail de plugins avec opérations de marketplace, et un changement de cycle de vie /goal. Continuez à préférer les flags explicites de sandbox/approval ou les profils de permission plutôt que l’ancien --full-auto ; js_repl reste supprimé.^86878991

Codex fonctionne comme un agent de codage multi-surface, et non comme un chatbot qui écrit du code. Le CLI lit votre base de code, exécute des commandes dans un sandbox, modifie des fichiers, se connecte à des services externes via MCP et délègue les tâches de longue durée au cloud. Il s’exécute localement mais pense globalement ; la même intelligence alimente cinq surfaces distinctes selon votre façon de travailler, y compris la nouvelle extension Chrome qui exécute Codex dans votre navigateur sans en prendre totalement le contrôle.⁹⁰

La différence entre une utilisation occasionnelle et une utilisation efficace de Codex se résume à cinq systèmes essentiels. Maîtrisez-les et Codex devient un multiplicateur de force :

1. Système de configuration : contrôle le comportement via config.toml
2. Modèle sandbox & approval : régit ce que Codex peut faire
3. AGENTS.md : définit les contrats opérationnels au niveau du projet
4. Protocole MCP : étend les capacités aux services externes
5. Système de skills : empaquette une expertise de domaine réutilisable

J’ai passé des mois à exécuter Codex aux côtés de Claude Code sur des bases de code de production, des pipelines CI/CD et des workflows d’équipe. Ce guide distille cette expérience en la référence complète que j’aurais aimé avoir au démarrage. Chaque fonctionnalité inclut la syntaxe réelle, des exemples de configuration concrets et les cas limites qui piègent même les utilisateurs expérimentés.

Note de stabilité : Les fonctionnalités marquées [EXPERIMENTAL] ou under development sont susceptibles de changer entre les versions. Depuis la v0.130.0 (8 mai 2026), Codex Cloud et le code mode restent expérimentaux ou en cours de développement, tandis que le CLI principal, le sandboxing, AGENTS.md, config.toml, les Skills, les hooks, les outils multi-agents et les plugins constituent des surfaces stables. La v0.130.0 ajoute la commande de premier niveau codex remote-control (point d’entrée plus simple pour un app-server headless contrôlable à distance), la résolution view_image multi-environnement, l’authentification Bedrock via les identifiants console-login aws login d’AWS, la pagination des threads de l’app-server avec vues unloaded / summary / full turn, la visibilité des détails de plugin pour les hooks bundlés ainsi que les métadonnées de share-link et les contrôles de discoverability, le rafraîchissement live de la configuration de l’app-server (les threads en cours captent les changements de configuration sans redémarrage), la suppression du libellé « research preview » dans le bandeau de démarrage de codex exec, des métadonnées de trace OpenTelemetry configurables, un durcissement du démarrage du sandbox Linux, et l’octroi du sandbox Windows pour le cache binaire du runtime desktop.⁹¹ La v0.129.0 (7 mai 2026) a ajouté l’édition modale Vim dans le composer (/vim + default-mode configurable), un sélecteur de workflow TUI repensé (resume/fork plus simple, scrollback brut), le navigateur /hooks, une barre d’état adaptée au thème avec résumés optionnels de PR + branche, le partage d’espace de travail de plugins + les opérations de marketplace + les contrôles d’accès au partage + le filtrage par source, un changement de cycle de vie /goal (les objectifs expérimentaux restent en pause après un resume sauf opt-in explicite), un durcissement du démarrage du sandbox Linux, des améliorations de fiabilité du sandbox Windows, et une montée de Bubblewrap en 0.11.2 avec correctifs de sécurité amont.⁸⁹ La v0.128.0 (30 avril 2026) a introduit les workflows /goal persistés, codex update, des keymaps TUI configurables et des profils de permission étendus ; l’ancien --full-auto reste déprécié et js_repl reste supprimé.⁸⁶⁸⁷

Points clés

• Cinq surfaces, un seul cerveau : CLI, application desktop, extension IDE, tâches cloud et la nouvelle extension Chrome partagent toutes la même intelligence GPT-5.x-Codex, donc choisissez la surface qui correspond à votre flux de travail.⁹⁰
• Sandboxing au niveau OS : Codex applique des restrictions de système de fichiers et de réseau au niveau du noyau (Seatbelt sur macOS, Landlock + seccomp sur Linux), pas à l’intérieur de conteneurs.
• AGENTS.md est cross-tool : Vos instructions de projet fonctionnent dans Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed et plus de 60 000 projets open source. Écrivez une fois, utilisez partout.
• Les profils économisent la surcharge de changement de contexte : Définissez des préréglages de configuration nommés (fast, careful, auto) et basculez entre eux avec --profile.
• La gestion du contexte est essentielle : GPT-5.4 offre 1M de contexte ; GPT-5.4 mini fournit 400K pour le travail des sous-agents ; GPT-5.3-Codex fournit 272K en entrée. Utilisez /compact, des prompts ciblés et des références @file pour gérer les budgets de tokens de manière proactive.

Comment utiliser ce guide

Ceci est une référence de plus de 2 500 lignes — commencez là où votre niveau d’expérience correspond :

La Carte de référence rapide à la fin fournit un résumé scannable de toutes les commandes principales.

Comment fonctionne Codex : le modèle mental

Avant de plonger dans les fonctionnalités, comprenez comment l’architecture de Codex façonne tout ce que vous faites avec lui. Le système opère sur quatre surfaces soutenues par une couche d’intelligence partagée :

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                          │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Couche centrale : La famille de modèles GPT-5.x alimente tout. Au 23 avril 2026, gpt-5.5 est le modèle recommandé quand il est disponible — 400K de contexte dans Codex (1M dans la API), 82,7 % SOTA Terminal-Bench 2.0. gpt-5.4 reste la valeur par défaut de repli pendant le déploiement (1M de contexte, computer use natif).⁸³⁶⁴ Il lit les fichiers, écrit les patchs, exécute les commandes shell et raisonne sur votre base de code. Lorsque le contexte se remplit, Codex compacte la conversation pour libérer de l’espace. Cette couche coûte des tokens.

Couche de sécurité : Chaque commande exécutée par Codex passe par un sandbox au niveau OS. Sur macOS, le framework Seatbelt d’Apple applique des restrictions au niveau du noyau. Sur Linux, Landlock + seccomp filtrent l’accès au système de fichiers et aux appels système. Le sandbox opère au niveau du noyau, pas à l’intérieur de conteneurs. La politique d’approbation décide ensuite quand demander une confirmation humaine.

Couche d’extension : MCP connecte des services externes (GitHub, Figma, Sentry). Les Skills empaquètent des flux de travail réutilisables que Codex charge à la demande. Les Apps se connectent aux connecteurs ChatGPT. La recherche web ajoute un contexte en temps réel depuis Internet.

Couche de surface : CLI pour les utilisateurs avancés du terminal et l’automatisation. Application desktop pour la gestion de projets multi-threadée. Extension IDE pour les boucles édition-compilation-test. Cloud pour les tâches asynchrones qui s’exécutent indépendamment.

L’idée clé : La plupart des utilisateurs n’utilisent qu’une seule surface. Les utilisateurs avancés utilisent les quatre : Cloud pour les tâches longues, CLI pour les opérations de dépôt déterministes, extension IDE pour les boucles de codage serrées, et l’application desktop pour la planification et la coordination.

Table des matières

1. Comment installer Codex ?
2. Démarrage rapide : votre première session
3. Surfaces d’interaction principales
4. Plongée approfondie dans le système de configuration
5. Quel modèle choisir ?
6. Combien coûte Codex ?
7. Cadres de décision
8. Comment fonctionne le système de sandbox et d’approbation ?
9. Comment fonctionne AGENTS.md ?
10. Hooks
11. Qu’est-ce que MCP (Model Context Protocol) ?
12. Code Mode
13. Runtime REPL JavaScript
14. Que sont les Skills ?
15. Plugins
16. Plan Mode et collaboration
17. Système de mémoire
18. Gestion des sessions
19. Mode non interactif (codex exec)
20. Codex Cloud et tâches en arrière-plan
21. L’application desktop Codex
22. Action GitHub et CI/CD
23. SDK Codex
24. Optimisation des performances
25. Comment déboguer les problèmes ?
26. Déploiement en entreprise
27. Bonnes pratiques et anti-patterns
28. Recettes de flux de travail
29. Guide de migration
30. Carte de référence rapide
31. Changelog
32. Références

Comment installer Codex ?

Gestionnaires de paquets

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

# Upgrade to latest
npm install -g @openai/codex@latest

Script d’installation directe (v0.106.0+)

Pour macOS et Linux, un script d’installation en une ligne est disponible comme asset de release GitHub :⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

Le script détecte automatiquement votre plateforme et votre architecture, télécharge le bon binaire et l’ajoute à votre PATH.

Téléchargements des binaires

Pour les environnements sans npm ni Homebrew, téléchargez les binaires propres à chaque plateforme depuis GitHub Releases¹ :

Configuration requise

• macOS : Apple Silicon ou Intel (prise en charge complète du sandbox via Seatbelt)
• Linux : x86_64 ou arm64 (sandbox via Landlock + seccomp)
• Windows : sandbox natif avec jetons restreints (sorti du statut expérimental en v0.100.0). WSL est également pris en charge²

Authentification

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Deux méthodes d’authentification :

1. Compte ChatGPT (recommandé) : connectez-vous avec votre abonnement Plus, Pro, Team, Business, Edu ou Enterprise existant. Accès complet aux fonctionnalités, y compris les tâches cloud.
2. Clé API : définissez-la via la variable d’environnement CODEX_API_KEY ou codex login --with-api-key. Certaines fonctionnalités (cloud threads) peuvent ne pas être disponibles.

Conseil d’expert : le stockage des identifiants est configurable via cli_auth_credentials_store dans config.toml. Options : file (par défaut), keyring (trousseau du système d’exploitation) ou auto (keyring si disponible, sinon file).

Complétions Shell

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Vérifier l’installation

codex --version
# codex-cli 0.130.0

Démarrage rapide : votre première session

Passez de zéro à productif en 5 minutes.

1. Installer et s’authentifier :

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Accéder à un projet :

cd ~/my-project                  # Any git repo works

3. Démarrer Codex :

codex

Vous verrez la TUI interactive. Codex lit automatiquement la structure de votre projet.

4. Poser une question :

> What does this project do? Summarize the architecture.

Codex lit les fichiers clés et explique la base de code. Aucune modification n’est effectuée dans le mode suggest par défaut.

5. Apporter une modification :

> Add input validation to the login endpoint

Codex propose des modifications sous forme de diff. Relisez-les et approuvez avec y, ou rejetez avec n.

6. Utiliser une slash command :

> /plan Refactor the database layer to use connection pooling

Codex crée un plan sans l’exécuter. Relisez le plan, puis approuvez pour lancer l’exécution.

7. Vérifier votre travail :

> /diff

Consultez toutes les modifications que Codex a effectuées pendant la session en cours.

Et ensuite : - Configurez AGENTS.md avec les instructions du projet (voir Comment fonctionne AGENTS.md ?) - Configurez un profil pour votre workflow (voir Profils) - Essayez codex exec pour l’automatisation non interactive (voir Mode non interactif)

Surfaces d’interaction principales

Codex propose quatre interfaces distinctes adossées à la même intelligence. Chaque surface est optimisée pour un schéma de travail différent.

1. CLI interactive (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

L’interface terminal est une application plein écran comportant :

• Composer : saisissez vos prompts, attachez des fichiers avec @, exécutez des commandes shell avec le préfixe !
• Volet de sortie : réponses du modèle en streaming, appels d’outils et sortie de commandes
• Barre d’état : modèle, utilisation de tokens, branche git, mode sandbox

Raccourcis TUI clés :

Changement de barre d’état (v0.121.0) : l’ancien indicateur de fenêtre de contexte dans la barre d’état a été remplacé par un indicateur de pourcentage de contexte montrant le niveau de remplissage de votre fenêtre de contexte. Si vous avez des scripts ou des hooks qui parsent la barre d’état, vérifiez ce changement de format.⁸² Codex affichera également une annonce de mise à jour de CLI lorsqu’une nouvelle version sera disponible.

Slash commands disponibles dans le CLI :

Refonte du sélecteur de workflow (v0.129.0) : la reprise et le fork sont désormais plus accessibles depuis un sélecteur repensé, et un nouveau mode scrollback brut vous permet de faire défiler la transcription non rendue lorsque vous devez copier des commandes ou la sortie du modèle textuellement. Utile pour trier une longue session de débogage ou pour rediriger la sortie vers un autre outil.⁸⁹

2. Codex Desktop App (macOS + Windows)

codex app                    # Launch desktop app (auto-installs if missing)

L’application desktop ajoute des capacités que le CLI n’a pas :

• Multi-tâches : exécutez plusieurs agents en parallèle sur différents projets simultanément
• Isolation par git worktree : chaque thread travaille sur une copie isolée de votre repo
• Revue inline des diffs : indexez, annulez et committez les changements sans quitter l’application
• Terminal intégré : terminal par thread pour exécuter des commandes
• Bifurcation de conversations : embranchez les conversations pour explorer des alternatives
• Fenêtres pop-out flottantes : détachez les conversations dans des fenêtres portables
• Automatisations : planifiez des tâches récurrentes (triage d’issues, surveillance CI, réponse aux alertes)

Quand utiliser l’app vs le CLI : utilisez l’application desktop lorsque vous coordonnez plusieurs flux de travail ou que vous avez besoin d’une revue visuelle des diffs. Utilisez le CLI lorsque vous voulez de la composabilité terminal, du scripting ou une intégration CI/CD.

3. Extension IDE (VS Code, Cursor, Windsurf)

L’extension IDE Codex s’intègre directement dans votre éditeur :

• Mode agent par défaut : lit les fichiers, effectue les modifications, exécute les commandes
• Édition inline : suggestions contextuelles dans vos fichiers actifs
• Sessions partagées : les sessions se synchronisent entre le CLI et l’extension IDE
• Authentification identique : connectez-vous avec un compte ChatGPT ou une clé API

Installez depuis le VS Code Marketplace ou les magasins d’extensions de Cursor/Windsurf.³

4. Codex Cloud [EXPERIMENTAL]

Les tâches cloud s’exécutent de manière asynchrone dans des environnements gérés par OpenAI :

• Fire and forget : mettez en file d’attente des tâches qui s’exécutent indépendamment de votre machine locale
• Exécution parallèle : exécutez plusieurs tâches cloud simultanément
• Création de PR : Codex crée des pull requests à partir du travail terminé
• Application locale : récupérez les résultats cloud dans votre repo local avec codex apply <TASK_ID>

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

Les tâches cloud sont également accessibles depuis chatgpt.com/codex.⁴

5. Codex for Chrome [NEW]

Codex est livré sous forme d’extension de navigateur pour Chrome, ajoutant une cinquième surface aux côtés du CLI, de l’application desktop, de l’extension IDE et du cloud. L’extension est conçue pour accompagner votre navigation normale plutôt que de la prendre en charge : Codex fonctionne en parallèle sur plusieurs onglets en arrière-plan, et vous gardez le contrôle des sites auxquels il accède.⁹⁰

• Exécution parallèle sur les onglets : Codex opère sur plusieurs onglets à la fois sans verrouiller l’onglet au premier plan.
• Contrôle par site : vous mettez en allow-list les sites web avec lesquels Codex peut interagir ; par défaut, aucun accès.
• Le navigateur comme atelier : l’extension est idéale pour le travail sur applications et sites web où la page est la source de vérité — consoles d’administration, dashboards internes, interfaces de gestion de contenu, systèmes de tickets — et non un remplacement du CLI pour les repos locaux.
• Même cerveau : Codex for Chrome utilise la même intelligence GPT-5.x-Codex que les autres surfaces, donc une configuration AGENTS.md ou des skills qui fonctionnent dans le CLI portent les mêmes conventions dans le travail piloté par navigateur.

Installez depuis la documentation de l’extension Chrome Codex.⁹⁰

Plongée approfondie dans le système de configuration

Codex utilise TOML pour la configuration. Comprendre la hiérarchie de précédence est essentiel, car elle détermine quels paramètres l’emportent en cas de conflit.

Précédence (de la plus haute à la plus basse)

1. Surcharges de session (la plus haute) : drapeaux CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) et surcharges -c key=value
2. Configuration du projet (.codex/config.toml, découverte depuis le CWD en remontant jusqu’à la racine du projet ; le dossier le plus proche l’emporte)
3. Configuration utilisateur ($CODEX_HOME/config.toml, par défaut ~/.codex/config.toml)
4. Configuration système (/etc/codex/config.toml sur Unix)
5. Valeurs par défaut intégrées (la plus basse)

requirements.toml agit comme une couche de contraintes de politique qui restreint les valeurs que les utilisateurs peuvent sélectionner après la fusion normale de la configuration. Voir Déploiement en entreprise.

Emplacements des fichiers de configuration

Astuce d’expert : la variable d’environnement CODEX_HOME remplace le dossier ~/.codex par défaut. Utile pour les configurations CI/CD ou multi-comptes.

Référence complète de la configuration

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.5"                      # Recommended model when available
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.5"               # Optional model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

Profils

Préréglages de configuration nommés pour différents modes de travail :

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.4"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Activez un profil :

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Astuce d’expert : définissez un profil par défaut avec profile = "fast" au niveau supérieur de votre configuration. Surchargez par session avec --profile.

Fournisseurs de modèles personnalisés

Connectez-vous à Azure, AWS Bedrock, à des modèles locaux ou à des services proxy :

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

Avertissement : la wire API chat/completions (wire_api = "chat") a été dépréciée pour les modèles hébergés par OpenAI, OpenAI ayant annoncé sa suppression en février 2026.³⁴ Les fournisseurs locaux (Ollama, LM Studio) peuvent encore accepter ce format. Pour les endpoints OpenAI, utilisez plutôt wire_api = "responses".

Utilisez des modèles locaux avec le drapeau --oss :

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

Ou définissez-le dans la configuration :

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Surcharges de configuration en ligne

Surchargez n’importe quelle valeur de configuration depuis la ligne de commande :

codex -c model="gpt-5.5" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Quel modèle choisir ?

Modèles disponibles (avril 2026)

GPT-5.5 (23 avril 2026) est le choix recommandé par OpenAI pour la plupart des tâches Codex : codage complexe, utilisation de l’ordinateur, travail intellectuel et workflows de recherche. Disponible dans Codex CLI / web / desktop le 23 avril pour ChatGPT Plus / Pro / Business / Enterprise / Edu / Go ; dans l’API OpenAI le 24 avril. Fenêtre de contexte : 400K dans Codex, 1M dans l’API — Codex plafonne la fenêtre à 400K pour équilibrer débit et coût entre les niveaux d’abonnement ; l’API expose la totalité des 1M. Tarification (API) : 5 $ en entrée / 30 $ en sortie par MTok (2× le tarif de GPT-5.4 ; OpenAI indique une augmentation effective d’environ 20 % après les améliorations d’efficacité des tokens). Benchmarks : 82,7 % sur Terminal-Bench 2.0 (SOTA actuel parmi les modèles publiquement disponibles), 84,9 % sur GDPval (44 professions), 78,7 % sur OSWorld-Verified, 98,0 % sur Tau2-bench Telecom (sans optimisation des prompts). OpenAI a utilisé GPT-5.5 + Codex en interne pour réécrire son infrastructure de service avant le lancement — ce qui a permis un gain de 20 % sur la vitesse de génération de tokens.⁸³

GPT-5.4 reste disponible sur toutes les surfaces Codex (CLI, app, extension IDE, cloud).⁶⁴ La liste exacte des modèles varie selon le compte et le déploiement. Vérifiez votre cache local : ~/.codex/models_cache.json.

Note de dépréciation (11 mars 2026) : les modèles GPT-5.1 ne sont plus disponibles dans ChatGPT. Les conversations existantes se poursuivent automatiquement sur GPT-5.3 Instant, GPT-5.4 Thinking ou GPT-5.4 Pro. GPT-5.1-Codex-Mini reste disponible via API et CLI pour les charges de travail sensibles aux coûts.⁷¹

Note sur le niveau gratuit (5 mai 2026) : GPT-5.5 Instant a été déployé sur le niveau gratuit de ChatGPT le 5 mai 2026. Cela élargit l’audience de la famille GPT-5.5 au-delà des plans payants, bien que l’accès à Codex CLI continue d’exiger un abonnement Plus / Pro / Business / Enterprise / Edu / Go éligible ou une clé API.⁹²

GPT-5.4 mini (17 mars 2026) : variante plus petite et plus rapide de GPT-5.4 avec un contexte de 400K à 0,75 $/4,50 $ par MTok — n’utilise que 30 % du quota GPT-5.4. Idéal pour la délégation à des sous-agents : laissez GPT-5.4 gérer la planification et la coordination pendant que des sous-agents GPT-5.4 mini traitent en parallèle des sous-tâches plus restreintes (recherche dans la base de code, revue de fichiers, traitement de documents).⁷⁶

Logigramme de sélection de modèle

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

Effort de raisonnement

Contrôlez à quel point le modèle « réfléchit » avant de répondre :

Les niveaux pris en charge dépendent du modèle. minimal n’est disponible que pour les modèles GPT-5. Tous les modèles ne prennent pas en charge tous les niveaux.

codex -c model_reasoning_effort="xhigh" "find the race condition"

Astuce d’expert : le raisonnement xhigh peut consommer 3 à 5 fois plus de tokens que medium pour le même prompt. Réservez-le aux problèmes véritablement difficiles où la réflexion supplémentaire est rentable.

Contrôles rapides du raisonnement dans la TUI (v0.124.0+).⁸⁵ Dans une session TUI interactive, Alt+, abaisse le raisonnement d’un cran et Alt+. le relève d’un cran — utile lorsqu’un problème difficile en cours de session justifie une montée temporaire medium → high → xhigh sans /effort ni -c. Lorsque vous acceptez une mise à niveau de modèle en cours de session, le raisonnement est réinitialisé à la valeur par défaut du nouveau modèle plutôt que de conserver le niveau précédent.

Changement de modèle

Changez de modèle en cours de session avec la commande slash /model, ou définissez-le par exécution via --model / -m :

codex -m gpt-5.3-codex-spark "pair with me on this component"

Combien coûte Codex ?

Voir aussi Sélection du modèle pour les capacités et Cadres de décision pour choisir le bon modèle selon la tâche.

Accès via les forfaits ChatGPT

La disponibilité de Codex dépend de votre forfait ChatGPT et des paramètres de votre organisation :⁵¹

Mise à jour tarifaire d’avril 2026 : Le tarif annuel Business est passé de 25 $ à 20 $/siège/mois. Les sièges Codex uniquement avec tarification à l’usage sont désormais disponibles pour les espaces de travail Business et Enterprise — pas de frais de siège fixes, facturés sur la consommation de tokens.⁷⁹ Les limites de débit promotionnelles 2x pour les forfaits payants (depuis le lancement de l’application Desktop en février 2026) restent actives.¹⁶

Boost des limites d’usage de mai 2026 (jusqu’au 31 mai 2026) : Codex sur le forfait Plus fonctionne avec une limite de 25× sur 5 heures (contre le boost standard de 20×), et le palier à 100 $/mois est doublé sur la même fenêtre. Profitez de cette période pour pousser des lots de tâches cloud plus longs ou des exécutions d’agents à plus haut débit sans atteindre votre mur habituel des 5 heures.⁸⁹

Coûts en crédits

Les opérations Codex consomment des crédits de l’allocation de votre forfait :

Les forfaits Enterprise et Edu adaptent les crédits à l’allocation contractuelle. Vérifiez /status dans le TUI pour l’usage actuel.

Facturation API

Lorsque vous utilisez Codex via l’API, OpenAI facture l’usage par token selon la tarification standard OpenAI API pour le modèle sélectionné (plus toutes les remises applicables de mise en cache des prompts). Consultez la page officielle de tarification API pour les tarifs actuels.²⁰

Stratégies d’optimisation des coûts

1. Utilisez les profils : Créez un profil fast avec gpt-5.1-codex-mini et model_reasoning_effort = "low" pour les tâches de routine
2. Réservez le raisonnement élevé : N’utilisez xhigh que pour les problèmes véritablement difficiles, car il coûte 3 à 5x plus de tokens
3. Utilisez --ephemeral : Sautez la persistance de session en CI/CD pour réduire la surcharge
4. Minimisez les résumés de raisonnement : Définissez model_reasoning_summary = "none" lorsque vous n’avez pas besoin d’explications
5. Regroupez avec le mode exec : codex exec évite la surcharge du TUI pour les workflows d’automatisation
6. Surveillez l’usage : Vérifiez /status dans le TUI et les tableaux de bord de facturation de votre organisation

Exemples de coûts réels

Coûts API représentatifs pour des tâches courantes (gpt-5.3-codex à la tarification standard, raisonnement moyen) :

Les coûts varient selon l’effort de raisonnement, la mise en cache et la longueur de la conversation. Utilisez gpt-5.1-codex-mini pour les tâches de routine afin de réduire les coûts d’environ 40 à 60 %. Les tokens d’entrée mis en cache sont facturés avec une remise.

Surcharge cachée en tokens

Chaque appel d’outil ajoute des tokens au-delà de votre prompt visible :

Conseil d’expert : Surveillez votre usage réel via /status dans le TUI. Le compteur de tokens inclut toute la surcharge, pas seulement vos messages visibles. Si les coûts vous surprennent, vérifiez combien de serveurs MCP sont connectés — chacun ajoute des définitions d’outils à chaque appel API.

Gestion des coûts d’équipe

Stratégies de contrôle des coûts d’équipe : - Définissez requirements.toml pour imposer des limites de modèle et d’effort de raisonnement à l’échelle de l’organisation - Utilisez gpt-5.1-codex-mini pour CI/CD — les pipelines automatisés ont rarement besoin du raisonnement maximal - Budgétisation par profil — définissez des profils ci, review et dev avec des plafonds de coût appropriés - Surveillance via OpenTelemetry — les déploiements Enterprise peuvent exporter la télémétrie d’usage vers les piles d’observabilité existantes

Cadres de décision

Quand utiliser chaque surface

Quand utiliser chaque mode de sandbox

Quand utiliser chaque niveau de raisonnement

Mode Plan vs exécution directe

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Mode Steer : Entrée vs Tab

Règle empirique : Entrée = « arrête, écoute ceci maintenant ». Tab = « quand tu as terminé, fais aussi ceci ».

Desktop App vs CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

Quel profil ?

Associez votre tâche à un profil préconfiguré :

Configuration de config.toml :

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Changez de profil par session : codex --profile careful

Comment fonctionne le système de sandbox et d’approbation ?

Codex utilise un modèle de sécurité à deux couches qui sépare ce qui est techniquement possible de quand Codex demande une approbation humaine. L’approche diffère fondamentalement du système de permissions de Claude Code — Codex applique les restrictions au niveau du noyau du système d’exploitation.⁵ Voir aussi Déploiement en entreprise pour les contraintes requirements.toml que les administrateurs imposent à l’échelle de l’organisation.

Couche 1 : Sandbox (ce qui est possible)

La sandbox contrôle l’accès au système de fichiers et au réseau à l’aide de mécanismes natifs au système d’exploitation :

Application spécifique à la plateforme :

• macOS : Le framework Seatbelt d’Apple via sandbox-exec avec des profils spécifiques au mode compilés à l’exécution et appliqués par le noyau⁶. Depuis la v0.121.0, les profils sandbox macOS peuvent autoriser des sockets Unix spécifiques (par exemple, docker.sock, les sockets IPC de l’éditeur) et la résolution DNS privée n’est plus bloquée par défaut.⁸²
• Linux : Landlock pour les restrictions du système de fichiers + seccomp pour le filtrage des appels système. Un processus auxiliaire autonome (codex-linux-sandbox) fournit une isolation en défense en profondeur.⁵ Bubblewrap (bwrap) est intégré et compilé dans le cadre de la build Linux (promu depuis optionnel dans la v0.100.0)⁷. La v0.117.0 a amélioré la fiabilité de la sandbox sur les distributions plus anciennes avec des configurations de noyau héritées.⁷⁵ La v0.129.0 a renforcé le démarrage de la sandbox sur Linux et a mis à jour Bubblewrap intégré vers la 0.11.2 avec les correctifs de sécurité en amont ; la v0.130.0 a ajouté un renforcement supplémentaire au démarrage.⁸⁹⁹¹
• Windows : Sandbox native avec jetons restreints (promue depuis expérimentale dans la v0.100.0). WSL est également pris en charge (hérite de Landlock + seccomp de Linux). La v0.117.0 inclut des améliorations de la sandbox à jetons restreints pour une meilleure isolation des processus.⁷⁵ La v0.130.0 accorde aux utilisateurs de la sandbox l’accès au cache binaire d’exécution du bureau afin que la sandbox Windows puisse résoudre les binaires d’exécution de manière fiable pour les utilisateurs de workspace-sandbox.⁹¹

Pourquoi cela compte : Contrairement à la sandbox basée sur des conteneurs (Docker), la sandbox au niveau du système d’exploitation est plus rapide, plus légère et plus difficile à contourner. Le noyau applique les restrictions avant même que Codex ne voie l’appel système.

Correctifs de sécurité : - Contournement de sandbox via fork zsh (v0.106.0) : Correction d’une vulnérabilité où l’exécution shell via fork zsh pouvait contourner les restrictions de la sandbox.⁶⁰ Si vous êtes sur une version antérieure, mettez à jour immédiatement. - Plafond de taille d’entrée (v0.106.0) : Codex applique désormais un plafond d’entrée d’environ 1 million de caractères pour éviter les blocages dus à des charges utiles excessivement volumineuses.⁶⁰ - Profil devcontainer sécurisé (v0.121.0) : Un nouveau profil client renforcé pour les devcontainers Docker utilise Bubblewrap pour la sandbox à l’intérieur du conteneur. WSL2 est pris en charge ; WSL1 est explicitement rejeté (Bubblewrap est incompatible avec le shim noyau de WSL1).⁸² - Revue Guardian + hooks (v0.121.0) : Les hooks sont désactivés pendant les sessions de revue Guardian afin que les hooks pré/post-outil ne puissent pas interférer avec les décisions du sous-agent Guardian.⁸² Si vous comptez sur les hooks pour la journalisation ou la validation, sachez qu’une revue Guardian les ignore — repliez-vous sur l’observabilité de l’app-server si vous avez besoin d’une piste d’audit complète. - Système de fichiers /dev Linux (v0.105.0) : Les commandes en sandbox sur Linux reçoivent désormais un système de fichiers /dev minimal, améliorant la compatibilité avec les outils qui s’attendent à des nœuds de périphérique.⁶¹

Politique ReadOnlyAccess (v0.100.0+) : Une forme de politique configurable pour un contrôle granulaire de l’accès en lecture. Utilisez-la pour restreindre les répertoires depuis lesquels Codex peut lire, même en mode workspace-write :

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Couche 2 : Politique d’approbation (quand demander)

La politique d’approbation détermine quand Codex s’arrête pour demander une confirmation humaine :

on-failure apparaît encore dans certains exemples plus anciens et chemins de compatibilité, mais la documentation de configuration OpenAI actuelle le marque comme obsolète. Préférez on-request pour les exécutions interactives et never pour les exécutions non interactives qui disposent déjà d’une limite de sécurité externe.⁸⁷

Identifiants d’approbation distincts (v0.104.0+)

Codex attribue désormais des identifiants d’approbation distincts à chaque commande au sein d’une exécution shell multi-étapes. Cela signifie que les approbations sont granulaires — approuver une commande dans une séquence n’approuve pas automatiquement les suivantes dans la même invocation shell.⁴⁹

Contrôles d’approbation flexibles (v0.105.0+)

Le flux d’approbation prend désormais en charge des permissions de sandbox supplémentaires et un rejet granulaire :⁶¹

• Permissions de sandbox supplémentaires : Lorsqu’une commande nécessite un accès au-delà du mode sandbox actuel, Codex peut demander des permissions supplémentaires spécifiques plutôt que d’exiger un changement complet de mode
• Rejet granulaire : Rejetez les appels d’outils individuels avec un retour d’information afin que Codex puisse ajuster son approche plutôt que de simplement réessayer la même commande

Demandes de permissions à l’exécution (v0.113.0+)

Codex inclut désormais un outil intégré request_permissions qui permet au modèle de demander des permissions supplémentaires à l’exécution.⁶⁹ Lorsque le modèle rencontre une tâche nécessitant un accès élevé, il peut formellement demander des permissions spécifiques (chemins du système de fichiers, accès réseau, etc.) via le flux d’approbation TUI plutôt que d’échouer silencieusement ou d’exiger que l’utilisateur redémarre avec des flags différents.

Profils de permissions (v0.113.0+, étendus dans la v0.128.0)

Les profils de permissions divisent les politiques de sandbox du système de fichiers et du réseau en sections nommées et réutilisables. Définissez default_permissions sur un profil intégré tel que :read-only, :workspace ou :danger-no-sandbox, ou pointez-le vers une table [permissions.<name>] personnalisée.⁸⁷

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

Utilisez none pour les fichiers sensibles et les globs qui devraient être illisibles même lorsque la racine du projet est accessible en écriture. Pour les exceptions ponctuelles à des commandes, préférez les règles plutôt que d’élargir largement un profil.⁸⁷

Conseils sur le --full-auto hérité

Les guides plus anciens décrivaient --full-auto comme un alias pratique pour :

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

Dans la v0.128.0, les notes de version marquent --full-auto comme obsolète, et l’aide actuelle de CLI ne le liste plus pour les exécutions interactives. Utilisez plutôt les flags explicites ci-dessus ou un profil de permissions nommé.⁸⁶

Fiabilité de la sandbox (v0.129.0) : Le renforcement du démarrage de la sandbox Linux réduit les conditions de course sur les systèmes de fichiers lents ou les checkouts via liens symboliques ; les améliorations de fiabilité de la sandbox Windows résolvent plusieurs plantages de cas limites lors d’exécutions de longue durée ; et Bubblewrap intégré est mis à jour vers la 0.11.2 avec les correctifs de sécurité en amont. Aucun changement de configuration requis. Exécutez codex update pour les récupérer.⁸⁹

Configurations recommandées

Développement quotidien (valeur par défaut sûre) :

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Utilisateur expérimenté (accès complet, humain dans la boucle) :

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

Cette combinaison est le « sweet spot » recommandé par la communauté : capacité maximale mais approbation requise pour chaque commande.⁸

Automatisation CI/CD :

sandbox_mode = "workspace-write"
approval_policy = "never"

Approbations intelligentes avec sous-agent Guardian (v0.115.0+)

Les Approbations intelligentes peuvent acheminer les demandes de revue via un sous-agent guardian au lieu de nécessiter une approbation humaine pour chaque action. La session guardian persiste à travers les approbations pour réutiliser le cache de prompts et éviter la surcharge de démarrage. Chaque revue obtient un historique propre (les décisions antérieures ne fuient pas dans les revues ultérieures).⁷³

Configurez le réviseur dans config.toml :

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

Ceci est particulièrement utile pour les workflows CI/CD où vous souhaitez une revue automatisée avec raisonnement plutôt qu’un approval_policy = "never" général.

Activation de l’accès réseau

Codex bloque l’accès réseau par défaut en mode workspace-write. Activez-le si nécessaire :

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

Prise en charge du proxy WebSocket (v0.104.0+)

Pour les environnements d’entreprise qui acheminent le trafic WebSocket via un proxy, Codex prend désormais en charge les variables d’environnement WS_PROXY et WSS_PROXY :⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

Celles-ci complètent le support proxy HTTPS_PROXY et SOCKS5 existant (v0.93.0+), couvrant toutes les couches de transport.

Tester la sandbox

Vérifiez le comportement de la sandbox avant de lui faire confiance :

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

Si la sandbox fonctionne correctement, les deux commandes devraient échouer avec une erreur de permission refusée sous un profil limité à l’espace de travail. Si l’une ou l’autre commande réussit, votre configuration de sandbox nécessite une investigation.

Comment fonctionne AGENTS.md ?

AGENTS.md est le système d’instructions de projet de Codex : un standard ouvert⁹ désormais régi par l’Agentic AI Foundation de la Linux Foundation. Pris en charge par Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode et plus de 60 000 projets open source. Il définit le comportement de Codex dans un dépôt ou un dossier précis. Consultez Skills pour découvrir les packages d’expertise réutilisables qui complètent AGENTS.md.

Hiérarchie de découverte

Codex construit une chaîne d’instructions au démarrage de la session en parcourant l’arborescence des dossiers :

1. Global (~/.codex/) : AGENTS.override.md > AGENTS.md
2. Projet (de la racine git au dossier actuel) : chaque niveau est vérifié pour AGENTS.override.md > AGENTS.md > noms de fichiers de secours
3. Fusion : les fichiers sont concaténés de la racine vers le bas ; les fichiers les plus proches apparaissent plus tard dans le prompt et remplacent les consignes précédentes

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

Ce qui fait un excellent AGENTS.md

D’après les recommandations directes de Codex lui-même et les pratiques de la communauté¹⁰ :

À FAIRE : - Soyez précis : "Use rg --files for discovery" vaut mieux que "search efficiently" - Définissez la clôture : que signifie « terminé » ? (tests réussis, lint sans erreur, etc.) - Incluez les commandes : build, test, lint, format (invocations exactes) - Organisez par tâche : sections codage, review, release, incident/debug - Définissez l’escalade : quoi faire en cas de blocage ou d’état inattendu

À NE PAS FAIRE : - Déverser des guides de style entiers sans règles d’exécution - Utiliser des directives ambiguës (« soyez prudent », « optimisez ») - Mélanger des priorités contradictoires (vitesse + vérification exhaustive + aucun budget d’exécution) - Rédiger de la documentation prose (AGENTS.md est une politique opérationnelle, pas un README)

Exemple : AGENTS.md de production

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

Gestion des secrets dans les sessions Agent

Considérez l’historique visible par Codex comme une surface de sécurité, pas seulement comme du code source. Les notes de version de Codex documentent les travaux sur les instantanés shell et la rédaction des variables d’environnement, et le système de mémoire recherche les secrets dans les écritures en mémoire, mais ces protections ne transforment pas les sorties de commande, transcriptions de session, instantanés shell, journaux locaux ou scripts d’aide en emplacements sûrs pour afficher des identifiants.³⁷⁵⁵⁹⁵

La règle opérationnelle est simple : n’affichez pas de secrets que le modèle pourrait inspecter ; conservez les identifiants d’aide dans une configuration qui exige l’environnement ; séparez le code source exécutable, la documentation, les caches générés, les transcriptions de session, les instantanés shell, les journaux et les magasins de secrets intentionnels pendant les audits ; expurgez l’historique local lorsqu’une forme de secret à forte confiance apparaît ; et ne promouvez les hooks de prévention qu’après validation de la boucle d’hygiène manuelle. La leçon publique est la cartographie des surfaces et les critères d’acceptation, pas les valeurs privées des tokens, les chemins exacts ni les détails internes des détecteurs.⁹⁵

Le mécanisme d’override

AGENTS.override.md à n’importe quel niveau de dossier remplace le AGENTS.md normal pour cette portée. À utiliser pour :

• Gel de release : « Pas de nouvelles fonctionnalités, correctifs uniquement »
• Mode incident : « Toutes les modifications doivent être examinées par l’astreinte »
• Durcissement temporaire : « Aucune mise à jour de dépendance ce sprint »

Configuration

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Génération de scaffold

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Ou vérifiez votre chaîne d’instructions :

codex --ask-for-approval never "Summarize your current instructions"

Hooks

Codex a introduit les hooks dans v0.99.0 (AfterAgent) et v0.100.0 (AfterToolUse), puis ajouté un moteur de hooks expérimental dans v0.114.0 avec les événements SessionStart et Stop.⁷⁰ Depuis v0.124.0 (23 avril 2026), les hooks sont stables.⁸⁵ Ils sont désormais configurables inline dans config.toml et requirements.toml : plus besoin de fichier de scripts de hooks séparé ; ils observent les outils MCP aux côtés de apply_patch et des longues sessions Bash. Le système couvre maintenant le cycle de vie de session et l’automatisation au niveau des outils, comblant l’écart avec le modèle de hooks de Claude Code.

Événements de hook disponibles

Configuration des hooks

Les hooks sont configurés dans .codex/config.toml :

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

La sortie stdout du hook SessionStart alimente le contexte du modèle, ce qui le rend idéal pour injecter des informations dynamiques (dates, noms de branche, variables d’environnement) au démarrage de la session.

Répliquer les patterns de hooks de Claude Code

Si vous migrez depuis Claude Code, voici comment obtenir une automatisation similaire :

Conseil d’expert : depuis v0.124.0 (23 avril 2026), le moteur de hooks est stable. De nouveaux événements de hook sont encore livrés dans les releases : consultez le changelog Codex.

Navigateur de hooks dans la TUI (v0.129.0) : exécutez /hooks dans la TUI pour découvrir les hooks disponibles, voir ceux qui sont actuellement actifs et activer ou désactiver des hooks individuels sans modifier config.toml. Utile pour diagnostiquer un hook intégré à un plugin qui se comporte mal, ou pour désactiver temporairement un linter AfterToolUse pendant une session d’édition concentrée.⁸⁹

Qu’est-ce que MCP (Model Context Protocol) ? [EXPERIMENTAL]

MCP étend les capacités de Codex en le connectant à des outils et services externes. Le groupe de commandes codex mcp est actuellement marqué comme expérimental, et les commandes comme le format de configuration peuvent changer d’une version à l’autre. Codex prend en charge 2 types de transport : STDIO (processus locaux) et Streamable HTTP (serveurs distants).¹¹

Changements MCP de v0.121.0 : les outils sont désormais enregistrés avec un namespace ; les noms d’outils apparaissent donc dans les listes sous la forme <server>:<tool> plutôt que comme des noms seuls — mettez à jour les scripts ou prompts qui recherchent des noms d’outils non qualifiés avec grep. Un nouveau flag supports_parallel_tool_calls est maintenant propagé aux MCPs inclus, ce qui permet l’exécution parallèle pour les serveurs qui déclarent cette prise en charge. Les métadonnées d’état du sandbox transitent désormais par les métadonnées des outils MCP, afin que les serveurs puissent adapter leur comportement (par exemple, avertir lorsqu’ils s’exécutent dans un sandbox read-only). La requête personnalisée codex/sandbox-state a été supprimée — utilisez plutôt le chemin des métadonnées. La phase 3 du déploiement des Apps MCP arrive ici avec la prise en charge des appels d’outils ; les appels d’outils différés aplatis sont désormais pris en charge pour les serveurs qui utilisent le modèle d’appel différé.⁸²

Configurer des serveurs MCP

Serveurs STDIO (processus locaux) :

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

Serveurs HTTP (distants) :

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

Gestion CLI

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

En session : /mcp affiche les serveurs actifs et les outils disponibles. /mcp verbose (v0.123.0+)⁸⁴ renvoie les diagnostics complets du serveur, les ressources et les modèles de ressources — utile lorsqu’un serveur ne se charge pas ou que des outils n’apparaissent pas à l’endroit attendu. Le simple /mcp reste rapide.

Le chargement de MCP de plugin (v0.123.0+) accepte à la fois le schéma standard mcpServers et les maps de serveurs de niveau supérieur dans .mcp.json, ce qui permet aux plugins écrits selon l’une ou l’autre convention de se charger proprement.⁸⁴

Exécuter Codex COMME serveur MCP

Codex peut s’exposer lui-même comme serveur MCP pour l’orchestration multi-agent :¹²

codex mcp-server                        # Start as MCP server (stdio transport)

Le serveur expose 2 outils : 1. codex() : démarrer une nouvelle session avec les paramètres de prompt, sandbox, modèle et approbation 2. codex-reply() : poursuivre une session existante avec threadId et un prompt

Utilisation avec le Agents SDK (Python) :

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Serveurs MCP notables

Modèles pratiques

Modèle 1 : développement contextualisé — Associez Context7 à la documentation de votre framework afin que Codex dispose toujours de références API à jour :

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

Modèle 2 : limites de sortie — Les réponses des outils MCP sont tronquées par défaut à environ 25K caractères. Pour les outils qui renvoient des charges utiles volumineuses (requêtes de base de données, captures de logs), utilisez enabled_tools afin de vous limiter à des outils précis et de garder des réponses ciblées.

Modèle 2a : sortie d’outil multimodale (v0.107.0) — Les outils personnalisés peuvent désormais renvoyer une sortie multimodale (images, contenu riche) en plus du texte. Cela permet aux outils qui produisent des artefacts visuels — captures d’écran, schémas, rendus de graphiques — de les transmettre directement au modèle pour analyse.⁶²

Modèle 3 : gouvernance MCP en entreprise — Verrouillez les serveurs MCP que les développeurs peuvent utiliser via requirements.toml :

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Tout serveur ne correspondant pas à une identité dans requirements.toml sera bloqué au démarrage. Consultez Déploiement en entreprise pour la configuration complète des politiques.

Mode code [EXPERIMENTAL]

Le mode code (v0.114.0) fournit des workflows de développement plus isolés en limitant le périmètre de l’agent aux opérations centrées sur le code.⁷⁰ Lorsqu’il est activé, l’agent se concentre sur la lecture, l’écriture et le test du code, sans interactions système plus larges.

Cette fonctionnalité est expérimentale. Consultez les notes de version pour suivre les mises à jour.

Runtime REPL JavaScript [REMOVED]

Codex v0.100.0 a ajouté un runtime REPL JavaScript expérimental (js_repl), puis v0.106.0 l’a promu via la surface /experimental.⁶⁰ Ces recommandations relèvent désormais de l’historique. Dans v0.128.0, le changelog de version inclut « supprimer la fonctionnalité js_repl », et la liste actuelle des fonctionnalités marque js_repl et js_repl_tools_only comme supprimées.⁸⁶

N’ajoutez pas features.js_repl = true aux nouvelles configurations. Utilisez des commandes shell, des scripts versionnés, des outils MCP ou une skill Codex avec un dossier scripts/ lorsque vous avez besoin d’une logique exécutable reproductible.

Que sont les skills ?

Les skills sont des packages de capacités réutilisables et propres à une tâche, que Codex charge à la demande. Ils suivent le standard ouvert des agent skills.¹³

Structure d’un skill

my-skill/
  SKILL.md           (required: instructions)
  scripts/           (optional: executable scripts)
  references/        (optional: reference docs)
  assets/            (optional: images, icons)
  agents/openai.yaml (optional: metadata, UI, dependencies)

Emplacements de découverte

Codex stocke les skills installés par l’utilisateur dans $CODEX_HOME/skills (par défaut : ~/.codex/skills), y compris les skills système intégrés sous .system/. Codex prend en charge les dossiers de skills liés par symlink.

Créer un skill

Format SKILL.md :

---
name: security-audit
description: Run a thorough security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

Métadonnées (agents/openai.yaml) :

interface:
  display_name: "Security Audit"
  short_description: "Full codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Invoquer des skills

• Explicite : menu /skills ou mention $skill-name dans le prompt
• Implicite : Codex détecte automatiquement les skills correspondants à partir de la description de la tâche (si allow_implicit_invocation: true)
• Creator : utilisez $skill-creator pour créer interactivement un nouveau skill
• Installer : utilisez $skill-installer install <name> pour installer des skills communautaires

Activer/désactiver

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Skills vs slash commands

Déboguer des skills

Si un skill ne s’active pas :

1. Vérifiez la découverte : /skills doit lister le skill dans la TUI
2. Vérifiez le chemin : assurez-vous que le dossier du skill se trouve dans un emplacement reconnu (~/.codex/skills/, racine du projet ou /etc/codex/skills/)
3. Vérifiez enabled : les skills avec enabled = false dans config.toml ne seront pas chargés
4. Vérifiez l’activation implicite : si vous comptez sur l’auto-détection, assurez-vous que allow_implicit_invocation: true figure dans agents/openai.yaml
5. Utilisez des mots-clés : incluez les termes de la description du skill dans votre prompt pour améliorer la correspondance implicite

Exemple de production : skill de déploiement

Un skill multi-fichier complet montrant comment références et scripts fonctionnent ensemble :

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md :

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Invoquez-le avec : $deploy to staging ou $deploy production with canary rollout

Plugins

Les plugins unifient les entrées MCP, les hooks, les skills et les connecteurs d’app dans un seul package installable (v0.110.0+).⁶⁵ Depuis la v0.117.0, les plugins sont des éléments de premier rang : les plugins limités au périmètre produit se synchronisent automatiquement au démarrage et /plugins fournit un navigateur intégré à la TUI pour la découverte et la gestion.⁷⁵ La v0.128.0 a étendu les workflows de plugins avec l’installation depuis marketplace, la mise en cache des bundles distants, les APIs de désinstallation distante, les hooks inclus dans les plugins, l’état d’activation des hooks et l’import de configuration d’agent externe.⁸⁶ La v0.129.0 (7 mai 2026) ajoute le partage d’espace de travail pour les plugins (envoyer un ensemble de plugins à des coéquipiers sans le republier), des contrôles d’accès au partage (activation/désactivation par destinataire, révocation), le filtrage des sources (limiter les marketplaces depuis lesquels un espace de travail récupère des plugins) et des opérations de marketplace pouvant être invoquées directement depuis le navigateur /plugins plutôt que depuis le CLI.⁸⁹ La v0.130.0 (8 mai 2026) rend le packaging des plugins plus transparent et le workflow de partage plus contrôlable :⁹¹

• Hooks inclus visibles dans les détails du plugin. La vue détaillée de /plugins liste désormais chaque lifecycle hook inclus dans un plugin (SessionStart, UserPromptSubmit, Stop, etc.). Avant d’installer un plugin, vous pouvez voir exactement quels hooks il enregistrera dans votre session — plus de side effects inattendus liés aux hooks d’un plugin auquel vous ne faites confiance que pour ses tools.
• Métadonnées de partage du plugin dans shareContext. Lorsqu’un plugin est partagé depuis un espace de travail, la payload du lien de partage expose désormais les métadonnées du lien (créateur, portée, fraîcheur) afin que les sessions réceptrices puissent afficher la provenance et décider de l’accepter ou non.
• Contrôles de découvrabilité dans les paramètres de partage. Les paramètres de partage exposent un toggle de découvrabilité afin que les équipes puissent publier des plugins vers des espaces de travail ou listes de destinataires spécifiques sans les rendre généralement listables dans toute l’organisation.

Sources des plugins

Découverte des plugins

Codex indique au modèle quels plugins sont activés au démarrage de la session (v0.111.0), ce qui améliore la découverte des MCPs, apps et skills installés.⁶⁵ Le modèle peut suggérer des plugins pertinents pendant une session en fonction du contexte de la tâche. En v0.117.0, les plugins limités au périmètre produit sont synchronisés au démarrage, ce qui garantit que le dernier catalogue de plugins est disponible sans intervention manuelle.⁷⁵

Mentions @plugin (v0.112.0+)

Référencez tout plugin installé directement dans le chat avec @plugin-name.⁶⁸ Lorsque vous mentionnez un plugin, son contexte (capacités, tools, configuration) est automatiquement inclus dans la fenêtre de contexte du modèle — inutile de décrire ce que fait le plugin.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

Cela fonctionne avec n’importe quel plugin installé, y compris les skills personnalisés, les serveurs MCP et les connecteurs d’app.

Marketplace de plugins (v0.113.0+)

Le marketplace de plugins inclut désormais une découverte plus riche avec métadonnées, catégories et notes.⁶⁹ Les contrôles d’authentification à l’installation vérifient que les plugins nécessitant des clés API ou OAuth disposent d’identifiants valides avant l’installation. Un endpoint de désinstallation supprime proprement les plugins et leur configuration associée.

Ajouter des marketplaces tiers (v0.121.0+)

La documentation actuelle d’OpenAI Codex conserve la gestion des sources de marketplace sous codex plugin marketplace. Cela formalise la distribution de plugins tiers au-delà du marketplace propriétaire d’OpenAI et prend en charge le raccourci de dépôt GitHub, les URL Git HTTP(S), les URL SSH et les dossiers racines de marketplace locaux ; utilisez --ref pour épingler une ref Git et répétez --sparse PATH uniquement pour les dépôts de marketplace basés sur Git.⁹³

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add [email protected]:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

Une fois ajouté, les plugins d’un marketplace apparaissent dans le navigateur /plugins aux côtés des plugins par défaut. Les appelants app-server (intégrations IDE/desktop) disposent d’un endpoint parallèle pour enregistrer des marketplaces par programmation.⁸²

Considération de sécurité : les marketplaces tiers exécutent du code de plugin arbitraire avec vos permissions Codex. Vérifiez les sources avant de les ajouter et privilégiez une exécution sandboxed lors des premiers lancements.

Gérer les plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace

Dans la TUI, utilisez /plugins (v0.117.0+) pour parcourir, installer et supprimer interactivement des plugins individuels sans quitter votre session.⁷⁵

Conseil d’expert : les plugins consolident ce qui nécessitait auparavant une configuration MCP séparée, l’installation de skills et la configuration de connecteurs d’app. Un seul plugin peut regrouper les trois — ce qui accélère l’onboarding d’équipe et rend la configuration plus portable.

Plan Mode et Collaboration

Le mode plan permet à Codex de concevoir une approche avant d’exécuter des modifications. Il est activé par défaut (depuis la v0.94.0).¹⁴ Consultez Decision Frameworks pour l’arbre de décision « Plan Mode vs Direct Execution ».

Activation du mode plan

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

En mode plan, Codex : - Lit les fichiers et analyse la base de code - Propose un plan d’implémentation - N’effectue aucune modification jusqu’à votre approbation - Diffuse le plan dans une vue TUI dédiée

Mode Steer

Le mode steer (activé par défaut depuis la v0.98.0) vous permet d’injecter de nouvelles instructions pendant que Codex travaille activement, sans interrompre sa tâche en cours.¹⁴

Il existe deux méthodes d’injection :

Exemples pratiques :

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Le mode steer est toujours actif dans le TUI. Si vous préférez attendre que Codex termine avant de donner des instructions, tapez simplement normalement après la fin du tour — aucun mode spécial n’est requis.

Améliorations du TUI (v0.105.0–v0.106.0)

Coloration syntaxique (v0.105.0) : Le TUI met désormais en évidence la syntaxe des blocs de code délimités et des diffs en ligne. Utilisez /theme pour choisir un schéma de couleurs.⁶¹

Nouvelles commandes TUI (v0.105.0+) :⁶¹

Transcription vocale (v0.105.0, expérimental) : Appuyez sur la barre d’espace pour dicter des prompts via la transcription vocale. Cette fonctionnalité est expérimentale et peut nécessiter des autorisations de microphone.⁶¹ Depuis la v0.107.0, les sessions vocales en temps réel prennent en charge la sélection des périphériques de microphone et de haut-parleur, vous permettant de choisir un matériel d’entrée/sortie audio spécifique.⁶²

Autres améliorations : - Les liens longs restent désormais cliquables même lorsqu’ils sont répartis sur plusieurs lignes du TUI (v0.105.0)⁶¹ - Les liens vers des fichiers locaux s’affichent avec un formatage amélioré (v0.106.0)⁶⁰ - La gestion de Ctrl+C pour les sous-agents a été corrigée pour terminer correctement les processus enfants (v0.106.0)⁶⁰

Système de Mémoire

Codex dispose d’un système de mémoire persistante (v0.100.0+) qui stocke les faits, les préférences et le contexte du projet d’une session à l’autre.²⁴

Commandes de mémoire

Les souvenirs sont stockés dans des fichiers markdown sous ~/.codex/memory/. Codex les charge au début de la session et les utilise pour orienter son comportement dans toutes les sessions futures.

Que stocker

Les souvenirs fonctionnent mieux pour les préférences persistantes et les faits de projet :

• Conventions de projet : « Ce projet utilise des tabulations, pas des espaces » ou « les réponses API incluent toujours un champ meta »
• Préférences d’outils : « Utiliser pnpm au lieu de npm » ou « Lancer les tests avec pytest -x --tb=short »
• Décisions d’architecture : « Le module d’authentification est dans src/core/auth/, pas src/middleware/ »
• Préférences de workflow : « Toujours lancer le linter avant de me montrer un diff »

Mémoire dans les pipelines

Lors de l’exécution de codex exec, les souvenirs sont chargés automatiquement. Cela signifie que les pipelines CI/CD et les scripts bénéficient du même contexte que les sessions interactives — inutile de répéter les instructions à chaque invocation.

Améliorations de la mémoire (v0.101.0–v0.107.0)

• Assainissement des secrets : Les souvenirs sont automatiquement analysés pour détecter les secrets avant d’être écrits sur le disque
• Conscience du CWD : Les fichiers de mémoire incluent désormais le contexte du répertoire de travail pour un rappel spécifique au projet
• Exclusion des messages développeur : Les messages développeur/système sont exclus de l’entrée mémoire de phase 1, améliorant la qualité de la mémoire en se concentrant sur les interactions utilisateur
• Oubli basé sur diff (v0.106.0) : La mémoire utilise désormais l’oubli basé sur diff pour supprimer les faits obsolètes, gardant le stockage de mémoire léger et pertinent au fil du temps⁶⁰
• Sélection consciente de l’usage (v0.106.0) : La récupération de la mémoire est désormais consciente de l’usage, priorisant les souvenirs fréquemment consultés et récemment pertinents⁶⁰
• Souvenirs configurables (v0.107.0) : Les souvenirs sont désormais entièrement configurables. Utilisez codex debug clear-memories pour réinitialiser tous les souvenirs stockés et repartir de zéro — utile lors d’un changement de contexte entre des projets sans rapport ou lorsque l’état de la mémoire a dérivé⁶²
• Mise à jour du modèle de phase 2 (v0.121.0) : Le modèle de consolidation de la mémoire de phase 2 est désormais gpt-5.4 (au lieu du précédent par défaut). Le pipeline de phase 2 s’exécute entre les sessions pour distiller les transcriptions de phase 1 en faits durables ; le changement de modèle améliore la qualité du rappel pour le même coût en tokens.⁸²
• Menu mémoires du TUI (v0.121.0) : Une nouvelle interface en session expose le mode mémoire, la suppression individuelle des souvenirs et un bouton de réinitialisation. La réinitialisation de la mémoire préserve désormais les rollouts passés au lieu de les invalider, de sorte que la réinitialisation efface la surface de rappel future sans casser la relecture de session.⁸²

Mémoire vs AGENTS.md

Astuce : Utilisez /m_update pour les faits qui doivent persister indéfiniment. Pour le contexte spécifique à une session, dites-le simplement directement à Codex dans la conversation. Pour le contexte partagé d’équipe, utilisez AGENTS.md.

Gestion des Sessions

Codex conserve les sessions sous ~/.codex/sessions/, permettant la reprise, le forking et les workflows multi-threads à travers CLI et les surfaces desktop.

Reprendre

Reprenez là où vous vous êtes arrêté :

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

La commande slash /resume à l’intérieur du TUI ouvre le même sélecteur interactif avec recherche.

Fork

Embranchez une conversation pour explorer des alternatives sans perdre votre progression actuelle :

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

Les forks créent des threads indépendants partageant le même historique jusqu’au point de fork. Les modifications dans un fork n’affectent pas l’autre. C’est utile pour comparer des approches (ex. : « forker et essayer Redis au lieu de Memcached ») ou pour explorer des changements risqués en toute sécurité.

Forking de threads en sous-agents (v0.107.0) : Les threads peuvent désormais être forkés en sous-agents indépendants, permettant à une conversation de générer des flux de travail parallèles qui s’exécutent de manière autonome. Cela étend le modèle de fork existant — au lieu de simplement embrancher la conversation, le thread forké devient un sous-agent avec son propre contexte d’exécution.⁶² Depuis la v0.117.0, les sous-agents utilisent des adresses basées sur des chemins (ex. : /root/agent_a) avec une messagerie inter-agents structurée, rendant la coordination multi-agents plus explicite et déboguable.⁷⁵

Liste des threads

Visualisez et gérez les sessions actives :

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

Dans l’application desktop, les threads sont visibles dans la barre latérale avec l’historique complet et les aperçus de diffs.

Cycle de vie d’une session

Les sessions se synchronisent entre CLI et l’application desktop — démarrez dans l’une, continuez dans l’autre.

Mode non interactif (codex exec)

codex exec exécute Codex de manière non interactive pour les scripts, le CI/CD et l’automatisation.¹⁵

Utilisation de base

codex exec "summarize the repository structure"
codex exec --sandbox workspace-write --ask-for-approval on-request "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

Par défaut, codex exec écrit la progression et les événements sur stderr et le message final de l’agent sur stdout. Cette conception le rend composable avec les pipelines Unix standard.

Sortie en lignes JSON

Avec --json, stdout devient un flux d’événements JSONL :

codex exec --json "fix the tests" | jq

Types d’événements : thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Sortie structurée

Imposez la forme de la réponse avec un schéma JSON :

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message écrit le message final dans un fichier.

Reprise et revue de session

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Options principales

Authentification CI

codex exec prend en charge CODEX_API_KEY pour l’authentification non interactive dans les environnements d’automatisation.

Bannière de démarrage de codex exec (v0.130.0). La bannière de démarrage de codex exec n’affiche plus l’ancienne mention « research preview ». Si votre CI analyse la sortie de démarrage, le texte de la bannière est désormais plus condensé ; les événements structurés --json restent inchangés.⁹¹

codex remote-control (v0.130.0+)

codex remote-control est une commande de premier niveau qui démarre un app-server headless conçu pour être piloté par un autre processus — extensions IDE, orchestrateurs personnalisés ou plans de contrôle distants. Elle remplace l’invocation codex app-server à plusieurs flags que de nombreux intégrateurs assemblaient à la main et offre aux outils tiers un point d’entrée unique et stable vers le même runtime app-server que celui livré sous les surfaces desktop et IDE.⁹¹

# Start a headless, remotely controllable app-server
codex remote-control

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

Associez codex remote-control aux APIs de pagination de l’app-server ci-dessous lorsque vous construisez des interfaces qui doivent énumérer de longs historiques de threads sans charger chaque tour en mémoire d’un seul coup.

Pagination des threads de l’app-server (v0.130.0+)

Les clients de l’app-server peuvent désormais paginer les longs threads via trois vues distinctes des éléments de tour :⁹¹

Associez la pagination à l’interface ThreadStore introduite en v0.121.0 pour parcourir efficacement les threads de longue durée, en particulier dans les déploiements remote-control où l’orchestrateur peut se trouver sur une machine différente de celle des fichiers de rollout.⁸²

Rafraîchissement à chaud de la configuration de l’app-server (v0.130.0+)

Les threads actifs de l’app-server prennent désormais en compte les modifications de config.toml sans nécessiter de redémarrage — modifiez la configuration, enregistrez, et le thread en cours d’exécution reflétera les nouvelles valeurs au tour suivant. C’est le pendant correctif de codex remote-control : un serveur headless de longue durée peut être reconfiguré sur place plutôt que démantelé.⁹¹

Codex Cloud et tâches en arrière-plan [EXPERIMENTAL]

Statut : Codex Cloud est une fonctionnalité expérimentale. Les interfaces, la tarification et la disponibilité peuvent changer. OpenAI gère les environnements cloud, et vous ne contrôlez pas l’infrastructure.

Codex Cloud exécute les tâches de manière asynchrone dans des environnements gérés par OpenAI.⁴ Voir également GitHub Action et CI/CD pour intégrer Codex à votre pipeline CI.

Fonctionnement

1. Soumettez une tâche (via chatgpt.com/codex, l’intégration Slack ou CLI)
2. Codex clone votre dépôt dans une sandbox cloud isolée
3. L’agent travaille de manière autonome : lit le code, exécute les tests, effectue les modifications
4. Une fois terminé, Codex crée une PR ou fournit un diff pour revue
5. Appliquez les résultats localement avec codex apply <TASK_ID>

Accès Internet dans le cloud

L’accès Internet de l’agent est désactivé par défaut et configuré par environnement :

• Off : pas d’accès Internet pour l’agent (par défaut)
• On : liste blanche de domaines optionnelle + restrictions de méthodes HTTP

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

Les scripts d’installation peuvent encore utiliser Internet pour installer les dépendances, même lorsque l’accès Internet de l’agent est désactivé.

Intégration Slack

Mentionnez @Codex dans un canal ou un fil Slack pour lancer une tâche cloud.

Prérequis : 1. Un plan ChatGPT éligible (Plus, Pro, Business, Enterprise ou Edu) 2. Un compte GitHub connecté 3. Au moins un environnement cloud configuré 4. L’application Slack installée pour votre espace de travail

Codex répond avec un lien vers la tâche et publie les résultats une fois terminés.

CLI Cloud

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

L’application de bureau Codex

L’application de bureau Codex (macOS et Windows) fournit une interface graphique optimisée pour la gestion multi-projets.¹⁶ La version Windows a été lancée le 4 mars 2026 avec la prise en charge native de PowerShell et un sandbox Windows natif.⁶⁶

Installation

codex app                      # Auto-downloads and installs on first run

Ou téléchargez directement : Codex.dmg (macOS) | Disponible sur le Microsoft Store (Windows)

Fonctionnalités clés

Modes de thread

Chaque thread s’exécute dans l’un des trois modes, sélectionné lors de sa création :

Mécanique d’isolation Worktree :

Lorsque vous démarrez un thread Worktree, l’application de bureau : 1. Crée un nouveau worktree git (git worktree add) dans un répertoire temporaire 2. Effectue le checkout d’une nouvelle branche depuis votre HEAD actuel 3. Exécute l’agent à l’intérieur du worktree — toutes les modifications de fichiers sont isolées 4. Présente une revue de diff une fois terminée — vous choisissez quels changements fusionner

Cela signifie que plusieurs threads Worktree peuvent s’exécuter simultanément sur le même dépôt sans conflit. Chacun obtient sa propre branche et son propre répertoire de travail.

Automatisations

Les automatisations s’exécutent localement dans l’application, donc l’application doit être en cours d’exécution et le projet disponible sur le disque :

• Dans les dépôts Git, les automatisations utilisent des worktrees d’arrière-plan dédiés (isolés de votre répertoire de travail)
• Dans les projets non-Git, les exécutions ont lieu directement dans le répertoire du projet
• Les automatisations utilisent vos paramètres de sandbox par défaut

Configurer une automatisation : 1. Ouvrez un projet dans l’application de bureau 2. Cliquez sur l’onglet Automations dans la barre latérale 3. Définissez un déclencheur (planification, webhook ou manuel) 4. Rédigez le prompt et sélectionnez le mode d’exécution (local ou worktree) 5. Définissez le niveau de raisonnement pour l’exécution de l’automatisation (App v26.312)⁷² 6. Les automatisations s’exécutent selon la planification et placent les résultats en file d’attente pour examen

Exemples de cas d’usage : - Triage des issues : Catégorisez et priorisez automatiquement les nouvelles issues - Surveillance CI : Observez les échecs de build et suggérez des correctifs - Réponse aux alertes : Réagissez aux alertes de monitoring avec une analyse diagnostique - Mises à jour des dépendances : Vérifiez et appliquez les correctifs de sécurité

Les résultats apparaissent dans une file d’attente de revue pour approbation humaine.

Prise en charge de Windows

L’application de bureau Codex a été lancée sur Windows le 4 mars 2026 (App v26.304) avec la prise en charge native de PowerShell, un sandbox Windows natif et une parité fonctionnelle complète incluant les skills, les automatisations et les worktrees, sans nécessiter WSL.⁶⁶

GitHub Action & CI/CD

L’Action GitHub officielle intègre Codex à votre pipeline CI/CD.¹⁸

Utilisation de base

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Options de configuration

Sortie : final-message, le texte de réponse final de Codex pour les étapes/jobs en aval.

Stratégies de sécurité

Contrôles d’accès

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

Par défaut : Seuls les collaborateurs avec un accès en écriture peuvent déclencher les workflows Codex.

Codex SDK

Le SDK TypeScript intègre les capacités d’agent de Codex dans des applications personnalisées.¹⁹

Installation

npm install @openai/codex-sdk

Utilisation de base

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

Fonctionnalités SDK avancées

• runStreamed(...) : Flux d’événements asynchrone pour les mises à jour intermédiaires
• outputSchema : Imposer une sortie finale structurée en JSON
• Entrée multimodale : Passez du texte + des images locales ({ type: "local_image", path: "..." })
• Workflows d’image (v0.117.0) : view_image retourne des URL, les images générées sont réouvrables, et l’historique des images survit à la reprise de session⁷⁵
• view_image multi-environnement (v0.130.0) : Pour les sessions qui s’étendent sur plusieurs environnements (introduit dans la v0.124.0 avec sélection d’environnement + répertoire de travail par tour, affiné dans la v0.125.0 avec environnements persistants), view_image résout désormais les chemins de fichiers via l’environnement sélectionné plutôt que via le système de fichiers local de l’orchestrateur. Une image attachée depuis un environnement distant est récupérée par rapport au répertoire de travail de cet environnement, et non par rapport à l’hôte qui exécute le SDK.⁹¹

Configuration de thread et de client

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.5" },
});

Les sessions persistent sous ~/.codex/sessions.

Runtime : Node.js 18+.

Optimisation des performances

Gestion du contexte

Les fenêtres de contexte varient selon le modèle. À la date d’avril 2026 : GPT-5.5 dans Codex offre 400K (1M dans l’API). GPT-5.4 / GPT-5.4-mini offrent respectivement 1M / 400K (équivalent API dans Codex). La famille GPT-5.3-Codex / GPT-5.2-Codex fonctionne sur 272K en entrée + 128K en sortie (budget total de 400K). Toutes se remplissent plus vite que vous ne le pensez — gérez de manière proactive :

1. Utilisez /compact régulièrement : Résume l’historique de conversation pour libérer des tokens
2. Fournissez de la documentation locale : Un AGENTS.md de qualité et de la documentation locale réduisent la surcharge d’exploration (qui consomme du contexte)
3. Utilisez @ pour attacher des fichiers spécifiques : Référencez les fichiers directement au lieu de demander à Codex de les trouver
4. Gardez les prompts ciblés : Des prompts cadrés avec des fichiers exacts consomment moins de contexte qu’une exploration ouverte

Efficacité des tokens

Optimisation de la vitesse

1. gpt-5.3-codex-spark : Variante à plus faible latence pour le pairing interactif
2. --profile fast : Modèle mini pré-configuré avec un raisonnement faible
3. Exécution parallèle d’outils : Codex exécute les lectures/vérifications indépendantes en simultané, structurez donc les prompts pour permettre cela
4. Boucles axées sur le résultat : Demandez « implémente, teste, corrige, arrête-toi quand c’est vert » au lieu d’instructions étape par étape

Comment déboguer les problèmes ?

Problèmes courants et solutions

Référence des messages d’erreur

Outils de diagnostic

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

Diagnostics TUI en session :

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

Remarque : codex --verbose n’est pas un flag de premier niveau valide. Utilisez les sous-commandes de débogage et les diagnostics TUI ci-dessus.

Réinstallation propre

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

Mode debug

codex debug app-server send-message-v2  # Test app-server client

Signaler des problèmes

/feedback                              # Send logs to Codex maintainers (in TUI)

Ou ouvrez un ticket sur github.com/openai/codex/issues.¹

Codex Security [PREVIEW]

Codex Security est entré en research preview le 6 mars 2026, apportant une revue de sécurité applicative contextuelle au sein de la stack Codex.⁷⁷ Disponible pour les clients ChatGPT Pro, Enterprise, Business et Edu via Codex web.

Comment ça fonctionne : Codex Security analyse les dépôts pour construire un modèle de menace spécifique au projet, identifie les vulnérabilités classées selon leur impact réel, et soumet les résultats à des tests de pression dans un environnement sandboxé pour les valider. L’agent fait remonter des résultats à plus haute confiance accompagnés de correctifs, réduisant le bruit issu de bugs insignifiants.

Performance : Pendant le research preview, Codex Security a scanné 1,2 million de commits et identifié 10 561 vulnérabilités de gravité élevée. La précision s’est améliorée avec le temps — réduisant le bruit de 84 %, réduisant les surévaluations de gravité de plus de 90 %, et divisant par deux les taux de faux positifs. Le système a trouvé de véritables vulnérabilités dans OpenSSH, GnuTLS et Chromium, avec 14 CVE attribués.⁷⁷

Remarque : Codex Security est distinct du modèle de sécurité sandbox intégré au CLI. Le sandbox protège votre machine de Codex ; Codex Security protège votre base de code des vulnérabilités.

Déploiement en entreprise

Contrôles administrateur (requirements.toml)

Les administrateurs appliquent la politique d’entreprise via requirements.toml, un fichier de configuration imposé par l’administrateur qui contraint les paramètres sensibles à la sécurité que les utilisateurs ne peuvent pas remplacer :²¹

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "never"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

Contrairement au config.toml au niveau utilisateur qui définit les préférences, requirements.toml est une couche de contrainte stricte qui restreint les valeurs que les utilisateurs peuvent sélectionner, et les utilisateurs ne peuvent pas la remplacer. Les règles de requirements administrateur ne peuvent que prompt ou forbid (jamais autoriser silencieusement).

Configuration MDM macOS

Distribuez via MDM en utilisant le domaine de préférences com.openai.codex.²¹ Codex respecte les charges utiles MDM macOS standard (Jamf Pro, Fleet, Kandji, etc.). Encodez le TOML en base64 sans retour à la ligne :

Précédence (du plus élevé au plus bas) :

1. Préférences gérées macOS (MDM)
2. Requirements récupérés depuis le cloud (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (système de fichiers local)

Les requirements cloud ne remplissent que les champs de requirements non définis, de sorte que les couches gérées de précédence supérieure l’emportent toujours. Les requirements cloud fonctionnent au mieux ; si la récupération échoue ou expire, Codex continue sans la couche cloud.

Intégration OpenTelemetry

Codex prend en charge la propagation du contexte de trace OpenTelemetry depuis les variables d’environnement OTel standard jusqu’aux appels OpenAI API. Définissez les variables d’environnement standard avant de lancer Codex :

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• Les variables d’environnement standard OTEL_* sont respectées (endpoint, nom de service, attributs de ressource)
• Le contexte de trace se propage à travers Codex jusqu’aux appels API, permettant une observabilité de bout en bout
• Utilisez les attributs de ressource pour étiqueter les traces par équipe, environnement ou projet
• Gardez à l’esprit les exigences de confidentialité lors de l’activation de la journalisation des prompts/outils — les traces peuvent contenir des extraits de code
• Métadonnées de trace OpenTelemetry configurables (v0.130.0+). Au-delà de l’enveloppe standard OTEL_RESOURCE_ATTRIBUTES, le crate codex-otel expose désormais des métadonnées de trace configurables afin que les administrateurs puissent étiqueter les traces avec des dimensions spécifiques à l’organisation (centre de coûts, ID de projet, référence de ticket) sans reconstruire OTEL_RESOURCE_ATTRIBUTES à partir de zéro à chaque invocation. Combinez cela avec les analyses enrichies de revue/feedback livrées dans la même version pour un débogage et un triage unifiés à travers les sessions CLI, app-server et remote-control.⁹¹

Accès entreprise

• ChatGPT Business / Enterprise / Edu : accès contrôlé par l’administrateur de l’organisation, avec des requirements récupérés depuis le cloud appliqués automatiquement. Prend en charge le SSO via SAML/OIDC à travers votre fournisseur d’identité (Okta, Entra ID, etc.)
• API : authentification API standard, facturation et contrôles d’organisation/projet. OpenAI publie des rapports SOC 2 Type II et SOC 3 ; un BAA HIPAA est disponible pour le niveau Enterprise
• Codex SDK : intégration dans les outils et flux de travail internes
• Application des politiques à grande échelle : utilisez requirements_toml_base64 distribué via MDM ou /etc/codex/requirements.toml au niveau du système de fichiers

Gestion des données et conformité : - Les entrées/sorties API ne sont pas utilisées pour l’entraînement selon les conditions Business/Enterprise/API d’OpenAI - Pour la résidence des données, le trafic OpenAI API transite par défaut par une infrastructure basée aux États-Unis ; pour les exigences de résidence des données dans l’UE, consultez l’équipe commerciale Enterprise d’OpenAI - Les transcriptions de session sont stockées localement ; seuls les appels API quittent la machine - ChatGPT Enterprise prend en charge les cadres de conformité incluant SOC 2, GDPR et CCPA

Stratégie de déploiement

Déploiement progressif recommandé pour les organisations :

1. Pilote (Semaine 1-2) : déployez auprès de 3-5 ingénieurs seniors avec requirements.toml imposant le mode sandbox untrusted et la recherche web cached. Recueillez les retours sur les modèles AGENTS.md et les besoins en serveurs MCP.
2. Extension à l’équipe (Semaine 3-4) : déployez à l’équipe complète. Distribuez le config.toml standard de l’équipe via MDM ou dépôt. Activez le sandbox workspace-write pour les dépôts de confiance.
3. Intégration CI (Semaine 5-6) : ajoutez codex-action aux pipelines CI/CD pour la revue automatisée des PR et la génération de tests. Utilisez --ephemeral pour garder les coûts prévisibles.
4. À l’échelle de l’organisation (Mois 2+) : déployez via MDM avec requirements.toml imposant les serveurs MCP approuvés, les politiques de sandbox et les listes blanches de modèles.

Modèles d’audit

Suivez l’utilisation de Codex et appliquez la conformité :

• Traces OpenTelemetry : surveillez le volume d’appels API, l’utilisation des tokens et la latence par équipe
• Persistance des sessions : auditez ~/.codex/sessions/ pour la revue de conformité (désactivez avec --ephemeral dans les contextes sensibles)
• Application de l’identité MCP : requirements.toml enregistre les tentatives de serveur bloquées — examinez pour détecter une utilisation d’outil non autorisée
• Piste d’audit Git : toutes les modifications de fichiers Codex passent par git standard — examinez via l’historique des branches et les diffs de PR

Bonnes pratiques et anti-modèles

Modèles de prompts

1. Prompts pilotés par les contraintes : commencez par les limites. « Ne modifiez PAS les contrats API. Refactorisez uniquement l’implémentation interne. »
2. Étapes de reproduction structurées : les étapes numérotées produisent de meilleurs correctifs que les descriptions vagues
3. Demandes de vérification : terminez par « Lancez le linter et la suite de tests pertinente la plus petite. Indiquez les commandes et les résultats. »
4. Références de fichiers : utilisez @filename pour joindre des fichiers spécifiques au contexte
5. Boucles pilotées par le résultat : « Implémentez, lancez les tests, corrigez les échecs, n’arrêtez que lorsque tous les tests passent. » Codex itère jusqu’à la fin

Philosophie de test

La communauté converge vers une collaboration avec l’IA pilotée par les tests :²²

• Définissez les tests en amont comme signaux d’achèvement
• Laissez Codex itérer jusqu’à ce que les tests passent (rouge → vert → refactor)
• Adoptez les modèles de programmation Tiger Style
• Fournissez le texte exact du fichier lorsque vous demandez des patchs. Codex utilise une correspondance stricte, et non un patching flou basé sur l’AST

Bonnes pratiques de gestion du contexte

• Fournissez de la documentation locale de haute qualité plutôt que de vous appuyer sur la recherche web
• Maintenez un markdown structuré avec des tables des matières et des fichiers de progression (« divulgation progressive »)
• Normalisez les fins de ligne (LF vs CRLF) sur les fichiers suivis pour éviter les échecs de patch
• Gardez AGENTS.md concis, car les instructions longues sont expulsées du contexte

Workflow Git

• Créez toujours une nouvelle branche avant de lancer Codex sur des dépôts inconnus
• Utilisez des workflows basés sur les patchs (git diff / git apply) plutôt que des modifications directes
• Examinez les suggestions de Codex comme des PR de revue de code
• Utilisez /diff pour vérifier les modifications avant de committer

Skills et prompts communautaires

Le dépôt feiskyer/codex-settings fournit des configurations maintenues par la communauté :²³

Prompts réutilisables (dans ~/.codex/prompts/) : - deep-reflector : extrait les apprentissages des sessions de développement - github-issue-fixer [issue-number] : analyse systématique des bugs et création de PR - github-pr-reviewer [pr-number] : workflows de revue de code - ui-engineer [requirements] : développement frontend de qualité production

Skills communautaires : - claude-skill : transfert de tâches vers Claude Code avec modes de permission - autonomous-skill : automatisation de tâches multi-sessions avec suivi de progression - deep-research : orchestration de sous-tâches en parallèle - kiro-skill : pipeline exigences → conception → tâches → exécution

Anti-modèles

Erreurs courantes qui gaspillent des tokens, produisent de mauvais résultats ou créent des workflows frustrants.

Anti-modèles de coût

Anti-modèles de contexte

Anti-modèles de workflow

Anti-modèles de prompt

Recettes de workflow

Modèles de bout en bout pour les scénarios de développement courants.

Recette 1 : configuration d’un nouveau projet

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

Examinez l’AGENTS.md généré, modifiez-le pour qu’il corresponde à vos conventions, puis :

> Run the health endpoint test and confirm it passes

Recette 2 : flux de développement quotidien

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

Examinez avec /diff, puis committez.

Recette 3 : refactor complexe avec le mode plan

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

Examinez le plan. Approuvez ou orientez :

[Tab] Also add a migration script using Alembic

Après l’exécution par Codex, vérifiez :

> Run the full test suite and report results
> /diff

Recette 4 : revue de PR avec codex exec

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

Recette 5 : débogage avec les Cloud Tasks [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

Vérifiez la progression plus tard :

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

Appliquez le correctif localement une fois terminé :

codex apply <TASK_ID>

## Guide de migration

### Depuis Claude Code

| Concept Claude Code | Équivalent Codex |
|---------------------|------------------|
| `CLAUDE.md` | `AGENTS.md` (standard ouvert) |
| `.claude/settings.json` | `.codex/config.toml` (format TOML) |
| Flag `--print` | Sous-commande `codex exec` |
| `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` |
| Hooks (12+ événements) | Hooks (SessionStart, Stop, UserPromptSubmit, AfterAgent, AfterToolUse ; v0.99.0–v0.116.0) |
| Subagents (outil Task) | Sous-agents (internes, max 6 ; pas d'équivalent utilisateur de l'outil Task) |
| `/compact` | `/compact` (identique) |
| `/cost` | `/status` (affiche l'utilisation des tokens) |
| Modèle : Opus/Sonnet/Haiku | Modèle : gpt-5.5 / gpt-5.4 / gpt-5.4-mini / variantes héritées gpt-5.3-codex (Codex utilise la famille de modèles GPT-5.x d'OpenAI) |
| `claude --resume` | `codex resume` |
| Règles de permissions | Modes sandbox + politiques d'approbation |
| Configuration MCP dans settings.json | Configuration MCP dans config.toml |

**Différences clés à comprendre :**

- **Le sandbox est au niveau du système d'exploitation** : Codex utilise Seatbelt/Landlock, pas des conteneurs. Les restrictions opèrent au niveau du noyau, en dessous de la couche applicative.
- **Les hooks s'enrichissent** : Codex prend désormais en charge 5 événements de hooks : `SessionStart`, `Stop` et `UserPromptSubmit` (v0.114.0–v0.116.0, expérimental) ainsi que `AfterAgent` (v0.99.0) et `AfterToolUse` (v0.100.0). Le système couvre le cycle de vie de la session, l'interception des prompts et l'automatisation au niveau des outils, bien que les 12+ événements de cycle de vie de Claude Code offrent toujours une couverture plus large. Pour les patterns d'automatisation non encore couverts, utilisez les instructions AGENTS.md ou les skills.
- **Sous-agents v2 (v0.117.0)** : Les sous-agents utilisent désormais des adresses basées sur les chemins (par exemple, `/root/agent_a`) avec des messages structurés inter-agents et le listage des agents.[^80] Cela étend la machinerie existante (max 6 simultanés, réduit de 12 dans v0.91.0). Les rôles multi-agents restent personnalisables via la configuration (v0.104.0+).[^57] v0.105.0 a ajouté `spawn_agents_on_csv` pour le fanout sur les lignes avec suivi de progression et ETA.[^63] Codex ne dispose toujours pas de l'expérience utilisateur explicite de l'outil Task de Claude Code pour la délégation dirigée par l'utilisateur — utilisez les tâches cloud ou l'orchestration SDK pour les patterns de délégation.
- **AGENTS.md est inter-outils** : Votre AGENTS.md fonctionne dans Cursor, Copilot, Amp, Jules, Gemini CLI et plus de 60 000 projets open source. CLAUDE.md est exclusif à Claude.
- **Les profils remplacent le changement manuel** : Au lieu de modifier les flags à chaque exécution, définissez des profils dans config.toml.

### Depuis GitHub Copilot

| Concept Copilot | Équivalent Codex |
|-----------------|------------------|
| Copilot CLI (terminal agentique) | CLI interactif ou application desktop |
| Agents spécialisés (Explore, Plan) | Skills + mode plan + mode steer |
| `copilot-instructions.md` / AGENTS.md | `AGENTS.md` (même standard) |
| Prise en charge MCP | Prise en charge MCP (STDIO + HTTP) |
| ACP (Agent Client Protocol) | Hooks (AfterAgent, AfterToolUse) |
| Copilot SDK | Codex SDK (TypeScript) |
| Workflows d'agent de coding | Agent Codex avec contrôles sandbox/approbation + tâches cloud |

**Ce que vous gagnez :**
- Sandboxing au niveau du système d'exploitation (Seatbelt/Landlock — appliqué par le noyau plutôt que par conteneur)
- Délégation de tâches cloud avec `codex apply`
- Profils de configuration pour le changement de workflow
- Application desktop avec isolation par worktree

### Depuis Cursor

| Concept Cursor | Équivalent Codex |
|---------------|------------------|
| Règles de projet (`.cursor/rules`) / `AGENTS.md` | `AGENTS.md` + profils/configuration |
| Workflows de chat/composer d'agent | CLI interactif ou application desktop |
| Références de fichiers `@` | Références de fichiers `@` (identique) |
| Apply/edit + revue | Patching et revue de diff intégrés |

---

## Carte de référence rapide

```text
╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "task" Sandboxed auto   ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Journal des modifications

Références

Note sur les URL du blog OpenAI : les références ¹⁶, ²⁵–³⁰, ³³, ⁶⁴, ⁶⁶, ⁶⁷, ⁷⁶ et ⁷⁷ pointent vers des articles de blog openai.com/index/ qui renvoient HTTP 403 à l’accès automatisé en raison de la protection anti-bot Cloudflare. Ces URL sont valides lorsqu’elles sont consultées depuis un navigateur web standard.