--- read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change. status: active summary: 'Mengapa suatu alat diblokir: runtime sandbox, kebijakan izin/tolak alat, dan gerbang eksekusi dengan hak istimewa yang lebih tinggi' title: Sandbox vs kebijakan alat vs hak akses yang ditingkatkan x-i18n: generated_at: "2026-07-12T14:15:36Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 2fce3dab337e89fc2b196f59e763a169d76206ce2695744e00252c158b161260 source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md workflow: 16 --- OpenClaw memiliki tiga kontrol yang saling terkait tetapi berbeda: 1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) menentukan **tempat alat dijalankan** (backend sandbox atau host). 2. **Kebijakan alat** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) menentukan **alat mana yang tersedia/diizinkan**. 3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) adalah **jalan keluar khusus `exec`** untuk menjalankan di luar sandbox ketika Anda berada dalam sandbox (`gateway` secara default, atau `node` ketika target exec dikonfigurasi sebagai `node`). ## Debug cepat Gunakan pemeriksa untuk melihat apa yang _sebenarnya_ dilakukan OpenClaw: ```bash openclaw sandbox explain openclaw sandbox explain --session agent:main:main openclaw sandbox explain --agent work openclaw sandbox explain --json ``` Perintah ini menampilkan: - mode/cakupan/akses ruang kerja sandbox yang efektif - apakah sesi saat ini berada dalam sandbox (utama atau non-utama) - aturan izinkan/tolak alat sandbox yang efektif (dan apakah aturan tersebut berasal dari agen/global/default) - gerbang elevated dan jalur kunci perbaikan ## Sandbox: tempat alat dijalankan Penggunaan sandbox dikontrol oleh `agents.defaults.sandbox.mode`: - `"off"`: semuanya berjalan pada host. - `"non-main"`: hanya sesi non-utama yang berada dalam sandbox (hal yang sering "mengejutkan" untuk grup/saluran). - `"all"`: semuanya berada dalam sandbox. `agents.defaults.sandbox.workspaceAccess` mengontrol apa yang dapat dilihat sandbox: `"none"`, `"ro"`, atau `"rw"`. Lihat [Penggunaan sandbox](/id/gateway/sandboxing) untuk matriks lengkap (cakupan, pemasangan ruang kerja, citra). ### Bind mount (pemeriksaan keamanan cepat) - `docker.binds` _menembus_ sistem berkas sandbox: apa pun yang Anda pasang akan terlihat di dalam kontainer dengan mode yang Anda tetapkan (`:ro` atau `:rw`). - Mode default adalah baca-tulis jika Anda tidak mencantumkan mode; utamakan `:ro` untuk sumber/rahasia. - `scope: "shared"` mengabaikan bind per agen (hanya bind global yang berlaku). - OpenClaw memvalidasi sumber bind dua kali: pertama pada jalur sumber yang telah dinormalisasi, lalu sekali lagi setelah menyelesaikannya melalui leluhur terdalam yang ada. Pelolosan melalui induk symlink tidak dapat melewati pemeriksaan jalur yang diblokir atau akar yang diizinkan. - Jalur daun yang belum ada tetap diperiksa dengan aman. Jika `/workspace/alias-out/new-file` diselesaikan melalui induk symlink menuju jalur yang diblokir atau ke luar akar yang dikonfigurasi, bind akan ditolak. - Mengikat `/var/run/docker.sock` secara efektif memberikan kendali host kepada sandbox; lakukan ini hanya secara sengaja. - Akses ruang kerja (`workspaceAccess`) tidak bergantung pada mode bind. ## Kebijakan alat: alat yang tersedia/dapat dipanggil Dua lapisan berpengaruh: - **Profil alat**: `tools.profile` dan `agents.list[].tools.profile` (daftar izin dasar) - **Profil alat penyedia**: `tools.byProvider[provider].profile` dan `agents.list[].tools.byProvider[provider].profile` - **Kebijakan alat global/per agen**: `tools.allow`/`tools.deny` dan `agents.list[].tools.allow`/`agents.list[].tools.deny` - **Kebijakan alat penyedia**: `tools.byProvider[provider].allow/deny` dan `agents.list[].tools.byProvider[provider].allow/deny` - **Kebijakan alat sandbox** (hanya berlaku saat berada dalam sandbox): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` dan `agents.list[].tools.sandbox.tools.*` Pedoman praktis: - `deny` selalu diutamakan. - Jika `allow` tidak kosong, semua yang lain dianggap diblokir. - Kebijakan alat adalah penghentian mutlak: `/exec` tidak dapat mengabaikan alat `exec` yang ditolak. - Kebijakan alat menyaring ketersediaan alat berdasarkan nama; kebijakan ini tidak memeriksa efek samping di dalam `exec`. Jika `exec` diizinkan, menolak `write`, `edit`, atau `apply_patch` tidak membuat perintah shell menjadi hanya-baca. - `/exec` hanya mengubah default sesi untuk pengirim yang berwenang; perintah ini tidak memberikan akses alat. - Kunci alat penyedia menerima `provider` (misalnya `google-antigravity`) atau `provider/model` (misalnya `openai/gpt-5.4`). - Log Gateway menyertakan entri audit `agents/tool-policy` ketika suatu langkah kebijakan alat menghapus alat atau kebijakan alat sandbox memblokir panggilan. Gunakan `openclaw logs` untuk melihat label aturan, kunci konfigurasi, dan nama alat yang terdampak. ### Grup alat (singkatan) Kebijakan alat (global, agen, sandbox) mendukung entri `group:*` yang diperluas menjadi beberapa alat: ```json5 { tools: { sandbox: { tools: { allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"], }, }, }, } ``` Grup yang tersedia: | Grup | Alat | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | | `group:web` | `web_search`, `x_search`, `web_fetch` | | `group:ui` | `browser`, `canvas` | | `group:automation` | `heartbeat_respond`, `cron`, `gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes`, `computer` | | `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop` | | `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | | `group:openclaw` | sebagian besar alat bawaan OpenClaw (tidak mencakup primitif sistem berkas dan waktu proses `read`/`write`/`edit`/`apply_patch`/`exec`/`process`, `canvas`, serta plugin penyedia) | | `group:plugins` | semua alat milik plugin yang dimuat, termasuk server MCP yang dikonfigurasi dan diekspos melalui `bundle-mcp` | Untuk agen hanya-baca, tolak `group:runtime` serta alat sistem berkas yang dapat mengubah data, kecuali kebijakan sistem berkas sandbox atau batas host terpisah memberlakukan pembatasan hanya-baca. Untuk server MCP dalam sandbox, kebijakan alat sandbox merupakan gerbang izin kedua. Jika `mcp.servers` dikonfigurasi tetapi giliran dalam sandbox hanya menampilkan alat bawaan, tambahkan `bundle-mcp`, `group:plugins`, atau nama/pola glob alat MCP berawalan server seperti `outlook__send_mail` atau `outlook__*` ke `tools.sandbox.tools.alsoAllow`, lalu mulai ulang/muat ulang Gateway dan ambil kembali daftar alat. Pola glob server menggunakan awalan server MCP yang aman bagi penyedia: karakter selain `[A-Za-z0-9_-]` menjadi `-`, nama yang tidak diawali huruf mendapat awalan `mcp-`, dan awalan yang panjang atau duplikat dapat dipotong atau diberi akhiran. `openclaw doctor` saat ini memeriksa bentuk ini untuk server yang dikelola OpenClaw dalam `mcp.servers`. Server MCP yang dimuat dari manifes plugin bawaan atau `.mcp.json` Claude menggunakan gerbang sandbox yang sama, tetapi diagnostik ini belum mencantumkan sumber-sumber tersebut; gunakan entri daftar izin yang sama jika alatnya menghilang dalam giliran yang berada dalam sandbox. ## Elevated: "jalankan pada host" khusus exec Elevated **tidak** memberikan alat tambahan; fitur ini hanya memengaruhi `exec`. - Jika Anda berada dalam sandbox, `/elevated on` (atau `exec` dengan `elevated: true`) berjalan di luar sandbox (persetujuan mungkin tetap berlaku). - Gunakan `/elevated full` untuk melewati persetujuan exec selama sesi. - Jika Anda sudah berjalan secara langsung, elevated pada dasarnya tidak berpengaruh (tetap dibatasi oleh gerbang). - Elevated **tidak** dibatasi berdasarkan skill dan **tidak** mengabaikan aturan izinkan/tolak alat. - Elevated tidak memberikan pengabaian lintas-host sewenang-wenang dari `host=auto`; fitur ini mengikuti aturan target exec normal dan hanya mempertahankan `node` ketika target yang dikonfigurasi/target sesi sudah berupa `node`. - `/exec` terpisah dari elevated. Perintah ini hanya menyesuaikan default exec per sesi untuk pengirim yang berwenang. Gerbang: - Pengaktifan: `tools.elevated.enabled` (dan secara opsional `agents.list[].tools.elevated.enabled`) - Daftar izin pengirim: `tools.elevated.allowFrom.` (dan secara opsional `agents.list[].tools.elevated.allowFrom.`) Lihat [Mode Elevated](/id/tools/elevated). ## Perbaikan umum untuk "penjara sandbox" ### "Alat X diblokir oleh kebijakan alat sandbox" Kunci perbaikan (pilih salah satu): - Nonaktifkan sandbox: `agents.defaults.sandbox.mode=off` (atau per agen `agents.list[].sandbox.mode=off`) - Izinkan alat di dalam sandbox: - hapus alat tersebut dari `tools.sandbox.tools.deny` (atau per agen `agents.list[].tools.sandbox.tools.deny`) - atau tambahkan alat tersebut ke `tools.sandbox.tools.allow` (atau daftar izin per agen) - Periksa `openclaw logs` untuk entri `agents/tool-policy`. Entri tersebut mencatat mode sandbox dan apakah aturan izinkan atau tolak memblokir alat. ### "Saya kira ini sesi utama, mengapa berada dalam sandbox?" Dalam mode `"non-main"`, kunci grup/saluran _bukan_ utama. Gunakan kunci sesi utama (ditampilkan oleh `sandbox explain`) atau ubah mode menjadi `"off"`. ## Terkait - [Penggunaan sandbox](/id/gateway/sandboxing) -- referensi lengkap sandbox (mode, cakupan, backend, citra) - [Sandbox & Alat Multi-Agen](/id/tools/multi-agent-sandbox-tools) -- pengabaian per agen dan urutan prioritas - [Mode Elevated](/id/tools/elevated)