Sandboxing

OpenClaw kann die Werkzeugausführung in einem Sandbox-Backend ausführen, um den möglichen Schadensradius zu reduzieren. Sandboxing ist standardmäßig deaktiviert und wird durch agents.defaults.sandbox (global) oder agents.entries.*.sandbox (pro Agent) gesteuert. Der Gateway-Prozess verbleibt immer auf dem Host; nur die Werkzeugausführung wird bei Aktivierung in die Sandbox verlagert.

Was in der Sandbox ausgeführt wird

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

Nicht in der Sandbox ausgeführt:

• Der Gateway-Prozess selbst.
• Jedes Werkzeug, das über tools.elevated ausdrücklich für die Ausführung außerhalb der Sandbox zugelassen ist. Die Ausführung mit erhöhten Rechten umgeht das Sandboxing und erfolgt über den konfigurierten Ausweichpfad (standardmäßig gateway oder node, wenn das Ausführungsziel node ist). Wenn Sandboxing deaktiviert ist, ändert tools.elevated nichts, da die Ausführung bereits auf dem Host erfolgt. Siehe Modus mit erhöhten Rechten.

Modi, Geltungsbereich und Backend

Drei voneinander unabhängige Einstellungen steuern das Sandbox-Verhalten:

Der Modus steuert, wann Sandboxing angewendet wird:

• off: kein Sandboxing.
• non-main: Jede Sitzung mit Ausnahme der Hauptsitzung des Agenten wird in einer Sandbox ausgeführt. Der Schlüssel der Hauptsitzung ist immer agent:<agentId>:main (oder global, wenn session.scope den Wert "global" hat); er ist nicht konfigurierbar. 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 von allen Sandbox-Sitzungen gemeinsam genutzter Container (agentenspezifische Überschreibungen von docker/ssh/browser werden in diesem Geltungsbereich ignoriert).

Das Backend steuert, welche Laufzeitumgebung die 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 standardmäßige Backend, sobald Sandboxing aktiviert ist. Es führt Werkzeuge und Sandbox-Browser lokal über den Socket des Docker-Daemons (/var/run/docker.sock) aus; die Isolation erfolgt durch Docker-Namespaces.

Standardwerte: network: "none" (kein ausgehender Datenverkehr), 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 das Docker-Flag --gpus übergeben und erfordert eine kompatible Host-Laufzeitumgebung wie das NVIDIA Container Toolkit.

Browser in der Sandbox

• Der Sandbox-Browser wird automatisch gestartet (wodurch die Erreichbarkeit von CDP sichergestellt wird), 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 Netzwerks bridge ein dediziertes Docker-Netzwerk (openclaw-sandbox-browser). Die Konfiguration erfolgt über agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange beschränkt den CDP-Zugriff am Container-Rand mit 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 als Ziel zu verwenden.
• 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 verwenden Sie SecretRefs/Inline-Inhalte anstelle lokaler Dateien:          // 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 mit dem lokalen Workspace initialisiert. Danach werden exec, read, write, edit, apply_patch, das Lesen von Prompt-Medien und die Bereitstellung eingehender Medien über SSH direkt 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 für 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: Nach der anfänglichen Initialisierung wird der Remote-SSH-Workspace zum tatsächlichen Sandbox-Zustand. Nach dem Initialisierungsschritt 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 der lokalen Umgebung. Browser-Sandboxing wird von diesem Backend nicht unterstützt und die 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 Modus zur Workspace-Synchronisierung über mirror.

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

mode: "mirror" (Standard) hält den lokalen Arbeitsbereich kanonisch: OpenClaw synchronisiert den lokalen Arbeitsbereich vor exec in die Sandbox und danach zurück. mode: "remote" befüllt den Remote-Arbeitsbereich einmalig aus dem lokalen Arbeitsbereich und führt anschließend exec/read/write/edit/apply_patch direkt im Remote-Arbeitsbereich aus, ohne zurückzusynchronisieren; lokale Änderungen nach der initialen Befüllung bleiben unsichtbar, bis Sie openclaw sandbox recreate. Unter scope: "agent" oder scope: "shared" wird dieser Remote-Arbeitsbereich im selben 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-Laufzeitumgebungen genauso wie Docker-Laufzeitumgebungen; die Bereinigungslogik berücksichtigt das Backend.

Die vollständigen Voraussetzungen, die Konfigurationsreferenz, den Vergleich der Arbeitsbereichsmodi und Details zum Lebenszyklus finden Sie unter OpenShell.

Zugriff auf den Arbeitsbereich

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

Mit dem OpenShell-Backend verwendet der Modus mirror weiterhin den lokalen Arbeitsbereich als kanonische Quelle zwischen Ausführungen, der Modus remote verwendet nach der initialen Befüllung den Remote-OpenShell-Arbeitsbereich als kanonische Quelle, und workspaceAccess: "ro"/"none" beschränken das Schreibverhalten weiterhin auf dieselbe Weise.

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

Mehrere Ordner für einen Agenten

Verwenden Sie Docker-Bind-Mounts, wenn ein in einer Sandbox ausgeführter Agent mehr als seinen primären Arbeitsbereich benötigt. Jeder Eintrag ordnet einen Host-Ordner mit einem expliziten Zugriffsmodus einem Container-Pfad zu:

host-directory:container-directory:rohost-directory:container-directory:rw

• ro macht den eingebundenen Ordner innerhalb der Sandbox schreibgeschützt.
• rw erlaubt Tools und Prozessen in der Sandbox, den Host-Ordner zu ändern.
• Der Container-Pfad ist der Pfad, den der Agent verwendet. Host-Pfade werden nicht automatisch offengelegt.

Dieses Beispiel gibt dem Agenten research einen beschreibbaren primären Arbeitsbereich, schreibgeschütztes Referenzmaterial unter /reference und einen separaten beschreibbaren Ausgabeordner unter /drafts:

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // Erforderlich, da sich diese Quellen außerhalb des Agenten-Arbeitsbereichs befinden.            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess und Bind-Modi sind unabhängig voneinander:

Das Ändern von workspaceAccess ändert eine zusätzliche Bind-Einbindung nicht von ro zu rw oder umgekehrt. Globale und agentenspezifische docker.binds werden zusammengeführt. Behalten Sie scope: "agent" oder "session" für agentenspezifische Bind-Einbindungen bei; scope: "shared" ignoriert alle agentenspezifischen Docker-Überschreibungen und verwendet ausschließlich globale Bind-Einbindungen.

Bind-Mounts sind die unterstützte Grenze für mehrere Ordner, da Docker die Dateisystemansicht des Containers mit Mount-Isolierung erstellt und der Modus ro/rw für jeden Prozess in der Sandbox gilt. Diese Grenze umfasst exec, Dateisystem-Tools, untergeordnete Prozesse und Bibliotheken, ohne Pfadautorisierungsprüfungen in jedem OpenClaw-Codepfad zu duplizieren. Eine hostseitige Pfad-Zulassungsliste kann nicht dieselbe vollständige Grenze bieten, wenn eine zugelassene Shell oder Abhängigkeit direkt auf Dateien zugreifen kann.

Die optionale Einstellung dangerouslyAllowExternalBindSources erlaubt nur Quellen außerhalb der Arbeitsbereichswurzeln. Sie deaktiviert nicht die Prüfungen von OpenClaw auf blockierte Systempfade, Anmeldedaten, Docker-Sockets, Symlink-Elternpfade oder reservierte Ziele. Bevorzugen Sie den kleinstmöglichen Ordner, verwenden Sie ro, sofern kein Schreibzugriff erforderlich ist, und erstellen Sie die Sandbox nach Änderungen an den Einbindungen neu:

openclaw sandbox recreate --agent research

Weiteres Verhalten von Bind-Einbindungen

agents.defaults.sandbox.docker.binds konfiguriert globale Einbindungen. Das Format entspricht derselben Form host:container:mode (zum Beispiel "/home/user/source:/source:rw").

agents.defaults.sandbox.browser.binds bindet zusätzliche Host-Verzeichnisse ausschließlich in den Container des Sandbox-Browsers ein. Wenn diese Einstellung gesetzt ist (einschließlich []), ersetzt sie docker.binds für den Browser-Container; wenn sie nicht gesetzt ist, 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

Standardmäßiges 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 werden Docker-Sandbox-Container 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. Legen Sie OPENCLAW_SANDBOX=1 (oder true/yes/on) fest, um diesen Pfad zu aktivieren. Überschreiben Sie den Speicherort des Sockets 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 jeder Ausführung). Der Befehl wird innerhalb des Containers über sh -lc ausgeführt.

Pfade:

• Global: agents.defaults.sandbox.docker.setupCommand
• Pro Agent: agents.entries.*.sandbox.docker.setupCommand

Tool-Richtlinien und Ausweichmöglichkeiten

Zulassungs-/Ablehnungsrichtlinien für Tools gelten weiterhin vor den Sandbox-Regeln. Wenn ein Tool global oder für einen Agenten abgelehnt wird, stellt die Sandbox es nicht wieder bereit.

tools.elevated ist eine explizite Ausweichmöglichkeit, die exec außerhalb der Sandbox ausführt (standardmäßig gateway oder node, wenn das Ausführungsziel node ist). /exec-Direktiven gelten nur für autorisierte Absender und bleiben sitzungsbezogen bestehen; um exec vollständig zu deaktivieren, verwenden Sie die Ablehnungsrichtlinie für Tools (siehe Sandbox im Vergleich zu Tool-Richtlinien und erhöhten Berechtigungen).

Fehlerdiagnose:

• openclaw sandbox list zeigt Sandbox-Container, Status, Image-Übereinstimmung, Alter, Leerlaufzeit und die zugehörige Sitzung bzw. den zugehörigen Agenten an.
• openclaw sandbox explain [--session <key>] [--agent <id>] prüft den effektiven Sandbox-Modus, den Host-Arbeitsbereich, das Laufzeit-Arbeitsverzeichnis, Docker-Einbindungen, Tool-Richtlinien und Konfigurationsschlüssel zur Problembehebung. Das Feld workspaceRoot enthält weiterhin 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 im Vergleich zu Tool-Richtlinien und erhöhten Berechtigungen finden Sie ein Denkmodell für die Frage „Warum ist dies blockiert?“.

Überschreibungen für mehrere Agenten

Jeder Agent kann Sandbox und Tools überschreiben: agents.entries.*.sandbox und agents.entries.*.tools (sowie agents.entries.*.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

• Sandbox und Tools für mehrere Agenten -- Überschreibungen pro Agent und Rangfolge
• OpenShell -- Einrichtung des verwalteten Sandbox-Backends, Arbeitsbereichsmodi und Konfigurationsreferenz
• Sandbox-Konfiguration
• Sandbox im Vergleich zu Tool-Richtlinien und erhöhten Berechtigungen -- Fehlerdiagnose für „Warum ist dies blockiert?“
• Sicherheit