Docker

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

# Docker est-il adapté à mon cas ?

• Oui : vous voulez un environnement 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 vous voulez simplement la boucle de développement la plus rapide. Utilisez plutôt le flux d’installation normal.
• Note sur la mise en bac à sable : le backend de bac à sable par défaut utilise Docker lorsque la mise en bac à sable est activée, mais elle est désactivée 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. Consultez Mise en 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 arrêté par manque de mémoire sur des hôtes de 1 Go avec le code de sortie 137)
• Assez d’espace disque pour les images et les journaux
• Si vous exécutez OpenClaw 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

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

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

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

# Discord
docker 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-daemon
docker 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 :

Les mainteneurs peuvent tester la source d’un Plugin groupé avec une image empaquetée en montant un répertoire source de Plugin sur son chemin 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 bundle compilé correspondant /app/dist/extensions/synology-chat pour le même ID de Plugin.

# Observabilité

L’export OpenTelemetry sortant part du 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’exportateur OpenTelemetry groupé soit disponible dans l’image, incluez ses dépendances d’exécution :

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 la source 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 scrapez :

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

La route est protégée par l’authentification Gateway. N’exposez pas de port public /metrics séparé ni de chemin de proxy inverse non authentifié. Consultez 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   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

L’image Docker inclut un HEALTHCHECK intégré qui interroge /healthz. Si les contrôles 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 hôte à http://127.0.0.1:18789 fonctionne avec la publication de port Docker.

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

# Fournisseurs locaux de l’hôte

Lorsque OpenClaw s’exécute dans Docker, 127.0.0.1 à l’intérieur du conteneur est 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 groupée utilise ces URL hôte comme valeurs par défaut de configuration initiale pour LM Studio et Ollama, et docker-compose.yml mappe host.docker.internal au Gateway hôte Docker pour Docker Engine sous Linux. Docker Desktop fournit déjà le même nom d’hôte sur macOS et Windows.

Les services hôte doivent également écouter sur une adresse accessible depuis Docker :

lms server start --port 1234 --bind 0.0.0.0
OLLAMA_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.

# Bonjour / mDNS

Le réseau bridge Docker ne transmet généralement pas de façon fiable le multicast Bonjour/mDNS (224.0.0.251:5353). La configuration Compose groupée définit donc par défaut OPENCLAW_DISABLE_BONJOUR=1 afin que le Gateway ne boucle pas en plantant ou ne redémarre pas l’annonce à répétition lorsque le bridge abandonne le trafic multicast.

Utilisez l’URL Gateway publiée, Tailscale ou DNS-SD étendu pour les hôtes Docker. Définissez OPENCLAW_DISABLE_BONJOUR=0 uniquement lors de l’exécution avec un réseau 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 et OPENCLAW_WORKSPACE_DIR sur /home/node/.openclaw/workspace, de sorte que ces chemins survivent au remplacement du conteneur. Lorsque l’une ou l’autre variable n’est pas définie, le docker-compose.yml groupé se rabat sur ${HOME}/.openclaw (et ${HOME}/.openclaw/workspace pour le montage de l’espace de travail), ou /tmp/.openclaw lorsque HOME lui-même est également absent. Cela évite que docker compose up émette une spécification de volume avec 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é API du fournisseur stockée
• .env pour les secrets d’exécution basés sur l’environnement, tels que OPENCLAW_GATEWAY_TOKEN

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

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

Points chauds de croissance du disque : surveillez media/, les fichiers JSONL de session, cron/runs/*.jsonl, les racines des packages de Plugin installés et les journaux de fichiers rotatifs sous /tmp/openclaw/.

# Assistants shell (facultatif)

Pour une gestion Docker quotidienne plus simple, installez ClawDock :

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo '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’assistance local suive le nouvel emplacement.

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

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

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

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
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"]

# Exécution sur un VPS ?

Consultez Hetzner (VPS Docker) et Environnement d’exécution VM Docker pour les étapes de déploiement sur VM partagée, y compris l’intégration du binaire, la persistance et les mises à jour.

# Bac à sable d’agent

Lorsque agents.defaults.sandbox est activé avec le backend Docker, le Gateway exécute les outils d’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’agent non fiables ou multi-locataires sans conteneuriser tout le Gateway.

La portée du bac à sable peut être par agent (par défaut), par session ou partagée. Chaque portée dispose de son propre espace de travail monté dans /workspace. Vous pouvez aussi configurer des politiques d’autorisation/refus d’outils, l’isolation réseau, les 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 :

• Mise en 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 -- surcharges 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 Mise en bac à sable § Images et configuration pour les commandes docker build en ligne.

# Dépannage

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>

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

# Articles connexes

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