Principes de base de la configuration

Codex lit les informations de configuration à plusieurs emplacements. Vos valeurs personnelles par défaut se trouvent dans ~/.codex/config.toml, et vous pouvez ajouter des remplacements propres à un projet à l’aide de fichiers .codex/config.toml. Par mesure de sécurité, Codex ne charge les couches .codex/ du projet que si vous faites confiance au projet.

Fichier de configuration de Codex

Codex stocke la configuration utilisateur dans ~/.codex/config.toml. Pour limiter des paramètres à un projet ou sous-dossier précis, ajoutez un fichier .codex/config.toml dans votre dépôt.

Pour ouvrir le fichier de configuration depuis l’extension Codex pour IDE, sélectionnez l’icône d’engrenage dans l’angle supérieur droit, puis Codex Settings > Open config.toml.

La CLI et l’extension IDE partagent les mêmes couches de configuration. Vous pouvez les utiliser pour :

• Définir le modèle et le fournisseur par défaut.
• Configurer les politiques d’approbation et les paramètres du bac à sable.
• Configurer les serveurs MCP.

Ordre de priorité de la configuration

Codex résout les valeurs dans l’ordre suivant (de la priorité la plus élevée à la plus faible) :

1. Options de la CLI et remplacements --config
2. Fichiers de configuration du projet : .codex/config.toml, classés depuis la racine du projet jusqu’à votre répertoire de travail actuel (le plus proche l’emporte ; projets approuvés uniquement)
3. Fichiers de profil sélectionnés avec --profile profile-name (~/.codex/profile-name.config.toml)
4. Configuration utilisateur : ~/.codex/config.toml
5. Configuration système (si elle existe) : /etc/codex/config.toml sous Unix
6. Valeurs par défaut intégrées

Utilisez cet ordre de priorité pour définir les valeurs par défaut partagées dans config.toml et limiter les fichiers de profil aux valeurs qui diffèrent.

Si vous marquez un projet comme non approuvé, Codex ignore les couches .codex/ propres au projet, notamment la configuration, les hooks et les règles locales au projet. Les configurations utilisateur et système restent chargées, y compris les hooks et règles utilisateur ou globaux.

Pour les remplacements ponctuels au moyen de -c/--config (y compris les règles relatives aux guillemets TOML), consultez la configuration avancée.

Options de configuration courantes

Voici quelques-unes des options les plus souvent modifiées :

Modèle par défaut

Choisissez le modèle que Codex utilise par défaut dans la CLI et l’IDE.

model = "gpt-5.6"

Demandes d’approbation

Déterminez quand Codex se met en pause pour demander votre autorisation avant d’exécuter les commandes générées.

approval_policy = "on-request"

Pour connaître les différences de comportement entre untrusted, on-request et never, consultez Exécuter sans demandes d’approbation et Combinaisons courantes de bac à sable et d’approbation.

Niveau du bac à sable

Ajustez le niveau d’accès au système de fichiers et au réseau dont dispose Codex lors de l’exécution de commandes.

sandbox_mode = "workspace-write"

Pour connaître le comportement de chaque mode (y compris les chemins .git/.codex protégés et les valeurs réseau par défaut), consultez Bac à sable et approbations, Chemins protégés dans les racines accessibles en écriture et Accès réseau.

Profils d’autorisation

Codex prend également en charge des profils d’autorisation nommés afin de réutiliser les politiques relatives au système de fichiers et au réseau. Les profils intégrés sont :read-only, :workspace et :danger-full-access. Les profils personnalisés utilisent des tables [permissions.<name>] et une valeur default_permissions correspondante. Consultez Autorisations.

Mode bac à sable de Windows

Lorsque vous exécutez Codex nativement sous Windows, définissez le mode de bac à sable natif sur elevated dans la table windows. Utilisez unelevated uniquement si vous ne disposez pas des droits d’administrateur ou si la configuration avec élévation des privilèges échoue.

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

Mode de recherche web

Codex active par défaut la recherche web pour les chats locaux et fournit les résultats depuis un cache de recherche web. Ce cache est un index de résultats web géré par OpenAI : le mode mis en cache renvoie donc des résultats préindexés au lieu de récupérer les pages en direct. Cela réduit l’exposition aux injections de requête provenant de contenus en direct arbitraires, mais vous devez tout de même considérer les résultats web comme non fiables. Si vous utilisez --yolo ou un autre paramètre de bac à sable avec accès complet, la recherche web utilise par défaut des résultats en direct. Choisissez un mode avec web_search :

• "cached" (par défaut) fournit les résultats depuis le cache de recherche web.
• "indexed" autorise l’accès externe au web uniquement lorsque l’index de recherche valide la requête.
• "live" récupère les données les plus récentes sur le web (équivaut à --search).
• "disabled" désactive l’outil de recherche web.

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Effort de raisonnement

Ajustez l’effort de raisonnement appliqué par le modèle lorsqu’il prend ce réglage en charge.

model_reasoning_effort = "high"

Style de communication

Définissez un style de communication par défaut pour les modèles compatibles.

personality = "friendly" # or "pragmatic" or "none"

Vous pouvez remplacer ce réglage ultérieurement dans une session active avec /personality, ou pour chaque fil/tour lorsque vous utilisez les API app-server.

Mappage des touches de la TUI

Personnalisez les raccourcis du terminal sous tui.keymap. Certaines actions du composeur se rabattent sur les liaisons tui.keymap.global correspondantes ; les liaisons propres au contexte sont prioritaires lorsqu’elles sont prises en charge. Une liste vide supprime la liaison de l’action.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

Environnement des commandes

Contrôlez les variables d’environnement que Codex transmet aux commandes générées. Utilisez des filtres à clés pour ne conserver que les variables dont vous avez besoin :

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

La valeur par défaut de ignore_default_excludes est true, ce qui désactive le filtrage automatique des noms de variables contenant KEY, SECRET ou TOKEN. Définissez-la sur false si vous souhaitez appliquer ce filtrage automatique. Pour en savoir plus sur les règles d’exclusion, leur ordre de priorité et la configuration héritée, consultez la politique d’environnement shell.

Répertoire des journaux

Remplacez l’emplacement dans lequel Codex écrit les fichiers journaux locaux. Définir explicitement log_dir active également le journal TUI facultatif en texte brut, codex-tui.log, dans ce répertoire.

log_dir = "/absolute/path/to/codex-logs"

Pour une exécution ponctuelle, vous pouvez également le définir depuis la CLI :

codex -c log_dir=./.codex-log

Indicateurs de fonctionnalité

Utilisez la table [features] dans config.toml pour activer ou désactiver des fonctionnalités facultatives et expérimentales.

Indicateurs de fonctionnalité courants

Pour configurer les hooks de cycle de vie, consultez Hooks.

Activation des fonctionnalités

• Dans config.toml, ajoutez feature_name = true sous [features].
• Depuis la CLI, exécutez codex --enable feature_name.
• Pour activer plusieurs fonctionnalités, exécutez codex --enable feature_a --enable feature_b.
• Pour désactiver une fonctionnalité, définissez la clé sur false dans config.toml.