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.
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
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
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
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
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
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 :
| Fichier | Objectif | Sensible ? |
|---|---|---|
| config.toml | Configuration principale locale ; toutes les personnalisations se font ici. | non |
| auth.json | Identifiants basés sur des fichiers (si le trousseau du système n'est pas utilisé) | Oui, permissions 600 recommandées |
| history.jsonl | Historique de conversation (peut être désactivé) | Peut contenir du contenu sensible |
| logs/, caches/ | Journaux d'exécution et cache | Peut 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
# 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ée | Raison |
|---|---|
| openai_base_url、chatgpt_base_url | Empêche la redirection des identifiants / la modification des métadonnées de l’hôte |
| apps_mcp_product_sku | Affecte l’identification du produit Codex Apps |
| model_provider、model_providers | Empêche le remplacement des identifiants / de l’identité du fournisseur |
| notify | Empêche l’exécution de commandes arbitraires sur la machine locale |
| profile、profiles | Au niveau du projet, impossible de sélectionner un profil de configuration |
| experimental_realtime_ws_base_url、otel | Té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 :
| Form | Emplacement | Scénarios adaptés |
|---|---|---|
| hooks.jsonFichier | Même répertoire que config.toml | Compatible avec la chaîne d'outils JSON, facile à réutiliser |
| En ligne[[hooks.*]]Tableau | Dans config.toml | Toute 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
# 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
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
# 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
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
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
# Fournisseur local par défaut ; en option : ollama ou lmstudio
oss_provider = "ollama"
Exemple d'utilisation :
Exemple
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
[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
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
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
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énarios | approval_policy | sandbox_mode | Description |
|---|---|---|---|
| Développement quotidien local | on-request | workspace-write | Demander confirmation avant chaque appel d'outil ; le plus sûr |
| Automatisation CI | never | workspace-write | Aucune intervention humaine, doit être testé dans un bac à sable |
| Environnement entièrement fiable | never | danger-full-access | Désactiver le sandbox ; à utiliser uniquement dans des environnements isolés |
| Scénarios d'audit strict | non fiable | workspace-write | Toutes 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
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
[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
[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
[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
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
protocol = "binary",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
Choisir un exportateur gRPC
Exemple
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énements | Signification |
|---|---|
| codex.conversation_starts | Modèle, paramètres de raisonnement, politique de sandbox/approbation |
| codex.api_request | Tentatives 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_event | Requêtes et messages WebSocket |
| codex.user_prompt | Longueur du prompt utilisateur ; le contenu est masqué par défaut. |
| codex.tool_decision | Décisions d'appel d'outil : approuver/rejeter, selon que la source est la configuration ou l'utilisateur |
| codex.tool_result | Duré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
[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
hide_agent_reasoning = true
Inversement, lorsque vous avez besoin de consulter le contenu de raisonnement brut du modèle :
Exemple
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
notify = ["python3", "/path/to/notify.py"]
Le script reçoit un argument JSON ; champs courants :
| Fields | Signification |
|---|---|
| type | Actuellement, uniquementagent-turn-complete |
| thread-id | ID de session |
| turn-id | ID de tour |
| cwd | Répertoire de travail |
| input-messages | Liste des messages utilisateur |
| last-assistant-message | Le dernier message de l'assistant |
Un exemple simple de script qui appelle terminal-notifier :
Exemple
#!/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écanisme | Scénarios adaptés | Configuration des clés |
|---|---|---|
| notify | webhooks, notifications de bureau, hooks CI | Programme externe |
| tui.notifications | Notifications intégrées de TUI | Prend en charge le filtrage par type d'événement |
| tui.notification_method | Méthode de notification du terminal | auto / osc9 / bel |
| tui.notification_condition | Condition de déclenchement | unfocused / 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
[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
[history]
persistence = "none"
Limite la taille du fichier (en cas de dépassement, supprime les entrées les plus anciennes et compresse) :
Exemple
[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
# 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 configuration | Fonction | Valeurs typiques |
|---|---|---|
| project_doc_max_bytes | Nombre maximal d'octets lus par AGENTS.md | Par défaut, environ 32 KiB |
| project_doc_fallback_filenames | Nom de fichier de secours lorsque AGENTS.md est absent | Par 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 :
| Touche | Fonction | Valeurs facultatives |
|---|---|---|
| tui.notifications | Activer/désactiver les notifications de l'interface TUI ; possibilité de filtrer par type d'événement | Booléen / tableau de types d'événements |
| tui.notification_method | Méthode de notification du terminal | auto、osc9、bel |
| tui.notification_condition | Condition de déclenchement | unfocused、always |
| tui.animations | Animations ASCII et effets de scintillement | true / false |
| tui.alternate_screen | Indique s'il faut utiliser l'écran alternatif (définir sur never pour conserver l'historique de défilement) | auto、always、never |
| tui.show_tooltips | Indique si la page d'accueil affiche des conseils pour débutants | true / 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 » :
| Exigences | Emplacement / 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 OpenAI | openai_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 bureau | notify = ["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