Sandboxing

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

# Was in die Sandbox verschoben wird

• Tool-Ausführung (exec, read, write, edit, apply_patch, process usw.).
• Optionaler Sandbox-Browser (agents.defaults.sandbox.browser).

Nicht in der Sandbox:

• Der Gateway-Prozess selbst.
• Jedes Tool, das ausdrücklich außerhalb der Sandbox ausgeführt werden darf (z. B. tools.elevated).
  • Elevated 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 (sie läuft bereits auf dem Host). Siehe Elevated Mode.

# Modi

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

# Geltungsbereich

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

• "agent" (Standard): ein Container pro Agent.
• "session": ein Container pro Sitzung.
• "shared": ein Container, den alle Sandbox-Sitzungen gemeinsam nutzen.

# Backend

agents.defaults.sandbox.backend steuert, welche Laufzeitumgebung die Sandbox bereitstellt:

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

SSH-spezifische Konfiguration befindet sich unter agents.defaults.sandbox.ssh. OpenShell-spezifische Konfiguration befindet sich unter plugins.entries.openshell.config.

# Backend auswählen

# Docker-Backend

Sandboxing ist standardmäßig deaktiviert. Wenn Sie Sandboxing aktivieren und kein Backend auswählen, verwendet OpenClaw das Docker-Backend. Es führt Tools und Sandbox-Browser lokal über den Docker-Daemon-Socket (/var/run/docker.sock) aus. Die Isolation von Sandbox-Containern wird durch Docker-Namespaces bestimmt.

Um Host-GPUs für Docker-Sandboxes verfügbar zu machen, setzen Sie agents.defaults.sandbox.docker.gpus oder die agentenspezifische Überschreibung agents.list[].sandbox.docker.gpus. Der Wert wird als separates Argument an Dockers --gpus-Flag übergeben, zum Beispiel "all" oder "device=GPU-uuid", und erfordert eine kompatible Host-Laufzeitumgebung wie NVIDIA Container Toolkit.

# SSH-Backend

Verwenden Sie backend: "ssh", wenn OpenClaw exec, Datei-Tools und Medienlesevorgänge auf einer beliebigen per SSH erreichbaren Maschine in einer Sandbox ausführen soll.

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

# OpenShell-Backend

Verwenden Sie backend: "openshell", wenn OpenClaw Tools in einer von OpenShell verwalteten Remote-Umgebung in einer Sandbox ausführen soll. Den vollständigen Einrichtungsleitfaden, die Konfigurationsreferenz und den Vergleich der Workspace-Modi finden Sie auf der dedizierten OpenShell-Seite.

OpenShell verwendet denselben zentralen SSH-Transport und dieselbe Remote-Dateisystem-Bridge wie das generische SSH-Backend wieder und ergänzt OpenShell-spezifischen Lebenszyklus (sandbox create/get/delete, sandbox ssh-config) sowie den optionalen mirror-Workspace-Modus.

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

OpenShell-Modi:

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

# Workspace-Modi

OpenShell hat zwei Workspace-Modelle. Dies ist der Teil, der in der Praxis am wichtigsten ist.

Wählen Sie mirror, wenn Sie die Sandbox als temporäre Ausführungsumgebung betrachten. Wählen Sie remote, wenn Sie die Sandbox als den echten Workspace betrachten.

# OpenShell-Lebenszyklus

OpenShell-Sandboxes werden weiterhin über den normalen Sandbox-Lebenszyklus verwaltet:

• openclaw sandbox list zeigt OpenShell-Runtimes ebenso wie Docker-Runtimes
• openclaw sandbox recreate löscht die aktuelle Runtime und lässt OpenClaw sie bei der nächsten Verwendung neu erstellen
• die Bereinigungslogik ist ebenfalls backend-bewusst

Für den Modus remote ist das Neuerstellen besonders wichtig:

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

Für den Modus mirror setzt das Neuerstellen vor allem die Remote-Ausführungsumgebung zurück, weil der lokale Workspace ohnehin kanonisch bleibt.

# Workspace-Zugriff

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

Mit dem OpenShell-Backend:

• der Modus mirror verwendet weiterhin den lokalen Workspace als kanonische Quelle zwischen exec-Durchläufen
• der Modus remote verwendet nach der anfänglichen Befüllung den Remote-OpenShell-Workspace als kanonische Quelle
• workspaceAccess: "ro" und "none" beschränken Schreibverhalten weiterhin auf dieselbe Weise

Eingehende Medien werden in den aktiven Sandbox-Workspace kopiert (media/inbound/*).

# 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 agentenspezifische Binds werden zusammengeführt (nicht ersetzt). Unter scope: "shared" werden agentenspezifische Binds ignoriert.

agents.defaults.sandbox.browser.binds bindet zusätzliche Host-Verzeichnisse nur in den Sandbox-Browser-Container ein.

• Wenn gesetzt (einschließlich []), ersetzt es agents.defaults.sandbox.docker.binds für den Browser-Container.
• Wenn weggelassen, fällt 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"],
          },
        },
      },
    ],
  },
}

# Images und Einrichtung

Standard-Docker-Image: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  bash ca-certificates curl git jq python3 ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Standardmäßig laufen Docker-Sandbox-Container mit keinem Netzwerk. Überschreiben Sie dies mit agents.defaults.sandbox.docker.network.

Docker-Installationen und das containerisierte Gateway finden Sie hier: Docker

Für Docker-Gateway-Deployments kann scripts/docker/setup.sh die Sandbox-Konfiguration bootstrappen. Setzen Sie OPENCLAW_SANDBOX=1 (oder true/yes/on), um diesen Pfad zu aktivieren. Sie können den Socket-Speicherort mit OPENCLAW_DOCKER_SOCKET überschreiben. Vollständige Einrichtungs- und Env-Referenz: Docker.

# setupCommand (einmalige Container-Einrichtung)

setupCommand wird einmal ausgeführt, nachdem der Sandbox-Container erstellt wurde (nicht bei jedem Lauf). Es wird im Container über sh -lc ausgeführt.

Pfade:

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

# Tool-Richtlinie und Escape Hatches

Tool-Allow/Deny-Richtlinien gelten weiterhin vor Sandbox-Regeln. Wenn ein Tool global oder pro Agent verweigert wird, aktiviert Sandboxing es nicht wieder.

tools.elevated ist ein expliziter Escape Hatch, der exec außerhalb der Sandbox ausführt (standardmäßig gateway, oder node, wenn das Exec-Ziel node ist). /exec-Direktiven gelten nur für autorisierte Absender und bleiben pro Sitzung bestehen; um exec hart zu deaktivieren, verwenden Sie eine Tool-Richtlinie mit Deny (siehe Sandbox vs Tool Policy vs Elevated).

Debugging:

• Verwenden Sie openclaw sandbox explain, um den wirksamen Sandbox-Modus, die Tool-Richtlinie und Fix-it-Konfigurationsschlüssel zu prüfen.
• Siehe Sandbox vs Tool Policy vs Elevated für das mentale Modell zu „Warum ist das blockiert?“.

Halten Sie es abgeriegelt.

# Multi-Agent-Overrides

Jeder Agent kann Sandbox + Tools überschreiben: agents.list[].sandbox und agents.list[].tools (plus agents.list[].tools.sandbox.tools für die Sandbox-Tool-Richtlinie). Siehe Multi-Agent Sandbox & Tools für die Vorrangregeln.

# Minimales Aktivierungsbeispiel

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

# Verwandte Themen

• Multi-Agent Sandbox & Tools — Overrides pro Agent und Vorrangregeln
• OpenShell — Einrichtung des verwalteten Sandbox-Backends, Workspace-Modi und Konfigurationsreferenz
• Sandbox-Konfiguration
• Sandbox vs Tool Policy vs Elevated — Debugging zu „Warum ist das blockiert?“
• Sicherheit