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 MCP servers.

Ordre de priorité de la configuration

Les exigences encadrent le comportement ; les valeurs de configuration fournissent les réglages par défaut. L’accès à l’ordinateur local avec Work Cloud respecte les exigences suivantes :

• Entre les politiques : Une politique de priorité supérieure l’emporte sur une politique de priorité inférieure, même si cette dernière est plus spécifique.
• Au sein d’une même politique : Les dérogations d’environnement propres à un système d’exploitation priment sur celles qui s’appliquent à tous les systèmes d’exploitation, puis viennent les paramètres Global.
• Pour l’exécution locale : Les exigences MDM et les anciennes exigences de gestion des appareils ont priorité sur Agent Security. Le fichier d’exigences système de l’appareil a une priorité inférieure à Agent Security.
• Pour Work Cloud : Les conteneurs cloud de Work conservent les politiques Work Cloud existantes. Pour Work avec accès local et dots, la politique Global prise en charge régit l’orchestrateur cloud partagé lorsque la politique gérée est activée ; les exigences d’exécution locale applicables régissent l’ordinateur connecté.

Certaines exigences comportent des règles de fusion propres à chaque champ. Consultez Configuration gérée pour connaître la portée des politiques et les limites d’exécution, ainsi que la Référence de configuration pour la compatibilité avec Work.

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 valeurs de remplacement --config
2. Fichiers de configuration du projet : .codex/config.toml, dans l’ordre de la racine du projet jusqu’à votre répertoire de travail actuel (le plus proche l’emporte ; uniquement pour les projets de confiance)
3. Fichiers de profil sélectionnés avec --profile profile-name (~/.codex/profile-name.config.toml)
4. Configuration utilisateur : ~/.codex/config.toml
5. Valeurs par défaut config.toml gérées dans le cloud, lorsqu’elles sont fournies pour l’espace de travail auquel vous êtes connecté
6. Configuration système (si présente) : /etc/codex/config.toml sous Unix
7. 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.

La configuration gérée dans le cloud et la configuration système peuvent définir des places de marché de plugins et préciser si les plugins sont activés par défaut. Elles sont distinctes des politiques requirements.toml imposées. Consultez Configurer les places de marché de plugins et les valeurs par défaut.

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-6.1-sol"

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 on-request et never, consultez Exécuter sans demandes d’approbation et Combinaisons courantes de sandbox et d’approbation. Si une configuration existante utilise approval_policy = "untrusted", consultez Migrer depuis la politique d’approbation untrusted supprimée.

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 protégés .git, .agents, .codex et .aws, ainsi que les paramètres réseau par défaut), consultez Sandbox 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

Sous Windows, privilégiez MXC lorsque l’appareil et la politique en vigueur le permettent. Définissez une implémentation historique comme solution de repli :

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

Utilisez unelevated uniquement lorsque la configuration avec élévation des privilèges n’est pas disponible et que la politique de votre organisation l’autorise. Consultez le guide de la sandbox Windows pour connaître les limites de compatibilité et les paramètres de contrôle du déploiement.

Mode de recherche web

Codex active la recherche web par défaut pour les conversations locales et fournit des résultats issus d’un cache de recherche web. Ce cache est un index de résultats web tenu à jour 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 prompt provenant de contenus en ligne quelconques. Considérez les résultats web comme non fiables. Si vous utilisez --yolo ou un autre réglage de sandbox avec accès complet, la recherche web utilise par défaut les 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 = "medium"

Style de communication

Pour omettre les instructions de personnalité intégrées, définissez :

personality = "none"

Cela supprime la section Personality des instructions intégrées du modèle. Les instructions de base personnalisées explicites restent inchangées. Les anciennes valeurs friendly et pragmatic ne permettent plus de sélectionner un style. Codex ne propose plus la commande /personality.

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.