​

Sandboxing

​

Was in eine Sandbox kommt

• Tool-Ausführung (exec, read, write, edit, apply_patch, process usw.).
• Optionaler sandboxierter Browser (agents.defaults.sandbox.browser).
  • Standardmäßig startet der Sandbox-Browser automatisch (stellt sicher, dass CDP erreichbar ist), wenn das Browser-Tool ihn benötigt. Konfiguration ü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. Konfiguration über agents.defaults.sandbox.browser.network.
  • Optionales agents.defaults.sandbox.browser.cdpSourceRange beschränkt eingehenden CDP-Zugriff am Container-Rand mit einer CIDR-Allowlist (zum Beispiel 172.21.0.1/32).
  • noVNC-Beobachterzugriff ist standardmäßig passwortgeschützt; OpenClaw erzeugt eine kurzlebige Token-URL, die eine lokale Bootstrap-Seite bereitstellt und noVNC mit Passwort im URL-Fragment öffnet (nicht in Query-/Header-Logs).
  • agents.defaults.sandbox.browser.allowHostControl erlaubt es sandboxierten Sitzungen, ausdrücklich den Host-Browser anzusprechen.
  • Optionale Allowlists begrenzen target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Der Gateway-Prozess selbst.
• Jedes Tool, das ausdrücklich für die Ausführung außerhalb der Sandbox erlaubt ist (z. B. tools.elevated).
  • Erhöhtes exec umgeht Sandboxing und verwendet den konfigurierten Escape-Pfad (gateway standardmäßig oder node, wenn das Exec-Ziel node ist).
  • Wenn Sandboxing deaktiviert ist, ändert tools.elevated die Ausführung nicht (läuft bereits auf dem Host). Siehe Elevated Mode.

​

Modi

• "off": kein Sandboxing.
• "non-main": nur Nicht-Main-Sitzungen werden sandboxiert (Standard, wenn normale Chats auf dem Host laufen sollen).
• "all": jede Sitzung läuft in einer Sandbox. Hinweis: "non-main" basiert auf session.mainKey (Standard "main"), nicht auf der Agent-ID. Gruppen-/Channel-Sitzungen verwenden ihre eigenen Schlüssel, zählen also als non-main und werden sandboxiert.

​

Scope

• "agent" (Standard): ein Container pro Agent.
• "session": ein Container pro Sitzung.
• "shared": ein Container, der von allen sandboxierten Sitzungen gemeinsam genutzt wird.

​

Backend

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

​

Backend auswählen

​

Docker-Backend

• Konfiguration erfordert Host-Pfade: Die workspace-Konfiguration in openclaw.json MUSS den absoluten Pfad des Hosts enthalten (z. B. /home/user/.openclaw/workspaces), nicht den internen Pfad des Gateway-Containers. Wenn OpenClaw den Docker-Daemon auffordert, eine Sandbox zu starten, wertet der Daemon Pfade relativ zum Namespace des Host-OS aus, nicht zum Gateway-Namespace.
• FS-Bridge-Parität (identisches Volume-Mapping): Der native OpenClaw-Gateway-Prozess schreibt außerdem Heartbeat- und Bridge-Dateien in das Verzeichnis workspace. Da das Gateway exakt denselben String (den Host-Pfad) innerhalb seiner eigenen containerisierten Umgebung auswertet, MUSS die Gateway-Bereitstellung ein identisches Volume-Mapping enthalten, das den Host-Namespace nativ verknüpft (-v /home/user/.openclaw:/home/user/.openclaw).

​

SSH-Backend

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

• OpenClaw erstellt unter sandbox.ssh.workspaceRoot ein Remote-Root pro Scope.
• Bei der ersten Verwendung nach Erstellung oder Neuerstellung seedet OpenClaw diesen Remote-Workspace einmalig aus dem lokalen Workspace.
• Danach laufen exec, read, write, edit, apply_patch, Media-Reads im Prompt und Inbound-Media-Staging direkt gegen den Remote-Workspace über SSH.
• OpenClaw synchronisiert Remote-Änderungen nicht automatisch zurück in den lokalen Workspace.

• identityFile, certificateFile, knownHostsFile: vorhandene lokale Dateien verwenden und über die OpenSSH-Konfiguration durchreichen.
• identityData, certificateData, knownHostsData: Inline-Strings oder SecretRefs verwenden. OpenClaw löst sie über den normalen Runtime-Snapshot für Secrets auf, schreibt sie mit 0600 in temporäre Dateien und löscht sie, wenn die SSH-Sitzung endet.
• Wenn für dasselbe Element sowohl *File als auch *Data gesetzt sind, gewinnt für diese SSH-Sitzung *Data.

• Host-lokale Bearbeitungen, die außerhalb von OpenClaw nach dem Seed-Schritt erfolgen, sind remote nicht sichtbar, bis Sie die Sandbox neu erstellen.
• openclaw sandbox recreate löscht das Remote-Root pro Scope und seedet es bei der nächsten Verwendung erneut aus lokal.
• Browser-Sandboxing wird im SSH-Backend nicht unterstützt.
• Einstellungen unter sandbox.docker.* gelten nicht für das SSH-Backend.

​

OpenShell-Backend

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

• 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 nach Erstellung der Sandbox kanonisch. OpenClaw seedet den Remote-Workspace einmalig aus dem lokalen Workspace, danach laufen Datei-Tools und exec direkt gegen die Remote-Sandbox, ohne Änderungen zurückzusynchronisieren.

• OpenClaw fordert bei OpenShell eine sandboxspezifische SSH-Konfiguration über openshell sandbox ssh-config <name> an.
• Der Core schreibt diese SSH-Konfiguration in eine temporäre Datei, öffnet die SSH-Sitzung und verwendet dieselbe Remote-Dateisystem-Bridge wie bei backend: "ssh" wieder.
• Nur im Modus mirror unterscheidet sich der Lebenszyklus: lokal nach remote vor exec synchronisieren, dann zurück synchronisieren.

• Sandbox-Browser wird noch nicht unterstützt
• sandbox.docker.binds wird im OpenShell-Backend nicht unterstützt
• Docker-spezifische Runtime-Optionen unter sandbox.docker.* gelten weiterhin nur für das Docker-Backend

​

Workspace-Modi

mirror

• Vor exec synchronisiert OpenClaw den lokalen Workspace in die OpenShell-Sandbox.
• Nach exec synchronisiert OpenClaw den Remote-Workspace zurück in den lokalen Workspace.
• Datei-Tools arbeiten weiterhin über die Sandbox-Bridge, aber der lokale Workspace bleibt zwischen den Zügen die Single Source of Truth.

• Sie Dateien lokal außerhalb von OpenClaw bearbeiten und möchten, dass diese Änderungen automatisch in der Sandbox erscheinen
• die OpenShell-Sandbox sich möglichst ähnlich wie das Docker-Backend verhalten soll
• der Host-Workspace nach jedem exec-Zug die Schreibvorgänge der Sandbox widerspiegeln soll

• zusätzlicher Synchronisationsaufwand vor und nach exec

remote

• Wenn die Sandbox zum ersten Mal erstellt wird, seedet OpenClaw den Remote-Workspace einmalig aus dem lokalen Workspace.
• Danach arbeiten exec, read, write, edit und apply_patch direkt gegen den Remote-OpenShell-Workspace.
• OpenClaw synchronisiert Remote-Änderungen nach exec nicht zurück in den lokalen Workspace.
• Media-Reads zur Prompt-Zeit funktionieren weiterhin, weil Datei- und Media-Tools über die Sandbox-Bridge lesen, statt einen lokalen Host-Pfad vorauszusetzen.
• Der Transport erfolgt per SSH in die OpenShell-Sandbox, die von openshell sandbox ssh-config zurückgegeben wird.

• Wenn Sie Dateien auf dem Host außerhalb von OpenClaw nach dem Seed-Schritt bearbeiten, sieht die Remote-Sandbox diese Änderungen nicht automatisch.
• Wenn die Sandbox neu erstellt wird, wird der Remote-Workspace erneut aus dem lokalen Workspace geseedet.
• Bei scope: "agent" oder scope: "shared" wird dieser Remote-Workspace auf genau diesem Scope gemeinsam genutzt.

• die Sandbox primär auf der Remote-Seite von OpenShell leben soll
• Sie geringeren Synchronisations-Overhead pro Zug möchten
• host-lokale Bearbeitungen den Remote-Sandbox-Zustand nicht stillschweigend überschreiben sollen

​

OpenShell-Lebenszyklus

• openclaw sandbox list zeigt OpenShell-Runtimes ebenso wie Docker-Runtimes an
• 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 backendbewusst

• recreate löscht den kanonischen Remote-Workspace für diesen Scope
• die nächste Verwendung seedet einen frischen Remote-Workspace aus dem lokalen Workspace

​

Workspace-Zugriff

• "none" (Standard): Tools sehen einen Sandbox-Workspace unter ~/.openclaw/sandboxes.
• "ro": mountet den Agent-Workspace schreibgeschützt unter /agent (deaktiviert write/edit/apply_patch).
• "rw": mountet den Agent-Workspace mit Lese-/Schreibzugriff unter /workspace.

• Im Modus mirror bleibt der lokale Workspace zwischen den exec-Zügen die kanonische Quelle
• Im Modus remote wird der Remote-OpenShell-Workspace nach dem initialen Seed zur kanonischen Quelle
• workspaceAccess: "ro" und "none" beschränken das Schreibverhalten weiterhin auf dieselbe Weise

​

Benutzerdefinierte Bind-Mounts

• Wenn gesetzt (einschließlich []), ersetzt es agents.defaults.sandbox.docker.binds für den Browser-Container.
• Wenn weggelassen, verwendet der Browser-Container als Fallback agents.defaults.sandbox.docker.binds (abwärtskompatibel).

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

• Binds umgehen das Sandbox-Dateisystem: Sie legen Host-Pfade mit dem von Ihnen gesetzten Modus offen (:ro oder :rw).
• OpenClaw blockiert gefährliche Bind-Quellen (zum Beispiel: docker.sock, /etc, /proc, /sys, /dev und übergeordnete Mounts, die diese freilegen würden).
• OpenClaw blockiert außerdem gängige Root-Verzeichnisse für Credentials im Home-Verzeichnis wie ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm und ~/.ssh.
• Die Bind-Validierung ist nicht nur String-Matching. OpenClaw normalisiert den Quellpfad und löst ihn dann erneut über den tiefsten vorhandenen Vorgänger auf, bevor blockierte Pfade und erlaubte Roots erneut geprüft werden.
• Das bedeutet, dass auch Escapes über Symlink-Eltern fail-closed bleiben, selbst wenn das endgültige Leaf noch nicht existiert. Beispiel: /workspace/run-link/new-file wird weiterhin als /var/run/... aufgelöst, wenn run-link dorthin zeigt.
• Erlaubte Quell-Roots werden auf dieselbe Weise kanonisiert, sodass ein Pfad, der nur vor der Symlink-Auflösung so aussieht, als läge er in der Allowlist, dennoch als outside allowed roots abgelehnt wird.
• Sensitive Mounts (Secrets, SSH-Schlüssel, Service-Credentials) sollten :ro sein, sofern es nicht absolut erforderlich ist.
• Kombinieren Sie dies mit workspaceAccess: "ro", wenn Sie nur Lesezugriff auf den Workspace benötigen; die Bind-Modi bleiben unabhängig.
• Siehe Sandbox vs Tool Policy vs Elevated, wie Binds mit Tool-Richtlinien und erhöhtem exec interagieren.

​

Images + Einrichtung

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --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 Flags zur Härtung der Grafik (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) sind optional und nützlich, wenn Container keine GPU-Unterstützung haben. Setzen Sie OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0, wenn Ihr 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 von Extensions abhängige Abläufe deaktiviert werden.
• --renderer-process-limit=2 wird über OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> gesteuert, wobei 0 den Standard von Chromium beibehält.

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

​

setupCommand (einmalige Container-Einrichtung)

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

• Standard docker.network ist "none" (kein Egress), daher schlagen Paketinstallationen fehl.
• docker.network: "container:<id>" erfordert dangerouslyAllowContainerNamespaceJoin: true und ist nur als Break-glass gedacht.
• readOnlyRoot: true verhindert Schreibvorgänge; setzen Sie readOnlyRoot: false oder erstellen Sie ein benutzerdefiniertes Image.
• user muss für Paketinstallationen root sein (lassen Sie user weg oder setzen Sie user: "0:0").
• Sandbox-exec erbt nicht das Host-process.env. Verwenden Sie agents.defaults.sandbox.docker.env (oder ein benutzerdefiniertes Image) für API-Schlüssel von Skills.

​

Tool-Richtlinien + Escape-Hatches

• 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 restriktiv.

​

Multi-Agent-Overrides

​

Minimales Aktivierungsbeispiel

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

​

Verwandte Dokumente

• OpenShell — Einrichtung des verwalteten Sandbox-Backends, Workspace-Modi und Konfigurationsreferenz
• Sandbox Configuration
• Sandbox vs Tool Policy vs Elevated — Debugging von „warum ist das blockiert?“
• Multi-Agent Sandbox & Tools — Overrides pro Agent und Priorität
• Security