Isolasi kotak pasir

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Apa yang dimasukkan ke sandbox

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

• 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 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 dalam sandbox.

​

Backend

• "docker" (default saat sandboxing diaktifkan): runtime sandbox lokal berbasis Docker.
• "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 canonical. OpenClaw menyinkronkan file lokal ke OpenShell sebelum exec dan menyinkronkan workspace jarak jauh kembali setelah exec.
• remote: workspace OpenShell menjadi canonical 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

​

Siklus hidup OpenShell

• openclaw sandbox list menampilkan runtime OpenShell sekaligus 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 remote kanonis untuk cakupan tersebut
• penggunaan berikutnya mengisi workspace remote baru dari workspace lokal

​

Akses workspace

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

• Ketika ditetapkan (termasuk []), ini menggantikan agents.defaults.sandbox.docker.binds untuk kontainer browser.
• Ketika dihilangkan, kontainer browser menggunakan 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 (penyiapan kontainer satu kali)

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

​

Kebijakan tool dan jalur keluar

• 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 aktivasi minimal

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

​

Terkait

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