Sandboxing

OpenClaw kan tooluitvoering binnen een sandboxbackend uitvoeren om de impact te beperken. Sandboxing is standaard uitgeschakeld en wordt geregeld via agents.defaults.sandbox (globaal) of agents.list[].sandbox (per agent). Het Gateway-proces blijft altijd op de host; alleen de tooluitvoering wordt naar de sandbox verplaatst wanneer deze is ingeschakeld.

Wat in de sandbox wordt uitgevoerd

• Tooluitvoering: exec, read, write, edit, apply_patch, process, enzovoort.
• De optionele browser in de sandbox (agents.defaults.sandbox.browser).

Niet in de sandbox uitgevoerd:

• Het Gateway-proces zelf.
• Elke tool die via tools.elevated expliciet buiten de sandbox mag worden uitgevoerd. Uitvoering met verhoogde rechten omzeilt sandboxing en gebruikt het geconfigureerde ontsnappingspad (standaard gateway, of node wanneer het uitvoeringsdoel node is). Als sandboxing is uitgeschakeld, verandert tools.elevated niets, omdat de uitvoering al op de host plaatsvindt. Zie Modus met verhoogde rechten.

Modi, bereik en backend

Drie onafhankelijke instellingen bepalen het sandboxgedrag:

Modus bepaalt wanneer sandboxing van toepassing is:

• off: geen sandboxing.
• non-main: voer elke sessie behalve de hoofdsessie van de agent in een sandbox uit. De sleutel van de hoofdsessie is altijd agent:<agentId>:main (of global wanneer session.scope "global" is); deze is niet configureerbaar. Groeps- en kanaalsessies gebruiken hun eigen sleutels, gelden dus altijd als niet-hoofdsessies en worden in een sandbox uitgevoerd.
• all: elke sessie wordt in een sandbox uitgevoerd.

Bereik bepaalt hoeveel containers/omgevingen worden gemaakt:

• agent: één container per agent.
• session: één container per sessie.
• shared: één container die door alle sessies in een sandbox wordt gedeeld (overschrijvingen van docker/ssh/browser per agent worden binnen dit bereik genegeerd).

Backend bepaalt welke runtime tools in een sandbox uitvoert. SSH-specifieke configuratie staat onder agents.defaults.sandbox.ssh; OpenShell-specifieke configuratie staat onder plugins.entries.openshell.config.

Docker-backend

Docker is de standaardbackend zodra sandboxing is ingeschakeld. Tools en sandboxbrowsers worden lokaal uitgevoerd via de Docker-daemonsocket (/var/run/docker.sock); de isolatie wordt geleverd door Docker-namespaces.

Standaardwaarden: network: "none" (geen uitgaand verkeer), readOnlyRoot: true, capDrop: ["ALL"], image openclaw-sandbox:bookworm-slim.

Stel agents.defaults.sandbox.docker.gpus (of de overschrijving per agent) in op een waarde zoals "all" of "device=GPU-uuid" om GPU's van de host beschikbaar te maken. Deze waarde wordt doorgegeven aan de Docker-vlag --gpus en vereist een compatibele hostruntime, zoals NVIDIA Container Toolkit.

Browser in de sandbox

• De sandboxbrowser start automatisch (en zorgt dat CDP bereikbaar is) wanneer de browsertool deze nodig heeft. Configureer dit via agents.defaults.sandbox.browser.autoStart (standaard true) en autoStartTimeoutMs (standaard 12 s).
• Sandboxbrowsercontainers gebruiken een speciaal Docker-netwerk (openclaw-sandbox-browser) in plaats van het globale bridge-netwerk. Configureer dit met agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange beperkt binnenkomend CDP-verkeer aan de containerrand met een CIDR-toelatingslijst (bijvoorbeeld 172.21.0.1/32).
• noVNC-waarnemerstoegang is standaard beveiligd met een wachtwoord; OpenClaw genereert een URL met een kortlevend token die een lokale opstartpagina aanbiedt en noVNC opent met het wachtwoord in het URL-fragment (niet in de querytekenreeks of headerlogboeken).
• Met agents.defaults.sandbox.browser.allowHostControl (standaard false) kunnen sessies in een sandbox expliciet de hostbrowser als doel gebruiken.
• Optionele toelatingslijsten bewaken target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

SSH-backend

Gebruik backend: "ssh" om exec, bestandstools en het lezen van media in een sandbox uit te voeren 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",          // Of gebruik SecretRefs / inline-inhoud in plaats van lokale bestanden:          // 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" },        },      },    },  },}

Standaardwaarden: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Levenscyclus: OpenClaw maakt onder sandbox.ssh.workspaceRoot een externe hoofdmap per bereik. Bij het eerste gebruik na aanmaak of heraanmaak vult OpenClaw die externe werkruimte eenmaal vanuit de lokale werkruimte. Daarna werken exec, read, write, edit, apply_patch, het lezen van promptmedia en de voorbereiding van inkomende media rechtstreeks via SSH op de externe werkruimte. OpenClaw synchroniseert externe wijzigingen niet automatisch terug naar de lokale werkruimte.
• Authenticatiemateriaal: identityFile/certificateFile/knownHostsFile verwijzen naar bestaande lokale bestanden. identityData/certificateData/knownHostsData accepteren inline-tekenreeksen of SecretRefs, worden via de normale momentopname van de secretsruntime omgezet, naar tijdelijke bestanden met modus 0600 geschreven en verwijderd wanneer de SSH-sessie eindigt. Als voor hetzelfde item zowel een *File- als een *Data-variant is ingesteld, krijgt *Data voor die sessie voorrang.
• Gevolgen van extern canoniek: de externe SSH-werkruimte wordt na de eerste initialisatie de werkelijke sandboxstatus. Lokale bewerkingen op de host die na de initialisatiestap buiten OpenClaw worden uitgevoerd, zijn extern niet zichtbaar totdat u de sandbox opnieuw maakt. openclaw sandbox recreate verwijdert de externe hoofdmap per bereik en initialiseert deze bij het volgende gebruik opnieuw vanuit de lokale werkruimte. Browsersandboxing wordt niet ondersteund op deze backend en instellingen van sandbox.docker.* zijn er niet op van toepassing.

OpenShell-backend

Gebruik backend: "openshell" om tools in een door OpenShell beheerde externe omgeving in een sandbox uit te voeren. OpenShell hergebruikt hetzelfde SSH-transport en dezelfde externe bestandssysteembridge als de algemene SSH-backend en voegt de OpenShell-levenscyclus (sandbox create/get/delete/ssh-config) plus een optionele mirror-modus voor werkruimtesynchronisatie toe.

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

mode: "mirror" (standaard) houdt de lokale werkruimte canoniek: OpenClaw synchroniseert de lokale werkruimte vóór exec naar de sandbox en synchroniseert deze daarna terug. mode: "remote" initialiseert de externe werkruimte eenmaal vanuit de lokale werkruimte en voert daarna exec/read/write/edit/apply_patch rechtstreeks op de externe werkruimte uit zonder terug te synchroniseren; lokale bewerkingen na de initialisatie zijn onzichtbaar totdat u openclaw sandbox recreate uitvoert. Onder scope: "agent" of scope: "shared" wordt die externe werkruimte binnen hetzelfde bereik gedeeld. Huidige beperkingen: de sandboxbrowser wordt nog niet ondersteund en sandbox.docker.binds is niet van toepassing op deze backend.

openclaw sandbox list/recreate/prune behandelen OpenShell-runtimes allemaal hetzelfde als Docker-runtimes; de opschoonlogica houdt rekening met de backend.

Zie OpenShell voor alle vereisten, de configuratiereferentie, de vergelijking van werkruimtemodi en details over de levenscyclus.

Toegang tot de werkruimte

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

Met de OpenShell-backend gebruikt de modus mirror nog steeds de lokale werkruimte als canonieke bron tussen exec-beurten, gebruikt de modus remote na de initiële vulling de externe OpenShell-werkruimte als canonieke bron en beperken workspaceAccess: "ro"/"none" het schrijfgedrag nog steeds op dezelfde manier.

Inkomende media worden naar de actieve sandboxwerkruimte gekopieerd (media/inbound/*).

Aangepaste bind-mounts

agents.defaults.sandbox.docker.binds koppelt extra hostmappen aan de container. Indeling: host:container:mode (bijvoorbeeld "/home/user/source:/source:rw").

Globale en agentspecifieke bind-mounts worden samengevoegd (niet vervangen). Bij scope: "shared" worden agentspecifieke bind-mounts genegeerd.

agents.defaults.sandbox.browser.binds koppelt extra hostmappen uitsluitend aan de container van de sandboxbrowser. Wanneer dit is ingesteld (ook als []), vervangt het docker.binds voor de browsercontainer; wanneer het is weggelaten, valt de browsercontainer terug op docker.binds.

{  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 configuratie

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

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN 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 sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

Standaard worden Docker-sandboxcontainers uitgevoerd zonder netwerk. Overschrijf dit met agents.defaults.sandbox.docker.network.

Docker-installaties en de gecontaineriseerde Gateway vindt u hier: Docker

Voor Docker-implementaties van de Gateway kan scripts/docker/setup.sh de sandboxconfiguratie initialiseren. Stel OPENCLAW_SANDBOX=1 (of true/yes/on) in om dat pad in te schakelen. Overschrijf de socketlocatie met OPENCLAW_DOCKER_SOCKET. Volledige configuratie en naslaginformatie voor omgevingsvariabelen: Docker.

setupCommand (eenmalige containerconfiguratie)

setupCommand wordt eenmaal uitgevoerd nadat de sandboxcontainer is gemaakt (niet bij elke uitvoering). 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 ontsnappingsmogelijkheden

Toestaan-/weigerenbeleid voor tools wordt nog steeds vóór sandboxregels toegepast. Als een tool globaal of per agent wordt geweigerd, maakt sandboxing deze niet opnieuw beschikbaar.

tools.elevated is een expliciete ontsnappingsmogelijkheid die exec buiten de sandbox uitvoert (standaard op de gateway, of op de node wanneer het exec-doel node is). /exec-instructies gelden alleen voor geautoriseerde afzenders en blijven per sessie behouden; om exec volledig uit te schakelen, gebruikt u weigering via het toolbeleid (zie Sandbox versus toolbeleid versus verhoogde rechten).

Foutopsporing:

• openclaw sandbox list toont sandboxcontainers, status, overeenkomst van de image, leeftijd, inactieve tijd en de gekoppelde sessie/agent.
• openclaw sandbox explain [--session <key>] [--agent <id>] inspecteert de effectieve sandboxmodus, hostwerkruimte, runtimewerkmap, Docker-mounts, toolbeleid en configuratiesleutels voor oplossingen. Het veld workspaceRoot blijft de geconfigureerde sandboxhoofdmap; effectiveHostWorkspaceRoot toont waar de actieve werkruimte zich daadwerkelijk bevindt.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] verwijdert containers/omgevingen, zodat deze bij het volgende gebruik opnieuw met de huidige configuratie worden gemaakt.
• Zie Sandbox versus toolbeleid versus verhoogde rechten voor het denkmodel achter “waarom wordt dit geblokkeerd?”.

Overschrijvingen voor meerdere agents

Elke agent kan sandbox + tools overschrijven: agents.list[].sandbox en agents.list[].tools (plus agents.list[].tools.sandbox.tools voor het toolbeleid van de sandbox). Zie Sandbox en tools voor meerdere agents voor de prioriteitsvolgorde.

Minimaal inschakelvoorbeeld

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

Gerelateerd

• Multi-agentsandbox en -tools -- overschrijvingen per agent en voorrangsvolgorde
• OpenShell -- instelling van de beheerde sandboxbackend, werkruimtemodi en configuratiereferentie
• Sandboxconfiguratie
• Sandbox versus toolbeleid versus verhoogde bevoegdheden -- fouten opsporen bij "waarom wordt dit geblokkeerd?"
• Beveiliging