Langsung ke konten utama
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 explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

​
openclaw sandbox list

Cantumkan semua runtime sandbox beserta status dan konfigurasinya. 
openclaw sandbox list
openclaw sandbox list --browser  # Cantumkan hanya kontainer browser
openclaw 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 kontainer
openclaw sandbox recreate --session main       # Sesi tertentu
openclaw sandbox recreate --agent mybot        # Agen tertentu
openclaw sandbox recreate --browser            # Hanya kontainer browser
openclaw 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
Runtime otomatis dibuat ulang saat agen berikutnya digunakan.

​
Kasus penggunaan

​
Setelah memperbarui image Docker

# Pull image baru
docker pull openclaw-sandbox:latest
docker 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 kontainer
openclaw sandbox recreate --all

​
Setelah mengubah konfigurasi sandbox

# Edit konfigurasi: agents.defaults.sandbox.* (atau agents.list[].sandbox.*)

# Buat ulang untuk menerapkan konfigurasi baru
openclaw 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 agen
openclaw 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.
Lebih pilih openclaw sandbox recreate daripada pembersihan manual khusus backend. Perintah ini menggunakan registri runtime milik Gateway dan menghindari ketidaksesuaian saat cakupan atau kunci sesi berubah.

​
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