Izolacja w piaskownicy

OpenClaw może uruchamiać narzędzia wewnątrz backendów piaskownicy, aby zmniejszyć zasięg 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; po włączeniu wykonywanie narzędzi odbywa się w izolowanej piaskownicy.

# 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).
  • Exec z podwyższonymi uprawnieniami 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 z podwyższonymi uprawnieniami.

# 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óry runtime zapewnia piaskownicę:

• "docker" (domyślnie, gdy piaskownica jest włączona): lokalny runtime piaskownicy oparty na Dockerze.
• "ssh": ogólny zdalny runtime piaskownicy oparty na SSH.
• "openshell": runtime piaskownicy oparty 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 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 runtime 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 obszaru roboczego znajdziesz na dedykowanej stronie OpenShell.

OpenShell ponownie wykorzystuje ten sam główny transport SSH i zdalny most systemu plików co ogólny backend SSH oraz dodaje cykl życia specyficzny dla OpenShell (sandbox create/get/delete, sandbox ssh-config) wraz z opcjonalnym trybem 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 pliki lokalne do OpenShell przed exec i synchronizuje zdalny obszar roboczy z powrotem po exec.
• remote: obszar roboczy OpenShell jest kanoniczny po utworzeniu piaskownicy. OpenClaw jednorazowo zasila zdalny obszar roboczy z lokalnego obszaru roboczego, a następnie narzędzia plikowe i exec działają bezpośrednio na zdalnej piaskownicy bez synchronizowania zmian z powrotem.

# Tryby obszaru roboczego

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

Wybierz mirror, jeśli traktujesz sandbox jako tymczasowe środowisko wykonywania. Wybierz remote, jeśli traktujesz sandbox jako rzeczywisty obszar roboczy.

# Cykl życia OpenShell

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

• openclaw sandbox list pokazuje środowiska uruchomieniowe OpenShell oraz 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

W trybie remote odtworzenie jest szczególnie ważne:

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

W trybie mirror odtworzenie głównie resetuje zdalne środowisko wykonywania, ponieważ lokalny obszar roboczy i tak pozostaje kanoniczny.

# Dostęp do obszaru roboczego

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

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 zasileniu
• workspaceAccess: "ro" i "none" nadal ograniczają zachowanie zapisu w ten sam sposób

Przychodzące multimedia są kopiowane do aktywnego obszaru roboczego 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 przypisane do agenta montowania bind są scalane (nie zastępowane). Przy scope: "shared" montowania bind przypisane do agenta 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 używa zastępczo 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-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

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ę sandboxa. Ustaw OPENCLAW_SANDBOX=1 (lub true/yes/on), aby włączyć tę ścieżkę. Możesz nadpisać lokalizację gniazda za pomocą OPENCLAW_DOCKER_SOCKET. Pełna konfiguracja i dokumentacja env: Docker.

# setupCommand (jednorazowa konfiguracja kontenera)

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

Ścieżki:

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

# Polityka 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 przywróci.

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 polityce narzędzi (zobacz Piaskownica kontra polityka narzędzi kontra podniesione uprawnienia).

Debugowanie:

• Użyj openclaw sandbox explain, aby sprawdzić efektywny tryb piaskownicy, politykę narzędzi i klucze konfiguracji do naprawy.
• Zobacz Piaskownica kontra polityka narzędzi kontra podniesione uprawnienia, aby poznać model myślowy dla pytania „dlaczego to jest zablokowane?”.

Utrzymuj to zablokowane.

# Nadpisania wieloagentowe

Każdy agent może nadpisać piaskownicę i narzędzia: agents.list[].sandbox oraz agents.list[].tools (plus agents.list[].tools.sandbox.tools dla polityki narzędzi piaskownicy). Zobacz Wieloagentowa piaskownica i narzędzia, aby poznać pierwszeństwo.

# Minimalny przykład włączenia

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

# Powiązane

• Wieloagentowa piaskownica i narzędzia — nadpisania dla poszczególnych agentów i pierwszeństwo
• OpenShell — konfiguracja zarządzanego zaplecza piaskownicy, tryby obszaru roboczego i odniesienie konfiguracji
• Konfiguracja piaskownicy
• Piaskownica kontra polityka narzędzi kontra podniesione uprawnienia — debugowanie pytania „dlaczego to jest zablokowane?”
• Bezpieczeństwo