Sandboxisolatie

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Wat in een sandbox wordt uitgevoerd

• Uitvoering van hulpmiddelen (exec, read, write, edit, apply_patch, process, enz.).
• Optionele browser in een sandbox (agents.defaults.sandbox.browser).

• Het Gateway-proces zelf.
• Elk hulpmiddel dat expliciet buiten de sandbox mag draaien (bijv. tools.elevated).
  • Verhoogde 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 (die draait al op de host). Zie Verhoogde modus.

​

Modi

​

Bereik

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

​

Backend

• "docker" (standaard wanneer sandboxing is ingeschakeld): lokale, door Docker ondersteunde sandboxruntime.
• "ssh": generieke, door SSH ondersteunde externe sandboxruntime.
• "openshell": door OpenShell ondersteunde sandboxruntime.

​

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): lokale werkruimte blijft canoniek. OpenClaw synchroniseert lokale bestanden naar OpenShell voor exec en synchroniseert de externe werkruimte terug na exec.
• remote: OpenShell-werkruimte is canoniek nadat de sandbox is gemaakt. OpenClaw seedt de externe werkruimte eenmalig vanuit de lokale werkruimte; daarna draaien bestandshulpmiddelen 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 deze bij het volgende gebruik opnieuw aanmaken
• opschoonlogica is ook backendbewust

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

​

Werkruimtetoegang

• de modus mirror gebruikt nog steeds de lokale werkruimte als canonieke bron tussen exec-beurten
• de modus remote gebruikt de externe OpenShell-werkruimte als canonieke bron na de eerste zaai
• 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

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 escape hatches

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

​

Multi-agent-overrides

​

Minimaal inschakelvoorbeeld

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

​

Gerelateerd

• Multi-agent-sandbox en tools — overschrijvingen per agent en prioriteit
• OpenShell — installatie van beheerde sandbox-backend, werkruimtemodi en configuratiereferentie
• Sandboxconfiguratie
• Sandbox versus toolbeleid versus verhoogd — foutopsporing “waarom wordt dit geblokkeerd?”
• Beveiliging