English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

Sandbox-CLI

Sandbox-Laufzeitumgebungen für isolierte Agent-Ausführung verwalten.

Überblick

OpenClaw kann Agents aus Sicherheitsgründen in isolierten Sandbox-Laufzeitumgebungen ausführen. Die sandbox-Befehle helfen Ihnen, diese Laufzeitumgebungen nach Updates oder Konfigurationsänderungen zu prüfen und neu zu erstellen.

Derzeit bedeutet das in der Regel:

  • Docker-Sandbox-Container
  • SSH-Sandbox-Laufzeitumgebungen, wenn agents.defaults.sandbox.backend = "ssh"
  • OpenShell-Sandbox-Laufzeitumgebungen, wenn agents.defaults.sandbox.backend = "openshell"

Für ssh und OpenShell remote ist das Neuerstellen wichtiger als bei Docker:

  • Der Remote-Arbeitsbereich ist nach dem initialen Seed maßgeblich
  • openclaw sandbox recreate löscht diesen maßgeblichen Remote-Arbeitsbereich für den ausgewählten Geltungsbereich
  • Bei der nächsten Verwendung wird er erneut aus dem aktuellen lokalen Arbeitsbereich befüllt

Befehle

openclaw sandbox explain

Prüfen Sie den effektiven Sandbox-Modus, Geltungsbereich, Arbeitsbereichszugriff, die Sandbox-Tool-Richtlinie und erhöhte Gates (mit Fix-it-Konfigurationsschlüsselpfaden).

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

openclaw sandbox list

Listet alle Sandbox-Laufzeitumgebungen mit Status und Konfiguration auf.

openclaw sandbox list
openclaw sandbox list --browser  # List only browser containers
openclaw sandbox list --json     # JSON output

Ausgabe enthält:

  • Name und Status der Laufzeitumgebung
  • Backend (docker, openshell usw.)
  • Konfigurationslabel und ob es mit der aktuellen Konfiguration übereinstimmt
  • Alter (Zeit seit Erstellung)
  • Leerlaufzeit (Zeit seit letzter Verwendung)
  • Zugeordnete Session/zugeordneter Agent

openclaw sandbox recreate

Entfernt Sandbox-Laufzeitumgebungen, um eine Neuerstellung mit aktualisierter Konfiguration zu erzwingen.

openclaw sandbox recreate --all                # Recreate all containers
openclaw sandbox recreate --session main       # Specific session
openclaw sandbox recreate --agent mybot        # Specific agent
openclaw sandbox recreate --browser            # Only browser containers
openclaw sandbox recreate --all --force        # Skip confirmation

Optionen:

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

Anwendungsfälle

Nach dem Aktualisieren eines Docker-Images

# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)

# Recreate containers
openclaw sandbox recreate --all

Nach dem Ändern der Sandbox-Konfiguration

# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)

# Recreate to apply new config
openclaw sandbox recreate --all

Nach dem Ändern des SSH-Ziels oder des SSH-Authentifizierungsmaterials

# Edit config:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData

openclaw sandbox recreate --all

Für das Core-Backend ssh löscht das Neuerstellen das Remote-Arbeitsbereichs-Root pro Geltungsbereich auf dem SSH-Ziel. Der nächste Lauf befüllt ihn erneut aus dem lokalen Arbeitsbereich.

Nach dem Ändern von OpenShell-Quelle, Richtlinie oder Modus

# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy

openclaw sandbox recreate --all

Im OpenShell-remote-Modus löscht das Neuerstellen den maßgeblichen Remote-Arbeitsbereich für diesen Geltungsbereich. Der nächste Lauf befüllt ihn erneut aus dem lokalen Arbeitsbereich.

Nach dem Ändern von setupCommand

openclaw sandbox recreate --all
# or just one agent:
openclaw sandbox recreate --agent family

Nur für einen bestimmten Agent

# Update only one agent's containers
openclaw sandbox recreate --agent alfred

Warum dies erforderlich ist

Wenn Sie die Sandbox-Konfiguration aktualisieren:

  • Vorhandene Laufzeitumgebungen laufen mit alten Einstellungen weiter.
  • Laufzeitumgebungen werden erst nach 24 Stunden Inaktivität bereinigt.
  • Regelmäßig verwendete Agents halten alte Laufzeitumgebungen unbegrenzt aktiv.

Verwenden Sie openclaw sandbox recreate, um das Entfernen alter Laufzeitumgebungen zu erzwingen. Sie werden bei Bedarf automatisch mit den aktuellen Einstellungen neu erstellt.

Registry-Migration

OpenClaw speichert Metadaten zu Sandbox-Laufzeitumgebungen als einen JSON-Shard pro Container-/Browser-Eintrag im Sandbox-Statusverzeichnis. Ältere Installationen haben möglicherweise noch monolithische Legacy-Dateien:

  • ~/.openclaw/sandbox/containers.json
  • ~/.openclaw/sandbox/browsers.json

Reguläre Lesevorgänge für Sandbox-Laufzeitumgebungen schreiben diese Dateien nicht neu. Führen Sie openclaw doctor --fix aus, um gültige Legacy-Einträge in die geshardeten Registry-Verzeichnisse zu migrieren. Ungültige Legacy-Dateien werden unter Quarantäne gestellt, damit eine fehlerhafte alte Registry keine aktuellen Laufzeiteinträge verbergen kann.

Konfiguration

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

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, ssh, openshell
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // Auto-prune after 24h idle
          "maxAgeDays": 7, // Auto-prune after 7 days
        },
      },
    },
  },
}

Verwandte Themen