Initialement développé sous le nom de ClawdBot par Peter Steinberger et publié sous licence MIT, OpenClaw n’est pas un LLM (Large Language Model), mais un framework d’orchestration. Il agit comme un middleware (logiciel intermédiaire) entre un moteur d’inférence (le LLM) et un environnement d’exécution (votre système d’exploitation ou vos serveurs).
Ce guide s’adresse aux développeurs, ingénieurs système et professionnels de l’automatisation. Il détaille l’architecture technique d’OpenClaw, la logique de ses boucles d’exécution, ses prérequis d’installation et les contraintes réelles liées à sa mise en production.
1. Architecture logicielle : comment fonctionne OpenClaw ?
L’objectif d’OpenClaw est de transformer des instructions en langage naturel en appels de fonctions exécutables. Son architecture repose sur trois composants modulaires.
La boucle de contrôle (Pattern ReAct)
OpenClaw n’exécute pas de requêtes linéaires. Il utilise le pattern ReAct (Reasoning and Acting). Lorsqu’une tâche lui est assignée, le framework structure un prompt système dynamique (souvent appelé System Prompt) qui oblige le LLM à formuler sa réponse en deux temps :
- Thought (Pensée) : Le modèle analyse l’état actuel et détermine la prochaine action requise.
- Action (Appel de fonction) : Le modèle génère un objet JSON (Function Calling) contenant le nom de l’outil à utiliser et ses paramètres.
OpenClaw intercepte ce JSON, exécute le script Python ou bash correspondant, récupère la sortie (stdout/stderr) et la renvoie au modèle en tant qu’Observation. La boucle se répète jusqu’à ce que le LLM émette un statut FINISH.
L’infrastructure des tools (outils natifs et custom)
Le framework est livré avec une suite d’outils natifs (exécution de commandes terminal, manipulation de système de fichiers, navigation web via un navigateur headless comme Playwright). D’un point de vue technique, intégrer un nouvel outil dans OpenClaw consiste simplement à fournir au LLM un schéma JSON décrivant les arguments attendus par un script local.
La persistance : context Window et bases vectorielles
La gestion de la mémoire est le défi principal des agents autonomes. OpenClaw gère deux niveaux de mémoire :
- La mémoire de travail (Short-term) : Elle correspond à la fenêtre de contexte (Context Window) du modèle utilisé. Pour éviter la saturation des tokens (Token Limit), OpenClaw intègre un mécanisme de « pruning » qui résume automatiquement les boucles d’actions trop anciennes.
- La mémoire persistante (Long-term) : OpenClaw intègre nativement une base de données vectorielle légère (comme ChromaDB ou SQLite couplé à une extension vectorielle). L’agent peut y stocker des informations et les requêter via RAG (Retrieval-Augmented Generation) pour maintenir un contexte sur plusieurs semaines.
2. Modes d’exécution : démon et webhooks
Contrairement aux interfaces web d’IA classiques, OpenClaw est conçu pour fonctionner en tâche de fond (processus Daemon).
Son architecture événementielle permet de le déclencher via des Webhooks. Vous pouvez par exemple exposer un point de terminaison (endpoint) relié à un bot Telegram, Slack, ou à des événements GitHub (via GitHub Actions). Dès qu’un message ou un push est détecté, le processus sort de veille, charge le contexte associé à l’utilisateur, et initie sa boucle ReAct.
3. Déploiement : exigences techniques et conteneurisation
Le déploiement d’OpenClaw sur un poste local ou un serveur dédié exige une configuration stricte, principalement pour des raisons de sécurité.
Prérequis
- Docker et Docker Compose (pour l’isolation).
- Un point d’accès API compatible avec les standards d’OpenAI (soit vers des fournisseurs cloud comme Anthropic/OpenAI, soit vers une instance locale via Ollama/vLLM).
Le fichier de configuration (.env)
La configuration se fait via les variables d’environnement. Voici les paramètres critiques :
LLM_API_BASE: L’URL du moteur d’inférence.LLM_MODEL_NAME: Le nom du modèle cible (ex: gpt-4-turbo, claude-3-opus, ou llama-3-8b-instruct).MAX_ITERATIONS: Paramètre vital. Il définit le nombre maximum de boucles ReAct autorisées pour une tâche. Sans cette limite, l’agent pourrait s’enfermer dans une boucle infinie et drainer votre budget API.WORKSPACE_DIR: Le chemin du volume monté où l’agent a le droit de lire/écrire.
Commande de déploiement
L’installation standard via Docker Compose se présente ainsi :
git clone [https://github.com/openclaw-project/openclaw.git](https://github.com/openclaw-project/openclaw.git)
cd openclaw
cp .env.example .env
# Éditez le fichier .env selon vos besoins
docker-compose up -d
4. Choix des modèles : cloud API vs inférence locale
Le choix du moteur d’inférence (le LLM) impacte drastiquement les performances et les coûts d’OpenClaw.
- Via API (OpenAI, Anthropic) : C’est le mode le plus performant pour les tâches de code ou d’analyse complexe. Cependant, la boucle ReAct est extrêmement gourmande. Chaque étape renvoie l’historique complet des actions précédentes au modèle. Le coût en tokens « Input » croît donc de manière exponentielle à chaque itération.
- Via Inférence Locale (Ollama, LM Studio) : Idéal pour garantir la souveraineté des données. Vous pouvez connecter OpenClaw à un modèle local quantifié (fichiers GGUF). Cependant, les modèles de moins de 14 milliards de paramètres (14B) ont souvent des difficultés avec le « Function Calling » strict et ont tendance à générer du JSON mal formaté, ce qui fait planter la boucle d’exécution d’OpenClaw.
5. Sécurité : isolation et Human-in-the-Loop
Accorder un accès à un terminal shell à un LLM est intrinsèquement dangereux. OpenClaw propose plusieurs niveaux de sécurité :
- Sandboxing (Isolation) : L’agent s’exécute dans un conteneur Docker dépourvu des privilèges
root. Le système de fichiers est monté en lecture seule, à l’exception du dossierWORKSPACE_DIRspécifiquement assigné à l’agent. - Filtrage réseau (Egress filtering) : Il est recommandé de configurer le réseau Docker pour limiter les accès sortants de l’agent (par exemple, autoriser l’API GitHub mais bloquer le reste) pour éviter l’exfiltration de données en cas d’injection de prompt (Prompt Injection).
- Le mode « Human-in-the-Loop » (HITL) : Activé par défaut pour les actions sensibles (exécution de code, suppression de fichiers). L’agent suspend sa boucle d’exécution, envoie une requête via webhook (sur votre messagerie) détaillant la commande exacte qu’il s’apprête à lancer, et attend un callback d’approbation (un simple « y » ou « n ») pour reprendre son cycle.
