Configuration et personnalisation de Codex

Codex offre un riche ensemble d'options de configuration, vous permettant de personnaliser le comportement de l'Agent pour l'adapter à différents besoins de travail.

Par défaut, l'application Codex utilise la langue de vos paramètres système. Si ce n'est pas le cas, vous pouvez utiliser Paramètres :

Sélectionnez Général pour modifier la langue souhaitée dans les options Général :

De même, pour passer du chinois à l’anglais, il suffit de cocher Anglais :


Réglages de l’application Codex

Comment l’ouvrir : cliquez sur Réglages dans le menu de l’application, ou appuyez surCmd + ,:

L’interface des réglages est présentée ci-dessous :

Général :La manière d’ouvrir les fichiers de configuration, et la quantité d’affichage de la sortie des commandes dans le fil de conversation. Vous pouvez aussi configurer les prompts multilignes pour exiger une confirmation par Cmd+Entrée, et empêcher le système de se mettre en veille pendant l’exécution des tâches.

Notifications :Définissez le moment de déclenchement des notifications de fin de tâche, et si l’application demande proactivement l’autorisation de notification système.

Configuration de l’agent (Agent Configuration) :L’agent Codex dans l’application partage la même configuration que les extensions IDE et CLI. Les options courantes peuvent être ajustées directement dans l’application, tandis que les options avancées nécessitent de modifier le fichier config.toml (décrit plus tard).

Apparence :Prend en charge la sélection d’un thème de base, le réglage de la couleur d’accentuation, de la couleur d’arrière-plan et de la couleur de premier plan, ainsi que la modification de la police de l’interface et de la police du code. Vous pouvez partager des thèmes personnalisés avec d’autres personnes.

Animaux Codex (Codex Pets) :Personnages compagnons dynamiques facultatifs, chemin :Réglages > Apparence > AnimauxVous pouvez sélectionner des animaux intégrés ou charger des animaux personnalisés depuis le répertoire local Codex home.

Méthode d’utilisation :

  • Saisissez dans la zone de saisie/pet
  • utilisezRéglages > ApparencedansRéveiller l’animalouRanger l’animal
  • appuyezCmd+K / Ctrl+Kpuis exécutez la commande du même nom

La fenêtre flottante de la mascotte peut afficher en continu l’état de travail actuel de Codex (En cours d’exécution / En attente de saisie / En attente de révision) pendant que vous utilisez d’autres applications, et inclut une brève indication de progression.

Mascottes personnalisées (processus de création) :

$skill-installer hatch-pet

Après l’installation, sélectionnez dans le menu des commandesForce Reload Skills, puis exécutez :

$hatch-pet create a new pet inspired by my recent projects

Git: Unifiez les conventions de nommage des branches, configurez si le push forcé doit être activé, et définissez le texte du prompt utilisé lorsque Codex génère automatiquement les messages de commit et les descriptions de PR.

Environnement :Vous pouvez consulter les répertoires de projets et ajouter des projets.

Arbre de travail :Utilisez Git worktree pour permettre à Codex de gérer plusieurs tâches en parallèle au sein du même projet.

Utilisation du navigateur :Installez ou activez le plugin Browser intégré pour gérer les listes blanches et noires de sites web. Par défaut, Codex demande à l’utilisateur avant d’utiliser un site web ; après avoir retiré un site de la liste noire, Codex reprendra le comportement de demande. Consultez la documentation du navigateur intégré à l’application pour plus de détails.

Utilisation de l’ordinateur :macOS uniquement. Vous pouvez consulter les autorisations d’accès des applications de bureau et les préférences associées. Pour révoquer les autorisations au niveau système, accédez à Confidentialité et sécurité de macOS et modifiez les autorisations d’Enregistrement de l’écran ou d’Accessibilité.

Fils archivés :

Liste toutes les conversations archivées, en affichant la date et le contexte du projet. Cliquez sur Désarchiver pour restaurer un fil spécifique.


Emplacement du fichier de configuration

Les fichiers de configuration Codex sont gérés en couches :

NiveauCheminPortée
Niveau utilisateur~/.codex/config.tomlConfiguration globale par défaut
Niveau projet.codex/config.tomlConfiguration spécifique au projet
Niveau géréDistribution d'entrepriseConfiguration unifiée d'entreprise

Règles de fusion de configuration

La configuration est fusionnée par priorité :

  • La configuration gérée a la priorité la plus élevée
  • La configuration du projet remplace la configuration utilisateur
  • La configuration utilisateur sert de valeur par défaut

Éléments de configuration de base

Configuration de base

# ~/.codex/config.toml

# Modèle par défaut
model = "gpt-5.4"

# Effort de raisonnement
model_reasoning_effort = "medium" # minimal | low | medium | high | xhigh

# Niveau de détail du résumé de raisonnement
model_reasoning_summary = "auto" # auto | concise | detailed | none

# Niveau de service
service_tier = "flex" # flex | fast

# Politique d'approbation
approval_policy = "suggest" # suggest | auto-edit | full-auto

AGENTS.md

AGENTS.md est un fichier d'instructions Agent au niveau du projet qui définit les spécifications de comportement de Codex dans ce projet.

Ordre de découverte des fichiers

  1. Lire le fichier global~/.codex/AGENTS.md
  2. Rechercher dans chaque répertoire en descendant depuis la racine du projet
  3. Les règles des répertoires plus proches ont priorité sur celles des répertoires plus éloignés

Exemple d’AGENTS.md

AGENTS.md du projet

# Normes de développement du projet

## Stack technique
- Frontend : React + TypeScript
- Backend : Python FastAPI
- Base de données : PostgreSQL

## Normes de code
- Utiliser une indentation de 4 espaces
- Maximum 100 caractères par ligne
- Toutes les fonctions doivent avoir des annotations de type

## Exigences de tests
- Les nouvelles fonctionnalités doivent inclure des tests
- Exécuter les tests avec pytest

## Commits Git
- Utiliser le format Conventional Commits
- Les messages de commit décrivent le « pourquoi »

## Directives de revue
- Ne pas journaliser les PII
- Vérifier le middleware d'authentification
- Vérifier les injections SQL

Surcharge de sous-répertoire

Vous pouvez placer AGENTS.override.md dans un sous-répertoire :

Règles de sous-répertoire

# src/auth/ Règles du module

## Exigences de sécurité
- Tous les mots de passe doivent être hachés avec bcrypt
- Ajouter des journaux d’audit
- Vérifier les injections SQL

AGENTS.md est limité à 32 KiB ; tout contenu plus volumineux sera tronqué.


Compétences

Les compétences sont des capacités personnalisées réutilisables qui encapsulent la logique des tâches courantes.

Emplacement du répertoire des compétences

EmplacementCheminObjectif
REPO.agents/skills/Compétences au niveau du projet
USER~/.agents/skills/Compétences au niveau de l’utilisateur
ADMIN/etc/codex/skills/Compétences au niveau du système
SYSTÈMEIntégréCompétences prédéfinies officielles

Structure des compétences

skill-name/
├── SKILL.md       # 技能定义(必需)
├── scripts/       # 可选脚本
├── references/    # 可选参考文档
└── assets/        # 可选资源

Création de compétences

Définition de compétence

---
name: code-review-standard
description: Effectuer une revue de code selon les normes de l'équipe
---

# Normes de revue de code

## Éléments à examiner
1. Lisibilité du code
2. Bogues potentiels
3. Vulnérabilités de sécurité
4. Problèmes de performance
5. Couverture des tests

## Format de sortie
Liste des problèmes (par gravité)
Suggestions d'amélioration
Note (1-10)

Déclenchement des compétences

Méthodes de déclenchementExemples
Invocation explicite$skill-nameou/skill-name
Correspondance impliciteLa description de la tâche correspond à la description de la compétence

Sous-agents

Les sous-agents permettent de diviser des tâches complexes et de les traiter en parallèle par plusieurs agents.

Types d'agents intégrés

AgentFonction
defaultAgent polyvalent
workerOrienté exécution, adapté à l'implémentation et aux corrections
explorerOrienté exploration, adapté à l'analyse de base de code

Configuration des sous-agents

Configuration du sous-agent

# ~/.codex/config.toml

[agents]
# Nombre maximal de threads parallèles
max_threads = 6

# Profondeur maximale d'imbrication
max_depth = 1

# Délai d'expiration d'une tâche unique
job_max_runtime_seconds = 1800

Agents personnalisés

Agents personnalisés

# ~/.codex/agents/reviewer.toml

name = "reviewer"
description = "Axé sur la revue de code et les problèmes de qualité"
nickname_candidates = ["Reviewer", "QualityBot"]

developer_instructions = """
Concentrez-vous sur la revue de la qualité du code :
- Vérifier la cohérence du style de code
- Découvrir les bogues potentiels
- Évaluer la couverture des tests
"""

Règles

Les règles définissent des politiques d'exécution des commandes, contrôlant quelles commandes peuvent être exécutées automatiquement.

Fichier de règles

Les règles utilisent le langage Starlark (similaire à Python) :

Définition de règle

# ~/.codex/rules/default.rules

# Autoriser les commandes Git
prefix_rule(
    pattern = ["git"],
    decision = "allow",
    justification = "Les commandes Git sont sûres"
)

# Interdire rm -rf /
prefix_rule(
    pattern = ["rm", "-rf", "/"],
    decision = "forbidden",
    justification = "Éviter d'endommager le système"
)

# Demander à propos des commandes npm
prefix_rule(
    pattern = ["npm"],
    decision = "prompt",
    justification = "npm peut modifier les dépendances"
)

Types de décision

DécisionComportement
allowApprobation automatique
promptDemander confirmation
forbiddenExécuter

Hooks

Les hooks exécutent des scripts personnalisés sur des événements spécifiques.

Activation des hooks

Activation des hooks

[features]
codex_hooks = true

Événements de hook

ÉvénementMoment du déclenchement
SessionStartDémarrage de session
PreToolUseAvant l'invocation d'outil
PostToolUseAprès l'invocation d'outil

Configuration du hook

Configuration du hook

{
  "hooks": [
    {
      "event": "PostToolUse",
      "matcher": {
        "toolName": "Bash"
      },
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Command executed'",
          "timeout": 10
        }
      ]
    }
  ]
}

FAQ

Q : Comment les modifications de configuration prennent-elles effet ?

Après avoir modifié la configuration, vous devez redémarrer Codex pour que cela prenne effet.

Q : Où AGENTS.md doit-il être placé ?

Dans le répertoire racine du projet, ou dans les sous-répertoires qui nécessitent des règles spéciales.

Q : Quelle est la différence entre Skills et Rules ?

Les Skills définissent la logique d'exécution des tâches, les Rules contrôlent les permissions des commandes.

Q : Comment afficher la configuration actuelle ?

Utiliser/statuscommande pour afficher la configuration actuelle.

Autres extensions