Isolation en bac à sable

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

• Le processus Gateway lui-même.
• Tout outil explicitement autorisé à s’exécuter en dehors du bac à sable (par ex. tools.elevated).
  • L’exécution élevée contourne le bac à sable et utilise le chemin d’échappement 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 pas l’exécution (déjà sur l’hôte). Voir Mode élevé.

​

Modes

​

Portée

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

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

​

Choisir un backend

​

Backend Docker

​

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",
          // 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

{
  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 vers OpenShell avant l’exécution et synchronise l’espace de travail distant en retour après l’exécution.
• remote : l’espace de travail OpenShell est canonique après la création du bac à sable. OpenClaw ensemence une fois l’espace de travail distant depuis l’espace de travail local, puis les outils de fichiers et l’exécution s’effectuent directement sur le bac à sable distant sans synchroniser les changements en retour.

​

Modes d’espace de travail

​

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 à la prochaine utilisation
• la logique d’élagage tient aussi compte du backend

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

​

Accès à l’espace de travail

• 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" restreignent toujours 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 se rabat sur agents.defaults.sandbox.docker.binds (rétrocompatible).

{
  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 unique du conteneur)

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

​

Politique des outils et échappatoires

• 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 est-ce bloqué ? ».

​

Remplacements multi-agents

​

Exemple minimal d’activation

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

​

Connexe

• Multi-Agent Sandbox & Tools — 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 la sandbox
• Sandbox vs Tool Policy vs Elevated — débogage de « pourquoi est-ce bloqué ? »
• Sécurité