​

Sandboxing

​

Apa yang disandbox

• Eksekusi tool (exec, read, write, edit, apply_patch, process, dll.).
• Browser sandbox opsional (agents.defaults.sandbox.browser).
  • Secara default, browser sandbox otomatis dimulai (memastikan CDP dapat dijangkau) saat tool browser membutuhkannya. Konfigurasikan melalui agents.defaults.sandbox.browser.autoStart dan agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • Secara default, container browser sandbox menggunakan jaringan Docker khusus (openclaw-sandbox-browser) alih-alih jaringan bridge global. Konfigurasikan dengan agents.defaults.sandbox.browser.network.
  • agents.defaults.sandbox.browser.cdpSourceRange opsional membatasi ingress CDP di tepi container dengan allowlist CIDR (misalnya 172.21.0.1/32).
  • Akses pengamat noVNC dilindungi kata sandi secara default; OpenClaw memancarkan URL token berumur pendek yang menyajikan halaman bootstrap lokal dan membuka noVNC dengan kata sandi di fragmen URL (bukan log kueri/header).
  • agents.defaults.sandbox.browser.allowHostControl memungkinkan sesi yang disandbox menargetkan browser host secara eksplisit.
  • Allowlist opsional mengatur target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Proses Gateway itu sendiri.
• Tool apa pun yang secara eksplisit diizinkan berjalan di luar sandbox (misalnya 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 di host). Lihat Elevated Mode.

​

Mode

• "off": tidak ada sandboxing.
• "non-main": sandbox hanya sesi non-main (default jika Anda ingin chat normal di host).
• "all": setiap sesi berjalan di sandbox. Catatan: "non-main" didasarkan pada session.mainKey (default "main"), bukan id agen. Sesi grup/kanal menggunakan kuncinya sendiri, sehingga dihitung sebagai non-main dan akan disandbox.

​

Cakupan

• "agent" (default): satu container per agen.
• "session": satu container per sesi.
• "shared": satu container dibagikan oleh semua sesi yang disandbox.

​

Backend

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

​

Memilih backend

​

Backend 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 SecretRef / konten inline alih-alih file 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" },
        },
      },
    },
  },
}

• OpenClaw membuat root jarak jauh per cakupan di bawah sandbox.ssh.workspaceRoot.
• Pada penggunaan pertama setelah create atau recreate, OpenClaw melakukan seed workspace jarak jauh itu dari workspace lokal satu kali.
• Setelah itu, exec, read, write, edit, apply_patch, pembacaan media prompt, dan staging media masuk berjalan langsung terhadap workspace jarak jauh melalui SSH.
• OpenClaw tidak menyinkronkan perubahan jarak jauh kembali ke workspace lokal secara otomatis.

• identityFile, certificateFile, knownHostsFile: gunakan file lokal yang sudah ada dan teruskan melalui config OpenSSH.
• identityData, certificateData, knownHostsData: gunakan string inline atau SecretRef. OpenClaw menyelesaikannya melalui snapshot runtime secrets normal, menuliskannya ke file sementara dengan 0600, lalu menghapusnya saat sesi SSH berakhir.
• Jika *File dan *Data keduanya disetel untuk item yang sama, *Data menang untuk sesi SSH tersebut.

• Edit lokal host yang dibuat di luar OpenClaw setelah langkah seed tidak terlihat dari jarak jauh sampai Anda membuat ulang sandbox.
• openclaw sandbox recreate menghapus root jarak jauh per cakupan dan melakukan seed lagi dari lokal pada penggunaan berikutnya.
• Browser sandboxing tidak didukung pada backend SSH.
• Pengaturan sandbox.docker.* tidak berlaku untuk backend SSH.

​

Backend OpenShell

{
  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",
        },
      },
    },
  },
}

• mirror (default): workspace lokal tetap kanonis. OpenClaw menyinkronkan file 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 satu kali dari workspace lokal, lalu tool file dan exec berjalan langsung terhadap sandbox jarak jauh tanpa menyinkronkan perubahan kembali.

• OpenClaw meminta config SSH khusus sandbox dari OpenShell melalui openshell sandbox ssh-config <name>.
• Core menulis config SSH itu ke file sementara, membuka sesi SSH, dan menggunakan kembali bridge filesystem jarak jauh yang sama dengan yang digunakan oleh backend: "ssh".
• Hanya pada mode mirror siklus hidupnya berbeda: sinkronkan lokal ke jarak jauh sebelum exec, lalu sinkronkan kembali setelah exec.

• browser sandbox belum didukung
• sandbox.docker.binds tidak didukung pada backend OpenShell
• pengaturan runtime khusus Docker di bawah sandbox.docker.* tetap hanya berlaku untuk backend Docker

​

Mode workspace

mirror

• Sebelum exec, OpenClaw menyinkronkan workspace lokal ke sandbox OpenShell.
• Setelah exec, OpenClaw menyinkronkan workspace jarak jauh kembali ke workspace lokal.
• Tool file tetap beroperasi melalui bridge sandbox, tetapi workspace lokal tetap menjadi source of truth di antara giliran.

• Anda mengedit file secara lokal di luar OpenClaw dan ingin perubahan itu otomatis muncul di sandbox
• Anda ingin sandbox OpenShell berperilaku semirip mungkin dengan backend Docker
• Anda ingin workspace host mencerminkan penulisan sandbox setelah setiap giliran exec

• biaya sinkronisasi tambahan sebelum dan sesudah exec

remote

• Saat sandbox pertama kali dibuat, OpenClaw melakukan seed workspace jarak jauh dari workspace lokal satu kali.
• Setelah itu, exec, read, write, edit, dan apply_patch beroperasi langsung terhadap workspace OpenShell jarak jauh.
• OpenClaw tidak menyinkronkan perubahan jarak jauh kembali ke workspace lokal setelah exec.
• Pembacaan media saat prompt tetap berfungsi karena tool file dan media membaca melalui bridge sandbox alih-alih mengasumsikan path host lokal.
• Transportnya adalah SSH ke sandbox OpenShell yang dikembalikan oleh openshell sandbox ssh-config.

• Jika Anda mengedit file di host di luar OpenClaw setelah langkah seed, sandbox jarak jauh tidak akan melihat perubahan itu secara otomatis.
• Jika sandbox dibuat ulang, workspace jarak jauh di-seed lagi dari workspace lokal.
• Dengan scope: "agent" atau scope: "shared", workspace jarak jauh itu dibagikan pada cakupan yang sama.

• sandbox seharusnya hidup terutama di sisi OpenShell jarak jauh
• Anda ingin overhead sinkronisasi per giliran lebih rendah
• Anda tidak ingin edit lokal host diam-diam menimpa status sandbox jarak jauh

​

Siklus hidup OpenShell

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

• recreate menghapus workspace jarak jauh kanonis untuk cakupan tersebut
• penggunaan berikutnya melakukan seed workspace jarak jauh baru dari workspace lokal

​

Akses workspace

• "none" (default): tool melihat workspace sandbox di bawah ~/.openclaw/sandboxes.
• "ro": mount workspace agen sebagai read-only di /agent (menonaktifkan write/edit/apply_patch).
• "rw": mount workspace agen sebagai read/write di /workspace.

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

​

Bind mount kustom

• Saat disetel (termasuk []), ia menggantikan agents.defaults.sandbox.docker.binds untuk container browser.
• Saat dihilangkan, container browser kembali ke agents.defaults.sandbox.docker.binds (kompatibel ke belakang).

{
  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"],
          },
        },
      },
    ],
  },
}

• Bind melewati filesystem sandbox: bind mengekspos path host dengan mode apa pun yang Anda setel (:ro atau :rw).
• OpenClaw memblokir sumber bind berbahaya (misalnya: docker.sock, /etc, /proc, /sys, /dev, dan mount induk yang akan mengeksposnya).
• OpenClaw juga memblokir root kredensial umum di direktori home seperti ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm, dan ~/.ssh.
• Validasi bind bukan hanya pencocokan string. OpenClaw menormalkan path sumber, lalu menyelesaikannya lagi melalui leluhur terdalam yang ada sebelum memeriksa ulang path yang diblokir dan root yang diizinkan.
• Ini berarti escape parent symlink tetap gagal secara tertutup bahkan saat leaf akhir belum ada. Contoh: /workspace/run-link/new-file tetap diselesaikan sebagai /var/run/... jika run-link menunjuk ke sana.
• Root sumber yang diizinkan juga dikanonisasi dengan cara yang sama, sehingga path yang hanya tampak berada di dalam allowlist sebelum resolusi symlink tetap ditolak sebagai outside allowed roots.
• Mount sensitif (secret, kunci SSH, kredensial layanan) sebaiknya :ro kecuali benar-benar diperlukan.
• Gabungkan dengan workspaceAccess: "ro" jika Anda hanya memerlukan akses baca ke workspace; mode bind tetap independen.
• Lihat Sandbox vs Tool Policy vs Elevated untuk bagaimana bind berinteraksi dengan kebijakan tool dan elevated exec.

​

Image + penyiapan

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox dan --disable-setuid-sandbox saat noSandbox diaktifkan.
• Tiga flag penguatan grafis (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) bersifat opsional dan berguna saat container tidak memiliki dukungan GPU. Setel OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 jika beban kerja Anda memerlukan WebGL atau fitur browser/3D lainnya.
• --disable-extensions diaktifkan secara default dan dapat dinonaktifkan dengan OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 untuk alur yang bergantung pada extension.
• --renderer-process-limit=2 dikendalikan oleh OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, di mana 0 mempertahankan default Chromium.

• network: "host" diblokir.
• network: "container:<id>" diblokir secara default (risiko bypass join namespace).
• Override break-glass: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (penyiapan container satu kali)

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

• Default docker.network adalah "none" (tanpa egress), sehingga instalasi paket akan gagal.
• docker.network: "container:<id>" memerlukan dangerouslyAllowContainerNamespaceJoin: true dan hanya untuk break-glass.
• readOnlyRoot: true mencegah penulisan; setel readOnlyRoot: false atau buat image kustom.
• user harus root untuk instalasi paket (hilangkan user atau setel user: "0:0").
• Sandbox exec tidak mewarisi process.env host. Gunakan agents.defaults.sandbox.docker.env (atau image kustom) untuk API key skill.

​

Kebijakan tool + jalur escape

• Gunakan openclaw sandbox explain untuk memeriksa mode sandbox efektif, kebijakan tool, dan kunci config perbaikan.
• Lihat Sandbox vs Tool Policy vs Elevated untuk model mental “mengapa ini diblokir?”. Pertahankan agar tetap terkunci.

​

Override multi-agent

​

Contoh pengaktifan minimal

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

​

Dokumen terkait

• OpenShell — penyiapan backend sandbox terkelola, mode workspace, dan referensi konfigurasi
• Konfigurasi Sandbox
• Sandbox vs Tool Policy vs Elevated — debugging “mengapa ini diblokir?”
• Multi-Agent Sandbox & Tools — override per agen dan prioritas
• Security