Sandboxing

OpenClaw kan tooluitvoering binnen een sandbox-backend uitvoeren om de impact te beperken. Sandboxing is standaard uitgeschakeld en wordt geregeld door agents.defaults.sandbox (globaal) of agents.entries.*.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 waarvoor via tools.elevated expliciet is toegestaan dat deze buiten de sandbox wordt uitgevoerd. Uitvoering met verhoogde bevoegdheden omzeilt sandboxing en vindt plaats via 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 bevoegdheden.

Modi, bereik en backend

Drie onafhankelijke instellingen bepalen het sandboxgedrag:

Modus bepaalt wanneer sandboxing wordt toegepast:

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

Bereik bepaalt hoeveel containers/omgevingen worden aangemaakt:

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

Backend bepaalt welke runtime tools in de 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. Het voert tools en sandboxbrowsers lokaal uit 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 host-GPU's beschikbaar te maken. Dit wordt doorgegeven aan de Docker-vlag --gpus en vereist een compatibele hostruntime, zoals NVIDIA Container Toolkit.

Browser in de sandbox

• De sandboxbrowser wordt automatisch gestart (zodat CDP bereikbaar is) wanneer de browsertool deze nodig heeft. Configureer dit via agents.defaults.sandbox.browser.autoStart (standaard true) en autoStartTimeoutMs (standaard 12s).
• 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 inkomend CDP-verkeer aan de containerrand met een CIDR-toestaanlijst (bijvoorbeeld 172.21.0.1/32).
• Waarnemerstoegang via noVNC is standaard met een wachtwoord beveiligd; 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).
• agents.defaults.sandbox.browser.allowHostControl (standaard false) laat sessies in een sandbox expliciet de hostbrowser als doel gebruiken.
• Optionele toestaanlijsten 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 aan. Bij het eerste gebruik na aanmaken of opnieuw aanmaken wordt die externe werkruimte eenmaal gevuld vanuit de lokale werkruimte. Daarna worden exec, read, write, edit, apply_patch, het lezen van promptmedia en het klaarzetten van inkomende media rechtstreeks via SSH uitgevoerd 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, die via de normale runtime-snapshot voor geheimen worden opgelost, met modus 0600 naar tijdelijke bestanden worden geschreven en worden verwijderd wanneer de SSH-sessie eindigt. Als voor hetzelfde item zowel een *File- als een *Data-variant is ingesteld, heeft *Data voor die sessie voorrang.
• Gevolgen van extern canoniek gebruik: de externe SSH-werkruimte wordt na de eerste vulling de werkelijke sandboxstatus. Lokale wijzigingen op de host die na het vullen buiten OpenClaw worden aangebracht, zijn extern niet zichtbaar totdat je de sandbox opnieuw aanmaakt. openclaw sandbox recreate verwijdert de externe hoofdmap per bereik en vult deze bij het volgende gebruik opnieuw vanuit de lokale werkruimte. Browsersandboxing wordt niet ondersteund op deze backend en de 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", // spiegelen | extern        },      },    },  },}

mode: "mirror" (standaard) houdt de lokale werkruimte canoniek: OpenClaw synchroniseert lokaal naar de sandbox vóór exec en synchroniseert daarna terug. mode: "remote" initialiseert de externe werkruimte eenmaal vanuit de lokale werkruimte en voert vervolgens exec/read/write/edit/apply_patch rechtstreeks uit op de externe werkruimte zonder terug te synchroniseren; lokale wijzigingen na de initialisatie zijn niet zichtbaar totdat je openclaw sandbox recreate. 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/opschonen behandelen OpenShell-runtimes allemaal hetzelfde als Docker-runtimes; de opschoonlogica houdt rekening met de backend.

Zie OpenShell voor alle vereisten, het configuratieoverzicht, 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 uitvoeringsbeurten, gebruikt de modus remote na de initiële initialisatie 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/*).

Meerdere mappen voor één agent

Gebruik Docker-bindmounts wanneer één agent in een sandbox meer nodig heeft dan de primaire werkruimte. Elk item wijst een hostmap toe aan een containerpad met een expliciete toegangsmodus:

host-directory:container-directory:rohost-directory:container-directory:rw

• ro maakt de gekoppelde map alleen-lezen binnen de sandbox.
• rw staat toe dat tools en processen in de sandbox de hostmap wijzigen.
• Het containerpad is het pad dat de agent gebruikt. Hostpaden worden niet automatisch blootgesteld.

Dit voorbeeld geeft de agent research een beschrijfbare primaire werkruimte, alleen-lezenreferentiemateriaal op /reference en een afzonderlijke beschrijfbare uitvoermap op /drafts:

{  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"],            // Vereist omdat deze bronnen zich buiten de agentwerkruimte bevinden.            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess en bindmodi zijn onafhankelijk:

Het wijzigen van workspaceAccess verandert een aanvullende bind niet van ro in rw, of omgekeerd. Globale en agentspecifieke docker.binds worden samengevoegd. Behoud scope: "agent" of "session" voor agentspecifieke binds; scope: "shared" negeert alle agentspecifieke Docker-overschrijvingen en gebruikt alleen globale binds.

Bindmounts vormen de ondersteunde grens voor meerdere mappen, omdat Docker met mountisolatie de bestandssysteemweergave van de container samenstelt en de modus ro/rw van toepassing is op elk proces in de sandbox. Die grens omvat exec, bestandssysteemtools, onderliggende processen en bibliotheken, zonder padmachtigingscontroles in elk OpenClaw-codepad te dupliceren. Een allowlist voor paden aan de hostzijde kan niet dezelfde volledige afbakening bieden wanneer een toegestane shell of afhankelijkheid rechtstreeks toegang tot bestanden kan krijgen.

De optionele dangerouslyAllowExternalBindSources staat alleen bronnen buiten de werkruimtehoofdmappen toe. Hiermee worden OpenClaws controles op geblokkeerde systeemlocaties, referenties, Docker-sockets, symlink-bovenliggende mappen of gereserveerde doelen niet uitgeschakeld. Geef de voorkeur aan de kleinste map, gebruik ro tenzij schrijftoegang vereist is en maak de sandbox opnieuw aan nadat je mounts hebt gewijzigd:

openclaw sandbox recreate --agent research

Overig bindgedrag

agents.defaults.sandbox.docker.binds configureert globale mounts. De indeling is dezelfde host:container:mode-vorm (bijvoorbeeld "/home/user/source:/source:rw").

agents.defaults.sandbox.browser.binds koppelt aanvullende hostmappen alleen aan de container van de sandboxbrowser. Wanneer dit is ingesteld (inclusief []), 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 installatie

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

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

Docker-installaties en de Gateway in een container vind je 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 dit pad in te schakelen. Overschrijf de socketlocatie met OPENCLAW_DOCKER_SOCKET. Volledige installatie- en omgevingsreferentie: Docker.

setupCommand (eenmalige containerinstallatie)

setupCommand wordt eenmaal uitgevoerd nadat de sandboxcontainer is gemaakt (niet bij elke uitvoering). De opdracht wordt in de container uitgevoerd via sh -lc.

Paden:

• Globaal: agents.defaults.sandbox.docker.setupCommand
• Per agent: agents.entries.*.sandbox.docker.setupCommand

Toolbeleid en ontsnappingsroutes

Beleid voor het toestaan of weigeren van tools wordt nog steeds vóór de sandboxregels toegepast. Als een tool globaal of per agent wordt geweigerd, maakt sandboxing deze niet opnieuw beschikbaar.

tools.elevated is een expliciete ontsnappingsroute die exec buiten de sandbox uitvoert (standaard gateway, of node wanneer het uitvoeringsdoel node is). /exec-instructies zijn alleen van toepassing op geautoriseerde afzenders en blijven per sessie behouden; om exec volledig uit te schakelen, gebruik je een weigering in het toolbeleid (zie Sandbox versus toolbeleid versus verhoogde rechten).

Probleemoplossing:

• openclaw sandbox list toont sandboxcontainers, status, overeenkomst met de image, leeftijd, inactieve tijd en de gekoppelde sessie/agent.
• openclaw sandbox explain [--session <key>] [--agent <id>] inspecteert de effectieve sandboxmodus, de werkruimte van de host, de runtimewerkmap, Docker-koppelingen, het toolbeleid en configuratiesleutels voor herstel. Het veld workspaceRoot blijft de geconfigureerde sandboxroot; 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 worden gemaakt met de huidige configuratie.
• Zie Sandbox versus toolbeleid versus verhoogde rechten voor het denkmodel achter 'waarom wordt dit geblokkeerd?'.

Overschrijvingen voor meerdere agents

Elke agent kan de sandbox en tools overschrijven: agents.entries.*.sandbox en agents.entries.*.tools (plus agents.entries.*.tools.sandbox.tools voor het toolbeleid van de sandbox). Zie Sandbox en tools voor meerdere agents voor de prioriteitsvolgorde.

Minimaal voorbeeld voor inschakeling

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

Gerelateerd

• Sandbox en tools voor meerdere agents -- overschrijvingen per agent en prioriteitsvolgorde
• OpenShell -- installatie van de beheerde sandboxbackend, werkruimtemodi en configuratiereferentie
• Sandboxconfiguratie
• Sandbox versus toolbeleid versus verhoogde rechten -- problemen oplossen rond 'waarom wordt dit geblokkeerd?'
• Beveiliging