OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Sandbox-CLI

Status: active

Verwalten Sie Sandbox-Laufzeitumgebungen für die isolierte Agent-Ausführung: Docker-Container, SSH-Ziele oder OpenShell-Backends.

Befehle

openclaw sandbox list

Listet Sandbox-Laufzeitumgebungen mit Status, Backend, Konfigurationsübereinstimmung, Alter, Leerlaufzeit und zugehöriger Sitzung bzw. zugehörigem Agent auf.

bash
openclaw sandbox listopenclaw sandbox list --browser  # nur Browser-Containeropenclaw sandbox list --json

openclaw sandbox recreate

Entfernt Sandbox-Laufzeitumgebungen, um deren Neuerstellung mit der aktuellen Konfiguration zu erzwingen. Die Laufzeitumgebungen werden automatisch neu erstellt, wenn der Agent das nächste Mal verwendet wird.

bash
openclaw sandbox recreate --allopenclaw sandbox recreate --agent mybot        # schließt Untersitzungen vom Typ agent:mybot:* einopenclaw sandbox recreate --session "agent:main:main"openclaw sandbox recreate --browser --all      # nur Browser-Containeropenclaw sandbox recreate --all --force        # Bestätigung überspringen

Optionen:

  • --all: alle Sandbox-Container neu erstellen
  • --session <key>: die Laufzeitumgebung mit diesem exakten Bereichsschlüssel neu erstellen (wie von sandbox list angezeigt); keine Erweiterung von Kurznamen
  • --agent <id>: Laufzeitumgebungen für einen Agent neu erstellen (entspricht agent:<id> und agent:<id>:*)
  • --browser: nur Browser-Container betreffen
  • --force: Bestätigungsabfrage überspringen

Übergeben Sie genau eine der Optionen --all, --session oder --agent.

Bei ssh und OpenShell remote ist die Neuerstellung wichtiger als bei Docker: Nach der anfänglichen Befüllung ist der entfernte Arbeitsbereich maßgeblich, recreate löscht diesen maßgeblichen entfernten Arbeitsbereich für den ausgewählten Bereich, und beim nächsten Lauf wird er aus dem aktuellen lokalen Arbeitsbereich neu befüllt.

openclaw sandbox explain

Prüft den effektiven Sandbox-Modus und -Bereich, den Arbeitsbereichszugriff, die Richtlinie für Sandbox-Werkzeuge und die Schranken für Werkzeuge mit erhöhten Rechten (einschließlich Konfigurationsschlüsselpfaden zur Behebung).

Der Bericht behält workspaceRoot als konfiguriertes Sandbox-Stammverzeichnis bei und zeigt separat den effektiven Host-Arbeitsbereich, das Arbeitsverzeichnis der Backend-Laufzeitumgebung und die Docker-Einhängetabelle an. Bei workspaceAccess: "rw" ist der effektive Host-Arbeitsbereich der Agent-Arbeitsbereich und kein Verzeichnis unterhalb von workspaceRoot.

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Anders als recreate --session akzeptiert dieser Befehl kurze Sitzungsnamen (beispielsweise main) und erweitert sie anhand des aufgelösten Agent.

Warum eine Neuerstellung erforderlich ist

Das Aktualisieren der Sandbox-Konfiguration wirkt sich nicht auf laufende Container aus: Bestehende Laufzeitumgebungen behalten ihre alten Einstellungen bei, und inaktive Laufzeitumgebungen werden erst nach prune.idleHours bereinigt (standardmäßig 24h). Regelmäßig verwendete Agents können veraltete Laufzeitumgebungen unbegrenzt aktiv halten. openclaw sandbox recreate entfernt die alte Laufzeitumgebung, sodass sie bei der nächsten Verwendung anhand der aktuellen Konfiguration neu erstellt wird.

Häufige Auslöser

Änderung Befehl
Docker-Image-Aktualisierung (agents.defaults.sandbox.docker.image) openclaw sandbox recreate --all
Sandbox-Konfiguration (agents.defaults.sandbox.*) openclaw sandbox recreate --all
SSH-Ziel/Authentifizierung (agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}) openclaw sandbox recreate --all
OpenShell-Quelle/-Richtlinie/-Modus (plugins.entries.openshell.config.{from,mode,policy}) openclaw sandbox recreate --all
setupCommand openclaw sandbox recreate --all (oder --agent <id> für einen Agent)

Registrierungsmigration

Die Metadaten der Sandbox-Laufzeitumgebungen befinden sich in der gemeinsam genutzten SQLite-Zustandsdatenbank. Ältere Installationen können veraltete Registrierungsdateien enthalten, die bei regulären Lesevorgängen nicht mehr neu geschrieben werden:

  • ~/.openclaw/sandbox/containers.json
  • ~/.openclaw/sandbox/browsers.json
  • ein JSON-Fragment pro Container/Browser unter ~/.openclaw/sandbox/containers/ oder ~/.openclaw/sandbox/browsers/

Führen Sie openclaw doctor --fix aus, um gültige veraltete Einträge nach SQLite zu migrieren. Ungültige veraltete Dateien werden unter Quarantäne gestellt, damit eine beschädigte alte Registrierung keine aktuellen Laufzeitumgebungseinträge verbergen kann.

Konfiguration

Die Sandbox-Einstellungen befinden sich in ~/.openclaw/openclaw.json unter agents.defaults.sandbox (Agent-spezifische Überschreibungen werden in agents.entries.*.sandbox eingetragen):

jsonc
{  "agents": {    "defaults": {      "sandbox": {        "mode": "all", // aus, nicht Haupt-Agent, alle        "backend": "docker", // docker, ssh, openshell (von Plugin bereitgestellt)        "scope": "agent", // Sitzung, Agent, gemeinsam        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "containerPrefix": "openclaw-sbx-",          // ... weitere Docker-Optionen        },        "prune": {          "idleHours": 24, // nach 24h Leerlauf automatisch bereinigen          "maxAgeDays": 7, // nach 7 Tagen automatisch bereinigen        },      },    },  },}

Verwandte Themen

Was this useful?
On this page

On this page