Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Regeln

Lege fest, welche Befehle Codex außerhalb der Sandbox ausführen darf

Mit Regeln legst du fest, welche Befehle Codex außerhalb der Sandbox ausführen darf.

Regeln sind experimentell und können sich ändern.

Regeldatei erstellen

Für den Zugriff auf den lokalen Computer mit Work Cloud konfigurierst du die unterstützten verwalteten Befehlsregeln über das TOML-Feld rules in den Sicherheitseinstellungen für Agenten. Diese Regeln gelten für lokale Ausführungsprogramme. Für Container in Work Cloud gelten die bestehenden Richtlinien von Work Cloud.

Die folgende Anleitung für lokale .rules-Dateien gilt für Codex. Geh nicht davon aus, dass Work Cloud beim Zugriff auf den lokalen Computer lokale Regeldateien liest. Welche Anforderungen für zentral verwaltete Work-Konfigurationen gelten, erfährst du in der Dokumentation zur verwalteten Konfiguration und in der Konfigurationsreferenz.

  1. Erstelle eine .rules-Datei im Ordner rules/ neben der Konfigurationsdatei einer aktiven Konfigurationsebene (zum Beispiel ~/.codex/rules/default.rules).

  2. Füge eine Regel hinzu. In diesem Beispiel fordert Codex eine Genehmigung an, bevor es gh pr view außerhalb der Sandbox ausführt.

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

Beim Start durchsucht Codex den Ordner rules/ jeder aktiven Konfigurationsebene. Dazu gehören die Speicherorte der Teamkonfiguration und deine persönliche Konfigurationsebene unter ~/.codex/rules/. Projektlokale Regeln unter <repo>/.codex/rules/ lädt Codex nur, wenn die Konfigurationsebene .codex/ des Projekts als vertrauenswürdig gilt.

Wenn du in der Terminaloberfläche (TUI) einen Befehl zur Liste der erlaubten Befehle hinzufügst, speichert Codex die Regel in deiner persönlichen Konfigurationsebene unter ~/.codex/rules/default.rules. Bei künftigen Ausführungen kann die Rückfrage dann entfallen.

Wenn intelligente Genehmigungen aktiviert sind (Standardeinstellung), kann Codex dir bei einer Anfrage nach erweiterten Berechtigungen eine prefix_rule vorschlagen. Prüfe das vorgeschlagene Präfix sorgfältig, bevor du es akzeptierst.

Admins können einschränkende prefix_rule-Einträge auch über requirements.toml durchsetzen.

Felder einer Regel

prefix_rule() unterstützt folgende Felder:

  • pattern (erforderlich): Eine nicht leere Liste, die festlegt, mit welchem Präfix ein Befehl beginnen muss, damit die Regel greift. Für jedes Element gibt es zwei Möglichkeiten:
    • Ein einzelnes Zeichenfolgenliteral (zum Beispiel "pr").
    • Eine Liste von Literalen (zum Beispiel ["view", "list"]), von denen eines an dieser Argumentposition stehen muss.
  • decision (Standardwert: "allow"): Legt fest, was passiert, wenn die Regel greift. Treffen mehrere Regeln zu, wendet Codex die strengste Entscheidung an (forbidden > prompt > allow).
    • allow: Codex führt den Befehl ohne Rückfrage außerhalb der Sandbox aus.
    • prompt: Codex fordert bei jedem passenden Aufruf eine Genehmigung an.
    • forbidden: Codex blockiert die Anfrage ohne Rückfrage.
  • justification (optional): Eine verständlich formulierte Begründung für die Regel. Das Feld darf nicht leer sein, wenn du es angibst. Codex kann die Begründung bei Genehmigungsanfragen oder Ablehnungen anzeigen. Wenn du forbidden verwendest, nenne gegebenenfalls eine empfohlene Alternative (zum Beispiel "Use \rg` instead of `grep`.“`).
  • match und not_match (Standardwert jeweils []): Beispiele, die Codex beim Laden deiner Regeln überprüft. Damit kannst du Fehler erkennen, bevor eine Regel wirksam wird.

Bevor Codex einen Befehl ausführt, vergleicht es dessen Argumentliste mit pattern. Intern behandelt Codex den Befehl als Liste von Argumenten, wie sie auch execvp(3) erhält.

Shell-Wrapper und zusammengesetzte Befehle

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

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

Da sich bei solchen Aufrufen mehrere Aktionen in einer einzigen Zeichenfolge verbergen können, behandelt Codex bash -lc, bash -c und die entsprechenden Aufrufe von zsh und sh gesondert.

Wann Codex das Skript sicher aufteilen kann

Codex kann eine lineare Folge von Befehlen aufteilen, wenn beide Bedingungen erfüllt sind:

  • Die Befehle bestehen nur aus einfachen Wörtern (keine Variablenexpansion, kein VAR=..., $FOO, * usw.).
  • Die Befehle sind ausschließlich durch sichere Operatoren verknüpft (&&, ||, ; oder |).

In diesem Fall analysiert Codex das Skript mit tree-sitter und zerlegt es in einzelne Befehle, bevor es deine Regeln anwendet.

Das Skript aus dem Beispiel behandelt Codex als zwei separate Befehle:

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

Codex prüft jeden Befehl einzeln anhand deiner Regeln. Für den gesamten Aufruf gilt die strengste Entscheidung.

Selbst wenn du pattern=["git", "add"] erlaubst, lässt Codex git add . && rm -rf / nicht automatisch zu, weil es rm -rf / separat prüft.

So lässt sich ein gefährlicher Befehl nicht zusammen mit einem harmlosen Befehl einschleusen.

Wann Codex das Skript als Ganzes behandelt

Bei komplexeren Shell-Funktionen verzichtet Codex auf die Aufteilung. Dazu gehören:

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

In diesen Fällen versucht Codex weder, das Skript zu interpretieren, noch, es aufzuteilen.

Codex behandelt den gesamten Aufruf dann wie folgt:

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

Deine Regeln gelten für diesen einen Aufruf.

So prüft Codex Befehle einzeln, wenn es sie sicher voneinander trennen kann. Andernfalls prüft es vorsichtshalber den gesamten Aufruf.

Regeldatei testen

Mit codex execpolicy check prüfst du, wie deine 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 die strengste Entscheidung und alle zutreffenden Regeln als JSON aus. Die Ausgabe enthält auch die justification-Werte, sofern die zutreffenden Regeln eine Begründung angeben. Um mehrere Dateien zu kombinieren, gib --rules mehrfach an. Mit --pretty formatierst du die Ausgabe.

Sprache der Regeldateien

Das Dateiformat .rules verwendet Starlark (siehe Sprachspezifikation). Die Syntax ähnelt der von Python. Die Sprache ist für die sichere Ausführung konzipiert. Die Regel-Engine kann die Regeln ohne Nebenwirkungen ausführen, etwa ohne auf das Dateisystem zuzugreifen.