Règles

Utilisez des règles pour contrôler les commandes que Codex peut exécuter en dehors du bac à sable.

Créer un fichier de règles

1. Créez un fichier .rules dans un dossier rules/ à côté d’une couche de configuration active (par exemple, ~/.codex/rules/default.rules).
2. Ajoutez une règle. Dans cet exemple, une confirmation est demandée avant d’autoriser l’exécution de gh pr view en dehors du bac à sable.

   # Prompt before running commands with the prefix `gh pr view` outside the sandbox.
   prefix_rule(
       # The prefix to match.
       pattern = ["gh", "pr", "view"],

       # The action to take when Codex requests to run a matching command.
       decision = "prompt",

       # Optional rationale for why this rule exists.
       justification = "Viewing PRs is allowed with approval",

       # `match` and `not_match` are optional "inline unit tests" where you can
       # provide examples of commands that should (or should not) match this rule.
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
           "gh pr view 7888 --json title,body,comments",
       ],
       not_match = [
           # Does not match because the `pattern` must be an exact prefix.
           "gh pr --repo openai/codex view 7888",
       ],
   )

3. Redémarrez Codex.

Au démarrage, Codex analyse les fichiers rules/ de chaque couche de configuration active, notamment les emplacements de configuration d’équipe et la couche utilisateur située dans ~/.codex/rules/. Les règles locales au projet sous <repo>/.codex/rules/ ne sont chargées que si la couche .codex/ du projet est approuvée.

Lorsque vous ajoutez une commande à la liste d’autorisation dans la TUI, Codex l’écrit dans la couche utilisateur située dans ~/.codex/rules/default.rules afin que les prochaines exécutions puissent ignorer la demande de confirmation.

Lorsque les approbations intelligentes sont activées (le réglage par défaut), Codex peut vous proposer un prefix_rule lors des demandes d’élévation. Examinez attentivement le préfixe suggéré avant de l’accepter.

Les administrateurs peuvent également imposer des entrées prefix_rule restrictives depuis requirements.toml.

Comprendre les champs des règles

prefix_rule() prend en charge les champs suivants :

• pattern (obligatoire) : liste non vide qui définit le préfixe de commande à rechercher. Chaque élément est soit :
  • Une chaîne littérale (par exemple, "pr").
  • Une union de littéraux (par exemple, ["view", "list"]) permettant de rechercher plusieurs possibilités à cette position d’argument.
• decision (valeur par défaut : "allow") : action à effectuer lorsque la règle correspond. Codex applique la décision la plus restrictive lorsque plusieurs règles correspondent (forbidden > prompt > allow).
  • allow : exécuter la commande en dehors du bac à sable sans demander de confirmation.
  • prompt : demander une confirmation avant chaque invocation correspondante.
  • forbidden : bloquer la demande sans demander de confirmation.
• justification (facultatif) : motif non vide et lisible expliquant la règle. Codex peut l’afficher dans les demandes d’approbation ou les messages de rejet. Lorsque vous utilisez forbidden, indiquez dans la justification une autre solution recommandée lorsque cela est pertinent (par exemple, "Use \rg` instead of `grep`."`).
• match et not_match (valeur par défaut : []) : exemples que Codex valide lors du chargement de vos règles. Utilisez-les pour détecter les erreurs avant l’entrée en vigueur d’une règle.

Lorsque Codex envisage d’exécuter une commande, il compare la liste d’arguments de celle-ci à pattern. En interne, Codex traite la commande comme une liste d’arguments (semblable à celle que reçoit execvp(3)).

Enveloppes de shell et commandes composées

Certains outils regroupent plusieurs commandes shell dans une seule invocation, par exemple :

["bash", "-lc", "git add . && rm -rf /"]

Comme ce type de commande peut dissimuler plusieurs actions dans une même chaîne, Codex traite bash -lc, bash -c et leurs équivalents zsh / sh de manière particulière.

Lorsque Codex peut scinder le script en toute sécurité

Si le script shell est une chaîne linéaire de commandes composée uniquement :

• de mots simples (sans développement de variable, ni VAR=..., $FOO, *, etc.)
• reliés par des opérateurs sûrs (&&, ||, ; ou |)

alors Codex l’analyse (avec tree-sitter) et le scinde en commandes individuelles avant d’appliquer vos règles.

Le script ci-dessus est traité comme deux commandes distinctes :

• ["git", "add", "."]
• ["rm", "-rf", "/"]

Codex évalue ensuite chaque commande en fonction de vos règles, et le résultat le plus restrictif l’emporte.

Même si vous autorisez pattern=["git", "add"], Codex n’autorisera pas automatiquement git add . && rm -rf /, car la partie rm -rf / est évaluée séparément et empêche l’autorisation automatique de l’ensemble de l’invocation.

Cela empêche l’introduction furtive de commandes dangereuses aux côtés de commandes sûres.

Lorsque Codex ne scinde pas le script

Si le script utilise des fonctionnalités de shell plus avancées, telles que :

• des redirections (>, >>, <)
• des substitutions ($(...), ...)
• des variables d’environnement (FOO=bar)
• des motifs génériques (*, ?)
• des structures de contrôle (if, for, && avec des affectations, etc.)

alors Codex n’essaie ni de l’interpréter ni de le scinder.

Dans ce cas, l’intégralité de l’invocation est traitée comme suit :

["bash", "-lc", "<full script>"]

et vos règles sont appliquées à cette invocation unique.

Ce traitement vous offre la sécurité d’une évaluation commande par commande lorsqu’elle peut être effectuée sans risque, ainsi qu’un comportement prudent dans le cas contraire.

Tester un fichier de règles

Utilisez codex execpolicy check pour tester la façon dont vos règles s’appliquent à une commande :

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

La commande produit du JSON indiquant la décision la plus stricte et toutes les règles correspondantes, y compris les éventuelles valeurs justification des règles concernées. Utilisez plusieurs options --rules pour combiner des fichiers et ajoutez --pretty pour mettre en forme la sortie.

Comprendre le langage des règles

Le format de fichier .rules utilise Starlark (consultez la spécification du langage). Sa syntaxe ressemble à celle de Python, mais elle est conçue pour garantir une exécution sûre : le moteur de règles peut l’exécuter sans effets de bord (par exemple, sans accéder au système de fichiers).