Sandboxisolatie

OpenClaw kan tools binnen sandbox-backends uitvoeren om de blast radius te verkleinen. Dit is optioneel en wordt beheerd via configuratie (agents.defaults.sandbox of agents.list[].sandbox). Als sandboxing uit staat, draaien tools op de host. De Gateway blijft op de host; tooluitvoering draait in een geïsoleerde sandbox wanneer dit is ingeschakeld.

# Wat in de sandbox wordt uitgevoerd

• Tooluitvoering (exec, read, write, edit, apply_patch, process, enz.).
• Optionele gesandboxte browser (agents.defaults.sandbox.browser).

Niet in de sandbox uitgevoerd:

• Het Gateway-proces zelf.
• Elke tool die expliciet buiten de sandbox mag draaien (bijv. tools.elevated).
  • Elevated exec omzeilt sandboxing en gebruikt het geconfigureerde escape-pad (gateway standaard, of node wanneer het exec-target node is).
  • Als sandboxing uit staat, verandert tools.elevated de uitvoering niet (die draait al op de host). Zie Elevated Mode.

# Modi

agents.defaults.sandbox.mode bepaalt wanneer sandboxing wordt gebruikt:

# Bereik

agents.defaults.sandbox.scope bepaalt hoeveel containers er worden gemaakt:

• "agent" (standaard): één container per agent.
• "session": één container per sessie.
• "shared": één container gedeeld door alle gesandboxte sessies.

# Backend

agents.defaults.sandbox.backend bepaalt welke runtime de sandbox levert:

• "docker" (standaard wanneer sandboxing is ingeschakeld): lokale Docker-ondersteunde sandboxruntime.
• "ssh": generieke SSH-ondersteunde externe sandboxruntime.
• "openshell": OpenShell-ondersteunde sandboxruntime.

SSH-specifieke configuratie staat onder agents.defaults.sandbox.ssh. OpenShell-specifieke configuratie staat onder plugins.entries.openshell.config.

# Een backend kiezen

# Docker-backend

Sandboxing staat standaard uit. Als je sandboxing inschakelt en geen backend kiest, gebruikt OpenClaw de Docker-backend. Deze voert tools en sandboxbrowsers lokaal uit via de Docker-daemonsocket (/var/run/docker.sock). Isolatie van sandboxcontainers wordt bepaald door Docker-namespaces.

Om host-GPU's beschikbaar te maken voor Docker-sandboxes, stel je agents.defaults.sandbox.docker.gpus in of de per-agent override agents.list[].sandbox.docker.gpus. De waarde wordt als afzonderlijk argument doorgegeven aan Docker's --gpus-flag, bijvoorbeeld "all" of "device=GPU-uuid", en vereist een compatibele hostruntime zoals NVIDIA Container Toolkit.

# SSH-backend

Gebruik backend: "ssh" wanneer je wilt dat OpenClaw exec, bestandstools en medialezingen sandboxt op een willekeurige via SSH toegankelijke machine.

{
  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

Gebruik backend: "openshell" wanneer je wilt dat OpenClaw tools in een door OpenShell beheerde externe omgeving sandboxt. Zie de toegewezen OpenShell-pagina voor de volledige setupgids, configuratiereferentie en vergelijking van werkruimtemodi.

OpenShell hergebruikt hetzelfde kern-SSH-transport en dezelfde externe filesystem-bridge als de generieke SSH-backend, en voegt OpenShell-specifieke lifecycle toe (sandbox create/get/delete, sandbox ssh-config) plus de optionele mirror-werkruimtemodus.

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

OpenShell-modi:

• mirror (standaard): lokale werkruimte blijft canonical. OpenClaw synchroniseert lokale bestanden naar OpenShell vóór exec en synchroniseert de externe werkruimte terug na exec.
• remote: OpenShell-werkruimte is canonical nadat de sandbox is aangemaakt. OpenClaw seedt de externe werkruimte één keer vanuit de lokale werkruimte, waarna bestandstools en exec rechtstreeks tegen de externe sandbox draaien zonder wijzigingen terug te synchroniseren.

# Werkruimtemodi

OpenShell heeft twee werkruimtemodellen. Dit is in de praktijk het belangrijkste deel.

Kies mirror als je de sandbox ziet als een tijdelijke uitvoeringsomgeving. Kies remote als je de sandbox ziet als de echte werkruimte.

# OpenShell-levenscyclus

OpenShell-sandboxes worden nog steeds beheerd via de normale sandbox-levenscyclus:

• openclaw sandbox list toont zowel OpenShell-runtimes als Docker-runtimes
• openclaw sandbox recreate verwijdert de huidige runtime en laat OpenClaw deze bij het volgende gebruik opnieuw maken
• opschoonlogica is ook backend-bewust

Voor de modus remote is opnieuw maken extra belangrijk:

• opnieuw maken verwijdert de canonieke externe werkruimte voor dat bereik
• het volgende gebruik vult een nieuwe externe werkruimte vanuit de lokale werkruimte

Voor de modus mirror reset opnieuw maken vooral de externe uitvoeringsomgeving, omdat de lokale werkruimte toch canoniek blijft.

# Werkruimtetoegang

agents.defaults.sandbox.workspaceAccess bepaalt wat de sandbox kan zien:

Met de OpenShell-backend:

• de modus mirror gebruikt nog steeds de lokale werkruimte als de canonieke bron tussen exec-beurten
• de modus remote gebruikt na de initiële seed de externe OpenShell-werkruimte als de canonieke bron
• workspaceAccess: "ro" en "none" beperken schrijfgedrag nog steeds op dezelfde manier

Inkomende media worden gekopieerd naar de actieve sandbox-werkruimte (media/inbound/*).

# Aangepaste bind mounts

agents.defaults.sandbox.docker.binds koppelt extra hostmappen in de container. Formaat: host:container:mode (bijv. "/home/user/source:/source:rw").

Globale binds en binds per agent worden samengevoegd (niet vervangen). Onder scope: "shared" worden binds per agent genegeerd.

agents.defaults.sandbox.browser.binds koppelt extra hostmappen alleen in de sandboxbrowser-container.

• Wanneer ingesteld (inclusief []), vervangt dit agents.defaults.sandbox.docker.binds voor de browsercontainer.
• Wanneer weggelaten, valt de browsercontainer terug op agents.defaults.sandbox.docker.binds (achterwaarts compatibel).

Voorbeeld (alleen-lezen bron + een extra datamap):

{
  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 en setup

Standaard Docker-image: openclaw-sandbox:bookworm-slim

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

Standaard draaien Docker-sandboxcontainers met geen netwerk. Overschrijf dit met agents.defaults.sandbox.docker.network.

Docker-installaties en de gecontaineriseerde Gateway staan hier: Docker

Voor Docker Gateway-deployments kan scripts/docker/setup.sh sandboxconfiguratie bootstrappen. Stel OPENCLAW_SANDBOX=1 (of true/yes/on) in om dat pad in te schakelen. Je kunt de socketlocatie overschrijven met OPENCLAW_DOCKER_SOCKET. Volledige setup- en env-referentie: Docker.

# setupCommand (eenmalige container-setup)

setupCommand draait één keer nadat de sandboxcontainer is gemaakt (niet bij elke run). Het wordt in de container uitgevoerd via sh -lc.

Paden:

• Globaal: agents.defaults.sandbox.docker.setupCommand
• Per agent: agents.list[].sandbox.docker.setupCommand

# Toolbeleid en escape hatches

Tool-allow/deny-beleid blijft van toepassing vóór sandboxregels. Als een tool globaal of per agent wordt geweigerd, brengt sandboxing die niet terug.

tools.elevated is een expliciete escape hatch die exec buiten de sandbox uitvoert (standaard gateway, of node wanneer het exec-doel node is). /exec-richtlijnen gelden alleen voor geautoriseerde afzenders en blijven per sessie bestaan; gebruik tool policy deny om exec hard uit te schakelen (zie Sandbox vs Tool Policy vs Elevated).

Debuggen:

• Gebruik openclaw sandbox explain om de effectieve sandboxmodus, het toolbeleid en fix-it-configuratiesleutels te inspecteren.
• Zie Sandbox vs Tool Policy vs Elevated voor het mentale model achter "waarom wordt dit geblokkeerd?".

Houd het vergrendeld.

# Multi-agent-overschrijvingen

Elke agent kan sandbox + tools overschrijven: agents.list[].sandbox en agents.list[].tools (plus agents.list[].tools.sandbox.tools voor sandbox-toolbeleid). Zie Multi-Agent Sandbox & Tools voor prioriteit.

# Minimaal inschakelvoorbeeld

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

# Gerelateerd

• Multi-Agent Sandbox & Tools — overschrijvingen per agent en prioriteit
• OpenShell — beheerde sandbox-backendconfiguratie, werkruimtemodi en configuratiereferentie
• Sandboxconfiguratie
• Sandbox vs Tool Policy vs Elevated — debuggen van "waarom wordt dit geblokkeerd?"
• Beveiliging