Configuration avancée

Utilisez ces options lorsque vous avez besoin d’un contrôle accru sur les fournisseurs, les politiques et les intégrations. Pour démarrer rapidement, consultez Principes 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 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 du 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"

Comme le fichier de profil constitue une couche située au-dessus de votre configuration utilisateur de base et en dessous des configurations du projet et de la CLI, il doit uniquement contenir 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

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

Emplacements de la configuration et de l’état

Codex stocke son état local sous CODEX_HOME (valeur 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 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 à l’utilisateur, comme les journaux et les caches

Pour plus de détails sur l’authentification (notamment les modes de stockage des identifiants), consultez 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 intégrés aux dépôts ou aux chemins système, consultez Configuration d’équipe.

Si vous avez seulement besoin de diriger 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 dans les fichiers .codex/config.toml de votre dépôt. Codex parcourt le chemin de la racine du projet jusqu’à votre répertoire de travail actuel et charge chaque fichier .codex/config.toml rencontré. 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 charge les fichiers de configuration propres au projet uniquement lorsque celui-ci est approuvé. Si le projet n’est pas approuvé, Codex ignore les couches .codex/ du projet, y compris .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 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 de requête d’une application gérée 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 des fichiers config.toml situés à côté des couches de configuration actives.

En pratique, les quatre emplacements les plus utiles sont :

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

Les hooks 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 de l’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 une configuration [hooks] intégrée, 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 de sortie et les limitations, consultez Hooks.

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

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

Détection de la racine du projet

Codex détecte la configuration du projet (par exemple, les couches .codex/ et AGENTS.md) en remontant l’arborescence depuis le répertoire de travail jusqu’à atteindre 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 ignorer la recherche 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 de transport, authentification et éventuels en-têtes HTTP). Les fournisseurs personnalisés ne peuvent pas réutiliser les ID réservés aux fournisseurs intégrés : openai, ollama et lmstudio.

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

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

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

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

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

Si un fournisseur personnalisé prend en charge le point de terminaison 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 prendre en charge un point de terminaison compatible, et le modèle ainsi que l’environnement d’exécution sélectionnés doivent prendre en charge la recherche autonome. Le mode web_search configuré et les restrictions de recherche 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 reposant sur 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 qui l’entourent, traite 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é prend uniquement en charge 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 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 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 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 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 ID des fournisseurs intégrés.

Organisations API 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é. Pour les espaces de travail ChatGPT avec résidence des données, aucun fournisseur personnalisé n’est requis ; 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 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 s’applique uniquement aux fournisseurs qui utilisent 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 s’interrompt) et le niveau du bac à sable (qui détermine l’accès aux fichiers et au réseau).

Pour connaître les aspects opérationnels à 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 les profils d’autorisation 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 refuser automatiquement certaines catégories d’invites. Cette approche est utile lorsque vous souhaitez conserver les approbations interactives habituelles dans certains cas, mais que d’autres, comme request_permissions ou les invites de scripts de skills, échouent automatiquement de manière sécurisée.

Définissez approvals_reviewer = "auto_review" pour faire passer les demandes d’approbation interactives éligibles par un examen automatique. Cela modifie l’examinateur, pas la limite du bac à sable.

Utilisez [auto_review].policy pour les instructions de politique de l’examinateur local. La configuration gérée 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’autorisation 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 Autorisations.

Pour obtenir la liste complète des clés et les contraintes liées aux exigences, consultez la Référence de configuration et la Configuration gérée.

Désactivez entièrement le bac à sable (à utiliser 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 lancées. Partez d’un environnement vide avec inherit = "none", ou héritez d’un ensemble restreint 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. Lorsqu’un motif utilise "include", Codex conserve uniquement les variables correspondant à un motif d’inclusion. Les inclusions ne rétablissent pas les variables déjà exclues. Les clés de filtrage sont fusionnées sans tenir compte de la casse entre les 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 toutefois supprimer à nouveau 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 et résultats des outils). Cette fonctionnalité est désactivée par défaut ; activez-la via [otel] :

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

Choisissez un exportateur :

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

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

Avec exporter = "none", Codex enregistre les événements, mais n’envoie rien. Les exportateurs regroupent les données de manière asynchrone et les transmettent à l’arrêt. Les métadonnées d’événement incluent le nom du service, la version de la CLI, l’étiquette d’environnement, l’ID de conversation, le modèle, les paramètres de bac à sable et d’approbation, ainsi que les champs propres à chaque événement (consultez 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. 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, état/réussite, durée et détails de l’erreur)
• codex.sse_event (type d’événement de 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 inclut également les étiquettes de métadonnées par défaut : auth_mode, originator, session_source, model et app.version.

Pour plus de conseils sur la sécurité et la confidentialité liés à la télémétrie, consultez Sécurité.

Métriques

Par défaut, Codex envoie périodiquement à OpenAI un petit volume de données anonymes sur l’utilisation et l’état de fonctionnement. Ces données aident à détecter les dysfonctionnements de Codex et indiquent quelles fonctionnalités et options de configuration sont utilisées, afin que l’équipe Codex puisse se concentrer sur les aspects les plus importants. Ces métriques ne contiennent aucune information permettant d’identifier personnellement une personne (PII). La collecte des métriques est indépendante de l’exportation des journaux et des 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 contextuels par défaut ci-dessous.

Champs contextuels 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 contextuels 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 émises en dehors 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 pas la commande shell ou le patch que codex tente réellement d’appliquer.

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 normaux comprennent également tool, ainsi que connector_id et connector_name lorsqu’ils sont disponibles. Les appels MCP de 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 sous 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 comporter 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 sur une machine dans l’app de bureau ChatGPT, Codex CLI et l’extension IDE, mettez à jour votre configuration :

[feedback]
enabled = false

Lorsqu’elle est désactivée, /feedback affiche un message indiquant la désactivation 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 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 déclencher un programme externe chaque fois que Codex émet des événements pris en charge (actuellement, uniquement agent-turn-complete). Cette option est pratique pour les notifications de bureau, les webhooks de messagerie, les mises à jour CI ou tout autre canal d’alerte non couvert par les notifications intégrées à la TUI.

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 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 par type d’événement (par exemple, agent-turn-complete et approval-requested).
• tui.notification_method détermine comment 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 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 BEL (\x07) comme solution de secours dans les autres cas.

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 le permet, 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 transformée en lien vscode://file/...:42 cliquable.

Découverte 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 à essayer lorsque AGENTS.md est absent à un niveau de répertoire

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

Bureau

Les options de cette section s’appliquent uniquement à l’app 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’app 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’app. L’app affiche la cible lorsque command est un chemin absolu existant ou peut être résolu depuis le PATH de l’app.

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’app de bureau ChatGPT.

L’identifiant du gestionnaire correspond au dernier segment de l’en-tête de table TOML. Il doit contenir entre 1 et 64 caractères, commencer par une lettre ou un chiffre ASCII et ne contenir par ailleurs que des lettres ASCII, des chiffres, des points, des tirets bas ou des traits d’union. L’app 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 détermine ce qui suit args :

• path ajoute le chemin comme dernier argument de la commande.
• json_argument ajoute un objet JSON comprenant target, path, appPath et location. La valeur location est un objet comportant des valeurs line et column indexées à partir de 1, ou null.
• json_stdin écrit l’objet JSON sur 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 }
}

Le choix d’un gestionnaire personnalisé comme éditeur préféré est conservé de la même manière que celui 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 se déclenchent
• 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 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

tui.notification_method vaut auto par défaut. 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 BEL (\x07) comme solution de secours dans les autres cas.

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