​

Sandboxing

​

Co jest objęte sandboxem

• Wykonywanie narzędzi (exec, read, write, edit, apply_patch, process itd.).
• Opcjonalna przeglądarka w sandboxie (agents.defaults.sandbox.browser).
  • Domyślnie przeglądarka sandboxa uruchamia się automatycznie (zapewnia dostępność 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 sandboxa 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 wejściowy ruch CDP na krawędzi kontenera za pomocą listy dozwolonych CIDR (na przykład 172.21.0.1/32).
  • Dostęp obserwatora noVNC jest domyślnie chroniony hasłem; OpenClaw emituje krótkotrwały URL z tokenem, który serwuje lokalną stronę bootstrap i otwiera noVNC z hasłem we fragmencie URL-a (nie w logach query/header).
  • agents.defaults.sandbox.browser.allowHostControl pozwala sesjom w sandboxie jawnie kierować się na przeglądarkę hosta.
  • Opcjonalne listy dozwolonych wartości ograniczają target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

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

​

Tryby

• "off": brak sandboxingu.
• "non-main": sandbox tylko dla sesji niebędących 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 nie-main i będą objęte sandboxem.

​

Zakres

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

​

Backend

• "docker" (domyślnie): lokalne środowisko sandbox oparte na Dockerze.
• "ssh": ogólne zdalne środowisko sandbox oparte na SSH.
• "openshell": środowisko sandbox oparte na OpenShell.

​

Wybór backendu

​

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",
          // Albo użyj SecretRefs / zawartości inline zamiast plików lokalnych:
          // 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 zakres w sandbox.ssh.workspaceRoot.
• Przy pierwszym użyciu po utworzeniu lub odtworzeniu OpenClaw jednorazowo zasiewa ten zdalny workspace z lokalnego workspace.
• Następnie exec, read, write, edit, apply_patch, odczyty multimediów w promptach i staging multimediów przychodzących działają bezpośrednio na zdalnym workspace przez SSH.
• OpenClaw nie synchronizuje automatycznie zdalnych zmian z powrotem do lokalnego workspace.

• identityFile, certificateFile, knownHostsFile: używają istniejących plików lokalnych i przekazują je przez konfigurację OpenSSH.
• identityData, certificateData, knownHostsData: używają ciągów inline lub SecretRefs. OpenClaw rozwiązuje je przez zwykły snapshot środowiska sekretów, zapisuje do plików tymczasowych z uprawnieniami 0600 i usuwa je po zakończeniu sesji SSH.
• Jeśli dla tego samego elementu ustawione są zarówno *File, jak i *Data, dla tej sesji SSH wygrywa *Data.

• Lokalne edycje hosta wykonane poza OpenClaw po etapie zasiania nie są widoczne zdalnie, dopóki nie odtworzysz sandboxa.
• openclaw sandbox recreate usuwa zdalny katalog główny per zakres i przy następnym użyciu ponownie zasiewa go lokalnie.
• Przeglądarka sandbox nie jest obsługiwana przez backend 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: po utworzeniu sandboxa workspace OpenShell staje się kanoniczny. OpenClaw jednorazowo zasiewa zdalny workspace z lokalnego workspace, a potem narzędzia plikowe i exec działają bezpośrednio na zdalnym sandboxie bez synchronizowania zmian z powrotem.

• OpenClaw pobiera konfigurację SSH specyficzną dla sandboxa przez openshell sandbox ssh-config <name>.
• Rdzeń zapisuje tę konfigurację SSH do pliku tymczasowego, otwiera sesję SSH i używa tego samego mostu zdalnego systemu plików co przy backend: "ssh".
• Tylko w trybie mirror cykl życia się różni: synchronizacja lokalnie -> zdalnie przed exec, a potem zdalnie -> lokalnie po exec.

• przeglądarka sandbox jeszcze nie jest obsługiwana
• sandbox.docker.binds nie jest obsługiwane przez backend OpenShell
• ustawienia środowiska wykonawczego specyficzne dla Dockera w sandbox.docker.* nadal mają zastosowanie tylko do 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 most sandboxa, ale lokalny workspace pozostaje źródłem prawdy między turami.

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

• dodatkowy koszt synchronizacji przed i po exec

remote

• Gdy sandbox jest tworzony po raz pierwszy, OpenClaw jednorazowo zasiewa 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 multimediów w czasie promptu nadal działają, ponieważ narzędzia plikowe i multimedialne czytają przez most sandboxa zamiast zakładać lokalną ścieżkę hosta.
• Transport odbywa się przez SSH do sandboxa OpenShell zwróconego przez openshell sandbox ssh-config.

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

• sandbox ma działać głównie po zdalnej stronie OpenShell
• chcesz mniejszego narzutu synchronizacji na każdą turę
• nie chcesz, aby lokalne edycje hosta po cichu nadpisywały stan zdalnego sandboxa

​

Cykl życia OpenShell

• openclaw sandbox list pokazuje środowiska wykonawcze OpenShell oraz Docker
• openclaw sandbox recreate usuwa bieżące środowisko wykonawcze i pozwala OpenClaw odtworzyć je przy następnym użyciu
• logika przycinania także uwzględnia backend

• recreate usuwa kanoniczny zdalny workspace dla tego zakresu
• przy następnym użyciu zostanie zasiany nowy zdalny workspace z lokalnego workspace

​

Dostęp do workspace

• "none" (domyślnie): narzędzia widzą workspace sandboxa w ~/.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 po początkowym zasianiu używa zdalnego workspace OpenShell jako kanonicznego źródła
• workspaceAccess: "ro" i "none" nadal ograniczają zachowanie zapisu w ten sam sposób

​

Niestandardowe bind mounts

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

• Binds omijają system plików sandboxa: udostępniają ścieżki hosta w ustawionym trybie (:ro lub :rw).
• OpenClaw blokuje niebezpieczne źródła bindów (na przykład: docker.sock, /etc, /proc, /sys, /dev oraz nadrzędne punkty montowania, 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 nie opiera się tylko na dopasowaniu ciągów. OpenClaw normalizuje ścieżkę źródłową, a następnie ponownie rozwiązuje ją przez najgłębszego istniejącego przodka przed ponownym sprawdzeniem zablokowanych ścieżek i dozwolonych katalogów głównych.
• Oznacza to, że ucieczki przez symlink-parent nadal kończą się bezpieczną odmową, nawet gdy końcowy element jeszcze nie istnieje. Przykład: /workspace/run-link/new-file nadal zostanie rozwiązane 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 na mieszczącą się w allowliście przed rozwiązaniem symlinków, nadal zostanie odrzucona jako outside allowed roots.
• Wrażliwe montowania (sekrety, klucze SSH, poświadczenia usług) powinny mieć tryb :ro, chyba że jest to absolutnie konieczne.
• Połącz to z workspaceAccess: "ro", jeśli potrzebujesz tylko dostępu do odczytu workspace; tryby bindów pozostają niezależne.
• Zobacz Sandbox vs Tool Policy vs Elevated, aby sprawdzić, 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 włączone jest noSandbox.
• Trzy flagi hardeningu grafiki (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) są opcjonalne i przydają się, gdy kontenery nie mają wsparcia GPU. Ustaw OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0, jeśli Twoje obciążenie wymaga WebGL lub innych funkcji 3D/przeglądarkowych.
• --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ślną wartość 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 ruchu wychodzącego), więc instalacje pakietów się nie powiodą.
• docker.network: "container:<id>" wymaga dangerouslyAllowContainerNamespaceJoin: true i jest tylko obejściem awaryjnym.
• readOnlyRoot: true uniemożliwia zapis; ustaw readOnlyRoot: false albo przygotuj niestandardowy obraz.
• user musi być rootem do instalacji pakietów (pomiń user lub ustaw user: "0:0").
• Sandbox exec nie dziedziczy host process.env. Użyj agents.defaults.sandbox.docker.env (lub niestandardowego obrazu) dla kluczy API Skills.

​

Polityka narzędzi + ścieżki ucieczki

• Użyj openclaw sandbox explain, aby sprawdzić efektywny tryb sandboxa, politykę narzędzi i klucze konfiguracji naprawczej.
• Zobacz Sandbox vs Tool Policy vs Elevated, aby zrozumieć model „dlaczego to jest zablokowane?”. Utrzymuj to w bezpiecznej konfiguracji.

​

Nadpisania Multi-Agent

​

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 dokumentacja ustawień
• Konfiguracja sandboxa
• Sandbox vs Tool Policy vs Elevated — debugowanie „dlaczego to jest zablokowane?”
• Multi-Agent Sandbox & Tools — nadpisania per agent i priorytety
• Security