Profil izin Codex adalah kebijakan bernama di config.toml yang menentukan apa yang dapat dibaca, ditulis, dan dijangkau di jaringan oleh perintah yang dijalankan Codex di mesin Anda. Anda memilihnya dengan default_permissions, mulai dari profil bawaan (:read-only, :workspace, atau :danger-full-access), lalu menambahkan path read, write, dan deny serta daftar izin domain.
Panduan ini menyediakan contoh config.toml siap salin untuk berbagai pengaturan paling umum, termasuk untuk pekerjaan API yang memungkinkan coding agent Anda menjalankan pengujian Apidog CLI terhadap host API Anda sendiri tanpa akses internet terbuka.
Apa Itu Profil Izin Codex?
Profil izin adalah kebijakan sandbox yang dapat digunakan ulang untuk Codex. Profil ini menggabungkan aturan filesystem (path mana yang dapat dibaca, ditulis, atau tidak boleh disentuh sama sekali oleh perintah) dengan aturan jaringan (apakah perintah dapat menjangkau jaringan, dan ke domain mana). Codex menegakkannya dengan Seatbelt di macOS, bubblewrap plus seccomp di Linux dan WSL, serta MXC di Windows.
OpenAI menjelaskan desainnya dalam Inside the Codex sandbox, yang diterbitkan pada 18 November 2026. Alih-alih memindahkan pekerjaan Anda ke dalam container, Codex membatasi perintah di lingkungan Anda yang sudah ada, sehingga toolchain native tetap dapat berjalan.
Codex menyertakan tiga profil bawaan:
| Profil | Filesystem | Jaringan |
|---|---|---|
:read-only |
Perintah dapat membaca, tidak dapat menulis | Mati |
:workspace |
Menulis di dalam root workspace dan direktori temp; .git, .agents, .codex, .aws tetap read-only |
Mati |
:danger-full-access |
Tanpa batasan sandbox lokal | Penuh, langsung |
Dokumentasi permissions masih menyebut fitur ini sebagai Beta, jadi bersiaplah jika nama key berubah antar rilis.
Di Mana Tabel Izin Diletakkan dalam config.toml
Profil Anda berada di ~/.codex/config.toml (atau di lapisan proyek maupun sistem). Ada dua bagian tingkat atas yang penting:
default_permissionsmenentukan nama profil yang diterapkan Codex secara default. Nilainya harus cocok dengan profil bawaan atau profil di bawah[permissions].[permissions.<name>]mendefinisikan sebuah profil. Beridescription; deskripsi ini akan muncul di pemilih/permissions.
Ada satu aturan yang sering menjebak banyak orang. Profil izin tidak dapat digabungkan dengan pengaturan sandbox lama. Jika sandbox_mode muncul di file config yang termuat, atau Anda meneruskan --sandbox, Codex akan memakai pengaturan lama dan mengabaikan default_permissions. Hapus sandbox_mode dan [sandbox_workspace_write] sebelum Anda beralih.
Profil mengikuti model presedensi config yang normal. Tabel digabungkan secara rekursif, sehingga config tim dapat menambahkan satu domain atau satu path ke profil organisasi tanpa perlu menulis ulang semuanya.
Aturan Filesystem: read, write, dan deny
Setiap entri filesystem memetakan sebuah path ke read, write, atau deny. Path yang lebih spesifik mengalahkan yang lebih umum, dan jika dua entri menargetkan path yang sama, deny mengalahkan write, yang mengalahkan read.
Bentuk path yang paling sering Anda gunakan:
:minimal: path platform dan runtime yang dibutuhkan oleh tool umum:workspace_roots: root workspace sesi ditambah root apa pun yang ditambahkan oleh profil:root,:tmpdir,:slash_tmp, path absolut, dan path~/
Gunakan extends agar Anda mewarisi pengamanan bawaan, bukan membangunnya dari awal. Berikut profil yang mempertahankan default :workspace dan mengunci rahasia:
default_permissions = "dev"
[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"
[permissions.dev.filesystem]
"~/build-cache" = "write"
[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
Aturan di bawah :workspace_roots berlaku untuk setiap root, jadi secrets berarti folder secrets di setiap root proyek. Sebuah profil dapat meng-extend :read-only, :workspace, atau profil bernama lain. Profil tidak dapat meng-extend :danger-full-access.
Di Linux, WSL, dan Windows native, glob ** deny yang tak terbatas mungkin memerlukan glob_scan_max_depth (minimal 1) di bawah [permissions.<name>.filesystem] agar Codex dapat mengembangkannya sebelum sandbox dimulai.

Aturan Jaringan: Mati, Terbuka, atau Daftar Izin
Jaringan memiliki tiga status, dan dua pengaturan mengendalikannya:
- Jaringan mati (
enabled = false, default:workspace): perintah tidak dapat menjangkau jaringan. - Jaringan aktif, proxy mati: perintah mendapat akses langsung tanpa batasan. Aturan domain Anda diabaikan.
- Jaringan aktif, proxy aktif: lalu lintas melewati proxy jaringan Codex, yang menegakkan aturan domain pada profil.
Status kedua inilah jebakannya. Menyetel permissions.<name>.network.enabled = true tidak menjalankan proxy. Anda juga memerlukan ini di tingkat atas:
[features]
network_proxy = true
Pola domain mendukung host persis (api.example.com), *.example.com untuk subdomain saja, **.example.com untuk apex plus subdomain, dan * sebagai wildcard global khusus allow. Entri deny mengesampingkan entri allow, dan proxy aktif tanpa entri allow akan memblokir semua yang eksternal.
Saat proxy aktif, secara default proxy juga memblokir target jaringan lokal dan privat. Untuk menjangkau layanan lokal, masukkan host literal ke daftar izin, seperti "localhost" = "allow" atau "127.0.0.1" = "allow".
Profil Izin Codex untuk Pekerjaan API
Berikut profil yang kami uji untuk pengembangan API. Profil ini mengedit kode di workspace, tidak pernah membaca file .env atau folder secrets, dan hanya dapat menjangkau host API Anda serta Apidog:
default_permissions = "api-work"
[features]
network_proxy = true
[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"
[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"
[permissions.api-work.network]
enabled = true
[permissions.api-work.network.domains]
"api.your-company.com" = "allow" # the API under test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow" # Apidog CLI and its API
Ganti kedua host tersebut dengan host yang diakses pengujian Anda. Apidog CLI mengirim permintaan pengujian dari mesin Anda ke API yang sedang diuji, jadi host tersebut harus masuk daftar izin, bukan hanya host Apidog. Jika Anda menguji server lokal, tambahkan "localhost" = "allow".
Instal paket sebelum sesi dimulai, bukan di dalamnya. Menjalankan npm install -g apidog-cli@latest memerlukan registry.npmjs.org, yang sengaja diblokir oleh profil ini.
Satu jebakan dari pengujian kami: di Mac yang menjalankan aplikasi proxy atau VPN dalam mode fake-IP DNS, setiap host yang diizinkan di-resolve ke alamat 198.18.x.x. Penjaga lokal/privat memperlakukannya sebagai privat dan memblokirnya, lalu Codex melaporkan "local/private network addresses are blocked by the sandbox policy." Menambahkan allow_local_binding = true di bawah [permissions.api-work.network] memperbaikinya, tetapi ini juga membuka hostname yang masuk daftar izin yang di-resolve ke alamat privat, jadi hanya atur saat Anda membutuhkannya.
Uji Profil dengan codex sandbox
Jangan percaya sebuah profil sampai Anda menyaksikannya memblokir sesuatu. Perintah codex sandbox menjalankan perintah apa pun di bawah profil bernama dan memperlakukan direktori saat ini sebagai root workspace:
codex sandbox --permission-profile api-work -- cat README.md .env
Dengan profil di atas, pengujian kami mencetak README lalu:
cat: .env: Operation not permitted
Penulisan di luar workspace gagal dengan cara yang sama (Operation not permitted), sementara file baru di dalam workspace berhasil dibuat. Untuk jaringan, periksa bahwa proxy memblokir host yang tidak Anda daftarkan:
codex sandbox -P api-work -- curl -sI https://example.org
Proxy menjawab 403 Forbidden dengan x-proxy-error: blocked-by-allowlist, sementara apidog.com mengembalikan 200. Di macOS, tambahkan --log-denials untuk mencetak penolakan Seatbelt setelah perintah selesai.
Anda juga dapat menggunakan codex sandbox untuk membungkus proses yang tidak di-sandbox sendiri oleh Codex. Posting OpenAI mencatat bahwa server MCP stdio di config.toml berjalan tanpa sandbox, dan menunjukkan profil memory-mcp dengan "~/mcp-data" = "write" dan network.enabled = false yang membungkus perintah npx pada server tersebut.
Ganti Profil di Tengah Sesi dengan /permissions
Di Codex CLI, ketik /permissions untuk membuka pemilih. Jika ada profil bernama, pemilih akan menampilkannya beserta deskripsinya. Untuk memilih salah satu secara langsung:
/permissions api-work --approval-policy=on-request --reviewer=user
Perintah itu mengatur profil untuk sesi saat ini dan mengirim permintaan persetujuan kepada Anda. Profil dan persetujuan adalah kontrol yang terpisah: profil menentukan apa yang bisa disentuh oleh perintah yang di-sandbox, dan kebijakan persetujuan menentukan kapan Codex bertanya sebelum melangkah keluar. Referensi perintah CLI mencantumkan perintah sesi lainnya.
Biarkan Codex Menguji API Anda dengan Apidog CLI
Dengan api-work aktif, Codex dapat menjalankan pengujian API sungguhan tanpa akses internet terbuka. Apidog CLI memberi agent Anda perintah untuk endpoint, test case, dan run, dengan output JSON yang dapat dibacanya. Anda menyiapkannya sekali di luar sandbox:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Lalu berikan satu prompt kepada Codex:
Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.
Codex membaca skema payload, memvalidasi JSON-nya, dan menjalankan test case:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json
Dalam pengujian kami, apidog auth status dan apidog project list sama-sama berjalan di dalam sandbox api-work dengan hanya **.apidog.com yang masuk daftar izin. Token Anda tetap berada di ~/.apidog, yang dapat dibaca tetapi tidak dapat diubah oleh profil. Untuk panduan lengkap, lihat cara menggunakan Apidog CLI di Codex, dan ganti -r cli,json dengan -r junit saat run yang sama dipindahkan ke pipeline CI. Paket Free Apidog mencakup hingga 4 pengguna.

Batasan yang Perlu Diketahui Sebelum Mempercayai Profil
Profil izin memperkecil radius dampak. Namun, profil tidak membuat agent aman dengan sendirinya. Dokumentasi dan posting OpenAI mencantumkan batasan-batasan berikut:
- Pembacaan yang luas tetap aktif dengan
:workspace. Compiler memerlukan SDK dan config di luar repo, jadi file config di tempat lain yang menyimpan kunci API mungkin tetap dapat dibaca. Tolak path~/.sshdan path serupa secara eksplisit, atau gunakan":root" = "deny"plus":minimal" = "read". - Glob deny bersifat snapshot. Di Linux, WSL, dan Windows, kecocokan diperluas saat setiap proses yang di-sandbox dimulai. File
.envyang dibuat belakangan tetap dapat dibaca oleh shell atau dev server yang berjalan lama. - Wildcard masih bisa bocor melalui DNS. Proxy hanya me-resolve hostname setelah hostname tersebut diizinkan, tetapi aturan wildcard yang luas atau akses ke layanan DNS masih dapat memungkinkan eksfiltrasi berbasis DNS.
- Proxy hanya mencakup perintah yang di-sandbox. Pencarian web, konektor, server MCP, browser, dan lalu lintas model Codex sendiri menggunakan kontrol terpisah.
- Penulisan dapat bertahan melampaui sesi. Contoh dari OpenAI adalah
node_modules/prettieryang dimanipulasi dan nantinya dijalankan editor Anda saat menyimpan, di luar sandbox.
Jika Anda pernah memakai solusi sementara untuk melewati sandbox Codex, profil kustom yang ketat biasanya menjadi solusi yang lebih bersih. Tim yang memerlukan kebijakan lintas mesin sebaiknya membaca cookbook keamanan Codex dan allowed_permission_profiles yang dikelola.
FAQ
Apa profil izin Codex default?
Tidak ada profil default yang sebaiknya Anda andalkan. Dokumentasi menyarankan untuk mengatur default_permissions secara eksplisit agar perilakunya dapat diprediksi. Untuk sebagian besar pekerjaan coding, :workspace adalah basis yang masuk akal: penulisan di root workspace dan direktori temp, jaringan mati.
Mengapa aturan domain saya diabaikan?
Biasanya karena features.network_proxy tidak disetel. Dengan network.enabled = true dan tanpa proxy, perintah mendapatkan akses jaringan langsung tanpa batasan. Periksa juga bahwa tidak ada config yang termuat yang menyetel sandbox_mode, karena itu menonaktifkan profil sepenuhnya.
Bagaimana cara mencegah Codex membaca file .env?
Tambahkan "**/*.env" = "deny" di bawah [permissions.<name>.filesystem.":workspace_roots"]. Di Linux, WSL, dan Windows, atur glob_scan_max_depth untuk pola ** yang tak terbatas, dan ingat bahwa kecocokan baru tidak ditambahkan ke proses yang sudah berjalan.
Bisakah saya mengizinkan localhost dalam profil izin Codex?
Bisa. Masukkan host literal ke daftar izin, seperti "localhost" = "allow" atau "127.0.0.1" = "allow". Atur allow_local_binding = true hanya ketika hostname yang masuk daftar izin di-resolve ke alamat lokal atau privat.
Apakah profil izin men-sandbox server MCP?
Tidak. Server MCP stdio di config.toml mulai tanpa sandbox. Bungkus perintah server dengan codex sandbox --permission-profile <name> -- memakai profilnya sendiri.
Bisakah saya menggunakan profil bersama flag --sandbox?
Tidak. Meneruskan --sandbox atau menyetel sandbox_mode membuat Codex memakai pengaturan sandbox lama alih-alih default_permissions. Pilih satu sistem per sesi.
