Sandboxing

Agenten zur Sicherheit sandboxen. Tools und Workspace isolieren. OpenClaw kann Tools in Docker-Containern ausführen, um die Reichweite zu begrenzen. Das ist optional und wird über die Konfiguration gesteuert (agents.defaults.sandbox oder agents.list[].sandbox). Ist Sandboxing aus, laufen Tools auf dem Host. Der Gateway bleibt auf dem Host; die Tool-Ausführung läuft bei Aktivierung in einer isolierten Sandbox. Das ist keine perfekte Sicherheitsgrenze, begrenzt aber Dateisystem- und Prozesszugriff spürbar, wenn das Modell etwas Dummes tut.

Was gesandboxt wird

Tool-Ausführung (exec, read, write, edit, apply_patch, process usw.).
Optional gesandboxter Browser (agents.defaults.sandbox.browser).
- Standardmäßig startet der Sandbox-Browser automatisch (stellt CDP-Erreichbarkeit sicher), wenn das Browser-Tool ihn braucht. Konfiguration über agents.defaults.sandbox.browser.autoStart und agents.defaults.sandbox.browser.autoStartTimeoutMs.
- agents.defaults.sandbox.browser.allowHostControl erlaubt gesandboxten Sitzungen, den Host-Browser explizit anzusprechen.
- Optionale Allowlists steuern 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 Sandboxing.
- Ist Sandboxing aus, ändert tools.elevated die Ausführung nicht (läuft bereits auf dem Host). Siehe Elevated Mode.

Modi

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

"off": kein Sandboxing.
"non-main": nur **Nicht-Haupt-**Sitzungen sandboxen (Standard, wenn Sie normale Chats auf dem Host wollen).
"all": jede Sitzung läuft in einer Sandbox.

Hinweis: "non-main" basiert auf session.mainKey (Standard "main"), nicht auf der Agenten-ID. Gruppen-/Kanal-Sitzungen nutzen eigene Keys und gelten als non-main und werden gesandboxt.

Geltungsbereich

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

"session" (Standard): ein Container pro Sitzung.
"agent": ein Container pro Agent.
"shared": ein Container für alle gesandboxten Sitzungen.

Workspace-Zugriff

agents.defaults.sandbox.workspaceAccess steuert, was die Sandbox sieht:

"none" (Standard): Tools sehen einen Sandbox-Workspace unter ~/.clawdbot/sandboxes.
"ro": Agenten-Workspace read-only unter /agent einbinden (deaktiviert write/edit/apply_patch).
"rw": Agenten-Workspace lesend/schreibend unter /workspace einbinden.

Eingehende Medien werden in den aktiven Sandbox-Workspace kopiert (media/inbound/*). Hinweis Skills: Das read-Tool ist sandbox-rooted. Bei workspaceAccess: "none" spiegelt OpenClaw geeignete Skills in den Sandbox-Workspace (.../skills), damit sie lesbar sind. Bei "rw" sind Workspace-Skills unter /workspace/skills lesbar.

Benutzerdefinierte Bind-Mounts

agents.defaults.sandbox.docker.binds bindet zusätzliche Host-Verzeichnisse in den Container ein. Format: host:container:mode (z. B. "/home/user/source:/source:rw"). Globale und pro-Agent-Binds werden zusammengeführt (nicht ersetzt). Bei scope: "shared" werden pro-Agent-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 exponieren Host-Pfade mit der gesetzten Mode (:ro oder :rw).
Sensible Mounts (z. B. docker.sock, Geheimnisse, SSH-Keys) sollten :ro sein, außer unbedingt nötig.
Mit workspaceAccess: "ro" kombinieren, wenn Sie nur Lesezugriff auf den Workspace brauchen; Bind-Modi bleiben unabhängig.
Siehe Sandbox vs. Tool Policy vs. Elevated für die Wechselwirkung 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. Braucht ein Skill Node (oder andere Laufzeiten), entweder ein eigenes Image bauen oder über sandbox.docker.setupCommand installieren (erfordert Netz-Egress + beschreibbares Root + Root-User). Sandbox-Browser-Image:


scripts/sandbox-browser-setup.sh

Standardmäßig laufen Sandbox-Container ohne Netzwerk. Überschreiben mit agents.defaults.sandbox.docker.network. Docker-Installationen und der containerisierte Gateway: Docker.

setupCommand (einmalige Container-Einrichtung)

setupCommand läuft einmal nach Erstellung des Sandbox-Containers (nicht bei jedem Lauf). Ausführung im Container über sh -lc. Pfade:

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

Typische Fallstricke:

Standard docker.network ist "none" (kein Egress), Paketinstallationen schlagen fehl.
readOnlyRoot: true verhindert Schreibzugriff; readOnlyRoot: false setzen oder eigenes Image bauen.
user muss root sein für Paketinstallationen (user weglassen oder user: "0:0" setzen).
Sandbox-Exec erbt nicht die Host-process.env. Für Skill-API-Keys agents.defaults.sandbox.docker.env (oder eigenes Image) nutzen.

Tool-Policy + Fluchtluken

Tool-Allow-/Deny-Policies gelten weiterhin vor Sandbox-Regeln. Ist ein Tool global oder pro Agent verweigert, bringt Sandboxing es nicht zurück. tools.elevated ist eine explizite Fluchtluke, die exec auf dem Host ausführt. /exec-Direktiven gelten nur für autorisierte Absender und pro Sitzung; für harte Deaktivierung von exec Tool-Policy deny nutzen (siehe Sandbox vs. Tool Policy vs. Elevated). Debugging:

openclaw sandbox explain nutzen, um effektiven Sandbox-Modus, Tool-Policy und Fix-it-Konfigurationsschlüssel zu prüfen.
Siehe Sandbox vs. Tool Policy vs. Elevated für das mentale Modell „Warum ist das blockiert?“.
Zugriff gering halten.

Pro-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). Vorrang: Multi-Agent Sandbox & Tools.

Minimales Aktivierungsbeispiel


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