Sandboxing

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

Das ist keine perfekte Sicherheitsgrenze, aber es schränkt Dateisystem- und Prozesszugriff deutlich ein, wenn das Modell mal etwas Dummes macht.

Was wird gesandboxt

Tool-Ausführung (exec, read, write, edit, apply_patch, process, etc.).
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. Konfiguriere das über agents.defaults.sandbox.browser.autoStart und agents.defaults.sandbox.browser.autoStartTimeoutMs.
- agents.defaults.sandbox.browser.allowHostControl erlaubt Sandbox-Sessions, explizit den Host-Browser anzusteuern.
- Optionale Allowlists für target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Nicht gesandboxt:

Der Gateway-Prozess selbst.
Jedes Tool, das explizit auf dem Host laufen darf (z.B. tools.elevated).
- Elevated exec läuft auf dem Host und umgeht das Sandboxing.
- Wenn Sandboxing deaktiviert ist, ändert tools.elevated nichts (läuft eh schon auf dem Host). Siehe Elevated Mode.

Modi

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

"off": kein Sandboxing.
"non-main": nur Nicht-Main-Sessions werden gesandboxt (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 nutzen eigene Keys, zählen also als Nicht-Main und werden gesandboxt.

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 gesandboxten Sessions gemeinsam.

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/*). Hinweis zu Skills: Das read-Tool ist auf die Sandbox beschränkt. Mit workspaceAccess: "none" spiegelt OpenClaw berechtigte Skills in den Sandbox-Workspace (.../skills), damit sie gelesen werden können. Mit "rw" sind Workspace-Skills unter /workspace/skills lesbar.

Eigene 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 Agent-spezifische Binds werden zusammengeführt (nicht ersetzt). Bei scope: "shared" werden Agent-spezifische Binds ignoriert.

Beispiel (read-only Source + Docker Socket):

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

Sicherheitshinweise:

Binds umgehen das Sandbox-Dateisystem: sie legen Host-Pfade mit dem von dir gesetzten Modus offen (:ro oder :rw).
Sensible Mounts (z.B. docker.sock, Secrets, SSH-Keys) sollten :ro sein, außer es ist unbedingt nötig.
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 das Zusammenspiel von Binds mit Tool Policy und Elevated Exec.

Images + Setup

Standard-Image: openclaw-sandbox:bookworm-slim

Einmal bauen:

scripts/sandbox-setup.sh

Hinweis: Das Standard-Image enthält kein Node. Wenn ein Skill Node (oder andere Runtimes) braucht, bau entweder ein eigenes Image oder installiere über sandbox.docker.setupCommand (erfordert Netzwerkzugang + beschreibbares Root + Root-User).

Sandbox-Browser-Image:

scripts/sandbox-browser-setup.sh

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

Docker-Installation und der containerisierte Gateway findest du hier: Docker

setupCommand (einmalige Container-Einrichtung)

setupCommand läuft einmal nach dem Erstellen des Sandbox-Containers (nicht bei jedem Start). Es wird im Container über sh -lc ausgeführt.

Pfade:

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

Häufige Stolperfallen:

Standard docker.network ist "none" (kein Netzwerk), daher schlagen Paketinstallationen fehl.
readOnlyRoot: true verhindert Schreibzugriffe; setze readOnlyRoot: false oder bau ein eigenes Image.
user muss root sein für Paketinstallationen (lass user weg oder setze user: "0:0").
Sandbox-Exec erbt nicht die Host-process.env. Nutze agents.defaults.sandbox.docker.env (oder ein eigenes Image) für Skill-API-Keys.

Tool Policy + Escape Hatches

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

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

Debugging:

Nutze openclaw sandbox explain, um den effektiven Sandbox-Modus, Tool Policy und Fix-it-Config-Keys zu prüfen.
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 Prioritätsreihenfolge.

Minimales Aktivierungsbeispiel

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