Sandboxing mit OpenClaw

Was wird in der Sandbox ausgeführt

OpenClaw führt Tools in isolierten Umgebungen aus, um das Risiko bei unerwartetem Modellverhalten zu minimieren. Die Sandbox-Umgebung für OpenClaw umfasst dabei verschiedene Aspekte der Dateisystem- und Prozesskontrolle.

Die Ausführung von Tools (exec, read, write, edit, apply_patch, process usw.) findet innerhalb der Sandbox statt.
Ein optionaler Browser in der Sandbox (agents.defaults.sandbox.browser) kann konfiguriert werden.
- Standardmäßig startet der Sandbox-Browser automatisch, sobald ein Tool ihn benötigt, um sicherzustellen, dass das CDP erreichbar ist. Dies steuerst du über agents.defaults.sandbox.browser.autoStart und agents.defaults.sandbox.browser.autoStartTimeoutMs.
- Sandbox-Browser-Container verwenden standardmäßig ein dediziertes Docker-Netzwerk (openclaw-sandbox-browser) anstelle des globalen bridge-Netzwerks. Die Konfiguration erfolgt über agents.defaults.sandbox.browser.network.
- Über agents.defaults.sandbox.browser.cdpSourceRange kannst du den Zugriff auf den Container-Edge-CDP mittels einer CIDR-Allowlist einschränken (z. B. 172.21.0.1/32).
- Der Zugriff auf den noVNC-Observer ist standardmäßig passwortgeschützt. OpenClaw generiert eine kurzlebige Token-URL, die eine lokale Bootstrap-Seite bereitstellt und noVNC mit dem Passwort im URL-Fragment öffnet (nicht in Query-Parametern oder Header-Logs).
- Mit agents.defaults.sandbox.browser.allowHostControl erlaubst du Sandbox-Sitzungen den expliziten Zugriff auf den Host-Browser.
- Optionale Allowlists steuern den Zugriff für target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Folgende Bereiche sind nicht in der Sandbox isoliert:

Der Gateway-Prozess selbst läuft außerhalb.
Tools, die explizit für die Ausführung außerhalb der Sandbox zugelassen sind (z. B. tools.elevated).
- Elevated exec umgeht die Sandbox und nutzt den konfigurierten Escape-Pfad (standardmäßig gateway oder node, wenn das exec-Ziel node ist).
- Wenn Sandboxing deaktiviert ist, ändert tools.elevated das Ausführungsverhalten nicht, da es ohnehin auf dem Host läuft. Siehe Elevated Mode.

Modi

Der Parameter agents.defaults.sandbox.mode legt fest, wann die Sandbox-Umgebung zum Einsatz kommt.

"off": Es findet kein Sandboxing statt.
"non-main": Die Sandbox wird nur für non-main-Sitzungen verwendet (Standardeinstellung, falls du normale Chats auf dem Host bevorzugst).
"all": Jede Sitzung wird in einer Sandbox ausgeführt. Hinweis: "non-main" basiert auf dem session.mainKey (Standard ist "main"), nicht auf der Agent-ID. Gruppen- oder Kanal-Sitzungen verwenden eigene Keys und werden daher als non-main eingestuft und in der Sandbox ausgeführt.

Umfang

Mit agents.defaults.sandbox.scope bestimmst du, wie viele Container erstellt werden.

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

Backend

Über agents.defaults.sandbox.backend wählst du aus, welche Runtime die Sandbox bereitstellt.

"docker" (Standard bei aktiviertem Sandboxing): Eine lokale, auf Docker basierende Sandbox-Runtime.
"ssh": Eine generische, SSH-basierte Remote-Sandbox-Runtime.
"openshell": Eine auf OpenShell basierende Sandbox-Runtime.

SSH-spezifische Konfigurationen findest du unter agents.defaults.sandbox.ssh. Konfigurationen für OpenShell liegen unter plugins.entries.openshell.config.

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

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

Workspace-Zugriff

Die Einstellung agents.defaults.sandbox.workspaceAccess legt fest, was die sandbox sehen kann:

"none" (Standard): Tools sehen ein sandbox-workspace unter ~/.openclaw/sandboxes.
"ro": Mountet das agent-workspace schreibgeschützt unter /agent (deaktiviert write, edit und apply_patch).
"rw": Mountet das agent-workspace mit Lese- und Schreibzugriff unter /workspace.

Beim OpenShell-Backend gilt:

Der mirror-Modus verwendet weiterhin das lokale workspace als kanonische Quelle zwischen den exec-Durchläufen.
Der remote-Modus nutzt nach dem initialen Seed das remote OpenShell-workspace als kanonische Quelle.
Die Einstellungen workspaceAccess: "ro" und "none" schränken das Schreibverhalten weiterhin auf die gleiche Weise ein.

Eingehende Medien werden in das aktive sandbox-workspace (media/inbound/*) kopiert. Ein Hinweis zu Skills: Das read-Tool ist auf die sandbox beschränkt. Bei workspaceAccess: "none" spiegelt OpenClaw berechtigte Skills in das sandbox-workspace (.../skills), damit sie gelesen werden können. Mit "rw" sind workspace-Skills direkt unter /workspace/skills lesbar.

Benutzerdefinierte Bind-Mounts

Mit agents.defaults.sandbox.docker.binds kannst du zusätzliche Host-Verzeichnisse in den Container einbinden. Das Format lautet host:container:mode (zum Beispiel "/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 ausschließlich in den sandbox browser-Container.

Wenn diese Option gesetzt ist (auch als []), ersetzt sie agents.defaults.sandbox.docker.binds für den Browser-Container.
Wenn sie weggelassen wird, greift 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"],
          },
        },
      },
    ],
  },
}

Sicherheitshinweise:

Binds umgehen das sandbox-Dateisystem: Sie legen Host-Pfade mit dem von dir gewählten Modus (:ro oder :rw) offen.
OpenClaw blockiert gefährliche Bind-Quellen (zum Beispiel: docker.sock, /etc, /proc, /sys, /dev sowie übergeordnete Mounts, die diese freilegen würden).
OpenClaw blockiert zudem gängige Verzeichnisse mit Anmeldedaten im Home-Verzeichnis wie ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm und ~/.ssh.
Die Validierung der Binds erfolgt nicht nur über einen String-Vergleich. OpenClaw normalisiert den Quellpfad und löst ihn durch den tiefsten existierenden Vorfahren auf, bevor blockierte Pfade und erlaubte Wurzelverzeichnisse erneut geprüft werden.
Das bedeutet, dass Symlink-Parent-Escapes auch dann fehlschlagen, wenn das finale Ziel noch nicht existiert. Beispiel: /workspace/run-link/new-file wird weiterhin als /var/run/... aufgelöst, falls run-link dorthin zeigt.
Erlaubte Quell-Wurzelverzeichnisse werden auf die gleiche Weise kanonisiert, sodass ein Pfad, der nur vor der Symlink-Auflösung innerhalb der Whitelist liegt, dennoch als outside allowed roots abgelehnt wird.
Sensible Mounts (Geheimnisse, SSH-Schlüssel, Service-Anmeldedaten) sollten immer :ro sein, sofern sie nicht zwingend Schreibzugriff benötigen.
Kombiniere dies mit workspaceAccess: "ro", wenn du nur Lesezugriff auf das workspace benötigst; die Bind-Modi bleiben davon unabhängig.
Siehe Sandbox vs Tool Policy vs Elevated für Details dazu, wie Binds mit Tool-Richtlinien und elevated exec interagieren.

Images und Setup

Das Standard-Docker-Image für OpenClaw ist openclaw-sandbox:bookworm-slim.

Erstelle es einmalig mit folgendem Befehl:

scripts/sandbox-setup.sh

Hinweis: Das Standard-Image enthält kein Node.js. Wenn ein Skill Node.js (oder andere Runtimes) benötigt, erstelle entweder ein eigenes Image oder installiere die Pakete über sandbox.docker.setupCommand (erfordert Netzwerkzugriff + beschreibbares Root-Verzeichnis + Root-Benutzer).

Wenn du ein funktionaleres Sandbox-Image mit gängigen Tools (zum Beispiel curl, jq, nodejs, python3, git) bevorzugst, baue es so:

scripts/sandbox-common-setup.sh

Setze danach agents.defaults.sandbox.docker.image auf openclaw-sandbox-common:bookworm-slim.

Für ein Sandbox-Browser-Image nutze:

scripts/sandbox-browser-setup.sh

Standardmäßig laufen Docker-Sandbox-Container ohne Netzwerk. Du kannst dies mit agents.defaults.sandbox.docker.network überschreiben.

Das mitgelieferte Sandbox-Browser-Image wendet zudem konservative Chromium-Start-Defaults für containerisierte Workloads an. Die aktuellen Container-Defaults umfassen:

--remote-debugging-address=127.0.0.1
--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
--user-data-dir=${HOME}/.chrome
--no-first-run
--no-default-browser-check
--disable-3d-apis
--disable-gpu
--disable-dev-shm-usage
--disable-background-networking
--disable-extensions
--disable-features=TranslateUI
--disable-breakpad
--disable-crash-reporter
--disable-software-rasterizer
--no-zygote
--metrics-recording-only
--renderer-process-limit=2
--no-sandbox und --disable-setuid-sandbox wenn noSandbox aktiviert ist.
Die drei Grafik-Härtungs-Flags (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) sind optional und nützlich, wenn Containern die GPU-Unterstützung fehlt. Setze OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0, falls dein Workload WebGL oder andere 3D/Browser-Funktionen benötigt.
--disable-extensions ist standardmäßig aktiviert und kann mit OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 für Flows, die Erweiterungen benötigen, deaktiviert werden.
--renderer-process-limit=2 wird durch OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> gesteuert, wobei 0 den Standardwert von Chromium beibehält.

Falls du ein anderes Runtime-Profil benötigst, verwende ein benutzerdefiniertes Browser-Image und stelle deinen eigenen Entrypoint bereit. Für lokale (Nicht-Container) Chromium-Profile verwende browser.extraArgs, um zusätzliche Start-Flags anzuhängen.

Sicherheits-Defaults:

network: "host" ist blockiert.
network: "container:<id>" ist standardmäßig blockiert (Risiko durch Namespace-Join-Bypass).
Notfall-Override: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

Docker-Installationen und das containerisierte Gateway findest du hier: Docker

Für Docker-Gateway-Deployments kann scripts/docker/setup.sh die Sandbox-Konfiguration booten. Setze OPENCLAW_SANDBOX=1 (oder true/yes/on), um diesen Pfad zu aktivieren. Du kannst den Socket-Speicherort mit OPENCLAW_DOCKER_SOCKET überschreiben. Vollständiges Setup und Umgebungsreferenz: Docker.

setupCommand (einmaliges Container-Setup)

Der setupCommand wird einmalig ausgeführt, nachdem der Sandbox-Container erstellt wurde (nicht bei jedem Durchlauf). Er wird innerhalb des Containers über sh -lc ausgeführt.

Pfade:

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

Häufige Fehlerquellen:

Das Standard-docker.network ist "none" (kein ausgehender Datenverkehr), daher schlagen Paketinstallationen fehl.
docker.network: "container:<id>" erfordert dangerouslyAllowContainerNamespaceJoin: true und ist nur als Notfalllösung gedacht.
readOnlyRoot: true verhindert Schreibzugriffe; setze readOnlyRoot: false oder erstelle ein benutzerdefiniertes Image.
Der user muss für Paketinstallationen Root sein (lasse user weg oder setze user: "0:0").
Sandbox-Exec erbt nicht die process.env des Hosts. Verwende agents.defaults.sandbox.docker.env (oder ein benutzerdefiniertes Image) für Skill-API-Schlüssel.

AI Setup Assistant

Tool-Richtlinien und Escape-Hatches

Tool-Allow- und Deny-Richtlinien greifen immer vor den Sandbox-Regeln. Wenn ein Tool global oder für einen bestimmten Agenten gesperrt ist, kann es durch die Sandbox nicht wieder freigeschaltet werden.

tools.elevated ist ein expliziter Escape-Hatch, der exec außerhalb der Sandbox ausführt (standardmäßig über das Gateway, oder über Node.js, wenn das Exec-Ziel Node.js ist). Die /exec-Direktiven gelten nur für autorisierte Absender und bleiben pro Sitzung bestehen; um exec vollständig zu deaktivieren, verwende die Tool-Richtlinie „Deny“ (siehe Sandbox vs Tool Policy vs Elevated).

Fehlerbehebung:

Nutze openclaw sandbox explain, um den effektiven Sandbox-Modus, die Tool-Richtlinie und die Konfigurationsschlüssel für „Fix-it“ zu überprüfen.
Sieh dir Sandbox vs Tool Policy vs Elevated an, um das mentale Modell hinter „Warum ist das blockiert?“ zu verstehen. Halte die Sicherheit strikt aufrecht.

Multi-Agent-Überschreibungen

Jeder Agent kann die Sandbox- und Tool-Einstellungen individuell überschreiben: agents.list[].sandbox und agents.list[].tools (zusätzlich zu agents.list[].tools.sandbox.tools für die Sandbox-Tool-Richtlinie). Informationen zur Rangfolge findest du unter Multi-Agent Sandbox & Tools.

Minimales Aktivierungsbeispiel

Wenn du OpenClaw mit einer minimalen Konfiguration starten möchtest, kannst du die Sandbox-Einstellungen direkt in deiner JSON-Konfigurationsdatei definieren. Dieses Beispiel zeigt dir, wie du die Standardeinstellungen für deine Agenten festlegst, um die Sandbox-Umgebung effizient zu steuern.

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

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.