Izolacja w piaskownicy

OpenClaw może uruchamiać narzędzia wewnątrz backendów piaskownicy, aby ograniczyć zakres skutków. Jest to opcjonalne i kontrolowane przez konfigurację (agents.defaults.sandbox lub agents.list[].sandbox). Jeśli uruchamianie w piaskownicy jest wyłączone, narzędzia działają na hoście. Gateway pozostaje na hoście; wykonywanie narzędzi odbywa się w izolowanej piaskownicy, gdy jest włączone.

Co trafia do piaskownicy

• Wykonywanie narzędzi (exec, read, write, edit, apply_patch, process itd.).
• Opcjonalna przeglądarka w piaskownicy (agents.defaults.sandbox.browser).

Nie trafia do piaskownicy:

• Sam proces Gateway.
• Każde narzędzie jawnie dopuszczone do działania poza piaskownicą (np. tools.elevated).
  • Podniesione exec omija piaskownicę i używa skonfigurowanej ścieżki ucieczki (gateway domyślnie albo node, gdy celem exec jest node).
  • Jeśli uruchamianie w piaskownicy jest wyłączone, tools.elevated nie zmienia wykonywania (już odbywa się na hoście). Zobacz Tryb podniesiony.

Tryby

agents.defaults.sandbox.mode kontroluje, kiedy używana jest piaskownica:

Zakres

agents.defaults.sandbox.scope kontroluje, ile kontenerów jest tworzonych:

• "agent" (domyślnie): jeden kontener na agenta.
• "session": jeden kontener na sesję.
• "shared": jeden kontener współdzielony przez wszystkie sesje w piaskownicy.

Backend

agents.defaults.sandbox.backend kontroluje, które środowisko uruchomieniowe zapewnia piaskownicę:

• "docker" (domyślnie, gdy piaskownica jest włączona): lokalne środowisko piaskownicy oparte na Dockerze.
• "ssh": ogólne zdalne środowisko piaskownicy oparte na SSH.
• "openshell": środowisko piaskownicy oparte na OpenShell.

Konfiguracja specyficzna dla SSH znajduje się w agents.defaults.sandbox.ssh. Konfiguracja specyficzna dla OpenShell znajduje się w plugins.entries.openshell.config.

Wybór backendu

Backend Docker

Uruchamianie w piaskownicy jest domyślnie wyłączone. Jeśli włączysz piaskownicę i nie wybierzesz backendu, OpenClaw użyje backendu Docker. Wykonuje narzędzia i przeglądarki w piaskownicy lokalnie przez gniazdo demona Docker (/var/run/docker.sock). Izolacja kontenera piaskownicy jest określana przez przestrzenie nazw Docker.

Aby udostępnić GPU hosta piaskownicom Docker, ustaw agents.defaults.sandbox.docker.gpus albo nadpisanie per agent agents.list[].sandbox.docker.gpus. Wartość jest przekazywana do flagi Docker --gpus jako osobny argument, na przykład "all" albo "device=GPU-uuid", i wymaga zgodnego środowiska uruchomieniowego hosta, takiego jak NVIDIA Container Toolkit.

Backend SSH

Użyj backend: "ssh", gdy chcesz, aby OpenClaw uruchamiał w piaskownicy exec, narzędzia plikowe i odczyty multimediów na dowolnej maszynie dostępnej przez 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

Użyj backend: "openshell", gdy chcesz, aby OpenClaw uruchamiał narzędzia w piaskownicy w zdalnym środowisku zarządzanym przez OpenShell. Pełny przewodnik konfiguracji, referencję konfiguracji i porównanie trybów przestrzeni roboczej znajdziesz na dedykowanej stronie OpenShell.

OpenShell ponownie wykorzystuje ten sam podstawowy transport SSH i mostek zdalnego systemu plików co ogólny backend SSH oraz dodaje cykl życia specyficzny dla OpenShell (sandbox create/get/delete, sandbox ssh-config) i opcjonalny tryb przestrzeni roboczej mirror.

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

Tryby OpenShell:

• mirror (domyślnie): lokalna przestrzeń robocza pozostaje kanoniczna. OpenClaw synchronizuje pliki lokalne do OpenShell przed exec i synchronizuje zdalną przestrzeń roboczą z powrotem po exec.
• remote: przestrzeń robocza OpenShell jest kanoniczna po utworzeniu piaskownicy. OpenClaw jednorazowo zasiewa zdalną przestrzeń roboczą z lokalnej przestrzeni roboczej, a następnie narzędzia plikowe i exec działają bezpośrednio na zdalnej piaskownicy bez synchronizowania zmian z powrotem.

Tryby przestrzeni roboczej

OpenShell ma dwa modele przestrzeni roboczej. To część, która w praktyce ma największe znaczenie.

Wybierz mirror, jeśli traktujesz piaskownicę jako tymczasowe środowisko wykonawcze. Wybierz remote, jeśli traktujesz piaskownicę jako rzeczywisty obszar roboczy.

Cykl życia OpenShell

Piaskownice OpenShell są nadal zarządzane przez normalny cykl życia piaskownicy:

• openclaw sandbox list pokazuje środowiska uruchomieniowe OpenShell oraz środowiska uruchomieniowe Docker
• openclaw sandbox recreate usuwa bieżące środowisko uruchomieniowe i pozwala OpenClaw odtworzyć je przy następnym użyciu
• logika czyszczenia również uwzględnia backend

Dla trybu remote odtworzenie jest szczególnie ważne:

• odtworzenie usuwa kanoniczny zdalny obszar roboczy dla tego zakresu
• następne użycie inicjuje świeży zdalny obszar roboczy z lokalnego obszaru roboczego

Dla trybu mirror odtworzenie głównie resetuje zdalne środowisko wykonawcze, ponieważ lokalny obszar roboczy i tak pozostaje kanoniczny.

Dostęp do obszaru roboczego

agents.defaults.sandbox.workspaceAccess kontroluje, co piaskownica może zobaczyć:

Z backendem OpenShell:

• tryb mirror nadal używa lokalnego obszaru roboczego jako kanonicznego źródła między turami exec
• tryb remote używa zdalnego obszaru roboczego OpenShell jako kanonicznego źródła po początkowym zainicjowaniu
• workspaceAccess: "ro" i "none" nadal ograniczają zachowanie zapisu w ten sam sposób

Przychodzące multimedia są kopiowane do aktywnego obszaru roboczego piaskownicy (media/inbound/*).

Niestandardowe montowania bind

agents.defaults.sandbox.docker.binds montuje dodatkowe katalogi hosta w kontenerze. Format: host:container:mode (np. "/home/user/source:/source:rw").

Globalne i per-agent bindy są scalane (nie zastępowane). Przy scope: "shared" bindy per-agent są ignorowane.

agents.defaults.sandbox.browser.binds montuje dodatkowe katalogi hosta tylko w kontenerze przeglądarki piaskownicy.

• Gdy jest ustawione (w tym []), zastępuje agents.defaults.sandbox.docker.binds dla kontenera przeglądarki.
• Gdy jest pominięte, kontener przeglądarki używa awaryjnie agents.defaults.sandbox.docker.binds (zgodność wsteczna).

Przykład (źródło tylko do odczytu + dodatkowy katalog danych):

{  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"],          },        },      },    ],  },}

Obrazy i konfiguracja

Domyślny obraz Docker: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN 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 sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Domyślnie kontenery piaskownicy Docker działają bez sieci. Nadpisz to przez agents.defaults.sandbox.docker.network.

Instalacje Docker i konteneryzowany Gateway znajdują się tutaj: Docker

W przypadku wdrożeń Gateway Docker scripts/docker/setup.sh może zainicjować konfigurację piaskownicy. Ustaw OPENCLAW_SANDBOX=1 (lub true/yes/on), aby włączyć tę ścieżkę. Lokalizację socketu możesz nadpisać za pomocą OPENCLAW_DOCKER_SOCKET. Pełna konfiguracja i opis zmiennych środowiskowych: Docker.

setupCommand (jednorazowa konfiguracja kontenera)

setupCommand uruchamia się raz po utworzeniu kontenera piaskownicy (nie przy każdym uruchomieniu). Wykonuje się wewnątrz kontenera przez sh -lc.

Ścieżki:

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

Zasady narzędzi i wyjścia awaryjne

Zasady zezwalania/odmawiania narzędzi nadal obowiązują przed regułami piaskownicy. Jeśli narzędzie jest zabronione globalnie albo dla danego agenta, piaskownica go nie przywraca.

tools.elevated to jawne wyjście awaryjne, które uruchamia exec poza piaskownicą (domyślnie gateway, albo node, gdy celem exec jest node). Dyrektywy /exec mają zastosowanie tylko do autoryzowanych nadawców i utrzymują się w ramach sesji; aby trwale wyłączyć exec, użyj odmowy w zasadach narzędzi (zobacz Piaskownica kontra zasady narzędzi kontra podwyższone uprawnienia).

Debugowanie:

• Użyj openclaw sandbox explain, aby sprawdzić efektywny tryb piaskownicy, zasady narzędzi i klucze konfiguracji naprawczej.
• Zobacz Piaskownica kontra zasady narzędzi kontra podwyższone uprawnienia, aby poznać model myślowy „dlaczego to jest zablokowane?”.

Utrzymuj to w ścisłej izolacji.

Nadpisania dla wielu agentów

Każdy agent może nadpisać piaskownicę i narzędzia: agents.list[].sandbox oraz agents.list[].tools (plus agents.list[].tools.sandbox.tools dla zasad narzędzi piaskownicy). Zobacz Piaskownica i narzędzia wielu agentów, aby poznać kolejność pierwszeństwa.

Minimalny przykład włączenia

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

Powiązane

• Piaskownica i narzędzia wielu agentów — nadpisania dla poszczególnych agentów i kolejność pierwszeństwa
• OpenShell — konfiguracja zarządzanego zaplecza piaskownicy, tryby przestrzeni roboczej i dokumentacja konfiguracji
• Konfiguracja piaskownicy
• Piaskownica kontra zasady narzędzi kontra podwyższone uprawnienia — debugowanie „dlaczego to jest zablokowane?”
• Bezpieczeństwo