Afgeschermde uitvoering

OpenClaw kan tools binnen sandbox-backends uitvoeren om de impactradius te beperken. Dit is optioneel en wordt door configuratie beheerd (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 geisoleerde sandbox wanneer dit is ingeschakeld.

Wat wordt in een sandbox uitgevoerd

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

Niet in een 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 ontsnappingspad (gateway standaard, of node wanneer het exec-doel node is).
  • Als sandboxing uit staat, verandert tools.elevated de uitvoering niet (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 worden gemaakt:

• "agent" (standaard): een container per agent.
• "session": een container per sessie.
• "shared": een container gedeeld door alle sandboxsessies.

Backend

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

• "docker" (standaard wanneer sandboxing is ingeschakeld): lokale door Docker ondersteunde sandboxruntime.
• "ssh": generieke door SSH ondersteunde externe sandboxruntime.
• "openshell": door 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. Die 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 aan Docker-sandboxes bloot te stellen, 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-vlag, 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 in een sandbox op een willekeurige via SSH bereikbare machine uitvoert.

{  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 in een sandbox uitvoert. Zie de speciale OpenShell-pagina voor de volledige setupgids, configuratiereferentie en vergelijking van werkruimtemodi.

OpenShell hergebruikt hetzelfde kern-SSH-transport en dezelfde externe bestandssysteembridge 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): de lokale werkruimte blijft canoniek. OpenClaw synchroniseert lokale bestanden naar OpenShell voor exec en synchroniseert de externe werkruimte terug na exec.
• remote: de OpenShell-werkruimte is canoniek nadat de sandbox is gemaakt. OpenClaw seedt de externe werkruimte eenmalig 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 het deel dat in de praktijk het belangrijkst is.

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

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 die bij het volgende gebruik opnieuw aanmaken
• opschoonlogica is ook backend-bewust

Voor de remote-modus is opnieuw aanmaken extra belangrijk:

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

Voor de mirror-modus reset opnieuw aanmaken vooral de externe uitvoeringsomgeving, omdat de lokale workspace toch canoniek blijft.

Workspace-toegang

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

Met de OpenShell-backend:

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

Binnenkomende media worden gekopieerd naar de actieve sandbox-workspace (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 en per-agent binds worden samengevoegd (niet vervangen). Onder scope: "shared" worden per-agent binds 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-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 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 aangemaakt (niet bij elke run). Het wordt binnen de container uitgevoerd via sh -lc.

Paden:

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

Toolbeleid en uitwijkroutes

Beleid voor toestaan/weigeren van tools blijft gelden vóór sandboxregels. Als een tool globaal of per agent wordt geweigerd, brengt sandboxing deze niet terug.

tools.elevated is een expliciete uitwijkroute die exec buiten de sandbox uitvoert (standaard gateway, of node wanneer het exec-doel node is). /exec-directieven gelden alleen voor geautoriseerde afzenders en blijven per sessie behouden; gebruik toolbeleid met weigeren 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-overrides

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 — overrides per agent en prioriteit
• OpenShell — beheerde installatie van sandbox-backend, werkruimtemodi en configuratiereferentie
• Sandboxconfiguratie
• Sandbox vs Tool Policy vs Elevated — debuggen van "waarom wordt dit geblokkeerd?"
• Beveiliging