Sandboxisolatie

​

Wat wordt gesandboxed

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

• Het Gateway-proces zelf.
• Elke tool die expliciet buiten de sandbox mag worden uitgevoerd (bijv. tools.elevated).
  • Elevated exec omzeilt sandboxing en gebruikt het geconfigureerde ontsnappingspad (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

​

Bereik

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

​

Backend

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

​

Een backend kiezen

​

Docker-backend

​

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",
          // 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

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

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

​

Werkruimtemodi

​

OpenShell-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 maken
• opruimlogica is ook backendbewust

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

​

Werkruimtetoegang

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

​

Aangepaste bind-mounts

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

{
  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

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 container-setup)

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

​

Toolbeleid en uitwijkmogelijkheden

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

​

Multi-agent-overrides

​

Minimaal inschakelvoorbeeld

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

​

Gerelateerd

• Multi-Agent Sandbox & Tools — overrides per agent en voorrang
• OpenShell — beheerde sandbox-backendsetup, werkruimtemodi en configuratiereferentie
• Sandboxconfiguratie
• Sandbox vs Tool Policy vs Elevated — debuggen van “waarom wordt dit geblokkeerd?”
• Beveiliging