Docker

Docker est facultatif. Utilisez-le uniquement si vous voulez un Gateway conteneurisé ou valider le flux Docker.

Docker me convient-il ?

• Oui : vous voulez un environnement de Gateway isolé et jetable, ou exécuter OpenClaw sur un hôte sans installations locales.
• Non : vous exécutez OpenClaw sur votre propre machine et voulez simplement la boucle de développement la plus rapide. Utilisez plutôt le flux d’installation normal.
• Note sur le bac à sable : le backend de bac à sable par défaut utilise Docker quand le bac à sable est activé, mais le bac à sable est désactivé par défaut et ne nécessite pas que le Gateway complet s’exécute dans Docker. Les backends de bac à sable SSH et OpenShell sont également disponibles. Voir Bac à sable.

Prérequis

• Docker Desktop (ou Docker Engine) + Docker Compose v2
• Au moins 2 Go de RAM pour la construction de l’image (pnpm install peut être tué par manque de mémoire sur des hôtes de 1 Go avec le code de sortie 137)
• Suffisamment d’espace disque pour les images et les journaux
• En cas d’exécution sur un VPS/hôte public, consultez Durcissement de la sécurité pour l’exposition réseau, en particulier la politique 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>"

Flux manuel

Si vous préférez exécuter chaque étape vous-même au lieu d’utiliser le script de configuration :

docker build -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

Variables d’environnement

Le script de configuration accepte ces variables d’environnement facultatives :

L’image Docker officielle n’inclut pas Homebrew. Pendant l’intégration, OpenClaw masque les installateurs de dépendances de Skills réservés à brew quand il s’exécute dans un conteneur Linux sans brew ; ces dépendances doivent être fournies par une image personnalisée ou installées manuellement. Pour les dépendances disponibles sous forme de paquets Debian, utilisez OPENCLAW_IMAGE_APT_PACKAGES pendant la construction de l’image. L’ancien nom OPENCLAW_DOCKER_APT_PACKAGES est toujours accepté. Pour les dépendances Python, utilisez OPENCLAW_IMAGE_PIP_PACKAGES. Cela exécute python3 -m pip install --break-system-packages pendant la construction de l’image ; épinglez donc les versions des paquets et utilisez uniquement des index de paquets auxquels vous faites confiance. Les constructions depuis les sources définissent par défaut OPENCLAW_DOCKER_BUILD_NODE_OPTIONS sur --max-old-space-size=8192 et laissent OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB non défini afin que le wrapper tsdown puisse respecter les limites de mémoire du conteneur. Elles définissent aussi par défaut OPENCLAW_DOCKER_BUILD_SKIP_DTS=1, car les images runtime suppriment les fichiers de déclaration après la construction. Si Docker signale ResourceExhausted, cannot allocate memory ou abandonne pendant tsdown, augmentez la limite de mémoire du builder Docker ou réessayez avec des tailles de tas explicites plus petites, par exemple OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Les mainteneurs peuvent tester les sources de plugins groupés avec une image empaquetée en montant un répertoire source de Plugin sur son chemin de source empaqueté, par exemple OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Ce répertoire source monté remplace le paquet compilé correspondant /app/dist/extensions/synology-chat 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 pas de port Docker publié. Si vous construisez l’image localement et voulez que l’exporteur OpenTelemetry groupé soit disponible dans l’image, incluez ses dépendances runtime :

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

Installez le Plugin officiel @openclaw/diagnostics-otel depuis ClawHub dans les installations Docker empaquetées avant d’activer l’export. Les images personnalisées construites depuis les sources peuvent toujours inclure la source locale du Plugin avec OPENCLAW_EXTENSIONS=diagnostics-otel. Pour activer l’export, autorisez et activez le Plugin diagnostics-otel dans la configuration, puis définissez diagnostics.otel.enabled=true ou utilisez l’exemple de configuration dans Export OpenTelemetry. Les en-têtes d’authentification du collecteur sont configurés via diagnostics.otel.headers, et non via des variables d’environnement Docker.

Les métriques Prometheus 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 séparé ni de chemin de proxy inverse non authentifié. Voir Métriques Prometheus.

Contrôles de santé

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

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

L’image Docker inclut un HEALTHCHECK intégré qui interroge /healthz. Si les vérifications continuent d’échouer, Docker marque le conteneur comme unhealthy et les systèmes d’orchestration peuvent le redémarrer ou le remplacer.

Instantané de santé approfondi authentifié :

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

LAN ou loopback

scripts/docker/setup.sh définit par défaut OPENCLAW_GATEWAY_BIND=lan afin que l’accès depuis l’hôte à http://127.0.0.1:18789 fonctionne avec la publication de port Docker.

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

Fournisseurs locaux de l’hôte

Quand OpenClaw s’exécute dans Docker, 127.0.0.1 à l’intérieur du conteneur désigne le conteneur lui-même, pas votre machine hôte. Utilisez host.docker.internal pour les fournisseurs d’IA qui s’exécutent sur l’hôte :

La configuration Docker fournie utilise ces URL d’hôte comme valeurs par défaut d’onboarding pour LM Studio et Ollama, et docker-compose.yml associe host.docker.internal au gateway hôte de Docker pour Docker Engine sous Linux. Docker Desktop fournit déjà le même nom d’hôte sous macOS et Windows.

Les services de l’hôte doivent aussi écouter sur une adresse joignable depuis Docker :

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

Si vous utilisez votre propre fichier Compose ou commande docker run, ajoutez vous-même le même mappage d’hôte, par exemple --add-host=host.docker.internal:host-gateway.

Backend Claude CLI dans Docker

L’image Docker officielle d’OpenClaw ne préinstalle pas Claude Code. Installez et connectez-vous à Claude Code dans l’utilisateur du conteneur qui exécute OpenClaw, puis persistez ce répertoire personnel de conteneur afin que les mises à niveau de l’image n’effacent pas le binaire ni l’état d’authentification Claude.

Pour les nouvelles installations Docker, activez un volume /home/node persistant 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 Docker existante, arrêtez d’abord la pile et rechargez les valeurs Docker .env actuelles avant de relancer la configuration. Le script de configuration ne lit pas .env tout seul ; il réécrit .env à partir du shell courant et des valeurs par défaut. Pour le fichier .env généré, exécutez :

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

Si votre .env contient des valeurs que votre shell ne peut pas sourcer, réexportez manuellement les valeurs existantes dont vous dépendez d’abord, comme OPENCLAW_IMAGE, les ports, le mode de liaison, les chemins personnalisés, OPENCLAW_EXTRA_MOUNTS, le bac à sable et les paramètres de saut d’onboarding. 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 la surcouche Compose générée afin que les deux services montent le répertoire personnel persisté. Si votre configuration utilise aussi docker-compose.override.yml, incluez-le avant docker-compose.extra.yml.

Installez Claude Code dans ce répertoire personnel persisté :

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'

L’installateur natif écrit le binaire claude sous /home/node/.local/bin/claude. Indiquez à OpenClaw d’utiliser ce chemin de conteneur :

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 de conteneur persisté :

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

Après cela, vous pouvez utiliser le backend claude-cli fourni :

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 "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME persiste l’installation native de Claude Code sous /home/node/.local/bin et /home/node/.local/share/claude, ainsi que les paramètres et l’état d’authentification Claude Code sous /home/node/.claude et /home/node/.claude.json. Persister seulement /home/node/.openclaw ne suffit pas pour réutiliser Claude CLI. Si vous utilisez OPENCLAW_EXTRA_MOUNTS au lieu d’un volume de répertoire personnel, montez tous ces chemins Claude dans les deux services Docker.

Bonjour / mDNS

Le réseau bridge Docker ne transfère généralement pas le multicast Bonjour/mDNS (224.0.0.251:5353) de manière fiable. La configuration Compose fournie définit donc par défaut OPENCLAW_DISABLE_BONJOUR=1 afin que le Gateway n’entre pas dans une boucle de plantage ou ne redémarre pas à répétition la publicité lorsque le bridge abandonne le trafic multicast.

Utilisez l’URL publiée du Gateway, Tailscale ou DNS-SD étendu pour les hôtes Docker. Définissez OPENCLAW_DISABLE_BONJOUR=0 uniquement lors de l’exécution avec le réseau de l’hôte, macvlan, ou un autre réseau où le multicast mDNS est connu pour fonctionner.

Pour les pièges et le dépannage, consultez découverte Bonjour.

Stockage et persistance

Docker Compose monte en bind 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. Quand une variable n’est pas définie, le docker-compose.yml fourni se rabat sous ${HOME}, ou /tmp lorsque HOME lui-même est également absent. Cela évite que docker compose up émette une spécification de volume à source vide dans les environnements nus.

Ce répertoire de configuration monté est l’endroit où OpenClaw conserve :

• openclaw.json pour la configuration du comportement
• agents/<agentId>/agent/auth-profiles.json pour l’authentification OAuth/clé d’API fournisseur stockée
• .env pour les secrets d’exécution basés sur l’environnement comme OPENCLAW_GATEWAY_TOKEN

Le répertoire de clé secrète des profils d’authentification stocke la clé de chiffrement locale utilisée pour les données de jetons de profils d’authentification basé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 leur état de paquet sous le répertoire personnel OpenClaw monté, afin que les enregistrements d’installation de plugins et les racines de paquets survivent au remplacement du conteneur. Le démarrage du Gateway ne génère pas d’arborescences de dépendances de plugins fournis.

Pour les détails complets de persistance sur les déploiements de VM, consultez Runtime VM Docker - ce qui persiste où.

Points chauds de croissance disque : surveillez media/, les fichiers JSONL de session, la base de données d’état SQLite partagée, les racines de paquets de plugins installés et les journaux de fichiers tournants sous /tmp/openclaw/.

Assistants shell (facultatif)

Pour faciliter la gestion quotidienne de Docker, 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 installé ClawDock depuis l’ancien chemin brut scripts/shell-helpers/clawdock-helpers.sh, relancez la commande d’installation ci-dessus afin que votre fichier d’assistant local suive le nouvel emplacement.

Utilisez ensuite clawdock-start, clawdock-stop, clawdock-dashboard, etc. Exécutez clawdock-help pour toutes les commandes. Consultez ClawDock pour le guide complet des assistants.

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 Exécution Docker VM pour les étapes de déploiement sur VM partagée, notamment l’intégration de 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. Cela vous donne une séparation stricte autour des sessions d’agents non fiables ou multi-locataires sans conteneuriser l’ensemble du Gateway.

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

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

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

Activation rapide

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Construisez l’image de bac à sable par défaut (depuis un checkout source) :

scripts/sandbox-setup.sh

Pour les installations npm sans checkout source, consultez Bac à sable § Images et configuration pour les commandes docker build en ligne.

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

Connexe

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