Sandboxing

OpenClaw kann Tools innerhalb von Docker-Containern ausführen, um den Wirkungsradius zu begrenzen. Das ist optional und wird per Konfiguration gesteuert (agents.defaults.sandbox oder agents.list[].sandbox). Wenn Sandboxing deaktiviert ist, laufen Tools auf dem Host. Das Gateway bleibt auf dem Host; nur die Tool-Ausführung läuft bei Aktivierung in einer isolierten Sandbox.

Das ist keine perfekte Sicherheitsgrenze, begrenzt aber materiell den Dateisystem- und Prozesszugriff, wenn das Modell etwas Dummes tut.

Was wird sandboxed

  • Tool-Ausführung (exec, read, write, edit, apply_patch, process usw.).
  • Optionaler Sandbox-Browser (agents.defaults.sandbox.browser).
    • Standardmäßig startet der Sandbox-Browser automatisch (stellt sicher, dass CDP erreichbar ist), wenn das Browser-Tool ihn braucht. Konfigurierbar über agents.defaults.sandbox.browser.autoStart und agents.defaults.sandbox.browser.autoStartTimeoutMs.
    • Standardmäßig verwenden Sandbox-Browser-Container ein dediziertes Docker-Netzwerk (openclaw-sandbox-browser) statt des globalen bridge-Netzwerks. Konfigurierbar mit agents.defaults.sandbox.browser.network.
    • Optionaler agents.defaults.sandbox.browser.cdpSourceRange schränkt Container-Edge-CDP-Ingress mit einer CIDR-Allowlist ein (z. B. 172.21.0.1/32).
    • noVNC-Beobachter-Zugriff 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/Header-Logs).
    • agents.defaults.sandbox.browser.allowHostControl erlaubt sandboxed Sessions, den Host-Browser explizit anzusprechen.
    • Optionale Allowlists steuern target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Nicht sandboxed:

  • Der Gateway-Prozess selbst.
  • Jedes Tool, das explizit auf dem Host ausgeführt werden darf (z. B. tools.elevated).
    • Elevated exec läuft auf dem Host und umgeht das Sandboxing.
    • Wenn Sandboxing deaktiviert ist, ändert tools.elevated die Ausführung nicht (bereits auf dem Host). Siehe Elevated-Modus.

Modi

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

  • "off": Kein Sandboxing.
  • "non-main": Nur Nicht-Main-Sessions werden sandboxed (Standard, wenn normale Chats auf dem Host laufen sollen).
  • "all": Jede Session läuft in einer Sandbox. Hinweis: "non-main" basiert auf session.mainKey (Standard "main"), nicht auf der Agent-ID. Gruppen-/Channel-Sessions verwenden eigene Keys und gelten daher als Nicht-Main und werden sandboxed.

Scope

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

  • "session" (Standard): Ein Container pro Session.
  • "agent": Ein Container pro Agent.
  • "shared": Ein Container für alle sandboxed Sessions.

Workspace-Zugriff

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

  • "none" (Standard): Tools sehen einen Sandbox-Workspace unter ~/.openclaw/sandboxes.
  • "ro": Mountet den Agent-Workspace read-only unter /agent (deaktiviert write/edit/apply_patch).
  • "rw": Mountet den Agent-Workspace read-write unter /workspace.

Eingehende Medien werden in den aktiven Sandbox-Workspace kopiert (media/inbound/*). Skills-Hinweis: Das read-Tool ist sandbox-root-beschränkt. Bei workspaceAccess: "none" spiegelt OpenClaw berechtigte Skills in den Sandbox-Workspace (.../skills), damit sie gelesen werden können. Bei "rw" sind Workspace-Skills unter /workspace/skills lesbar.

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 per-Agent-Binds werden zusammengeführt (nicht ersetzt). Unter scope: "shared" werden per-Agent-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 nicht gesetzt, fällt der Browser-Container auf agents.defaults.sandbox.docker.binds zurück (abwärtskompatibel).

Beispiel (Read-only-Quellcode + 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 gesetzten Modus offen (:ro oder :rw).
  • OpenClaw blockiert gefährliche Bind-Quellen (z. B.: docker.sock, /etc, /proc, /sys, /dev und übergeordnete Mounts, die diese exponieren würden).
  • Sensitive Mounts (Secrets, SSH-Keys, Service-Credentials) sollten :ro sein, es sei denn, es ist absolut notwendig.
  • Kombiniere mit workspaceAccess: "ro", wenn du nur Lesezugriff auf den Workspace brauchst; Bind-Modi bleiben unabhängig.
  • Siehe Sandbox vs Tool-Policy vs Elevated für die Interaktion von Binds mit Tool-Policy und Elevated Exec.

Images + Setup

Standard-Image: openclaw-sandbox:bookworm-slim

Einmalig bauen:

scripts/sandbox-setup.sh

Hinweis: Das Standard-Image enthält kein Node. Wenn ein Skill Node (oder andere Runtimes) benötigt, erstelle entweder ein benutzerdefiniertes Image oder installiere per sandbox.docker.setupCommand (erfordert Netzwerk-Egress + beschreibbares Root + Root-User).

Wenn du ein funktionaleres Sandbox-Image mit gängiger Tooling brauchst (z. B. curl, jq, nodejs, python3, git), baue:

scripts/sandbox-common-setup.sh

Dann setze agents.defaults.sandbox.docker.image auf openclaw-sandbox-common:bookworm-slim.

Sandbox-Browser-Image:

scripts/sandbox-browser-setup.sh

Standardmäßig laufen Sandbox-Container ohne Netzwerk. Überschreibe mit agents.defaults.sandbox.docker.network.

Das mitgelieferte Sandbox-Browser-Image wendet auch konservative Chromium-Startoptionen für containerisierte Workloads an. Aktuelle Container-Standardwerte umfassen:

  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<abgeleitet von 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 Container keine GPU-Unterstützung haben. Setze OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0, wenn dein Workload WebGL oder andere 3D-/Browser-Features benötigt.
  • --disable-extensions ist standardmäßig aktiviert und kann mit OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 für Extensions-abhängige Flows deaktiviert werden.
  • --renderer-process-limit=2 wird durch OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> gesteuert, wobei 0 den Chromium-Standard beibehält.

Wenn du ein anderes Runtime-Profil brauchst, verwende ein benutzerdefiniertes Browser-Image und stelle deinen eigenen Entrypoint bereit. Für lokale (Nicht-Container) Chromium-Profile nutze browser.extraArgs, um zusätzliche Startflags anzuhängen.

Sicherheits-Standardwerte:

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

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

Für Docker-Gateway-Deployments kann docker-setup.sh die Sandbox-Konfiguration bootstrappen. 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 Env-Referenz: Docker.

setupCommand (einmaliges Container-Setup)

setupCommand wird einmal nach der Container-Erstellung ausgeführt (nicht bei jedem Run). Es wird im Container über sh -lc ausgeführt.

Pfade:

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

Häufige Stolperfallen:

  • Standard docker.network ist "none" (kein Egress), daher schlagen Paket-Installationen fehl.
  • docker.network: "container:<id>" erfordert dangerouslyAllowContainerNamespaceJoin: true und ist nur für Break-Glass.
  • readOnlyRoot: true verhindert Schreibvorgänge; setze readOnlyRoot: false oder erstelle ein benutzerdefiniertes Image.
  • user muss Root sein für Paketinstallationen (lasse user weg oder setze user: "0:0").
  • Sandbox-Exec erbt nicht die Host-process.env. Verwende agents.defaults.sandbox.docker.env (oder ein benutzerdefiniertes Image) für Skill-API-Keys.

Tool-Policy + Notausgänge

Tool-Allow/Deny-Policies gelten weiterhin vor den Sandbox-Regeln. Wenn ein Tool global oder per-Agent denied ist, bringt Sandboxing es nicht zurück.

tools.elevated ist ein expliziter Notausgang, der exec auf dem Host ausführt. /exec-Direktiven gelten nur für autorisierte Sender und persistieren pro Session; um exec hart zu deaktivieren, verwende Tool-Policy-Deny (siehe Sandbox vs Tool-Policy vs Elevated).

Debugging:

  • Verwende openclaw sandbox explain, um den effektiven Sandbox-Modus, die Tool-Policy und Fix-it-Config-Keys zu inspizieren.
  • Siehe Sandbox vs Tool-Policy vs Elevated für das “warum ist das blockiert?”-Denkmodell. Halte 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 Sandbox-Tool-Policy). Siehe Multi-Agent Sandbox & Tools für die Vorrangreihenfolge.

Minimales Aktivierungsbeispiel

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

Verwandte Dokumentation

arrow_back
Zurück
Security
Weiter
Sandbox Vs Tool Policy Vs Elevated
arrow_forward