Isolasi Lingkungan Terbatas

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

Apa yang dimasukkan ke sandbox

• Eksekusi alat (exec, read, write, edit, apply_patch, process, dll.).
• Peramban 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 (misalnya tools.elevated).
  • Elevated exec melewati sandboxing dan menggunakan jalur keluar 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 yang dimasukkan ke sandbox.

Backend

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

• "docker" (default saat sandboxing diaktifkan): runtime sandbox berbasis Docker lokal.
• "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 soket daemon Docker (/var/run/docker.sock). Isolasi kontainer sandbox ditentukan oleh namespace Docker.

Untuk mengekspos GPU host ke sandbox Docker, setel agents.defaults.sandbox.docker.gpus atau override per agen agents.list[].sandbox.docker.gpus. Nilai tersebut diteruskan ke flag --gpus 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 berkas, 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 dalam 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 jembatan sistem berkas jarak jauh yang sama seperti backend SSH generik, serta menambahkan siklus hidup 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 kanonis. OpenClaw menyinkronkan berkas lokal ke OpenShell sebelum exec dan menyinkronkan workspace jarak jauh kembali setelah exec.
• remote: workspace OpenShell menjadi kanonis setelah sandbox dibuat. OpenClaw melakukan seed workspace jarak jauh sekali dari workspace lokal, lalu alat berkas dan exec berjalan langsung terhadap sandbox jarak jauh tanpa menyinkronkan perubahan kembali.

Mode workspace

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

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

Siklus hidup OpenShell

Sandbox OpenShell tetap dikelola melalui siklus hidup sandbox normal:

• openclaw sandbox list menampilkan runtime OpenShell serta 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:

• pembuatan ulang menghapus workspace jarak jauh kanonis untuk cakupan tersebut
• penggunaan berikutnya mengisi workspace jarak jauh baru dari workspace lokal

Untuk mode mirror, pembuatan ulang terutama mereset lingkungan eksekusi jarak jauh 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 jarak jauh sebagai sumber kanonis setelah pengisian awal
• workspaceAccess: "ro" dan "none" tetap membatasi perilaku penulisan dengan cara yang sama

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

Mount bind kustom

agents.defaults.sandbox.docker.binds me-mount 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 me-mount direktori host tambahan hanya ke kontainer peramban sandbox.

• Saat disetel (termasuk []), ini menggantikan agents.defaults.sandbox.docker.binds untuk kontainer peramban.
• Saat dihilangkan, kontainer peramban fallback ke agents.defaults.sandbox.docker.binds (kompatibel mundur).

Contoh (sumber baca-saja + 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. Timpa 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 jalur tersebut. Anda dapat mengganti lokasi socket dengan OPENCLAW_DOCKER_SOCKET. Referensi setup dan env lengkap: Docker.

setupCommand (setup 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-agent: agents.list[].sandbox.docker.setupCommand

Kebijakan tool dan jalan keluar darurat

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 jalan keluar darurat eksplisit yang menjalankan exec di luar sandbox (gateway secara default, atau node saat target exec adalah node). Direktif /exec hanya berlaku untuk pengirim yang berwenang dan bertahan per sesi; untuk menonaktifkan exec sepenuhnya, 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 mengganti 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 pengaktifan minimal

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

Terkait

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