Codex CLI: The Definitive Technical Reference

En résumé : Codex est un agent de programmation multi-surface qui lit votre codebase, 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 fondamentaux (config.toml, le modèle sandbox/approbation, AGENTS.md, MCP et les skills) et Codex devient un multiplicateur de force. Utilisez les profils pour le changement de contexte, /compact pour gérer le budget de 272K tokens, et AGENTS.md pour des instructions de projet inter-outils compatibles avec Codex, Cursor, Amp et d’autres.

Codex fonctionne comme un agent de programmation multi-surface, et non comme un chatbot qui écrit du code. Le CLI lit votre codebase, 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 raisonne globalement ; la même intelligence alimente quatre surfaces distinctes selon votre façon de travailler.

La différence entre une utilisation occasionnelle et une utilisation efficace de Codex repose sur cinq systèmes fondamentaux. 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 et approbation : détermine 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 : encapsule une expertise métier réutilisable

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

Note de stabilité : les fonctionnalités marquées [EXPERIMENTAL] sont susceptibles de changer entre les versions. Codex Cloud et le groupe de commandes MCP sont tous deux expérimentaux à partir de la v0.107.0. Le CLI principal, le sandbox, AGENTS.md, config.toml et les Skills sont stables.

Points clés

• Quatre surfaces, un seul cerveau : CLI, application de bureau, extension IDE et tâches cloud partagent tous la même intelligence GPT-5.x-Codex — choisissez la surface qui correspond à votre flux de travail.
• Sandboxing au niveau du système d’exploitation : Codex applique les restrictions de système de fichiers et de réseau au niveau du noyau (Seatbelt sur macOS, Landlock + seccomp sur Linux), et non à l’intérieur de conteneurs.
• AGENTS.md est multi-outils : 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 éliminent les changements de contexte : définissez des préréglages de configuration nommés (fast, careful, auto) et basculez entre eux avec --profile.
• Le contexte d’entrée de 272K se remplit vite : 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 vous situe :

La Carte de référence rapide en fin de document fournit un résumé synthétique 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 à travers 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         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Couche centrale : la famille de modèles GPT-5.x-Codex alimente l’ensemble du système. Depuis la v0.107.0, gpt-5.3-codex est le modèle par défaut avec une fenêtre de contexte d’entrée de 272K tokens (128K en sortie, budget total de 400K).³⁵ Il lit les fichiers, écrit des correctifs, exécute des 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 consomme des tokens.

Couche de sécurité : chaque commande exécutée par Codex passe par un sandbox au niveau du système d’exploitation. 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, et non à l’intérieur de conteneurs. La politique d’approbation détermine ensuite quand demander une confirmation humaine.

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

Couche de surface : CLI pour les utilisateurs avancés du terminal et l’automatisation. L’application de bureau pour la gestion de projets multi-threads. L’extension IDE pour les boucles édition-compilation-test. Le cloud pour les tâches asynchrones qui s’exécutent de manière indépendante.

L’idée essentielle : la plupart des utilisateurs n’utilisent qu’une seule surface. Les utilisateurs avancés exploitent les quatre : le cloud pour les tâches de longue durée, CLI pour les opérations déterministes sur le dépôt, l’extension IDE pour les boucles de développement serrées, et l’application de bureau 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. Système de configuration en profondeur
5. Quel modèle choisir ?
6. Combien coûte Codex ?
7. Cadres de décision
8. Comment fonctionne le sandbox et le système d’approbation ?
9. Comment fonctionne AGENTS.md ?
10. Hooks
11. Qu’est-ce que MCP (Model Context Protocol) ?
12. Runtime REPL JavaScript
13. Que sont les Skills ?
14. Mode Plan et collaboration
15. Système de mémoire
16. Gestion des sessions
17. Mode non interactif (codex exec)
18. Codex Cloud et tâches en arrière-plan
19. L’application de bureau Codex
20. GitHub Action et CI/CD
21. Codex SDK
22. Optimisation des performances
23. Comment déboguer les problèmes ?
24. Déploiement entreprise
25. Bonnes pratiques et anti-patterns
26. Recettes de workflow
27. Guide de migration
28. Carte de référence rapide
29. Journal des modifications
30. Références

Comment installer Codex ?

Gestionnaires de paquets

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

# Homebrew (macOS)
brew install --cask 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 en tant qu’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 binaire correspondant et le place dans votre PATH.

Téléchargements de binaires

Pour les environnements sans npm ni Homebrew, téléchargez les binaires spécifiques à votre plateforme depuis les releases GitHub¹ :

Configuration requise

• macOS : Apple Silicon ou Intel (support complet du sandbox via Seatbelt)
• Linux : x86_64 ou arm64 (sandbox via Landlock + seccomp)
• Windows : sandbox natif avec tokens restreints (promu depuis le statut expérimental en v0.100.0). WSL également supporté²

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 à toutes les fonctionnalités, y compris les tâches cloud.
2. Clé API : configurée via la variable d’environnement CODEX_API_KEY ou codex login --with-api-key. Certaines fonctionnalités (threads cloud) peuvent être indisponibles.

Astuce avancée : 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 (trousseau si disponible, fichier en secours).

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érification de l’installation

codex --version
# Codex CLI v0.104.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. Naviguer vers un projet :

cd ~/my-project                  # Any git repo works

3. Lancer Codex :

codex

Vous verrez le TUI interactif. 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. Effectuer une modification :

> Add input validation to the login endpoint

Codex propose des modifications sous forme de diff. Validez 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. Examinez le plan, puis approuvez pour lancer l’exécution.

7. Vérifier votre travail :

> /diff

Consultez toutes les modifications apportées par Codex au cours de la session en cours.

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

Surfaces d’interaction principales

Codex offre quatre interfaces distinctes, alimentées par la même intelligence. Chaque surface est optimisée pour un schéma de travail différent.

1. CLI interactif (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

Le TUI est une application plein écran comprenant :

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

Raccourcis clés du TUI :

Slash commands disponibles dans le TUI :

2. Codex Desktop App (macOS)

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

L’application de bureau ajoute des fonctionnalités que le CLI ne propose pas :

• Multi-tâches : exécutez plusieurs agents en parallèle sur différents projets simultanément
• Isolation par git worktree : chaque fil de discussion travaille sur une copie isolée de votre dépôt
• Revue de diff intégrée : indexez, annulez et committez des modifications sans quitter l’application
• Terminal intégré : un terminal par fil pour exécuter des commandes
• Duplication de conversations : créez des branches de conversation pour explorer des alternatives
• Fenêtres flottantes détachables : détachez des conversations dans des fenêtres portables
• Automatisations : planifiez des tâches récurrentes (tri des issues, surveillance CI, réponse aux alertes)

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

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

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

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

Installez depuis le VS Code Marketplace ou les boutiques d’extensions 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 :

• Lancer et oublier : mettez en file d’attente des tâches qui s’exécutent indépendamment de votre machine locale
• Exécution parallèle : lancez plusieurs tâches cloud simultanément
• Création de PR : Codex crée des pull requests à partir du travail accompli
• Application locale : récupérez les résultats cloud dans votre dépôt 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.⁴

Plongée dans le système de configuration

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

Priorité (de la plus haute à la plus basse)

1. Substitutions de session (la plus haute) : drapeaux CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) et substitutions -c key=value
2. Configuration du projet (.codex/config.toml, découverte depuis le répertoire courant en remontant jusqu’à la racine du projet ; le répertoire 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 sous 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 répertoire par défaut ~/.codex. Utile pour les environnements CI/CD ou les configurations multi-comptes.

Référence complète de la configuration

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

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.3-codex"                # Default model (272K input context)
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.2-codex"         # 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-failure|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.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

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

Activer 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. Substituez-le par session avec --profile.

Fournisseurs de modèles personnalisés

Connectez-vous à Azure, à 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"

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

Avertissement : Le protocole filaire chat/completions (wire_api = "chat") a été déprécié 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 points de terminaison OpenAI, utilisez wire_api = "responses" à la place.

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"

Substitutions de configuration en ligne

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

codex -c model="gpt-5.2-codex" "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 (février 2026)

La liste exacte des modèles varie selon le compte et le déploiement. Depuis la v0.106.0, gpt-5.3-codex est visible dans la liste des modèles CLI pour les utilisateurs de clé API.⁶² Vérifiez votre cache local : ~/.codex/models_cache.json.

Organigramme de sélection du 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 (interactive, lower latency)
   │  └─ No
   │     ├─ Is this a multi-file refactor or migration?
   │     │  ├─ Yes → gpt-5.2-codex (272K context, strong at long tasks)
   │     │  └─ No → gpt-5.3-codex (default, best overall)
   └─ Still unsure? → gpt-5.3-codex

Effort de raisonnement

Contrôlez l’intensité de la « réflexion » du modèle avant de répondre :

Les niveaux disponibles 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 avancée : le raisonnement xhigh peut utiliser 3 à 5 fois plus de tokens que medium pour la même requête. Réservez-le aux problèmes véritablement complexes où la réflexion supplémentaire en vaut la peine.

Changement de modèle

Changez de modèle en cours de session avec la commande /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 abonnements ChatGPT

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

Tarifs promotionnels : l’accès Free/Go et les limites de débit ×2 pour les abonnements payants ont coïncidé avec le lancement du Codex Desktop App (février 2026). Ces limites plus élevées s’appliquent sur toutes les surfaces — application, CLI, IDE et cloud. OpenAI n’a pas annoncé de date de fin.¹⁷

Coûts en crédits

Les opérations Codex consomment des crédits de votre allocation d’abonnement :

Les abonnements Enterprise et Edu ajustent les crédits selon l’allocation contractuelle. Vérifiez /status dans le TUI pour consulter votre utilisation actuelle.

Facturation API

Lorsque vous utilisez Codex via l’API, OpenAI facture l’utilisation par token selon la tarification standard de l’API OpenAI pour le modèle sélectionné (plus les éventuelles réductions de mise en cache des prompts). Consultez la page officielle de tarification API pour les tarifs en vigueur.²¹

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 courantes
2. Réservez le raisonnement élevé : n’utilisez xhigh que pour les problèmes véritablement complexes, car cela coûte 3 à 5 fois plus de tokens
3. Utilisez --ephemeral : ignorez 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 flux d’automatisation
6. Surveillez l’utilisation : vérifiez /status dans le TUI et les tableaux de bord de facturation de votre organisation

Exemples de coûts réels

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

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 courantes afin de réduire les coûts de ~40-60 %. Les tokens d’entrée mis en cache sont facturés à prix réduit.

Surcharge cachée de tokens

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

Astuce avancée : surveillez votre utilisation réelle 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 maîtrise 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 la CI/CD — les pipelines automatisés ont rarement besoin du raisonnement maximal - Budgétisation par profils — définissez des profils ci, review et dev avec des plafonds de coûts appropriés - Surveillez via OpenTelemetry — les déploiements entreprise peuvent exporter la télémétrie d’utilisation vers les piles d’observabilité existantes

Cadres de décision

Quand utiliser chaque interface

Quand utiliser chaque mode 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

Steer Mode : Enter vs Tab

Règle générale : Enter = « arrête-toi, écoute ça maintenant. » Tab = « quand tu as fini, fais aussi ça. »

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 choisir ?

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

Configuration 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.⁵ Consultez également Déploiement en entreprise pour les contraintes requirements.toml que les administrateurs appliquent à l’échelle de l’organisation.

Couche 1 : Sandbox (ce qui est possible)

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

Application spécifique à chaque plateforme :

• macOS : Le framework Seatbelt d’Apple via sandbox-exec avec des profils spécifiques à chaque mode compilés à l’exécution et appliqués par le noyau⁶
• 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 profondeur.⁵ Bubblewrap (bwrap) est intégré et compilé dans le cadre de la compilation Linux (promu d’optionnel dans la v0.100.0)⁷
• Windows : Sandbox natif avec des jetons restreints (promu d’expérimental dans la v0.100.0). WSL également pris en charge (hérite de Landlock + seccomp de Linux)

Pourquoi c’est important : Contrairement au sandboxing basé sur les conteneurs (Docker), le sandboxing au niveau du système d’exploitation est plus rapide, plus léger 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 du sandbox par fork zsh (v0.106.0) : Correction d’une vulnérabilité où l’exécution de shell via un fork zsh pouvait contourner les restrictions du sandbox.⁶² Si vous utilisez une version antérieure, mettez à jour immédiatement. - Limite de taille d’entrée (v0.106.0) : Codex applique désormais une limite d’entrée d’environ 1 million de caractères pour éviter les blocages causés par des charges utiles excessivement volumineuses.⁶² - Système de fichiers /dev sous Linux (v0.105.0) : Les commandes sandboxées sous 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ériques.⁶³

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 que 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’interrompt pour demander une confirmation humaine :

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 sandbox supplémentaires et un rejet granulaire :⁶³

• Permissions 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 des appels d’outils individuels avec un retour d’information afin que Codex puisse ajuster son approche plutôt que de simplement retenter la même commande

Le flag --full-auto

--full-auto est un alias pratique pour :

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

Point critique : --full-auto remplace toute valeur --sandbox explicite. Si vous passez --full-auto --sandbox read-only, vous obtenez workspace-write car --full-auto a la priorité.⁸

Configurations recommandées

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

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

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

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

Cette combinaison est le « point idéal » recommandé par la communauté : capacité maximale mais approbation requise pour chaque commande.⁹

Automatisation CI/CD :

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

Activer l’accès réseau

Codex bloque l’accès réseau par défaut en mode workspace-write. Activez-le lorsque 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

Support 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 existant des proxys HTTPS_PROXY et SOCKS5 (v0.93.0+), couvrant toutes les couches de transport.

Tester le sandbox

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

codex sandbox macos --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

Si le sandbox fonctionne correctement, les deux commandes devraient échouer avec une erreur de permission refusée — le sandbox empêche la lecture de fichiers système sensibles même en mode --full-auto. Si l’une des commandes réussit, la configuration de votre 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 gouverné 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 comment Codex se comporte au sein d’un dépôt ou répertoire spécifique. Consultez Skills pour 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 répertoires :

1. Global (~/.codex/) : AGENTS.override.md > AGENTS.md
2. Projet (racine git jusqu’au répertoire courant) : Chaque niveau est vérifié pour AGENTS.override.md > AGENTS.md > noms de fichiers alternatifs
3. Fusion : Les fichiers se concatènent de la racine vers le bas ; les fichiers plus proches apparaissent plus tard dans le prompt et remplacent les directives 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

Basé sur les recommandations directes de Codex lui-même et les pratiques de la communauté¹¹ :

À FAIRE : - Soyez spécifique : "Use rg --files for discovery" est mieux que "search efficiently" - Définissez la clôture : Que signifie « terminé » ? (tests réussis, lint propre, etc.) - Incluez les commandes : Build, test, lint, format (invocations exactes) - Organisez par tâche : Sections codage, revue, publication, incident/débogage - Définissez l’escalade : Que faire en cas de blocage ou d’état inattendu

À NE PAS FAIRE : - Copier 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 + pas de budget d’exécution) - Écrire de la documentation en 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.

## Sécurité
- Ne committez jamais de secrets. Utilisez `.env` pour la configuration locale.
- Validez tous les appels API externes avec une gestion d'erreurs appropriée.

Le mécanisme de remplacement

AGENTS.override.md à n’importe quel niveau de répertoire remplace le AGENTS.md normal pour cette portée. Utilisez-le pour :

• Gel de release : « Pas de nouvelles fonctionnalités, corrections uniquement »
• Mode incident : « Toutes les modifications doivent être revues par l’astreinte »
• Durcissement temporaire : « Pas de mises à jour de dépendances 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 ajouté les hooks dans la v0.99.0 (AfterAgent) et la v0.100.0 (AfterToolUse). Le système de hooks est encore à un stade précoce comparé aux 12+ événements de cycle de vie de Claude Code, mais il fournit des points d’entrée d’automatisation pour les workflows courants.

É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"

Reproduire les patterns de hooks de Claude Code

Si vous migrez depuis Claude Code, voici comment obtenir une automatisation similaire sans l’ensemble complet d’événements de hooks :

Astuce d’expert : Le système de hooks est en expansion active. Consultez le changelog de Codex pour les nouveaux événements de hooks à chaque release.

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é expérimental, et les commandes ainsi que le format de configuration peuvent changer entre les releases. Codex prend en charge deux types de transport : STDIO (processus locaux) et Streamable HTTP (serveurs distants).¹²

Configuration 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 des 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.

Exécuter Codex EN TANT QUE serveur MCP

Codex peut s’exposer en tant que serveur MCP pour l’orchestration multi-agents :¹³

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

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

Utilisation avec le SDK Agents (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

Patterns pratiques

Pattern 1 : Développement contextuel — Associez Context7 à la documentation de votre framework pour que Codex dispose toujours des références API actuelles :

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

Pattern 2 : Limites de sortie — Les réponses des outils MCP sont tronquées à environ 25K caractères par défaut. Pour les outils qui renvoient des charges utiles volumineuses (requêtes de base de données, captures de logs), utilisez enabled_tools pour restreindre les outils spécifiques et garder les réponses ciblées.

Pattern 2a : Sortie multimodale des outils (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, diagrammes, rendus de graphiques — de les transmettre directement au modèle pour analyse.⁶⁴

Pattern 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.

Runtime REPL JavaScript [EXPERIMENTAL]

Codex v0.100.0 a ajouté un runtime REPL JavaScript expérimental (js_repl) qui persiste l’état entre les appels d’outils. Dans la v0.106.0, le REPL a été promu vers la commande slash /experimental avec des vérifications de compatibilité au démarrage — il nécessite Node.js 22.22.0 ou supérieur.⁶²

Activation du JS REPL :

# In config.toml
[features]
js_repl = true

Ou activez-le en session via /experimental dans le TUI.

Exemple d’utilisation : Lorsqu’il est activé, Codex peut maintenir l’état entre les appels d’outils au sein d’une session :

// Codex can accumulate data across multiple tool calls
const results = await fetchTestResults();
const failures = results.filter(r => r.status === "failed");
console.log(`${failures.length} failures out of ${results.length} tests`);
// Variable 'failures' persists and is available in subsequent tool calls

Prérequis : Node.js 22.22.0+ (les vérifications au démarrage contrôlent la compatibilité). La v0.105.0 a ajouté un meilleur rapport d’erreurs et une récupération améliorée en cas d’échec du REPL.⁶³

Cette fonctionnalité est expérimentale. L’interface peut changer entre les releases.

Que sont les skills ?

Les skills sont des paquets de capacités réutilisables et spécifiques à une tâche que Codex charge à la demande. Ils suivent le standard ouvert 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 lien symbolique.

Créer un skill

Format de SKILL.md :

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

## Procédure d'audit de sécurité

1. Rechercher les secrets codés en dur avec `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Vérifier les injections SQL : rechercher l'interpolation de chaînes dans les requêtes
3. Vérifier la validation des entrées sur tous les endpoints API
4. Vérifier les vulnérabilités des dépendances : `pip audit` ou `npm audit`
5. Examiner les modèles d'authentification et d'autorisation
6. Rapporter les résultats avec des niveaux de sévérité (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)
• Créateur : Utilisez $skill-creator pour créer interactivement un nouveau skill
• Installateur : 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 les skills

Si un skill ne s’active pas :

1. Vérifier la découverte : /skills devrait le lister dans le TUI
2. Vérifier 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érifier enabled : Les skills avec enabled = false dans config.toml ne se chargent pas
4. Vérifier l’activation implicite : Si vous comptez sur la détection automatique, assurez-vous que allow_implicit_invocation: true est défini dans agents/openai.yaml
5. Utiliser 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 complet multi-fichiers montrant les références et les scripts fonctionnant 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`.

Invoquer avec : $deploy to staging ou $deploy production with canary rollout

Mode Plan 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 Cadres de décision pour l’arbre de décision « Mode Plan vs exécution directe ».

Entrer en 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 - Ne fait pas de modifications tant que vous n’avez pas approuvé - 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 ait terminé avant de donner des instructions, tapez simplement normalement après la fin du tour — aucun mode spécial n’est nécessaire.

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

Coloration syntaxique (v0.105.0) : Le TUI met désormais en surbrillance syntaxique les blocs de code et les 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 microphone.⁶³ Depuis la v0.107.0, les sessions vocales en temps réel prennent en charge la sélection de périphériques microphone et haut-parleur, vous permettant de choisir un matériel audio d’entrée/sortie spécifique.⁶⁴

Autres améliorations : - Les liens longs restent désormais cliquables même lorsqu’ils sont coupés sur plusieurs lignes dans le 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 est corrigée afin de 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, préférences et le contexte du projet à travers les sessions.²⁵

Commandes de mémoire

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

Que stocker

Les mémoires fonctionnent mieux pour les préférences persistantes et les faits liés au 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 mémoires sont chargées automatiquement. Cela signifie que les pipelines CI/CD et les scripts bénéficient du même contexte que les sessions interactives — pas besoin de répéter les instructions à chaque invocation.

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

• Nettoyage des secrets : Les mémoires sont automatiquement analysées pour détecter les secrets avant d’être écrites sur le disque
• Conscience du répertoire de travail : 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 phase 1, améliorant la qualité de la mémoire en se concentrant sur les interactions utilisateur
• Oubli basé sur les diffs (v0.106.0) : La mémoire utilise désormais un oubli basé sur les diffs pour supprimer les faits obsolètes, maintenant le stockage mémoire léger et pertinent au fil du temps⁶²
• Sélection sensible à l’utilisation (v0.106.0) : La récupération de mémoire est désormais sensible à l’utilisation, priorisant les mémoires fréquemment consultées et récemment pertinentes⁶²
• Mémoires configurables (v0.107.0) : Les mémoires sont désormais entièrement configurables. Utilisez codex debug clear-memories pour réinitialiser toutes les mémoires stockées et repartir de zéro — utile lors du changement de contexte entre des projets sans rapport ou lorsque l’état de la mémoire a dérivé⁶⁴

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 à Codex directement dans la conversation. Pour le contexte d’équipe partagé, utilisez AGENTS.md.

Gestion des sessions

Codex conserve les sessions dans ~/.codex/sessions/, permettant la reprise, la bifurcation et les flux de travail multi-threads à travers CLI et les interfaces de bureau.

Reprise

Reprenez là où vous vous étiez 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 /resume dans le TUI ouvre le même sélecteur interactif avec recherche.

Bifurcation

Créez une branche de conversation pour explorer des alternatives sans perdre votre progression actuelle :

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

Les bifurcations créent des threads indépendants partageant le même historique jusqu’au point de bifurcation. Les modifications dans une bifurcation n’affectent pas l’autre. Cela s’avère utile pour comparer des approches (par exemple, « bifurquer et essayer Redis au lieu de Memcached ») ou pour explorer des changements risqués en toute sécurité.

Bifurcation de threads en sous-agents (v0.107.0) : Les threads peuvent désormais être bifurqué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 bifurcation existant — au lieu de simplement créer une branche de conversation, le thread bifurqué devient un sous-agent avec son propre contexte d’exécution.⁶⁴

Liste des threads

Consultez et gérez les sessions actives :

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

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

Cycle de vie des sessions

Les sessions se synchronisent entre CLI et l’application de bureau — commencez dans l’un, continuez dans l’autre.

Mode non interactif (codex exec)

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

Utilisation de base

codex exec "summarize the repository structure"
codex exec --full-auto "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 standards.

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.

Codex Cloud et tâches en arrière-plan [EXPÉRIMENTAL]

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

Codex Cloud exécute des tâches de manière asynchrone dans des environnements gérés par OpenAI.⁴ Consultez également GitHub Action et CI/CD pour intégrer Codex dans 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 un sandbox cloud isolé
3. L’agent travaille de manière indépendante : lit le code, exécute les tests, effectue des 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 :

• Désactivé : pas d’accès Internet pour l’agent (par défaut)
• Activé : 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 de configuration peuvent toujours 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. Abonnement ChatGPT éligible (Plus, Pro, Business, Enterprise ou Edu) 2. Compte GitHub connecté 3. Au moins un environnement cloud configuré 4. 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é.

Cloud CLI

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 Codex Desktop App

L'application Codex Desktop App (macOS uniquement, Apple Silicon) fournit une interface graphique optimisée pour la gestion multi-projets.[^17]

### Installation

```bash
codex app                      # Auto-downloads and installs on first run

Ou téléchargez directement : Codex.dmg

Fonctionnalités principales

Modes de thread

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

Mécanisme d’isolation Worktree :

Lorsque vous lancez un thread Worktree, l’application de bureau : 1. Crée un nouveau git worktree (git worktree add) dans un répertoire temporaire 2. Effectue un checkout d’une nouvelle branche à partir de 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é — vous choisissez les modifications à réintégrer

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

Automations

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

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

Configuration d’une automation : 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 de thread 5. Les automations s’exécutent selon la planification et mettent les résultats en file d’attente pour révision

Exemples de cas d’utilisation : - Tri des issues : Catégorisez et priorisez automatiquement les nouvelles issues - Surveillance CI : Surveillez 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 révision pour approbation humaine.

Support Windows

Le support Windows est prévu. Consultez la page de l’application Codex Desktop App ou les versions de GitHub pour les mises à jour de disponibilité.¹⁸

GitHub Action et CI/CD

L’Action GitHub officielle intègre Codex dans 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 finale 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 disposant d’un accès en écriture peuvent déclencher les workflows Codex.

Codex SDK

Le TypeScript SDK 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 avancées du SDK

• runStreamed(...) : Flux d’événements asynchrone pour les mises à jour intermédiaires
• outputSchema : Imposer une sortie finale au format JSON
• Entrée multimodale : Transmettez du texte et des images locales ({ type: "local_image", path: "..." })

Configuration du thread et du 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.2-codex" },
});

Les sessions persistent sous ~/.codex/sessions.

Runtime : Node.js 18+.

Optimisation des performances

Gestion du contexte

Les modèles phares disposent de fenêtres d’entrée de 272K tokens (128K en sortie, 400K de budget total), mais elles se remplissent plus vite qu’on ne le pense. Gérez-les de manière proactive :

1. Utilisez /compact régulièrement : Résume l’historique de la conversation pour libérer des tokens
2. Fournissez de la documentation locale : Un AGENTS.md de qualité et une documentation locale réduisent la surcharge d’exploration (qui consomme du contexte)
3. Utilisez @ pour joindre des fichiers spécifiques : Référencez directement les fichiers au lieu de demander à Codex de les trouver
4. Gardez vos prompts ciblés : Des prompts précis 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 à latence réduite pour le pair-programming interactif
2. --profile fast : Modèle mini préconfiguré avec raisonnement faible
3. Exécution parallèle des outils : Codex exécute les lectures/vérifications indépendantes de manière concurrente, structurez donc vos prompts pour favoriser cela
4. Boucles orientées résultat : Demandez « implémenter, tester, corriger, arrêter 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

Note : 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 débogage

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

Signaler des problèmes

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

Ou déposez des issues sur github.com/openai/codex/issues.¹

Déploiement en entreprise

Contrôles administrateur (requirements.toml)

Les administrateurs appliquent les politiques d’entreprise via requirements.toml, un fichier de configuration imposé par l’administrateur qui contraint les paramètres sensibles en matière de sécurité que les utilisateurs ne peuvent pas outrepasser :²²

# /etc/codex/requirements.toml

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

# 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 utilisateur qui définit des préférences, requirements.toml est une couche de contraintes strictes qui restreint les valeurs que les utilisateurs peuvent sélectionner, et que ceux-ci ne peuvent pas outrepasser. Les règles d’exigences administrateur ne peuvent qu’inviter à confirmer ou interdire (jamais autoriser silencieusement).

Configuration MDM macOS

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

Ordre de priorité (du plus élevé au plus bas) :

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

Les exigences cloud ne remplissent que les champs d’exigences non définis, de sorte que les couches gérées de priorité supérieure l’emportent toujours. Les exigences 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 à partir des variables d’environnement OTel standard vers les appels API OpenAI. 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 OTEL_* standard 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 taguer 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

Accès entreprise

• ChatGPT Business / Enterprise / Edu : accès contrôlé par l’administrateur de l’organisation, avec des exigences récupérées depuis le cloud appliquées 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 tier Enterprise
• Codex SDK : intégration dans les outils et workflows 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 API OpenAI 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, RGPD et CCPA

Stratégie de déploiement

Déploiement progressif recommandé pour les organisations :

1. Pilote (Semaine 1-2) : déployer auprès de 3 à 5 ingénieurs seniors avec requirements.toml imposant le mode sandbox untrusted et la recherche web cached. Recueillir les retours sur les patterns AGENTS.md et les besoins en serveurs MCP.
2. Extension à l’équipe (Semaine 3-4) : déployer à l’ensemble de l’équipe. Distribuer le config.toml standard de l’équipe via MDM ou dépôt. Activer le sandbox workspace-write pour les dépôts de confiance.
3. Intégration CI (Semaine 5-6) : ajouter codex-action aux pipelines CI/CD pour la revue automatisée de PR et la génération de tests. Utiliser --ephemeral pour maintenir des coûts prévisibles.
4. Organisation entière (Mois 2+) : déployer via MDM avec requirements.toml imposant les serveurs MCP approuvés, les politiques de sandbox et les listes de modèles autorisés.

Modèles d’audit

Suivre l’utilisation de Codex et assurer la conformité :

• Traces OpenTelemetry : surveiller le volume d’appels API, l’utilisation de tokens et la latence par équipe
• Persistance des sessions : auditer ~/.codex/sessions/ pour la revue de conformité (désactiver avec --ephemeral dans les contextes sensibles)
• Application de l’identité MCP : requirements.toml journalise les tentatives de serveurs bloqués — examiner pour détecter l’utilisation non autorisée d’outils
• Piste d’audit Git : toutes les modifications de fichiers par Codex passent par le git standard — examiner via l’historique des branches et les diffs de PR

Bonnes pratiques et anti-patterns

Modèles de prompts

1. Prompts orientés contraintes : commencez par les limites. « Ne modifiez PAS les contrats API. Refactorisez uniquement l’implémentation interne. »
2. Étapes de reproduction structurées : des étapes numérotées produisent de meilleures corrections de bugs que des descriptions vagues
3. Demandes de vérification : terminez par « Exécutez le lint + la plus petite suite de tests pertinente. Rapportez les commandes et les résultats. »
4. Références de fichiers : utilisez @filename pour joindre des fichiers spécifiques au contexte
5. Boucles orientées résultats : « Implémentez, exécutez les tests, corrigez les échecs, arrêtez uniquement quand tous les tests passent. » Codex itère jusqu’à complétion

Philosophie de test

La communauté converge vers une collaboration IA pilotée par les tests :²³

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

Bonnes pratiques de gestion du contexte

• Fournissez une documentation locale de 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) dans les fichiers suivis pour éviter les échecs de patch
• Gardez AGENTS.md concis, car les instructions longues sont poussées hors du contexte

Workflow Git

• Créez toujours une nouvelle branche avant d’exécuter Codex sur des dépôts inconnus
• Utilisez des workflows basés sur les patches (git diff / git apply) plutôt que des modifications directes
• Examinez les suggestions de Codex comme des revues de code de PR
• Utilisez /diff pour vérifier les changements avant de commiter

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 : extraire les apprentissages des sessions de développement - github-issue-fixer [issue-number] : analyse systématique de 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 : déléguer des tâches à Claude Code avec des modes de permission - autonomous-skill : automatisation de tâches multi-sessions avec suivi de progression - deep-research : orchestration parallèle de sous-tâches - kiro-skill : pipeline exigences → conception → tâches → exécution

Anti-patterns

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

Anti-patterns de coût

Anti-patterns de contexte

Anti-patterns de workflow

Anti-patterns 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 le fichier AGENTS.md généré, modifiez-le pour correspondre à 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.

Vérifiez avec /diff, puis commitez.

Recette 3 : Refactorisation 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 tâches Cloud [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 la correction en local une fois terminé :

codex apply <TASK_ID>

Guide de migration

Depuis Claude Code

Différences clés à comprendre :

• Le sandbox opère 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 sont embryonnaires : Codex a ajouté les hooks dans la v0.99.0 (AfterAgent) et la v0.100.0 (AfterToolUse), mais le système en est à ses débuts comparé aux 12+ événements de cycle de vie de Claude Code. Pour les cas d’automatisation non encore couverts, utilisez les instructions AGENTS.md ou les skills.
• Les sub-agents sont internes mais désormais configurables : Codex dispose d’un mécanisme de sub-agents (max 6 simultanés, réduit de 12 dans la v0.91.0). Depuis la v0.104.0, les rôles multi-agents sont personnalisables via la configuration, permettant des rôles d’agents nommés avec des profils distincts.⁴⁹ La v0.105.0 a ajouté spawn_agents_on_csv pour la distribution en éventail sur les lignes avec suivi de progression et estimation du temps restant.⁶³ Codex ne dispose toujours pas de l’interface 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 schémas de délégation.
• AGENTS.md est multi-outils : Votre fichier 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

Ce que vous gagnez : - Sandboxing au niveau du système d’exploitation (Seatbelt/Landlock — appliqué au niveau du noyau vs basé sur des conteneurs) - Délégation de tâches cloud avec codex apply - Profils de configuration pour le changement de workflow - Application de bureau avec isolation par worktree

Depuis Cursor

Carte de référence rapide

╔═══════════════════════════════════════════════════════════════╗
║                    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                   ║
║  --full-auto                workspace-write + on-request      ║
║  --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   /init        AGENTS.md scaffold  ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║  /experimental Toggle experimental features (js_repl)        ║
║                                                               ║
║  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 --full-auto "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               ║
║                                                               ║
║  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-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Feb 2026, v0.106.0)                                  ║
║  gpt-5.3-codex         Default flagship (272K in / 400K)     ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K / 400K)  ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K/400K)║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

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 un HTTP 403 lors d’un accès automatisé en raison de la protection anti-bots Cloudflare. Ces URL sont valides lorsqu’elles sont consultées via un navigateur web standard.