Sandboxing

OpenClaw kann die Werkzeugausführung innerhalb eines Sandbox-Backends ausführen, um den möglichen Schadensradius zu verringern. Sandboxing ist standardmäßig deaktiviert und wird über agents.defaults.sandbox (global) oder agents.list[].sandbox (pro Agent) gesteuert. Der Gateway-Prozess verbleibt immer auf dem Host; bei aktiviertem Sandboxing wird nur die Werkzeugausführung in die Sandbox verlagert.

Was in der Sandbox ausgeführt wird

• Werkzeugausführung: exec, read, write, edit, apply_patch, process usw.
• Der optionale Sandbox-Browser (agents.defaults.sandbox.browser).

Nicht in der Sandbox ausgeführt:

• Der Gateway-Prozess selbst.
• Jedes Werkzeug, dessen Ausführung außerhalb der Sandbox ausdrücklich über tools.elevated erlaubt ist. Die erhöhte Ausführung umgeht das Sandboxing und erfolgt über den konfigurierten Escape-Pfad (standardmäßig gateway oder node, wenn das Ausführungsziel node ist). Wenn Sandboxing deaktiviert ist, ändert tools.elevated nichts, da die Ausführung ohnehin bereits auf dem Host erfolgt. Siehe Erhöhter Modus.

Modi, Geltungsbereich und Backend

Drei unabhängige Einstellungen steuern das Sandbox-Verhalten:

Der Modus steuert, wann Sandboxing angewendet wird:

• off: kein Sandboxing.
• non-main: Alle Sitzungen außer der Hauptsitzung des Agenten werden in einer Sandbox ausgeführt. Der Schlüssel der Hauptsitzung ist immer agent:<agentId>:main (oder global, wenn session.scope auf "global" gesetzt ist); er kann nicht konfiguriert werden. Gruppen-/Kanalsitzungen verwenden eigene Schlüssel, gelten daher immer als Nicht-Hauptsitzungen und werden in einer Sandbox ausgeführt.
• all: Jede Sitzung wird in einer Sandbox ausgeführt.

Der Geltungsbereich steuert, wie viele Container/Umgebungen erstellt werden:

• agent: ein Container pro Agent.
• session: ein Container pro Sitzung.
• shared: ein gemeinsam von allen Sandbox-Sitzungen verwendeter Container (agentenspezifische Überschreibungen für docker/ssh/browser werden in diesem Geltungsbereich ignoriert).

Das Backend steuert, welche Laufzeit Sandbox-Werkzeuge ausführt. SSH-spezifische Konfiguration befindet sich unter agents.defaults.sandbox.ssh; OpenShell-spezifische Konfiguration befindet sich unter plugins.entries.openshell.config.

Docker-Backend

Docker ist das Standard-Backend, sobald Sandboxing aktiviert ist. Es führt Werkzeuge und Sandbox-Browser lokal über den Docker-Daemon-Socket (/var/run/docker.sock) aus; die Isolation erfolgt durch Docker-Namespaces.

Standardwerte: network: "none" (kein ausgehender Zugriff), readOnlyRoot: true, capDrop: ["ALL"], Image openclaw-sandbox:bookworm-slim.

Um Host-GPUs bereitzustellen, setzen Sie agents.defaults.sandbox.docker.gpus (oder die agentenspezifische Überschreibung) auf einen Wert wie "all" oder "device=GPU-uuid". Dieser Wert wird an Dockers Flag --gpus übergeben und erfordert eine kompatible Host-Laufzeit wie das NVIDIA Container Toolkit.

Sandbox-Browser

• Der Sandbox-Browser startet automatisch (und stellt sicher, dass CDP erreichbar ist), wenn das Browser-Werkzeug ihn benötigt. Die Konfiguration erfolgt über agents.defaults.sandbox.browser.autoStart (Standardwert true) und autoStartTimeoutMs (Standardwert 12s).
• Sandbox-Browser-Container verwenden anstelle des globalen bridge-Netzwerks ein dediziertes Docker-Netzwerk (openclaw-sandbox-browser). Konfigurieren Sie es mit agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange beschränkt eingehende CDP-Verbindungen am Containerrand mithilfe einer CIDR-Zulassungsliste (zum Beispiel 172.21.0.1/32).
• Der noVNC-Beobachterzugriff ist standardmäßig passwortgeschützt; OpenClaw gibt eine kurzlebige Token-URL aus, die eine lokale Bootstrap-Seite bereitstellt und noVNC mit dem Passwort im URL-Fragment öffnet (nicht in der Abfragezeichenfolge oder in Header-Protokollen).
• agents.defaults.sandbox.browser.allowHostControl (Standardwert false) ermöglicht Sandbox-Sitzungen, ausdrücklich den Host-Browser anzusteuern.
• Optionale Zulassungslisten beschränken target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

SSH-Backend

Verwenden Sie backend: "ssh", um exec, Dateiwerkzeuge und das Lesen von Medien auf einem beliebigen per SSH erreichbaren Rechner in einer Sandbox auszuführen.

{  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",          // Oder SecretRefs/Inline-Inhalte anstelle lokaler Dateien verwenden:          // 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" },        },      },    },  },}

Standardwerte: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Lebenszyklus: OpenClaw erstellt unter sandbox.ssh.workspaceRoot ein Remote-Stammverzeichnis pro Geltungsbereich. Bei der ersten Verwendung nach dem Erstellen oder Neuerstellen wird dieser Remote-Workspace einmalig aus dem lokalen Workspace initialisiert. Danach werden exec, read, write, edit, apply_patch, das Lesen von Prompt-Medien und die Bereitstellung eingehender Medien direkt über SSH im Remote-Workspace ausgeführt. OpenClaw synchronisiert Remote-Änderungen nicht automatisch zurück in den lokalen Workspace.
• Authentifizierungsmaterial: identityFile/certificateFile/knownHostsFile verweisen auf vorhandene lokale Dateien. identityData/certificateData/knownHostsData akzeptieren Inline-Zeichenfolgen oder SecretRefs, die über den normalen Laufzeit-Snapshot der Geheimnisse aufgelöst, mit dem Modus 0600 in temporäre Dateien geschrieben und beim Ende der SSH-Sitzung gelöscht werden. Wenn für dasselbe Element sowohl eine *File- als auch eine *Data-Variante festgelegt ist, hat *Data für diese Sitzung Vorrang.
• Folgen des Remote-kanonischen Modells: Der Remote-SSH-Workspace wird nach der anfänglichen Initialisierung zum tatsächlichen Sandbox-Zustand. Nach der Initialisierung außerhalb von OpenClaw vorgenommene lokale Host-Änderungen sind remote erst sichtbar, wenn Sie die Sandbox neu erstellen. openclaw sandbox recreate löscht das Remote-Stammverzeichnis des jeweiligen Geltungsbereichs und initialisiert es bei der nächsten Verwendung erneut aus dem lokalen Workspace. Browser-Sandboxing wird von diesem Backend nicht unterstützt, und Einstellungen unter sandbox.docker.* gelten dafür nicht.

OpenShell-Backend

Verwenden Sie backend: "openshell", um Werkzeuge in einer von OpenShell verwalteten Remote-Umgebung in einer Sandbox auszuführen. OpenShell verwendet denselben SSH-Transport und dieselbe Remote-Dateisystem-Bridge wie das generische SSH-Backend und ergänzt den OpenShell-Lebenszyklus (sandbox create/get/delete/ssh-config) sowie einen optionalen Workspace-Synchronisierungsmodus mirror.

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

mode: "mirror" (Standard) behält den lokalen Workspace als kanonische Quelle bei: OpenClaw synchronisiert den lokalen Workspace vor exec in die Sandbox und anschließend wieder zurück. mode: "remote" initialisiert den Remote-Workspace einmalig aus dem lokalen Workspace und führt anschließend exec/read/write/edit/apply_patch direkt im Remote-Workspace aus, ohne Änderungen zurückzusynchronisieren; lokale Änderungen nach der Initialisierung sind nicht sichtbar, bis Sie openclaw sandbox recreate ausführen. Unter scope: "agent" oder scope: "shared" wird dieser Remote-Workspace im jeweiligen Geltungsbereich gemeinsam genutzt. Aktuelle Einschränkungen: Der Sandbox-Browser wird noch nicht unterstützt, und sandbox.docker.binds gilt nicht für dieses Backend.

openclaw sandbox list/recreate/prune behandeln OpenShell-Laufzeiten genauso wie Docker-Laufzeiten; die Bereinigungslogik berücksichtigt das Backend.

Die vollständigen Voraussetzungen, die Konfigurationsreferenz, den Vergleich der Workspace-Modi und Einzelheiten zum Lebenszyklus finden Sie unter OpenShell.

Workspace-Zugriff

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

Mit dem OpenShell-Backend verwendet der Modus mirror zwischen exec-Durchläufen weiterhin den lokalen Arbeitsbereich als kanonische Quelle, der Modus remote verwendet nach der initialen Übertragung den entfernten OpenShell-Arbeitsbereich als kanonische Quelle, und workspaceAccess: "ro"/"none" schränkt das Schreibverhalten weiterhin auf dieselbe Weise ein.

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

Benutzerdefinierte Bind-Mounts

agents.defaults.sandbox.docker.binds bindet zusätzliche Hostverzeichnisse in den Container ein. Format: host:container:mode (z. B. "/home/user/source:/source:rw").

Globale und agentspezifische Bind-Mounts werden zusammengeführt (nicht ersetzt). Unter scope: "shared" werden agentspezifische Bind-Mounts ignoriert.

agents.defaults.sandbox.browser.binds bindet zusätzliche Hostverzeichnisse ausschließlich in den Sandbox-Browser-Container ein. Wenn die Option gesetzt ist (einschließlich []), ersetzt sie docker.binds für den Browser-Container; wenn sie fehlt, greift der Browser-Container auf docker.binds zurück.

{  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

Docker-Sandbox-Container werden standardmäßig ohne Netzwerk ausgeführt. Überschreiben Sie dies mit agents.defaults.sandbox.docker.network.

Docker-Installationen und das containerisierte Gateway finden Sie hier: Docker

Bei Docker-Gateway-Bereitstellungen kann scripts/docker/setup.sh die Sandbox-Konfiguration initialisieren. Setzen Sie OPENCLAW_SANDBOX=1 (oder true/yes/on), um diesen Pfad zu aktivieren. Überschreiben Sie den Socket-Speicherort mit OPENCLAW_DOCKER_SOCKET. Vollständige Einrichtung und Umgebungsvariablenreferenz: Docker.

setupCommand (einmalige Container-Einrichtung)

setupCommand wird einmal ausgeführt, nachdem der Sandbox-Container erstellt wurde (nicht bei jedem Durchlauf). Der Befehl 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 Ausweichmöglichkeiten

Tool-Zulassungs-/Ablehnungsrichtlinien gelten weiterhin vor den Sandbox-Regeln. Wenn ein Tool global oder pro Agent abgelehnt wird, macht die Sandbox es nicht wieder verfügbar.

tools.elevated ist eine explizite Ausweichmöglichkeit, die exec außerhalb der Sandbox ausführt (standardmäßig im gateway oder in node, wenn das exec-Ziel node ist). /exec-Direktiven gelten nur für autorisierte Absender und bleiben pro Sitzung bestehen; um exec vollständig zu deaktivieren, verwenden Sie eine Ablehnung in der Tool-Richtlinie (siehe Sandbox vs. Tool-Richtlinie vs. erhöhte Rechte).

Fehlersuche:

• openclaw sandbox list zeigt Sandbox-Container, Status, Image-Übereinstimmung, Alter, Leerlaufzeit und die zugehörige Sitzung/den zugehörigen Agenten.
• openclaw sandbox explain [--session <key>] [--agent <id>] untersucht den effektiven Sandbox-Modus, den Host-Arbeitsbereich, das Laufzeit-Arbeitsverzeichnis, Docker-Mounts, die Tool-Richtlinie und Konfigurationsschlüssel zur Problembehebung. Das Feld workspaceRoot bleibt das konfigurierte Sandbox-Stammverzeichnis; effectiveHostWorkspaceRoot zeigt, wo sich der aktive Arbeitsbereich tatsächlich befindet.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] entfernt Container/Umgebungen, damit sie bei der nächsten Verwendung mit der aktuellen Konfiguration neu erstellt werden.
• Unter Sandbox vs. Tool-Richtlinie vs. erhöhte Rechte finden Sie das Denkmodell für die Frage „Warum ist das blockiert?“.

Überschreibungen für mehrere Agenten

Jeder Agent kann Sandbox und Tools überschreiben: agents.list[].sandbox und agents.list[].tools (sowie agents.list[].tools.sandbox.tools für die Sandbox-Tool-Richtlinie). Informationen zur Rangfolge finden Sie unter Sandbox und Tools für mehrere Agenten.

Minimales Aktivierungsbeispiel

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

Verwandte Themen

• Multi-Agent-Sandbox und Tools -- agentenspezifische Überschreibungen und Rangfolge
• OpenShell -- Einrichtung des verwalteten Sandbox-Backends, Workspace-Modi und Konfigurationsreferenz
• Sandbox-Konfiguration
• Sandbox vs. Tool-Richtlinie vs. erhöhte Berechtigungen -- Fehlerbehebung bei der Frage „Warum wird dies blockiert?“
• Sicherheit