​

Sandbox vs Kebijakan Alat vs Elevated

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) menentukan di mana alat dijalankan (Docker vs 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 jalur keluar khusus exec untuk berjalan di luar sandbox saat Anda berada dalam sandbox (gateway secara default, atau node saat target exec dikonfigurasi ke node).

​

Debug cepat

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

• mode/cakupan/akses workspace sandbox yang efektif
• apakah sesi saat ini berada dalam sandbox (main vs non-main)
• allow/deny alat sandbox yang efektif (dan apakah berasal dari agent/global/default)
• gerbang elevated dan path kunci perbaikan

​

Sandbox: tempat alat dijalankan

• "off": semuanya berjalan di host.
• "non-main": hanya sesi non-main yang berada dalam sandbox (sering menjadi “kejutan” umum untuk grup/channel).
• "all": semuanya berada dalam sandbox.

​

Bind mount (pemeriksaan keamanan cepat)

• docker.binds menembus filesystem sandbox: apa pun yang Anda mount akan terlihat di dalam container dengan mode yang Anda tetapkan (:ro atau :rw).
• Default-nya adalah read-write jika Anda menghilangkan mode; utamakan :ro untuk source/secret.
• scope: "shared" mengabaikan bind per-agent (hanya bind global yang berlaku).
• OpenClaw memvalidasi sumber bind dua kali: pertama pada path sumber yang telah dinormalisasi, lalu sekali lagi setelah menyelesaikannya melalui ancestor terdalam yang ada. Escape melalui parent symlink tidak melewati pemeriksaan blocked-path atau allowed-root.
• Path leaf yang belum ada tetap diperiksa dengan aman. Jika /workspace/alias-out/new-file diselesaikan melalui parent yang disymlink ke path yang diblokir atau ke luar allowed roots yang dikonfigurasi, bind akan ditolak.
• Melakukan bind pada /var/run/docker.sock secara efektif memberikan kontrol host ke sandbox; lakukan ini hanya dengan sengaja.
• Akses workspace (workspaceAccess: "ro"/"rw") independen dari mode bind.

​

Kebijakan alat: alat mana yang ada/dapat dipanggil

• Profil alat: tools.profile dan agents.list[].tools.profile (allowlist dasar)
• Profil alat provider: tools.byProvider[provider].profile dan agents.list[].tools.byProvider[provider].profile
• Kebijakan alat global/per-agent: tools.allow/tools.deny dan agents.list[].tools.allow/agents.list[].tools.deny
• Kebijakan alat provider: tools.byProvider[provider].allow/deny dan agents.list[].tools.byProvider[provider].allow/deny
• Kebijakan alat sandbox (hanya berlaku saat dalam sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny dan agents.list[].tools.sandbox.tools.*

• deny selalu menang.
• Jika allow tidak kosong, semua yang lain dianggap diblokir.
• Kebijakan alat adalah penghentian keras: /exec tidak dapat mengesampingkan alat exec yang ditolak.
• /exec hanya mengubah default sesi untuk pengirim yang berwenang; perintah ini tidak memberikan akses alat. Kunci alat provider menerima provider (misalnya google-antigravity) atau provider/model (misalnya openai/gpt-5.4).

​

Grup alat (singkatan)

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

• 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: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:agents: agents_list
• group:media: image, image_generate, video_generate, tts
• group:openclaw: semua alat OpenClaw bawaan (tidak termasuk plugin provider)

​

Elevated: “jalankan di host” khusus exec

• Jika Anda berada dalam sandbox, /elevated on (atau exec dengan elevated: true) akan berjalan di luar sandbox (persetujuan mungkin tetap berlaku).
• Gunakan /elevated full untuk melewati persetujuan exec untuk sesi tersebut.
• Jika Anda sudah berjalan secara langsung, elevated pada dasarnya tidak berpengaruh (tetap berada di balik gerbang).
• Elevated tidak dibatasi per skill dan tidak mengesampingkan allow/deny alat.
• Elevated tidak memberikan override lintas host sembarang dari host=auto; fitur ini mengikuti aturan target exec normal dan hanya mempertahankan node saat target yang dikonfigurasi/sesi memang sudah node.
• /exec terpisah dari elevated. Perintah ini hanya menyesuaikan default exec per sesi untuk pengirim yang berwenang.

• Pengaktifan: tools.elevated.enabled (dan secara opsional agents.list[].tools.elevated.enabled)
• Allowlist pengirim: tools.elevated.allowFrom.<provider> (dan secara opsional agents.list[].tools.elevated.allowFrom.<provider>)

​

Perbaikan umum “sandbox jail"

​

"Alat X diblokir oleh kebijakan alat sandbox”

• Nonaktifkan sandbox: agents.defaults.sandbox.mode=off (atau per-agent agents.list[].sandbox.mode=off)
• Izinkan alat tersebut di dalam sandbox:
  • hapus dari tools.sandbox.tools.deny (atau per-agent agents.list[].tools.sandbox.tools.deny)
  • atau tambahkan ke tools.sandbox.tools.allow (atau allow per-agent)

​

“Saya kira ini main, kenapa berada dalam sandbox?”

​

Lihat juga

• Sandboxing — referensi sandbox lengkap (mode, cakupan, backend, image)
• Multi-Agent Sandbox & Tools — override per-agent dan prioritas
• Elevated Mode