Codex CLI : Le guide technique de référence

TL;DR: Codex is a multi-surface coding agent that reads your codebase, runs commands in an OS-level sandbox, patches files, and delegates tasks to the cloud. Master five core systems (config.toml, sandbox/approval model, AGENTS.md, MCP, and skills) and Codex becomes a force multiplier. Use profiles for context-switching, /compact to manage the context budget, and AGENTS.md for cross-tool project instructions that work in Codex, Cursor, Amp, and more. GPT-5.4 is now the recommended model with 1M context windows.

Codex operates as a multi-surface coding agent, not a chatbot that writes code. The CLI reads your codebase, executes commands in a sandbox, patches files, connects to external services via MCP, and delegates long-running tasks to the cloud. It runs locally but thinks globally; the same intelligence powers four distinct surfaces depending on how you work.

The difference between casual and effective Codex usage comes down to five core systems. Master these and Codex becomes a force multiplier:

1. Configuration system: controls behavior via config.toml
2. Sandbox & approval model: gates what Codex can do
3. AGENTS.md: defines project-level operating contracts
4. MCP protocol: extends capabilities to external services
5. Skills system: packages reusable domain expertise

I spent months running Codex alongside Claude Code across production codebases, CI/CD pipelines, and team workflows. This guide distills that experience into the complete reference I wish existed when I started. Every feature includes actual syntax, real configuration examples, and the edge cases that trip up experienced users.

Stability note: Features marked [EXPERIMENTAL] are subject to change between releases. Codex Cloud, MCP command group, code mode, and hooks engine are experimental as of v0.117.0. Core CLI, sandbox, AGENTS.md, config.toml, Skills, and the plugin system are stable.

Key Takeaways

• Four surfaces, one brain: CLI, desktop app, IDE extension, and cloud tasks all share the same GPT-5.x-Codex intelligence, so pick the surface that fits your workflow.
• OS-level sandboxing: Codex enforces filesystem and network restrictions at the kernel level (Seatbelt on macOS, Landlock + seccomp on Linux), not inside containers.
• AGENTS.md is cross-tool: Your project instructions work in Codex, Cursor, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed, and 60,000+ open source projects. Write once, use everywhere.
• Profiles save context-switching overhead: Define named config presets (fast, careful, auto) and switch between them with --profile.
• Context management matters: GPT-5.4 offers 1M context; GPT-5.3-Codex provides 272K input. Either way, use /compact, focused prompts, and @file references to manage token budgets proactively.

How to Use This Guide

This is a 2,500+ line reference — start where your experience level fits:

The Quick Reference Card at the end provides a scannable summary of all major commands.

How Codex Works: The Mental Model

Before diving into features, understand how Codex’s architecture shapes everything you do with it. The system operates across four surfaces backed by a shared intelligence layer:

┌─────────────────────────────────────────────────────────┐
│                    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          │
└─────────────────────────────────────────────────────────┘

Core Layer: The GPT-5.x-Codex model family powers everything. As of v0.111.0, gpt-5.4 is the recommended model — OpenAI’s flagship frontier model combining GPT-5.3-Codex coding capabilities with stronger reasoning, native computer use, and 1M context windows.⁶⁶ It reads files, writes patches, executes shell commands, and reasons about your codebase. When context fills, Codex compacts the conversation to free space. This layer costs tokens.

Security Layer: Every command Codex runs passes through an OS-level sandbox. On macOS, Apple’s Seatbelt framework enforces kernel-level restrictions. On Linux, Landlock + seccomp filter filesystem and syscall access. The sandbox operates at the kernel level, not inside containers. The approval policy then decides when to ask for human confirmation.

Extension Layer: MCP connects external services (GitHub, Figma, Sentry). Skills package reusable workflows that Codex loads on demand. Apps connect to ChatGPT connectors. Web search adds real-time context from the internet.

Surface Layer: CLI for terminal power users and automation. Desktop app for multi-threaded project management. IDE extension for edit-compile-test loops. Cloud for async tasks that run independently.

The key insight: Most users only use one surface. Power users use all four: Cloud for long-running tasks, CLI for deterministic repo operations, IDE extension for tight coding loops, and the desktop app for planning and coordination.

Table of Contents

1. How Do I Install Codex?
2. Quick Start: Your First Session
3. Core Interaction Surfaces
4. Configuration System Deep Dive
5. Which Model Should I Choose?
6. What Does Codex Cost?
7. Decision Frameworks
8. How Does the Sandbox & Approval System Work?
9. How Does AGENTS.md Work?
10. Hooks
11. What Is MCP (Model Context Protocol)?
12. Code Mode
13. JavaScript REPL Runtime
14. What Are Skills?
15. Plugins
16. Plan Mode & Collaboration
17. Memory System
18. Session Management
19. Non-Interactive Mode (codex exec)
20. Codex Cloud & Background Tasks
21. The Codex Desktop App
22. GitHub Action & CI/CD
23. Codex SDK
24. Performance Optimization
25. How Do I Debug Issues?
26. Enterprise Deployment
27. Best Practices & Anti-Patterns
28. Workflow Recipes
29. Migration Guide
30. Quick Reference Card
31. Changelog
32. References

How Do I Install Codex?

Package Managers

# 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

Direct Install Script (v0.106.0+)

For macOS and Linux, a one-line install script is available as a GitHub release asset:⁶²

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

The script auto-detects your platform and architecture, downloads the correct binary, and places it on your PATH.

Binary Downloads

For environments without npm or Homebrew, download platform-specific binaries from GitHub Releases¹:

System Requirements

• macOS: Apple Silicon or Intel (full sandbox support via Seatbelt)
• Linux: x86_64 or arm64 (sandbox via Landlock + seccomp)
• Windows: Native sandbox with restricted tokens (promoted from experimental in v0.100.0). WSL also supported²

Authentication

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

Two authentication paths:

1. ChatGPT Account (recommended): Sign in with your existing Plus, Pro, Team, Business, Edu, or Enterprise subscription. Full feature access including cloud tasks.
2. API Key: Set via CODEX_API_KEY environment variable or codex login --with-api-key. Some features (cloud threads) may be unavailable.

Expert tip: Credential storage is configurable via cli_auth_credentials_store in config.toml. Options: file (default), keyring (OS keychain), or auto (keyring if available, file fallback).

Shell Completions

# 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

Verify Installation

codex --version
# Codex CLI v0.104.0

Quick Start: Your First Session

Get from zero to productive in 5 minutes.

1. Install and authenticate:

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

2. Navigate to a project:

cd ~/my-project                  # Any git repo works

3. Start Codex:

codex

You’ll see the interactive TUI. Codex reads your project structure automatically.

4. Ask a question:

> What does this project do? Summarize the architecture.

Codex reads key files and explains the codebase. No changes are made in the default suggest mode.

5. Make a change:

> Add input validation to the login endpoint

Codex proposes edits as a diff. Review and approve with y, or reject with n.

6. Use a slash command:

> /plan Refactor the database layer to use connection pooling

Codex creates a plan without executing. Review the plan, then approve to begin execution.

7. Check your work:

> /diff

See all changes Codex has made in the current session.

What’s next: - Set up AGENTS.md with project instructions (see How Does AGENTS.md Work?) - Configure a profile for your workflow (see Profiles) - Try codex exec for non-interactive automation (see Non-Interactive Mode)

Core Interaction Surfaces

Codex provides four distinct interfaces backed by the same intelligence. Each surface optimizes for a different workflow pattern.

1. Interactive CLI (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

The terminal UI is a full-screen application with:

• Composer: Type prompts, attach files with @, run shell commands with ! prefix
• Output pane: Streaming model responses, tool calls, and command output
• Status bar: Model, token usage, git branch, sandbox mode

Key TUI shortcuts:

Slash commands available in the TUI:

2. Codex Desktop App (macOS + Windows)

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

The desktop app adds capabilities the CLI doesn’t have:

• Multi-tasking: Run multiple parallel agents across different projects simultaneously
• Git worktree isolation: Each thread works on an isolated copy of your repo
• Inline diff review: Stage, revert, and commit changes without leaving the app
• Integrated terminal: Per-thread terminal for running commands
• Conversation forking: Branch conversations to explore alternatives
• Floating pop-out windows: Detach conversations into portable windows
• Automations: Schedule recurring tasks (issue triage, CI monitoring, alert response)

When to use the app vs CLI: Use the desktop app when you’re coordinating multiple workstreams or need visual diff review. Use the CLI when you want terminal composability, scripting, or CI/CD integration.

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

The Codex IDE extension integrates directly into your editor:

• Agent mode by default: Reads files, makes edits, runs commands
• Inline edits: Context-aware suggestions in your active files
• Shared sessions: Sessions sync between CLI and IDE extension
• Same authentication: Sign in with ChatGPT account or API key

Install from the VS Code Marketplace or Cursor/Windsurf extension stores.³

4. Codex Cloud [EXPERIMENTAL]

Cloud tasks run asynchronously in OpenAI-managed environments:

• Fire and forget: Queue tasks that run independently of your local machine
• Parallel execution: Run multiple cloud tasks simultaneously
• PR creation: Codex creates pull requests from completed work
• Local apply: Pull cloud results into your local repo with codex apply <TASK_ID>

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

Cloud tasks are also accessible from chatgpt.com/codex.⁴

Exploration approfondie du 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. Substitutions de session (la plus haute) : flags CLI (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) et substitutions -c key=value
2. Configuration projet (.codex/config.toml, découverte depuis le répertoire courant en remontant vers 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 des configurations. Voir Déploiement en entreprise.

Emplacements des fichiers de configuration

Conseil 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.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"

Activer un profil :

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

Conseil d’expert : Définissez un profil par défaut avec profile = "fast" au niveau racine de votre configuration. Substituez-le par session avec --profile.

Fournisseurs de modèles personnalisés

Connexion à 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, avec une annonce de suppression par OpenAI 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".

Utiliser des modèles locaux avec le flag --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éfinir dans la configuration :

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

Substitutions de configuration en ligne

Remplacer 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 (mars 2026)

GPT-5.4 est disponible sur toutes les surfaces Codex (CLI, application, 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.⁷³

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 (near-instant, Pro only)
   │  └─ No
   │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │  └─ No → gpt-5.4 (recommended: coding + reasoning + computer use, 1M context)
   └─ Still unsure? → gpt-5.4

Effort de raisonnement

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

Les niveaux pris en charge dépendent du modèle. minimal est uniquement disponible pour les modèles GPT-5. Tous les modèles ne prennent pas en charge chaque niveau.

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

Conseil d’expert : le raisonnement xhigh peut consommer 3 à 5 fois plus de tokens que medium pour la même requête. Réservez-le aux problèmes réellement difficiles où la réflexion supplémentaire en vaut la peine.

Changement de modèle

Changez de modèle en cours de session avec la slash command /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 ?

Consultez également 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 2x 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 l’allocation de votre abonnement :

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

Facturation API

Lorsque vous utilisez Codex via API, OpenAI facture l’utilisation par token selon la tarification standard de API d’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 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 courantes
2. Réservez le raisonnement élevé : n’utilisez xhigh que pour les problèmes réellement difficiles, car il 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. Traitez par lots avec le mode exec : codex exec évite la surcharge du TUI pour les workflows 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 API représentatifs 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 à un tarif réduit.

Surcharge cachée en tokens

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

Conseil d’expert : 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 en équipe

Stratégies pour le contrôle des coûts en é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 Enterprise 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

Mode Steer : Enter vs Tab

Règle générale : Enter = « arrête, écoute ça maintenant. » Tab = « quand tu auras fini, 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 choisir ?

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.⁵ Consultez également Enterprise Deployment 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 via des mécanismes natifs du système d’exploitation :

Application spécifique par plateforme :

• macOS : 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⁶
• 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 build Linux (promu d’optionnel dans la v0.100.0)⁷. La v0.117.0 a amélioré la fiabilité du sandbox sur les distributions plus anciennes avec des configurations de noyau legacy.⁷⁷
• Windows : sandbox natif avec des jetons restreints (promu d’expérimental 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 du sandbox à jetons restreints pour une meilleure isolation des processus.⁷⁷

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 shell via le forking 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’environ 1 million de caractères en entrée pour éviter les blocages causés par des charges utiles excessivement volumineuses.⁶² - Système de fichiers /dev 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 fait une pause 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. Les approbations sont ainsi 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 des appels d’outils individuels avec un retour d’information afin que Codex puisse ajuster son approche au lieu de simplement retenter la même commande

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

Codex intègre désormais un outil 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’obliger l’utilisateur à redémarrer avec des options différentes.

Langage de configuration des profils de permissions (v0.113.0+)

Un nouveau langage de configuration pour les profils de permissions sépare les politiques de sandbox du système de fichiers et du réseau en sections distinctes et composables :⁷¹

[permission_profile.filesystem]
read = ["~/Projects", "/usr/local"]
write = ["~/Projects/my-app"]

[permission_profile.network]
allow = ["api.github.com", "registry.npmjs.org"]
deny = ["*"]   # Global wildcard domains now rejected (hardened in v0.113.0)

Cela remplace le mode sandbox monolithique par des politiques granulaires par ressource. Les profils de permissions exécutables s’intègrent également à la politique de sandbox par tour pour l’exécution de skills (v0.112.0).⁷⁰

Le flag --full-auto

--full-auto est un alias pratique pour :

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

Point critique : --full-auto écrase 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 « 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 diriger les demandes de révision vers un sous-agent guardian au lieu d’exiger une approbation humaine pour chaque action. La session du guardian persiste entre les approbations pour réutiliser le cache de prompt et éviter le surcoût de démarrage. Chaque révision dispose d’un historique vierge (les décisions antérieures ne se propagent pas aux révisions suivantes).⁷⁵

Configurez le réviseur dans config.toml :

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

C’est particulièrement utile pour les workflows CI/CD où vous souhaitez une révision automatisée avec raisonnement plutôt qu’un simple 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

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 la prise en charge existante 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, 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 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 le comportement de Codex au sein d’un dépôt ou répertoire spécifique. Consultez Skills pour les paquets 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 de repli
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 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 bon AGENTS.md

D’après les recommandations directes de Codex et les pratiques de la communauté¹¹ :

À FAIRE : - Soyez précis : "Use rg --files for discovery" est plus efficace que "search efficiently" - Définissez la complétion : 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, release, incident/débogage - Définissez l’escalade : que faire en cas de blocage ou d’état inattendu

À ÉVITER : - 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 (rapidité + vérification exhaustive + pas de budget d’exécution) - Rédiger de la documentation en prose (AGENTS.md est une politique opérationnelle, pas un README)

Exemple : AGENTS.md en 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.

Le mécanisme de remplacement

AGENTS.override.md à n’importe quel niveau de répertoire 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 revues par l’astreinte »
• Durcissement temporaire : « Aucune mise à 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 squelette

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 la v0.99.0 (AfterAgent) et la v0.100.0 (AfterToolUse), puis a ajouté un moteur de hooks expérimental dans la v0.114.0 avec les événements SessionStart et Stop.⁷² Le système couvre désormais le cycle de vie des sessions et l’automatisation au niveau des outils, comblant l’écart avec le modèle de hooks de Claude Code.

Événements de hooks 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 en fait l’outil idéal pour injecter des informations dynamiques (dates, noms de branches, variables d’environnement) au démarrage de la session.

Reproduire les patterns de hooks de Claude Code

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

Astuce avancée : le moteur de hooks est expérimental et en expansion active. Consultez le changelog de Codex pour découvrir les nouveaux événements de hooks dans chaque version.

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 versions. 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 de 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 comme 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() : Poursuivre 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

Cas d’usage pratiques

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

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

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

Cas 2a : Sortie multimodale des outils (v0.107.0) — Les outils personnalisés peuvent désormais renvoyer du contenu multimodal (images, contenu enrichi) en plus du texte. Cela permet aux outils produisant des artefacts visuels — captures d’écran, diagrammes, rendus de graphiques — de les transmettre directement au modèle pour analyse.⁶⁴

Cas 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 Enterprise Deployment pour la configuration complète des politiques.

Code Mode [EXPERIMENTAL]

Le mode Code (v0.114.0) offre des flux de travail de développement plus isolés en restreignant 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 plus larges avec le système.

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

Runtime REPL JavaScript [EXPERIMENTAL]

Codex v0.100.0 a introduit un runtime REPL JavaScript expérimental (js_repl) qui conserve l’état entre les appels d’outils. Dans la v0.106.0, le REPL a été promu vers la commande /experimental avec des vérifications de compatibilité au démarrage — il nécessite Node.js 22.22.0 ou ulté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 conserver 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+ (des vérifications au démarrage confirment la compatibilité). La v0.105.0 a amélioré le signalement des erreurs et la récupération en cas de défaillance du REPL.⁶³

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

Que sont les skills ?

Les skills sont des paquets de capacités réutilisables et spécialisés que Codex charge à la demande. Ils suivent le standard ouvert des skills d’agents.¹⁴

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. Recherchez les secrets codés en dur avec `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Vérifiez les injections SQL : recherchez l'interpolation de chaînes dans les requêtes
3. Validez la validation des entrées sur tous les endpoints API
4. Vérifiez les vulnérabilités des dépendances : `pip audit` ou `npm audit`
5. Examinez les schémas d'authentification et d'autorisation
6. Documentez les résultats avec des niveaux de sévérité (Critique/Élevé/Moyen/Faible)

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"

Invocation 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 construire un nouveau skill de manière interactive
• Installateur : utilisez $skill-installer install <name> pour installer des skills communautaires

Activation/Désactivation

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

Skills vs slash commands

Débogage des skills

Si un skill ne s’active pas :

1. Vérifiez la découverte : /skills devrait le lister dans le 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 se chargent pas
4. Vérifiez 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. 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-fichiers complet montrant les références et 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`.

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

Plugins

Les plugins unifient skills, entrées MCP et connecteurs d’applications en un seul package installable (v0.110.0+).⁶⁷ Depuis la v0.117.0, les plugins sont des composants de premier plan : les plugins à portée produit se synchronisent automatiquement au démarrage, /plugins offre un navigateur intégré au TUI pour la découverte et la gestion, et les opérations d’installation/suppression fonctionnent depuis le CLI comme depuis le TUI.⁷⁷

Sources de plugins

Découverte des plugins

Codex informe le modèle des plugins activés au début de la session (v0.111.0), améliorant la découverte des MCPs, applications et skills installés.⁶⁷ Le modèle peut suggérer des plugins pertinents pendant une session en fonction du contexte de la tâche. Depuis la v0.117.0, les plugins à portée produit sont synchronisés au démarrage, garantissant la disponibilité du catalogue de plugins le plus récent sans intervention manuelle.⁷⁷

Mentions @plugin (v0.112.0+)

Référencez n’importe quel plugin installé directement dans le chat avec @plugin-name.⁷⁰ Lorsque vous mentionnez un plugin, son contexte (capacités, outils, 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’applications.

Marketplace de plugins (v0.113.0+)

Le marketplace de plugins inclut désormais une découverte enrichie avec métadonnées, catégories et évaluations.⁷¹ Les vérifications d’authentification à l’installation confirment 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.

Gestion des plugins

codex plugin list              # Show installed plugins
codex plugin install <name>    # Install from marketplace
codex plugin uninstall <name>  # Remove plugin and config (v0.113.0+)

Dans le TUI, utilisez /plugins (v0.117.0+) pour parcourir, installer et supprimer des plugins de manière interactive 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 mise en place de connecteurs d’applications. Un seul plugin peut regrouper les trois — accélérant l’intégration de l’équipe et rendant la configuration plus portable.

Mode Plan et collaboration

Le mode Plan permet à Codex de concevoir une approche avant d’exécuter les modifications. Il est activé par défaut (depuis la v0.94.0).¹⁵ Consultez Cadres décisionnels pour l’arbre de décision « Mode Plan vs exécution directe ».

Accéder au 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 le codebase - Propose un plan d’implémentation - N’effectue aucune modification tant que vous n’approuvez pas - 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 affiche désormais la coloration syntaxique des blocs de code 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 d’accès au microphone.⁶³ Depuis la v0.107.0, les sessions vocales en temps réel prennent en charge la sélection des 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 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 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 persistant (v0.100.0+) qui stocke des faits, des préférences et du contexte 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émarrage de la session et s’en sert pour ajuster son comportement dans toutes les sessions ultérieures.

Que stocker

Les mémoires fonctionnent au 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 se trouve dans src/core/auth/, pas dans src/middleware/ »
• Préférences de workflow : « Toujours exécuter 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. Les pipelines CI/CD et les scripts bénéficient ainsi 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)

• Nettoyage des secrets : les mémoires sont automatiquement analysées pour détecter les secrets avant d’être écrites sur disque
• Prise en compte du répertoire courant : 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é en se concentrant sur les interactions utilisateur
• Oubli basé sur les diffs (v0.106.0) : la mémoire utilise désormais un mécanisme d’oubli basé sur les diffs pour supprimer les faits obsolètes, maintenant le stockage mémoire léger et pertinent dans le temps⁶²
• Sélection contextuelle selon l’usage (v0.106.0) : la récupération des mémoires tient désormais compte de l’usage, en priorisant les souvenirs fréquemment consultés et récemment pertinents⁶²
• 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 à zéro — utile lors d’un changement de contexte entre projets non liés ou lorsque l’état de la mémoire a dérivé⁶⁴

Mémoire vs AGENTS.md

Conseil : utilisez /m_update pour les faits qui doivent persister indéfiniment. Pour du contexte spécifique à une session, dites-le simplement à Codex dans la conversation. Pour un contexte partagé en équipe, utilisez AGENTS.md.

Gestion des sessions

Codex persiste les sessions sous ~/.codex/sessions/, permettant la reprise, le fork et les workflows multi-threads entre CLI et l’application de bureau.

Reprise

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 /resume dans le TUI ouvre le même sélecteur interactif avec recherche.

Fork

Bifurquez 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 bifurcation. Les modifications dans un fork n’affectent pas l’autre. C’est utile pour comparer des approches (par exemple, « fork et essayer Redis au lieu de Memcached ») ou explorer des changements risqués en toute sécurité.

Fork 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 lancer 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 bifurquer 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 les chemins (ex. : /root/agent_a) avec une messagerie inter-agents structurée, rendant la coordination multi-agents plus explicite et plus facile à déboguer.⁷⁷

Liste des threads

Affichez 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 un aperçu des diffs.

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

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é peuvent évoluer. OpenAI gère les environnements cloud ; 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 & 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 : il 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é : aucun accès internet pour l’agent (par défaut)
• Activé : liste blanche de domaines optionnelle + restrictions sur les méthodes HTTP

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

Les scripts d’installation peuvent toujours accéder à 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 abonnement 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é.

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

L'application Codex Desktop App (macOS et Windows) offre une interface graphique optimisée pour la gestion multi-projets.[^17] La version Windows a été lancée le 4 mars 2026 avec la prise en charge native de PowerShell et un sandbox Windows natif.[^68]

### Installation

```bash
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 principales

Modes de thread

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

Mécanismes 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 à fusionner

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

Automatisations

Les automatisations s’exécutent localement dans l’application ; celle-ci doit donc ê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édiés en arrière-plan (isolés de votre répertoire de travail)
• Dans les projets non-Git, l’exécution se fait directement dans le répertoire du projet
• Les automatisations utilisent vos paramètres de sandbox par défaut

Configuration d’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 le planning et mettent les résultats en file d’attente pour revue

Exemples de cas d’usage : - Triage des issues : catégorisation et priorisation automatiques des nouvelles issues - Surveillance CI : détection des échecs de build et suggestions de correctifs - Réponse aux alertes : réaction aux alertes de monitoring avec analyse diagnostique - Mises à jour des dépendances : vérification et application des correctifs de sécurité

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

Prise en charge Windows

L’application Codex Desktop App 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 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 : impose une sortie finale au format JSON
• Entrée multimodale : transmettez du texte et des images locales ({ type: "local_image", path: "..." })
• Workflows d’images (v0.117.0) : view_image renvoie des URL, les images générées peuvent être rouvertes, et l’historique des images persiste après la reprise de session⁷⁷

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 sont conservées sous ~/.codex/sessions.

Environnement d’exécution : 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, budget total de 400K), 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 conversation pour libérer des tokens
2. Fournissez de la documentation locale : des fichiers AGENTS.md et une documentation locale de qualité réduisent le surcoût d’exploration (qui consomme du contexte)
3. Utilisez @ pour joindre des fichiers spécifiques : référencez les fichiers directement au lieu de demander à Codex de les chercher
4. Gardez vos prompts ciblés : des prompts précis avec les 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 travail interactif en binôme
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 vos prompts pour en tirer parti
4. Boucles orientées résultat : demandez « implémente, teste, corrige, arrête quand c’est vert » plutôt que des 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 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)

Vous pouvez également créer 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 constitue une couche de contraintes strictes qui restreint les valeurs sélectionnables par les utilisateurs, lesquels ne peuvent pas l’outrepasser. Les règles 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 profils 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 non définis, de sorte que les couches gérées de priorité supérieure l’emportent toujours. Les exigences cloud fonctionnent au mieux ; en cas d’échec ou d’expiration de la récupération, 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 prises en charge (endpoint, nom de service, attributs de ressource)
• Le contexte de trace se propage à travers Codex vers les 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. Prise en charge du SSO via SAML/OIDC à travers votre fournisseur d’identité (Okta, Entra ID, etc.)
• API : authentification API standard, facturation et contrôles 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égrez dans vos 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

Traitement 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 (Semaines 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 patterns AGENTS.md et les besoins en serveurs MCP.
2. Extension à l’équipe (Semaines 3-4) : déployez à l’ensemble de l’équipe. Distribuez le config.toml standard de l’équipe via MDM ou le dépôt. Activez le sandbox workspace-write pour les dépôts de confiance.
3. Intégration CI (Semaines 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 maîtriser les coûts.
4. Déploiement organisationnel (Mois 2+) : déployez via MDM avec requirements.toml imposant les serveurs MCP approuvés, les politiques sandbox et les listes de modèles autorisés.

Patterns d’audit

Suivez l’utilisation de Codex et assurez 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 journalise les tentatives de serveurs bloqués — examinez pour détecter les usages d’outils non autorisés
• Piste d’audit Git : toutes les modifications de fichiers par Codex passent par git standard — examinez via l’historique des branches et les diffs de PR

Bonnes pratiques et anti-patterns

Techniques de prompting

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 résultats. »
4. Références de fichiers : utilisez @filename pour joindre des fichiers spécifiques au contexte
5. Boucles orientées résultat : « Implémentez, exécutez les tests, corrigez les échecs, arrêtez uniquement quand tous les tests passent. » Codex itère jusqu’à la fin

Philosophie de test

La communauté converge vers une collaboration IA guidé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 → refactoriser)
• Adoptez les patterns de programmation Tiger Style
• Fournissez le texte exact du fichier lorsque vous demandez des correctifs. 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 tables des matières et 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 repoussées hors du contexte

Workflow Git

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

Skills et prompts de la communauté

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 de mauvais résultats ou créent des workflows frustrants.

Anti-patterns de coût

Anti-patterns de contexte

Anti-patterns de workflow

Anti-patterns de prompting

Recettes de workflow

Patterns 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

Vérifiez le 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 de 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 [EXPÉRIMENTAL]

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

Différences clés à comprendre :

• Le sandbox opère au niveau OS : Codex utilise Seatbelt/Landlock, pas des conteneurs. Les restrictions opèrent au niveau du noyau, en dessous de la couche applicative.
• Les hooks sont en expansion : 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 des sessions, 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 encore une couverture plus large. Pour les schémas d’automatisation non encore couverts, utilisez les instructions AGENTS.md ou les skills.
• Sub-agents v2 (v0.117.0) : Les sub-agents utilisent désormais des adresses basées sur des chemins (par ex. /root/agent_a) avec une messagerie inter-agents structurée et un listing des agents.⁷⁷ Cela étend le mécanisme existant (max 6 en simultané, réduit de 12 en v0.91.0). Les rôles multi-agents restent personnalisables via la configuration (v0.104.0+).⁴⁹ La v0.105.0 a ajouté spawn_agents_on_csv pour un déploiement en éventail sur les lignes avec suivi de la progression et estimation du temps restant.⁶³ Codex ne dispose toujours pas de l’interface 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 schémas de délégation.
• AGENTS.md est multi-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 la commutation manuelle : Au lieu de changer les flags à chaque exécution, définissez des profils dans config.toml.

Depuis GitHub Copilot

Ce que vous gagnez : - Sandboxing au niveau OS (Seatbelt/Landlock — appliqué par le noyau vs basé sur des conteneurs) - Délégation de tâches cloud avec codex apply - Profils de configuration pour changer 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       ║
║  /fast         Toggle fast mode (default: on)                ║
║  /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               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin list              List installed plugins        ║
║  codex plugin install <name>    Install from marketplace      ║
║                                                               ║
║  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 (March 2026, v0.116.0)                                ║
║  gpt-5.4               Recommended flagship (1M context)     ║
║  gpt-5.3-codex         Coding specialist (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

Remarque sur les URL du blog OpenAI : les références ¹⁷, ²⁶–³¹, ³⁴, ⁶⁶, ⁶⁸ et ⁶⁹ renvoient vers des articles du blog openai.com/index/ qui retournent HTTP 403 aux accès automatisés en raison de la protection anti-bots Cloudflare. Ces URL sont valides lorsqu’elles sont consultées via un navigateur web standard.