OpenShell

OpenShell to zarządzany backend piaskownicy: zamiast uruchamiać kontenery Docker lokalnie, OpenClaw deleguje cykl życia piaskownicy do CLI openshell, które udostępnia zdalne środowiska i wykonuje polecenia przez SSH. Plugin ponownie wykorzystuje ten sam transport SSH i most zdalnego systemu plików co ogólny backend SSH, a także dodaje obsługę cyklu życia OpenShell (sandbox create/get/delete/ssh-config) oraz opcjonalny tryb synchronizacji przestrzeni roboczej mirror.

Wymagania wstępne

Zainstalowany plugin OpenShell (openclaw plugins install @openclaw/openshell-sandbox)
CLI openshell dostępne w PATH (lub niestandardowa ścieżka ustawiona przez plugins.entries.openshell.config.command)
Konto OpenShell z dostępem do piaskownic
Gateway OpenClaw uruchomiony na hoście

Szybki start

openclaw plugins install @openclaw/openshell-sandbox

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

Uruchom ponownie Gateway. Przy następnym cyklu agenta OpenClaw utworzy piaskownicę OpenShell i skieruje przez nią wykonywanie narzędzi. Sprawdź to za pomocą:

openclaw sandbox list
openclaw sandbox explain

Tryby przestrzeni roboczej

To najważniejsza decyzja dotycząca OpenShell.

mirror (domyślny)

plugins.entries.openshell.config.mode: "mirror" sprawia, że lokalna przestrzeń robocza jest kanoniczna:

Przed exec OpenClaw synchronizuje lokalną przestrzeń roboczą z piaskownicą.
Po exec OpenClaw synchronizuje zdalną przestrzeń roboczą z powrotem do lokalnej.
Narzędzia plikowe korzystają z mostu piaskownicy, ale między cyklami źródłem prawdy pozostaje lokalna przestrzeń robocza.

Najlepszy wybór dla przepływów pracy programistycznej: lokalne zmiany wprowadzone poza OpenClaw pojawią się przy następnym exec, a piaskownica zachowuje się podobnie do backendu Docker. Kompromis: koszt wysyłania i pobierania przy każdym cyklu exec.

remote

mode: "remote" sprawia, że przestrzeń robocza OpenShell jest kanoniczna:

Przy pierwszym utworzeniu piaskownicy OpenClaw jednorazowo inicjalizuje zdalną przestrzeń roboczą na podstawie lokalnej.
Następnie exec, read, write, edit i apply_patch działają bezpośrednio na zdalnej przestrzeni roboczej. OpenClaw nie synchronizuje zdalnych zmian z powrotem do lokalnej przestrzeni roboczej.
Odczyty multimediów podczas tworzenia promptu nadal działają (narzędzia plikowe i multimedialne odczytują dane przez most piaskownicy).

Najlepszy wybór dla długotrwale działających agentów i CI: mniejszy narzut na cykl, a lokalne zmiany na hoście nie mogą po cichu nadpisać stanu zdalnego.

Edycja plików na hoście poza OpenClaw po początkowej inicjalizacji nie jest widoczna dla zdalnej piaskownicy. Uruchom openclaw sandbox recreate, aby zainicjalizować ją ponownie.

Wybór trybu

	`mirror`	`remote`
Kanoniczna przestrzeń robocza	Host lokalny	Zdalny OpenShell
Kierunek synchronizacji	Dwukierunkowy (przy każdym `exec`)	Jednorazowa inicjalizacja
Narzut na cykl	Wyższy (wysyłanie i pobieranie)	Niższy (bezpośrednie operacje zdalne)
Czy lokalne zmiany są widoczne?	Tak, przy następnym `exec`	Nie, do czasu ponownego utworzenia
Najlepsze zastosowanie	Przepływy pracy programistycznej	Długotrwale działający agenci, CI

Dokumentacja konfiguracji

Cała konfiguracja OpenShell znajduje się w plugins.entries.openshell.config:

Klucz	Typ	Wartość domyślna	Opis
`mode`	`"mirror"` lub `"remote"`	`"mirror"`	Tryb synchronizacji przestrzeni roboczej
`command`	`string`	`"openshell"`	Ścieżka lub nazwa CLI `openshell`
`from`	`string`	`"openclaw"`	Źródło piaskownicy przy pierwszym utworzeniu
`gateway`	`string`	nieustawiona	Nazwa Gateway OpenShell (`--gateway` najwyższego poziomu)
`gatewayEndpoint`	`string`	nieustawiona	Punkt końcowy Gateway OpenShell (`--gateway-endpoint` najwyższego poziomu)
`policy`	`string`	nieustawiona	Identyfikator zasad OpenShell używany podczas tworzenia piaskownicy
`providers`	`string[]`	`[]`	Nazwy dostawców dołączanych podczas tworzenia piaskownicy (bez duplikatów, jedna flaga `--provider` na wpis)
`gpu`	`boolean`	`false`	Żądanie zasobów GPU (`--gpu`)
`autoProviders`	`boolean`	`true`	Przekazuje `--auto-providers` (lub `--no-auto-providers`, gdy wartość to `false`) podczas tworzenia
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Główna zapisywalna przestrzeń robocza wewnątrz piaskownicy
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Ścieżka montowania przestrzeni roboczej agenta (tylko do odczytu, gdy dostęp do przestrzeni roboczej nie ma wartości `rw`)
`timeoutSeconds`	`number`	`120`	Limit czasu operacji CLI `openshell`

remoteWorkspaceDir i remoteAgentWorkspaceDir muszą być ścieżkami bezwzględnymi i pozostawać w zarządzanych katalogach głównych /sandbox lub /agent; inne ścieżki bezwzględne są odrzucane. Ustawienia na poziomie piaskownicy (mode, scope, workspaceAccess) znajdują się w agents.defaults.sandbox, tak jak w przypadku każdego backendu. Pełną macierz opisano w sekcji Piaskownice.

Przykłady

Minimalna konfiguracja zdalna

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

Tryb mirror z GPU

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

OpenShell dla poszczególnych agentów z niestandardowym Gateway

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

Zarządzanie cyklem życia

# Wyświetl wszystkie środowiska wykonawcze piaskownic (Docker + OpenShell)
openclaw sandbox list

# Sprawdź obowiązujące zasady
openclaw sandbox explain

# Utwórz ponownie (usuwa zdalną przestrzeń roboczą i inicjalizuje ją ponownie przy następnym użyciu)
openclaw sandbox recreate --all

W trybie remote ponowne utworzenie jest szczególnie ważne: usuwa kanoniczną zdalną przestrzeń roboczą dla danego zakresu, a przy następnym użyciu inicjalizuje nową na podstawie lokalnej przestrzeni roboczej. W trybie mirror ponowne utworzenie głównie resetuje zdalne środowisko wykonawcze, ponieważ lokalna przestrzeń robocza pozostaje kanoniczna. Utwórz piaskownicę ponownie po zmianie któregokolwiek z następujących ustawień:

agents.defaults.sandbox.backend
plugins.entries.openshell.config.from
plugins.entries.openshell.config.mode
plugins.entries.openshell.config.policy

Wzmocnienie zabezpieczeń

Most systemu plików w trybie mirror przypina katalog główny lokalnej przestrzeni roboczej i ponownie sprawdza ścieżki kanoniczne (za pomocą realpath) przed każdym odczytem, zapisem, utworzeniem katalogu, usunięciem i zmianą nazwy, odrzucając dowiązania symboliczne w środkowych segmentach ścieżki. Podmiana dowiązania symbolicznego lub ponowne zamontowanie przestrzeni roboczej nie może przekierować dostępu do plików poza replikowane drzewo.

Obecne ograniczenia

Przeglądarka piaskownicy nie jest obsługiwana przez backend OpenShell.
sandbox.docker.binds nie ma zastosowania do OpenShell; tworzenie piaskownicy kończy się niepowodzeniem, jeśli skonfigurowano powiązania.
Ustawienia środowiska wykonawczego specyficzne dla Docker w sandbox.docker.* (poza env) dotyczą wyłącznie backendu Docker.

Jak to działa

OpenClaw uruchamia sandbox get dla nazwy piaskownicy (z każdym skonfigurowanym --gateway/--gateway-endpoint); jeśli to polecenie zakończy się niepowodzeniem, tworzy piaskownicę za pomocą sandbox create, przekazując --name, --from, --policy, jeśli ustawiono, --gpu, jeśli włączono, --auto-providers/--no-auto-providers oraz po jednej fladze --provider dla każdego skonfigurowanego dostawcy.
OpenClaw uruchamia sandbox ssh-config dla nazwy piaskownicy, aby pobrać szczegóły połączenia SSH.
Rdzeń zapisuje konfigurację SSH w pliku tymczasowym i otwiera sesję SSH przez ten sam most zdalnego systemu plików co ogólny backend SSH.
W trybie mirror: synchronizuje dane lokalne ze zdalnymi przed exec, wykonuje polecenie, a następnie synchronizuje dane z powrotem.
W trybie remote: inicjalizuje przestrzeń roboczą raz podczas tworzenia, a następnie działa bezpośrednio na zdalnej przestrzeni roboczej.

Powiązane materiały

Piaskownice — tryby, zakresy i porównanie backendów
Piaskownica a zasady narzędzi a tryb podwyższonych uprawnień — debugowanie zablokowanych narzędzi
Piaskownica i narzędzia dla wielu agentów — ustawienia zastępcze dla poszczególnych agentów
CLI piaskownicy — polecenia openclaw sandbox

Gateway

Remote access

Security

Nodes and media

Web interfaces

Wymagania wstępne

Szybki start

Tryby przestrzeni roboczej

mirror (domyślny)

remote

Wybór trybu

Dokumentacja konfiguracji

Przykłady

Minimalna konfiguracja zdalna

Tryb mirror z GPU

OpenShell dla poszczególnych agentów z niestandardowym Gateway

Zarządzanie cyklem życia

Wzmocnienie zabezpieczeń

Obecne ograniczenia

Jak to działa

Powiązane materiały

​Wymagania wstępne

​Szybki start

​Tryby przestrzeni roboczej

​mirror (domyślny)

​remote

​Wybór trybu

​Dokumentacja konfiguracji

​Przykłady

​Minimalna konfiguracja zdalna

​Tryb mirror z GPU

​OpenShell dla poszczególnych agentów z niestandardowym Gateway

​Zarządzanie cyklem życia

​Wzmocnienie zabezpieczeń

​Obecne ograniczenia

​Jak to działa

​Powiązane materiały

Wymagania wstępne

Szybki start

Tryby przestrzeni roboczej

mirror (domyślny)

remote

Wybór trybu

Dokumentacja konfiguracji

Przykłady

Minimalna konfiguracja zdalna

Tryb mirror z GPU

OpenShell dla poszczególnych agentów z niestandardowym Gateway

Zarządzanie cyklem życia

Wzmocnienie zabezpieczeń

Obecne ograniczenia

Jak to działa

Powiązane materiały