Piaskownica

​

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).

• 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

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

• 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 Docker

​

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

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

• 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

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}

​

Dostęp do obszaru roboczego

​

Niestandardowe montowania typu bind

{
  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

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 (jednorazowa konfiguracja kontenera)

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

​

Zasady narzędzi i drogi obejścia zabezpieczeń

• 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

​

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