Izolacja środowiska

OpenClaw może uruchamiać narzędzia wewnątrz backendów piaskownicy, aby ograniczyć zakres potencjalnych szkód. Jest to opcjonalne i kontrolowane przez konfigurację (agents.defaults.sandbox lub agents.list[].sandbox). Jeśli piaskownica jest wyłączona, narzędzia działają na hoście. Gateway pozostaje na hoście; wykonywanie narzędzi działa 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 uruchamiania poza piaskownicą (np. tools.elevated).
  • Podniesione exec omija piaskownicę i używa skonfigurowanej ścieżki wyjścia (gateway domyślnie albo node, gdy celem exec jest node).
  • Jeśli piaskownica jest wyłączona, 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 wykonawcze zapewnia piaskownicę:

• "docker" (domyślnie, gdy piaskownica jest włączona): lokalne środowisko wykonawcze piaskownicy oparte na Docker.
• "ssh": ogólne zdalne środowisko wykonawcze piaskownicy oparte na SSH.
• "openshell": środowisko wykonawcze 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

Piaskownica jest domyślnie wyłączona. 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 dla konkretnego agenta agents.list[].sandbox.docker.gpus. Wartość jest przekazywana do flagi Docker --gpus jako osobny argument, na przykład "all" lub "device=GPU-uuid", i wymaga zgodnego środowiska wykonawczego hosta, takiego jak NVIDIA Container Toolkit.

Backend SSH

Użyj backend: "ssh", gdy chcesz, aby OpenClaw uruchamiał exec, narzędzia plikowe i odczyty multimediów w piaskownicy 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 obszaru roboczego znajdziesz na dedykowanej stronie OpenShell.

OpenShell ponownie używa tego samego podstawowego transportu SSH i mostu zdalnego systemu plików co ogólny backend SSH, a dodatkowo dodaje cykl życia specyficzny dla OpenShell (sandbox create/get/delete, sandbox ssh-config) oraz opcjonalny tryb obszaru roboczego 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): lokalny obszar roboczy pozostaje kanoniczny. OpenClaw synchronizuje lokalne pliki do OpenShell przed exec i synchronizuje zdalny obszar roboczy z powrotem po exec.
• remote: obszar roboczy OpenShell jest kanoniczny po utworzeniu piaskownicy. OpenClaw jednorazowo zasiewa zdalny obszar roboczy z lokalnego, 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 sandbox jako tymczasowe środowisko wykonawcze. Wybierz remote, jeśli traktujesz sandbox jako rzeczywistą przestrzeń roboczą.

Cykl życia OpenShell

Sandboxy OpenShell są nadal zarządzane przez normalny cykl życia sandboxa:

• openclaw sandbox list pokazuje runtime OpenShell oraz runtime Docker
• openclaw sandbox recreate usuwa bieżący runtime i pozwala OpenClaw odtworzyć go przy następnym użyciu
• logika czyszczenia również uwzględnia backend

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

• odtworzenie usuwa kanoniczną zdalną przestrzeń roboczą dla tego zakresu
• następne użycie inicjuje świeżą zdalną przestrzeń roboczą z lokalnej przestrzeni roboczej

Dla trybu mirror odtworzenie głównie resetuje zdalne środowisko wykonawcze, ponieważ lokalna przestrzeń robocza i tak pozostaje kanoniczna.

Dostęp do przestrzeni roboczej

agents.defaults.sandbox.workspaceAccess kontroluje co sandbox może widzieć:

Z backendem OpenShell:

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

Przychodzące multimedia są kopiowane do aktywnej przestrzeni roboczej sandboxa (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-agentowe bind są scalane (nie zastępowane). Przy scope: "shared" per-agentowe bind są ignorowane.

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

• Gdy jest ustawione (w tym []), zastępuje agents.defaults.sandbox.docker.binds dla kontenera przeglądarki.
• Gdy jest pominięte, kontener przeglądarki wraca do agents.defaults.sandbox.docker.binds (zgodne wstecz).

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 sandboxa Docker działają bez sieci. Nadpisz to za pomocą agents.defaults.sandbox.docker.network.

Instalacje Docker i skonteneryzowany 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ę gniazda można 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:

• Globalna: agents.defaults.sandbox.docker.setupCommand
• Dla agenta: agents.list[].sandbox.docker.setupCommand

Zasady narzędzi i awaryjne obejścia

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

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

Debugowanie:

• Użyj openclaw sandbox explain, aby sprawdzić efektywny tryb piaskownicy, zasady narzędzi i klucze konfiguracji naprawczej.
• Zobacz Piaskownica a zasady narzędzi a podniesione uprawnienia, aby poznać model mentalny "dlaczego to jest blokowane?".

Utrzymuj ścisłe ograniczenia.

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 dla 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 dla wielu agentów — nadpisania dla agentów i kolejność pierwszeństwa
• OpenShell — konfiguracja zarządzanego zaplecza piaskownicy, tryby obszaru roboczego i opis konfiguracji
• Konfiguracja piaskownicy
• Piaskownica a zasady narzędzi a podniesione uprawnienia — debugowanie "dlaczego to jest blokowane?"
• Bezpieczeństwo