Mise en 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 sandboxing 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’il est activé.

# Ce qui est mis en bac à sable

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

Non mis en bac à sable :

• Le processus Gateway lui-même.
• Tout outil explicitement autorisé à s’exécuter hors du bac à sable (par exemple tools.elevated).
  • L’exécution élevée contourne le sandboxing et utilise le chemin d’échappement configuré (gateway par défaut, ou node lorsque la cible d’exécution est node).
  • Si le sandboxing 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 sandboxing 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 sandboxing 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 spécifique à SSH se trouve sous agents.defaults.sandbox.ssh. La configuration spécifique à OpenShell se trouve sous plugins.entries.openshell.config.

# Choisir un backend

# Backend Docker

Le sandboxing est désactivé par défaut. Si vous activez le sandboxing 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 du conteneur 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 le remplacement 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 tel que NVIDIA Container Toolkit.

# Backend SSH

Utilisez backend: "ssh" lorsque vous voulez qu’OpenClaw mette en bac à sable exec, les outils de fichiers et les lectures de médias sur une machine arbitraire accessible en 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 mette les outils en bac à sable dans 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 spécifique à 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 synchronise l’espace de travail distant en retour après exec.
• remote : l’espace de travail OpenShell est canonique après la création du bac à sable. OpenClaw amorce une fois l’espace de travail distant depuis l’espace de travail local, puis les outils de fichiers et exec s’exécutent directement contre le bac à sable distant sans synchroniser les changements en retour.

# Modes d’espace de travail

OpenShell a deux modèles d’espace de travail. 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 véritable espace de travail.

# Cycle de vie OpenShell

Les sandbox OpenShell sont toujours gérés via le cycle de vie normal des sandbox :

• 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 aussi compte du backend

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

• la recréation supprime l’espace de travail distant canonique pour cette portée
• la prochaine utilisation initialise un nouvel espace de travail distant à partir de l’espace de travail local

Pour le mode mirror, la recréation réinitialise principalement l’environnement d’exécution distant, car l’espace de travail local reste canonique dans tous les cas.

# Accès à l’espace de travail

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

Avec le backend OpenShell :

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

Les médias entrants sont copiés dans l’espace de travail actif du sandbox (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 montages globaux et par agent sont fusionnés (pas remplacés). Sous scope: "shared", les montages par 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 (compatible avec les versions précédentes).

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

Par défaut, les conteneurs de sandbox Docker s’exécutent avec aucun 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 de Gateway Docker, scripts/docker/setup.sh peut initialiser la configuration du 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 d’environnement : Docker.

# setupCommand (configuration unique du conteneur)

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

Chemins :

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

# Politique d’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 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 s’appliquent uniquement aux expéditeurs autorisés et persistent par session ; pour désactiver strictement exec, utilisez un refus dans la politique d’outils (voir Sandbox, politique d’outils et élévation).

Débogage :

• Utilisez openclaw sandbox explain pour inspecter le mode de sandbox effectif, la politique d’outils et les clés de configuration de correction.
• Consultez Sandbox, politique d’outils et élévation pour le modèle mental « pourquoi est-ce 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 d’outils de la sandbox). Consultez Sandbox multi-agent et outils pour l’ordre de priorité.

# Exemple d’activation minimal

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

# Connexe

• Sandbox multi-agent et outils — remplacements par agent et ordre de priorité
• OpenShell — configuration du backend de sandbox géré, modes d’espace de travail et référence de configuration
• Configuration de la sandbox
• Sandbox, politique d’outils et élévation — débogage « pourquoi est-ce bloqué ? »
• Sécurité