Objectif d’apprentissage : Identifier les responsabilités exactes du processus Gateway et les distinguer de celles du moteur de raisonnement, afin de diagnostiquer correctement l’origine d’un dysfonctionnement dans une installation OpenClaw.

Le problème concret

Vous administrez un assistant OpenClaw pour une petite agence immobilière. L’assistant répond sur WhatsApp aux prospects, sur Slack aux agents internes, et déclenche des scripts sur le serveur pour générer des PDF de mandats.

Un vendredi soir, l’assistant cesse de répondre sur WhatsApp mais continue de fonctionner normalement sur Slack. Où cherchez-vous le bug : dans le modèle de langage, dans le code métier, ou ailleurs ?

Si vous ne savez pas répondre immédiatement, c’est que vous n’avez pas encore intégré la séparation fondamentale sur laquelle repose OpenClaw : un canal de communication en panne n’a, par construction, aucun rapport avec la capacité de raisonnement du système.

Le mécanisme

OpenClaw repose sur un processus Node.js unique et persistant appelé le Gateway.

Ce processus tourne en continu sur votre machine, qu’il s’agisse d’un Mac Mini laissé allumé dans un coin du bureau ou d’un VPS loué chez un hébergeur.

Sa fonction est volontairement limitée : il ne réfléchit jamais. Il ne génère aucun texte, ne prend aucune décision de contenu, n’appelle aucun modèle de langage pour produire une réponse. Son rôle se résume à trois tâches purement mécaniques.

La première est le routage des messages. Le Gateway reçoit des signaux entrants depuis plus de treize plateformes différentes — WhatsApp, Telegram, iMessage, Slack, Discord, et d’autres — chacune ayant son propre format d’événement, son propre protocole d’authentification, sa propre structure de charge utile.

Un message WhatsApp n’a pas la même forme brute qu’un message Slack : l’un arrive via un webhook HTTP avec une structure JSON propre à l’API Business de Meta, l’autre via un événement WebSocket structuré selon le format interne de Slack.

Le Gateway absorbe cette hétérogénéité grâce à des adaptateurs de canal (channel adapters), un par plateforme, dont le seul travail consiste à traduire ces formats disparates vers une représentation interne unique. Une fois normalisé, un message ressemble strictement au même objet en interne, qu’il provienne d’un texto iMessage ou d’un message direct Discord.

Cette normalisation est ce qui permet à toute la logique d’agent en aval de ne jamais avoir à connaître l’origine du message.

La deuxième tâche est la gestion des sessions utilisateur. Le Gateway sait associer un identifiant de canal (un numéro de téléphone WhatsApp, un identifiant Slack, un identifiant Telegram) à une session persistante, ce qui permet à un même utilisateur de reprendre une conversation là où il l’avait laissée, même en changeant d’appareil ou de canal.

La troisième tâche est l’accès au matériel local. Comme le Gateway tourne directement sur votre machine plutôt que dans un environnement cloud tiers, c’est lui qui détient les permissions d’accès au système de fichiers, aux processus, et aux ressources réseau locales. C’est cette position qui rend possible, plus loin dans la chaîne, l’exécution de commandes shell ou la modification de fichiers.

Cette architecture s’appelle un modèle de plan de contrôle (control plane) séparé du plan d’exécution logique. Le Gateway est le plan de contrôle : il décide qui parle à qui et par où transite l’information, sans jamais interpréter le contenu de ce qui est dit.

La conséquence directe pour vous, en tant qu’opérateur, est qu’un incident doit toujours être diagnostiqué en deux temps distincts : le message est-il arrivé jusqu’au Gateway (problème de canal, d’authentification API, de connectivité) ou le message est-il arrivé mais mal traité en aval (problème de raisonnement, de contexte, d’outil) ? Confondre ces deux niveaux de panne est l’erreur de diagnostic la plus fréquente chez les nouveaux administrateurs OpenClaw.

Exemple

Reprenons le cas de l’agence immobilière. Le journal du Gateway (accessible via la commande de logs d’OpenClaw) montre, pour la période du vendredi soir concerné, une absence totale d’entrées provenant de l’adaptateur WhatsApp, alors que l’adaptateur Slack continue d’enregistrer des événements toutes les quelques minutes.

Cette asymétrie est le signal déterminant : si le problème venait du moteur de raisonnement ou d’un outil partagé, les deux canaux seraient affectés simultanément, puisqu’ils convergent vers la même boucle d’agent une fois normalisés.

En creusant, vous découvrez que le token d’accès à l’API WhatsApp Business a expiré à minuit, un renouvellement automatique ayant échoué faute de connexion sortante temporaire chez l’hébergeur. Le Gateway a continué de fonctionner parfaitement ; seul l’adaptateur WhatsApp, isolé des autres, a cessé de recevoir des événements.

Aucune ligne de code métier, aucun prompt, aucun outil n’a été touché. Le correctif consiste uniquement à régénérer le token côté Meta Business Suite et à redémarrer l’adaptateur concerné, sans toucher au reste du système.

Application

Ouvrez la documentation ou l’interface de logs de votre propre installation OpenClaw (ou, si vous n’en avez pas encore, consultez la structure de configuration de référence du projet). Listez, pour chacun des canaux que vous prévoyez d’utiliser, le type d’authentification requis par cet adaptateur (token API, QR code de session, clé webhook).

Pour chaque canal, notez ce qui se passerait concrètement, côté utilisateur final, si cette authentification expirait sans que vous vous en rendiez compte pendant une semaine. Cet exercice vous oblige à cartographier les points de défaillance du plan de contrôle avant qu’ils ne deviennent des incidents en production.