Bac à sable

OpenClaw peut exécuter des outils dans des backends de bac à sable afin de réduire le rayon d’impact. C’est facultatif et contrôlé par la configuration (agents.defaults.sandbox ou agents.list[].sandbox). Si le bac à sable est désactivé, les outils s’exécutent sur l’hôte. Le Gateway reste sur l’hôte ; l’exécution des outils se fait dans un bac à sable isolé lorsqu’elle est activée.

Ce qui est exécuté dans le bac à sable

• Exécution des outils (exec, read, write, edit, apply_patch, process, etc.).
• Navigateur facultatif en bac à sable (agents.defaults.sandbox.browser).

Non exécuté dans le bac à sable :

• Le processus Gateway lui-même.
• Tout outil explicitement autorisé à s’exécuter en dehors du bac à sable (par exemple tools.elevated).
  • L’exec élevé contourne le bac à sable et utilise le chemin d’échappement configuré (gateway par défaut, ou node quand la cible exec est node).
  • Si le bac à sable est désactivé, tools.elevated ne change pas l’exécution (déjà sur l’hôte). Consultez Mode élevé.

Modes

agents.defaults.sandbox.mode contrôle quand le bac à sable est utilisé :

Portée

agents.defaults.sandbox.scope contrôle combien de conteneurs sont créés :

• "agent" (par défaut) : un conteneur par agent.
• "session" : un conteneur par session.
• "shared" : un conteneur partagé par toutes les sessions en bac à sable.

Backend

agents.defaults.sandbox.backend contrôle quel runtime fournit le bac à sable :

• "docker" (par défaut lorsque le bac à sable est activé) : runtime de bac à sable local adossé à Docker.
• "ssh" : runtime de bac à sable distant générique adossé à SSH.
• "openshell" : runtime de bac à sable adossé à OpenShell.

La configuration propre à SSH se trouve sous agents.defaults.sandbox.ssh. La configuration propre à OpenShell se trouve sous plugins.entries.openshell.config.

Choisir un backend

Backend Docker

Le bac à sable est désactivé par défaut. Si vous activez le bac à sable sans choisir de backend, OpenClaw utilise le backend Docker. Il exécute les outils et les navigateurs en bac à sable localement via le socket du démon Docker (/var/run/docker.sock). L’isolation des conteneurs de bac à sable est déterminée par les espaces de noms Docker.

Pour exposer les GPU de l’hôte aux bacs à sable Docker, définissez agents.defaults.sandbox.docker.gpus ou la surcharge par agent agents.list[].sandbox.docker.gpus. La valeur est transmise au flag --gpus de Docker comme argument séparé, par exemple "all" ou "device=GPU-uuid", et nécessite un runtime hôte compatible comme NVIDIA Container Toolkit.

Backend SSH

Utilisez backend: "ssh" lorsque vous voulez qu’OpenClaw exécute exec, les outils de fichiers et les lectures de médias dans un bac à sable sur une machine arbitraire accessible par SSH.

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

Backend OpenShell

Utilisez backend: "openshell" lorsque vous voulez qu’OpenClaw exécute les outils dans un bac à sable au sein d’un environnement distant géré par OpenShell. Pour le guide de configuration complet, la référence de configuration et la comparaison des modes d’espace de travail, consultez la page OpenShell dédiée.

OpenShell réutilise le même transport SSH central et le même pont de système de fichiers distant que le backend SSH générique, et ajoute le cycle de vie propre à OpenShell (sandbox create/get/delete, sandbox ssh-config) ainsi que le mode d’espace de travail facultatif mirror.

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

Modes OpenShell :

• mirror (par défaut) : l’espace de travail local reste canonique. OpenClaw synchronise les fichiers locaux vers OpenShell avant exec et resynchronise l’espace de travail distant après exec.
• remote : l’espace de travail OpenShell est canonique après la création du bac à sable. OpenClaw initialise l’espace de travail distant une seule fois depuis l’espace de travail local, puis les outils de fichiers et exec s’exécutent directement contre le bac à sable distant sans resynchroniser les modifications.

Modes de workspace

OpenShell propose deux modèles de workspace. C’est la partie la plus importante en pratique.

Choisissez mirror si vous considérez le sandbox comme un environnement d’exécution temporaire. Choisissez remote si vous considérez le sandbox comme le vrai workspace.

Cycle de vie OpenShell

Les sandboxes OpenShell restent gérés via le cycle de vie normal des sandboxes :

• openclaw sandbox list affiche les runtimes OpenShell ainsi que les runtimes Docker
• openclaw sandbox recreate supprime le runtime actuel et laisse OpenClaw le recréer à la prochaine utilisation
• la logique de nettoyage tient également compte du backend

Pour le mode remote, la recréation est particulièrement importante :

• recréer supprime le workspace distant canonique pour ce périmètre
• la prochaine utilisation initialise un nouveau workspace distant à partir du workspace local

Pour le mode mirror, recréer réinitialise surtout l’environnement d’exécution distant, car le workspace local reste de toute façon canonique.

Accès au workspace

agents.defaults.sandbox.workspaceAccess contrôle ce que le sandbox peut voir :

Avec le backend OpenShell :

• le mode mirror utilise toujours le workspace local comme source canonique entre les tours d’exec
• le mode remote utilise le workspace OpenShell distant comme source canonique après l’initialisation initiale
• workspaceAccess: "ro" et "none" restreignent toujours le comportement d’écriture de la même manière

Les médias entrants sont copiés dans le workspace du sandbox actif (media/inbound/*).

Montages bind personnalisés

agents.defaults.sandbox.docker.binds monte des répertoires hôtes supplémentaires dans le conteneur. Format : host:container:mode (par exemple, "/home/user/source:/source:rw").

Les binds globaux et propres à un agent sont fusionnés (et non remplacés). Sous scope: "shared", les binds propres à un agent sont ignorés.

agents.defaults.sandbox.browser.binds monte des répertoires hôtes supplémentaires uniquement dans le conteneur du navigateur de sandbox.

• Lorsqu’il est défini (y compris []), il remplace agents.defaults.sandbox.docker.binds pour le conteneur du navigateur.
• Lorsqu’il est omis, le conteneur du navigateur se rabat sur agents.defaults.sandbox.docker.binds (rétrocompatible).

Exemple (source en lecture seule + un répertoire de données supplémentaire) :

{  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 et configuration

Image Docker par défaut : 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

Par défaut, les conteneurs de sandbox Docker s’exécutent sans réseau. Remplacez ce comportement avec agents.defaults.sandbox.docker.network.

Les installations Docker et le Gateway conteneurisé se trouvent ici : Docker

Pour les déploiements du Gateway Docker, scripts/docker/setup.sh peut amorcer la configuration de sandbox. Définissez OPENCLAW_SANDBOX=1 (ou true/yes/on) pour activer ce chemin. Vous pouvez remplacer l’emplacement du socket avec OPENCLAW_DOCKER_SOCKET. Configuration complète et référence des variables d’environnement : Docker.

setupCommand (configuration ponctuelle du conteneur)

setupCommand s’exécute une seule fois après la création du conteneur de sandbox (pas à chaque exécution). Elle s’exécute dans le conteneur via sh -lc.

Chemins :

• Global : agents.defaults.sandbox.docker.setupCommand
• Par agent : agents.list[].sandbox.docker.setupCommand

Politique des outils et échappatoires

Les politiques d’autorisation/refus des outils s’appliquent toujours avant les règles de sandbox. Si un outil est refusé globalement ou par agent, la mise en sandbox ne le réactive pas.

tools.elevated est une échappatoire explicite qui exécute exec hors de la sandbox (gateway par défaut, ou node lorsque la cible d’exécution est node). Les directives /exec ne s’appliquent qu’aux expéditeurs autorisés et persistent par session ; pour désactiver strictement exec, utilisez la politique de refus des outils (voir Sandbox vs Tool Policy vs Elevated).

Débogage :

• Utilisez openclaw sandbox explain pour inspecter le mode de sandbox effectif, la politique des outils et les clés de configuration correctives.
• Consultez Sandbox vs Tool Policy vs Elevated pour le modèle mental « pourquoi ceci est-il bloqué ? ».

Gardez-le verrouillé.

Remplacements multi-agent

Chaque agent peut remplacer la sandbox et les outils : agents.list[].sandbox et agents.list[].tools (plus agents.list[].tools.sandbox.tools pour la politique des outils de sandbox). Consultez Sandbox et outils multi-agent pour la précédence.

Exemple d’activation minimal

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

Associés

• Sandbox et outils multi-agent — remplacements par agent et précédence
• OpenShell — configuration du backend de sandbox géré, modes d’espace de travail et référence de configuration
• Configuration de sandbox
• Sandbox vs Tool Policy vs Elevated — débogage « pourquoi ceci est-il bloqué ? »
• Sécurité