​

Sandboxing

​

Apa yang di-sandbox

• Eksekusi tool (exec, read, write, edit, apply_patch, process, dll.).
• Browser sandbox opsional (agents.defaults.sandbox.browser).
  • Secara default, browser sandbox memulai otomatis (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 observer noVNC dilindungi kata sandi secara default; OpenClaw mengeluarkan URL token singkat yang menyajikan halaman bootstrap lokal dan membuka noVNC dengan kata sandi di fragmen URL (bukan log query/header).
  • agents.defaults.sandbox.browser.allowHostControl memungkinkan sesi sandbox menargetkan browser host secara eksplisit.
  • Allowlist opsional membatasi 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 dimatikan, tools.elevated tidak mengubah eksekusi (sudah berjalan di host). Lihat Elevated Mode.

​

Mode

• "off": tanpa sandboxing.
• "non-main": sandbox hanya sesi non-main (default jika Anda ingin chat normal berjalan di host).
• "all": setiap sesi berjalan di sandbox. Catatan: "non-main" didasarkan pada session.mainKey (default "main"), bukan agent id. Sesi grup/channel menggunakan key mereka sendiri, sehingga dihitung sebagai non-main dan akan di-sandbox.

​

Scope

• "agent" (default): satu container per agent.
• "session": satu container per sesi.
• "shared": satu container dibagi oleh semua sesi yang di-sandbox.

​

Backend

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

​

Memilih backend

​

Backend Docker

• Config Memerlukan Path Host: Konfigurasi workspace di openclaw.json HARUS berisi path absolut milik Host (misalnya /home/user/.openclaw/workspaces), bukan path internal container Gateway. Saat OpenClaw meminta daemon Docker untuk memunculkan sandbox, daemon mengevaluasi path relatif terhadap namespace OS Host, bukan namespace Gateway.
• Paritas FS Bridge (Peta Volume Identik): Proses native OpenClaw Gateway juga menulis file heartbeat dan bridge ke direktori workspace. Karena Gateway mengevaluasi string yang sama persis (path host) dari dalam lingkungan container-nya sendiri, deployment Gateway HARUS menyertakan peta volume identik yang menautkan namespace host secara native (-v /home/user/.openclaw:/home/user/.openclaw).

​

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 remote per-scope di bawah sandbox.ssh.workspaceRoot.
• Pada penggunaan pertama setelah create atau recreate, OpenClaw melakukan seed workspace remote dari workspace lokal satu kali.
• Setelah itu, exec, read, write, edit, apply_patch, pembacaan media prompt, dan staging media masuk berjalan langsung terhadap workspace remote melalui SSH.
• OpenClaw tidak menyinkronkan perubahan remote 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 me-resolve-nya melalui snapshot runtime secrets normal, menuliskannya ke file sementara dengan 0600, lalu menghapusnya saat sesi SSH berakhir.
• Jika *File dan *Data keduanya diatur untuk item yang sama, *Data menang untuk sesi SSH tersebut.

• Edit lokal host yang dilakukan di luar OpenClaw setelah langkah seed tidak terlihat di remote sampai Anda membuat ulang sandbox.
• openclaw sandbox recreate menghapus root remote per-scope dan melakukan seed lagi dari lokal pada penggunaan berikutnya.
• Browser sandbox 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 remote kembali setelah exec.
• remote: workspace OpenShell menjadi kanonis setelah sandbox dibuat. OpenClaw melakukan seed workspace remote satu kali dari workspace lokal, lalu tool file dan exec berjalan langsung terhadap sandbox remote 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 remote yang sama seperti backend: "ssh".
• Dalam mode mirror hanya lifecycle yang berbeda: sinkronkan lokal ke remote sebelum exec, lalu sinkronkan kembali setelah exec.

• browser sandbox belum didukung
• sandbox.docker.binds tidak didukung pada backend OpenShell
• knob 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 remote kembali ke workspace lokal.
• Tool file tetap beroperasi melalui bridge sandbox, tetapi workspace lokal tetap menjadi sumber kebenaran 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

• ada biaya sinkronisasi tambahan sebelum dan sesudah exec

remote

• Saat sandbox pertama kali dibuat, OpenClaw melakukan seed workspace remote dari workspace lokal satu kali.
• Setelah itu, exec, read, write, edit, dan apply_patch beroperasi langsung terhadap workspace OpenShell remote.
• OpenClaw tidak menyinkronkan perubahan remote 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.
• Transport menggunakan SSH ke sandbox OpenShell yang dikembalikan oleh openshell sandbox ssh-config.

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

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

​

Lifecycle OpenShell

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

• recreate menghapus workspace remote kanonis untuk scope tersebut
• penggunaan berikutnya melakukan seed workspace remote baru dari workspace lokal

​

Akses workspace

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

• mode mirror tetap menggunakan workspace lokal sebagai sumber kanonis di antara 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

​

Bind mount kustom

• Saat diatur (termasuk []), ini menggantikan agents.defaults.sandbox.docker.binds untuk container browser.
• Saat dihilangkan, container browser fallback 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: mereka mengekspos path host dengan mode apa pun yang Anda atur (:ro atau :rw).
• OpenClaw memblokir sumber bind berbahaya (misalnya: docker.sock, /etc, /proc, /sys, /dev, dan parent mount yang akan mengeksposnya).
• OpenClaw juga memblokir root kredensial direktori home yang umum seperti ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm, dan ~/.ssh.
• Validasi bind bukan hanya pencocokan string. OpenClaw menormalkan path sumber, lalu me-resolve-nya lagi melalui ancestor terdalam yang ada sebelum memeriksa ulang path yang diblokir dan root yang diizinkan.
• Ini berarti escape parent-symlink tetap fail-closed bahkan ketika leaf akhir belum ada. Contoh: /workspace/run-link/new-file tetap di-resolve sebagai /var/run/... jika run-link menunjuk ke sana.
• Root sumber yang diizinkan juga dikanonisasi dengan cara yang sama, jadi path yang hanya tampak berada di dalam allowlist sebelum resolusi symlink tetap ditolak sebagai outside allowed roots.
• Mount sensitif (secret, SSH key, service credential) sebaiknya :ro kecuali benar-benar diperlukan.
• Gabungkan dengan workspaceAccess: "ro" jika Anda hanya membutuhkan akses baca ke workspace; mode bind tetap independen.
• Lihat Sandbox vs Tool Policy vs Elevated untuk cara bind berinteraksi dengan tool policy 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 hardening grafis (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) bersifat opsional dan berguna saat container tidak memiliki dukungan GPU. Atur OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 jika workload 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 namespace join).
• Override break-glass: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (penyiapan container satu kali)

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

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

​

Tool policy + jalur escape

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

​

Override multi-agent

​

Contoh aktivasi minimal

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

​

Dokumentasi terkait

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