Mise en bac à sable

OpenClaw peut exécuter les outils dans un backend de bac à sable afin de réduire l’étendue des dommages potentiels. Le bac à sable est désactivé par défaut et contrôlé par agents.defaults.sandbox (globalement) ou agents.list[].sandbox (par agent). Le processus Gateway reste toujours sur l’hôte ; seule l’exécution des outils est déplacée dans le bac à sable lorsqu’il est activé.

Éléments placés dans le bac à sable

• Exécution des outils : exec, read, write, edit, apply_patch, process, etc.
• Le navigateur facultatif placé dans le bac à sable (agents.defaults.sandbox.browser).

Ne sont pas placés dans le bac à sable :

• Le processus Gateway lui-même.
• Tout outil explicitement autorisé à s’exécuter hors du bac à sable via tools.elevated. L’exécution avec élévation contourne le bac à sable et utilise le chemin de sortie configuré (gateway par défaut, ou node lorsque la cible d’exécution est node). Si le bac à sable est désactivé, tools.elevated ne change rien puisque l’exécution se déroule déjà sur l’hôte. Consultez le mode avec élévation.

Modes, portée et backend

Trois paramètres indépendants contrôlent le comportement du bac à sable :

Le mode détermine quand le bac à sable s’applique :

• off : aucun bac à sable.
• non-main : place chaque session dans un bac à sable, sauf la session principale de l’agent. La clé de la session principale est toujours agent:<agentId>:main (ou global lorsque session.scope vaut "global") ; elle n’est pas configurable. Les sessions de groupe ou de canal utilisent leurs propres clés ; elles sont donc toujours considérées comme non principales et placées dans un bac à sable.
• all : chaque session s’exécute dans un bac à sable.

La portée détermine le nombre de conteneurs ou d’environnements créés :

• agent : un conteneur par agent.
• session : un conteneur par session.
• shared : un conteneur partagé par toutes les sessions placées dans un bac à sable (les remplacements de docker/ssh/browser propres à chaque agent sont ignorés avec cette portée).

Le backend détermine quel environnement d’exécution exécute les outils placés dans le bac à sable. La configuration propre à SSH se trouve sous agents.defaults.sandbox.ssh ; celle propre à OpenShell se trouve sous plugins.entries.openshell.config.

Backend Docker

Docker est le backend par défaut une fois le bac à sable activé. Il exécute les outils et les navigateurs en bac à sable localement par l’intermédiaire du socket du démon Docker (/var/run/docker.sock) ; l’isolation repose sur les espaces de noms Docker.

Valeurs par défaut : network: "none" (aucun trafic sortant), readOnlyRoot: true, capDrop: ["ALL"], image openclaw-sandbox:bookworm-slim.

Pour exposer les GPU de l’hôte, définissez agents.defaults.sandbox.docker.gpus (ou le remplacement propre à l’agent) sur une valeur telle que "all" ou "device=GPU-uuid". Cette valeur est transmise à l’option --gpus de Docker et nécessite un environnement d’exécution hôte compatible, tel que NVIDIA Container Toolkit.

Navigateur en bac à sable

• Le navigateur en bac à sable démarre automatiquement (afin de garantir l’accessibilité de CDP) lorsque l’outil de navigation en a besoin. Configurez ce comportement avec agents.defaults.sandbox.browser.autoStart (true par défaut) et autoStartTimeoutMs (12 s par défaut).
• Les conteneurs du navigateur en bac à sable utilisent un réseau Docker dédié (openclaw-sandbox-browser) plutôt que le réseau global bridge. Configurez-le avec agents.defaults.sandbox.browser.network.
• agents.defaults.sandbox.browser.cdpSourceRange limite les connexions CDP entrantes à la périphérie du conteneur au moyen d’une liste d’autorisation CIDR (par exemple 172.21.0.1/32).
• L’accès d’observation noVNC est protégé par mot de passe par défaut ; OpenClaw émet une URL à jeton de courte durée qui fournit une page d’amorçage locale et ouvre noVNC avec le mot de passe dans le fragment de l’URL (et non dans la chaîne de requête ni dans les journaux d’en-têtes).
• agents.defaults.sandbox.browser.allowHostControl (false par défaut) permet aux sessions placées dans un bac à sable de cibler explicitement le navigateur de l’hôte.
• Des listes d’autorisation facultatives contrôlent target: "custom" : allowedControlUrls, allowedControlHosts, allowedControlPorts.

Backend SSH

Utilisez backend: "ssh" pour placer exec, les outils de fichiers et la lecture de médias dans un bac à sable sur une machine quelconque 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",          // Ou utilisez des SecretRefs / du contenu intégré au lieu de fichiers locaux :          // 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" },        },      },    },  },}

Valeurs par défaut : command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true.

• Cycle de vie : OpenClaw crée une racine distante propre à chaque portée sous sandbox.ssh.workspaceRoot. Lors de la première utilisation après sa création ou sa recréation, il initialise une fois cet espace de travail distant à partir de l’espace de travail local. Ensuite, exec, read, write, edit, apply_patch, la lecture des médias de l’invite et la préparation des médias entrants s’exécutent directement dans l’espace de travail distant via SSH. OpenClaw ne synchronise pas automatiquement les modifications distantes vers l’espace de travail local.
• Matériel d’authentification : identityFile/certificateFile/knownHostsFile font référence à des fichiers locaux existants. identityData/certificateData/knownHostsData acceptent des chaînes intégrées ou des SecretRefs, résolues au moyen de l’instantané d’exécution habituel des secrets, écrites dans des fichiers temporaires avec le mode 0600, puis supprimées à la fin de la session SSH. Si une variante *File et une variante *Data sont toutes deux définies pour le même élément, *Data prévaut pour cette session.
• Conséquences du modèle distant canonique : l’espace de travail SSH distant devient l’état réel du bac à sable après l’initialisation. Les modifications locales effectuées sur l’hôte en dehors d’OpenClaw après cette étape ne sont pas visibles à distance tant que vous ne recréez pas le bac à sable. openclaw sandbox recreate supprime la racine distante propre à la portée, puis la réinitialise depuis l’espace local lors de l’utilisation suivante. Le navigateur en bac à sable n’est pas pris en charge par ce backend, et les paramètres sandbox.docker.* ne s’y appliquent pas.

Backend OpenShell

Utilisez backend: "openshell" pour placer les outils dans un bac à sable au sein d’un environnement distant géré par OpenShell. OpenShell réutilise le même transport SSH et le même pont de système de fichiers distant que le backend SSH générique, et y ajoute le cycle de vie OpenShell (sandbox create/get/delete/ssh-config) ainsi qu’un mode facultatif de synchronisation d’espace de travail mirror.

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

mode: "mirror" (valeur par défaut) conserve l’espace de travail local comme référence canonique : OpenClaw synchronise l’espace local vers le bac à sable avant exec, puis synchronise les modifications en retour après l’exécution. mode: "remote" initialise une fois l’espace de travail distant à partir de l’espace local, puis exécute exec/read/write/edit/apply_patch directement dans l’espace de travail distant sans synchronisation en retour ; les modifications locales effectuées après l’initialisation restent invisibles jusqu’à l’exécution de openclaw sandbox recreate. Avec scope: "agent" ou scope: "shared", cet espace de travail distant est partagé selon la même portée. Limites actuelles : le navigateur en bac à sable n’est pas encore pris en charge et sandbox.docker.binds ne s’applique pas à ce backend.

openclaw sandbox list/recreate/prune traitent tous les environnements d’exécution OpenShell de la même manière que ceux de Docker ; la logique d’élagage tient compte du backend.

Pour connaître l’ensemble des prérequis, la référence de configuration, la comparaison des modes d’espace de travail et les détails du cycle de vie, consultez OpenShell.

Accès à l’espace de travail

agents.defaults.sandbox.workspaceAccess détermine ce que le bac à sable peut voir :

Avec le backend OpenShell, le mode mirror continue d’utiliser l’espace de travail local comme source canonique entre les exécutions, le mode remote utilise l’espace de travail OpenShell distant comme source canonique après l’initialisation, et workspaceAccess: "ro"/"none" continue de restreindre les écritures de la même manière.

Les médias entrants sont copiés dans l’espace de travail actif du bac à sable (media/inbound/*).

Montages bind personnalisés

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

Les montages bind globaux et propres à chaque agent sont fusionnés (et non remplacés). Avec scope: "shared", les montages bind propres à chaque agent sont ignorés.

agents.defaults.sandbox.browser.binds monte des répertoires supplémentaires de l’hôte uniquement dans le conteneur du navigateur du bac à sable. Lorsque cette propriété est définie (y compris sur []), elle remplace docker.binds pour le conteneur du navigateur ; lorsqu’elle est omise, le conteneur du navigateur utilise docker.binds par défaut.

{  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 Docker du bac à sable s’exécutent sans réseau. Utilisez agents.defaults.sandbox.docker.network pour modifier ce comportement.

Les installations Docker et le Gateway conteneurisé sont documentés ici : Docker

Pour les déploiements du Gateway avec Docker, scripts/docker/setup.sh peut initialiser la configuration du bac à sable. Définissez OPENCLAW_SANDBOX=1 (ou true/yes/on) pour activer ce chemin. Modifiez 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 du bac à sable (et non à chaque exécution). Il s’exécute dans le conteneur avec sh -lc.

Chemins :

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

Stratégie des outils et échappatoires

Les stratégies d’autorisation et d’interdiction des outils s’appliquent toujours avant les règles du bac à sable. Si un outil est interdit globalement ou pour un agent, le bac à sable ne le réactive pas.

tools.elevated est une échappatoire explicite qui exécute exec en dehors du bac à sable (gateway par défaut, ou node lorsque la cible d’exécution est node). Les directives /exec s’appliquent uniquement aux expéditeurs autorisés et persistent pendant toute la session ; pour désactiver complètement exec, utilisez une interdiction dans la stratégie des outils (consultez Bac à sable, stratégie des outils et mode privilégié).

Débogage :

• openclaw sandbox list affiche les conteneurs du bac à sable, leur état, la correspondance de l’image, leur âge, leur durée d’inactivité et la session ou l’agent associé.
• openclaw sandbox explain [--session <key>] [--agent <id>] inspecte le mode effectif du bac à sable, l’espace de travail de l’hôte, le répertoire de travail d’exécution, les montages Docker, la stratégie des outils et les clés de configuration correctives. Son champ workspaceRoot reste la racine du bac à sable configurée ; effectiveHostWorkspaceRoot indique l’emplacement réel de l’espace de travail actif.
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] supprime les conteneurs et les environnements afin qu’ils soient recréés avec la configuration actuelle lors de la prochaine utilisation.
• Consultez Bac à sable, stratégie des outils et mode privilégié pour comprendre pourquoi une opération est bloquée.

Remplacements propres à chaque agent

Chaque agent peut remplacer la configuration du bac à sable et des outils : agents.list[].sandbox et agents.list[].tools (ainsi que agents.list[].tools.sandbox.tools pour la stratégie des outils du bac à sable). Consultez Bac à sable et outils multi-agents pour connaître l’ordre de priorité.

Exemple minimal d’activation

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

Ressources connexes

• Bac à sable et outils multi-agents -- remplacements par agent et ordre de priorité
• OpenShell -- configuration du moteur de bac à sable géré, modes d’espace de travail et référence de configuration
• Configuration du bac à sable
• Bac à sable, politique des outils et mode privilégié -- diagnostic de « pourquoi ceci est-il bloqué ? »
• Sécurité