CLI Sandbox

Kelola runtime sandbox untuk eksekusi agen yang terisolasi.

Ikhtisar

OpenClaw dapat menjalankan agen dalam runtime sandbox terisolasi demi keamanan. Perintah sandbox membantu Anda memeriksa dan membuat ulang runtime tersebut setelah pembaruan atau perubahan konfigurasi.

Saat ini biasanya berarti:

• Kontainer sandbox Docker
• Runtime sandbox SSH saat agents.defaults.sandbox.backend = "ssh"
• Runtime sandbox OpenShell saat agents.defaults.sandbox.backend = "openshell"

Untuk ssh dan OpenShell remote, membuat ulang lebih penting dibandingkan dengan Docker:

• workspace jarak jauh menjadi kanonis setelah seed awal
• openclaw sandbox recreate menghapus workspace jarak jauh kanonis tersebut untuk cakupan yang dipilih
• penggunaan berikutnya melakukan seed lagi dari workspace lokal saat ini

Perintah

openclaw sandbox explain

Periksa mode/cakupan/akses workspace sandbox yang efektif, kebijakan alat sandbox, dan gerbang elevasi (dengan jalur kunci konfigurasi untuk perbaikan).

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

openclaw sandbox list

Cantumkan semua runtime sandbox beserta status dan konfigurasinya.

openclaw sandbox listopenclaw sandbox list --browser  # Cantumkan hanya kontainer browseropenclaw sandbox list --json     # Output JSON

Output mencakup:

• Nama dan status runtime
• Backend (docker, openshell, dll.)
• Label konfigurasi dan apakah cocok dengan konfigurasi saat ini
• Usia (waktu sejak dibuat)
• Waktu menganggur (waktu sejak terakhir digunakan)
• Sesi/agen terkait

openclaw sandbox recreate

Hapus runtime sandbox untuk memaksa pembuatan ulang dengan konfigurasi yang diperbarui.

openclaw sandbox recreate --all                # Buat ulang semua kontaineropenclaw sandbox recreate --session main       # Sesi tertentuopenclaw sandbox recreate --agent mybot        # Agen tertentuopenclaw sandbox recreate --browser            # Hanya kontainer browseropenclaw sandbox recreate --all --force        # Lewati konfirmasi

Opsi:

• --all: Buat ulang semua kontainer sandbox
• --session <key>: Buat ulang kontainer untuk sesi tertentu
• --agent <id>: Buat ulang kontainer untuk agen tertentu
• --browser: Hanya buat ulang kontainer browser
• --force: Lewati prompt konfirmasi

Kasus penggunaan

Setelah memperbarui image Docker

# Pull image barudocker pull openclaw-sandbox:latestdocker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim # Perbarui konfigurasi untuk menggunakan image baru# Edit konfigurasi: agents.defaults.sandbox.docker.image (atau agents.list[].sandbox.docker.image) # Buat ulang kontaineropenclaw sandbox recreate --all

Setelah mengubah konfigurasi sandbox

# Edit konfigurasi: agents.defaults.sandbox.* (atau agents.list[].sandbox.*) # Buat ulang untuk menerapkan konfigurasi baruopenclaw sandbox recreate --all

Setelah mengubah target SSH atau materi auth SSH

# Edit konfigurasi:# - agents.defaults.sandbox.backend# - agents.defaults.sandbox.ssh.target# - agents.defaults.sandbox.ssh.workspaceRoot# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData openclaw sandbox recreate --all

Untuk backend inti ssh, pembuatan ulang menghapus root workspace jarak jauh per cakupan pada target SSH. Run berikutnya melakukan seed lagi dari workspace lokal.

Setelah mengubah sumber, kebijakan, atau mode OpenShell

# Edit konfigurasi:# - agents.defaults.sandbox.backend# - plugins.entries.openshell.config.from# - plugins.entries.openshell.config.mode# - plugins.entries.openshell.config.policy openclaw sandbox recreate --all

Untuk mode OpenShell remote, pembuatan ulang menghapus workspace jarak jauh kanonis untuk cakupan tersebut. Run berikutnya melakukan seed lagi dari workspace lokal.

Setelah mengubah setupCommand

openclaw sandbox recreate --all# atau hanya satu agen:openclaw sandbox recreate --agent family

Hanya untuk agen tertentu

# Perbarui hanya kontainer milik satu agenopenclaw sandbox recreate --agent alfred

Mengapa ini diperlukan

Saat Anda memperbarui konfigurasi sandbox:

• Runtime yang ada terus berjalan dengan pengaturan lama.
• Runtime hanya dipangkas setelah 24 jam tidak aktif.
• Agen yang digunakan secara rutin mempertahankan runtime lama tetap hidup tanpa batas.

Gunakan openclaw sandbox recreate untuk memaksa penghapusan runtime lama. Runtime tersebut dibuat ulang otomatis dengan pengaturan saat ini saat berikutnya diperlukan.

Migrasi registri

OpenClaw menyimpan metadata runtime sandbox dalam basis data status SQLite bersama. Instalasi lama mungkin masih memiliki file registri sandbox legacy:

• ~/.openclaw/sandbox/containers.json
• ~/.openclaw/sandbox/browsers.json

Beberapa upgrade juga mungkin memiliki satu shard JSON per kontainer/browser di bawah ~/.openclaw/sandbox/containers/ atau ~/.openclaw/sandbox/browsers/. Pembacaan runtime sandbox biasa tidak menulis ulang sumber legacy tersebut. Jalankan openclaw doctor --fix untuk memigrasikan entri legacy yang valid ke SQLite. File legacy yang tidak valid dikarantina sehingga satu registri lama yang rusak tidak dapat menyembunyikan entri runtime saat ini.

Konfigurasi

Pengaturan sandbox berada di ~/.openclaw/openclaw.json di bawah agents.defaults.sandbox (override per agen berada di agents.list[].sandbox):

{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // off, non-main, all        "backend": "docker", // docker, ssh, openshell        "scope": "agent", // session, agent, shared        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... more Docker options        },        "prune": {          "idleHours": 24, // Auto-prune after 24h idle          "maxAgeDays": 7, // Auto-prune after 7 days        },      },    },  },}

Terkait

• Referensi CLI
• Sandboxing
• Workspace agen
• Doctor: memeriksa penyiapan sandbox.