Isolasi Sandbox

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 di sandbox terisolasi saat diaktifkan.

# Apa yang dimasukkan ke sandbox

• Eksekusi alat (exec, read, write, edit, apply_patch, process, dll.).
• Browser bersandbox opsional (agents.defaults.sandbox.browser).

Tidak dimasukkan ke sandbox:

• Proses Gateway itu sendiri.
• Alat apa pun yang secara eksplisit diizinkan berjalan di luar sandbox (mis. 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 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 bersandbox.

# Backend

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

• "docker" (default saat sandboxing diaktifkan): runtime sandbox lokal berbasis Docker.
• "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 browser 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, atur agents.defaults.sandbox.docker.gpus atau override per agen agents.list[].sandbox.docker.gpus. Nilainya diteruskan ke flag --gpus Docker sebagai argumen terpisah, misalnya "all" atau "device=GPU-uuid", dan membutuhkan runtime host yang kompatibel seperti NVIDIA Container Toolkit.

# Backend SSH

Gunakan backend: "ssh" saat Anda ingin OpenClaw memasukkan exec, alat file, 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 kembali transport SSH inti yang sama dan bridge sistem file jarak jauh yang sama dengan backend SSH generik, serta menambahkan lifecycle 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 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 sekali dari workspace lokal, lalu alat file 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, recreate sangat penting:

• recreate menghapus workspace jarak jauh kanonis untuk scope tersebut
• penggunaan berikutnya mengisi workspace jarak jauh baru dari workspace lokal

Untuk mode mirror, recreate 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 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

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

# Bind mount khusus

agents.defaults.sandbox.docker.binds memasang direktori host tambahan ke dalam container. 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 memasang direktori host tambahan hanya ke dalam container browser sandbox.

• Ketika disetel (termasuk []), ini menggantikan agents.defaults.sandbox.docker.binds untuk container browser.
• Ketika dihilangkan, container browser menggunakan fallback ke agents.defaults.sandbox.docker.binds (kompatibel mundur).

Contoh (source hanya-baca + 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 setup

Image Docker default: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Secara default, container sandbox Docker berjalan dengan tanpa jaringan. Timpa dengan agents.defaults.sandbox.docker.network.

Instalasi Docker dan Gateway dalam container berada di sini: Docker

Untuk deployment Gateway Docker, scripts/docker/setup.sh dapat melakukan bootstrap konfigurasi sandbox. Setel OPENCLAW_SANDBOX=1 (atau true/yes/on) untuk mengaktifkan path tersebut. Anda dapat menimpa lokasi socket dengan OPENCLAW_DOCKER_SOCKET. Referensi setup dan env lengkap: Docker.

# setupCommand (setup container satu kali)

setupCommand berjalan sekali setelah container sandbox dibuat (bukan pada setiap run). Ini dieksekusi di dalam container melalui sh -lc.

Path:

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

# Kebijakan alat dan celah keluar darurat

Kebijakan izinkan/tolak alat tetap berlaku sebelum aturan sandbox. Jika sebuah alat ditolak secara global atau per agen, sandboxing tidak akan mengembalikannya.

tools.elevated adalah celah 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 secara paksa, gunakan penolakan kebijakan alat (lihat Sandbox vs Tool Policy vs Elevated).

Debugging:

• Gunakan openclaw sandbox explain untuk memeriksa mode sandbox efektif, kebijakan alat, dan kunci konfigurasi perbaikan.
• Lihat Sandbox vs Tool Policy vs Elevated untuk model mental "mengapa ini diblokir?".

Tetap kunci dengan ketat.

# Penimpaan multi-agen

Setiap agen dapat menimpa sandbox + alat: agents.list[].sandbox dan agents.list[].tools (ditambah agents.list[].tools.sandbox.tools untuk kebijakan alat sandbox). Lihat Sandbox & Alat Multi-Agen untuk prioritas.

# Contoh pengaktifan minimal

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

# Terkait

• Sandbox & Alat Multi-Agen — penimpaan per agen dan prioritas
• OpenShell — penyiapan backend sandbox terkelola, mode workspace, dan referensi konfigurasi
• Konfigurasi sandbox
• Sandbox vs Tool Policy vs Elevated — debugging "mengapa ini diblokir?"
• Keamanan