Sandboxing

​

Apa yang dimasukkan ke sandbox

• Eksekusi alat: exec, read, write, edit, apply_patch, process, dan sebagainya.
• Browser dalam sandbox opsional (agents.defaults.sandbox.browser).

• Proses Gateway itu sendiri.
• Alat apa pun yang secara eksplisit diizinkan berjalan di luar sandbox melalui tools.elevated. Eksekusi dengan hak istimewa yang ditingkatkan melewati sandboxing dan berjalan pada jalur keluar yang dikonfigurasi (gateway secara default, atau node saat target eksekusi adalah node). Jika sandboxing dinonaktifkan, tools.elevated tidak mengubah apa pun karena eksekusi sudah berjalan di host. Lihat Mode dengan Hak Istimewa yang Ditingkatkan.

​

Mode, cakupan, dan backend

• off: tanpa sandboxing.
• non-main: masukkan setiap sesi ke sandbox kecuali sesi utama agen. Kunci sesi utama selalu agent:<agentId>:main (atau global saat session.scope adalah "global"); kunci ini tidak dapat dikonfigurasi. Sesi grup/saluran menggunakan kuncinya sendiri, sehingga selalu dianggap bukan sesi utama dan dimasukkan ke sandbox.
• all: setiap sesi berjalan di dalam sandbox.

• agent: satu kontainer per agen.
• session: satu kontainer per sesi.
• shared: satu kontainer yang digunakan bersama oleh semua sesi dalam sandbox (penggantian per agen docker/ssh/browser diabaikan dalam cakupan ini).

​

Backend Docker

​

Browser dalam sandbox

• Browser sandbox dimulai secara otomatis (memastikan CDP dapat dijangkau) saat alat browser membutuhkannya. Konfigurasikan melalui agents.defaults.sandbox.browser.autoStart (default true) dan autoStartTimeoutMs (default 12 dtk).
• Kontainer browser sandbox menggunakan jaringan Docker khusus (openclaw-sandbox-browser), bukan jaringan global bridge. Konfigurasikan dengan agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange membatasi akses masuk CDP pada tepi kontainer dengan daftar izin CIDR (misalnya 172.21.0.1/32).
• Akses pengamat noVNC dilindungi kata sandi secara default; OpenClaw menghasilkan URL token berumur pendek yang menyajikan halaman bootstrap lokal dan membuka noVNC dengan kata sandi di fragmen URL (bukan string kueri atau log header).
• agents.defaults.sandbox.browser.allowHostControl (default false) memungkinkan sesi dalam sandbox menargetkan browser host secara eksplisit.
• Daftar izin opsional membatasi target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

​

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 SecretRefs / konten sebaris sebagai pengganti berkas 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" },
        },
      },
    },
  },
}

• Siklus hidup: OpenClaw membuat root jarak jauh per cakupan di bawah sandbox.ssh.workspaceRoot. Pada penggunaan pertama setelah dibuat atau dibuat ulang, OpenClaw menyemai ruang kerja jarak jauh tersebut dari ruang kerja lokal satu kali. Setelah itu, exec, read, write, edit, apply_patch, pembacaan media prompt, dan penyiapan media masuk berjalan langsung terhadap ruang kerja jarak jauh melalui SSH. OpenClaw tidak secara otomatis menyinkronkan perubahan jarak jauh kembali ke ruang kerja lokal.
• Materi autentikasi: identityFile/certificateFile/knownHostsFile merujuk ke berkas lokal yang ada. identityData/certificateData/knownHostsData menerima string sebaris atau SecretRefs, yang diselesaikan melalui snapshot runtime rahasia normal, ditulis ke berkas sementara dengan mode 0600, dan dihapus saat sesi SSH berakhir. Jika varian *File dan *Data ditetapkan untuk item yang sama, *Data berlaku untuk sesi tersebut.
• Konsekuensi kanonis jarak jauh: ruang kerja SSH jarak jauh menjadi status sandbox yang sebenarnya setelah penyemaian awal. Perubahan lokal host yang dibuat di luar OpenClaw setelah langkah penyemaian tidak terlihat dari jarak jauh hingga Anda membuat ulang sandbox. openclaw sandbox recreate menghapus root jarak jauh per cakupan dan menyemai ulang dari lokal pada penggunaan berikutnya. Sandboxing browser tidak didukung pada backend ini, dan pengaturan sandbox.docker.* tidak berlaku untuk backend ini.

​

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

​

Akses ruang kerja

​

Beberapa folder untuk satu agen

host-directory:container-directory:ro
host-directory:container-directory:rw

• ro menjadikan folder yang dipasang hanya-baca di dalam sandbox.
• rw memungkinkan alat dan proses dalam sandbox mengubah folder host.
• Jalur kontainer adalah jalur yang digunakan agen. Jalur host tidak diekspos secara otomatis.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Diperlukan karena sumber-sumber ini berada di luar ruang kerja agen.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

​

Perilaku bind lainnya

{
  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 penyiapan

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

​

setupCommand (penyiapan kontainer satu kali)

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

​

Kebijakan alat dan jalur pengabaian

• openclaw sandbox list menampilkan kontainer sandbox, status, kecocokan image, usia, waktu tidak aktif, serta sesi/agen yang terkait.
• openclaw sandbox explain [--session <key>] [--agent <id>] memeriksa mode sandbox efektif, ruang kerja host, direktori kerja runtime, pemasangan Docker, kebijakan alat, dan kunci konfigurasi perbaikan. Kolom workspaceRoot tetap menunjukkan root sandbox yang dikonfigurasi; effectiveHostWorkspaceRoot menunjukkan lokasi sebenarnya dari ruang kerja yang aktif.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] menghapus kontainer/lingkungan agar dibuat ulang dengan konfigurasi saat ini pada penggunaan berikutnya.
• Lihat Sandbox vs Kebijakan Alat vs Elevated untuk model mental “mengapa ini diblokir?”.

​

Penggantian konfigurasi multiagen

​

Contoh pengaktifan minimal

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

​

Terkait

• Sandbox & Alat Multiagen — penggantian konfigurasi per agen dan urutan prioritas
• OpenShell — penyiapan backend sandbox terkelola, mode ruang kerja, dan referensi konfigurasi
• Konfigurasi sandbox
• Sandbox vs Kebijakan Alat vs Elevated — debugging “mengapa ini diblokir?”
• Keamanan