Sandboxing

​

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

• 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

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

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

​

Docker-backend

​

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

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

• 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

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

​

Toegang tot de werkruimte

​

Meerdere mappen voor één agent

host-directory:container-directory:ro
host-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.

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

openclaw sandbox recreate --agent research

​

Overig bindgedrag

{
  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

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 (eenmalige containerinstallatie)

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

​

Toolbeleid en ontsnappingsroutes

• 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

​

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