Sandbox CLI

Docker-basierte Sandbox-Container für isolierte Agenten-Ausführung verwalten.

Überblick

OpenClaw kann Agenten in isolierten Docker-Containern für mehr Sicherheit ausführen. Die sandbox-Befehle helfen dir, diese Container zu verwalten, besonders nach Updates oder Konfigurationsänderungen.

Befehle

`openclaw sandbox explain`

Inspiziere den effektiven Sandbox-Modus/-Scope/-Workspace-Zugriff, die Sandbox-Tool-Richtlinie und erweiterte Gates (mit Fix-it-Konfigurations-Schlüsselpfaden).

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

`openclaw sandbox list`

Alle Sandbox-Container mit ihrem Status und ihrer Konfiguration auflisten.

openclaw sandbox list
openclaw sandbox list --browser  # Nur Browser-Container auflisten
openclaw sandbox list --json     # JSON-Ausgabe

Die Ausgabe enthält:

Containername und Status (laufend/gestoppt)
Docker-Image und ob es mit der Konfiguration übereinstimmt
Alter (Zeit seit der Erstellung)
Leerlaufzeit (Zeit seit der letzten Nutzung)
Zugehörige Sitzung/Agent

`openclaw sandbox recreate`

Sandbox-Container entfernen, um eine Neuerstellung mit aktualisierten Images/Konfiguration zu erzwingen.

openclaw sandbox recreate --all                # Alle Container neu erstellen
openclaw sandbox recreate --session main       # Bestimmte Sitzung
openclaw sandbox recreate --agent mybot        # Bestimmter Agent
openclaw sandbox recreate --browser            # Nur Browser-Container
openclaw sandbox recreate --all --force        # Bestätigung überspringen

Optionen:

--all: Alle Sandbox-Container neu erstellen
--session <key>: Container für eine bestimmte Sitzung neu erstellen
--agent <id>: Container für einen bestimmten Agenten neu erstellen
--browser: Nur Browser-Container neu erstellen
--force: Bestätigungsabfrage überspringen

Wichtig: Container werden automatisch neu erstellt, wenn der Agent das nächste Mal verwendet wird.

Anwendungsfälle

Nach dem Aktualisieren von Docker-Images

# Neues Image pullen
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Konfiguration aktualisieren, um das neue Image zu verwenden
# Konfiguration bearbeiten: agents.defaults.sandbox.docker.image (oder agents.list[].sandbox.docker.image)

# Container neu erstellen
openclaw sandbox recreate --all

Nach dem Ändern der Sandbox-Konfiguration

# Konfiguration bearbeiten: agents.defaults.sandbox.* (oder agents.list[].sandbox.*)

# Neu erstellen, um neue Konfiguration anzuwenden
openclaw sandbox recreate --all

Nach dem Ändern von setupCommand

openclaw sandbox recreate --all
# oder nur ein Agent:
openclaw sandbox recreate --agent family

Für einen bestimmten Agenten

# Nur die Container eines Agenten aktualisieren
openclaw sandbox recreate --agent alfred

Warum ist das nötig?

Problem: Wenn du Sandbox-Docker-Images oder -Konfiguration aktualisierst:

Bestehende Container laufen mit den alten Einstellungen weiter
Container werden erst nach 24 Stunden Inaktivität bereinigt
Regelmäßig genutzte Agenten behalten alte Container unbegrenzt

Lösung: Verwende openclaw sandbox recreate, um das Entfernen alter Container zu erzwingen. Sie werden automatisch mit den aktuellen Einstellungen neu erstellt, wenn sie das nächste Mal benötigt werden.

Tipp: Bevorzuge openclaw sandbox recreate gegenüber manuellem docker rm. Es verwendet die Gateway-Container-Benennung und vermeidet Diskrepanzen, wenn sich Scope/Session-Keys ändern.

Konfiguration

Sandbox-Einstellungen befinden sich in ~/.openclaw/openclaw.json unter agents.defaults.sandbox (agentenbezogene Überschreibungen unter agents.list[].sandbox):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... weitere Docker-Optionen
        },
        "prune": {
          "idleHours": 24, // Automatische Bereinigung nach 24h Leerlauf
          "maxAgeDays": 7, // Automatische Bereinigung nach 7 Tagen
        },
      },
    },
  },
}