​

Sandboxing

​

Co jest sandboxowane

• Wykonywanie narzędzi (exec, read, write, edit, apply_patch, process itd.).
• Opcjonalna przeglądarka sandboxowana (agents.defaults.sandbox.browser).
  • Domyślnie przeglądarka sandbox jest uruchamiana automatycznie (zapewnia osiągalność CDP), gdy narzędzie przeglądarki jej potrzebuje. Konfiguracja przez agents.defaults.sandbox.browser.autoStart i agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • Domyślnie kontenery przeglądarki sandbox używają dedykowanej sieci Docker (openclaw-sandbox-browser) zamiast globalnej sieci bridge. Konfiguracja przez agents.defaults.sandbox.browser.network.
  • Opcjonalne agents.defaults.sandbox.browser.cdpSourceRange ogranicza ingress CDP na krawędzi kontenera przez allowlist CIDR (na przykład 172.21.0.1/32).
  • Dostęp obserwatora noVNC jest domyślnie chroniony hasłem; OpenClaw emituje krótkożyjący URL z tokenem, który serwuje lokalną stronę bootstrap i otwiera noVNC z hasłem w fragmencie URL (a nie w logach query/header).
  • agents.defaults.sandbox.browser.allowHostControl pozwala sandboxowanym sesjom jawnie kierować się do przeglądarki hosta.
  • Opcjonalne allowlist kontrolują target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Sam proces Gateway.
• Każde narzędzie jawnie dopuszczone do uruchamiania poza sandboxem (np. tools.elevated).
  • Elevated exec omija sandboxing i używa skonfigurowanej ścieżki wyjścia (gateway domyślnie albo node, gdy celem exec jest node).
  • Jeśli sandboxing jest wyłączony, tools.elevated nie zmienia wykonania (już działa na hoście). Zobacz Tryb Elevated.

​

Tryby

• "off": bez sandboxingu.
• "non-main": sandboxuj tylko sesje nie-main (domyślnie, jeśli chcesz normalne czaty na hoście).
• "all": każda sesja działa w sandboxie. Uwaga: "non-main" opiera się na session.mainKey (domyślnie "main"), a nie na identyfikatorze agenta. Sesje grupowe/kanałowe używają własnych kluczy, więc są traktowane jako non-main i będą sandboxowane.

​

Scope

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

​

Backend

• "docker" (domyślnie, gdy sandboxing jest włączony): lokalny runtime sandbox oparty na Docker.
• "ssh": generyczny zdalny runtime sandbox oparty na SSH.
• "openshell": runtime sandbox oparty na OpenShell.

​

Wybór backendu

​

Backend Docker

• Konfiguracja wymaga ścieżek hosta: konfiguracja workspace w openclaw.json MUSI zawierać bezwzględną ścieżkę hosta (np. /home/user/.openclaw/workspaces), a nie wewnętrzną ścieżkę kontenera Gateway. Gdy OpenClaw prosi demona Docker o uruchomienie sandboxa, demon ocenia ścieżki względem przestrzeni nazw systemu operacyjnego hosta, a nie przestrzeni nazw Gateway.
• Parzystość FS Bridge (identyczne mapowanie wolumenów): natywny proces Gateway OpenClaw także zapisuje pliki heartbeat i bridge do katalogu workspace. Ponieważ Gateway ocenia ten sam dokładny ciąg znaków (ścieżkę hosta) ze swojego własnego środowiska kontenerowego, wdrożenie Gateway MUSI zawierać identyczne mapowanie wolumenu łączące przestrzeń nazw hosta natywnie (-v /home/user/.openclaw:/home/user/.openclaw).

​

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",
          // Lub użyj SecretRefs / treści inline zamiast lokalnych plików:
          // 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" },
        },
      },
    },
  },
}

• OpenClaw tworzy zdalny katalog główny per scope pod sandbox.ssh.workspaceRoot.
• Przy pierwszym użyciu po utworzeniu albo odtworzeniu OpenClaw jednorazowo seeduje ten zdalny workspace z lokalnego workspace.
• Potem exec, read, write, edit, apply_patch, odczyty mediów promptu i etapowanie mediów przychodzących działają bezpośrednio na zdalnym workspace przez SSH.
• OpenClaw nie synchronizuje zmian zdalnych z powrotem do lokalnego workspace automatycznie.

• identityFile, certificateFile, knownHostsFile: używają istniejących lokalnych plików i przekazują je przez konfigurację OpenSSH.
• identityData, certificateData, knownHostsData: używają ciągów inline albo SecretRefs. OpenClaw rozwiązuje je przez normalną migawkę runtime secrets, zapisuje do plików tymczasowych z 0600 i usuwa po zakończeniu sesji SSH.
• Jeśli dla tego samego elementu ustawiono zarówno *File, jak i *Data, dla tej sesji SSH wygrywa *Data.

• Lokalne edycje hosta wykonane poza OpenClaw po kroku seed nie są widoczne zdalnie, dopóki nie odtworzysz sandboxa.
• openclaw sandbox recreate usuwa zdalny katalog główny per scope i przy następnym użyciu seeduje go ponownie z lokalnego.
• Browser sandboxing nie jest obsługiwany w backendzie SSH.
• Ustawienia sandbox.docker.* nie mają zastosowania do backendu SSH.

​

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
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

• mirror (domyślnie): lokalny workspace pozostaje kanoniczny. OpenClaw synchronizuje lokalne pliki do OpenShell przed exec i synchronizuje zdalny workspace z powrotem po exec.
• remote: workspace OpenShell jest kanoniczny po utworzeniu sandboxa. OpenClaw jednorazowo seeduje zdalny workspace z lokalnego workspace, a następnie narzędzia plikowe i exec działają bezpośrednio na zdalnym sandboxie bez synchronizacji zmian z powrotem.

• OpenClaw prosi OpenShell o konfigurację SSH specyficzną dla sandbox przez openshell sandbox ssh-config <name>.
• Core zapisuje tę konfigurację SSH do pliku tymczasowego, otwiera sesję SSH i używa ponownie tego samego zdalnego mostka systemu plików, który jest używany przez backend: "ssh".
• Tylko w trybie mirror lifecycle jest inny: synchronizacja lokalne do zdalnego przed exec, potem synchronizacja z powrotem po exec.

• sandbox browser nie jest jeszcze obsługiwany
• sandbox.docker.binds nie jest obsługiwane w backendzie OpenShell
• parametry runtime specyficzne dla Docker pod sandbox.docker.* nadal dotyczą tylko backendu Docker

​

Tryby workspace

mirror

• Przed exec OpenClaw synchronizuje lokalny workspace do sandboxa OpenShell.
• Po exec OpenClaw synchronizuje zdalny workspace z powrotem do lokalnego workspace.
• Narzędzia plikowe nadal działają przez mostek sandbox, ale lokalny workspace pozostaje źródłem prawdy między turami.

• edytujesz pliki lokalnie poza OpenClaw i chcesz, aby te zmiany pojawiały się automatycznie w sandboxie
• chcesz, aby sandbox OpenShell zachowywał się możliwie najbardziej podobnie do backendu Docker
• chcesz, aby workspace hosta odzwierciedlał zapisy sandbox po każdej turze exec

• dodatkowy koszt synchronizacji przed i po exec

remote

• Gdy sandbox jest tworzony po raz pierwszy, OpenClaw jednorazowo seeduje zdalny workspace z lokalnego workspace.
• Następnie exec, read, write, edit i apply_patch działają bezpośrednio na zdalnym workspace OpenShell.
• OpenClaw nie synchronizuje zdalnych zmian z powrotem do lokalnego workspace po exec.
• Odczyty mediów w czasie promptu nadal działają, ponieważ narzędzia plikowe i multimedialne odczytują przez mostek sandbox zamiast zakładać lokalną ścieżkę hosta.
• Transport to SSH do sandboxa OpenShell zwróconego przez openshell sandbox ssh-config.

• Jeśli edytujesz pliki na hoście poza OpenClaw po kroku seed, zdalny sandbox nie zobaczy tych zmian automatycznie.
• Jeśli sandbox zostanie odtworzony, zdalny workspace jest ponownie seedowany z lokalnego workspace.
• Przy scope: "agent" albo scope: "shared" ten zdalny workspace jest współdzielony w tym samym scope.

• sandbox ma żyć głównie po zdalnej stronie OpenShell
• chcesz mniejszego narzutu synchronizacji per tura
• nie chcesz, aby lokalne edycje hosta po cichu nadpisywały stan zdalnego sandboxa

​

Lifecycle OpenShell

• openclaw sandbox list pokazuje runtime OpenShell, a także runtime Docker
• openclaw sandbox recreate usuwa bieżący runtime i pozwala OpenClaw odtworzyć go przy następnym użyciu
• logika prune także uwzględnia backend

• recreate usuwa kanoniczny zdalny workspace dla danego scope
• następne użycie seeduje świeży zdalny workspace z lokalnego workspace

​

Dostęp do workspace

• "none" (domyślnie): narzędzia widzą sandbox workspace pod ~/.openclaw/sandboxes.
• "ro": montuje workspace agenta tylko do odczytu pod /agent (wyłącza write/edit/apply_patch).
• "rw": montuje workspace agenta do odczytu i zapisu pod /workspace.

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

​

Niestandardowe bind mounty

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

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

• Bindy omijają system plików sandboxa: udostępniają ścieżki hosta z ustawionym trybem (:ro albo :rw).
• OpenClaw blokuje niebezpieczne źródła bindów (na przykład: docker.sock, /etc, /proc, /sys, /dev oraz montowania nadrzędne, które by je ujawniały).
• OpenClaw blokuje także typowe katalogi główne z poświadczeniami w katalogu domowym, takie jak ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm i ~/.ssh.
• Walidacja bindów to nie tylko dopasowanie ciągów. OpenClaw normalizuje ścieżkę źródłową, a następnie rozwiązuje ją ponownie przez najgłębszego istniejącego przodka przed ponownym sprawdzeniem zablokowanych ścieżek i dozwolonych katalogów głównych.
• Oznacza to, że ucieczki przez rodzica będącego linkiem symbolicznym nadal kończą się fail-closed, nawet gdy końcowy liść jeszcze nie istnieje. Przykład: /workspace/run-link/new-file nadal rozwiązuje się jako /var/run/..., jeśli run-link wskazuje tam.
• Dozwolone katalogi główne źródeł są kanonikalizowane w ten sam sposób, więc ścieżka, która tylko wygląda, jakby znajdowała się na allowlist przed rozwiązaniem linku symbolicznego, nadal jest odrzucana jako outside allowed roots.
• Wrażliwe montowania (sekrety, klucze SSH, poświadczenia usług) powinny być :ro, chyba że jest to absolutnie wymagane.
• Połącz to z workspaceAccess: "ro", jeśli potrzebujesz tylko dostępu do odczytu do workspace; tryby bindów pozostają niezależne.
• Zobacz Sandbox vs Tool Policy vs Elevated, aby zrozumieć, jak bindy współdziałają z polityką narzędzi i elevated exec.

​

Obrazy + konfiguracja

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox i --disable-setuid-sandbox, gdy noSandbox jest włączone.
• Trzy flagi utwardzania grafiki (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) są opcjonalne i są przydatne, gdy kontenery nie mają obsługi GPU. Ustaw OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0, jeśli Twój workload wymaga WebGL albo innych funkcji 3D/przeglądarki.
• --disable-extensions jest domyślnie włączone i można je wyłączyć przez OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 dla przepływów zależnych od rozszerzeń.
• --renderer-process-limit=2 jest kontrolowane przez OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, gdzie 0 zachowuje domyślne ustawienie Chromium.

• network: "host" jest blokowane.
• network: "container:<id>" jest domyślnie blokowane (ryzyko obejścia przez dołączenie do namespace).
• Awaryjne obejście: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (jednorazowa konfiguracja kontenera)

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

• Domyślne docker.network to "none" (brak egress), więc instalacje pakietów zakończą się niepowodzeniem.
• docker.network: "container:<id>" wymaga dangerouslyAllowContainerNamespaceJoin: true i jest tylko awaryjnym obejściem.
• readOnlyRoot: true uniemożliwia zapis; ustaw readOnlyRoot: false albo przygotuj niestandardowy obraz.
• user musi być root dla instalacji pakietów (pomiń user albo ustaw user: "0:0").
• Sandbox exec nie dziedziczy host process.env. Użyj agents.defaults.sandbox.docker.env (albo niestandardowego obrazu) dla kluczy API Skill.

​

Polityka narzędzi + ścieżki wyjścia

• Użyj openclaw sandbox explain, aby sprawdzić efektywny tryb sandbox, politykę narzędzi i klucze konfiguracji naprawy.
• Zobacz Sandbox vs Tool Policy vs Elevated, aby zrozumieć model „dlaczego to jest zablokowane?”. Zachowaj ścisłe ograniczenia.

​

Nadpisania wielu agentów

​

Minimalny przykład włączenia

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

​

Powiązana dokumentacja

• OpenShell — konfiguracja zarządzanego backendu sandbox, tryby workspace i referencja konfiguracji
• Konfiguracja Sandbox
• Sandbox vs Tool Policy vs Elevated — debugowanie „dlaczego to jest zablokowane?”
• Sandbox i narzędzia wielu agentów — nadpisania per agent i priorytety
• Bezpieczeństwo