L'analogie du système nerveux central
Most people think of AI assistants as standalone brains—a single entity that processes and responds. clawbot is different: it's architected like a biological nervous system . Your brain (the AI model) doesn't directly control your muscles; signals travel through nerves (channels), are processed by the spinal cord (Gateway), and execute through motor neurons (system tools).
Cette architecture distribuée est la raison pour laquelle clawbot peut écouter simultanément WhatsApp, répondre via Telegram, exécuter une commande shell et mettre à jour sa mémoire — le tout en parallèle. L'IA monolithique traditionnelle ne peut pas faire cela car chaque capacité est étroitement couplée. La conception modulaire de clawbot traite chaque composant comme un service indépendant communiquant via des protocoles bien définis.
Architecture du système clawbot
Plongée dans les composants : Comment chaque pièce fonctionne
🌐 The Gateway: Central Command
The Gateway is the heart of clawbot—a persistent Node.js process that never sleeps. Why a dedicated service instead of running AI directly in each channel? Three critical reasons:
- Unified State : Single source of truth for conversation history across all channels
- Resource Efficiency : One connection to AI APIs instead of 15+ separate connections
- Fault Isolation : If WhatsApp crashes, Telegram keeps working—channels are replaceable plugins
The Gateway communicates via WebSockets, not HTTP. Why? HTTP requires the client to constantly ask "any updates?" (polling). WebSockets maintain a persistent two-way connection—the Gateway can push messages to channels the instant they're ready, enabling real-time streaming responses.
💬 Channels: The Sensory Interface
Channels are independent processes that translate between messaging platform protocols and the Gateway's unified message format. Think of them as protocol adapters —WhatsApp speaks Baileys, Telegram speaks Bot API, but both present messages to the Gateway in identical JSON structure.
Cette abstraction est puissante : ajouter une nouvelle plateforme de messagerie nécessite d'écrire un plugin de canal, pas de modifier l'ensemble du système. Chaque canal est isolé en bac à sable — s'il plante, la Passerelle tente automatiquement de se reconnecter sans affecter les autres canaux.
🧠 AI Model Router: The Intelligence Backbone
clawbot doesn't lock you into a single AI provider. The model router implements dynamic provider selection : choose Claude for complex reasoning, GPT-4 for creative tasks, or local Ollama for privacy-critical operations—all within the same conversation.
How does this work technically? Each AI provider has a standardized interface (following the OpenAI Completion API pattern). The router maintains connection pools to all configured providers, routes requests based on configured preferences, and handles automatic failover if a provider is unavailable.
Advanced: Custom Model Routing Logic
You can configure custom routing rules in
~/.clawbot/clawbot.json
:
- Route coding tasks to Claude (better at programming)
- Route creative writing to GPT-4 (more imaginative)
- Route sensitive data processing to local Ollama (zero external transmission)
- Automatic fallback to secondary provider if primary fails
💾 Persistent Memory: Conversation State Management
Unlike stateless AI APIs that forget everything between requests, clawbot maintains
durable conversation history
stored in Markdown files at
~/.clawbot/conversations/
. Each conversation is a complete log of messages,
tool executions, and AI responses.
Why Markdown instead of a database? Three reasons:
- Human-Readable : You can grep, search, and version control your AI conversations
- Portable : Move your entire conversation history by copying a folder
- AI-Friendly : AI models can natively understand Markdown formatting for context retrieval
La Passerelle gère automatiquement les fenêtres de contexte — lorsqu'une conversation dépasse la limite de tokens du modèle, elle résume intelligemment les messages plus anciens tout en préservant le contexte critique. Cela permet des conversations qui s'étendent sur des semaines sans dégradation.
⚙️ Execution Engine: Safe System Control
This is where clawbot differentiates from chatbots: genuine task execution . When the AI decides a shell command is needed, the execution engine handles it safely through multiple protection layers:
- Sandboxing : Commands run in restricted environments with limited file system access
- Permission Gates : User-configurable allowlists/denylists for command patterns
- Confirmation Prompts : Destructive operations require explicit user approval
- Audit Logging : Every executed command is logged with timestamp, user, and result
- Timeout Protection : Commands automatically terminate after configurable duration
🔌 Skills System: Extensible Capabilities
Skills are clawbot's plugin system—folders containing
SKILL.md
files that teach the AI new capabilities.
How does a Markdown file extend functionality?
The AI reads the skill definition and learns:
- What the skill does and when to use it
- What parameters it accepts
- Example commands that trigger it
- Expected behavior and edge cases
Les compétences peuvent inclure des scripts shell, des modules Node.js ou du code d'intégration d'API. L'IA appelle ces outils via des appels de fonction structurés, reçoit les résultats et les intègre dans les réponses. C'est ainsi que clawbot peut contrôler les maisons intelligentes, gérer l'infrastructure cloud ou s'intégrer à des systèmes internes propriétaires — n'importe qui peut écrire une compétence.
La pile technologique : Ce qui alimente clawbot
Runtime: Node.js 22+
Moteur JavaScript moderne avec d'excellentes performances d'E/S asynchrones pour la communication en temps réel. Le support natif des WebSockets, HTTP/2 et des threads de travail permet l'exécution parallèle des tâches.
Language: TypeScript
Le développement typé empêche des catégories entières de bugs. Le typage fort pour les messages WebSocket, les réponses IA et la configuration garantit une gestion robuste des erreurs.
Communication: WebSocket Protocol
Connexions bidirectionnelles et persistantes entre la Passerelle et tous les clients. Permet le streaming de messages en temps réel, les notifications instantanées et une latence inférieure à la seconde pour les réponses IA.
Storage: File-Based State
Conversations stockées en Markdown, configuration en JSON, compétences dans des dossiers structurés. Aucune dépendance à une base de données — déploiement plus simple, sauvegardes plus faciles, débogage compatible avec grep.
WhatsApp: Baileys Library
Implémentation du protocole WhatsApp Web rétro-conçue. Maintient une connexion persistante en utilisant le même protocole que votre navigateur — pas d'API non officielles ni de partage de numéro de téléphone.
Telegram: grammY Framework
Wrapper officiel de l'API Telegram Bot avec support TypeScript. Support du long-polling et des webhooks pour un déploiement flexible, des transferts de fichiers, des claviers inline et des fonctionnalités complètes de bot.
AI Integration: Provider Abstraction
Interface unifiée prenant en charge Anthropic Claude, OpenAI GPT-4, les modèles locaux Ollama et Google Gemini. Conversion automatique entre différents formats d'API pour un changement de fournisseur transparent.
Security: Sandboxed Execution
Les commandes shell s'exécutent dans des environnements restreints avec des permissions configurables. Les limites de confiance définies par l'utilisateur empêchent les dommages accidentels au système ou les opérations non autorisées.
Flux de messages : Suivre une requête à travers le système
Let's trace what happens when you send: "Remind me to call Mom in 2 hours" via WhatsApp.
{"from": "user", "text": "Remind...", "channel": "whatsapp"}
schedule_reminder(time="+2h", message="Call Mom")
Cette chorégraphie en 19 étapes se déroule en moins de 2 secondes. L'architecture distribuée permet à chaque composant de fonctionner indépendamment — le canal WhatsApp ne connaît pas Claude, Claude ne connaît pas WhatsApp, pourtant ils se coordonnent de manière transparente grâce à l'orchestration de la Passerelle.
Pourquoi cette architecture est importante
La plupart des assistants IA sont monolithiques — toute la logique dans une seule application, étroitement liée à des plateformes spécifiques. La conception distribuée de clawbot permet des capacités impossibles dans les architectures traditionnelles :
- Hot-Swappable Components : Upgrade AI models without restarting channels. Replace WhatsApp with Telegram without touching the Gateway.
- Horizontal Scaling : Run multiple channel instances across different machines, all connecting to one Gateway.
- Fault Tolerance : If one channel crashes, others continue operating. If the Gateway restarts, channels automatically reconnect.
- Multi-Tenancy : One Gateway can serve multiple users with isolated conversation spaces—perfect for family deployments.
- Extensibility : Community members can build new channels, skills, or tools without access to core code.
🔐 Security Through Architecture
La conception distribuée n'est pas seulement une question de flexibilité — c'est une frontière de sécurité. Les canaux s'exécutent dans des processus séparés avec des permissions limitées. Si un canal est compromis, les attaquants n'obtiennent l'accès qu'à cette plateforme de messagerie, pas à l'ensemble de votre système. La Passerelle applique l'authentification, et le moteur d'exécution applique un sandboxing supplémentaire avant l'exécution de toute commande système.
Décisions techniques et compromis
Pourquoi WebSockets plutôt que HTTP REST ?
HTTP is request-response: client asks, server answers. AI responses often take 5-15 seconds. Without WebSockets, you'd need polling (wasteful) or long-polling (complex). WebSockets enable streaming responses —the AI begins sending words the moment it generates them, creating the perception of instant responsiveness.
Pourquoi le stockage de fichiers plutôt qu'une base de données ?
Databases add deployment complexity—installation, configuration, backup strategies. For personal AI (1-10 users), files provide sufficient performance while remaining portable, inspectable, and version-controllable . You can grep your conversation history, back it up with Dropbox, or track changes with Git.
Pourquoi Node.js plutôt que Python/Go/Rust ?
Node.js excelle dans les tâches liées aux E/S (communication en temps réel, appels d'API). Le modèle async/await de JavaScript correspond naturellement aux flux de travail IA (envoyer une requête, attendre la réponse, traiter le résultat). L'écosystème npm fournit des bibliothèques matures pour chaque plateforme de messagerie. TypeScript ajoute de la sécurité sans sacrifier la vitesse de développement.
Prêt à déployer le vôtre ?
Comprendre l'architecture est la première étape. La deuxième étape est de la construire.