Isolasi kotak pasir

OpenClaw dapat menjalankan alat di dalam backend sandbox untuk mengurangi jangkauan dampak. Ini opsional dan dikontrol oleh konfigurasi (agents.defaults.sandbox atau agents.list[].sandbox). Jika sandboxing nonaktif, alat berjalan di host. Gateway tetap berada di host; eksekusi alat berjalan di sandbox terisolasi saat diaktifkan.

Apa yang dimasukkan ke sandbox

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

Tidak dimasukkan ke sandbox:

• Proses Gateway itu sendiri.
• Alat apa pun yang secara eksplisit diizinkan berjalan di luar sandbox (mis. tools.elevated).
  • Elevated exec melewati sandboxing dan menggunakan jalur escape yang dikonfigurasi (gateway secara default, atau node saat target exec adalah node).
  • Jika sandboxing nonaktif, tools.elevated tidak mengubah eksekusi (sudah berada di host). Lihat Mode Elevated.

Mode

agents.defaults.sandbox.mode mengontrol kapan sandboxing digunakan:

Cakupan

agents.defaults.sandbox.scope mengontrol berapa banyak kontainer yang dibuat:

• "agent" (default): satu kontainer per agen.
• "session": satu kontainer per sesi.
• "shared": satu kontainer yang dibagikan oleh semua sesi dalam sandbox.

Backend

agents.defaults.sandbox.backend mengontrol runtime mana yang menyediakan sandbox:

• "docker" (default saat sandboxing diaktifkan): runtime sandbox lokal berbasis Docker.
• "ssh": runtime sandbox jarak jauh generik berbasis SSH.
• "openshell": runtime sandbox berbasis OpenShell.

Konfigurasi khusus SSH berada di bawah agents.defaults.sandbox.ssh. Konfigurasi khusus OpenShell berada di bawah plugins.entries.openshell.config.

Memilih backend

Backend Docker

Sandboxing nonaktif secara default. Jika Anda mengaktifkan sandboxing dan tidak memilih backend, OpenClaw menggunakan backend Docker. Backend ini mengeksekusi alat dan peramban sandbox secara lokal melalui socket daemon Docker (/var/run/docker.sock). Isolasi kontainer sandbox ditentukan oleh namespace Docker.

Untuk mengekspos GPU host ke sandbox Docker, atur agents.defaults.sandbox.docker.gpus atau override per agen agents.list[].sandbox.docker.gpus. Nilainya diteruskan ke flag --gpus milik Docker sebagai argumen terpisah, misalnya "all" atau "device=GPU-uuid", dan memerlukan runtime host yang kompatibel seperti NVIDIA Container Toolkit.

Backend SSH

Gunakan backend: "ssh" saat Anda ingin OpenClaw memasukkan exec, alat file, dan pembacaan media ke sandbox pada mesin arbitrer yang dapat diakses 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" },        },      },    },  },}

Backend OpenShell

Gunakan backend: "openshell" saat Anda ingin OpenClaw memasukkan alat ke sandbox di lingkungan jarak jauh yang dikelola OpenShell. Untuk panduan penyiapan lengkap, referensi konfigurasi, dan perbandingan mode workspace, lihat halaman OpenShell khusus.

OpenShell menggunakan ulang transport SSH inti dan bridge filesystem jarak jauh yang sama dengan backend SSH generik, serta menambahkan lifecycle khusus OpenShell (sandbox create/get/delete, sandbox ssh-config) plus mode workspace 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          remoteWorkspaceDir: "/sandbox",          remoteAgentWorkspaceDir: "/agent",        },      },    },  },}

Mode OpenShell:

• mirror (default): workspace lokal tetap canonical. OpenClaw menyinkronkan file lokal ke OpenShell sebelum exec dan menyinkronkan workspace jarak jauh kembali setelah exec.
• remote: workspace OpenShell menjadi canonical setelah sandbox dibuat. OpenClaw melakukan seed workspace jarak jauh sekali dari workspace lokal, lalu alat file dan exec berjalan langsung terhadap sandbox jarak jauh tanpa menyinkronkan perubahan kembali.

Mode workspace

OpenShell memiliki dua model workspace. Inilah bagian yang paling penting dalam praktik.

Pilih mirror jika Anda menganggap sandbox sebagai lingkungan eksekusi sementara. Pilih remote jika Anda menganggap sandbox sebagai workspace yang sebenarnya.

Siklus hidup OpenShell

Sandbox OpenShell tetap dikelola melalui siklus hidup sandbox normal:

• openclaw sandbox list menampilkan runtime OpenShell sekaligus runtime Docker
• openclaw sandbox recreate menghapus runtime saat ini dan membiarkan OpenClaw membuatnya ulang pada penggunaan berikutnya
• logika prune juga sadar backend

Untuk mode remote, pembuatan ulang sangat penting:

• recreate menghapus workspace remote kanonis untuk cakupan tersebut
• penggunaan berikutnya mengisi workspace remote baru dari workspace lokal

Untuk mode mirror, recreate terutama mereset lingkungan eksekusi remote karena workspace lokal tetap kanonis.

Akses workspace

agents.defaults.sandbox.workspaceAccess mengontrol apa yang dapat dilihat sandbox:

Dengan backend OpenShell:

• mode mirror tetap menggunakan workspace lokal sebagai sumber kanonis antar giliran exec
• mode remote menggunakan workspace OpenShell remote sebagai sumber kanonis setelah seed awal
• workspaceAccess: "ro" dan "none" tetap membatasi perilaku penulisan dengan cara yang sama

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

Bind mount kustom

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 browser sandbox.

• Ketika ditetapkan (termasuk []), ini menggantikan agents.defaults.sandbox.docker.binds untuk kontainer browser.
• Ketika dihilangkan, kontainer browser menggunakan fallback ke agents.defaults.sandbox.docker.binds (kompatibel mundur).

Contoh (source hanya-baca + direktori data tambahan):

{  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 dengan tanpa jaringan. Ganti dengan agents.defaults.sandbox.docker.network.

Instalasi Docker dan gateway dalam kontainer berada di sini: Docker

Untuk deployment gateway Docker, scripts/docker/setup.sh dapat melakukan bootstrap konfigurasi sandbox. Tetapkan OPENCLAW_SANDBOX=1 (atau true/yes/on) untuk mengaktifkan path tersebut. Anda dapat mengganti lokasi socket dengan OPENCLAW_DOCKER_SOCKET. Referensi penyiapan lengkap dan env: Docker.

setupCommand (penyiapan kontainer satu kali)

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

Path:

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

Kebijakan tool dan jalur keluar

Kebijakan izinkan/tolak tool tetap berlaku sebelum aturan sandbox. Jika sebuah tool ditolak secara global atau per-agent, sandboxing tidak mengaktifkannya kembali.

tools.elevated adalah jalur keluar eksplisit yang menjalankan exec di luar sandbox (gateway secara default, atau node ketika target exec adalah node). Direktif /exec hanya berlaku untuk pengirim yang diotorisasi dan bertahan per sesi; untuk menonaktifkan exec secara tegas, gunakan penolakan kebijakan tool (lihat Sandbox vs Tool Policy vs Elevated).

Debugging:

• Gunakan openclaw sandbox explain untuk memeriksa mode sandbox efektif, kebijakan tool, dan kunci konfigurasi perbaikan.
• Lihat Sandbox vs Tool Policy vs Elevated untuk model mental "mengapa ini diblokir?".

Jaga tetap terkunci.

Override multi-agent

Setiap agent dapat meng-override sandbox + tools: agents.list[].sandbox dan agents.list[].tools (ditambah agents.list[].tools.sandbox.tools untuk kebijakan tool sandbox). Lihat Multi-Agent Sandbox & Tools untuk presedensi.

Contoh aktivasi minimal

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

Terkait

• Multi-Agent Sandbox & Tools — override per-agent dan presedensi
• OpenShell — penyiapan backend sandbox terkelola, mode workspace, dan referensi konfigurasi
• Konfigurasi sandbox
• Sandbox vs Tool Policy vs Elevated — debugging "mengapa ini diblokir?"
• Keamanan