Docker (optionnel)

Docker est optionnel. Utilisez-le uniquement si vous souhaitez une passerelle containerisee ou valider le flux Docker.

Docker est-il fait pour vous ?

Oui : vous voulez un environnement de passerelle isole et jetable, ou executer OpenClaw sur un hote sans installations locales.
Non : vous travaillez sur votre propre machine et voulez la boucle de developpement la plus rapide. Utilisez plutot le flux d’installation classique.
Note sur le sandboxing : le sandboxing des agents utilise aussi Docker, mais il ne necessite pas que la passerelle complete tourne dans Docker. Consultez Sandboxing.

Ce guide couvre :

Passerelle containerisee (OpenClaw complet dans Docker)
Sandbox d’agent par session (passerelle sur l’hote + outils d’agent isoles via Docker)

Details du sandboxing : Sandboxing

Pre-requis

Docker Desktop (ou Docker Engine) + Docker Compose v2
Au moins 2 Go de RAM pour la construction de l’image (pnpm install peut etre tue par OOM sur les hotes a 1 Go avec exit 137)
Suffisamment d’espace disque pour les images + logs
Si vous executez sur un VPS/hote public, consultez Renforcement de la securite pour l’exposition reseau, en particulier la politique pare-feu Docker DOCKER-USER.

Passerelle containerisee (Docker Compose)

Demarrage rapide (recommande)

Remarque : Les valeurs par defaut Docker ici supposent des modes de liaison (lan/loopback), pas des alias d’hote. Utilisez les valeurs de mode de liaison dans gateway.bind (par exemple lan ou loopback), pas des alias d’hote comme 0.0.0.0 ou localhost.

Depuis la racine du depot :

./docker-setup.sh

Ce script :

construit l’image de la passerelle localement (ou tire une image distante si OPENCLAW_IMAGE est defini)
lance l’assistant d’accueil
affiche des indications optionnelles pour la configuration des fournisseurs
demarre la passerelle via Docker Compose
genere un token de passerelle et l’ecrit dans .env

Variables d’environnement optionnelles :

OPENCLAW_IMAGE — utiliser une image distante au lieu de compiler localement (par ex. ghcr.io/openclaw/openclaw:latest)
OPENCLAW_DOCKER_APT_PACKAGES — installer des paquets apt supplementaires pendant la construction
OPENCLAW_EXTENSIONS — pre-installer les dependances d’extensions au moment de la construction (noms d’extensions separes par des espaces, par ex. diagnostics-otel matrix)
OPENCLAW_EXTRA_MOUNTS — ajouter des montages bind supplementaires de l’hote
OPENCLAW_HOME_VOLUME — persister /home/node dans un volume nomme
OPENCLAW_SANDBOX — activer le bootstrap sandbox de la passerelle Docker. Seules les valeurs explicitement vraies l’activent : 1, true, yes, on
OPENCLAW_INSTALL_DOCKER_CLI — argument de construction pour les builds locaux d’image (1 installe le CLI Docker dans l’image). docker-setup.sh le definit automatiquement quand OPENCLAW_SANDBOX=1 pour les builds locaux.
OPENCLAW_DOCKER_SOCKET — chemin du socket Docker personnalise (par defaut : chemin DOCKER_HOST=unix://..., sinon /var/run/docker.sock)
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — mode derogatoire : autoriser les cibles ws:// de reseau prive de confiance pour les chemins client CLI/accueil (par defaut : loopback uniquement)
OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — desactiver les drapeaux de renforcement du navigateur conteneurise --disable-3d-apis, --disable-software-rasterizer, --disable-gpu si vous avez besoin de compatibilite WebGL/3D.
OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — garder les extensions activees quand les flux du navigateur les necessitent (par defaut, les extensions sont desactivees dans le navigateur sandbox).
OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> — definir la limite de processus de rendu Chromium ; mettez 0 pour ne pas passer le drapeau et utiliser le comportement par defaut de Chromium.

Une fois termine :

Ouvrez http://127.0.0.1:18789/ dans votre navigateur.
Collez le token dans l’interface de controle (Parametres → token).
Besoin de l’URL a nouveau ? Executez docker compose run --rm openclaw-cli dashboard --no-open.

Activer le sandbox d’agent pour la passerelle Docker (opt-in)

docker-setup.sh peut aussi configurer agents.defaults.sandbox.* pour les deploiements Docker.

Activez avec :

export OPENCLAW_SANDBOX=1
./docker-setup.sh

Chemin de socket personnalise (par exemple Docker rootless) :

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

Notes :

Le script monte docker.sock uniquement apres validation des pre-requis sandbox.
Si la configuration sandbox ne peut pas etre completee, le script reinitialise agents.defaults.sandbox.mode a off pour eviter une configuration sandbox obsolete/cassee lors des re-executions.
Si Dockerfile.sandbox est manquant, le script affiche un avertissement et continue ; construisez openclaw-sandbox:bookworm-slim avec scripts/sandbox-setup.sh si necessaire.
Pour les valeurs non locales de OPENCLAW_IMAGE, l’image doit deja contenir le support du CLI Docker pour l’execution sandbox.

Automatisation/CI (non-interactif, pas de bruit TTY)

Pour les scripts et le CI, desactivez l’allocation pseudo-TTY de Compose avec -T :

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

Si votre automatisation n’exporte pas de variables de session Claude, les laisser non definies se resout desormais en valeurs vides par defaut dans docker-compose.yml pour eviter les avertissements repetes “variable is not set”.

Note de securite reseau partage (CLI + passerelle)

openclaw-cli utilise network_mode: "service:openclaw-gateway" pour que les commandes CLI puissent atteindre de facon fiable la passerelle via 127.0.0.1 dans Docker.

Considerez cela comme une frontiere de confiance partagee : la liaison loopback n’est pas une isolation entre ces deux conteneurs. Si vous avez besoin d’une separation plus forte, executez les commandes depuis un conteneur/chemin reseau hote separe au lieu du service openclaw-cli fourni.

Pour reduire l’impact en cas de compromission du processus CLI, la configuration compose supprime NET_RAW/NET_ADMIN et active no-new-privileges sur openclaw-cli.

Il ecrit la configuration/l’espace de travail sur l’hote :

~/.openclaw/
~/.openclaw/workspace

Vous executez sur un VPS ? Consultez Hetzner (Docker VPS).

Utiliser une image distante (sauter la construction locale)

Les images pre-construites officielles sont publiees sur :

Package GitHub Container Registry

Utilisez le nom d’image ghcr.io/openclaw/openclaw (pas les images Docker Hub portant un nom similaire).

Tags courants :

main — dernier build depuis main
<version> — builds de tags de release (par exemple 2026.2.26)
latest — derniere release stable

Metadonnees de l’image de base

L’image Docker principale utilise actuellement :

node:24-bookworm

L’image Docker publie desormais des annotations OCI de l’image de base (le sha256 est un exemple et pointe vers la liste de manifestes multi-arch epinglee pour ce tag) :

org.opencontainers.image.base.name=docker.io/library/node:24-bookworm
org.opencontainers.image.base.digest=sha256:3a09aa6354567619221ef6c45a5051b671f953f0a1924d1f819ffb236e520e6b
org.opencontainers.image.source=https://github.com/openclaw/openclaw
org.opencontainers.image.url=https://openclaw.ai
org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker
org.opencontainers.image.licenses=MIT
org.opencontainers.image.title=OpenClaw
org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image
org.opencontainers.image.revision=<git-sha>
org.opencontainers.image.version=<tag-or-main>
org.opencontainers.image.created=<rfc3339 timestamp>

Reference : Annotations d’images OCI

Contexte de release : l’historique des tags de ce depot utilise deja Bookworm dans v2026.2.22 et les tags anterieurs de 2026 (par exemple v2026.2.21, v2026.2.9).

Par defaut, le script de configuration construit l’image depuis les sources. Pour tirer une image pre-construite a la place, definissez OPENCLAW_IMAGE avant d’executer le script :

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

Le script detecte que OPENCLAW_IMAGE n’est pas la valeur par defaut openclaw:local et execute docker pull au lieu de docker build. Tout le reste (accueil, demarrage de la passerelle, generation du token) fonctionne de la meme maniere.

docker-setup.sh s’execute toujours depuis la racine du depot car il utilise le docker-compose.yml local et les fichiers utilitaires. OPENCLAW_IMAGE saute le temps de construction de l’image locale ; il ne remplace pas le workflow compose/setup.

Utilitaires shell (optionnel)

Pour une gestion quotidienne plus facile de Docker, installez ClawDock :

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

Ajoutez a votre configuration shell (zsh) :

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Utilisez ensuite clawdock-start, clawdock-stop, clawdock-dashboard, etc. Executez clawdock-help pour toutes les commandes.

Consultez le README ClawDock Helper pour les details.

Flux manuel (compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

A noter : executez docker compose ... depuis la racine du depot. Si vous avez active OPENCLAW_EXTRA_MOUNTS ou OPENCLAW_HOME_VOLUME, le script de configuration ecrit docker-compose.extra.yml ; incluez-le quand vous utilisez Compose ailleurs :

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Token de l’interface de controle + appairage (Docker)

Si vous voyez “unauthorized” ou “disconnected (1008): pairing required”, recuperez un lien de tableau de bord frais et approuvez le peripherique navigateur :

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Plus de details : Dashboard, Peripheriques.

Montages supplementaires (optionnel)

Si vous voulez monter des repertoires hote supplementaires dans les conteneurs, definissez OPENCLAW_EXTRA_MOUNTS avant d’executer docker-setup.sh. Cela accepte une liste separee par des virgules de montages bind Docker et les applique a la fois a openclaw-gateway et openclaw-cli en generant docker-compose.extra.yml.

Exemple :

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Notes :

Les chemins doivent etre partages avec Docker Desktop sur macOS/Windows.
Chaque entree doit etre au format source:target[:options] sans espaces, tabulations ni retours a la ligne.
Si vous modifiez OPENCLAW_EXTRA_MOUNTS, relancez docker-setup.sh pour regenerer le fichier compose supplementaire.
docker-compose.extra.yml est genere. Ne le modifiez pas manuellement.

Persister le home complet du conteneur (optionnel)

Si vous voulez que /home/node persiste apres la recreation du conteneur, definissez un volume nomme via OPENCLAW_HOME_VOLUME. Cela cree un volume Docker et le monte a /home/node, tout en gardant les montages bind standard config/workspace. Utilisez un volume nomme ici (pas un chemin bind) ; pour les montages bind, utilisez OPENCLAW_EXTRA_MOUNTS.

Exemple :

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Vous pouvez combiner cela avec des montages supplementaires :

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Notes :

Les volumes nommes doivent correspondre a ^[A-Za-z0-9][A-Za-z0-9_.-]*$.
Si vous changez OPENCLAW_HOME_VOLUME, relancez docker-setup.sh pour regenerer le fichier compose supplementaire.
Le volume nomme persiste jusqu’a suppression avec docker volume rm <name>.

Installer des paquets apt supplementaires (optionnel)

Si vous avez besoin de paquets systeme dans l’image (par exemple, des outils de compilation ou des bibliotheques multimedia), definissez OPENCLAW_DOCKER_APT_PACKAGES avant d’executer docker-setup.sh. Cela installe les paquets pendant la construction de l’image, afin qu’ils persistent meme si le conteneur est supprime.

Exemple :

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Notes :

Cela accepte une liste de noms de paquets apt separes par des espaces.
Si vous changez OPENCLAW_DOCKER_APT_PACKAGES, relancez docker-setup.sh pour reconstruire l’image.

Pre-installer les dependances d’extensions (optionnel)

Les extensions avec leur propre package.json (par ex. diagnostics-otel, matrix, msteams) installent leurs dependances npm au premier chargement. Pour integrer ces dependances dans l’image, definissez OPENCLAW_EXTENSIONS avant d’executer docker-setup.sh :

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

Ou lors de la construction directe :

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .

Notes :

Cela accepte une liste de noms de repertoires d’extensions separes par des espaces (sous extensions/).
Seules les extensions avec un package.json sont concernees ; les plugins legers sans en sont ignores.
Si vous changez OPENCLAW_EXTENSIONS, relancez docker-setup.sh pour reconstruire l’image.

Conteneur complet / utilisateur avance (opt-in)

L’image Docker par defaut est axee sur la securite et s’execute en tant qu’utilisateur non-root node. Cela reduit la surface d’attaque, mais implique :

pas d’installation de paquets systeme a l’execution
pas de Homebrew par defaut
pas de navigateurs Chromium/Playwright inclus

Si vous voulez un conteneur plus complet, utilisez ces options opt-in :

Persister /home/node pour que les telechargements de navigateurs et les caches d’outils survivent :

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Integrer les dependances systeme dans l’image (reproductible + persistant) :

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

Installer les navigateurs Playwright sans npx (evite les conflits de surcharge npm) :

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Si vous avez besoin que Playwright installe les dependances systeme, reconstruisez l’image avec OPENCLAW_DOCKER_APT_PACKAGES au lieu d’utiliser --with-deps a l’execution.

Persister les telechargements de navigateurs Playwright :

Definissez PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright dans docker-compose.yml.
Assurez-vous que /home/node persiste via OPENCLAW_HOME_VOLUME, ou montez /home/node/.cache/ms-playwright via OPENCLAW_EXTRA_MOUNTS.

Permissions + EACCES

L’image s’execute en tant que node (uid 1000). Si vous voyez des erreurs de permission sur /home/node/.openclaw, assurez-vous que vos montages bind hote appartiennent a l’uid 1000.

Exemple (hote Linux) :

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Si vous choisissez de s’executer en tant que root par commodite, vous acceptez le compromis de securite.

Reconstructions plus rapides (recommande)

Pour accelerer les reconstructions, ordonnez votre Dockerfile afin que les couches de dependances soient en cache. Cela evite de relancer pnpm install sauf si les lockfiles changent :

FROM node:24-bookworm

# Installer Bun (necessaire pour les scripts de build)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Mettre en cache les dependances sauf si les metadonnees de package changent
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

Configuration des canaux (optionnel)

Utilisez le conteneur CLI pour configurer les canaux, puis redemarrez la passerelle si necessaire.

WhatsApp (QR) :

docker compose run --rm openclaw-cli channels login

Telegram (token de bot) :

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord (token de bot) :

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Docs : WhatsApp, Telegram, Discord

OpenAI Codex OAuth (Docker headless)

Si vous choisissez OpenAI Codex OAuth dans l’assistant, il ouvre une URL de navigateur et tente de capturer un callback sur http://127.0.0.1:1455/auth/callback. Dans Docker ou les configurations headless, ce callback peut afficher une erreur de navigateur. Copiez l’URL complete de redirection sur laquelle vous atterrissez et collez-la dans l’assistant pour terminer l’authentification.

Verifications de sante

Points de terminaison de sonde du conteneur (pas d’authentification requise) :

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

Alias : /health et /ready.

/healthz est une sonde de vivacite superficielle pour “le processus de passerelle est actif”. /readyz reste pret pendant la grace de demarrage, puis passe en 503 uniquement si les canaux geres requis sont toujours deconnectes apres la grace ou se deconnectent plus tard.

L’image Docker inclut un HEALTHCHECK integre qui ping /healthz en arriere-plan. En termes simples : Docker verifie continuellement si OpenClaw est toujours reactif. Si les verifications echouent, Docker marque le conteneur comme unhealthy, et les systemes d’orchestration (politique de redemarrage Docker Compose, Swarm, Kubernetes, etc.) peuvent le redemarrer ou le remplacer automatiquement.

Instantane de sante approfondi authentifie (passerelle + canaux) :

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Test de bout en bout (Docker)

scripts/e2e/onboard-docker.sh

Test d’import QR (Docker)

pnpm test:docker:qr

LAN vs loopback (Docker Compose)

docker-setup.sh definit par defaut OPENCLAW_GATEWAY_BIND=lan pour que l’acces hote a http://127.0.0.1:18789 fonctionne avec la publication de ports Docker.

lan (par defaut) : le navigateur hote + le CLI hote peuvent atteindre le port publie de la passerelle.
loopback : seuls les processus a l’interieur du namespace reseau du conteneur peuvent atteindre la passerelle directement ; l’acces au port publie sur l’hote peut echouer.

Le script de configuration fixe aussi gateway.mode=local apres l’accueil pour que les commandes CLI Docker ciblent par defaut le loopback local.

Note sur la configuration legacy : utilisez les valeurs de mode de liaison dans gateway.bind (lan / loopback / custom / tailnet / auto), pas les alias d’hote (0.0.0.0, 127.0.0.1, localhost, ::, ::1).

Si vous voyez Gateway target: ws://172.x.x.x:18789 ou des erreurs repetees pairing required depuis les commandes CLI Docker, executez :

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Notes

La liaison de la passerelle est par defaut lan pour l’utilisation en conteneur (OPENCLAW_GATEWAY_BIND).
Le CMD du Dockerfile utilise --allow-unconfigured ; une configuration montee avec gateway.mode different de local demarrera quand meme. Surchargez le CMD pour forcer la garde.
Le conteneur de la passerelle est la reference pour les sessions (~/.openclaw/agents/<agentId>/sessions/).

Modele de stockage

Donnees hote persistantes : Docker Compose monte en bind OPENCLAW_CONFIG_DIR vers /home/node/.openclaw et OPENCLAW_WORKSPACE_DIR vers /home/node/.openclaw/workspace, de sorte que ces chemins survivent au remplacement du conteneur.
tmpfs sandbox ephemere : quand agents.defaults.sandbox est active, les conteneurs sandbox utilisent tmpfs pour /tmp, /var/tmp et /run. Ces montages sont separes du stack Compose principal et disparaissent avec le conteneur sandbox.
Points chauds de croissance disque : surveillez media/, agents/<agentId>/sessions/sessions.json, les fichiers JSONL de transcription, cron/runs/*.jsonl et les logs fichier rotatifs sous /tmp/openclaw/ (ou votre logging.file configure). Si vous executez aussi l’app macOS en dehors de Docker, ses logs de service sont separes : ~/.openclaw/logs/gateway.log, ~/.openclaw/logs/gateway.err.log et /tmp/openclaw/openclaw-gateway.log.

Sandbox d’agent (passerelle hote + outils Docker)

Pour approfondir : Sandboxing

Fonctionnement

Quand agents.defaults.sandbox est active, les sessions non principales executent les outils dans un conteneur Docker. La passerelle reste sur votre hote, mais l’execution des outils est isolee :

scope : "agent" par defaut (un conteneur + espace de travail par agent)
scope : "session" pour une isolation par session
dossier d’espace de travail par scope monte a /workspace
acces optionnel a l’espace de travail de l’agent (agents.defaults.sandbox.workspaceAccess)
politique d’outils autoriser/refuser (le refus l’emporte)
les medias entrants sont copies dans l’espace de travail sandbox actif (media/inbound/*) pour que les outils puissent les lire (avec workspaceAccess: "rw", cela arrive dans l’espace de travail de l’agent)

Attention : scope: "shared" desactive l’isolation inter-sessions. Toutes les sessions partagent un conteneur et un espace de travail.

Profils sandbox par agent (multi-agent)

Si vous utilisez le routage multi-agent, chaque agent peut surcharger les parametres sandbox + outils : agents.list[].sandbox et agents.list[].tools (plus agents.list[].tools.sandbox.tools). Cela vous permet d’executer des niveaux d’acces mixtes sur une seule passerelle :

Acces complet (agent personnel)
Outils en lecture seule + espace de travail en lecture seule (agent familial/professionnel)
Pas d’outils de systeme de fichiers/shell (agent public)

Consultez Multi-Agent Sandbox & Tools pour les exemples, la priorite et le depannage.

Comportement par defaut

Image : openclaw-sandbox:bookworm-slim
Un conteneur par agent
Acces a l’espace de travail de l’agent : workspaceAccess: "none" (par defaut) utilise ~/.openclaw/sandboxes
- "ro" garde l’espace de travail sandbox a /workspace et monte l’espace de travail de l’agent en lecture seule a /agent (desactive write/edit/apply_patch)
- "rw" monte l’espace de travail de l’agent en lecture/ecriture a /workspace
Nettoyage automatique : inactif > 24h OU age > 7j
Reseau : none par defaut (opt-in explicite si vous avez besoin de sortie)
- host est bloque.
- container:<id> est bloque par defaut (risque de jonction de namespace).
Autorise par defaut : exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
Refuse par defaut : browser, canvas, nodes, cron, discord, gateway

Activer le sandboxing

Si vous prevoyez d’installer des paquets dans setupCommand, notez :

Le docker.network par defaut est "none" (pas de sortie).
docker.network: "host" est bloque.
docker.network: "container:<id>" est bloque par defaut.
Mode derogatoire : agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.
readOnlyRoot: true bloque l’installation de paquets.
user doit etre root pour apt-get (omettez user ou definissez user: "0:0"). OpenClaw recree automatiquement les conteneurs quand setupCommand (ou la config docker) change sauf si le conteneur a ete recemment utilise (dans les ~5 minutes). Les conteneurs actifs journalisent un avertissement avec la commande exacte openclaw sandbox recreate ....

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent par defaut)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 desactive le nettoyage par inactivite
          maxAgeDays: 7, // 0 desactive le nettoyage par age maximum
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Les options de renforcement se trouvent sous agents.defaults.sandbox.docker : network, user, pidsLimit, memory, memorySwap, cpus, ulimits, seccompProfile, apparmorProfile, dns, extraHosts, dangerouslyAllowContainerNamespaceJoin (mode derogatoire uniquement).

Multi-agent : surchargez agents.defaults.sandbox.{docker,browser,prune}.* par agent via agents.list[].sandbox.{docker,browser,prune}.* (ignore quand agents.defaults.sandbox.scope / agents.list[].sandbox.scope est "shared").

Construire l’image sandbox par defaut

scripts/sandbox-setup.sh

Cela construit openclaw-sandbox:bookworm-slim en utilisant Dockerfile.sandbox.

Image sandbox commune (optionnel)

Si vous voulez une image sandbox avec des outils de compilation courants (Node, Go, Rust, etc.), construisez l’image commune :

scripts/sandbox-common-setup.sh

Cela construit openclaw-sandbox-common:bookworm-slim. Pour l’utiliser :

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

Image sandbox navigateur

Pour executer l’outil navigateur dans le sandbox, construisez l’image navigateur :

scripts/sandbox-browser-setup.sh

Cela construit openclaw-sandbox-browser:bookworm-slim en utilisant Dockerfile.sandbox-browser. Le conteneur execute Chromium avec CDP active et un observateur noVNC optionnel (affichage via Xvfb).

Notes :

L’affichage (Xvfb) reduit le blocage par les bots par rapport au mode headless.
Le mode headless peut toujours etre utilise en definissant agents.defaults.sandbox.browser.headless=true.
Aucun environnement de bureau complet (GNOME) n’est necessaire ; Xvfb fournit l’affichage.
Les conteneurs navigateur utilisent par defaut un reseau Docker dedie (openclaw-sandbox-browser) au lieu du bridge global.
L’option agents.defaults.sandbox.browser.cdpSourceRange permet de restreindre l’ingres CDP en bordure de conteneur par CIDR (par exemple 172.21.0.1/32).
L’acces observateur noVNC est protege par mot de passe par defaut ; OpenClaw fournit une URL de token observateur a duree limitee qui sert une page bootstrap locale et garde le mot de passe dans le fragment d’URL (et non dans les parametres d’URL).
Les parametres par defaut du demarrage du conteneur navigateur sont conservateurs pour les charges partagees/conteneurisees, incluant :
- --remote-debugging-address=127.0.0.1
- --remote-debugging-port=<derive de OPENCLAW_BROWSER_CDP_PORT>
- --user-data-dir=${HOME}/.chrome
- --no-first-run
- --no-default-browser-check
- --disable-3d-apis
- --disable-software-rasterizer
- --disable-gpu
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --metrics-recording-only
- --renderer-process-limit=2
- --no-zygote
- --disable-extensions
- Si agents.defaults.sandbox.browser.noSandbox est defini, --no-sandbox et --disable-setuid-sandbox sont aussi ajoutes.
- Les trois drapeaux de renforcement graphique ci-dessus sont optionnels. Si votre charge a besoin de WebGL/3D, definissez OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 pour s’executer sans --disable-3d-apis, --disable-software-rasterizer et --disable-gpu.
- Le comportement des extensions est controle par --disable-extensions et peut etre desactive (active les extensions) via OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 pour les pages dependantes des extensions ou les workflows lourds en extensions.
- --renderer-process-limit=2 est aussi configurable avec OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT ; mettez 0 pour laisser Chromium choisir sa limite de processus par defaut quand la concurrence du navigateur doit etre ajustee.

Les valeurs par defaut sont appliquees dans l’image fournie. Si vous avez besoin de drapeaux Chromium differents, utilisez une image navigateur personnalisee et fournissez votre propre point d’entree.

Configuration a utiliser :

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Image navigateur personnalisee :

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

Une fois active, l’agent recoit :

une URL de controle du navigateur sandbox (pour l’outil browser)
une URL noVNC (si active et headless=false)

N’oubliez pas : si vous utilisez une liste d’autorisation pour les outils, ajoutez browser (et retirez-le de deny) sinon l’outil reste bloque. Les regles de nettoyage (agents.defaults.sandbox.prune) s’appliquent aussi aux conteneurs navigateur.

Image sandbox personnalisee

Construisez votre propre image et pointez la configuration vers elle :

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

Politique d’outils (autoriser/refuser)

deny l’emporte sur allow.
Si allow est vide : tous les outils (sauf deny) sont disponibles.
Si allow n’est pas vide : seuls les outils dans allow sont disponibles (moins deny).

Strategie de nettoyage

Deux options :

prune.idleHours : supprimer les conteneurs non utilises depuis X heures (0 = desactiver)
prune.maxAgeDays : supprimer les conteneurs plus vieux que X jours (0 = desactiver)

Exemple :

Garder les sessions actives mais limiter la duree de vie : idleHours: 24, maxAgeDays: 7
Ne jamais nettoyer : idleHours: 0, maxAgeDays: 0

Notes de securite

La barriere stricte ne s’applique qu’aux outils (exec/read/write/edit/apply_patch).
Les outils hote uniquement comme browser/camera/canvas sont bloques par defaut.
Autoriser browser dans le sandbox casse l’isolation (le navigateur tourne sur l’hote).

Depannage

Image manquante : construisez avec scripts/sandbox-setup.sh ou definissez agents.defaults.sandbox.docker.image.
Conteneur non en cours d’execution : il sera cree automatiquement par session a la demande.
Erreurs de permission dans le sandbox : definissez docker.user sur un UID:GID correspondant a la propriete de votre espace de travail monte (ou changez le proprietaire du dossier workspace).
Outils personnalises introuvables : OpenClaw execute les commandes avec sh -lc (shell de connexion), qui source /etc/profile et peut reinitialiser PATH. Definissez docker.env.PATH pour prependre vos chemins d’outils personnalises (par ex. /custom/bin:/usr/local/share/npm-global/bin), ou ajoutez un script sous /etc/profile.d/ dans votre Dockerfile.