Sandbox-Isolierung

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Was in der Sandbox ausgeführt wird

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

• Der Gateway-Prozess selbst.
• Jedes Tool, dem ausdrücklich erlaubt wurde, außerhalb der Sandbox zu laufen (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 ausgeschaltet ist, ändert tools.elevated die Ausführung nicht (bereits auf dem Host). Siehe Elevated Mode.

​

Modi

​

Geltungsbereich

• "agent" (Standard): ein Container pro Agent.
• "session": ein Container pro Sitzung.
• "shared": ein Container, der von allen sandboxed Sitzungen gemeinsam genutzt wird.

​

Backend

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

​

Ein Backend auswählen

​

Docker-Backend

​

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",
          // 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

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

• 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 initialisiert 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-Lebenszyklus

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

• Neuerstellen löscht den kanonischen entfernten Arbeitsbereich für diesen Scope
• die nächste Verwendung initialisiert einen frischen entfernten Arbeitsbereich aus dem lokalen Arbeitsbereich

​

Arbeitsbereichszugriff

• Der Modus mirror verwendet weiterhin den lokalen Arbeitsbereich als kanonische Quelle zwischen exec-Turns
• Der Modus remote verwendet den entfernten OpenShell-Arbeitsbereich nach der anfänglichen Initialisierung als kanonische Quelle
• workspaceAccess: "ro" und "none" schränken Schreibverhalten weiterhin auf dieselbe Weise ein

​

Benutzerdefinierte Bind-Mounts

• 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).

{
  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.list[].sandbox.docker.setupCommand

​

Tool-Richtlinie und Notfallwege

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

​

Multi-Agent-Overrides

​

Minimales Aktivierungsbeispiel

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

​

Verwandt

• Multi-Agent Sandbox & Tools — Overrides pro Agent und Rangfolge
• 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