Piaskownica

OpenClaw może uruchamiać wykonywanie narzędzi w backendzie piaskownicy, aby ograniczyć zakres potencjalnych szkód. Piaskownica jest domyślnie wyłączona i kontrolowana przez agents.defaults.sandbox (globalnie) lub agents.list[].sandbox (dla poszczególnych agentów). Proces Gateway zawsze pozostaje na hoście; po włączeniu piaskownicy przenoszone jest do niej wyłącznie wykonywanie narzędzi.

Co jest uruchamiane w piaskownicy

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

Poza piaskownicą:

• Sam proces Gateway.
• Każde narzędzie, któremu jawnie zezwolono na działanie poza piaskownicą za pomocą tools.elevated. Uprzywilejowane wykonywanie poleceń omija piaskownicę i działa w skonfigurowanym miejscu wyjścia (gateway domyślnie lub node, gdy celem wykonywania jest node). Jeśli piaskownica jest wyłączona, tools.elevated niczego nie zmienia, ponieważ polecenia i tak są już wykonywane na hoście. Zobacz Tryb uprzywilejowany.

Tryby, zakres i backend

Zachowanie piaskownicy kontrolują trzy niezależne ustawienia:

Tryb określa, kiedy używana jest piaskownica:

• off: bez piaskownicy.
• non-main: piaskownica dla każdej sesji z wyjątkiem głównej sesji agenta. Kluczem głównej sesji jest zawsze agent:<agentId>:main (lub global, gdy session.scope ma wartość "global"); nie można go konfigurować. Sesje grup i kanałów używają własnych kluczy, dlatego zawsze są uznawane za inne niż główna i działają w piaskownicy.
• all: każda sesja działa w piaskownicy.

Zakres określa liczbę tworzonych kontenerów lub środowisk:

• agent: jeden kontener na agenta.
• session: jeden kontener na sesję.
• shared: jeden kontener współdzielony przez wszystkie sesje działające w piaskownicy (w tym zakresie ignorowane są nadpisania docker/ssh/browser dla poszczególnych agentów).

Backend określa środowisko uruchomieniowe wykonujące narzędzia w piaskownicy. Konfiguracja właściwa dla SSH znajduje się w agents.defaults.sandbox.ssh, a konfiguracja właściwa dla OpenShell — w plugins.entries.openshell.config.

Backend Docker

Docker jest domyślnym backendem po włączeniu piaskownicy. Uruchamia narzędzia i przeglądarki piaskownicy lokalnie za pośrednictwem gniazda demona Docker (/var/run/docker.sock); izolację zapewniają przestrzenie nazw Docker.

Wartości domyślne: network: "none" (brak ruchu wychodzącego), readOnlyRoot: true, capDrop: ["ALL"], obraz openclaw-sandbox:bookworm-slim.

Aby udostępnić procesory graficzne hosta, ustaw agents.defaults.sandbox.docker.gpus (lub nadpisanie dla danego agenta) na wartość taką jak "all" albo "device=GPU-uuid". Wartość ta jest przekazywana do flagi Docker --gpus i wymaga zgodnego środowiska uruchomieniowego hosta, takiego jak NVIDIA Container Toolkit.

Przeglądarka w piaskownicy

• Przeglądarka piaskownicy uruchamia się automatycznie (zapewniając dostępność CDP), gdy wymaga jej narzędzie przeglądarki. Skonfiguruj ją za pomocą agents.defaults.sandbox.browser.autoStart (domyślnie true) i autoStartTimeoutMs (domyślnie 12 s).
• Kontenery przeglądarki piaskownicy korzystają z dedykowanej sieci Docker (openclaw-sandbox-browser) zamiast globalnej sieci bridge. Skonfiguruj ją za pomocą agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange ogranicza przychodzący ruch CDP na granicy kontenera za pomocą listy dozwolonych zakresów CIDR (na przykład 172.21.0.1/32).
• Dostęp obserwatora noVNC jest domyślnie chroniony hasłem; OpenClaw generuje adres URL z krótkotrwałym tokenem, który udostępnia lokalną stronę inicjującą i otwiera noVNC z hasłem we fragmencie adresu URL (nie w ciągu zapytania ani dziennikach nagłówków).
• agents.defaults.sandbox.browser.allowHostControl (domyślnie false) umożliwia sesjom w piaskownicy jawne wskazanie przeglądarki hosta jako celu.
• Opcjonalne listy dozwolonych wartości kontrolują target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Użyj backend: "ssh", aby 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" },        },      },    },  },}

Wartości domyślne: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Cykl życia: OpenClaw tworzy zdalny katalog główny dla każdego zakresu w sandbox.ssh.workspaceRoot. Przy pierwszym użyciu po utworzeniu lub ponownym utworzeniu jednorazowo inicjuje ten zdalny obszar roboczy z lokalnego obszaru roboczego. Następnie exec, read, write, edit, apply_patch, odczyty multimediów na potrzeby promptów oraz przygotowywanie przychodzących multimediów działają bezpośrednio na zdalnym obszarze roboczym przez SSH. OpenClaw nie synchronizuje automatycznie zmian zdalnych z powrotem do lokalnego obszaru roboczego.
• Materiały uwierzytelniające: identityFile/certificateFile/knownHostsFile wskazują istniejące pliki lokalne. identityData/certificateData/knownHostsData przyjmują ciągi podane bezpośrednio lub odwołania SecretRefs, rozwiązywane przez standardową migawkę środowiska uruchomieniowego sekretów, zapisywane w plikach tymczasowych z trybem 0600 i usuwane po zakończeniu sesji SSH. Jeśli dla tego samego elementu ustawiono zarówno wariant *File, jak i *Data, w danej sesji pierwszeństwo ma *Data.
• Konsekwencje zdalnego stanu kanonicznego: po początkowym zainicjowaniu zdalny obszar roboczy SSH staje się rzeczywistym stanem piaskownicy. Lokalne zmiany na hoście wprowadzone poza OpenClaw po etapie inicjowania nie są widoczne zdalnie, dopóki nie utworzysz piaskownicy ponownie. openclaw sandbox recreate usuwa zdalny katalog główny danego zakresu i przy następnym użyciu ponownie inicjuje go z lokalnego obszaru roboczego. Ten backend nie obsługuje piaskownicy przeglądarki, a ustawienia sandbox.docker.* nie mają do niego zastosowania.

Backend OpenShell

Użyj backend: "openshell", aby uruchamiać narzędzia w piaskownicy w zdalnym środowisku zarządzanym przez OpenShell. OpenShell używa tego samego transportu SSH i mostu zdalnego systemu plików co ogólny backend SSH, a ponadto zapewnia obsługę cyklu życia OpenShell (sandbox create/get/delete/ssh-config) oraz opcjonalny tryb synchronizacji 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        },      },    },  },}

mode: "mirror" (domyślny) zachowuje lokalny obszar roboczy jako kanoniczny: OpenClaw synchronizuje dane lokalne z piaskownicą przed exec, a następnie synchronizuje zmiany z powrotem. mode: "remote" jednorazowo inicjuje zdalny obszar roboczy z lokalnego, po czym uruchamia exec/read/write/edit/apply_patch bezpośrednio na zdalnym obszarze roboczym bez synchronizowania zmian z powrotem; lokalne zmiany po zainicjowaniu są niewidoczne, dopóki nie uruchomisz openclaw sandbox recreate. W przypadku scope: "agent" lub scope: "shared" ten zdalny obszar roboczy jest współdzielony w tym samym zakresie. Obecne ograniczenia: piaskownica przeglądarki nie jest jeszcze obsługiwana, a sandbox.docker.binds nie ma zastosowania do tego backendu.

Polecenia openclaw sandbox list/recreate/prune traktują środowiska uruchomieniowe OpenShell tak samo jak środowiska Docker; logika czyszczenia uwzględnia backend.

Pełne wymagania wstępne, opis konfiguracji, porównanie trybów obszaru roboczego i szczegóły cyklu życia znajdziesz w sekcji OpenShell.

Dostęp do obszaru roboczego

agents.defaults.sandbox.workspaceAccess określa, co jest widoczne dla piaskownicy:

W przypadku backendu OpenShell tryb mirror nadal używa lokalnego obszaru roboczego jako źródła kanonicznego między wywołaniami exec, tryb remote po początkowym zainicjowaniu używa jako źródła kanonicznego zdalnego obszaru roboczego OpenShell, a workspaceAccess: "ro"/"none" nadal ogranicza możliwość zapisu w taki sam sposób.

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

Niestandardowe montowania typu bind

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

Globalne montowania typu bind i montowania przypisane do poszczególnych agentów są scalane (a nie zastępowane). Przy scope: "shared" montowania przypisane do poszczególnych agentów są ignorowane.

agents.defaults.sandbox.browser.binds montuje dodatkowe katalogi hosta wyłącznie w kontenerze przeglądarki piaskownicy. Gdy ta opcja jest ustawiona (również na []), zastępuje docker.binds dla kontenera przeglądarki; gdy ją pominięto, kontener przeglądarki używa docker.binds.

{  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 Dockera: 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 Dockera działają bez dostępu do sieci. Można to zmienić za pomocą agents.defaults.sandbox.docker.network.

Informacje o instalacjach Dockera i Gateway działającym w kontenerze znajdują się tutaj: Docker

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

setupCommand (jednorazowa konfiguracja kontenera)

setupCommand jest uruchamiane raz po utworzeniu kontenera piaskownicy (a nie przy każdym uruchomieniu). Jest wykonywane wewnątrz kontenera za pomocą sh -lc.

Ścieżki:

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

Zasady narzędzi i drogi obejścia zabezpieczeń

Zasady zezwalania na narzędzia i blokowania ich nadal obowiązują przed regułami piaskownicy. Jeśli narzędzie jest zablokowane globalnie lub dla konkretnego agenta, piaskownica nie przywraca do niego dostępu.

tools.elevated jest jawnym mechanizmem obejścia, który uruchamia exec poza piaskownicą (domyślnie na gateway, a na node, gdy celem wykonania jest node). Dyrektywy /exec mają zastosowanie tylko do autoryzowanych nadawców i są zachowywane w ramach sesji; aby całkowicie wyłączyć exec, zablokuj je w zasadach narzędzi (zobacz Piaskownica a zasady narzędzi a tryb podwyższonych uprawnień).

Debugowanie:

• openclaw sandbox list wyświetla kontenery piaskownicy, ich stan, zgodność obrazu, wiek, czas bezczynności oraz powiązaną sesję lub agenta.
• openclaw sandbox explain [--session <key>] [--agent <id>] sprawdza obowiązujący tryb piaskownicy, obszar roboczy hosta, katalog roboczy środowiska uruchomieniowego, montowania Dockera, zasady narzędzi i klucze konfiguracji służące do rozwiązania problemu. Pole workspaceRoot nadal zawiera skonfigurowany katalog główny piaskownicy; effectiveHostWorkspaceRoot wskazuje rzeczywistą lokalizację aktywnego obszaru roboczego.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] usuwa kontenery lub środowiska, aby przy następnym użyciu zostały ponownie utworzone zgodnie z bieżącą konfiguracją.
• Zobacz Piaskownica a zasady narzędzi a tryb podwyższonych uprawnień, aby poznać model mentalny odpowiadający na pytanie „dlaczego to jest zablokowane?”.

Ustawienia zastępcze dla wielu agentów

Każdy agent może zastąpić ustawienia piaskownicy i narzędzi: agents.list[].sandbox oraz agents.list[].tools (a także agents.list[].tools.sandbox.tools w przypadku zasad narzędzi piaskownicy). Kolejność pierwszeństwa opisano w sekcji Piaskownica i narzędzia dla wielu agentów.

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 poszczególnych agentów i kolejność pierwszeństwa
• OpenShell -- konfiguracja zarządzanego zaplecza piaskownicy, tryby obszaru roboczego i dokumentacja konfiguracji
• Konfiguracja piaskownicy
• Piaskownica a zasady narzędzi a tryb podwyższonych uprawnień -- diagnozowanie problemu „dlaczego jest to blokowane?”
• Bezpieczeństwo