Sandbox vs kebijakan alat vs hak istimewa yang ditingkatkan

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) menentukan di mana tool dijalankan (backend sandbox vs host).
2. Kebijakan tool (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) menentukan tool mana yang tersedia/diizinkan.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) adalah jalan keluar khusus exec untuk menjalankan 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 sandbox/akses workspace efektif
• apakah sesi saat ini berada dalam sandbox (main vs non-main)
• allow/deny tool sandbox efektif (dan apakah berasal dari agent/global/default)
• gerbang elevated dan path kunci perbaikan

​

Sandbox: tempat tool dijalankan

• "off": semuanya berjalan di host.
• "non-main": hanya sesi non-main yang berada dalam sandbox (“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 terlihat di dalam container dengan mode yang Anda tetapkan (:ro atau :rw).
• Default-nya adalah read-write jika Anda menghilangkan mode; pilih :ro untuk source/secret.
• scope: "shared" mengabaikan bind per-agent (hanya bind global yang berlaku).
• OpenClaw memvalidasi source bind dua kali: pertama pada path source yang dinormalisasi, lalu lagi setelah resolve melalui ancestor terdalam yang ada. Escape melalui parent symlink tidak melewati pemeriksaan path yang diblokir atau root yang diizinkan.
• Path leaf yang tidak ada tetap diperiksa dengan aman. Jika /workspace/alias-out/new-file resolve melalui parent symlink ke path yang diblokir atau ke luar root yang diizinkan yang dikonfigurasi, bind ditolak.
• Binding /var/run/docker.sock secara efektif menyerahkan kontrol host ke sandbox; lakukan ini hanya dengan sengaja.
• Akses workspace (workspaceAccess: "ro"/"rw") independen dari mode bind.

​

Kebijakan tool: tool mana yang ada/dapat dipanggil

• Profil tool: tools.profile dan agents.list[].tools.profile (allowlist dasar)
• Profil tool provider: tools.byProvider[provider].profile dan agents.list[].tools.byProvider[provider].profile
• Kebijakan tool global/per-agent: tools.allow/tools.deny dan agents.list[].tools.allow/agents.list[].tools.deny
• Kebijakan tool provider: tools.byProvider[provider].allow/deny dan agents.list[].tools.byProvider[provider].allow/deny
• Kebijakan tool sandbox (hanya berlaku saat berada 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 diperlakukan sebagai diblokir.
• Kebijakan tool adalah penghentian keras: /exec tidak dapat menimpa tool exec yang ditolak.
• Kebijakan tool memfilter ketersediaan tool 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 read-only.
• /exec hanya mengubah default sesi untuk pengirim yang berwenang; ini tidak memberikan akses tool. Kunci tool provider menerima provider (mis. google-antigravity) atau provider/model (mis. openai/gpt-5.4).

​

Grup tool (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 Untuk agent read-only, tolak group:runtime serta tool filesystem yang memutasi kecuali kebijakan filesystem sandbox atau batas host terpisah memberlakukan batasan read-only.
• 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
• group:agents: agents_list, update_plan
• group:media: image, image_generate, music_generate, video_generate, tts
• group:openclaw: semua tool bawaan OpenClaw (tidak mencakup Plugin provider)

​

Elevated: “jalankan di host” khusus exec

• Jika Anda berada dalam sandbox, /elevated on (atau exec dengan elevated: true) berjalan di luar sandbox (approval mungkin tetap berlaku).
• Gunakan /elevated full untuk melewati approval exec untuk sesi.
• Jika Anda sudah berjalan langsung, elevated secara efektif tidak melakukan apa pun (tetap melalui gerbang).
• Elevated tidak ber-cakupan skill dan tidak menimpa allow/deny tool.
• Elevated tidak memberikan override lintas-host arbitrer dari host=auto; ini mengikuti aturan target exec normal dan hanya mempertahankan node saat target yang dikonfigurasi/sesi sudah node.
• /exec terpisah dari elevated. Ini hanya menyesuaikan default exec per-sesi untuk pengirim yang berwenang.

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

​

Perbaikan umum “penjara sandbox"

​

"Tool X diblokir oleh kebijakan tool sandbox”

• Nonaktifkan sandbox: agents.defaults.sandbox.mode=off (atau per-agent agents.list[].sandbox.mode=off)
• Izinkan tool 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, mengapa berada dalam sandbox?”

​

Terkait

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