Gateway

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-spezifische Lebenszyklusfunktionen (sandbox create/get/delete, sandbox ssh-config) und einen optionalen mirror-Workspace-Modus.

Voraussetzungen

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

Schnellstart

Aktivieren Sie das Plugin und legen Sie das Sandbox-Backend fest:

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

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

openclaw sandbox list
openclaw sandbox explain

Workspace-Modi

Dies ist die wichtigste Entscheidung bei der Verwendung von OpenShell.

`mirror`

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

Verhalten:

Vor exec synchronisiert OpenClaw den lokalen Workspace in die OpenShell-Sandbox.
Nach exec synchronisiert OpenClaw den Remote-Workspace zurück in den lokalen Workspace.
Datei-Tools arbeiten weiterhin über die Sandbox-Bridge, aber der lokale Workspace 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 werden.
Sie möchten, dass sich die OpenShell-Sandbox so weit wie möglich wie das Docker-Backend verhält.
Sie möchten, dass der Host-Workspace nach jedem Exec-Turn Schreibvorgänge aus der Sandbox widerspiegelt.

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

`remote`

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

Verhalten:

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

Am besten geeignet für:

Die Sandbox soll hauptsächlich auf der Remote-Seite leben.
Sie möchten einen geringeren Synchronisierungsaufwand pro Turn.
Sie möchten nicht, dass host-lokale Bearbeitungen den Remote-Sandbox-Zustand stillschweigend überschreiben.

Einen Modus auswählen

	`mirror`	`remote`
Kanonischer Workspace	Lokaler Host	Remote-OpenShell
Synchronisierungsrichtung	Bidirektional (jedes Exec)	Einmalige Befüllung
Aufwand pro Turn	Höher (Upload + Download)	Geringer (direkte Remote-Operationen)
Lokale Änderungen sichtbar?	Ja, beim nächsten Exec	Nein, erst nach recreate
Am besten geeignet für	Entwicklungsworkflows	Lang laufende Agents, CI

Konfigurationsreferenz

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

Schlüssel	Typ	Standard	Beschreibung
`mode`	`"mirror"` oder `"remote"`	`"mirror"`	Workspace-Synchronisierungsmodus
`command`	`string`	`"openshell"`	Pfad oder Name der `openshell`-CLI
`from`	`string`	`"openclaw"`	Sandbox-Quelle für die erstmalige Erstellung
`gateway`	`string`	—	OpenShell-Gateway-Name (`--gateway`)
`gatewayEndpoint`	`string`	—	OpenShell-Gateway-Endpunkt-URL (`--gateway-endpoint`)
`policy`	`string`	—	OpenShell-Policy-ID für die Sandbox-Erstellung
`providers`	`string[]`	`[]`	Provider-Namen, die beim Erstellen der Sandbox angehängt werden
`gpu`	`boolean`	`false`	GPU-Ressourcen anfordern
`autoProviders`	`boolean`	`true`	`--auto-providers` bei der Sandbox-Erstellung übergeben
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Primärer beschreibbarer Workspace innerhalb der Sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Mount-Pfad des Agent-Workspaces (für schreibgeschützten Zugriff)
`timeoutSeconds`	`number`	`120`	Timeout für `openshell`-CLI-Operationen

Sandbox-Einstellungen (mode, scope, workspaceAccess) werden wie bei jedem Backend unter agents.defaults.sandbox konfiguriert. Die vollständige Matrix finden Sie unter Sandboxing.

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:

# 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

Für den remote-Modus ist recreate besonders wichtig: Es löscht den kanonischen Remote-Workspace für diesen Scope. Bei der nächsten Verwendung wird ein frischer Remote-Workspace aus dem lokalen Workspace befüllt.

Für den mirror-Modus setzt recreate vor allem die Remote-Ausführungsumgebung zurück, weil der lokale Workspace kanonisch bleibt.

Wann recreate verwendet werden sollte

Verwenden Sie recreate nach Änderungen an einem der folgenden Werte:

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 Root-fd des Workspaces und prüft vor jedem Lesevorgang die Sandbox-Identität erneut, sodass Symlink-Austausche oder ein neu eingehängter Workspace Lesevorgänge nicht aus dem vorgesehenen Remote-Workspace heraus umleiten können.

Aktuelle Einschränkungen

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

Funktionsweise

OpenClaw ruft openshell sandbox create auf (mit den Flags --from, --gateway, --policy, --providers, --gpu wie konfiguriert).
OpenClaw ruft openshell sandbox ssh-config <name> auf, um SSH-Verbindungsdetails für die Sandbox abzurufen.
Der Core schreibt die SSH-Konfiguration in eine temporäre Datei und öffnet eine SSH-Sitzung über dieselbe Remote-Dateisystem-Bridge wie das generische SSH-Backend.
Im mirror-Modus: lokal vor exec nach remote synchronisieren, ausführen, nach exec zurück synchronisieren.
Im remote-Modus: einmalig beim Erstellen befüllen, danach direkt auf dem Remote- Workspace arbeiten.

OpenShell

Voraussetzungen

Schnellstart

Workspace-Modi

`mirror`

`remote`

Einen Modus auswählen

Konfigurationsreferenz

Beispiele

Minimale Remote-Einrichtung

Mirror-Modus mit GPU

OpenShell pro Agent mit benutzerdefiniertem Gateway

Lebenszyklusverwaltung

Wann recreate verwendet werden sollte

Sicherheitshärtung

Aktuelle Einschränkungen

Funktionsweise

Verwandte Themen

Ask OpenClaw

# Voraussetzungen

# Schnellstart

# Workspace-Modi

# mirror

# remote

# Einen Modus auswählen

# Konfigurationsreferenz

# Beispiele

# Minimale Remote-Einrichtung

# Mirror-Modus mit GPU

# OpenShell pro Agent mit benutzerdefiniertem Gateway

# Lebenszyklusverwaltung

# Wann recreate verwendet werden sollte

# Sicherheitshärtung

# Aktuelle Einschränkungen

# Funktionsweise

# Verwandte Themen

Voraussetzungen

Schnellstart

Workspace-Modi

`mirror`

`remote`

Einen Modus auswählen

Konfigurationsreferenz

Beispiele

Minimale Remote-Einrichtung

Mirror-Modus mit GPU

OpenShell pro Agent mit benutzerdefiniertem Gateway

Lebenszyklusverwaltung

Wann recreate verwendet werden sollte

Sicherheitshärtung

Aktuelle Einschränkungen

Funktionsweise

Verwandte Themen