Mise en bac à sable

​

É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).

• 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

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

• 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).

​

Backend Docker

​

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

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

• 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

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

​

Accès à l’espace de travail

​

Montages bind personnalisés

{
  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

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

​

setupCommand (configuration ponctuelle du conteneur)

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

​

Stratégie des outils et échappatoires

• 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

​

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é