Sandboxing

OpenClaw kann Tools innerhalb von Sandbox-Backends ausführen, um den Blast Radius zu verringern. Dies ist optional und wird über die Konfiguration gesteuert (agents.defaults.sandbox oder agents.list[].sandbox). Wenn Sandboxing deaktiviert ist, werden Tools auf dem Host ausgeführt. Der Gateway bleibt auf dem Host; die Tool-Ausführung läuft bei Aktivierung in einer isolierten Sandbox.

Was in die Sandbox gelegt wird

• Tool-Ausführung (exec, read, write, edit, apply_patch, process usw.).
• Optionaler Browser in der Sandbox (agents.defaults.sandbox.browser).

Nicht in der Sandbox:

• Der Gateway-Prozess selbst.
• Jedes Tool, das explizit außerhalb der Sandbox ausgeführt werden darf (z. B. tools.elevated).
  • Elevated Exec umgeht Sandboxing und verwendet den konfigurierten Escape-Pfad (standardmäßig gateway, oder node, wenn das Exec-Ziel node ist).
  • Wenn Sandboxing deaktiviert ist, ändert tools.elevated die Ausführung nicht (bereits auf dem Host). Siehe Elevated Mode.

Modi

agents.defaults.sandbox.mode steuert, wann Sandboxing verwendet wird:

Geltungsbereich

agents.defaults.sandbox.scope steuert, wie viele Container erstellt werden:

• "agent" (Standard): ein Container pro Agent.
• "session": ein Container pro Sitzung.
• "shared": ein Container, der von allen Sandbox-Sitzungen gemeinsam genutzt wird.

Backend

agents.defaults.sandbox.backend steuert, welche Laufzeitumgebung die Sandbox bereitstellt:

• "docker" (Standard, wenn Sandboxing aktiviert ist): lokale Docker-gestützte Sandbox-Laufzeitumgebung.
• "ssh": generische SSH-gestützte Remote-Sandbox-Laufzeitumgebung.
• "openshell": OpenShell-gestützte Sandbox-Laufzeitumgebung.

SSH-spezifische Konfiguration befindet sich unter agents.defaults.sandbox.ssh. OpenShell-spezifische Konfiguration befindet sich unter plugins.entries.openshell.config.

Backend auswählen

Docker-Backend

Sandboxing ist standardmäßig deaktiviert. Wenn Sie Sandboxing aktivieren und kein Backend auswählen, verwendet OpenClaw das Docker-Backend. Es führt Tools und Sandbox-Browser lokal über den Docker-Daemon-Socket (/var/run/docker.sock) aus. Die Isolation von Sandbox-Containern wird durch Docker-Namespaces bestimmt.

Um Host-GPUs für Docker-Sandboxes verfügbar zu machen, setzen Sie agents.defaults.sandbox.docker.gpus oder die agentspezifische Überschreibung agents.list[].sandbox.docker.gpus. Der Wert wird als separates Argument an Dockers --gpus-Flag übergeben, zum Beispiel "all" oder "device=GPU-uuid", und erfordert eine kompatible Host-Laufzeitumgebung wie NVIDIA Container Toolkit.

SSH-Backend

Verwenden Sie backend: "ssh", wenn OpenClaw exec, Datei-Tools und Medienlesevorgänge auf einer beliebigen per SSH erreichbaren Maschine in eine Sandbox legen soll.

{  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",          // Or use SecretRefs / inline contents instead of local files:          // 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" },        },      },    },  },}

OpenShell-Backend

Verwenden Sie backend: "openshell", wenn OpenClaw Tools in einer von OpenShell verwalteten Remote-Umgebung in eine Sandbox legen soll. Die vollständige Einrichtungsanleitung, Konfigurationsreferenz und den Vergleich der Workspace-Modi finden Sie auf der dedizierten OpenShell-Seite.

OpenShell verwendet denselben zentralen SSH-Transport und dieselbe Remote-Dateisystem-Bridge wie das generische SSH-Backend wieder und ergänzt OpenShell-spezifischen Lifecycle (sandbox create/get/delete, sandbox ssh-config) sowie den optionalen Workspace-Modus mirror.

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

OpenShell-Modi:

• mirror (Standard): Der lokale Workspace bleibt kanonisch. OpenClaw synchronisiert lokale Dateien vor Exec in OpenShell und synchronisiert den Remote-Workspace nach Exec zurück.
• remote: Der OpenShell-Workspace ist kanonisch, nachdem die Sandbox erstellt wurde. OpenClaw seedet den Remote-Workspace einmal aus dem lokalen Workspace, danach werden Datei-Tools und Exec direkt gegen die Remote-Sandbox ausgeführt, ohne Änderungen zurückzusynchronisieren.

Workspace-Modi

OpenShell hat zwei Workspace-Modelle. Das ist in der Praxis der wichtigste Teil.

Wählen Sie mirror, wenn Sie die Sandbox als temporäre Ausführungsumgebung betrachten. Wählen Sie remote, wenn Sie die Sandbox als den eigentlichen Workspace betrachten.

OpenShell-Lebenszyklus

OpenShell-Sandboxes werden weiterhin über den normalen Sandbox-Lebenszyklus verwaltet:

• openclaw sandbox list zeigt OpenShell-Runtimes ebenso wie Docker-Runtimes
• openclaw sandbox recreate löscht die aktuelle Runtime und lässt OpenClaw sie bei der nächsten Verwendung neu erstellen
• Die Bereinigungslogik ist ebenfalls backend-bewusst

Für den Modus remote ist recreate besonders wichtig:

• recreate löscht den kanonischen Remote-Workspace für diesen Scope
• die nächste Verwendung befüllt einen frischen Remote-Workspace aus dem lokalen Workspace

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

Workspace-Zugriff

agents.defaults.sandbox.workspaceAccess steuert, was die Sandbox sehen kann:

Mit dem OpenShell-Backend:

• Der Modus mirror verwendet zwischen Exec-Turns weiterhin den lokalen Workspace als kanonische Quelle
• Der Modus remote verwendet nach dem initialen Seed den Remote-OpenShell-Workspace als kanonische Quelle
• workspaceAccess: "ro" und "none" schränken das Schreibverhalten weiterhin auf dieselbe Weise ein

Eingehende Medien werden in den aktiven Sandbox-Workspace kopiert (media/inbound/*).

Benutzerdefinierte Bind-Mounts

agents.defaults.sandbox.docker.binds mountet zusätzliche Host-Verzeichnisse in den Container. Format: host:container:mode (z. B. "/home/user/source:/source:rw").

Globale und agent-spezifische Binds werden zusammengeführt (nicht ersetzt). Unter scope: "shared" werden agent-spezifische Binds ignoriert.

agents.defaults.sandbox.browser.binds mountet zusätzliche Host-Verzeichnisse nur in den Sandbox-Browser-Container.

• Wenn gesetzt (einschließlich []), ersetzt es agents.defaults.sandbox.docker.binds für den Browser-Container.
• Wenn weggelassen, fällt der Browser-Container auf agents.defaults.sandbox.docker.binds zurück (abwärtskompatibel).

Beispiel (schreibgeschützte Quelle + ein zusätzliches Datenverzeichnis):

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

Images und Einrichtung

Standard-Docker-Image: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Standardmäßig laufen Docker-Sandbox-Container mit keinem Netzwerk. Überschreiben Sie dies mit agents.defaults.sandbox.docker.network.

Docker-Installationen und der containerisierte Gateway befinden sich hier: Docker

Für Docker-Gateway-Bereitstellungen kann scripts/docker/setup.sh die Sandbox-Konfiguration bootstrappen. Setzen Sie OPENCLAW_SANDBOX=1 (oder true/yes/on), um diesen Pfad zu aktivieren. Sie können den Socket-Speicherort mit OPENCLAW_DOCKER_SOCKET überschreiben. Vollständige Setup- und Umgebungsreferenz: Docker.

setupCommand (einmalige Container-Einrichtung)

setupCommand wird einmal ausgeführt, nachdem der Sandbox-Container erstellt wurde (nicht bei jedem Lauf). Es wird innerhalb des Containers über sh -lc ausgeführt.

Pfade:

• Global: agents.defaults.sandbox.docker.setupCommand
• Pro Agent: agents.list[].sandbox.docker.setupCommand

Tool-Richtlinie und Notfallausnahmen

Tool-Zulassen-/Verweigern-Richtlinien gelten weiterhin vor Sandbox-Regeln. Wenn ein Tool global oder pro Agent verweigert wird, bringt Sandboxing es nicht zurück.

tools.elevated ist eine explizite Notfallausnahme, die exec außerhalb der Sandbox ausführt (standardmäßig gateway oder node, wenn das Exec-Ziel node ist). /exec-Direktiven gelten nur für autorisierte Absender und bleiben pro Sitzung bestehen; um exec hart zu deaktivieren, verwenden Sie die Tool-Richtlinie zum Verweigern (siehe Sandbox vs Tool Policy vs Elevated).

Debugging:

• Verwenden Sie openclaw sandbox explain, um den effektiven Sandbox-Modus, die Tool-Richtlinie und Fix-it-Konfigurationsschlüssel zu prüfen.
• Siehe Sandbox vs Tool Policy vs Elevated für das mentale Modell zu „Warum ist das blockiert?“.

Halten Sie die Umgebung abgesichert.

Multi-Agent-Overrides

Jeder Agent kann Sandbox und Tools überschreiben: agents.list[].sandbox und agents.list[].tools (plus agents.list[].tools.sandbox.tools für die Sandbox-Tool-Richtlinie). Siehe Multi-Agent Sandbox & Tools für die Rangfolge.

Minimales Aktivierungsbeispiel

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

Verwandte Themen

• Multi-Agent Sandbox & Tools — Overrides pro Agent und Rangfolge
• OpenShell — Einrichtung des verwalteten Sandbox-Backends, Workspace-Modi und Konfigurationsreferenz
• Sandbox-Konfiguration
• Sandbox vs Tool Policy vs Elevated — Debugging für „Warum ist das blockiert?“
• Sicherheit