Docker

Docker est facultatif. Utilisez-le pour disposer d’un environnement Gateway isolé et jetable, ou sur un hôte dépourvu d’installations locales. Si vous développez déjà sur votre propre machine, utilisez plutôt le processus d’installation normal.

Le backend de bac à sable par défaut utilise Docker lorsque agents.defaults.sandbox est activé, mais le bac à sable est désactivé par défaut et n’exige pas que le Gateway lui-même s’exécute dans Docker. Les backends de bac à sable SSH et OpenShell sont également disponibles ; consultez Mise en bac à sable.

Vous hébergez plusieurs utilisateurs ? Consultez Hébergement mutualisé pour le modèle d’une cellule par locataire.

Prérequis

• Docker Desktop (ou Docker Engine) + Docker Compose v2
• Au moins 2 GB de RAM pour construire l’image (pnpm install peut être interrompu par manque de mémoire sur les hôtes disposant de 1 GB, avec le code de sortie 137)
• Suffisamment d’espace disque pour les images et les journaux
• Sur un VPS ou un hôte public, consultez Renforcement de la sécurité pour l’exposition réseau, en particulier la chaîne de pare-feu Docker DOCKER-USER

Gateway conteneurisé

./scripts/docker/setup.sh

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

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Processus manuel

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

Le contexte Docker exclut .git. Transmettez l’identité de la source comme arguments de construction, comme illustré ci-dessus, afin que l’écran À propos de l’image indique le commit extrait et un horodatage de construction. scripts/docker/setup.sh détermine et transmet automatiquement ces deux valeurs.

Mise à niveau des images de conteneur

Lorsque vous remplacez l’image OpenClaw tout en conservant le même état et la même configuration montés, le nouveau Gateway exécute avant d’être prêt les migrations de mise à niveau sûres au démarrage et la convergence des plugins. Les mises à niveau ordinaires des images ne devraient pas nécessiter une exécution distincte de openclaw doctor --fix.

Si le démarrage ne peut pas effectuer ces réparations en toute sécurité, le Gateway se ferme au lieu de signaler qu’il est opérationnel. Avec une politique de redémarrage, Docker, Podman ou Kubernetes peut indiquer que le conteneur du Gateway redémarre. Conservez le volume d’état monté, puis exécutez une fois la même image avec openclaw doctor --fix comme commande du conteneur, en utilisant les mêmes montages d’état et de configuration que le Gateway :

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

Une fois doctor terminé, redémarrez le conteneur du Gateway avec sa commande par défaut. Dans Kubernetes, exécutez la même commande dans un Job ponctuel ou un pod de débogage monté sur le même PVC, puis redémarrez le Deployment ou le StatefulSet.

Variables d’environnement

Variables facultatives acceptées par scripts/docker/setup.sh (et, pour le conteneur du Gateway, directement par docker-compose.yml) :

L’image officielle ne contient pas Homebrew. Pendant l’intégration initiale, OpenClaw masque les programmes d’installation des dépendances de Skills réservés à brew dans un conteneur Linux dépourvu de brew ; fournissez ces dépendances au moyen d’une image personnalisée ou installez-les manuellement. Utilisez OPENCLAW_IMAGE_APT_PACKAGES pour les dépendances empaquetées pour Debian et OPENCLAW_IMAGE_PIP_PACKAGES pour les dépendances Python (exécute python3 -m pip install --break-system-packages lors de la construction ; épinglez donc les versions et utilisez uniquement des index auxquels vous faites confiance).

Si Docker signale ResourceExhausted, cannot allocate memory, ou s’interrompt pendant tsdown, augmentez la limite de mémoire du constructeur Docker ou réessayez avec des tas explicites plus petits :

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

Images construites depuis les sources avec des plugins sélectionnés

OPENCLAW_EXTENSIONS sélectionne les identifiants de manifeste de Plugin dans le dépôt source ; les noms de répertoires source existants sont également acceptés lorsqu’ils diffèrent. La construction Docker résout une seule fois la sélection en répertoires source, installe les dépendances de production et, lorsqu’un Plugin sélectionné est publié séparément avec openclaw.build.bundledDist: false, compile son environnement d’exécution dans le répertoire dist groupé racine. Ce conditionnement propre à Docker ne modifie pas le contrat d’artefact npm ou ClawHub du Plugin. Les identifiants inconnus, non valides ou ambigus font échouer la construction de l’image. Les identifiants connus réservés aux dépendances ou aux sources conservent leur préparation existante des sources et des dépendances sans obtenir d’entrée dist racine compilée. Un Plugin sélectionné avec des entrées de construction unifiées doit être compilé correctement ; les sources et la sortie d’exécution des Plugins externes non sélectionnés sont supprimées.

Par exemple, ces commandes construisent des images Gateway autonomes, distinctes et multi-architectures de FakeCo pour ClickClack, Slack et Microsoft Teams. ClawRouter fait déjà partie de l’environnement d’exécution OpenClaw racine ; l’image ClickClack sélectionne donc uniquement clickclack. L’argument de navigateur explicitement vide permet de conserver l’image par défaut sans Chromium :

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

Utilisez --platform linux/arm64 --load ou --platform linux/amd64 --load pour une seule construction locale native. Une sortie multiplateforme ainsi que les SBOM et données de provenance joints nécessitent un registre ou une autre sortie Buildx qui préserve les attestations. Après l’envoi, inspectez le manifeste et déployez le condensat immuable plutôt que l’étiquette mutable fondée sur le SHA source :

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Déployer : registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

Ces images sont destinées aux Gateway autonomes fondés sur OCI et aux utilisateurs génériques de Docker. Les Gateway gérés par Crabhelm ne les utilisent pas : ce chemin de livraison construit une archive d’appliance x86_64 distincte contenant une archive tar npm OpenClaw et épingle les condensats de Node, de l’archive et du manifeste. Construisez cette appliance séparément à partir de la même source OpenClaw intégrée.

Pour tester la source d’un Plugin groupé avec une image conditionnée, montez un répertoire source du Plugin sur son chemin source conditionné, par exemple OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Cela remplace le paquet compilé /app/dist/extensions/synology-chat correspondant pour le même identifiant de Plugin.

Observabilité

L’export OpenTelemetry est sortant depuis le conteneur Gateway vers votre collecteur OTLP ; il ne nécessite aucun port Docker publié. Pour inclure l’exportateur groupé dans une image construite localement :

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

Les images officielles préconstruites incluent déjà diagnostics-otel ; installez vous-même clawhub:@openclaw/diagnostics-otel uniquement si vous l’avez supprimé. Pour activer l’export, autorisez et activez le Plugin diagnostics-otel dans la configuration, puis définissez diagnostics.otel.enabled=true (consultez l’exemple complet dans Export OpenTelemetry). Les en-têtes d’authentification du collecteur passent par diagnostics.otel.headers, et non par les variables d’environnement Docker.

Les métriques Prometheus réutilisent le port Gateway déjà publié. Installez clawhub:@openclaw/diagnostics-prometheus, activez le Plugin diagnostics-prometheus, puis collectez :

http://<gateway-host>:18789/api/diagnostics/prometheus

La route est protégée par l’authentification du Gateway ; n’exposez pas de port public /metrics distinct ni de chemin de proxy inverse non authentifié. Consultez Métriques Prometheus.

Contrôles d’intégrité

Points de terminaison de sonde du conteneur (aucune authentification requise) :

curl -fsS http://127.0.0.1:18789/healthz   # activitécurl -fsS http://127.0.0.1:18789/readyz     # disponibilité

Le HEALTHCHECK intégré de l’image interroge /healthz ; des échecs répétés marquent le conteneur comme unhealthy afin que les orchestrateurs puissent le redémarrer ou le remplacer.

Instantané d’intégrité approfondi authentifié :

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

LAN ou interface de bouclage

scripts/docker/setup.sh utilise par défaut OPENCLAW_GATEWAY_BIND=lan afin que http://127.0.0.1:18789 sur l’hôte fonctionne avec la publication de ports Docker.

• lan (par défaut) : le navigateur et la CLI de l’hôte peuvent atteindre le port Gateway publié.
• loopback : seuls les processus situés dans l’espace de noms réseau du conteneur peuvent atteindre directement le Gateway.

Fournisseurs locaux de l’hôte

Dans le conteneur, 127.0.0.1 désigne le conteneur lui-même, et non l’hôte. Utilisez host.docker.internal pour les fournisseurs exécutés sur l’hôte :

La configuration groupée utilise ces URL comme valeurs par défaut d’intégration de LM Studio/Ollama, et docker-compose.yml associe host.docker.internal au Gateway de l’hôte sur Docker Engine pour Linux (Docker Desktop fournit le même alias sous macOS/Windows). Les services de l’hôte doivent écouter sur une adresse accessible par Docker :

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

Vous utilisez votre propre fichier Compose ou docker run ? Ajoutez vous-même la même association, par exemple --add-host=host.docker.internal:host-gateway.

Backend Claude CLI dans Docker

L’image officielle ne préinstalle pas Claude Code. Installez-le et connectez-vous dans le conteneur avec l’utilisateur node, puis rendez persistant le répertoire personnel de ce conteneur afin que les mises à niveau de l’image n’effacent pas le binaire ni l’état d’authentification.

Pour une nouvelle installation, activez un volume persistant /home/node avant d’exécuter la configuration :

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

Pour une installation existante, arrêtez la pile et rechargez d’abord les valeurs actuelles de .env — le script de configuration réécrit toujours .env à partir de l’environnement actuel du shell et des valeurs par défaut ; il ne lit pas ce fichier de lui-même :

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

Si .env contient des valeurs que votre shell ne peut pas charger, réexportez d’abord manuellement celles dont vous dépendez (OPENCLAW_IMAGE, ports, mode de liaison, chemins personnalisés, OPENCLAW_EXTRA_MOUNTS, bac à sable, omission de l’intégration). La surcouche générée monte le volume du répertoire personnel pour openclaw-gateway et openclaw-cli ; exécutez les commandes restantes avec cette surcouche (et d’abord docker-compose.override.yml, si vous en utilisez un) :

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

Le programme d’installation natif écrit claude dans /home/node/.local/bin/claude. Indiquez ce chemin à OpenClaw :

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

Connectez-vous et vérifiez depuis le même répertoire personnel persistant :

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

Utilisez ensuite le backend claude-cli groupé :

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Dites bonjour depuis la CLI Claude dans Docker"

OPENCLAW_HOME_VOLUME rend persistants l’installation native sous /home/node/.local/bin et /home/node/.local/share/claude, ainsi que les paramètres et l’authentification de Claude Code sous /home/node/.claude et /home/node/.claude.json. Rendre persistant uniquement /home/node/.openclaw ne suffit pas ; si vous utilisez OPENCLAW_EXTRA_MOUNTS au lieu d’un volume de répertoire personnel, montez tous ces chemins Claude dans les deux services.

Bonjour / mDNS

Le réseau en pont de Docker ne transmet généralement pas de manière fiable le multicast Bonjour/mDNS (224.0.0.251:5353). Lorsque OPENCLAW_DISABLE_BONJOUR n’est pas défini, le Plugin Bonjour groupé désactive automatiquement la diffusion LAN dès qu’il détecte son exécution dans un conteneur, afin d’éviter une boucle de plantage due aux nouvelles tentatives de multicast abandonnées par le pont. Définissez OPENCLAW_DISABLE_BONJOUR=1 pour forcer sa désactivation indépendamment de la détection, ou 0 pour forcer son activation (uniquement avec le réseau de l’hôte, macvlan ou un autre réseau où le multicast mDNS est réputé fonctionner).

Sinon, utilisez l’URL Gateway publiée, Tailscale ou le DNS-SD étendu pour les hôtes Docker. Consultez Découverte Bonjour pour connaître les pièges et les procédures de dépannage.

Stockage et persistance

Docker Compose monte par liaison OPENCLAW_CONFIG_DIR sur /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR sur /home/node/.openclaw/workspace et OPENCLAW_AUTH_PROFILE_SECRET_DIR sur /home/node/.config/openclaw, afin que ces chemins survivent au remplacement du conteneur. Lorsqu’une variable n’est pas définie, docker-compose.yml utilise un chemin de secours sous ${HOME}, ou sous /tmp si HOME lui-même est absent, de sorte que docker compose up ne génère jamais de spécification de volume avec une source vide dans les environnements minimaux.

Ce répertoire de configuration monté contient :

• openclaw.json pour la configuration du comportement
• agents/<agentId>/agent/auth-profiles.json pour l’authentification OAuth/par clé d’API stockée des fournisseurs
• .env pour les secrets d’exécution fournis par l’environnement, tels que OPENCLAW_GATEWAY_TOKEN

Le répertoire de secrets des profils d’authentification stocke la clé de chiffrement locale du contenu des jetons de profils d’authentification fondés sur OAuth. Conservez-le avec l’état de votre hôte Docker, mais séparément de OPENCLAW_CONFIG_DIR.

Les Plugins téléchargeables installés stockent l’état de leurs paquets sous le répertoire personnel OpenClaw monté, de sorte que les enregistrements d’installation et les racines des paquets survivent au remplacement du conteneur ; le démarrage du Gateway ne régénère pas les arborescences de dépendances des Plugins groupés.

Pour obtenir tous les détails sur la persistance des machines virtuelles, consultez Environnement d’exécution de machine virtuelle Docker — Emplacements des données persistantes.

Principales sources de croissance du disque : media/, les bases de données SQLite propres à chaque agent, les transcriptions JSONL de sessions héritées, la base de données d’état SQLite partagée, les racines de paquets des Plugins installés et les journaux de fichiers tournants sous /tmp/openclaw/.

Assistants shell (facultatif)

Pour raccourcir les commandes quotidiennes, installez ClawDock :

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Si vous avez effectué l’installation depuis l’ancien chemin scripts/shell-helpers/clawdock-helpers.sh, réexécutez la commande ci-dessus afin que votre assistant local suive l’emplacement actuel. Utilisez ensuite clawdock-start, clawdock-stop, clawdock-dashboard, etc. (exécutez clawdock-help pour obtenir la liste complète).

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

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

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

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

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

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Exécution sur un VPS ?

Consultez Hetzner (VPS Docker) et Environnement d’exécution de VM Docker pour connaître les étapes de déploiement sur une VM partagée, notamment l’intégration des binaires, la persistance et les mises à jour.

Bac à sable de l’agent

Lorsque agents.defaults.sandbox est activé avec le backend Docker, le Gateway exécute les outils de l’agent (shell, lecture/écriture de fichiers, etc.) dans des conteneurs Docker isolés, tandis que le Gateway lui-même reste sur l’hôte : une séparation stricte autour des sessions d’agent non fiables ou mutualisées, sans conteneuriser l’ensemble du Gateway.

La portée du bac à sable peut être définie par agent (valeur par défaut), par session ou être partagée ; chaque portée dispose de son propre espace de travail monté dans /workspace. Vous pouvez également configurer des politiques d’autorisation ou de refus des outils, l’isolation réseau, les limites de ressources et les conteneurs de navigateur.

Pour obtenir la configuration complète, les images, les remarques de sécurité et les profils multi-agents :

• Mise en bac à sable -- référence complète du bac à sable
• OpenShell -- accès interactif au shell des conteneurs de bac à sable
• Bac à sable et outils multi-agents -- remplacements par agent

Activation rapide

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // désactivé | non principal | tous        scope: "agent", // session | agent | partagé      },    },  },}

Construisez l’image de bac à sable par défaut (depuis un dépôt source extrait) :

scripts/sandbox-setup.sh

Pour les installations npm sans dépôt source extrait, consultez Mise en bac à sable § Images et configuration pour obtenir les commandes docker build intégrées.

Dépannage

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Contenu associé

• Présentation de l’installation — toutes les méthodes d’installation
• Podman — alternative à Docker avec Podman
• ClawDock — configuration communautaire de Docker Compose
• Mise à jour — maintenir OpenClaw à jour
• Configuration — configuration du Gateway après l’installation