Configuration avancée

Utilisez ces options lorsque vous avez besoin de mieux contrôler les fournisseurs, les politiques et les intégrations. Pour démarrer rapidement, consultez les Notions de base de la configuration.

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

Profils

Les profils vous permettent d’enregistrer des couches de configuration nommées et de passer de l’une à l’autre depuis la CLI. Lorsque vous transmettez --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 tirets bas.

Créez un fichier TOML distinct pour chaque profil. Utilisez les 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"

Comme le fichier de profil constitue une couche située au-dessus de votre configuration utilisateur de base et en dessous de la configuration du projet et de la CLI, il ne doit contenir que les valeurs qui diffèrent de votre configuration de base. Les fichiers de profil peuvent également remplacer model_catalog_json ; Codex utilise la valeur du profil lorsque les deux fichiers la définissent.

Dans Codex 0.134.0 et versions ultérieures, --profile ne lit plus [profiles.profile-name] depuis 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 [profiles.profile-name] correspondante et le sélecteur profile = "profile-name" de config.toml.

Remplacements ponctuels depuis la CLI

Outre la modification de ~/.codex/config.toml, vous pouvez remplacer 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 lorsque vous devez remplacer une clé arbitraire.

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 par points pour définir des valeurs imbriquées (par exemple, mcp_servers.context7.enabled=false).
• Les valeurs --config sont analysées comme du TOML. En cas de doute, placez la valeur entre guillemets afin que votre shell ne la scinde pas au niveau des espaces.
• Si la valeur ne peut pas être analysée comme du TOML, Codex la traite comme une chaîne.

Emplacements de la configuration et de l’état

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

Fichiers courants que vous pouvez y trouver :

• config.toml (votre configuration locale)
• auth.json (si vous utilisez le stockage des identifiants dans des fichiers) ou le trousseau de votre système d’exploitation
• history.jsonl (si la persistance de l’historique est activée)
• D’autres données d’état propres à l’utilisateur, telles que les journaux et les caches

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

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

Si vous souhaitez simplement faire pointer le fournisseur OpenAI intégré vers un proxy LLM, un routeur ou un projet avec résidence des données 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 remplacements propres au projet depuis 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é, le fichier le plus proche de votre répertoire de travail l’emporte.

Pour des raisons de sécurité, Codex ne charge les fichiers de configuration propres au projet que lorsque celui-ci est approuvé. Si le projet n’est pas approuvé, Codex ignore les couches .codex/ du projet, notamment .codex/config.toml, les hooks locaux au projet et les règles locales au projet. Les couches utilisateur et système restent distinctes et continuent d’être chargées.

Les chemins relatifs figurant 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 remplacer les paramètres qui redirigent les identifiants, modifient les métadonnées des requêtes de l’application gérées par l’hôte, changent l’authentification du fournisseur, sélectionnent des profils de configuration ou exécutent des commandes locales de notification ou de télémétrie. Codex ignore les clés suivantes dans le fichier .codex/config.toml local au projet et affiche un avertissement au démarrage lorsqu’il les détecte : 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 ~/.codex/config.toml de niveau utilisateur ; 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 dans les 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 locaux au projet ne sont chargés que lorsque la couche .codex/ du projet est approuvée. Les hooks de niveau utilisateur restent indépendants du statut d’approbation du projet.

Les hooks TOML intégrés 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 [hooks] intégré, Codex charge les deux et affiche un avertissement. Privilégiez une seule représentation par couche.

Pour consulter la liste actuelle des événements, les champs d’entrée, le comportement des sorties et les limitations, reportez-vous à la page Hooks.

Rôles d’agent ([agents] dans config.toml)

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

Détection de la racine du projet

Codex découvre la configuration du projet (par exemple, les couches .codex/ et AGENTS.md) en remontant l’arborescence depuis le répertoire de travail jusqu’à atteindre une racine de 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 ne pas rechercher dans les répertoires parents et traiter 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 filaire, 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 ceux-ci :

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 autonome de recherche sur le Web, 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

La valeur par défaut du paramètre est false pour les fournisseurs personnalisés. La recherche autonome sur le Web 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 proposer 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 gérées continuent de s’appliquer.

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 adossée à une commande lorsqu’un fournisseur exige que Codex récupère des jetons bearer auprès d’un gestionnaire d’identifiants externe :

[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 aucun stdin et doit écrire le jeton sur stdout. Codex supprime les espaces environnants, considère un jeton vide comme une erreur et l’actualise de manière proactive à refresh_interval_ms ; définissez refresh_interval_ms = 0 pour ne l’actualiser 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é. Définissez-le directement comme model_provider ; contrairement aux fournisseurs personnalisés, ce fournisseur intégré ne prend en charge que les remplacements imbriqués du profil et de la région AWS.

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 d’identifiants AWS standard. Définissez region sur la région Bedrock prise en charge qui doit traiter les requêtes.

Pour connaître toute la procédure 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 s’exécuter avec un fournisseur « open source » local tel qu’Ollama ou LM Studio lorsque vous transmettez --oss. Choisissez-en un pour une seule exécution avec --local-provider, ou définissez oss_provider comme valeur par défaut. Si aucun n’est défini, la CLI interactive vous invite à en choisir un ; codex exec se termine avec 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 remplacer les identifiants des fournisseurs intégrés.

Clients ChatGPT utilisant la résidence des données

Les projets créés avec la résidence des données activée peuvent créer un fournisseur de modèles afin de mettre à jour base_url avec le préfixe approprié.

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

Raisonnement du modèle, verbosité et limites

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 ne s’applique qu’aux fournisseurs utilisant la Responses API. Les fournisseurs Chat Completions ignorent ce paramètre.

Politiques d’approbation et modes de bac à sable

Choisissez le niveau de rigueur 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 opérationnels à garder à l’esprit lors de la modification de config.toml, consultez les pages Combinaisons courantes de bac à sable et d’approbation, Chemins protégés dans les racines accessibles en écriture et Accès réseau.

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

Vous pouvez également utiliser une politique d’approbation granulaire (approval_policy = { granular = { ... } }) pour autoriser ou rejeter automatiquement certaines catégories d’invites. Cette option est utile si vous souhaitez conserver les approbations interactives habituelles dans certains cas, tout en faisant échouer automatiquement et de manière sécurisée d’autres cas, tels que request_permissions ou les invites de scripts de skills.

Définissez approvals_reviewer = "auto_review" pour acheminer les demandes d’approbation interactives éligibles vers une vérification automatique. Cela modifie le vérificateur, et non les limites du bac à sable.

Utilisez [auto_review].policy pour les instructions locales relatives à la politique du vérificateur. La valeur gérée guardian_policy_config est prioritaire.

approval_policy = "untrusted"   # Other options: on-request, 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 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 la page Autorisations.

Pour obtenir la liste complète des clés et les contraintes d’exigences, consultez la Référence de configuration et la 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. Commencez avec un environnement vide en utilisant inherit = "none", ou héritez d’un ensemble réduit 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 tiennent pas compte de la casse et prennent en charge * et ?. Utilisez "exclude" pour supprimer les variables correspondantes. Lorsqu’un motif utilise "include", Codex conserve uniquement les variables correspondant à un motif d’inclusion. Les inclusions ne rétablissent pas les variables qui ont déjà été exclues. Les clés de filtre sont fusionnées sans tenir compte de la casse entre les différentes couches de configuration.

La valeur par défaut de ignore_default_excludes est true ; Codex ne supprime donc pas automatiquement les noms de variables contenant KEY, SECRET ou TOKEN. Définissez-la 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 des motifs d’inclusion. Comme set s’exécute après les exclusions, il peut rétablir une variable exclue. Une liste d’autorisation de motifs d’inclusion peut néanmoins 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 la même couche de configuration ; Codex rejette cette combinaison.

Serveurs MCP

Consultez la documentation MCP dédiée pour obtenir 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, invites, approbations/résultats des outils). Elle est désactivée par défaut ; activez-la avec [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" }
}}

Si exporter = "none", Codex enregistre les événements, mais n’envoie rien. Les exportateurs traitent les données par lots de manière asynchrone et les vident à l’arrêt. Les métadonnées des événements comprennent le nom du service, la version de la CLI, l’étiquette d’environnement, l’identifiant de conversation, le modèle, les paramètres de bac à sable et d’approbation, ainsi que les champs propres à chaque événement (voir la 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. Les types d’événements représentatifs comprennent :

• codex.conversation_starts (modèle, paramètres de raisonnement, politique de bac à sable et d’approbation)
• codex.api_request (tentative, état/réussite, durée et détails de l’erreur)
• codex.sse_event (type d’événement du flux, réussite/échec, durée, ainsi que le nombre de jetons pour response.completed)
• codex.websocket_request et codex.websocket_event (durée de la requête, ainsi que type/réussite/erreur pour chaque message)
• codex.user_prompt (longueur ; contenu masqué sauf activation explicite)
• codex.tool_decision (approuvé/refusé et origine de la décision : configuration ou utilisateur)
• codex.tool_result (durée, réussite, extrait de 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é de l’API, des flux et des outils.

Chaque métrique ci-dessous comprend également les étiquettes 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é liées à la télémétrie, consultez la page Sécurité.

Métriques

Par défaut, Codex envoie périodiquement à OpenAI une petite quantité de données anonymes sur l’utilisation et l’état de fonctionnement. Ces données permettent de détecter les dysfonctionnements de Codex et d’identifier les fonctionnalités et 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 traces OTel.

Si vous souhaitez désactiver entièrement la collecte des métriques sur une machine pour l’application de bureau ChatGPT, Codex CLI et l’extension IDE, définissez l’indicateur 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 (applicables à chaque événement/métrique)

• 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. Les noms de métriques ci-dessous omettent le préfixe codex.. 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 hors de ce fichier sont également incluses 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 réelle ni le correctif que codex tente d’appliquer.

Environnement d’exécution et transport du modèle

La métrique cloud_requirements.fetch_attempt comprend les champs trigger, attempt, outcome et status_code. La métrique cloud_requirements.fetch_final comprend 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 comprennent status ; les émissions d’appels d’outils ordinaires comprennent également tool, ainsi que connector_id et connector_name lorsqu’ils sont disponibles. Les appels MCP Codex Apps bloqués peuvent émettre mcp.call avec uniquement status.

Threads, tâches et fonctionnalités

La métrique shell_snapshot comprend 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 comprennent migration_type ; les migrations de skills comprennent également skills_count.

Bac à sable Windows

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

Contrôles des commentaires

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

[feedback]
enabled = false

Lorsque cette fonctionnalité est désactivée, /feedback affiche un message indiquant qu’elle est désactivée et Codex refuse l’envoi de commentaires.

Masquer ou afficher les événements de raisonnement

Si vous souhaitez réduire les sorties de « raisonnement » parasites (par exemple dans les journaux CI), vous pouvez les supprimer :

hide_agent_reasoning = true

Si vous souhaitez afficher le contenu brut du raisonnement lorsqu’un modèle en émet :

show_raw_agent_reasoning = true

N’activez le raisonnement brut que s’il convient à votre flux de travail. 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 déclencher un programme externe chaque fois que Codex émet des événements pris en charge (actuellement, uniquement agent-turn-complete). Cette fonctionnalité est pratique pour les notifications de bureau, les webhooks de messagerie, les mises à jour CI ou toute alerte par un canal secondaire que les notifications intégrées à la TUI ne couvrent pas.

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

Exemple 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 seul 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 utilisateur ayant conduit au tour)
• last-assistant-message (texte du dernier message de l’assistant)

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

notify ou tui.notifications

• notify exécute un programme externe (adapté aux webhooks, aux outils de notification de bureau et aux hooks CI).
• tui.notifications est intégré à la TUI et peut éventuellement filtrer les événements par type (par exemple, agent-turn-complete et approval-requested).
• tui.notification_method contrôle 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 sont émises uniquement lorsque le terminal est unfocused ou always.

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

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 tout en conservant les enregistrements les plus récents.

[history]
max_bytes = 104857600 # 100 MiB

Citations cliquables

Si vous utilisez une intégration de terminal ou d’éditeur qui les prend en charge, Codex peut afficher les citations de fichiers sous forme de liens cliquables. Configurez file_opener pour choisir le schéma URI utilisé par Codex :

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

Exemple : une citation telle que /home/user/project/main.py:42 peut être convertie en lien vscode://file/...:42 cliquable.

Détection des instructions du projet

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

• 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 à un niveau de répertoire

Pour une présentation détaillée, consultez Instructions personnalisées avec AGENTS.md.

Application de bureau

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

Ajouter des gestionnaires de fichiers personnalisés

Dans votre fichier ~/.codex/config.toml au niveau utilisateur, 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 une cible d’éditeur aux menus Ouvrir dans de l’application. L’application affiche la cible lorsque command est un chemin absolu existant ou peut être résolu à partir du PATH de l’application.

L’exemple suivant présente trois manières 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 correspond au dernier segment de l’en-tête de table TOML. Il doit comporter entre 1 et 64 caractères, commencer par une lettre ou un chiffre ASCII et ne contenir ensuite que des lettres ASCII, des chiffres, 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. Placez entre guillemets tout identifiant contenant un point afin 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 input contrôle 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 location est un objet contenant les valeurs line et column indexées à partir de 1, ou null.
• json_stdin écrit l’objet JSON dans l’entrée standard au lieu d’ajouter un argument. Il inclut é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 }
}

La sélection d’un gestionnaire personnalisé comme éditeur préféré est conservée de la même manière que celle d’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 expose certains paramètres propres à la TUI sous [tui], notamment :

• tui.notifications : activer ou désactiver les notifications (ou les limiter à certains types)
• tui.notification_method : choisir auto, osc9 ou bel pour les notifications du terminal
• tui.notification_condition : choisir unfocused ou always pour déterminer quand les notifications sont émises
• tui.animations : activer ou désactiver les animations ASCII et les effets de scintillement
• tui.alternate_screen : contrôler l’utilisation de l’écran alternatif (définissez la valeur sur never pour conserver l’historique de défilement du terminal)
• tui.show_tooltips : afficher ou masquer les infobulles d’intégration 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 de terminal que certains terminaux interprètent comme une notification de bureau) lorsque le terminal semble les prendre en charge, et utilise sinon BEL (\x07) comme solution de secours.

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