OpenShell

OpenShell ist ein verwaltetes Sandbox-Backend für OpenClaw. Statt Docker- Container lokal auszuführen, delegiert OpenClaw den Sandbox-Lebenszyklus an die openshell CLI, die Remote-Umgebungen mit SSH-basierter Befehlsausführung bereitstellt.

Das OpenShell-Plugin verwendet denselben zentralen SSH-Transport und dieselbe Remote-Dateisystem- Bridge wie das generische SSH-Backend. Es ergänzt OpenShell-spezifischen Lebenszyklus (sandbox create/get/delete, sandbox ssh-config) und einen optionalen Arbeitsbereichsmodus mirror.

Voraussetzungen

• OpenShell-Plugin installiert (openclaw plugins install @openclaw/openshell-sandbox)
• Die openshell CLI ist installiert und auf PATH verfügbar (oder legen Sie einen benutzerdefinierten Pfad über plugins.entries.openshell.config.command fest)
• Ein OpenShell-Konto mit Sandbox-Zugriff
• OpenClaw Gateway läuft auf dem Host

Schnellstart

1. Installieren und aktivieren Sie das Plugin, legen Sie dann das Sandbox-Backend fest:

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

2. Starten Sie den Gateway neu. Beim nächsten Agent-Turn erstellt OpenClaw eine OpenShell- Sandbox und leitet die Tool-Ausführung darüber.

3. Prüfen Sie:

openclaw sandbox listopenclaw sandbox explain

Arbeitsbereichsmodi

Dies ist die wichtigste Entscheidung bei der Verwendung von OpenShell.

mirror

Verwenden Sie plugins.entries.openshell.config.mode: "mirror", wenn der lokale Arbeitsbereich kanonisch bleiben soll.

Verhalten:

• Vor exec synchronisiert OpenClaw den lokalen Arbeitsbereich in die OpenShell-Sandbox.
• Nach exec synchronisiert OpenClaw den Remote-Arbeitsbereich zurück in den lokalen Arbeitsbereich.
• Datei-Tools arbeiten weiterhin über die Sandbox-Bridge, aber der lokale Arbeitsbereich bleibt zwischen Turns die Quelle der Wahrheit.

Am besten geeignet für:

• Sie bearbeiten Dateien lokal außerhalb von OpenClaw und möchten, dass diese Änderungen automatisch in der Sandbox sichtbar sind.
• Die OpenShell-Sandbox soll sich möglichst ähnlich wie das Docker-Backend verhalten.
• Der Host-Arbeitsbereich soll Sandbox-Schreibvorgänge nach jedem Exec-Turn widerspiegeln.

Kompromiss: zusätzliche Synchronisierungskosten vor und nach jedem Exec.

remote

Verwenden Sie plugins.entries.openshell.config.mode: "remote", wenn der OpenShell-Arbeitsbereich kanonisch werden soll.

Verhalten:

• Wenn die Sandbox erstmals erstellt wird, befüllt OpenClaw den Remote-Arbeitsbereich einmal aus dem lokalen Arbeitsbereich.
• Danach arbeiten exec, read, write, edit und apply_patch direkt gegen den Remote-OpenShell-Arbeitsbereich.
• OpenClaw synchronisiert Remote-Änderungen nicht zurück in den lokalen Arbeitsbereich.
• Medien-Lesevorgänge zur Prompt-Zeit funktionieren weiterhin, da Datei- und Medien-Tools über die Sandbox-Bridge lesen.

Am besten geeignet für:

• Die Sandbox soll primär auf der Remote-Seite leben.
• Sie möchten geringeren Synchronisierungsaufwand pro Turn.
• Sie möchten nicht, dass hostlokale Bearbeitungen den Remote-Sandbox-Zustand stillschweigend überschreiben.

Einen Modus wählen

Konfigurationsreferenz

Die gesamte OpenShell-Konfiguration liegt unter plugins.entries.openshell.config:

Sandbox-Einstellungen (mode, scope, workspaceAccess) werden unter agents.defaults.sandbox wie bei jedem Backend konfiguriert. Siehe Sandboxing für die vollständige Matrix.

Beispiele

Minimale Remote-Einrichtung

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

Mirror-Modus mit 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 pro Agent mit benutzerdefiniertem 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",        },      },    },  },}

Lebenszyklusverwaltung

OpenShell-Sandboxes werden über die normale Sandbox-CLI verwaltet:

# Alle Sandbox-Runtimes auflisten (Docker + OpenShell)openclaw sandbox list # Effektive Richtlinie prüfenopenclaw sandbox explain # Neu erstellen (löscht Remote-Arbeitsbereich, befüllt bei der nächsten Verwendung erneut)openclaw sandbox recreate --all

Für den Modus remote ist recreate besonders wichtig: Es löscht den kanonischen Remote-Arbeitsbereich für diesen Scope. Die nächste Verwendung befüllt einen frischen Remote-Arbeitsbereich aus dem lokalen Arbeitsbereich.

Für den Modus mirror setzt recreate hauptsächlich die Remote-Ausführungsumgebung zurück, weil der lokale Arbeitsbereich kanonisch bleibt.

Wann neu erstellen

Erstellen Sie neu, nachdem Sie eines der folgenden Elemente geändert haben:

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

openclaw sandbox recreate --all

Sicherheitshärtung

OpenShell fixiert den fd des Arbeitsbereichs-Roots und prüft die Sandbox-Identität vor jedem Lesevorgang erneut, sodass Symlink-Austausche oder ein erneut gemounteter Arbeitsbereich Lesevorgänge nicht aus dem beabsichtigten Remote-Arbeitsbereich heraus umleiten können.

Aktuelle Einschränkungen

• Der Sandbox-Browser wird auf dem OpenShell-Backend nicht unterstützt.
• sandbox.docker.binds gilt nicht für OpenShell.
• Docker-spezifische Runtime-Optionen unter sandbox.docker.* gelten nur für das Docker- Backend.

Funktionsweise

1. OpenClaw ruft openshell sandbox create auf (mit --from, --gateway, --policy, --providers, --gpu Flags gemäß Konfiguration).
2. OpenClaw ruft openshell sandbox ssh-config <name> auf, um SSH-Verbindungsdetails für die Sandbox zu erhalten.
3. Core schreibt die SSH-Konfiguration in eine temporäre Datei und öffnet eine SSH-Sitzung mit derselben Remote-Dateisystem-Bridge wie das generische SSH-Backend.
4. Im Modus mirror: lokal vor exec nach remote synchronisieren, ausführen, nach exec zurücksynchronisieren.
5. Im Modus remote: einmal beim Erstellen befüllen, dann direkt im Remote- Arbeitsbereich arbeiten.

Verwandt

• Sandboxing -- Modi, Scopes und Backend-Vergleich
• Sandbox vs Tool Policy vs Elevated -- Debugging blockierter Tools
• Multi-Agent Sandbox and Tools -- Overrides pro Agent
• Sandbox CLI -- openclaw sandbox Befehle