Isolasi Lingkungan Terbatas

​

Apa yang dimasukkan ke sandbox

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

• Proses Gateway itu sendiri.
• Alat apa pun yang secara eksplisit diizinkan berjalan di luar sandbox (misalnya tools.elevated).
  • Elevated exec melewati sandboxing dan menggunakan jalur keluar yang dikonfigurasi (gateway secara default, atau node saat target exec adalah node).
  • Jika sandboxing nonaktif, tools.elevated tidak mengubah eksekusi (sudah berada di host). Lihat Mode Elevated.

​

Mode

​

Cakupan

• "agent" (default): satu kontainer per agen.
• "session": satu kontainer per sesi.
• "shared": satu kontainer yang dibagikan oleh semua sesi yang dimasukkan ke sandbox.

​

Backend

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

​

Memilih backend

​

Backend Docker

​

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",
          // 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

{
  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 berkas 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 berkas dan exec berjalan langsung terhadap sandbox jarak jauh tanpa menyinkronkan perubahan kembali.

​

Mode workspace

​

Siklus hidup OpenShell

• 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

• pembuatan ulang menghapus workspace jarak jauh kanonis untuk cakupan tersebut
• penggunaan berikutnya mengisi workspace jarak jauh baru dari workspace lokal

​

Akses workspace

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

​

Mount bind kustom

• Saat disetel (termasuk []), ini menggantikan agents.defaults.sandbox.docker.binds untuk kontainer peramban.
• Saat dihilangkan, kontainer peramban fallback ke agents.defaults.sandbox.docker.binds (kompatibel mundur).

{
  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 (setup kontainer satu kali)

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

​

Kebijakan tool dan jalan keluar darurat

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

​

Override multi-agent

​

Contoh pengaktifan minimal

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

​

Terkait

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