OpenClaw avec Docker : guide complet

Déployer OpenClaw dans un conteneur Docker simplifie la gestion des dépendances, garantit la reproductibilité entre environnements et facilite le passage en production. Que vous travailliez en local ou sur un VPS, Docker élimine le problème du "ça marche sur ma machine". Ce guide couvre l'ensemble de la chaîne : Dockerfile, docker-compose, variables d'environnement et un exemple concret d'agent SEO conteneurisé. Vous aurez un environnement OpenClaw fonctionnel en moins de 15 minutes.

Pourquoi Docker pour OpenClaw ?

OpenClaw dépend de plusieurs bibliothèques Python, d'un accès réseau pour les skills externes et souvent d'une base de données ou d'un broker de messages pour les agents persistants. Sans conteneurisation, chaque déploiement exige de reconfigurer manuellement l'environnement, avec les risques de conflits de versions associés.

Docker apporte trois avantages concrets pour OpenClaw :

• Isolation : les dépendances Python d'OpenClaw n'interfèrent pas avec les autres projets du serveur.
• Reproductibilité : le même Dockerfile produit le même comportement en local, en staging et en production.
• Portabilité : migrer d'un VPS à un autre revient à copier le docker-compose.yml et les volumes.

Docker est particulièrement utile quand vous orchestrez plusieurs agents avec des skills différents, chacun dans son propre conteneur, ou quand vous souhaitez scaler horizontalement un agent à fort trafic.

Prérequis

Avant de commencer, vérifiez que votre machine dispose de :

• Docker Engine 24.x ou supérieur
• Docker Compose v2.x (intégré à Docker Desktop ou installé séparément)
• Une clé API pour le provider LLM choisi (OpenAI, Anthropic ou Mistral)
• Python 3.11+ si vous voulez tester localement avant de conteneuriser

Vérifiez les versions installées :

docker --version
# Docker version 24.0.7, build afdd53b

docker compose version
# Docker Compose version v2.23.3

Si Docker n'est pas installé, suivez le guide officiel Docker pour votre distribution. Pour la configuration initiale d'OpenClaw, consultez Installer OpenClaw.

Dockerfile OpenClaw

Voici un Dockerfile de production optimisé pour OpenClaw. Il utilise une image Python slim, installe les dépendances en couches séparées pour bénéficier du cache Docker, et crée un utilisateur non-root pour la sécurité.

# Dockerfile
FROM python:3.11-slim

# Métadonnées
LABEL maintainer="votre-equipe@exemple.com"
LABEL description="OpenClaw agent runtime"

# Variables de build
ARG OPENCLAW_VERSION=latest

# Dépendances système nécessaires pour certains skills (lxml, Pillow, etc.)
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Utilisateur non-root
RUN useradd --create-home --shell /bin/bash openclaw
WORKDIR /app

# Dépendances Python d'abord (couche cachée si requirements.txt inchangé)
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

# Code applicatif
COPY --chown=openclaw:openclaw . .

# Passage à l'utilisateur non-root
USER openclaw

# Port exposé si l'agent dispose d'une API HTTP
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Point d'entrée
CMD ["python", "-m", "openclaw.run", "--config", "openclaw.yaml"]

Le fichier requirements.txt minimal pour OpenClaw :

openclaw>=1.2.0
openai>=1.10.0
anthropic>=0.20.0
httpx>=0.26.0
pydantic>=2.5.0
python-dotenv>=1.0.0
psycopg2-binary>=2.9.0

docker-compose complet

Un seul conteneur suffit pour développer. En production, docker-compose.yml orchestre OpenClaw avec ses dépendances (base PostgreSQL pour la mémoire des agents, Redis pour la file de tâches).

# docker-compose.yml
version: "3.9"

services:
  openclaw:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: openclaw-agent
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - OPENCLAW_ENV=production
    volumes:
      - ./openclaw.yaml:/app/openclaw.yaml:ro
      - ./skills:/app/skills:ro
      - openclaw-logs:/app/logs
      - openclaw-data:/app/data
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - openclaw-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    image: postgres:16-alpine
    container_name: openclaw-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-openclaw}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB:-openclaw_db}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - openclaw-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-openclaw}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: openclaw-redis
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - redis-data:/data
    networks:
      - openclaw-net
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:
  redis-data:
  openclaw-logs:
  openclaw-data:

networks:
  openclaw-net:
    driver: bridge

Les volumes nommés openclaw-logs et openclaw-data garantissent la persistance des données entre les redémarrages de conteneurs. Le réseau openclaw-net isole les services du reste de l'hôte.

Variables d'environnement

Ne stockez jamais de clés API dans le Dockerfile ou le docker-compose.yml. Utilisez un fichier .env exclu du versioning.

# .env.example — copiez en .env et remplissez les valeurs

# LLM Provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...

# Base de données
POSTGRES_USER=openclaw
POSTGRES_PASSWORD=changez-ce-mot-de-passe
POSTGRES_DB=openclaw_db
DATABASE_URL=postgresql://openclaw:${POSTGRES_PASSWORD}@postgres:5432/openclaw_db

# Redis
REDIS_URL=redis://redis:6379/0

# Skills externes
BRAVE_API_KEY=...
SLACK_BOT_TOKEN=xoxb-...
SENDGRID_API_KEY=SG....

# OpenClaw
OPENCLAW_LOG_LEVEL=INFO
OPENCLAW_MAX_RETRIES=3
OPENCLAW_TIMEOUT=30

Ajoutez .env à votre .gitignore immédiatement :

echo ".env" >> .gitignore

Pour en savoir plus sur la gestion des clés et la configuration avancée, consultez Configurer OpenClaw.

Exemple concret : agent SEO conteneurisé

Voici un agent OpenClaw qui analyse les SERPs Brave Search et génère des briefs SEO, entièrement conteneurisé.

Structure du projet :

seo-agent/
├── Dockerfile
├── docker-compose.yml
├── .env
├── openclaw.yaml
├── requirements.txt
└── skills/
    ├── brave_search_skill.py
    └── seo_brief_skill.py

Le fichier openclaw.yaml pour cet agent :

# openclaw.yaml
agent:
  name: seo-analyzer
  description: "Analyse les SERPs et génère des briefs SEO"
  llm:
    provider: openai
    model: gpt-4o
    temperature: 0.3

skills:
  - path: skills/brave_search_skill.py
    name: BraveSearchSkill
  - path: skills/seo_brief_skill.py
    name: SEOBriefSkill

memory:
  backend: postgresql
  connection: ${DATABASE_URL}

queue:
  backend: redis
  connection: ${REDIS_URL}

tasks:
  - trigger: cron
    schedule: "0 6 * * 1"
    prompt: "Analyse le top 10 des SERPs pour les mots-clés de la liste keywords.txt et génère un brief pour chacun."

Démarrage de l'agent :

# Construire l'image
docker compose build

# Démarrer en arrière-plan
docker compose up -d

# Vérifier le statut
docker compose ps

# Suivre les logs en temps réel
docker compose logs -f openclaw

# Arrêter proprement
docker compose down

# Arrêter ET supprimer les volumes (reset complet)
docker compose down -v

Pour exécuter une tâche à la demande sans attendre le cron :

docker compose exec openclaw python -m openclaw.run \
  --config openclaw.yaml \
  --prompt "Analyse les 5 premiers résultats pour 'agent IA Python'"

Bonnes pratiques

Images légères : préférez python:3.11-slim à python:3.11. La différence est significative (~150 Mo vs ~1 Go). Évitez d'installer des outils de build inutiles en production.

Multi-stage builds : pour des images encore plus légères, compilez les dépendances dans un stage builder et copiez uniquement les artefacts dans le stage final.

Secrets Docker : en production sur Docker Swarm ou Kubernetes, utilisez les secrets natifs plutôt que les variables d'environnement pour les clés API sensibles.

Logs centralisés : redirigez les logs vers stdout/stderr (comportement par défaut d'OpenClaw) plutôt que vers des fichiers. Docker les collecte automatiquement et vous pouvez les router vers Loki, CloudWatch ou Datadog.

Mises à jour : reconstruisez régulièrement l'image pour intégrer les patches de sécurité des dépendances :

docker compose pull
docker compose build --no-cache
docker compose up -d

Limites de ressources : ajoutez des limites dans docker-compose.yml pour éviter qu'un agent mal configuré ne consomme toute la RAM du serveur :

deploy:
  resources:
    limits:
      cpus: "1.0"
      memory: 512M

Pour un déploiement sur serveur distant, consultez OpenClaw sur VPS.

Conclusion

Docker et OpenClaw forment une combinaison efficace : Docker gère l'isolation et la portabilité, OpenClaw gère l'orchestration des agents et des skills. Le docker-compose.yml présenté ici est prêt pour la production, avec PostgreSQL pour la mémoire persistante et Redis pour la file de tâches. Adaptez les volumes, les limites de ressources et les variables d'environnement à votre infrastructure, et vos agents seront déployables en quelques minutes sur n'importe quel serveur Linux.