build-your-own-openclaw : reconstruire un agent IA en 18 étapes
A step-by-step guide to build your own AI agent.
En bref
- De quoi s’agit-il ?
- Un tutoriel Python qui décompose un agent de type OpenClaw en 18 paliers exécutables, du simple chat loop jusqu'à la mémoire et le contrôle de concurrence. Le dépôt est une progression pédagogique, pas une bibliothèque à installer.
- À qui s’adresse-t-il ?
- À adopter si vous voulez comprendre le fonctionnement interne d'un agent conversationnel en écrivant le code vous-même, étape par étape, en Python. À éviter si vous cherchez un framework prêt pour la production ou une dépendance à installer dans un projet existant : ici, chaque dossier est un exercice, pas un paquet.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 70 jours.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le problème : un agent n'est pas une API, c'est une pile de décisions
Appeler un modèle de langage tient en quelques lignes. Ce qui prend du temps, c'est tout ce qu'on empile autour : boucle de conversation, appels d'outils, persistance des échanges, compaction de l'historique, puis routage entre plusieurs agents et concurrence. La documentation du dépôt présente l'objectif ainsi : construire « a minimal version of OpenClaw » à partir d'une boucle de chat. Le public visé est donc l'ingénieur qui sait déjà écrire du Python et veut voir où se situent les points de rupture d'un agent, plutôt que celui qui cherche une abstraction prête à l'emploi. Le dépôt se présente comme un tutoriel, et son arborescence le confirme : dix-huit dossiers numérotés, chacun avec son README et son code exécutable. Le projet de référence, pickle-bot, sert d'illustration finale. Cette approche a une conséquence directe : vous lisez du code pour en comprendre les compromis, vous n'importez pas une bibliothèque.
Quatre phases, dix-huit dossiers, une seule trajectoire
La progression est explicite dans le README. La phase 1 (étapes 0 à 6) construit un agent unique capable de discuter, d'utiliser des outils, d'apprendre des skills, de mémoriser les conversations et d'accéder au web. La phase 2 (7 à 10) refactorise vers une architecture événementielle pour sortir du terminal et supporter plusieurs plateformes, avec rechargement de configuration à chaud et WebSocket. La phase 3 (11 à 15) ajoute les tâches planifiées, le routage multi-agent, les prompts en couches et l'envoi de messages vers l'utilisateur. La phase 4 (16 et 17) traite la fiabilité et la mémoire longue. Ce découpage impose un ordre : l'étape 07-event-driven réécrit ce que les étapes précédentes avaient posé en ligne droite. Si vous sautez directement à la phase 3, vous héritez d'un modèle de concurrence et de routage sans avoir vu la boucle de base qu'ils remplacent, ce qui rend les choix de conception difficiles à évaluer.
Le mécanisme : des skills en markdown et une compaction d'historique
Deux mécanismes ressortent de la nomenclature des étapes. D'abord les skills : l'étape 02-skills indique que l'agent s'étend au moyen d'un fichier SKILL.md. Autrement dit, la capacité de l'agent n'est pas seulement codée en Python, elle est décrite dans un document que le modèle lit. C'est un choix qui déplace l'extension vers la rédaction de texte plutôt que vers l'ajout de fonctions. Ensuite la compaction : l'étape 05-compaction résume l'idée par « Pack you history and carry on... ». Un agent qui tient une conversation longue finit par dépasser la fenêtre de contexte du modèle, et cette étape traite précisément ce point. Les phases suivantes prolongent la logique : 13-multi-layer-prompts empile du contexte, 17-memory conserve de l'information au-delà d'une session. Le fil conducteur est donc la gestion de ce qui entre dans le contexte et de ce qui en sort. Le README ne détaille pas l'algorithme de compaction retenu, ni le format de stockage de la mémoire : ces éléments sont à chercher dans le code de chaque dossier.
Mise en route : deux fichiers de configuration avant tout
Le README donne une procédure unique, valable pour toutes les étapes. On copie d'abord l'exemple de configuration : cp default_workspace/config.example.yaml default_workspace/config.user.yaml. On édite ensuite config.user.yaml pour y placer ses clés d'API. Le projet s'appuie sur LiteLLM, et le README renvoie vers la documentation des fournisseurs LiteLLM pour la liste complète, ainsi que vers le fichier PROVIDER_EXAMPLES.md pour des exemples concrets. C'est le seul point d'entrée documenté : il n'y a pas de commande d'installation globale ni de paquet à publier, puisque chaque étape est un dossier autonome. La consigne finale du README est volontairement minimale : suivre chaque étape, lire, essayer. Notez que le nom du fichier cible, config.user.yaml, suggère une séparation entre configuration versionnée et configuration personnelle, mais le README ne précise pas de mécanisme de fusion entre les deux : c'est à vérifier dans le code de chargement.
Le prix de la progression : duplication et dette pédagogique
Un tutoriel en dix-huit étapes exécutables implique que chaque étape contienne un codebase complet et lançable. Cela signifie que le même code apparaît plusieurs fois, avec des écarts volontairement limités d'un dossier à l'autre. Pour l'apprenant, c'est un avantage : la différence entre deux étapes est lisible. Pour toute autre usage, c'est un obstacle : corriger un défaut repéré à l'étape 03 n'a aucune raison de se propager à l'étape 12, et rien dans le README n'indique qu'une synchronisation soit maintenue entre les dossiers. Le projet ne publie d'ailleurs aucune release, ce qui va dans le même sens : l'état de référence est la branche main, pas une version figée. Autre point à surveiller, la phase 2 introduit une architecture événementielle, mais le README ne décrit ni le bus d'événements ni le modèle d'exécution. Un lecteur qui découvre l'étape 07-event-driven sans expérience préalable des boucles d'événements devra s'appuyer sur le README local du dossier, dont le contenu n'est pas fourni ici.
Ce qui manque pour en faire un outil de production
Le dépôt ne se présente jamais comme un framework. Il n'expose pas d'API publique stable, ne documente pas de politique de compatibilité et ne fournit pas de procédure de déploiement. L'étape 16-concurrency-control aborde le cas où trop d'agents tournent simultanément, et l'étape 12-cron-heartbeat ajoute des tâches planifiées, mais ces briques restent des démonstrations : rien n'indique qu'elles aient été éprouvées sous charge réelle. La question des coûts d'appels aux modèles n'est pas traitée non plus, alors que la compaction et la mémoire longue multiplient les appels. Si votre besoin est de faire tourner un agent fiable en production dès la semaine prochaine, ce dépôt est le mauvais outil : il vous demandera de réécrire vous-même l'observabilité, la gestion des erreurs et la persistance. Si votre besoin est de comprendre pourquoi votre agent oublie le contexte au bout de vingt tours, il est bien placé.
Face à LangChain ou à un agent écrit à la main
L'alternative la plus proche n'est pas un concurrent direct mais une famille d'outils : les frameworks d'orchestration qui fournissent des abstractions prêtes, là où ce dépôt fournit une séquence d'exercices. La différence de méthode est nette. Un framework vous donne une classe d'agent et des intégrations ; vous lisez sa documentation et vous composez. Ici, vous écrivez la boucle, puis vous la refactorisez vous-même à l'étape 07. Le second point de comparaison est l'agent écrit entièrement à la main, sans tutoriel : c'est ce que ferait un ingénieur qui connaît déjà le domaine, et le résultat serait probablement plus compact que dix-huit dossiers. L'apport du dépôt tient à l'ordonnancement des problèmes : il place la compaction avant le multi-agent, et la concurrence après la planification. Cet ordre est un jugement de conception, et c'est peut-être ce que le projet offre de plus utile, davantage que le code lui-même. Le README invite d'ailleurs les contributions, en précisant que chaque étape est implémentée dans une session distincte.
Licence, maintenance et coût de suivi
Le dépôt est publié sous licence MIT. Concrètement, cela autorise la réutilisation, la modification et la redistribution du code, y compris dans un contexte commercial, à condition de conserver l'avis de licence. Cela ne dit rien de la qualité du code ni de sa compatibilité avec vos dépendances : la licence couvre les droits d'usage, pas les garanties techniques. Sur la maintenance, les éléments disponibles sont limités. La branche par défaut est main, le dépôt n'est pas archivé, et le dernier push est daté du 8 juillet 2026. Aucune release n'a été récupérée, ce qui signifie qu'il n'existe pas de point de version auquel s'accrocher pour un suivi. Si vous forkez ce dépôt pour en faire une base interne, vous héritez de la maintenance : les mises à jour de LiteLLM et des fournisseurs de modèles ne seront pas absorbées automatiquement. Le coût réel n'est donc pas l'adoption, qui consiste à copier un dossier, mais le suivi dans la durée, qui repose entièrement sur vous. Ce n'est pas un défaut du projet, c'est la contrepartie d'un format tutoriel.
Conclusion éditoriale
À adopter si vous voulez comprendre le fonctionnement interne d'un agent conversationnel en écrivant le code vous-même, étape par étape, en Python. À éviter si vous cherchez un framework prêt pour la production ou une dépendance à installer dans un projet existant : ici, chaque dossier est un exercice, pas un paquet. Avant de vous engager, vérifiez trois points concrets : le contenu de default_workspace/config.example.yaml pour la liste des clés attendues, le fichier PROVIDER_EXAMPLES.md pour la compatibilité de votre fournisseur via LiteLLM, et le README de l'étape 16 pour juger si le modèle de concurrence correspond à votre charge réelle.
Notes de la communauté