OpenShell - OpenClaw

OpenShell to zarządzany backend piaskownicy dla OpenClaw. Zamiast uruchamiać kontenery Docker lokalnie, OpenClaw deleguje cykl życia piaskownicy do CLI openshell, które udostępnia zdalne środowiska z wykonywaniem poleceń przez SSH. Plugin OpenShell ponownie wykorzystuje ten sam podstawowy transport SSH i most zdalnego systemu plików co ogólny backend SSH. Dodaje cykl życia specyficzny dla OpenShell (sandbox create/get/delete, sandbox ssh-config) oraz opcjonalny tryb przestrzeni roboczej mirror.

Wymagania wstępne

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

Szybki start

Zainstaluj i włącz plugin, a następnie ustaw backend piaskownicy:

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 ruchu agenta OpenClaw tworzy piaskownicę OpenShell i kieruje przez nią wykonywanie narzędzi.
Zweryfikuj:

openclaw sandbox list
openclaw sandbox explain

Tryby przestrzeni roboczej

To najważniejsza decyzja przy używaniu OpenShell.

`mirror`

Użyj plugins.entries.openshell.config.mode: "mirror", gdy chcesz, aby lokalna przestrzeń robocza pozostała kanoniczna. Zachowanie:

Przed exec OpenClaw synchronizuje lokalną przestrzeń roboczą do piaskownicy OpenShell.
Po exec OpenClaw synchronizuje zdalną przestrzeń roboczą z powrotem do lokalnej.
Narzędzia plikowe nadal działają przez most piaskownicy, ale lokalna przestrzeń robocza pozostaje źródłem prawdy między turami.

Najlepsze do:

Edytujesz pliki lokalnie poza OpenClaw i chcesz, aby te zmiany były automatycznie widoczne w piaskownicy.
Chcesz, aby piaskownica OpenShell zachowywała się możliwie najbardziej podobnie do backendu Docker.
Chcesz, aby przestrzeń robocza hosta odzwierciedlała zapisy w piaskownicy po każdej turze exec.

Kompromis: dodatkowy koszt synchronizacji przed każdym exec i po nim.

`remote`

Użyj plugins.entries.openshell.config.mode: "remote", gdy chcesz, aby przestrzeń robocza OpenShell stała się kanoniczna. Zachowanie:

Gdy piaskownica jest tworzona po raz pierwszy, OpenClaw jednorazowo zasila zdalną przestrzeń roboczą z lokalnej przestrzeni roboczej.
Następnie exec, read, write, edit i apply_patch działają bezpośrednio na zdalnej przestrzeni roboczej OpenShell.
OpenClaw nie synchronizuje zdalnych zmian z powrotem do lokalnej przestrzeni roboczej.
Odczyty multimediów w czasie promptu nadal działają, ponieważ narzędzia plikowe i multimedialne czytają przez most piaskownicy.

Najlepsze do:

Piaskownica powinna działać głównie po stronie zdalnej.
Chcesz niższego narzutu synchronizacji na turę.
Nie chcesz, aby lokalne edycje na hoście po cichu nadpisywały stan zdalnej piaskownicy.

Jeśli po początkowym zasileniu edytujesz pliki na hoście poza OpenClaw, zdalna piaskownica nie zobaczy tych zmian. Użyj openclaw sandbox recreate, aby ponownie zasilić.

Wybór trybu

	`mirror`	`remote`
Kanoniczna przestrzeń robocza	Lokalny host	Zdalny OpenShell
Kierunek synchronizacji	Dwukierunkowy (każdy exec)	Jednorazowe zasilenie
Narzut na turę	Wyższy (wysyłanie + pobieranie)	Niższy (bezpośrednie operacje zdalne)
Czy lokalne edycje są widoczne?	Tak, przy następnym exec	Nie, dopóki nie odtworzysz
Najlepsze do	Przepływy pracy developerskiej	Długo działający agenci, CI

Dokumentacja konfiguracji

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

Klucz	Typ	Domyślne	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 tworzeniu
`gateway`	`string`	—	Nazwa Gateway OpenShell (`--gateway`)
`gatewayEndpoint`	`string`	—	URL punktu końcowego Gateway OpenShell (`--gateway-endpoint`)
`policy`	`string`	—	ID polityki OpenShell do tworzenia piaskownicy
`providers`	`string[]`	`[]`	Nazwy dostawców do dołączenia podczas tworzenia piaskownicy
`gpu`	`boolean`	`false`	Żądaj zasobów GPU
`autoProviders`	`boolean`	`true`	Przekaż `--auto-providers` podczas tworzenia piaskownicy
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Główna zapisywalna przestrzeń robocza wewnątrz piaskownicy
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Ścieżka montowania przestrzeni roboczej agenta (do dostępu tylko do odczytu)
`timeoutSeconds`	`number`	`120`	Limit czasu dla operacji CLI `openshell`

Ustawienia na poziomie piaskownicy (mode, scope, workspaceAccess) konfiguruje się pod agents.defaults.sandbox, tak jak w przypadku każdego backendu. Zobacz Piaskownice, aby poznać pełną macierz.

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 na agenta 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

Piaskownice OpenShell są zarządzane przez standardowe CLI piaskownicy:

# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
openclaw sandbox recreate --all

W trybie remote odtworzenie jest szczególnie ważne: usuwa kanoniczną zdalną przestrzeń roboczą dla danego zakresu. Następne użycie zasila świeżą zdalną przestrzeń roboczą z lokalnej przestrzeni roboczej. W trybie mirror odtworzenie głównie resetuje zdalne środowisko wykonywania, ponieważ lokalna przestrzeń robocza pozostaje kanoniczna.

Kiedy odtwarzać

Odtwórz po zmianie dowolnego z poniższych:

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

openclaw sandbox recreate --all

Wzmocnienie zabezpieczeń

OpenShell przypina fd katalogu głównego przestrzeni roboczej i ponownie sprawdza tożsamość piaskownicy przed każdym odczytem, dzięki czemu podmiany dowiązań symbolicznych ani ponownie zamontowana przestrzeń robocza nie mogą przekierować odczytów poza zamierzoną zdalną przestrzeń roboczą.

Obecne ograniczenia

Przeglądarka piaskownicy nie jest obsługiwana w backendzie OpenShell.
sandbox.docker.binds nie ma zastosowania do OpenShell.
Pokrętła środowiska uruchomieniowego specyficzne dla Docker pod sandbox.docker.* mają zastosowanie tylko do backendu Docker.

Jak to działa

OpenClaw wywołuje openshell sandbox create (z flagami --from, --gateway, --policy, --providers, --gpu zgodnie z konfiguracją).
OpenClaw wywołuje openshell sandbox ssh-config <name>, aby uzyskać szczegóły połączenia SSH dla piaskownicy.
Core zapisuje konfigurację SSH do pliku tymczasowego i otwiera sesję SSH przy użyciu tego samego mostu zdalnego systemu plików co ogólny backend SSH.
W trybie mirror: synchronizacja lokalnie do zdalnie przed exec, uruchomienie, synchronizacja z powrotem po exec.
W trybie remote: jednorazowe zasilenie przy tworzeniu, a następnie bezpośrednie działanie na zdalnej przestrzeni roboczej.

Powiązane

Piaskownice — tryby, zakresy i porównanie backendów
Piaskownica vs polityka narzędzi vs podniesione uprawnienia — debugowanie zablokowanych narzędzi
Piaskownica i narzędzia wielu agentów — nadpisania na agenta
CLI piaskownicy — polecenia openclaw sandbox

​Wymagania wstępne

​Szybki start

​Tryby przestrzeni roboczej

​mirror

​remote

​Wybór trybu

​Dokumentacja konfiguracji

​Przykłady

​Minimalna konfiguracja zdalna

​Tryb mirror z GPU

​OpenShell na agenta z niestandardowym Gateway

​Zarządzanie cyklem życia

​Kiedy odtwarzać

​Wzmocnienie zabezpieczeń

​Obecne ograniczenia

​Jak to działa

​Powiązane

Wymagania wstępne

Szybki start

Tryby przestrzeni roboczej

`mirror`

`remote`

Wybór trybu

Dokumentacja konfiguracji

Przykłady

Minimalna konfiguracja zdalna

Tryb mirror z GPU

OpenShell na agenta z niestandardowym Gateway

Zarządzanie cyklem życia

Kiedy odtwarzać

Wzmocnienie zabezpieczeń

Obecne ograniczenia

Jak to działa

Powiązane