Sandbox-Isolierung

OpenClaw kann Tools innerhalb von Sandbox-Backends ausführen, um den Schadensradius zu verringern. Dies ist optional und wird über die Konfiguration gesteuert (agents.defaults.sandbox oder agents.list[].sandbox). Wenn Sandboxing ausgeschaltet 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 der Sandbox ausgeführt wird

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

Nicht in der Sandbox:

• Der Gateway-Prozess selbst.
• Jedes Tool, dem ausdrücklich erlaubt wurde, außerhalb der Sandbox zu laufen (z. B. tools.elevated).
  • Elevated Exec umgeht Sandboxing und verwendet den konfigurierten Escape-Pfad (gateway standardmäßig oder node, wenn das Exec-Ziel node ist).
  • Wenn Sandboxing ausgeschaltet 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 sandboxed Sitzungen gemeinsam genutzt wird.

Backend

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

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

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

Ein Backend auswählen

Docker-Backend

Sandboxing ist standardmäßig ausgeschaltet. Wenn Sie Sandboxing aktivieren und kein Backend auswählen, verwendet OpenClaw das Docker-Backend. Es führt Tools und sandboxed 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 das agentenspezifische Override 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-Runtime 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 einer Sandbox ausführen 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 einer Sandbox ausführen soll. Die vollständige Einrichtungsanleitung, die 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 und ergänzt OpenShell-spezifischen Lebenszyklus (sandbox create/get/delete, sandbox ssh-config) sowie den optionalen mirror-Workspace-Modus.

{  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 initialisiert den Remote-Workspace einmal aus dem lokalen Workspace; danach laufen Datei-Tools und exec direkt gegen die Remote-Sandbox, ohne Änderungen zurückzusynchronisieren.

Workspace-Modi

OpenShell hat zwei Workspace-Modelle. Dies ist der Teil, der in der Praxis am wichtigsten ist.

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 Arbeitsbereich betrachten.

OpenShell-Lebenszyklus

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

• openclaw sandbox list zeigt sowohl OpenShell-Runtimes als auch Docker-Runtimes
• openclaw sandbox recreate löscht die aktuelle Runtime und lässt OpenClaw sie bei der nächsten Verwendung neu erstellen
• die Prune-Logik ist ebenfalls backend-bewusst

Für den Modus remote ist das Neuerstellen besonders wichtig:

• Neuerstellen löscht den kanonischen entfernten Arbeitsbereich für diesen Scope
• die nächste Verwendung initialisiert einen frischen entfernten Arbeitsbereich aus dem lokalen Arbeitsbereich

Für den Modus mirror setzt das Neuerstellen hauptsächlich die entfernte Ausführungsumgebung zurück, weil der lokale Arbeitsbereich ohnehin kanonisch bleibt.

Arbeitsbereichszugriff

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

Mit dem OpenShell-Backend:

• Der Modus mirror verwendet weiterhin den lokalen Arbeitsbereich als kanonische Quelle zwischen exec-Turns
• Der Modus remote verwendet den entfernten OpenShell-Arbeitsbereich nach der anfänglichen Initialisierung als kanonische Quelle
• workspaceAccess: "ro" und "none" schränken Schreibverhalten weiterhin auf dieselbe Weise ein

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

Benutzerdefinierte Bind-Mounts

agents.defaults.sandbox.docker.binds bindet zusätzliche Host-Verzeichnisse in den Container ein. 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 bindet zusätzliche Host-Verzeichnisse nur in den Sandbox-Browser-Container ein.

• 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 das containerisierte Gateway befinden sich hier: Docker

Für Docker-Gateway-Bereitstellungen kann scripts/docker/setup.sh die Sandbox-Konfiguration bootstrapen. 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 Einrichtung und env-Referenz: Docker.

setupCommand (einmalige Container-Einrichtung)

setupCommand läuft einmal, nachdem der Sandbox-Container erstellt wurde (nicht bei jedem Lauf). Es wird im Container über sh -lc ausgeführt.

Pfade:

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

Tool-Richtlinie und Notfallwege

Tool-Zulassungs-/Sperrrichtlinien gelten weiterhin vor Sandbox-Regeln. Wenn ein Tool global oder pro Agent gesperrt ist, bringt Sandboxing es nicht zurück.

tools.elevated ist ein expliziter Notfallweg, der 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 eine Tool-Richtliniensperre (siehe Sandbox vs Tool Policy vs Elevated).

Debugging:

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

Halten Sie es abgesichert.

Multi-Agent-Overrides

Jeder Agent kann Sandbox + 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 zur Rangfolge.

Minimales Aktivierungsbeispiel

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

Verwandt

• 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 zu „Warum ist das blockiert?“
• Sicherheit