Regeln

Verwenden Sie Regeln, um zu steuern, welche Befehle Codex außerhalb der Sandbox ausführen kann.

Regeldatei erstellen

1. Erstellen Sie eine .rules-Datei in einem rules/-Ordner neben einer aktiven Konfigurationsebene (zum Beispiel ~/.codex/rules/default.rules).
2. Fügen Sie eine Regel hinzu. Dieses Beispiel fragt nach, bevor gh pr view außerhalb der Sandbox ausgeführt werden darf.

   # 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. Starten Sie Codex neu.

Codex durchsucht beim Start die rules/-Dateien unter jeder aktiven Konfigurationsebene, einschließlich der Speicherorte der Teamkonfiguration und der Benutzerebene unter ~/.codex/rules/. Projektlokale Regeln unter <repo>/.codex/rules/ werden nur geladen, wenn die .codex/-Ebene des Projekts als vertrauenswürdig eingestuft ist.

Wenn Sie in der TUI einen Befehl zur Zulassungsliste hinzufügen, schreibt Codex ihn in die Benutzerebene unter ~/.codex/rules/default.rules, sodass bei zukünftigen Ausführungen keine Nachfrage erforderlich ist.

Wenn intelligente Genehmigungen aktiviert sind (Standardeinstellung), kann Codex Ihnen bei Eskalationsanfragen ein prefix_rule vorschlagen. Prüfen Sie das vorgeschlagene Präfix sorgfältig, bevor Sie es akzeptieren.

Administratoren können außerdem restriktive prefix_rule-Einträge aus requirements.toml erzwingen.

Regelfelder verstehen

prefix_rule() unterstützt diese Felder:

• pattern (erforderlich): Eine nicht leere Liste, die das abzugleichende Befehlspräfix definiert. Jedes Element ist entweder:
  • Eine Literalzeichenfolge (zum Beispiel "pr").
  • Eine Vereinigung von Literalen (zum Beispiel ["view", "list"]), um Alternativen an dieser Argumentposition abzugleichen.
• decision (Standardwert: "allow"): Die Aktion, die bei Übereinstimmung mit der Regel ausgeführt wird. Wenn mehrere Regeln übereinstimmen, wendet Codex die restriktivste Entscheidung an (forbidden > prompt > allow).
  • allow: Den Befehl ohne Nachfrage außerhalb der Sandbox ausführen.
  • prompt: Vor jedem übereinstimmenden Aufruf nachfragen.
  • forbidden: Die Anfrage ohne Nachfrage blockieren.
• justification (optional): Eine nicht leere, menschenlesbare Begründung für die Regel. Codex kann sie in Genehmigungsaufforderungen oder Ablehnungsmeldungen anzeigen. Wenn Sie forbidden verwenden, geben Sie in der Begründung gegebenenfalls eine empfohlene Alternative an (zum Beispiel "Use \rg` instead of `grep`."`).
• match und not_match (Standardwert: []): Beispiele, die Codex beim Laden Ihrer Regeln validiert. Verwenden Sie diese, um Fehler zu erkennen, bevor eine Regel wirksam wird.

Wenn Codex die Ausführung eines Befehls erwägt, vergleicht es die Argumentliste des Befehls mit pattern. Intern behandelt Codex den Befehl als Argumentliste (wie diejenige, die execvp(3) empfängt).

Shell-Wrapper und zusammengesetzte Befehle

Einige Tools fassen mehrere Shell-Befehle in einem einzigen Aufruf zusammen, zum Beispiel:

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

Da diese Art von Befehl mehrere Aktionen in einer einzigen Zeichenfolge verbergen kann, behandelt Codex bash -lc, bash -c und deren Entsprechungen zsh / sh gesondert.

Wann Codex das Skript sicher aufteilen kann

Wenn das Shell-Skript eine lineare Befehlskette ist, die ausschließlich aus Folgendem besteht:

• einfachen Wörtern (keine Variablenexpansion, kein VAR=..., $FOO, * usw.)
• verknüpft durch sichere Operatoren (&&, ||, ; oder |)

dann analysiert Codex es (mit tree-sitter) und teilt es in einzelne Befehle auf, bevor Ihre Regeln angewendet werden.

Das obige Skript wird als zwei separate Befehle behandelt:

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

Codex wertet anschließend jeden Befehl anhand Ihrer Regeln aus, wobei das restriktivste Ergebnis maßgeblich ist.

Selbst wenn Sie pattern=["git", "add"] zulassen, lässt Codex git add . && rm -rf / nicht automatisch zu, da der Teil rm -rf / separat ausgewertet wird und verhindert, dass der gesamte Aufruf automatisch zugelassen wird.

Dadurch wird verhindert, dass gefährliche Befehle zusammen mit sicheren Befehlen eingeschleust werden.

Wann Codex das Skript nicht aufteilt

Wenn das Skript erweiterte Shell-Funktionen verwendet, etwa:

• Umleitungen (>, >>, <)
• Ersetzungen ($(...), ...)
• Umgebungsvariablen (FOO=bar)
• Platzhaltermuster (*, ?)
• Kontrollfluss (if, for, && mit Zuweisungen usw.)

dann versucht Codex nicht, es zu interpretieren oder aufzuteilen.

In diesen Fällen wird der gesamte Aufruf wie folgt behandelt:

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

und Ihre Regeln werden auf diesen einzelnen Aufruf angewendet.

Mit dieser Handhabung erhalten Sie die Sicherheit einer befehlsweisen Auswertung, wenn diese sicher möglich ist, und ein konservatives Verhalten, wenn dies nicht der Fall ist.

Regeldatei testen

Verwenden Sie codex execpolicy check, um zu testen, wie Ihre Regeln auf einen Befehl angewendet werden:

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

Der Befehl gibt JSON mit der strengsten Entscheidung und allen übereinstimmenden Regeln aus, einschließlich aller justification-Werte aus übereinstimmenden Regeln. Verwenden Sie mehr als ein --rules-Flag, um Dateien zu kombinieren, und fügen Sie --pretty hinzu, um die Ausgabe zu formatieren.

Regelsprache verstehen

Das .rules-Dateiformat verwendet Starlark (siehe Sprachspezifikation). Seine Syntax ähnelt Python, ist jedoch für eine sichere Ausführung konzipiert: Die Regel-Engine kann es ohne Nebenwirkungen ausführen (zum Beispiel ohne auf das Dateisystem zuzugreifen).