Aturan

Gunakan aturan untuk mengontrol perintah yang dapat dijalankan Codex di luar sandbox.

Membuat file aturan

1. Buat file .rules di dalam folder rules/ di samping lapisan konfigurasi aktif (misalnya, ~/.codex/rules/default.rules).
2. Tambahkan aturan. Contoh ini meminta konfirmasi sebelum mengizinkan gh pr view berjalan di luar sandbox.

   # 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. Mulai ulang Codex.

Codex memindai rules/ di bawah setiap lapisan konfigurasi aktif saat dimulai, termasuk lokasi Konfigurasi Tim dan lapisan pengguna di ~/.codex/rules/. Aturan lokal proyek di bawah <repo>/.codex/rules/ hanya dimuat jika lapisan .codex/ proyek dipercaya.

Saat Anda menambahkan perintah ke daftar yang diizinkan di TUI, Codex menuliskannya ke lapisan pengguna di ~/.codex/rules/default.rules agar eksekusi berikutnya dapat melewati prompt.

Saat persetujuan Cerdas diaktifkan (default), Codex dapat mengusulkan prefix_rule untuk Anda selama permintaan eskalasi. Tinjau prefiks yang disarankan dengan cermat sebelum menerimanya.

Admin juga dapat memberlakukan entri prefix_rule yang membatasi dari requirements.toml.

Memahami bidang aturan

prefix_rule() mendukung bidang berikut:

• pattern (wajib): Daftar tidak kosong yang menentukan prefiks perintah yang akan dicocokkan. Setiap elemen berupa:
  • String literal (misalnya, "pr").
  • Gabungan literal (misalnya, ["view", "list"]) untuk mencocokkan alternatif pada posisi argumen tersebut.
• decision (secara default "allow"): Tindakan yang diambil saat aturan cocok. Codex menerapkan keputusan yang paling membatasi jika lebih dari satu aturan cocok (forbidden > prompt > allow).
  • allow: Jalankan perintah di luar sandbox tanpa meminta konfirmasi.
  • prompt: Minta konfirmasi sebelum setiap pemanggilan yang cocok.
  • forbidden: Blokir permintaan tanpa meminta konfirmasi.
• justification (opsional): Alasan yang mudah dipahami manusia dan tidak kosong untuk aturan tersebut. Codex dapat menampilkannya dalam prompt persetujuan atau pesan penolakan. Saat menggunakan forbidden, sertakan alternatif yang disarankan dalam justifikasi jika sesuai (misalnya, "Use \rg` instead of `grep`."`).
• match dan not_match (secara default []): Contoh yang divalidasi Codex saat memuat aturan Anda. Gunakan ini untuk menemukan kesalahan sebelum aturan diterapkan.

Saat Codex mempertimbangkan perintah untuk dijalankan, Codex membandingkan daftar argumen perintah tersebut dengan pattern. Secara internal, Codex memperlakukan perintah sebagai daftar argumen (seperti yang diterima execvp(3)).

Pembungkus shell dan perintah gabungan

Beberapa alat membungkus beberapa perintah shell ke dalam satu pemanggilan, misalnya:

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

Karena jenis perintah ini dapat menyembunyikan beberapa tindakan dalam satu string, Codex memperlakukan bash -lc, bash -c, dan padanan zsh / sh secara khusus.

Saat Codex dapat memisahkan skrip dengan aman

Jika skrip shell merupakan rangkaian linear perintah yang hanya terdiri dari:

• kata biasa (tanpa ekspansi variabel, tanpa VAR=..., $FOO, *, dan sebagainya)
• digabungkan dengan operator aman (&&, ||, ;, atau |)

maka Codex mengurainya (menggunakan tree-sitter) dan memisahkannya menjadi perintah tersendiri sebelum menerapkan aturan Anda.

Skrip di atas diperlakukan sebagai dua perintah terpisah:

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

Codex kemudian mengevaluasi setiap perintah berdasarkan aturan Anda, dan hasil yang paling membatasi berlaku.

Meskipun Anda mengizinkan pattern=["git", "add"], Codex tidak akan otomatis mengizinkan git add . && rm -rf / karena bagian rm -rf / dievaluasi secara terpisah dan mencegah seluruh pemanggilan diizinkan secara otomatis.

Hal ini mencegah perintah berbahaya diselundupkan bersama perintah yang aman.

Saat Codex tidak memisahkan skrip

Jika skrip menggunakan fitur shell yang lebih canggih, seperti:

• pengalihan (>, >>, <)
• substitusi ($(...), ...)
• variabel lingkungan (FOO=bar)
• pola wildcard (*, ?)
• alur kontrol (if, for, && dengan penetapan, dan sebagainya)

maka Codex tidak mencoba menafsirkan atau memisahkannya.

Dalam kasus tersebut, seluruh pemanggilan diperlakukan sebagai:

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

dan aturan Anda diterapkan pada satu pemanggilan tersebut.

Dengan penanganan ini, Anda mendapatkan keamanan evaluasi per perintah saat aman dilakukan, dan perilaku konservatif saat tidak aman.

Menguji file aturan

Gunakan codex execpolicy check untuk menguji cara aturan Anda diterapkan pada suatu perintah:

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

Perintah tersebut menghasilkan JSON yang menampilkan keputusan paling ketat dan setiap aturan yang cocok, termasuk nilai justification dari aturan yang cocok. Gunakan lebih dari satu flag --rules untuk menggabungkan file, lalu tambahkan --pretty untuk memformat output.

Memahami bahasa aturan

Format file .rules menggunakan Starlark (lihat spesifikasi bahasa). Sintaksnya menyerupai Python, tetapi dirancang agar aman dijalankan: mesin aturan dapat menjalankannya tanpa efek samping (misalnya, menyentuh sistem file).