Configuration avancée

Utilisez ces options lorsque vous avez besoin de davantage de contrôle sur les fournisseurs, les politiques et les intégrations. Pour démarrer rapidement, consultez Principes de configuration.

Pour en savoir plus sur les consignes de projet, les capacités réutilisables, les commandes slash personnalisées, les workflows de sous-agents et les intégrations, consultez Personnalisation. Pour les clés de configuration, consultez Référence de configuration.

Profils

Les profils permettent d’enregistrer des couches de configuration nommées et de passer de l’une à l’autre depuis la CLI. Lorsque vous utilisez --profile profile-name, Codex charge ~/.codex/config.toml, puis lui superpose ~/.codex/profile-name.config.toml. Les noms de profils peuvent contenir des lettres, des chiffres, des traits d’union et des traits de soulignement.

Créez un fichier TOML distinct pour chaque profil. Utilisez des clés de configuration de premier niveau dans le fichier de profil ; ne les imbriquez pas sous [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Le fichier de profil a priorité sur votre configuration utilisateur de base, mais reste subordonné aux configurations du projet et de la CLI. Il suffit donc d’y inclure les valeurs qui diffèrent de votre configuration de base. Les fichiers de profil peuvent également redéfinir model_catalog_json ; Codex utilise la valeur du profil lorsque ce paramètre est défini dans les deux fichiers.

Dans Codex 0.134.0 et les versions ultérieures, --profile ne lit plus [profiles.profile-name] dans config.toml, et le sélecteur de premier niveau profile = "profile-name" n’est plus pris en charge. Déplacez les anciens paramètres de profil vers ~/.codex/profile-name.config.toml, puis supprimez la table correspondante [profiles.profile-name] et le sélecteur profile = "profile-name" de config.toml.

Redéfinitions ponctuelles depuis la CLI

En plus de modifier ~/.codex/config.toml, vous pouvez redéfinir la configuration pour une seule exécution depuis la CLI :

• Privilégiez les options dédiées lorsqu’elles existent (par exemple, --model).
• Utilisez -c / --config pour redéfinir la valeur de n’importe quelle clé.

Exemples :

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Remarques :

• Les clés peuvent utiliser la notation pointée pour définir des valeurs imbriquées (par exemple, mcp_servers.context7.enabled=false).
• Les valeurs de --config sont analysées au format TOML. En cas de doute, placez la valeur entre guillemets pour éviter que votre shell ne la découpe au niveau des espaces.
• Si la valeur ne peut pas être analysée au format TOML, Codex la traite comme une chaîne de caractères.

Emplacements de la configuration et des données d’état

Codex stocke son état local dans CODEX_HOME (~/.codex par défaut).

Fichiers courants que vous pouvez y trouver :

• config.toml (votre configuration locale)
• auth.json (si vous stockez les identifiants dans un fichier) ou le trousseau de clés de votre système d’exploitation
• history.jsonl (si la persistance de l’historique est activée)
• Autres données d’état propres à l’utilisateur, comme les journaux et les caches

Pour en savoir plus sur l’authentification (y compris les modes de stockage des identifiants), consultez Authentification. Pour la liste complète des clés de configuration, consultez Référence de configuration.

Pour les valeurs par défaut partagées, les règles et les skills enregistrés dans des dépôts ou des chemins système, consultez Configuration d’équipe.

Si vous souhaitez simplement faire pointer le fournisseur OpenAI intégré vers un proxy LLM, un routeur ou un projet où la résidence des données est activée, définissez openai_base_url dans config.toml au lieu de définir un nouveau fournisseur. Cela modifie l’URL de base du fournisseur openai intégré sans nécessiter d’entrée model_providers.<id> distincte.

openai_base_url = "https://us.api.openai.com/v1"

Fichiers de configuration du projet (.codex/config.toml)

En plus de votre configuration utilisateur, Codex lit les paramètres redéfinis pour le projet dans les fichiers .codex/config.toml de votre dépôt. Codex parcourt l’arborescence depuis la racine du projet jusqu’à votre répertoire de travail actuel et charge chaque fichier .codex/config.toml trouvé. Si plusieurs fichiers définissent la même clé, celui qui se trouve le plus près de votre répertoire de travail l’emporte.

Par sécurité, Codex ne charge les fichiers de configuration propres au projet que lorsque celui-ci est considéré comme fiable. Si le projet n’est pas considéré comme fiable, Codex ignore ses couches .codex/, notamment .codex/config.toml, les hooks propres au projet et les règles propres au projet. Les couches utilisateur et système restent distinctes et sont tout de même chargées.

Les chemins relatifs dans une configuration de projet (par exemple, model_instructions_file) sont résolus par rapport au dossier .codex/ qui contient le fichier config.toml.

Les fichiers de configuration du projet ne peuvent pas redéfinir les paramètres qui redirigent les identifiants, modifient les métadonnées contrôlées par l’hôte dans les requêtes de l’application, changent l’authentification du fournisseur, sélectionnent des profils de configuration ou exécutent des commandes de notification ou de télémétrie locales à la machine. Codex ignore les clés suivantes dans le fichier .codex/config.toml propre au projet et affiche un avertissement au démarrage lorsqu’il les rencontre : openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url et otel. Définissez les clés de fournisseur, de notification et de télémétrie dans votre fichier utilisateur ~/.codex/config.toml ; sélectionnez les profils de configuration avec --profile profile-name et ~/.codex/profile-name.config.toml.

Hooks

Codex peut également charger des hooks de cycle de vie depuis des fichiers hooks.json ou des tables [hooks] intégrées à des fichiers config.toml situés à côté des couches de configuration actives.

En pratique, les quatre emplacements les plus utiles sont :

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Les hooks propres au projet ne sont chargés que si la couche .codex/ du projet est considérée comme fiable. Les hooks de niveau utilisateur ne dépendent pas de la confiance accordée au projet.

Les hooks intégrés au format TOML utilisent la même structure d’événements que hooks.json :

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Si une même couche contient à la fois hooks.json et une table [hooks] intégrée, Codex charge les deux et affiche un avertissement. Privilégiez une seule représentation par couche.

Pour connaître la liste actuelle des événements, les champs d’entrée, le comportement des sorties et les limitations, consultez Hooks.

Rôles des agents ([agents] dans config.toml)

Pour configurer les rôles des sous-agents ([agents] dans config.toml), consultez Sous-agents.

Détection de la racine du projet

Codex détecte la configuration du projet (par exemple, les couches .codex/ et AGENTS.md) en remontant l’arborescence depuis le répertoire de travail jusqu’à atteindre la racine d’un projet.

Par défaut, Codex considère qu’un répertoire contenant .git est la racine du projet. Pour personnaliser ce comportement, définissez project_root_markers dans config.toml :

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

Définissez project_root_markers = [] pour ignorer la recherche dans les répertoires parents et considérer le répertoire de travail actuel comme la racine du projet.

Fournisseurs de modèles personnalisés

Un fournisseur de modèles définit la manière dont Codex se connecte à un modèle (URL de base, API de communication, authentification et en-têtes HTTP facultatifs). Les fournisseurs personnalisés ne peuvent pas réutiliser les identifiants réservés des fournisseurs intégrés : openai, ollama et lmstudio.

Définissez des fournisseurs supplémentaires et faites pointer model_provider vers eux :

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Si un fournisseur personnalisé prend en charge le point de terminaison de recherche web autonome, déclarez cette capacité dans sa configuration :

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

Pour les fournisseurs personnalisés, ce paramètre vaut false par défaut. La recherche web autonome est en cours de développement et désactivée par défaut. Définir la capacité du fournisseur sur true ne l’active pas : le fournisseur doit prendre en charge un point de terminaison compatible, et le modèle ainsi que l’environnement d’exécution sélectionnés doivent prendre en charge la recherche autonome. Le mode web_search configuré et les restrictions de recherche administrées s’appliquent toujours.

Ajoutez des en-têtes de requête si nécessaire :

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Utilisez une authentification par commande lorsqu’un fournisseur exige que Codex récupère des tokens Bearer auprès d’un utilitaire externe de gestion des identifiants :

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

La commande d’authentification ne reçoit aucune donnée via stdin et doit écrire le token sur stdout. Codex supprime les espaces blancs en début et en fin, considère un token vide comme une erreur et le renouvelle de manière proactive à l’intervalle défini par refresh_interval_ms ; définissez refresh_interval_ms = 0 pour ne le renouveler qu’après une nouvelle tentative d’authentification. Ne combinez pas [model_providers.<id>.auth] avec env_key, experimental_bearer_token ou requires_openai_auth.

Fournisseur Amazon Bedrock

Codex inclut un fournisseur de modèles amazon-bedrock intégré. Affectez-le directement à model_provider ; contrairement aux fournisseurs personnalisés, ce fournisseur intégré ne permet de redéfinir que le profil et la région AWS dans ses paramètres imbriqués.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

Si vous omettez profile, Codex utilise la chaîne standard de recherche d’identifiants AWS. Définissez region sur la région Bedrock prise en charge qui doit traiter les requêtes.

Pour connaître la procédure complète de configuration, les options d’authentification, les modèles pris en charge et la disponibilité des fonctionnalités, consultez Utiliser ChatGPT Work et Codex avec Amazon Bedrock.

Mode OSS (fournisseurs locaux)

Codex peut fonctionner avec un fournisseur local « open source » tel qu’Ollama ou LM Studio lorsque vous utilisez --oss. Choisissez-en un pour une seule exécution avec --local-provider, ou définissez oss_provider pour choisir le fournisseur par défaut. Si aucun des deux n’est défini, la CLI interactive vous invite à en choisir un ; codex exec se termine par une erreur.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Fournisseur Azure et réglages propres à chaque fournisseur

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Pour modifier l’URL de base du fournisseur OpenAI intégré, utilisez openai_base_url ; ne créez pas [model_providers.openai], car vous ne pouvez pas redéfinir les identifiants des fournisseurs intégrés.

Organisations API utilisant la résidence des données

Pour les projets créés avec la résidence des données activée, vous pouvez créer un fournisseur de modèles afin de mettre à jour base_url avec le préfixe approprié. Pour les espaces de travail ChatGPT avec résidence des données, aucun fournisseur personnalisé n’est nécessaire ; Codex respecte les paramètres de résidence de l’espace de travail lorsque vous vous connectez avec ChatGPT.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

Raisonnement, niveau de détail et limites du modèle

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity s’applique uniquement aux fournisseurs qui utilisent l’API Responses. Les fournisseurs Chat Completions ignorent ce paramètre.

Politiques d’approbation et modes de bac à sable

Choisissez le niveau d’exigence des approbations (qui détermine quand Codex se met en pause) et le niveau du bac à sable (qui détermine l’accès aux fichiers et au réseau).

Pour connaître les détails de fonctionnement à prendre en compte lors de la modification de config.toml, consultez Combinaisons courantes de bac à sable et d’approbation, Chemins protégés dans les racines accessibles en écriture et Accès réseau.

Codex et ChatGPT Work ne prennent plus en charge approval_policy = "untrusted". Consultez Migrez depuis l’ancienne politique d’approbation untrusted pour connaître les paramètres pris en charge et les approbations plus strictes fondées sur le projet.

Pour découvrir les profils d’autorisations en version bêta qui configurent conjointement l’accès au système de fichiers et au réseau, consultez Autorisations.

Vous pouvez aussi utiliser une politique d’approbation granulaire (approval_policy = { granular = { ... } }) pour autoriser ou rejeter automatiquement chaque catégorie de demandes d’approbation. Cette option est utile si vous souhaitez conserver les approbations interactives habituelles dans certains cas, tout en refusant automatiquement les autres par défaut, comme les demandes request_permissions ou celles liées aux scripts de skills.

Définissez approvals_reviewer = "auto_review" pour soumettre les demandes d’approbation interactives admissibles à la révision automatique. Ce paramètre change l’entité chargée de la révision, sans modifier les limites du bac à sable.

Utilisez [auto_review].policy pour définir localement les instructions de la politique de révision. Le paramètre géré guardian_policy_config est prioritaire.

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

Profils d’autorisations nommés

Pour connaître les profils intégrés, la syntaxe des profils personnalisés et le modèle complet de configuration du système de fichiers et du réseau, consultez Autorisations.

Pour connaître la liste complète des clés et les contraintes imposées par les exigences, consultez Référence de configuration et Configuration gérée.

Désactivez entièrement le bac à sable (uniquement si votre environnement isole déjà les processus) :

sandbox_mode = "danger-full-access"

Politique d’environnement du shell

shell_environment_policy détermine les variables d’environnement que Codex transmet aux commandes lancées. Partez d’un environnement vide avec inherit = "none", ou héritez d’un ensemble réduit de variables avec inherit = "core". Ajoutez des valeurs explicites et des filtres par clé pour éviter de transmettre des secrets inutiles aux commandes lancées.

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

Les motifs de filtrage ne sont pas sensibles à la casse et prennent en charge * et ?. Utilisez "exclude" pour supprimer les variables correspondantes. Dès qu’un motif utilise "include", Codex conserve uniquement les variables correspondant à un motif d’inclusion. Les inclusions ne rétablissent pas les variables déjà exclues. Les clés de filtre sont fusionnées sans distinction de casse entre les différentes couches de configuration.

ignore_default_excludes vaut true par défaut : Codex ne supprime donc pas automatiquement les variables dont le nom contient KEY, SECRET ou TOKEN. Définissez ce paramètre sur false pour appliquer ces exclusions automatiques avant l’exécution de vos filtres explicites.

Codex applique d’abord les exclusions automatiques, puis les exclusions personnalisées, les valeurs de set et enfin la liste d’autorisation définie par les motifs d’inclusion. Comme set s’applique après les exclusions, il peut rétablir une variable exclue. Une liste d’autorisation définie par des motifs d’inclusion peut toutefois supprimer cette valeur rétablie.

Les anciens tableaux exclude et include_only restent pris en charge pour les configurations existantes. Ne combinez aucun de ces tableaux avec [shell_environment_policy.filters] dans une même couche de configuration : Codex rejette cette combinaison.

Serveurs MCP

Consultez la documentation MCP dédiée pour connaître les détails de configuration.

Observabilité et télémétrie

Activez l’exportation des journaux OpenTelemetry (OTel) pour suivre les exécutions de Codex (requêtes API, SSE/événements, prompts, approbations et résultats des outils). Cette fonctionnalité est désactivée par défaut ; activez-la via [otel] :

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

Choisissez un exportateur :

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Avec exporter = "none", Codex enregistre les événements sans rien envoyer. Les exportateurs regroupent les événements en lots de manière asynchrone et envoient les données restantes à l’arrêt. Les métadonnées des événements comprennent le nom du service, la version de la CLI, le tag d’environnement, l’identifiant de conversation, le modèle, les paramètres du bac à sable et d’approbation, ainsi que les champs propres à chaque événement (voir Référence de configuration).

Données émises

Codex émet des événements de journal structurés pour les exécutions et l’utilisation des outils. Voici quelques types d’événements représentatifs :

• codex.conversation_starts (modèle, paramètres de raisonnement, politique de bac à sable et d’approbation)
• codex.api_request (tentative, statut/succès, durée et détails de l’erreur)
• codex.sse_event (type d’événement du flux, succès/échec, durée, ainsi que le nombre de tokens lors de response.completed)
• codex.websocket_request et codex.websocket_event (durée de la requête, ainsi que le type, le succès et l’erreur pour chaque message)
• codex.user_prompt (longueur ; contenu masqué sauf activation explicite)
• codex.tool_decision (approbation/refus et origine de la décision : configuration ou utilisateur)
• codex.tool_result (durée, succès, extrait de la sortie)

Métriques OTel émises

Lorsque le pipeline de métriques OTel est activé, Codex émet des compteurs et des histogrammes de durée pour l’activité des API, des flux et des outils.

Chaque métrique ci-dessous comprend également les tags de métadonnées par défaut : auth_mode, originator, session_source, model et app.version.

Pour en savoir plus sur la sécurité et la confidentialité de la télémétrie, consultez Sécurité.

Métriques

Par défaut, Codex envoie périodiquement à OpenAI une petite quantité de données anonymes sur son utilisation et son état de fonctionnement. Ces données permettent de détecter les dysfonctionnements de Codex et d’identifier les fonctionnalités et les options de configuration utilisées, afin que l’équipe Codex puisse se concentrer sur l’essentiel. Ces métriques ne contiennent aucune information permettant d’identifier une personne (PII). La collecte des métriques est indépendante de l’exportation des journaux et des traces OTel.

Pour désactiver entièrement la collecte des métriques dans l’application de bureau ChatGPT, Codex CLI et l’extension IDE sur une machine, définissez le paramètre d’analyse dans votre configuration :

[analytics]
enabled = false

Chaque métrique comprend ses propres champs ainsi que les champs de contexte par défaut ci-dessous.

Champs de contexte par défaut (communs à tous les événements et métriques)

• auth_mode : swic | api | unknown.
• model : nom du modèle utilisé.
• app.version : version de Codex.

Catalogue des métriques

Chaque métrique comprend les champs requis ainsi que les champs de contexte par défaut ci-dessus. Le préfixe codex. est omis dans les noms de métriques ci-dessous. La plupart des noms de métriques sont centralisés dans codex-rs/otel/src/metrics/names.rs ; les métriques propres à certaines fonctionnalités et émises en dehors de ce fichier figurent également ici. Si une métrique comprend le champ tool, celui-ci indique l’outil interne utilisé (par exemple, apply_patch ou shell) et ne contient ni la commande shell exécutée ni le patch que codex tente d’appliquer.

Environnement d’exécution et transport des échanges avec le modèle

La métrique cloud_requirements.fetch_attempt inclut les champs trigger, attempt, outcome et status_code. La métrique cloud_requirements.fetch_final inclut les champs trigger, outcome, reason, attempt_count et status_code.

Activité des tours et des outils

Les métriques mcp.call et mcp.call.duration_ms incluent status ; les émissions habituelles liées aux appels d’outils incluent aussi tool, ainsi que connector_id et connector_name lorsqu’ils sont disponibles. Les appels MCP bloqués des applications Codex peuvent émettre mcp.call avec uniquement status.

Fils de discussion, tâches et fonctionnalités

La métrique shell_snapshot inclut success et, en cas d’échec, failure_reason.

Mémoire et état local

Les métriques external_agent_config.detect et external_agent_config.import incluent migration_type ; les migrations de skills incluent également skills_count.

Bac à sable Windows

Les métriques d’échec de la configuration avec élévation de privilèges incluent code et message lorsque les détails de l’échec de la configuration Windows sont disponibles. Elles peuvent aussi inclure originator lorsqu’elles sont émises depuis le chemin de code de configuration partagé. La métrique windows_sandbox.legacy_setup_preflight_failed inclut originator lorsqu’elle est émise depuis ce chemin partagé, mais les échecs de vérification préalable depuis l’invite de secours peuvent ne comporter aucun champ.

Paramètres des retours d’expérience

Par défaut, les clients locaux permettent aux utilisateurs d’envoyer des retours via /feedback. Pour désactiver la collecte des retours dans l’application de bureau ChatGPT, Codex CLI et l’extension IDE sur une machine, modifiez votre configuration :

[feedback]
enabled = false

Lorsque la collecte est désactivée, /feedback affiche un message qui l’indique et Codex refuse l’envoi de retours.

Masquage ou affichage des événements de raisonnement

Pour réduire le bruit généré par les sorties de « raisonnement » (par exemple dans les journaux de CI), vous pouvez les masquer :

hide_agent_reasoning = true

Pour afficher le contenu brut du raisonnement lorsqu’un modèle en émet :

show_raw_agent_reasoning = true

N’activez l’affichage du raisonnement brut que si cela convient à votre workflow. Certains modèles ou fournisseurs (comme gpt-oss) n’émettent pas de raisonnement brut ; dans ce cas, ce paramètre n’a aucun effet visible.

Notifications

Utilisez notify pour lancer un programme externe chaque fois que Codex émet un événement pris en charge (actuellement, uniquement agent-turn-complete). Cette option est pratique pour les notifications de bureau, les webhooks de messagerie, les mises à jour de CI ou toute alerte sur un canal externe que les notifications intégrées à la TUI ne couvrent pas.

notify = ["python3", "/path/to/notify.py"]

Exemple de notify.py (tronqué) qui réagit à agent-turn-complete :

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

Le script reçoit un unique argument JSON. Les champs courants comprennent :

• type (actuellement agent-turn-complete)
• thread-id (identifiant de session)
• turn-id (identifiant du tour)
• cwd (répertoire de travail)
• input-messages (messages de l’utilisateur à l’origine du tour)
• last-assistant-message (texte du dernier message de l’assistant)

Placez le script sur le disque et faites pointer notify vers celui-ci.

Comparaison de notify et tui.notifications

• notify exécute un programme externe (utile pour les webhooks, les outils de notification de bureau et les hooks de CI).
• tui.notifications est intégré à la TUI et permet, si nécessaire, de filtrer par type d’événement (par exemple, agent-turn-complete et approval-requested).
• tui.notification_method détermine la manière dont la TUI émet les notifications du terminal (auto, osc9 ou bel).
• tui.notification_condition détermine si les notifications de la TUI se déclenchent uniquement lorsque le terminal n’a pas le focus (unfocused) ou dans tous les cas (always).

En mode auto, Codex privilégie les notifications OSC 9 (une séquence d’échappement que certains terminaux interprètent comme une notification de bureau) et utilise BEL (\x07) à défaut.

Consultez la Référence de configuration pour connaître les clés exactes.

Persistance de l’historique

Par défaut, Codex enregistre les transcriptions des sessions locales sous CODEX_HOME (par exemple, ~/.codex/history.jsonl). Pour désactiver la persistance de l’historique local :

[history]
persistence = "none"

Pour limiter la taille du fichier d’historique, définissez history.max_bytes. Lorsque le fichier dépasse cette limite, Codex supprime les entrées les plus anciennes et compacte le fichier en conservant les plus récentes.

[history]
max_bytes = 104857600 # 100 MiB

Références cliquables

Si vous utilisez une intégration de terminal ou d’éditeur compatible, Codex peut afficher les références aux fichiers sous forme de liens cliquables. Configurez file_opener pour choisir le schéma d’URI utilisé par Codex :

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

Exemple : une référence comme /home/user/project/main.py:42 peut être transformée en lien cliquable vscode://file/...:42.

Détection des instructions du projet

Codex lit AGENTS.md (et les fichiers associés) et inclut une quantité limitée d’instructions du projet dans le premier tour d’une session. Deux paramètres contrôlent ce comportement :

• project_doc_max_bytes : quantité de contenu à lire dans chaque fichier AGENTS.md
• project_doc_fallback_filenames : noms de fichiers supplémentaires à rechercher lorsque AGENTS.md est absent d’un répertoire

Pour un guide détaillé, consultez Instructions personnalisées avec AGENTS.md.

Application de bureau

Les options de cette section s’appliquent uniquement à l’application de bureau ChatGPT.

Ajout de gestionnaires de fichiers personnalisés

Dans votre fichier de configuration utilisateur ~/.codex/config.toml, ajoutez des entrées sous desktop.custom_file_handlers pour ouvrir des fichiers dans des éditeurs ou des lanceurs internes que l’application de bureau ChatGPT ne prend pas en charge par défaut. Chaque entrée ajoute un éditeur aux menus Ouvrir dans de l’application. L’application affiche cette option lorsque command est un chemin absolu existant ou peut être trouvé via le PATH de l’application.

L’exemple suivant présente trois façons de transmettre un fichier à un gestionnaire :

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

Enregistrez config.toml, puis redémarrez l’application de bureau ChatGPT.

L’identifiant du gestionnaire est le dernier segment de l’en-tête de table TOML. Il doit comporter 1 à 64 caractères, commencer par une lettre ou un chiffre ASCII et ne contenir ensuite que des lettres ou des chiffres ASCII, des points, des traits de soulignement ou des traits d’union. L’application expose l’identifiant avec le préfixe custom: ; par exemple, company_editor devient custom:company_editor. Entourez de guillemets tout identifiant contenant un point pour que TOML ne l’interprète pas comme une table imbriquée. Par exemple :

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

Chaque gestionnaire prend en charge les champs suivants :

La valeur de input détermine ce qui suit args :

• path ajoute le chemin comme dernier argument de la commande.
• json_argument ajoute un objet JSON contenant target, path, appPath et location. La valeur de location est soit un objet dont les valeurs line et column sont indexées à partir de 1, soit null.
• json_stdin écrit l’objet JSON sur l’entrée standard au lieu d’ajouter un argument. Cet objet contient également hostConfig, remoteWorkspaceRoot et remotePath ; ces champs valent null lorsqu’ils ne s’appliquent pas.

Par exemple, company_editor peut recevoir cet argument lorsque l’utilisateur ouvre un emplacement précis dans le code source :

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

Lorsque vous sélectionnez un gestionnaire personnalisé comme éditeur préféré, ce choix est enregistré de la même manière que pour un éditeur intégré, y compris dans les préférences propres à chaque projet.

Options de la TUI

L’exécution de codex sans sous-commande lance l’interface utilisateur interactive du terminal (TUI). Codex propose des paramètres propres à la TUI sous [tui], notamment :

• tui.notifications : activez ou désactivez les notifications (ou limitez-les à certains types)
• tui.notification_method : choisissez auto, osc9 ou bel pour les notifications du terminal
• tui.notification_condition : choisissez unfocused ou always pour déterminer quand les notifications se déclenchent
• tui.animations : activez ou désactivez les animations ASCII et les effets de scintillement
• tui.alternate_screen : contrôlez l’utilisation de l’écran alternatif (définissez la valeur sur never pour conserver l’historique de défilement du terminal)
• tui.show_tooltips : affichez ou masquez les infobulles de prise en main sur l’écran d’accueil

La valeur par défaut de tui.notification_method est auto. En mode auto, Codex privilégie les notifications OSC 9 (une séquence d’échappement du terminal que certains terminaux interprètent comme une notification de bureau) lorsque le terminal semble les prendre en charge, et utilise BEL (\x07) dans le cas contraire.

Consultez la Référence de configuration pour obtenir la liste complète des clés.