​

Sandboxing

​

Ce qui est sandboxé

• Exécution d’outils (exec, read, write, edit, apply_patch, process, etc.).
• Navigateur sandboxé optionnel (agents.defaults.sandbox.browser).
  • Par défaut, le navigateur du sandbox démarre automatiquement (garantit que le CDP est accessible) lorsque l’outil navigateur en a besoin. Configurez-le via agents.defaults.sandbox.browser.autoStart et agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • Par défaut, les conteneurs du navigateur sandboxé utilisent un réseau Docker dédié (openclaw-sandbox-browser) au lieu du réseau global bridge. Configurez cela avec agents.defaults.sandbox.browser.network.
  • Le paramètre optionnel agents.defaults.sandbox.browser.cdpSourceRange restreint l’entrée CDP au bord du conteneur avec une liste d’autorisation CIDR (par exemple 172.21.0.1/32).
  • L’accès observateur noVNC est protégé par mot de passe par défaut ; OpenClaw émet une URL à jeton de courte durée qui sert une page d’amorçage locale et ouvre noVNC avec le mot de passe dans le fragment de l’URL (pas dans les journaux de requête/en-tête).
  • agents.defaults.sandbox.browser.allowHostControl permet aux sessions sandboxées de cibler explicitement le navigateur hôte.
  • Des listes d’autorisation optionnelles contrôlent target: "custom" : allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Le processus Gateway lui-même.
• Tout outil explicitement autorisé à s’exécuter hors du sandbox (par exemple tools.elevated).
  • Le mode exec elevated contourne le sandboxing et utilise le chemin d’échappement configuré (gateway par défaut, ou node lorsque la cible exec est node).
  • Si le sandboxing est désactivé, tools.elevated ne change pas l’exécution (déjà sur l’hôte). Voir Mode Elevated.

​

Modes

• "off" : aucun sandboxing.
• "non-main" : sandbox uniquement des sessions non principales (par défaut si vous voulez des chats normaux sur l’hôte).
• "all" : chaque session s’exécute dans un sandbox. Remarque : "non-main" est basé sur session.mainKey (par défaut "main"), pas sur l’identifiant d’agent. Les sessions de groupe/canal utilisent leurs propres clés, elles sont donc considérées comme non principales et seront sandboxées.

​

Portée

• "agent" (par défaut) : un conteneur par agent.
• "session" : un conteneur par session.
• "shared" : un conteneur partagé par toutes les sessions sandboxées.

​

Backend

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

​

Choisir un backend

​

Backend Docker

• La configuration exige des chemins hôte : la configuration workspace dans openclaw.json DOIT contenir le chemin absolu de l’hôte (par ex. /home/user/.openclaw/workspaces), et non le chemin interne du conteneur Gateway. Quand OpenClaw demande au démon Docker de démarrer un sandbox, le démon évalue les chemins par rapport à l’espace de noms de l’OS hôte, pas à celui du Gateway.
• Parité du pont FS (mappage de volume identique) : le processus natif du Gateway OpenClaw écrit aussi des fichiers heartbeat et bridge dans le répertoire workspace. Comme le Gateway évalue exactement la même chaîne (le chemin hôte) depuis son propre environnement conteneurisé, le déploiement du Gateway DOIT inclure un mappage de volume identique reliant nativement l’espace de noms de l’hôte (-v /home/user/.openclaw:/home/user/.openclaw).

​

Backend 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 SecretRefs / du contenu inline 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" },
        },
      },
    },
  },
}

• OpenClaw crée une racine distante par portée sous sandbox.ssh.workspaceRoot.
• Lors de la première utilisation après création ou recréation, OpenClaw amorce cet espace de travail distant à partir de l’espace de travail local une seule fois.
• Ensuite, exec, read, write, edit, apply_patch, les lectures de médias de prompt et la préparation des médias entrants s’exécutent directement sur l’espace de travail distant via SSH.
• OpenClaw ne synchronise pas automatiquement les modifications distantes vers l’espace de travail local.

• identityFile, certificateFile, knownHostsFile : utilisent les fichiers locaux existants et les transmettent via la configuration OpenSSH.
• identityData, certificateData, knownHostsData : utilisent des chaînes inline ou SecretRefs. OpenClaw les résout via l’instantané runtime normal des secrets, les écrit dans des fichiers temporaires avec 0600, puis les supprime lorsque la session SSH se termine.
• Si *File et *Data sont tous deux définis pour le même élément, *Data l’emporte pour cette session SSH.

• Les modifications locales sur l’hôte effectuées hors d’OpenClaw après l’étape d’amorçage ne sont pas visibles à distance tant que vous ne recréez pas le sandbox.
• openclaw sandbox recreate supprime la racine distante par portée et réamorce depuis le local lors de la prochaine utilisation.
• Le sandboxing de navigateur n’est pas pris en charge sur le backend SSH.
• Les paramètres sandbox.docker.* ne s’appliquent pas au backend SSH.

​

Backend OpenShell

{
  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 (par défaut) : l’espace de travail local reste canonique. OpenClaw synchronise les fichiers locaux dans OpenShell avant exec et resynchronise l’espace de travail distant après exec.
• remote : l’espace de travail OpenShell devient canonique après la création du sandbox. OpenClaw amorce une fois l’espace de travail distant à partir de l’espace de travail local, puis les outils de fichiers et exec s’exécutent directement sur le sandbox distant sans resynchroniser les modifications en retour.

• OpenClaw demande à OpenShell une configuration SSH spécifique au sandbox via openshell sandbox ssh-config <name>.
• Le cœur écrit cette configuration SSH dans un fichier temporaire, ouvre la session SSH et réutilise le même pont de système de fichiers distant que backend: "ssh".
• En mode mirror uniquement, seul le cycle de vie diffère : synchronisation local vers distant avant exec, puis synchronisation en retour après exec.

• le navigateur sandboxé n’est pas encore pris en charge
• sandbox.docker.binds n’est pas pris en charge sur le backend OpenShell
• les réglages runtime spécifiques à Docker sous sandbox.docker.* continuent de ne s’appliquer qu’au backend Docker

​

Modes d’espace de travail

mirror

• Avant exec, OpenClaw synchronise l’espace de travail local dans le sandbox OpenShell.
• Après exec, OpenClaw synchronise l’espace de travail distant vers l’espace de travail local.
• Les outils de fichiers fonctionnent toujours via le pont du sandbox, mais l’espace de travail local reste la source de vérité entre les tours.

• vous modifiez des fichiers localement hors d’OpenClaw et voulez que ces changements apparaissent automatiquement dans le sandbox
• vous voulez que le sandbox OpenShell se comporte autant que possible comme le backend Docker
• vous voulez que l’espace de travail hôte reflète les écritures du sandbox après chaque tour exec

• coût de synchronisation supplémentaire avant et après exec

remote

• Lors de la première création du sandbox, OpenClaw amorce une fois l’espace de travail distant à partir de l’espace de travail local.
• Ensuite, exec, read, write, edit et apply_patch opèrent directement sur l’espace de travail OpenShell distant.
• OpenClaw ne synchronise pas les modifications distantes vers l’espace de travail local après exec.
• Les lectures de médias au moment du prompt continuent de fonctionner, car les outils de fichiers et de médias lisent via le pont du sandbox au lieu de supposer un chemin d’hôte local.
• Le transport se fait en SSH dans le sandbox OpenShell renvoyé par openshell sandbox ssh-config.

• Si vous modifiez des fichiers sur l’hôte hors d’OpenClaw après l’étape d’amorçage, le sandbox distant ne verra pas automatiquement ces changements.
• Si le sandbox est recréé, l’espace de travail distant est à nouveau amorcé à partir de l’espace de travail local.
• Avec scope: "agent" ou scope: "shared", cet espace de travail distant est partagé à cette même portée.

• le sandbox doit vivre principalement du côté distant OpenShell
• vous voulez une surcharge de synchronisation plus faible à chaque tour
• vous ne voulez pas que des modifications locales sur l’hôte écrasent silencieusement l’état du sandbox distant

​

Cycle de vie OpenShell

• 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 lors de la prochaine utilisation
• la logique de purge tient aussi compte du backend

• recreate supprime l’espace de travail distant canonique pour cette portée
• l’utilisation suivante amorce un nouvel espace de travail distant à partir de l’espace de travail local

​

Accès à l’espace de travail

• "none" (par défaut) : les outils voient un espace de travail sandboxé sous ~/.openclaw/sandboxes.
• "ro" : monte l’espace de travail de l’agent en lecture seule à /agent (désactive write/edit/apply_patch).
• "rw" : monte l’espace de travail de l’agent en lecture/écriture à /workspace.

• 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’amorçage initial
• workspaceAccess: "ro" et "none" continuent de restreindre le comportement d’écriture de la même manière

​

Montages bind personnalisés

• 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 revient à agents.defaults.sandbox.docker.binds (compatibilité descendante).

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

• Les montages bind contournent le système de fichiers du sandbox : ils exposent des chemins hôte avec le mode que vous définissez (:ro ou :rw).
• OpenClaw bloque les sources de montage bind dangereuses (par exemple : docker.sock, /etc, /proc, /sys, /dev et les montages parents qui les exposeraient).
• OpenClaw bloque aussi les racines d’identifiants courantes des répertoires personnels telles que ~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm et ~/.ssh.
• La validation des montages bind ne repose pas uniquement sur une comparaison de chaînes. OpenClaw normalise le chemin source, puis le résout à nouveau via l’ancêtre existant le plus profond avant de revérifier les chemins bloqués et les racines autorisées.
• Cela signifie que les échappées via parent symbolique échouent toujours de façon sûre, même lorsque la feuille finale n’existe pas encore. Exemple : /workspace/run-link/new-file se résout toujours en /var/run/... si run-link pointe vers cet emplacement.
• Les racines sources autorisées sont canonisées de la même manière ; ainsi, un chemin qui ne semble être dans la liste d’autorisation qu’avant résolution des liens symboliques est quand même rejeté comme outside allowed roots.
• Les montages sensibles (secrets, clés SSH, identifiants de service) doivent être en :ro sauf nécessité absolue.
• Combinez cela avec workspaceAccess: "ro" si vous n’avez besoin que d’un accès en lecture à l’espace de travail ; les modes de montage bind restent indépendants.
• Voir Sandbox vs Tool Policy vs Elevated pour comprendre comment les montages bind interagissent avec la politique des outils et le mode elevated exec.

​

Images + configuration

scripts/sandbox-setup.sh

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

• --remote-debugging-address=127.0.0.1
• --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
• --user-data-dir=${HOME}/.chrome
• --no-first-run
• --no-default-browser-check
• --disable-3d-apis
• --disable-gpu
• --disable-dev-shm-usage
• --disable-background-networking
• --disable-extensions
• --disable-features=TranslateUI
• --disable-breakpad
• --disable-crash-reporter
• --disable-software-rasterizer
• --no-zygote
• --metrics-recording-only
• --renderer-process-limit=2
• --no-sandbox et --disable-setuid-sandbox lorsque noSandbox est activé.
• Les trois options de durcissement graphique (--disable-3d-apis, --disable-software-rasterizer, --disable-gpu) sont facultatives et utiles lorsque les conteneurs n’ont pas de prise en charge GPU. Définissez OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 si votre charge de travail exige WebGL ou d’autres fonctionnalités 3D/navigateur.
• --disable-extensions est activé par défaut et peut être désactivé avec OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 pour les flux qui dépendent des extensions.
• --renderer-process-limit=2 est contrôlé par OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, où 0 conserve la valeur par défaut de Chromium.

• network: "host" est bloqué.
• network: "container:<id>" est bloqué par défaut (risque de contournement par jonction d’espace de noms).
• Remplacement de dernier recours : agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

​

setupCommand (configuration du conteneur en une seule fois)

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

• La valeur par défaut de docker.network est "none" (aucune sortie), donc les installations de paquets échoueront.
• docker.network: "container:<id>" exige dangerouslyAllowContainerNamespaceJoin: true et doit rester un mode de dernier recours.
• readOnlyRoot: true empêche les écritures ; définissez readOnlyRoot: false ou intégrez une image personnalisée.
• user doit être root pour les installations de paquets (omettez user ou définissez user: "0:0").
• Le sandbox exec n’hérite pas de process.env de l’hôte. Utilisez agents.defaults.sandbox.docker.env (ou une image personnalisée) pour les clés API des skills.

​

Politique des outils + échappatoires

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

​

Remplacements multi-agents

​

Exemple minimal d’activation

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

​

Documentation associée

• OpenShell — configuration du backend de sandbox géré, modes d’espace de travail et référence de configuration
• Configuration du sandbox
• Sandbox vs Tool Policy vs Elevated — déboguer « pourquoi ceci est-il bloqué ? »
• Sandbox & Tools multi-agents — remplacements par agent et ordre de priorité
• Sécurité