Configuration avancée de Codex

Codex CLILa couche de configuration avancée nous permet de contrôler précisément les fournisseurs de modèles, les autorisations de sandbox, les hooks, les données de télémétrie et le comportement du terminal.

Si vous débutez avec Codex, lisez d'abordBases de la configuration(Notions de base de la configuration)pour acquérir une compréhension globale ; cet article suppose que vous connaissez déjà~/.codex/config.tomlson existence et sa finalité.


Aperçu de la hiérarchie de configuration

La configuration de Codex est composée de plusieurs couches empilées. Comprendre cela est la pierre angulaire de tout usage avancé ultérieur.

De bas en haut, les couches sont : couche système → couche utilisateur (~/.codex/config.toml) → couche Profil → couche projet (.codex/config.toml) → arguments de ligne de commande de la CLI.

Les couches supérieures remplacent les couches inférieures du même nom ; la configuration de projet la plus proche du répertoire de travail actuel a la priorité la plus élevée.

Title Codex configuration hierarchy (bottom → top, overridden in order) Layer 5: CLI ① CLI command-line arguments (highest priority) --model、--config、--profile Layer 4: Project-level ② Project-level .codex/config.toml The .codex/ directory in the repository (requires the project to be trusted) Layer 3: Profile ③ Profile named configuration (--profile) ~/.codex/<name>.config.toml Layer 2: User-level ④ User-level ~/.codex/config.toml Personal default configuration under the CODEX_HOME directory Layer 1: System-level ⑤ System-level / team-shared configuration Team Config shared rules and system-level files Right-side notes Single-run override Project-level enforcement Scenario switching Personal defaults Team baseline Bottom notes Merge rules: for the same key, the later one overrides the earlier one; dot syntax can target nested fields. Example: --config mcp_servers.context7.enabled=false disables a single MCP service

La façon la plus sûre de déterminer la configuration actuellement active estcodex --helpd'utiliser les journaux, ou d'utiliser explicitementcodex exec "show my current config"et de laisser le modèle l'interpréter pour vous.


Profils : couche de configuration nommée

Profilest l'approche recommandée par Codex de « changement basé sur des scénarios » : enregistrez un ensemble de configurations dans un fichier TOML, et chargez-le à la demande via--profilechargement.

Les fichiers de profil se trouvent dans~/.codex/<name>.config.toml, où<name>ne peut contenir que des lettres, des chiffres, des traits d'union et des traits de soulignement.

Créer et utiliser un profil

Supposons que vous effectuez souvent des revues de code approfondies et que vous souhaitiez une capacité de raisonnement plus forte :

Exemple

# Chemin du fichier : ~/.codex/deep-review.config.toml
model = "gpt-5.5"                  # Utiliser un modèle avec une capacité de raisonnement plus forte
model_reasoning_effort = "xhigh"   # Régler l'effort de raisonnement au maximum
approval_policy = "on-request"    # Demander une approbation à chaque appel d'outil
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"  # Facultatif : répertoire de modèles personnalisé

Lancer Codex avec le profil :

Exemple

# Lancer l'interface TUI interactive
codex --profile deep-review

# Ou à utiliser en mode exec non interactif
codex exec --profile deep-review "examiner ce changement"

Sémantique de fusion des profils

Les fichiers de profil ne constituent pas une configuration complète ; ils sont une surcharge incrémentielle par-dessus la couche au niveau utilisateur~/.codex/config.toml.

Cela signifie que vous devez uniquement écrire les champs "différents de la configuration par défaut" dans le profil ; les autres champs héritent automatiquement des paramètres au niveau utilisateur.

Si le niveau utilisateur et le profil définissent le même champmodel_catalog_json,la valeur du profil est prioritaire.。

À partir de Codex 0.134.0,--profileil ne lit plusconfig.tomldans[profiles.<name>]tables, et ne prend plus en charge les sélecteurs de niveau supérieurprofile = "name". Tous les paramètres de profil historiques doivent être migrés vers des fichiers séparés~/.codex/<name>.config.toml.

Migration de l'ancienne configuration vers un profil

Si votre précédentconfig.tomlressemblait à ceci :

Exemple

# Ancienne syntaxe (obsolète)
profile = "deep-review"

[profiles.deep-review]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

Vous devez le diviser en deux fichiers :

# 文件路径:~/.codex/config.toml(保留非 profile 部分)
# 注意:删除了 profile = "deep-review" 选择器
# 文件路径:~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

Après la migration, l'utilisation en ligne de commande d'originecodex --profile deep-reviewreste inchangée.


Surcharge ponctuelle en ligne de commande

Parfois, vous souhaitez simplement modifier temporairement un ou deux champs pour une seule tâche sans polluer les fichiers de configuration. Dans ce cas, vous pouvez utiliser des surcharges CLI :

Privilégiez les options dédiées

Si des paramètres officiels dédiés sont fournis (tels que--model),préférez l'option dédiée, pour une meilleure lisibilité :

Exemple

# Changer de modèle avec une option dédiée
codex --model gpt-5.4

Utiliser --config pour surcharger des clés arbitraires

Pour les champs sans options dédiées, utilisez-cou--configsurcharges. La valeur est au format TOML, pas JSON.

Exemple

# Les valeurs de chaîne doivent utiliser des guillemets doubles pour imbriquer des guillemets
codex --config model='"gpt-5.4"'

# Les valeurs booléennes s'écrivent directement
codex --config sandbox_workspace_write.network_access=true

# Les tableaux utilisent la syntaxe de tableau TOML
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Quelques règles propices aux pièges :

  • Utilisez la syntaxe point pour localiser les champs imbriqués, par ex.,mcp_servers.context7.enabled=false
  • --configLa valeur est analysée comme du TOML ; les chaînes contenant des espaces doivent être mises entre guillemets.
  • Si l'analyse échoue, Codex traite la valeur entière comme une chaîne.

Le moyen le plus rapide de savoir si une surcharge a pris effet est de faire suivre la commande d'une simple question : « quel modèle utilisez-vous ? », en laissant Codex indiquer la configuration actuelle.


Emplacements du fichier de configuration et de l'état

Codex stocke tout l'état local dansCODEX_HOMEle répertoire, par défaut~/.codex。

Fichiers courants et leur signification :

FichierObjectifSensible ?
config.tomlConfiguration principale locale ; toutes les personnalisations se font ici.non
auth.jsonIdentifiants basés sur des fichiers (si le trousseau du système n'est pas utilisé)Oui, permissions 600 recommandées
history.jsonlHistorique de conversation (peut être désactivé)Peut contenir du contenu sensible
logs/, caches/Journaux d'exécution et cachePeut contenir des fragments de corps de requête

Vous voulez simplement changer l’URL de base d’OpenAI ?

Beaucoup de personnes utilisent des proxys LLM, des routeurs ou des projets de résidence des données, et ont seulement besoin de modifieropenail’URL de base du fournisseur intégré.

Dans ce cas, définissez directementopenai_base_url, n’en créez pas un nouveau[model_providers.openai], car les identifiants intégrés ne peuvent pas être remplacés :

Exemple

# Chemin du fichier : ~/.codex/config.toml
# Faire pointer l’URL de base du fournisseur openai intégré vers le proxy
openai_base_url = "https://us.api.openai.com/v1"

Configuration au niveau du projet .codex/config.toml

La configuration au niveau du projet est placée à la racine du dépôt.codex/config.toml, utilisée pour les valeurs par défaut partagées par l’équipe.

Codex effectue une recherche vers le haut depuis le répertoire de travail,Le fichier le plus proche du répertoire de travail actuel a la priorité la plus élevée.。

Limites de la configuration au niveau du projet

Pour des raisons de sécurité,ce n’est que lorsque le projet est marqué comme « trusted »que la couche .codex/ au niveau du projet sera chargée (y compris config.toml, les hooks locaux et les règles locales).

Dans les projets non approuvés, les clés sensibles du tableau ci-dessous sont ignorées et un avertissement au démarrage est affiché :

Clé ignoréeRaison
openai_base_url、chatgpt_base_urlEmpêche la redirection des identifiants / la modification des métadonnées de l’hôte
apps_mcp_product_skuAffecte l’identification du produit Codex Apps
model_provider、model_providersEmpêche le remplacement des identifiants / de l’identité du fournisseur
notifyEmpêche l’exécution de commandes arbitraires sur la machine locale
profile、profilesAu niveau du projet, impossible de sélectionner un profil de configuration
experimental_realtime_ws_base_url、otelTélémétrie et canaux en temps réel

Ces clés doivent être placées dans le fichier utilisateur~/.codex/config.toml.

Les chemins relatifs (par ex.,model_instructions_file) sont résolus relativement à leur répertoire contenant.codex/.

Si le projet n'est pas approuvé et que vous définissezmodel_provider = "proxy", Codex affichera un avertissement au démarrage et utilisera le fournisseur par défaut ; il s'agit d'un choix de sécurité, pas d'un bug.


Hooks : hooks de cycle de vie

Les hooks vous permettent d'insérer des scripts personnalisés à des points clés tels que les appels d'outils, les débuts de round, etc., adaptés à l'audit, au filtrage de mots sensibles, aux vérifications de commit, et plus encore.

La configuration des hooks prend en charge deux formes, et la structure des événements est exactement la même :

FormEmplacementScénarios adaptés
hooks.jsonFichierMême répertoire que config.tomlCompatible avec la chaîne d'outils JSON, facile à réutiliser
En ligne[[hooks.*]]TableauDans config.tomlToute la configuration gérée de manière centralisée

Les quatre emplacements de chargement les plus couramment utilisés :

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

Les hooks au niveau du projet ne sont chargés que lorsque le projet est approuvé ; les hooks au niveau de l'utilisateur sont toujours chargés indépendamment.

Exemple de hook TOML en ligne

Ce qui suit est un hook de pré-vérification qui s'exécute avant les appels de l'outil Bash :

Exemple

# Chemin du fichier : ~/.codex/config.toml
# Correspond à tous les appels de l'outil Bash
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
# Invoquer le script de pré-vérification dans le dépôt (chemin relatif au répertoire où se trouve .codex/)
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30                                 # Délai d'attente en secondes ; après expiration, considérer comme rejeté
statusMessage = "Vérification de la commande Bash"      # Indication de la barre d'état

Si la même couche existe déjàhooks.jsonEn ligne existe aussi[hooks]Dans le tableau, Codex chargera les deux et affichera un avertissement.Il est recommandé de ne choisir qu'une seule forme par couche, afin d'éviter de doubler les coûts de maintenance.


Fournisseurs de modèles personnalisés

Lorsque vous devez connecter Codex à des points de terminaison officiels non-OpenAI tels que des proxys LLM, Ollama, Mistral, Azure, etc.,model_providersest l'entrée.

ID de fournisseur intégré (openai、ollama、lmstudio)Ne peut pas être réutilisésinon il y aura un conflit.

Définition de base

Exemple

# Chemin du fichier : ~/.codex/config.toml
model = "gpt-5.4"           # Le nom du modèle est déterminé par le fournisseur sélectionné
model_provider = "proxy"    # Pointe vers le [model_providers.proxy] suivant

[model_providers.proxy]
name = "OpenAI via un proxy LLM"  # Nom d'affichage
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"       # Lire le secret depuis la variable d'environnement

[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"

Ajout d'en-têtes HTTP

Certains proxys nécessitent des en-têtes supplémentaires (tels que l'identifiant de locataire, les indicateurs de fonctionnalité) :

Exemple

[model_providers.example]
# En-tête statique : envoyé à chaque requête
http_headers = { "X-Example-Header" = "example-value" }
# En-tête dynamique : valeur lue depuis une variable d'environnement
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Authentification basée sur une commande

Lorsque le jeton bearer du fournisseur doit être récupéré dynamiquement depuis un utilitaire d'identification externe, utilisez[model_providers.<id>.auth]:

Exemple

[model_providers.proxy]
name = "OpenAI utilisant un proxy LLM"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"   # Utiliser le protocole de l'API Responses

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000            # Délai d'expiration pour une seule récupération
refresh_interval_ms = 300000 # Intervalle de rafraîchissement actif (5 minutes)

Contraintes d'exécution pour la commande auth :

  • Ne reçoit passtdin, doit écrire le jeton surstdout
  • Codex supprime automatiquement les espaces en début et en fin, et un jeton vide est traité comme une erreur.
  • Paramètresrefresh_interval_ms = 0Indique un rafraîchissement uniquement après un échec d'authentification
  • Ne peut pas être utilisé avec env_key, experimental_bearer_token, requires_openai_auth

Fournisseur intégré Amazon Bedrock

Intégré à Codexamazon-bedrockPour les fournisseurs intégrés, vous pouvez directement utilisermodel_providerRéférence :

Exemple

# Chemin du fichier : ~/.codex/config.toml
model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"      # profil AWS ; s'il n'est pas défini, utilisez la chaîne d'informations d'identification standard
region = "eu-central-1"  # région Bedrock

Le fournisseur Bedrock intégré ne prend en charge que l'imbrication..awsles surcharges de profil et de région sous ... ; pour les autres éléments personnalisés, veuillez utiliser le processus standardmodel_providers.<id>.


Mode local OSS

Codex prend en charge la connexion à des modèles locaux « open source » (par ex., Ollama, LM Studio), via--ossDémarrer.

Si vous passez uniquement--ossSi aucun fournisseur n'est spécifié, Codex liraoss_providerSélectionner la valeur par défaut :

Exemple

# Chemin du fichier : ~/.codex/config.toml
# Fournisseur local par défaut ; en option : ollama ou lmstudio
oss_provider = "ollama"

Exemple d'utilisation :

Exemple

# Utiliser oss_provider par défaut (ollama)
codex --oss

# Spécifier explicitement que cette session utilise lmstudio
codex --oss --oss-provider lmstudio

Fournisseur Azure et réglage fin

Exemple d'intégration Azure OpenAI, démontrant les paramètres au niveau des requêtes et la stratégie de réessai :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"          # Lire la clé à partir de la variable d'environnement
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"                    # Utiliser le protocole de l'API Responses
request_max_retries = 4                   # Nombre de tentatives de réessai des requêtes normales
stream_max_retries = 10                   # Nombre de tentatives de réessai des requêtes en streaming
stream_idle_timeout_ms = 300000           # Délai d'inactivité du streaming (5 minutes)

Nécessite de modifier l'openai intégréLors de l'utilisation de l'URL de base du fournisseur, utilisezopenai_base_url, n'en créez pas un nouveau[model_providers.openai]。


Projets de résidence des données ChatGPT

Les projets ChatGPT avec "Data Residency" activé doivent utiliser une URL de base préfixée par une région :

Exemple

# Chemin du fichier : ~/.codex/config.toml
model_provider = "openaidr"

[model_providers.openaidr]
name = "OpenAI Data Residency"
# Remplacez "us" par le préfixe requis par la documentation sur la résidence des données (par ex., eu, jp, etc.)
base_url = "https://us.api.openai.com/v1"

Tous les modèles ne prennent pas en charge la résidence des données ; avant de choisir, consultez la liste des "modèles éligibles" dans la documentation OpenAI sur la résidence des données.


Raisonnement du modèle, verbosité et contexte

Le quatuor le plus courant pour contrôler le comportement du modèle :

Exemple

# Chemin du fichier : ~/.codex/config.toml
model_reasoning_summary = "none"          # Désactiver le résumé du raisonnement
model_verbosity = "low"                   # Raccourcir la longueur de la réponse
model_supports_reasoning_summaries = true # Forcer le modèle à produire un raisonnement
model_context_window = 128000             # Remplacer la taille de la fenêtre de contexte

oùmodel_verbosityne prend effet que sur les fournisseurs utilisant l’API Responses ; le fournisseur Chat Completions ignorera ce paramètre.


Politiques d’approbation et modes de bac à sable

approval_policyContrôle quand Codex s’arrête pour demander une confirmation humaine,sandbox_modeContrôle à quels fichiers et réseaux il peut accéder.

Les deux dimensions peuvent être combinées indépendamment ; vous trouverez ci-dessous un ensemble de configurations typiques :

Exemple

# Chemin du fichier : ~/.codex/config.toml
approval_policy = "untrusted"   # Autres options : on-request, never, ou { granular = { ... } }
approvals_reviewer = "user"     # "auto_review" passe par une revue automatique
sandbox_mode = "workspace-write"
allow_login_shell = false       # Désactiver le shell de connexion (durcissement)

# Exemple de politique d'approbation granulaire (distinguée par catégorie de prompt)
# approval_policy = { granular = {
# sandbox_approval = true,
# rules = true,
# mcp_elicitations = true,
# request_permissions = false, # les catégories request-permission échouent directement en mode fermé
# skill_approval = false # les catégories skill-script échouent directement en mode fermé
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Autoriser l'écriture dans $TMPDIR
exclude_slash_tmp = false       # Autoriser l'écriture dans /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]   # Répertoires inscriptibles supplémentaires
network_access = false          # Interdire l'accès au réseau externe par défaut

[auto_review]
policy = """
Utilisez la politique de révision automatique de votre organisation.
"
""
]

Référence rapide des combinaisons courantes

Scénariosapproval_policysandbox_modeDescription
Développement quotidien localon-requestworkspace-writeDemander confirmation avant chaque appel d'outil ; le plus sûr
Automatisation CIneverworkspace-writeAucune intervention humaine, doit être testé dans un bac à sable
Environnement entièrement fiableneverdanger-full-accessDésactiver le sandbox ; à utiliser uniquement dans des environnements isolés
Scénarios d'audit strictnon fiableworkspace-writeToutes les opérations d'écriture nécessitent une confirmation secondaire

Désactiver le sandbox (à utiliser avec prudence)

Lorsque votre environnement dispose déjà d'une isolation au niveau des processus, vous pouvez désactiver le sandbox Codex :

Exemple

# Chemin du fichier : ~/.codex/config.toml
sandbox_mode = "danger-full-access"

Dansworkspace-writemode, certains environnements vont.git/et.codex/Conserver en lecture seule. Cela signifie quegit commitDes commandes telles que ... nécessitent toujours une approbation lorsqu'elles sont exécutées en dehors du sandbox. Pour committer directement à l'intérieur du sandbox, utilisezrulesAutoriser explicitement.


Politique des variables d'environnement du shell

shell_environment_policyContrôle les variables d'environnement que Codex transmet lors du lancement de sous-processus.Cible par défautest "divulguer moins de secrets + préserver les chemins nécessaires à la tâche."

Exemple

# Chemin du fichier : ~/.codex/config.toml
[shell_environment_policy]
inherit = "none"                            # Démarrage propre (recommandé)
set = { PATH = "/usr/bin", MY_FLAG = "1" } # Définir explicitement les variables
ignore_default_excludes = false             # Conserver le filtrage KEY/SECRET/TOKEN par défaut
exclude = ["AWS_*", "AZURE_*"]              # Exclure en plus les variables correspondant aux globs
include_only = ["PATH", "HOME"]             # Ne transmettre que la liste blanche (remplace exclude)

Syntaxe des motifs : glob insensible à la casse,*Correspond à n'importe quel caractère,?Correspond à un seul caractère,[A-Z]Est une classe de caractères.

ignore_default_excludes = falseCela préservera les filtres KEY/SECRET/TOKEN intégrés de Codex, en prenant effet avant include/exclude.


Serveurs MCP

Les serveurs MCP (Model Context Protocol) permettent à Codex de se connecter à des ensembles d'outils externes.

Pour des instructions complètes de configuration MCP, consultez ladocumentation MCPofficielle, non développée dans cet article. Motifs courants :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true

# Désactiver temporairement un service MCP spécifique avec --config
# codex --config mcp_servers.context7.enabled=false

Observabilité et télémétrie (OTel)

Codex prend en charge l'exportation des journaux d'exécution via OpenTelemetry, désactivée par défaut. Comment l'activer :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[otel]
environment = "staging"   # dev par défaut
exporter = "none"         # Optionnel : otlp-http ou otlp-grpc
log_user_prompt = false   # Ne pas exporter le contenu du prompt utilisateur (recommandé)

Choisir un exportateur HTTP

Exemple

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

Choisir un exportateur gRPC

Exemple

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

Types d'événements exportés

Codex émet des événements structurés, y compris, mais sans s'y limiter :

ÉvénementsSignification
codex.conversation_startsModèle, paramètres de raisonnement, politique de sandbox/approbation
codex.api_requestTentatives de requête API, statut, durée, erreurs
codex.sse_eventÉvénements de flux SSE, nombre de tokens (sur response.completed)
codex.websocket_request、codex.websocket_eventRequêtes et messages WebSocket
codex.user_promptLongueur du prompt utilisateur ; le contenu est masqué par défaut.
codex.tool_decisionDécisions d'appel d'outil : approuver/rejeter, selon que la source est la configuration ou l'utilisateur
codex.tool_resultDurée d'exécution de l'outil, succès/échec, extraits de sortie

Lorsqueexporter = "none"Lorsque ..., Codex enregistre toujours les événements en mémoire mais ne les envoie pas.Lorsqu'il est fermé, il déclenche toujours un lot asynchrone par événement, flush à la sortie du processus.

Métriques anonymes (activées par défaut)

Par défaut, Codex signale périodiquement une petite quantité de données d'utilisation et de santé anonymes pour détecter les anomalies.Ne contient pas de PII。

Pour désactiver complètement :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[analytics]
enabled = false

Masquage et affichage des événements de raisonnement

Dans les journaux CI, la sortie de raisonnement est souvent « bruyante » et peut être désactivée globalement :

Exemple

# Chemin du fichier : ~/.codex/config.toml
hide_agent_reasoning = true

Inversement, lorsque vous avez besoin de consulter le contenu de raisonnement brut du modèle :

Exemple

# Chemin du fichier : ~/.codex/config.toml
show_raw_agent_reasoning = true

Ne l'activez que lorsque vous avez confirmé que votre flux de travail permet d'exposer le raisonnement brut. Certains modèles (commegpt-oss) ne génèrent pas eux-mêmes de raisonnement brut ; dans ce cas, ce paramètre n'a aucun effet.


Notifications externes (notify)

Lorsque Codex termine un tour, il peut déclencher des scripts externes pour implémenter des notifications de bureau, des webhooks de chat, des mises à jour de statut CI, etc.

Exemple

# Chemin du fichier : ~/.codex/config.toml
notify = ["python3", "/path/to/notify.py"]

Le script reçoit un argument JSON ; champs courants :

FieldsSignification
typeActuellement, uniquementagent-turn-complete
thread-idID de session
turn-idID de tour
cwdRépertoire de travail
input-messagesListe des messages utilisateur
last-assistant-messageLe dernier message de l'assistant

Un exemple simple de script qui appelle terminal-notifier :

Exemple

# Chemin du fichier : /path/to/notify.py
#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    # Ne gérer que les événements de fin de tour
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Tour terminé !')}"
    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())

Différence entre notify et tui.notifications

MécanismeScénarios adaptésConfiguration des clés
notifywebhooks, notifications de bureau, hooks CIProgramme externe
tui.notificationsNotifications intégrées de TUIPrend en charge le filtrage par type d'événement
tui.notification_methodMéthode de notification du terminalauto / osc9 / bel
tui.notification_conditionCondition de déclenchementunfocused / always

autoDans ce mode, Codex préfère la séquence d'échappement de terminal OSC 9 ; certains terminaux la traitent comme une notification de bureau ; lorsqu'elle n'est pas prise en charge, il revient à BEL (\x07)。


Retour d'information et historique

Désactiver la collecte des retours d'information

Par défaut, Codex est fourni dans la TUI./feedbackcommande. Pour désactiver :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[feedback]
enabled = false

Après la fermeture,/feedbackaffichera un message de désactivation, et Codex refuse d'envoyer des commentaires.

Enregistrements d'historique (history.jsonl)

Par défaut, Codex écrit les transcriptions de session locales dans~/.codex/history.jsonlComment désactiver :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[history]
persistence = "none"

Limite la taille du fichier (en cas de dépassement, supprime les entrées les plus anciennes et compresse) :

Exemple

# Chemin du fichier : ~/.codex/config.toml
[history]
max_bytes = 104857600  # 100 MiB

Citations cliquables

Lorsque le terminal ou l'éditeur le prend en charge, Codex peut afficher les références de fichiers sous forme de liens cliquables.

Exemple

# Chemin du fichier : ~/.codex/config.toml
# Facultatif : vscode, cursor, windsurf, vscode-insiders, none
file_opener = "vscode"

Après la configuration, la référence/home/example/project/main.py:42sera réécrite sous la formevscode://file/.../main.py:42, et un clic dans VS Code vous amènera à cet emplacement.


Découverte des instructions du projet (AGENTS.md)

Codex liraAGENTS.md(et les fichiers associés), et intégrera automatiquement les conventions du projet dans le « premier tour » de la session.

Deux paramètres essentiels :

Clé de configurationFonctionValeurs typiques
project_doc_max_bytesNombre maximal d'octets lus par AGENTS.mdPar défaut, environ 32 KiB
project_doc_fallback_filenamesNom de fichier de secours lorsque AGENTS.md est absentPar exempleCLAUDE.md

Options de l'interface utilisateur de terminal (TUI)

ExécutercodexL'exécution sans sous-commande entre dans l'interface TUI interactive.[tui]Touches courantes sous le tableau :

ToucheFonctionValeurs facultatives
tui.notificationsActiver/désactiver les notifications de l'interface TUI ; possibilité de filtrer par type d'événementBooléen / tableau de types d'événements
tui.notification_methodMéthode de notification du terminalauto、osc9、bel
tui.notification_conditionCondition de déclenchementunfocused、always
tui.animationsAnimations ASCII et effets de scintillementtrue / false
tui.alternate_screenIndique s'il faut utiliser l'écran alternatif (définir sur never pour conserver l'historique de défilement)auto、always、never
tui.show_tooltipsIndique si la page d'accueil affiche des conseils pour débutantstrue / false

Tableau de référence rapide des configurations courantes

Considérez cette section comme une liste de référence rapide « à consulter en cas d'oubli » :

ExigencesEmplacement / commande de configuration
Changer de modèle--model gpt-5.4oumodel = "..."
Configuration basée sur des scénarios--profile <name> + ~/.codex/<name>.config.toml
Modifier temporairement n'importe quel champ--config key=value(syntaxe TOML)
Modifier le point de terminaison OpenAIopenai_base_url
Connecter un proxy/fournisseur auto-construit[model_providers.<id>] + model_provider
Ollama local--oss + oss_provider
Désactiver le bac à sable (à utiliser avec prudence)sandbox_mode = "danger-full-access"
Désactiver les métriques anonymes[analytics] enabled = false
Désactiver l'historique[history] persistence = "none"
Désactiver le retour d'information[feedback] enabled = false
Notifications de bureaunotify = ["python3", "/path/to/notify.py"]

Questions fréquentes

Le model_provider défini dans la configuration au niveau du projet n'est pas pris en compte ?

Pour des raisons de sécurité,model_provider、model_providers、profile、notifyet d'autres clés sensiblesSeront ignorés dans le .codex/config.tomlau niveau du projet, et affiche un avertissement au démarrage.

Déplacez ces clés au niveau utilisateur~/.codex/config.tomlUniquement dans celui-ci.

Les modifications écrites avec --config n'ont aucun effet ?

Vérifiez trois choses : si la valeur respecte la syntaxe TOML (les tableaux utilisent[], les chaînes utilisent"", l'imbrication utilise des points) ; si le shell a séparé plusieurs valeurs en traitant les espaces comme séparateurs ; si les noms de clés sont correctement orthographiés. Ouvrez~/.codex/logs/Dans les derniers journaux, vous pouvez voir la chaîne d'origine qui n'a pas pu être analysée.

Toujours le modèle par défaut après un lancement avec un Profile ?

Cause la plus fréquente : le fichier Profile utilise encore l'ancienne[profiles.<name>]table, ou le suffixe du nom de fichier n'est pas.config.toml. À partir de 0.134.0, seul ... est reconnu~/.codex/<name>.config.tomlformat.

Pourquoi git commit est-il encore soumis à approbation après la désactivation du sandbox ?

Fermersandbox_moden'affecte pas la politique d'approbation.git commitet d'autres commandes peuvent encore, carapproval_policy = "on-request"et déclenche une invite ; si vous voulez des "commits entièrement automatiques", vous devez aussi définir la politique d'approbation surnever。

Les modèles personnalisés peuvent-ils sélectionner la série gpt-5 ?

Cela dépend debase_urlsi le service vers lequel il pointe le prend en charge. Codex lui-même ne valide pas strictement le champmodel; l'essentiel est de savoir si votre côté fournisseur peut le reconnaître et y répondre.

autres extensions