Sandboxing

OpenClaw dapat menjalankan eksekusi alat di dalam backend sandbox untuk mengurangi radius dampak. 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 berpindah ke sandbox saat diaktifkan.

Apa yang dimasukkan ke sandbox

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

Tidak dimasukkan ke sandbox:

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

Mode, cakupan, dan backend

Tiga pengaturan independen mengendalikan perilaku sandbox:

Mode mengendalikan kapan sandboxing diterapkan:

• off: tanpa sandboxing.
• non-main: masukkan setiap sesi ke sandbox kecuali sesi utama agen. Kunci sesi utama selalu agent:<agentId>:main (atau global saat session.scope adalah "global"); kunci ini tidak dapat dikonfigurasi. Sesi grup/saluran menggunakan kuncinya sendiri, sehingga selalu dianggap bukan sesi utama dan dimasukkan ke sandbox.
• all: setiap sesi berjalan di 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 (penggantian per agen docker/ssh/browser 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 browser 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 mengekspos GPU host, atur agents.defaults.sandbox.docker.gpus (atau penggantian 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.

Browser dalam sandbox

• Browser sandbox dimulai secara otomatis (memastikan CDP dapat dijangkau) saat alat browser membutuhkannya. Konfigurasikan melalui agents.defaults.sandbox.browser.autoStart (default true) dan autoStartTimeoutMs (default 12 dtk).
• Kontainer browser sandbox menggunakan jaringan Docker khusus (openclaw-sandbox-browser), bukan jaringan global bridge. Konfigurasikan dengan agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange membatasi akses masuk CDP pada tepi kontainer dengan 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 browser host secara eksplisit.
• Daftar izin opsional membatasi target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Gunakan backend: "ssh" untuk memasukkan exec, alat berkas, dan pembacaan media ke 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",          // Atau gunakan SecretRefs / konten sebaris sebagai pengganti berkas lokal:          // 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 root jarak jauh per cakupan di bawah sandbox.ssh.workspaceRoot. Pada penggunaan pertama setelah dibuat atau dibuat ulang, OpenClaw menyemai ruang kerja jarak jauh tersebut dari ruang kerja lokal satu kali. Setelah itu, exec, read, write, edit, apply_patch, pembacaan media prompt, dan penyiapan media masuk berjalan langsung terhadap ruang kerja jarak jauh melalui SSH. OpenClaw tidak secara otomatis menyinkronkan perubahan jarak jauh kembali ke ruang kerja lokal.
• Materi autentikasi: identityFile/certificateFile/knownHostsFile merujuk ke berkas lokal yang ada. identityData/certificateData/knownHostsData menerima string sebaris atau SecretRefs, yang diselesaikan melalui snapshot runtime rahasia normal, ditulis ke berkas sementara dengan mode 0600, dan dihapus saat 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 status sandbox yang sebenarnya setelah penyemaian awal. Perubahan lokal host yang dibuat di luar OpenClaw setelah langkah penyemaian tidak terlihat dari jarak jauh hingga Anda membuat ulang sandbox. openclaw sandbox recreate menghapus root jarak jauh per cakupan dan menyemai ulang dari lokal pada penggunaan berikutnya. Sandboxing browser tidak didukung pada backend ini, dan pengaturan sandbox.docker.* tidak berlaku untuk backend ini.

Backend OpenShell

Gunakan backend: "openshell" untuk memasukkan alat ke sandbox dalam lingkungan jarak jauh yang dikelola OpenShell. OpenShell menggunakan kembali transportasi SSH dan jembatan sistem berkas jarak jauh yang sama seperti 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 sandbox sebelum exec dan menyinkronkannya kembali setelahnya. mode: "remote" menginisialisasi ruang kerja jarak jauh satu kali dari ruang kerja lokal, lalu menjalankan exec/read/write/edit/apply_patch langsung pada ruang kerja jarak jauh tanpa menyinkronkannya kembali; perubahan lokal setelah inisialisasi tidak terlihat hingga Anda melakukan openclaw sandbox recreate. Dalam scope: "agent" atau scope: "shared", ruang kerja jarak jauh tersebut dibagikan pada cakupan yang sama. Keterbatasan saat ini: browser 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 menyadari backend.

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

Akses ruang kerja

agents.defaults.sandbox.workspaceAccess mengontrol apa yang dapat dilihat 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 kanonis setelah inisialisasi awal, dan workspaceAccess: "ro"/"none" tetap membatasi perilaku penulisan dengan cara yang sama.

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

Beberapa folder untuk satu agen

Gunakan pemasangan bind Docker ketika satu agen dalam sandbox memerlukan lebih dari ruang kerja utamanya. Setiap entri memetakan folder host ke jalur kontainer dengan mode akses eksplisit:

host-directory:container-directory:rohost-directory:container-directory:rw

• ro menjadikan folder yang dipasang hanya-baca di dalam sandbox.
• rw memungkinkan alat dan proses dalam sandbox mengubah folder host.
• Jalur kontainer adalah jalur yang digunakan agen. Jalur host tidak diekspos secara otomatis.

Contoh ini memberi agen research ruang kerja utama yang dapat ditulis, materi referensi hanya-baca di /reference, dan folder keluaran terpisah yang dapat ditulis di /drafts:

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // Diperlukan karena sumber-sumber ini berada di luar ruang kerja agen.            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess dan mode bind bersifat independen:

Mengubah workspaceAccess tidak mengubah bind tambahan dari ro menjadi rw, atau sebaliknya. docker.binds global dan per agen digabungkan. Pertahankan scope: "agent" atau "session" untuk bind per agen; scope: "shared" mengabaikan semua penggantian Docker per agen dan hanya menggunakan bind global.

Pemasangan bind merupakan batas beberapa folder yang didukung karena Docker membentuk tampilan sistem berkas kontainer dengan isolasi pemasangan, dan mode ro/rw berlaku untuk setiap proses dalam sandbox. Batas tersebut mencakup exec, alat sistem berkas, proses anak, dan pustaka tanpa menduplikasi pemeriksaan otorisasi jalur di setiap jalur kode OpenClaw. Daftar izin jalur pada sisi host tidak dapat menyediakan batas lengkap yang sama ketika shell atau dependensi yang diizinkan dapat mengakses berkas secara langsung.

dangerouslyAllowExternalBindSources yang harus diaktifkan secara eksplisit hanya mengizinkan sumber di luar akar ruang kerja. Opsi ini tidak menonaktifkan pemeriksaan OpenClaw terhadap sistem yang diblokir, kredensial, soket Docker, induk symlink, atau target yang dicadangkan. Pilih folder sekecil mungkin, gunakan ro kecuali penulisan diperlukan, dan buat ulang sandbox setelah mengubah pemasangan:

openclaw sandbox recreate --agent research

Perilaku bind lainnya

agents.defaults.sandbox.docker.binds mengonfigurasi pemasangan global. Formatnya menggunakan bentuk host:container:mode yang sama (misalnya, "/home/user/source:/source:rw").

agents.defaults.sandbox.browser.binds memasang direktori host tambahan hanya ke kontainer browser sandbox. Jika ditetapkan (termasuk []), opsi ini menggantikan docker.binds untuk kontainer browser; jika dihilangkan, kontainer browser 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"],          },        },      },    ],  },}

Image dan penyiapan

Image Docker default: 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 default, kontainer sandbox Docker berjalan tanpa jaringan. Ganti perilaku ini dengan agents.defaults.sandbox.docker.network.

Instalasi Docker dan Gateway dalam kontainer tersedia di sini: Docker

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

setupCommand (penyiapan kontainer satu kali)

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

Jalur:

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

Kebijakan alat dan jalur pengabaian

Kebijakan izin/penolakan alat tetap berlaku sebelum aturan sandbox. Jika suatu alat ditolak secara global atau per agen, sandbox tidak akan mengaktifkannya kembali.

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

Debugging:

• openclaw sandbox list menampilkan kontainer sandbox, status, kecocokan image, usia, waktu tidak aktif, serta sesi/agen yang 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. Kolom workspaceRoot tetap menunjukkan root sandbox yang dikonfigurasi; effectiveHostWorkspaceRoot menunjukkan lokasi sebenarnya dari ruang kerja yang aktif.
• 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?".

Penggantian konfigurasi multiagen

Setiap agen dapat mengganti konfigurasi sandbox + alat: agents.list[].sandbox dan agents.list[].tools (serta 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 Multiagen -- penggantian konfigurasi per agen dan urutan prioritas
• OpenShell -- penyiapan backend sandbox terkelola, mode ruang kerja, dan referensi konfigurasi
• Konfigurasi sandbox
• Sandbox vs Kebijakan Alat vs Elevated -- debugging "mengapa ini diblokir?"
• Keamanan