規則

使用規則控制 Codex 可以在沙箱外執行哪些命令。

建立規則檔案

對於 Work Cloud 的本機電腦存取功能，請使用 Agent Security 中的 rules TOML 欄位設定受支援的託管命令規則。這些規則適用於本機執行器；Work 雲容器使用現有的 Work Cloud 策略。

這些本機 .rules 指令適用於 Codex；不要假定 Work Cloud 的本機電腦存取功能會讀取本機規則檔案。有關 Work 的託管要求，請參閱託管設定和設定參考。

1. 在當前啟用設定層旁邊的 rules/ 目錄下建立一個 .rules 檔案，例如 ~/.codex/rules/default.rules。
2. 新增一條規則。下面這個例子會在允許 gh pr view 於沙箱外執行前先提示使用者確認。

   # 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. 重啟 Codex。

Codex 會在啟動時掃描每個啟用設定層下的 rules/ 目錄，包括 Team Config 位置和使用者層 ~/.codex/rules/。位於 <repo>/.codex/rules/ 的專案本機規則只會在專案 .codex/ 設定層受信任時載入。

當你在 TUI 中把某條命令加入允許列表時，Codex 會把規則寫入使用者層的 ~/.codex/rules/default.rules，這樣後續執行就可以跳過同類提示。

啟用 Smart approvals（智慧核准，預設啟用）時，Codex 在升級權限請求期間可能會為你建議一條 prefix_rule。接受前，請仔細檢查它建議的命令前綴。

管理員也可以透過 requirements.toml 強制下發更嚴格的 prefix_rule。

理解規則欄位

prefix_rule() 支援這些欄位：

• pattern（必填）：一個非空列表，用來定義要匹配的命令前綴。列表中的每個元素可以是：
  • 一個字面量字串，例如 "pr"
  • 一個由多個字面量構成的並集，例如 ["view", "list"]，表示在這一參數位置匹配多個備選值
• decision（預設值為 "allow"）：當規則命中時要採取的動作。如果多條規則同時命中，Codex 會採用最嚴格的決策（forbidden > prompt > allow）。
  • allow：不提示，直接在 沙箱外執行命令
  • prompt：每次命中都先請求確認
  • forbidden：不提示，直接阻止該請求
• justification（可選）：非空的人類可讀說明。Codex 可能會在 核准提示或拒絕訊息中顯示它。如果使用 forbidden，適合在這裡順帶給出一個推薦替代方案，例如 "Use \rg` instead of `grep`."`
• match 和 not_match（預設都是 []）：在載入 rules 時由 Codex 校驗的命令範例，用來在規則真正生效前發現設定錯誤

當 Codex 評估一條待執行命令時，它會把命令的參數陣列與 pattern 做比較。在內部，Codex 會把命令視為一個參數列表，類似 execvp(3) 接收到的形式。

Shell 包裝器與複合命令

有些工具會把多條 shell 命令包裝成一次呼叫，例如：

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

由於這類命令可能在一個字串中隱藏多個操作，Codex 會對 bash -lc、bash -c 及其對應的 zsh / sh 形式進行特殊處理。

Codex 何時可以安全拆分指令碼

如果 shell 指令碼只是由下列元素組成的線性命令鏈：

• 純字面量單詞，不包含變數展開、VAR=...、$FOO、* 等特殊語法
• 只透過安全運算子連線，例如 &&、||、; 或 |

那麼 Codex 會使用 tree-sitter 解析它，並在應用 rules 前把它拆成多條獨立命令。

上面的指令碼會被視為兩條命令：

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

Codex 會分別用你的 rules 評估每條命令，並以最嚴格的結果為準。

即使你允許 pattern=["git", "add"]，Codex 也不會自動允許 git add . && rm -rf /，因為它會單獨評估 rm -rf /。

這可以防止危險命令混在安全命令後面一起“偷渡”執行。

Codex 何時不會拆分指令碼

如果指令碼使用了更複雜的 shell 特性，例如：

• 重定向，例如 >、>>、<
• 替換表示式，例如 $(...) 或 ...
• 環境變數賦值，例如 FOO=bar
• 萬用字元模式，例如 *、?
• 控制流，例如 if、for，或帶賦值的 &&

那麼 Codex 就不會嘗試解釋或拆分它。

在這種情況下，整次呼叫會被當作：

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

並按一次單獨呼叫 整體應用你的 rules。

這種處理方式意味著：在可以安全拆分時，Codex 會按單條命令逐項評估；在不能安全拆分時，則採用更保守的整體判斷。

測試規則檔案

使用 codex execpolicy check 可以測試 rules 對某條命令會產生什麼效果：

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

這個命令會輸出 JSON，展示最嚴格的決策結果以及命中的規則，其中也包括命中規則裡的 justification。你可以傳多個 --rules 來組合多份規則檔案；加上 --pretty 則會得到格式化輸出。

理解規則語言

.rules 檔案格式使用 Starlark（參閱語言規範）。它的語法類似於 Python，但其設計確保了執行安全：規則引擎可以在不產生副作用（例如存取檔案系統）的情況下執行它。