Configuration avancée

Utilisez ces options pour contrôler plus finement les fournisseurs, les politiques et les intégrations. Pour démarrer rapidement, consultez les principes de base de la configuration.

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

Application de ces exemples à l’accès à l’ordinateur local avec Work Cloud

Ces exemples décrivent la configuration de Codex. Consultez la référence de configuration avant de les adapter à l’accès à l’ordinateur local avec Work Cloud.

• Portée des politiques : pour le mode Work avec accès local et pour les dots, les règles prises en charge de la politique globale s’appliquent à l’orchestrateur cloud partagé lorsque la gestion des politiques est activée. Les exigences d’exécution locale applicables régissent l’ordinateur connecté. Les conteneurs cloud de Work conservent les politiques Work Cloud existantes.
• Exécution locale : les exigences MDM et les anciennes exigences relatives aux appareils gérés ont priorité sur les règles de sécurité des agents. Ces dernières ont priorité sur le fichier d’exigences système de l’appareil.
• Hooks d’entreprise : si cette fonctionnalité est activée pour votre espace de travail, les administrateurs peuvent définir des hooks MCP qui s’exécutent sur le coordinateur cloud (l’orchestrateur) lors des événements de cycle de vie et d’outils pris en charge. L’orchestration cloud ne prend en charge ni les hooks de commande ni ceux issus de la configuration locale ou de plugins, même lorsque les outils s’exécutent localement.
• Audit : avant de vous appuyer sur ces hooks, testez la connexion de rappel, vérifiez quels événements elle reçoit et examinez l’incidence des échecs sur la tâche. Les hooks MCP ne fournissent pas de piste d’audit complète pour l’API de conformité.
• Autres paramètres : la configuration gérée ne transmet à cette fonctionnalité ni les fournisseurs de modèles personnalisés ni les chemins locaux de l’hôte. Consultez les restrictions réseau et les règles de fusion propres à chaque champ dans la configuration gérée.

Consultez la page Hooks pour connaître les cas pris en charge et la procédure de configuration.

Profils

Les profils permettent d’enregistrer des couches de configuration sous un nom et de passer de l’une à l’autre depuis la CLI. Lorsque vous utilisez --profile profile-name, Codex charge ~/.codex/config.toml, puis applique les paramètres de ~/.codex/profile-name.config.toml. Les noms de profil peuvent contenir des lettres, des chiffres, des traits d’union et des tirets bas.

Créez un fichier TOML distinct pour chaque profil. Placez les clés de configuration à la racine du fichier de profil, sans les imbriquer sous [profiles.profile-name].

L’exemple utilise GPT-6.1 Sol. Votre compte connecté ou votre espace de travail doit avoir accès à ce modèle. S’il est indisponible, choisissez un modèle auquel vous avez accès.

1
2
3
4
5# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
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 la configuration du projet et celle de la CLI ont priorité sur le profil. Il suffit donc d’y indiquer les valeurs qui diffèrent de votre configuration de base. Le profil peut aussi redéfinir model_catalog_json. Si les deux fichiers définissent cette clé, Codex utilise la valeur du profil.

À partir de Codex 0.134.0, --profile ne lit plus la table [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 dans ~/.codex/profile-name.config.toml, puis supprimez la table [profiles.profile-name] correspondante et le sélecteur profile = "profile-name" de config.toml.

Remplacement ponctuel de paramètres depuis la CLI

Vous pouvez modifier ~/.codex/config.toml ou remplacer des paramètres 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 remplacer la valeur d’une clé quelconque.

Les exemples ci-dessous qui changent le modèle nécessitent également un accès à GPT-6.1 Sol. Si vous n’y avez pas accès, remplacez-le par un modèle disponible pour votre compte :

1
2
3
4
5
6# Dedicated flag
codex --model gpt-6.1-sol
# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-6.1-sol"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Remarques :

• Utilisez la notation pointée pour définir des valeurs imbriquées (par exemple, mcp_servers.context7.enabled=false).
• Les valeurs de --config sont interprétées au format TOML. En cas de doute, placez la valeur entre guillemets pour éviter que le shell ne la scinde au niveau des espaces.
• Si Codex ne parvient pas à interpréter la valeur au format TOML, il la traite comme une chaîne de caractères.

Emplacement de la configuration et de l’état local

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

Vous y trouverez généralement les éléments suivants :

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

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

Pour les paramètres par défaut, les règles et les skills partagés, enregistrés dans les dépôts ou placés dans des répertoires système, consultez la configuration d’équipe.

Pour connecter le fournisseur OpenAI intégré à un proxy LLM, à un routeur ou à un projet pour lequel la résidence des données est activée, définissez openai_base_url dans config.toml au lieu de créer un fournisseur. Ce paramètre change l’URL de base du fournisseur intégré openai 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 propres au projet dans les fichiers .codex/config.toml du dépôt. Il parcourt les répertoires depuis la racine du projet jusqu’au répertoire de travail actuel et charge chaque fichier .codex/config.toml trouvé. Si plusieurs fichiers définissent la même clé, la valeur du fichier le plus proche du répertoire de travail prévaut.

Par mesure de sécurité, Codex ne charge les fichiers de configuration propres au projet que si celui-ci est approuvé. Dans le cas contraire, Codex ignore les couches .codex/ du projet, notamment .codex/config.toml, les hooks et les règles propres au projet. Il continue de charger séparément les couches utilisateur et système.

Codex résout les chemins relatifs d’une configuration de projet (par exemple, model_instructions_file) à partir du 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 de requêtes d’application gérées par l’hôte, changent l’authentification du fournisseur, sélectionnent un profil de configuration ou exécutent des commandes locales de notification ou de télémétrie. Dans le fichier .codex/config.toml du projet, Codex ignore les clés suivantes et affiche un avertissement au démarrage s’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 utilisateur ~/.codex/config.toml. Pour sélectionner un profil de configuration, utilisez --profile profile-name et ~/.codex/profile-name.config.toml.

Hooks

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

En pratique, les quatre emplacements les plus utiles sont les suivants :

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

Codex ne charge les hooks du projet que si la couche .codex/ du projet est approuvée. Les hooks de l’utilisateur sont indépendants du statut de confiance du projet.

Les hooks intégrés au 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 un fichier hooks.json et une table [hooks] intégrée, Codex charge les deux et affiche un avertissement. Privilégiez un seul format par couche.

Pour connaître les événements actuellement pris en charge, les champs d’entrée, le traitement des sorties et les limites, consultez la page Hooks.

Rôles des agents ([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 recherche la configuration du projet (par exemple, les couches .codex/ et le fichier AGENTS.md) en remontant depuis le répertoire de travail jusqu’à la racine du 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 les répertoires parents et utiliser le répertoire de travail actuel comme racine du projet.

Fournisseurs de modèles personnalisés

Si votre organisation fournit une passerelle de modèles, suivez les étapes de connexion à une passerelle pour configurer le client et vérifier la connexion. Pour un déploiement à l’échelle de l’organisation, consultez le guide de déploiement d’une passerelle.

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). Choisissez un identifiant unique pour chaque fournisseur personnalisé. Codex réserve openai, ollama, lmstudio, amazon-bedrock, amazon-bedrock-runtime et gcp à ses fournisseurs intégrés.

Définissez des fournisseurs supplémentaires et utilisez model_provider pour sélectionner celui à utiliser :

1
2
3
4
5
6
7
8
9
10
11
12
13model = "gpt-6.1-sol"
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 fonctionnalité 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éclarer sa prise en charge avec true ne suffit pas à l’activer. Le fournisseur doit proposer un point de terminaison compatible, et le modèle sélectionné comme l’environnement d’exécution 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" }

Pour vous connecter depuis le navigateur via le fournisseur d’identité de votre organisation, utilisez OAuth natif pour les passerelles. Dans [model_providers.<id>.gateway_oauth], indiquez les URL d’autorisation et d’obtention des jetons, l’identifiant du client public et les paramètres de transmission du jeton. Cette configuration fonctionne avec requires_openai_auth = false sans nécessiter de connexion à ChatGPT, de PowerShell, de CLI Azure ni d’utilitaire externe de gestion des identifiants. La passerelle doit accepter le jeton OAuth dans le cookie ou l’en-tête personnalisé configuré.

Utilisez l’authentification par commande si le fournisseur exige que Codex récupère des jetons 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 rien sur stdin et doit écrire le jeton sur stdout. Codex supprime les espaces blancs en début et en fin de jeton, traite un jeton vide comme une erreur et renouvelle le jeton à 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

Définissez model_provider sur amazon-bedrock pour utiliser le point de terminaison Bedrock Mantle ou sur amazon-bedrock-runtime pour utiliser le point de terminaison Runtime. Pour sélectionner les identifiants AWS et la région à utiliser avec Mantle, configurez sa table 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 standard de recherche des identifiants AWS. Pour region, indiquez la région Bedrock prise en charge qui doit traiter les requêtes.

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

Fournisseur Google Cloud Vertex AI

Pour utiliser un modèle auquel votre projet a accès sur Vertex AI, sélectionnez le fournisseur intégré dans config.toml :

model_provider = "gcp"

[model_providers.gcp]
project_id = "my-project"
location = "global"

Si vous omettez project_id ou location, Codex lit respectivement GOOGLE_CLOUD_PROJECT ou GOOGLE_CLOUD_LOCATION. L’emplacement par défaut est global.

Pour utiliser l’authentification par défaut, installez la CLI Google Cloud sur la machine qui exécute Codex. Pour vous connecter localement, exécutez gcloud auth application-default login. Codex exécute gcloud auth application-default print-access-token pour obtenir des jetons d’accès.

Pour utiliser un fichier ADC précis, indiquez son chemin absolu dans credential_file sous [model_providers.gcp]. Codex attribue ce chemin à GOOGLE_APPLICATION_CREDENTIALS pour la commande d’authentification.

Si votre déploiement utilise un autre point de terminaison, une autre commande d’obtention de jetons ou d’autres en-têtes statiques, configurez respectivement base_url, auth ou http_headers sous [model_providers.gcp].

Mode OSS (fournisseurs locaux)

Avec l’option --oss, Codex peut utiliser un fournisseur local « open source » tel qu’Ollama ou LM Studio. Choisissez un fournisseur pour une seule exécution avec --local-provider, ou définissez le fournisseur par défaut avec oss_provider. Si vous n’utilisez aucune de ces options, la CLI interactive vous invite à choisir un fournisseur, tandis que 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 de table [model_providers.openai], car les identifiants des fournisseurs intégrés ne peuvent pas être redéfinis.

Organisations utilisant l’API avec 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 et modifier base_url pour utiliser le préfixe approprié. Les espaces de travail ChatGPT avec résidence des données ne nécessitent pas de fournisseur personnalisé. Lorsque vous vous connectez avec ChatGPT, Codex respecte les paramètres de résidence de l’espace de travail.

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, niveau de détail et limites

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

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

Politiques d’approbation et modes de bac à sable

Choisissez le degré de rigueur des approbations, qui détermine quand Codex suspend l’exécution, et le niveau d’isolation du bac à sable, qui régit l’accès aux fichiers et au réseau.

Pour modifier config.toml, consultez les combinaisons courantes de bac à sable et d’approbation, les chemins protégés dans les racines accessibles en écriture et la section sur l’accès au réseau.

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

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

Vous pouvez aussi utiliser une politique d’approbation détaillée (approval_policy = { granular = { ... } }) pour autoriser ou rejeter automatiquement les demandes selon leur catégorie. Vous pouvez ainsi conserver les approbations interactives habituelles dans certains cas et refuser automatiquement d’autres demandes, comme celles de request_permissions ou des scripts de skills.

Définissez approvals_reviewer = "auto_review" pour confier les demandes d’approbation interactives admissibles à la fonctionnalité Révision automatique. Pour remplacer la politique qui guide cet examen, consultez la configuration de la Révision automatique.

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for Auto-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

Profils d’autorisations nommés

Pour connaître les profils intégrés, la syntaxe des profils personnalisés et l’ensemble des paramètres d’accès au système de fichiers et au réseau, consultez la page Autorisations.

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

Pour désactiver entièrement le bac à sable, utilisez le réglage suivant uniquement si votre environnement isole déjà les processus :

sandbox_mode = "danger-full-access"

Politique d’environnement du shell

shell_environment_policy contrôle les variables d’environnement que Codex transmet aux commandes qu’il lance. 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 nom de variable pour éviter de transmettre des secrets inutiles aux commandes.

[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 sont insensibles à la casse et acceptent * 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. L’inclusion ne rétablit pas les variables déjà exclues. Lors de la fusion des couches de configuration, Codex compare les clés de filtre sans tenir compte de la casse.

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 vos filtres explicites.

Codex applique d’abord les exclusions automatiques, puis les exclusions personnalisées, les valeurs de set et enfin la liste des motifs d’inclusion autorisés. Comme set intervient après les exclusions, il peut rétablir une variable exclue. La liste des motifs d’inclusion peut encore écarter cette valeur.

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

Pour configurer les serveurs, consultez la documentation MCP.

Observabilité et télémétrie

Activez l’exportation des journaux OpenTelemetry (OTel) pour suivre les exécutions de Codex : requêtes API, événements SSE, prompts, approbations et résultats des outils. L’exportation est désactivée par défaut. Pour l’activer, configurez [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

Les administrateurs peuvent imposer le choix des exportateurs et la valeur de chaque paramètre de journalisation dans requirements.toml.

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 les envoyer. Les exportateurs regroupent les événements par lots de manière asynchrone et envoient ceux qui restent à l’arrêt. Les métadonnées 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 des champs propres à chaque événement (voir la référence de configuration).

Événements émis

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 et réussite, durée et détails de l’erreur)
• codex.sse_event (type d’événement du flux, réussite ou échec, durée et, pour response.completed, nombre de tokens)
• codex.websocket_request et codex.websocket_event (durée de la requête, puis type, réussite et erreur pour chaque message)
• codex.user_prompt (longueur du prompt, contenu masqué sauf activation explicite de sa journalisation)
• codex.agent_response (réponses finales de l’agent principal et des sous-agents lancés lorsque otel.log_agent_responses = true)
• codex.guardian_assessment (révisions automatiques des demandes d’approbation arrivées à leur terme lorsque otel.log_guardian_assessments = true)
• codex.tool_decision (approbation ou refus, et origine de la décision : configuration ou utilisateur)
• codex.tool_result (durée, réussite, 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 les requêtes API, les flux et les outils.

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

Pour plus d’informations sur la sécurité et la confidentialité de la télémétrie, consultez la page Sécurité.

Métriques

Par défaut, Codex transmet périodiquement à OpenAI un petit volume de données anonymes sur son utilisation et son fonctionnement. Ces données aident l’équipe Codex à détecter les dysfonctionnements et à identifier les fonctionnalités et options de configuration utilisées pour orienter ses priorités. Ces métriques ne contiennent aucune information permettant d’identifier une personne (PII). Leur collecte est indépendante de l’exportation des journaux et des traces OTel.

Pour désactiver l’analyse d’usage et l’exportateur de métriques intégré statsig, définissez le paramètre suivant dans votre configuration :

[analytics]
enabled = false

Pour désactiver également un exportateur de métriques OTLP personnalisé, définissez otel.metrics_exporter = "none".

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

Champs de contexte par défaut pour chaque événement et chaque 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 et les champs de contexte par défaut indiqués ci-dessus. Les noms ci-dessous omettent le préfixe codex.. La plupart des noms de métriques sont regroupés dans codex-rs/otel/src/metrics/names.rs. Le catalogue inclut aussi les métriques propres à certaines fonctionnalités qui sont émises ailleurs. Lorsqu’une métrique comprend le champ tool, celui-ci indique l’outil interne utilisé (par exemple, apply_patch ou shell). Il ne contient ni la commande shell ni le correctif que codex tente d’appliquer.

Exécution et transport des échanges avec le 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é par tour et par outil

Les métriques mcp.call et mcp.call.duration_ms comprennent le champ status. Pour les appels d’outils ordinaires, elles comprennent également tool, ainsi que connector_id et connector_name lorsqu’ils sont disponibles. Un appel MCP bloqué dans les applications Codex peut émettre mcp.call avec le seul champ status.

Fils de discussion, tâches et fonctionnalités

La métrique shell_snapshot comprend le champ 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 le champ migration_type. Pour les migrations de skills, elles comprennent aussi skills_count.

Bac à sable Windows

Les métriques d’échec de configuration avec élévation de privilèges comprennent code et message lorsque les détails de l’échec sous Windows sont disponibles. Elles peuvent aussi comprendre originator lorsqu’elles proviennent de la procédure de configuration commune. La métrique windows_sandbox.legacy_setup_preflight_failed comprend originator lorsqu’elle provient de cette procédure, mais les échecs de vérification préalable depuis l’invite de secours peuvent ne comporter aucun champ.

Paramètres d’envoi des commentaires

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

[feedback]
enabled = false

Lorsque la collecte est désactivée, /feedback affiche un message à cet effet et Codex refuse les envois de commentaires.

Masquage ou affichage des événements de raisonnement

Pour alléger la sortie, par exemple dans les journaux de CI, vous pouvez masquer les messages de « raisonnement » :

hide_agent_reasoning = true

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

show_raw_agent_reasoning = true

N’activez l’affichage du raisonnement brut que s’il convient à votre workflow. Certains modèles ou fournisseurs (comme gpt-oss) n’émettent pas de raisonnement brut. Ce réglage n’a alors aucun effet visible.

Notifications

Utilisez notify pour lancer un programme externe chaque fois que Codex émet un événement pris en charge (actuellement, seul agent-turn-complete est pris en charge). Vous pouvez ainsi afficher des notifications de bureau, appeler des webhooks de messagerie, transmettre des mises à jour à la CI ou envoyer des alertes par d’autres canaux que ceux des notifications intégrées à la TUI.

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

Exemple abrégé de script notify.py qui réagit à agent-turn-complete :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35#!/usr/bin/env python3
import argparse
import json
import subprocess
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Show a Codex turn-completion notification on macOS."
    )
    parser.add_argument("notification", type=json.loads, help="Codex notification JSON")
    notification = parser.parse_args().notification
    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 sont les suivants :

• 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)

Enregistrez le script sur le disque et indiquez son chemin dans notify.

Différences entre notify et tui.notifications

• notify lance un programme externe, par exemple pour appeler des webhooks, afficher des notifications de bureau ou déclencher des hooks de CI.
• tui.notifications est intégré à la TUI et permet de filtrer les notifications par type d’événement (par exemple, agent-turn-complete et approval-requested).
• tui.notification_method contrôle la méthode utilisée par la TUI pour émettre les notifications du terminal (auto, osc9 ou bel).
• tui.notification_condition détermine si la TUI émet des notifications 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. À défaut, il utilise BEL (\x07).

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

Conservation de l’historique

Par défaut, Codex enregistre les transcriptions des sessions locales sous CODEX_HOME (par exemple, dans ~/.codex/history.jsonl). Pour désactiver la conservation 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 votre intégration de terminal ou d’éditeur le permet, 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

Par exemple, Codex peut convertir une référence comme /home/user/project/main.py:42 en lien cliquable vscode://file/...:42.

Recherche des instructions du projet

Codex lit AGENTS.md et les fichiers associés, puis 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é maximale de données à lire dans chaque fichier AGENTS.md
• project_doc_fallback_filenames : autres noms de fichiers à rechercher lorsqu’un répertoire ne contient pas de fichier AGENTS.md

Pour connaître la procédure détaillée, consultez le guide des 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 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’éditeur apparaît si command est un chemin absolu existant ou si l’application trouve la commande dans son PATH.

L’exemple suivant illustre 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 de 1 à 64 caractères et commencer par une lettre ou un chiffre ASCII. Les caractères suivants doivent être des lettres ou des chiffres ASCII, des points, des tirets bas ou des traits d’union. L’application ajoute le préfixe custom: à l’identifiant. Par exemple, company_editor devient custom:company_editor. Si l’identifiant contient un point, placez-le entre guillemets 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 accepte 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 un objet dont les champs line et column sont numérotés à partir de 1, ou null.
• json_stdin écrit l’objet JSON sur l’entrée standard au lieu d’ajouter un argument. L’objet comprend également hostConfig, remoteWorkspaceRoot et remotePath. Ces champs valent null lorsqu’ils ne s’appliquent pas.

Par exemple, company_editor peut recevoir l’argument suivant 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 choisissez un gestionnaire personnalisé comme éditeur préféré, l’application enregistre ce choix de la même manière que pour un éditeur intégré, y compris pour les préférences propres à chaque projet.

Options de la TUI

L’exécution de codex sans sous-commande lance l’interface interactive du terminal (TUI). Codex regroupe plusieurs paramètres propres à cette interface 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 pour émettre les notifications lorsque le terminal n’a pas le focus, ou always pour les émettre dans tous les cas.
• 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 (choisissez 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.

tui.notification_method vaut auto par défaut. En mode auto, Codex privilégie les notifications OSC 9 lorsque le terminal semble les prendre en charge. Certains terminaux interprètent cette séquence d’échappement comme une notification de bureau. À défaut, Codex utilise BEL (\x07).

Pour obtenir la liste complète des clés, consultez la référence de configuration.