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.6-sol"
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 pas sur la configuration du projet ni celle de la CLI. Il suffit donc d’y indiquer les valeurs qui diffèrent de votre configuration de base. Les fichiers de profil peuvent aussi remplacer la valeur de model_catalog_json ; Codex utilise alors la valeur du profil lorsque les deux fichiers la définissent.

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

Remplacements ponctuels depuis la CLI

Outre la modification de ~/.codex/config.toml, vous pouvez remplacer des paramètres de 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 remplacer la valeur d’une clé quelconque.

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 interprété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 interprétée au format TOML, Codex la traite comme une chaîne de caractères.

Emplacements de la configuration et de l’état

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

Voici les fichiers que vous pouvez généralement y trouver :

• config.toml (votre configuration locale)
• auth.json (si vous stockez vos 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)
• D’autres données d’état propres à chaque utilisateur, comme les journaux et les caches

Pour en savoir plus sur l’authentification, notamment 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, les règles et les skills partagés, 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 créer un 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 propres au projet dans les fichiers .codex/config.toml de votre dépôt. Codex parcourt les répertoires depuis la racine du projet jusqu’à votre répertoire de travail actuel et charge chaque fichier .codex/config.toml qu’il trouve. Si plusieurs fichiers définissent la même clé, celui qui est le plus proche de votre répertoire de travail a priorité.

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

Les chemins relatifs dans la configuration d’un 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 de requêtes d’application contrôlées par l’hôte, changent l’authentification des fournisseurs, 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 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 de configuration utilisateur ~/.codex/config.toml ; sélectionnez les profils de configuration avec --profile profile-name et ~/.codex/profile-name.config.toml.

Hooks

Codex peut aussi charger des hooks de cycle de vie depuis des fichiers hooks.json ou des tables [hooks] intégrées aux 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 si la couche .codex/ du projet est approuvée. Les hooks définis au niveau utilisateur ne dépendent pas de l’approbation 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 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 limites, 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 recherche la configuration du projet (par exemple, les couches .codex/ et AGENTS.md) en remontant depuis le répertoire de travail jusqu’à la racine d’un projet.

Par défaut, Codex considère un répertoire contenant .git comme 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 aux fournisseurs intégrés : openai, ollama et lmstudio.

Définissez des fournisseurs supplémentaires et référencez-les avec model_provider :

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

Ce paramètre vaut false par défaut pour les fournisseurs personnalisés. 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 suffit pas à l’activer : le fournisseur doit prendre en charge un point de terminaison compatible, et le modèle sélectionné ainsi que l’environnement d’exécution doivent prendre en charge la recherche autonome. Le mode web_search configuré et les restrictions de recherche administrées restent applicables.

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 sur stdin et doit écrire le token sur stdout. Codex supprime les espaces blancs en début et en fin de token, considère un token vide comme une erreur et le renouvelle de manière proactive à l’intervalle refresh_interval_ms ; définissez refresh_interval_ms = 0 pour le renouveler uniquement 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 intègre le fournisseur de modèles amazon-bedrock. Définissez-le directement comme valeur de model_provider ; contrairement aux fournisseurs personnalisés, ce fournisseur intégré ne permet de remplacer que les paramètres imbriqués de profil et de 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 standard de résolution des identifiants AWS. Définissez region sur la région Bedrock prise en charge qui doit traiter les requêtes.

Pour la procédure de configuration complète, 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 utiliser un fournisseur « open source » local, comme Ollama ou LM Studio, lorsque vous passez --oss. Choisissez-en un pour une seule exécution avec --local-provider, ou définissez le fournisseur par défaut avec oss_provider. Si aucun des deux n’est défini, la CLI interactive vous invite à choisir ; codex exec se termine avec une erreur.

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

Fournisseur Azure et réglages par 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 les identifiants des fournisseurs intégrés ne peuvent pas être redéfinis.

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 utilisant la 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, verbosité 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 d’isolation 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 Migrer depuis la politique d’approbation untrusted supprimée pour connaître les paramètres pris en charge et les approbations plus strictes fondées sur le projet.

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

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

Définissez approvals_reviewer = "auto_review" pour soumettre les demandes d’approbation interactives éligibles à une révision automatique. Ce paramètre change qui effectue la révision, sans modifier les limites du bac à sable.

Utilisez [auto_review].policy pour définir les instructions locales 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 en savoir plus sur 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 obtenir 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 complètement 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 quelles variables d’environnement Codex transmet aux commandes qu’il lance. Commencez avec un environnement vide en utilisant 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 sont insensibles à la casse et prennent en charge * et ?. Utilisez "exclude" pour supprimer les variables correspondantes. Dès qu’un motif utilise "include", Codex ne conserve que les variables correspondant à un motif d’inclusion. Les inclusions ne rétablissent pas les variables déjà exclues. Les clés de filtrage sont fusionnées sans tenir compte de la 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 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 fondée sur les motifs d’inclusion. Comme set s’applique après les exclusions, il peut rétablir une variable exclue. La liste d’autorisation fondée sur les 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 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 exportation 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" }
}}

Si exporter = "none", Codex enregistre les événements mais n’envoie rien. Les exportateurs regroupent les événements en lots de façon 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 de bac à sable et d’approbation, ainsi que des 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/réussite, durée et détails des erreurs)
• codex.sse_event (type d’événement du flux, réussite/échec, durée et nombre de tokens lors de response.completed)
• codex.websocket_request et codex.websocket_event (durée de la requête et type/réussite/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, 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 l’activité de l’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 régulièrement à 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 les priorités. 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 (applicables à chaque événement et 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 des métriques ci-dessous sont présentés sans 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 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 réelle ni le patch 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é des tours et des outils

Les métriques mcp.call et mcp.call.duration_ms incluent status ; les données émises lors des appels d’outils ordinaires incluent également 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 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 d’exécution partagé de la configuration. La métrique windows_sandbox.legacy_setup_preflight_failed inclut originator lorsqu’elle est émise depuis ce même chemin d’exécution, mais les échecs de vérification préalable depuis l’invite de secours peuvent ne comporter aucun champ.

Paramètres des commentaires

Par défaut, les clients locaux permettent aux utilisateurs d’envoyer des commentaires via /feedback. Pour désactiver la collecte des commentaires 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 le signalant et Codex refuse l’envoi de commentaires.

Masquer ou afficher les événements de raisonnement

Si les sorties de « raisonnement » encombrent vos journaux (par exemple, ceux de la 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 est acceptable pour 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 utile pour les notifications de bureau, les webhooks de messagerie, les mises à jour de CI ou toute alerte sur un canal auxiliaire 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 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 de l’utilisateur à l’origine du tour)
• last-assistant-message (texte du dernier message de l’assistant)

Placez le script sur le disque et configurez notify pour qu’il pointe vers ce script.

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 les notifications par type d’événement (par exemple, agent-turn-complete et approval-requested).
• tui.notification_method définit la façon 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 sinon 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, ~/.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 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 convertie 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 à un niveau de 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.

Ajoutez des gestionnaires d’ouverture 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’application affiche cet éditeur lorsque command est un chemin absolu existant ou peut être résolu à partir du 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 de 1 à 64 caractères, commencer par une lettre ou un chiffre ASCII et ne contenir ensuite que des lettres et 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. Mettez entre 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 choisissez 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 options de configuration 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éfinir quand les notifications sont émises
• 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 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.