Sandboxing

OpenClaw dapat menjalankan eksekusi alat di dalam backend sandbox untuk mengurangi dampak kerusakan. Sandboxing dinonaktifkan secara default dan dikendalikan oleh agents.defaults.sandbox (global) atau agents.list[].sandbox (per agen). Proses Gateway selalu tetap berada di host; hanya eksekusi alat yang dipindahkan ke sandbox saat diaktifkan.

Apa yang dijalankan dalam sandbox

• Eksekusi alat: exec, read, write, edit, apply_patch, process, dan sebagainya.
• Peramban opsional dalam sandbox (agents.defaults.sandbox.browser).

Tidak dijalankan dalam sandbox:

• Proses Gateway itu sendiri.
• Alat apa pun yang secara eksplisit diizinkan berjalan di luar sandbox melalui tools.elevated. Eksekusi dengan hak istimewa melewati sandboxing dan berjalan pada jalur keluar yang dikonfigurasi (gateway secara default, atau node ketika target eksekusinya adalah node). Jika sandboxing dinonaktifkan, tools.elevated tidak mengubah apa pun karena eksekusi sudah berjalan di host. Lihat Mode dengan Hak Istimewa.

Mode, cakupan, dan backend

Tiga pengaturan independen mengendalikan perilaku sandbox:

Mode mengendalikan kapan sandboxing diterapkan:

• off: tanpa sandboxing.
• non-main: jalankan setiap sesi dalam sandbox kecuali sesi utama agen. Kunci sesi utama selalu agent:<agentId>:main (atau global ketika session.scope bernilai "global"); kunci ini tidak dapat dikonfigurasi. Sesi grup/saluran menggunakan kuncinya sendiri, sehingga selalu dianggap bukan sesi utama dan dijalankan dalam sandbox.
• all: setiap sesi berjalan dalam sandbox.

Cakupan mengendalikan jumlah kontainer/lingkungan yang dibuat:

• agent: satu kontainer per agen.
• session: satu kontainer per sesi.
• shared: satu kontainer yang digunakan bersama oleh semua sesi dalam sandbox (penimpaan docker/ssh/browser per agen diabaikan dalam cakupan ini).

Backend mengendalikan runtime yang mengeksekusi alat dalam sandbox. Konfigurasi khusus SSH berada di bawah agents.defaults.sandbox.ssh; konfigurasi khusus OpenShell berada di bawah plugins.entries.openshell.config.

Backend Docker

Docker adalah backend default setelah sandboxing diaktifkan. Backend ini menjalankan alat dan peramban sandbox secara lokal melalui soket daemon Docker (/var/run/docker.sock); isolasi berasal dari namespace Docker.

Default: network: "none" (tanpa akses keluar), readOnlyRoot: true, capDrop: ["ALL"], image openclaw-sandbox:bookworm-slim.

Untuk menyediakan GPU host, atur agents.defaults.sandbox.docker.gpus (atau penimpaan per agen) ke nilai seperti "all" atau "device=GPU-uuid". Nilai ini diteruskan ke flag --gpus milik Docker dan memerlukan runtime host yang kompatibel seperti NVIDIA Container Toolkit.

Peramban dalam sandbox

• Peramban sandbox dimulai secara otomatis (memastikan CDP dapat dijangkau) ketika alat peramban membutuhkannya. Konfigurasikan melalui agents.defaults.sandbox.browser.autoStart (default true) dan autoStartTimeoutMs (default 12 dtk).
• Kontainer peramban sandbox menggunakan jaringan Docker khusus (openclaw-sandbox-browser), bukan jaringan bridge global. Konfigurasikan dengan agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange membatasi akses masuk CDP di tepi kontainer menggunakan daftar izin CIDR (misalnya 172.21.0.1/32).
• Akses pengamat noVNC dilindungi kata sandi secara default; OpenClaw menghasilkan URL token berumur pendek yang menyajikan halaman bootstrap lokal dan membuka noVNC dengan kata sandi di fragmen URL (bukan string kueri atau log header).
• agents.defaults.sandbox.browser.allowHostControl (default false) memungkinkan sesi dalam sandbox menargetkan peramban host secara eksplisit.
• Daftar izin opsional membatasi target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Gunakan backend: "ssh" untuk menjalankan exec, alat berkas, dan pembacaan media dalam sandbox pada mesin apa pun yang dapat diakses melalui SSH.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // Or use SecretRefs / inline contents instead of local files:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

Default: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Siklus hidup: OpenClaw membuat direktori akar jarak jauh per cakupan di bawah sandbox.ssh.workspaceRoot. Pada penggunaan pertama setelah pembuatan atau pembuatan ulang, OpenClaw menginisialisasi ruang kerja jarak jauh tersebut satu kali dari ruang kerja lokal. Setelah itu, exec, read, write, edit, apply_patch, pembacaan media prompt, dan penempatan awal media masuk berjalan langsung terhadap ruang kerja jarak jauh melalui SSH. OpenClaw tidak menyinkronkan perubahan jarak jauh kembali ke ruang kerja lokal secara otomatis.
• Materi autentikasi: identityFile/certificateFile/knownHostsFile merujuk ke berkas lokal yang sudah ada. identityData/certificateData/knownHostsData menerima string inline atau SecretRef, diselesaikan melalui snapshot runtime rahasia normal, ditulis ke berkas sementara dengan mode 0600, dan dihapus ketika sesi SSH berakhir. Jika varian *File dan *Data ditetapkan untuk item yang sama, *Data berlaku untuk sesi tersebut.
• Konsekuensi kanonis-jarak-jauh: ruang kerja SSH jarak jauh menjadi keadaan sandbox yang sebenarnya setelah inisialisasi awal. Pengeditan lokal di host yang dilakukan di luar OpenClaw setelah langkah inisialisasi tidak terlihat dari jarak jauh hingga Anda membuat ulang sandbox. openclaw sandbox recreate menghapus direktori akar jarak jauh per cakupan dan melakukan inisialisasi ulang dari lokal pada penggunaan berikutnya. Sandboxing peramban tidak didukung pada backend ini, dan pengaturan sandbox.docker.* tidak berlaku untuknya.

Backend OpenShell

Gunakan backend: "openshell" untuk menjalankan alat dalam sandbox di lingkungan jarak jauh yang dikelola OpenShell. OpenShell menggunakan kembali transportasi SSH dan bridge sistem berkas jarak jauh yang sama dengan backend SSH generik, serta menambahkan siklus hidup OpenShell (sandbox create/get/delete/ssh-config) dan mode sinkronisasi ruang kerja mirror opsional.

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // mirror | remote        },      },    },  },}

mode: "mirror" (default) mempertahankan ruang kerja lokal sebagai kanonis: OpenClaw menyinkronkan ruang kerja lokal ke dalam sandbox sebelum exec dan menyinkronkannya kembali setelahnya. mode: "remote" menginisialisasi ruang kerja jarak jauh satu kali dari lokal, lalu menjalankan exec/read/write/edit/apply_patch langsung terhadap ruang kerja jarak jauh tanpa menyinkronkannya kembali; pengeditan lokal setelah inisialisasi tidak terlihat hingga Anda menjalankan openclaw sandbox recreate. Dalam scope: "agent" atau scope: "shared", ruang kerja jarak jauh tersebut digunakan bersama pada cakupan yang sama. Keterbatasan saat ini: peramban sandbox belum didukung, dan sandbox.docker.binds tidak berlaku untuk backend ini.

openclaw sandbox list/recreate/prune semuanya memperlakukan runtime OpenShell sama seperti runtime Docker; logika prune memperhitungkan backend.

Untuk prasyarat lengkap, referensi konfigurasi, perbandingan mode ruang kerja, dan detail siklus hidup, lihat OpenShell.

Akses ruang kerja

agents.defaults.sandbox.workspaceAccess mengendalikan apa yang dapat dilihat oleh sandbox:

Dengan backend OpenShell, mode mirror tetap menggunakan ruang kerja lokal sebagai sumber kanonis di antara giliran eksekusi, mode remote menggunakan ruang kerja OpenShell jarak jauh sebagai sumber kanonis setelah penanaman awal, dan workspaceAccess: "ro"/"none" tetap membatasi perilaku penulisan dengan cara yang sama.

Media masuk disalin ke ruang kerja sandbox aktif (media/inbound/*).

Pemasangan bind khusus

agents.defaults.sandbox.docker.binds memasang direktori host tambahan ke dalam kontainer. Format: host:container:mode (misalnya, "/home/user/source:/source:rw").

Bind global dan per agen digabungkan (bukan diganti). Di bawah scope: "shared", bind per agen diabaikan.

agents.defaults.sandbox.browser.binds memasang direktori host tambahan hanya ke dalam kontainer peramban sandbox. Ketika ditetapkan (termasuk []), nilai ini menggantikan docker.binds untuk kontainer peramban; ketika dihilangkan, kontainer peramban kembali menggunakan docker.binds.

{  agents: {    defaults: {      sandbox: {        docker: {          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],        },      },    },    list: [      {        id: "build",        sandbox: {          docker: {            binds: ["/mnt/cache:/cache:rw"],          },        },      },    ],  },}

Citra dan penyiapan

Citra Docker bawaan: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Secara bawaan, kontainer sandbox Docker berjalan tanpa jaringan. Timpa dengan agents.defaults.sandbox.docker.network.

Instalasi Docker dan Gateway dalam kontainer tersedia di sini: Docker

Untuk penerapan Gateway Docker, scripts/docker/setup.sh dapat melakukan bootstrap konfigurasi sandbox. Tetapkan OPENCLAW_SANDBOX=1 (atau true/yes/on) untuk mengaktifkan jalur tersebut. Timpa lokasi soket dengan OPENCLAW_DOCKER_SOCKET. Referensi penyiapan lengkap dan variabel lingkungan: Docker.

setupCommand (penyiapan kontainer satu kali)

setupCommand berjalan sekali setelah kontainer sandbox dibuat (bukan pada setiap proses). Perintah ini dieksekusi di dalam kontainer melalui sh -lc.

Jalur:

• Global: agents.defaults.sandbox.docker.setupCommand
• Per agen: agents.list[].sandbox.docker.setupCommand

Kebijakan alat dan jalur keluar darurat

Kebijakan izin/tolak alat tetap berlaku sebelum aturan sandbox. Jika sebuah alat ditolak secara global atau per agen, sandboxing tidak mengaktifkannya kembali.

tools.elevated adalah jalur keluar eksplisit yang menjalankan exec di luar sandbox (gateway secara bawaan, atau node ketika target eksekusi adalah node). Direktif /exec hanya berlaku untuk pengirim yang diotorisasi dan bertahan per sesi; untuk menonaktifkan exec sepenuhnya, gunakan penolakan kebijakan alat (lihat Sandbox vs Kebijakan Alat vs Elevated).

Debugging:

• openclaw sandbox list menampilkan kontainer sandbox, status, kecocokan citra, usia, waktu menganggur, serta sesi/agen terkait.
• openclaw sandbox explain [--session <key>] [--agent <id>] memeriksa mode sandbox efektif, ruang kerja host, direktori kerja runtime, pemasangan Docker, kebijakan alat, dan kunci konfigurasi perbaikan. Bidang workspaceRoot tetap merupakan akar sandbox yang dikonfigurasi; effectiveHostWorkspaceRoot menunjukkan lokasi ruang kerja aktif yang sebenarnya.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] menghapus kontainer/lingkungan agar dibuat ulang dengan konfigurasi saat ini pada penggunaan berikutnya.
• Lihat Sandbox vs Kebijakan Alat vs Elevated untuk model mental "mengapa ini diblokir?".

Penimpaan multiagen

Setiap agen dapat menimpa sandbox + alat: agents.list[].sandbox dan agents.list[].tools (ditambah agents.list[].tools.sandbox.tools untuk kebijakan alat sandbox). Lihat Sandbox & Alat Multiagen untuk urutan prioritas.

Contoh pengaktifan minimal

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

Terkait

• Sandbox & Alat Multi-Agen -- penggantian khusus per agen dan urutan prioritas
• OpenShell -- penyiapan backend sandbox terkelola, mode ruang kerja, dan referensi konfigurasi
• Konfigurasi sandbox
• Sandbox vs Kebijakan Alat vs Hak Istimewa -- men-debug "mengapa ini diblokir?"
• Keamanan