Sandboxing

​

Was in der Sandbox ausgeführt wird

• Werkzeugausführung: exec, read, write, edit, apply_patch, process usw.
• Der optionale Browser in der Sandbox (agents.defaults.sandbox.browser).

• Der Gateway-Prozess selbst.
• Jedes Werkzeug, das über tools.elevated ausdrücklich für die Ausführung außerhalb der Sandbox zugelassen ist. Die Ausführung mit erhöhten Rechten umgeht das Sandboxing und erfolgt über den konfigurierten Ausweichpfad (standardmäßig gateway oder node, wenn das Ausführungsziel node ist). Wenn Sandboxing deaktiviert ist, ändert tools.elevated nichts, da die Ausführung bereits auf dem Host erfolgt. Siehe Modus mit erhöhten Rechten.

​

Modi, Geltungsbereich und Backend

• off: kein Sandboxing.
• non-main: Jede Sitzung mit Ausnahme der Hauptsitzung des Agenten wird in einer Sandbox ausgeführt. Der Schlüssel der Hauptsitzung ist immer agent:<agentId>:main (oder global, wenn session.scope den Wert "global" hat); er ist nicht konfigurierbar. Gruppen-/Kanalsitzungen verwenden eigene Schlüssel, gelten daher immer als Nicht-Hauptsitzungen und werden in einer Sandbox ausgeführt.
• all: Jede Sitzung wird in einer Sandbox ausgeführt.

• agent: ein Container pro Agent.
• session: ein Container pro Sitzung.
• shared: ein von allen Sandbox-Sitzungen gemeinsam genutzter Container (agentenspezifische Überschreibungen von docker/ssh/browser werden in diesem Geltungsbereich ignoriert).

​

Docker-Backend

​

Browser in der Sandbox

• Der Sandbox-Browser wird automatisch gestartet (wodurch die Erreichbarkeit von CDP sichergestellt wird), wenn das Browser-Werkzeug ihn benötigt. Die Konfiguration erfolgt über agents.defaults.sandbox.browser.autoStart (Standardwert true) und autoStartTimeoutMs (Standardwert 12s).
• Sandbox-Browser-Container verwenden anstelle des globalen Netzwerks bridge ein dediziertes Docker-Netzwerk (openclaw-sandbox-browser). Die Konfiguration erfolgt über agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange beschränkt den CDP-Zugriff am Container-Rand mit einer CIDR-Zulassungsliste (zum Beispiel 172.21.0.1/32).
• Der noVNC-Beobachterzugriff ist standardmäßig passwortgeschützt. OpenClaw gibt eine kurzlebige Token-URL aus, die eine lokale Bootstrap-Seite bereitstellt und noVNC mit dem Passwort im URL-Fragment öffnet (nicht in der Abfragezeichenfolge oder in Header-Protokollen).
• agents.defaults.sandbox.browser.allowHostControl (Standardwert false) ermöglicht Sandbox-Sitzungen, ausdrücklich den Host-Browser als Ziel zu verwenden.
• Optionale Zulassungslisten beschränken target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

​

SSH-Backend

{
  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",
          // Oder verwenden Sie SecretRefs/Inline-Inhalte anstelle lokaler Dateien:
          // 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" },
        },
      },
    },
  },
}

• Lebenszyklus: OpenClaw erstellt unter sandbox.ssh.workspaceRoot ein Remote-Stammverzeichnis pro Geltungsbereich. Bei der ersten Verwendung nach dem Erstellen oder Neuerstellen wird dieser Remote-Workspace einmalig mit dem lokalen Workspace initialisiert. Danach werden exec, read, write, edit, apply_patch, das Lesen von Prompt-Medien und die Bereitstellung eingehender Medien über SSH direkt im Remote-Workspace ausgeführt. OpenClaw synchronisiert Remote-Änderungen nicht automatisch zurück in den lokalen Workspace.
• Authentifizierungsmaterial: identityFile/certificateFile/knownHostsFile verweisen auf vorhandene lokale Dateien. identityData/certificateData/knownHostsData akzeptieren Inline-Zeichenfolgen oder SecretRefs, die über den normalen Laufzeit-Snapshot für Geheimnisse aufgelöst, mit dem Modus 0600 in temporäre Dateien geschrieben und beim Ende der SSH-Sitzung gelöscht werden. Wenn für dasselbe Element sowohl eine *File- als auch eine *Data-Variante festgelegt ist, hat *Data für diese Sitzung Vorrang.
• Folgen des Remote-kanonischen Modells: Nach der anfänglichen Initialisierung wird der Remote-SSH-Workspace zum tatsächlichen Sandbox-Zustand. Nach dem Initialisierungsschritt außerhalb von OpenClaw vorgenommene lokale Host-Änderungen sind remote erst sichtbar, wenn Sie die Sandbox neu erstellen. openclaw sandbox recreate löscht das Remote-Stammverzeichnis des jeweiligen Geltungsbereichs und initialisiert es bei der nächsten Verwendung erneut aus der lokalen Umgebung. Browser-Sandboxing wird von diesem Backend nicht unterstützt und die Einstellungen unter sandbox.docker.* gelten dafür nicht.

​

OpenShell-Backend

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // spiegeln | remote
        },
      },
    },
  },
}

​

Zugriff auf den Arbeitsbereich

​

Mehrere Ordner für einen Agenten

host-directory:container-directory:ro
host-directory:container-directory:rw

• ro macht den eingebundenen Ordner innerhalb der Sandbox schreibgeschützt.
• rw erlaubt Tools und Prozessen in der Sandbox, den Host-Ordner zu ändern.
• Der Container-Pfad ist der Pfad, den der Agent verwendet. Host-Pfade werden nicht automatisch offengelegt.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Erforderlich, da sich diese Quellen außerhalb des Agenten-Arbeitsbereichs befinden.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

​

Weiteres Verhalten von Bind-Einbindungen

{
  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

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

​

setupCommand (einmalige Container-Einrichtung)

• Global: agents.defaults.sandbox.docker.setupCommand
• Pro Agent: agents.entries.*.sandbox.docker.setupCommand

​

Tool-Richtlinien und Ausweichmöglichkeiten

• openclaw sandbox list zeigt Sandbox-Container, Status, Image-Übereinstimmung, Alter, Leerlaufzeit und die zugehörige Sitzung bzw. den zugehörigen Agenten an.
• openclaw sandbox explain [--session <key>] [--agent <id>] prüft den effektiven Sandbox-Modus, den Host-Arbeitsbereich, das Laufzeit-Arbeitsverzeichnis, Docker-Einbindungen, Tool-Richtlinien und Konfigurationsschlüssel zur Problembehebung. Das Feld workspaceRoot enthält weiterhin das konfigurierte Sandbox-Stammverzeichnis; effectiveHostWorkspaceRoot zeigt, wo sich der aktive Arbeitsbereich tatsächlich befindet.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] entfernt Container/Umgebungen, damit sie bei der nächsten Verwendung mit der aktuellen Konfiguration neu erstellt werden.
• Unter Sandbox im Vergleich zu Tool-Richtlinien und erhöhten Berechtigungen finden Sie ein Denkmodell für die Frage „Warum ist dies blockiert?“.

​

Überschreibungen für mehrere Agenten

​

Minimales Aktivierungsbeispiel

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

​

Verwandte Themen

• Sandbox und Tools für mehrere Agenten — Überschreibungen pro Agent und Rangfolge
• OpenShell — Einrichtung des verwalteten Sandbox-Backends, Arbeitsbereichsmodi und Konfigurationsreferenz
• Sandbox-Konfiguration
• Sandbox im Vergleich zu Tool-Richtlinien und erhöhten Berechtigungen — Fehlerdiagnose für „Warum ist dies blockiert?“
• Sicherheit