Architecture OpenClaw en profondeur : principes de la conception en trois couches et pratiques d'extension

Conclusion rapide (saisir la ligne directrice de l’architecture)

La façon la plus rapide de comprendre OpenClaw est de saisir les responsabilités des trois couches : Gateway gère les sessions, Channel le routage des messages, LLM l’interface modèle.
Dès que vous classez un problème dans l’une de ces trois couches, le dépannage et l’extension deviennent beaucoup plus rapides.
Développer un nouveau Channel ou Provider revient essentiellement à implémenter l’interface et à l’enregistrer.

Deux heures du matin, je fixais le dépôt OpenClaw dans l’éditeur, prêt à ajouter un Channel DingTalk. Des dizaines de fichiers dans src/, gateway, channel et llm entremêlés — je ne savais pas par où commencer. Modifier gateway impacterait-il les autres Channels ? Copier le code WhatsApp serait-il fiable ? Et si rien ne démarre après mes modifications ?

Franchement, c’était décourageant. La documentation officielle explique comment utiliser le produit, pas comment le système fonctionne en interne. Pour du développement personnalisé, c’était comme tâtonner dans le noir — toucher le traitement webhook sans comprendre le routage ; voir l’appel LLM sans saisir l’enregistrement des Providers.

J’ai ensuite passé trois jours entiers à parcourir le code source, et découvert la finesse du design d’OpenClaw : Gateway gère les sessions, Channel le routage, LLM l’interface — trois couches aux responsabilités nettes. Une fois compris, le développement personnalisé n’est plus de l’exploration aveugle, mais un processus structuré.

Cet article rassemble systématiquement le fruit de ces trois jours. Vous verrez pourquoi OpenClaw se divise en trois couches, quel problème chacune résout, comment Gateway gère l’état des sessions, comment Channel adapte les différentes plateformes, comment le système de plugins Provider de la couche LLM est conçu, et enfin un guide pas à pas pour développer des Channels et Providers personnalisés.

Guide « élevage de homard » à faible coût : ArkClaw démocratise l’agent IA

OpenClaw (le « homard ») est populaire mais sa configuration rebute ? ArkClaw de ByteDance Volcano Engine abaisse la barrière au minimum. Sans serveur ni configuration de Token, un clic suffit pour un « agent IA » en ligne 24 h/24, capable de contrôler le navigateur, exécuter des scripts et gérer le calendrier.

Le prix est réellement bas : 9,9 yuans/mois ; avec mon code d’invitation ZLKUK54M (inscrivez-vous ici), seulement 8,9 yuans. Si vous êtes développeur, le Coding Plan Pro offre l’accès gratuit.

Panorama de l’architecture OpenClaw : pourquoi trois couches ?

En découvrant OpenClaw, je me demandais : pourquoi une telle complexité en couches ? Ne suffit-il pas de transmettre le message de l’utilisateur à l’IA ?

En étudiant le code source, j’ai compris : un design monolithique fonctionne à petite échelle, mais OpenClaw doit supporter plusieurs plateformes (WhatsApp, Telegram, Gmail), plusieurs modèles (Claude, GPT, modèles locaux) et gérer des centaines de sessions utilisateur. Sans séparation en couches, toute la logique s’entasse — modifier un point peut impacter l’ensemble, rendant la maintenance impossible.

Philosophie de la conception en trois couches

OpenClaw divise le système en trois couches, chacune avec sa responsabilité :

Couche Gateway (centre de gestion des sessions)

• Gestion du cycle de vie complet des sessions utilisateur
• File d’attente et ordonnancement des messages (priorités)
• Authentification et contrôle des permissions (qui peut utiliser)
• Maintien des connexions WebSocket longues

Couche Channel (adaptateur de plateforme)

• Adaptation des formats de message selon la plateforme (WhatsApp et Telegram diffèrent)
• Règles de routage (DM ou groupe, réponse uniquement sur @)
• Gestion des événements (réception, envoi, erreurs)

Couche LLM (interface modèle)

• Interface Provider unifiée (même mode d’appel pour Claude ou GPT)
• Appel d’outils (Function Calling)
• Traitement des réponses en streaming
• Intégration des serveurs MCP

Flux complet de traitement d’un message

Un scénario concret : vous envoyez un message au bot sur WhatsApp.

1. Réception Channel : le Channel WhatsApp reçoit le webhook et normalise le message au format interne
2. Décision de routage : vérification DM/groupe, mention du bot, permissions utilisateur
3. Ordonnancement Gateway : trouver (ou créer) la Session de l’utilisateur, ajouter le message à la file
4. Traitement LLM : selon la config, choisir un Provider (ex. Anthropic) et envoyer le contexte de conversation
5. Retour de la réponse : résultat LLM → Gateway → Channel → l’utilisateur reçoit la réponse

La finesse de ce design : chaque couche est indépendante. Nouvelle plateforme ? Modifier uniquement Channel. Changer de modèle ? Modifier uniquement LLM. Gateway reste intact.

Couche Gateway : pivot central de la gestion des sessions

En lisant le code Gateway, ce qui m’a le plus déconcerté, c’est l’objet Session. Chaque utilisateur en a une — mais que contient-il exactement, et comment est-il géré ?

Cycle de vie d’une Session

Imaginez Gateway comme un centre de tri postal : chaque utilisateur est une adresse de livraison, la Session est le registre de cette adresse.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Contenu d’un objet Session :

• conversationHistory : historique de conversation (N derniers messages)
• context : variables de contexte (préférences utilisateur, données temporaires)
• state : état courant (idle, processing, waiting)
• channelInfo : informations de la plateforme source (Channel d’origine)

Gestion du cycle de vie :

// Exemple simplifié, logique centrale
class SessionManager {
  // À la réception d'un message
  async handleMessage(userId, channelId, message) {
    // 1. Trouver la Session (ou en créer une)
    let session = this.getOrCreate(userId, channelId);

    // 2. Mettre à jour l'historique
    session.conversationHistory.push(message);

    // 3. Ajouter à la file de traitement
    await this.messageQueue.enqueue(session, message);

    // 4. Persister (éviter la perte en cas de crash)
    await this.persist(session);
  }
}

Point clé : OpenClaw utilise le mode d’isolation per-channel-peer. Concrètement, le même utilisateur sur WhatsApp et Telegram a deux Sessions indépendantes. Cela évite la confusion de contexte — technique sur WhatsApp, météo sur Telegram, sans mélange.

Stratégie de priorité de l’ordonnancement des messages

Gateway ne traite pas immédiatement chaque message reçu ; il passe par une file d’ordonnancement. Deux problèmes résolus :

Problème 1 : contrôle de concurrence
Si 100 utilisateurs envoient un message simultanément et que tout part directement vers le LLM, l’API est saturée. La file Gateway limite le débit, par ex. « 10 requêtes simultanées maximum ».

Problème 2 : retry en cas d’erreur
Si l’appel LLM échoue ? Gateway retente automatiquement 3 fois avec un intervalle croissant (1 s, 2 s, 4 s), évitant la perte de messages sur une panne transitoire.

// Logique centrale de la file de messages
class MessageQueue {
  async enqueue(session, message) {
    // Vérifier la concurrence
    if (this.activeJobs >= this.maxConcurrency) {
      // Placer en file d'attente
      this.waitingQueue.push({ session, message });
      return;
    }

    // Exécuter le traitement
    this.activeJobs++;
    try {
      await this.process(session, message);
    } catch (error) {
      // Logique de retry
      await this.retryWithBackoff(session, message);
    } finally {
      this.activeJobs--;
      this.processNext(); // traiter le suivant
    }
  }
}

Les pièges des connexions WebSocket longues

Pour des applications exigeant du temps réel (ex. bot de support client), la gestion WebSocket est un vrai défi.

Approche d’OpenClaw :

• Heartbeat : ping toutes les 30 secondes, timeout = connexion considérée comme coupée
• Reconnexion automatique : backoff exponentiel après déconnexion (1 s, 2 s, 4 s… max 30 s)
• Synchronisation d’état : restauration automatique de la Session après reconnexion

Ces détails semblent mineurs, mais améliorent nettement la stabilité. J’ai déjà écrit un système similaire sans heartbeat — connexion fantôme, messages perdus sans que le programme le sache.

Couche Channel : routage multi-plateforme

La couche Channel est pour moi la plus intéressante. Elle résout un problème central : les formats de message diffèrent totalement selon les plateformes — comment les traiter de façon unifiée ?

L’utilité du pattern Adapter

Message WhatsApp :

{
  "from": "1234567890",
  "body": "Bonjour",
  "type": "text"
}

Message Telegram :

{
  "message": {
    "chat": {"id": 123},
    "text": "Bonjour"
  }
}

Écrire une logique par plateforme ferait exploser le code. OpenClaw applique le pattern Adapter classique : une interface Message standardisée, chaque Channel convertissant le message de sa plateforme vers ce format.

// Format de message standardisé
interface StandardMessage {
  userId: string;      // ID utilisateur unifié
  content: string;     // Contenu du message
  timestamp: number;   // Horodatage
  metadata: any;       // Données spécifiques à la plateforme
}

// Adaptateur WhatsApp
class WhatsAppChannel implements Channel {
  adaptMessage(rawMessage): StandardMessage {
    return {
      userId: rawMessage.from,
      content: rawMessage.body,
      timestamp: Date.now(),
      metadata: { platform: 'whatsapp' }
    };
  }
}

Avantage : Gateway et LLM ignorent la plateforme d’origine — ils ne traitent que des StandardMessage.

Principe d’implémentation des règles de routage

Autre responsabilité importante de Channel : décider quels messages méritent une réponse.

OpenClaw supporte deux types de règles :

dmPolicy (politique de messages privés)

• pairing : appairage préalable requis (le plus sûr)
• allowlist : seuls les utilisateurs en liste blanche
• open : tout le monde peut utiliser (bot public)
• disabled : messages privés désactivés

mentionGating (déclenchement par @ en groupe)
En groupe, réponse uniquement si le bot est mentionné, évitant le spam. Logique simple :

class TelegramChannel {
  shouldRespond(message): boolean {
    // Message privé : répondre directement
    if (message.chat.type === 'private') {
      return this.checkDmPolicy(message.from.id);
    }

    // Groupe : vérifier @
    if (message.chat.type === 'group') {
      const mentioned = message.entities?.some(
        e => e.type === 'mention' && e.user.id === this.botId
      );
      return mentioned;
    }

    return false;
  }
}

En développant un Channel DingTalk, j’ai suivi cette logique. La détection @ DingTalk diffère légèrement (champ atUsers), mais le cadre reste le même.

Méthode pour développer un Channel personnalisé

Pour intégrer Discord, le flux ressemble à ceci :

1. Créer la classe Channel : implémenter l’interface Channel
2. Implémenter les méthodes requises :
   • start() : démarrer le Channel (écouter webhook ou WebSocket)
   • sendMessage() : envoyer un message vers la plateforme
   • adaptMessage() : conversion de format
3. Enregistrer dans le système : ajouter la config Channel
4. Tester : exposer le service local avec ngrok, tester le webhook

Les exemples complets sont dans la section pratique en fin d’article.

Couche LLM : conception plugin de l’interface modèle

La couche LLM a subi en 2026 une refonte majeure, passant du hardcodé au système de plugins. Ce changement détermine combien de modèles OpenClaw peut supporter.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Système de plugins Provider

Ancien design (pseudo-code) :

// Ancien design : hardcodé
if (config.provider === 'anthropic') {
  return new AnthropicClient();
} else if (config.provider === 'openai') {
  return new OpenAIClient();
}

Problème : chaque nouveau modèle ajoute un if-else, le code grossit indéfiniment.

Le nouveau design introduit l’interface Provider :

// Définition de l'interface Provider
interface LLMProvider {
  name: string;  // 'anthropic', 'openai', 'ollama'

  // Envoyer un message, retourner une réponse en streaming
  chat(messages: Message[], options: ChatOptions): AsyncIterator<string>;

  // Support des appels d'outils
  supportTools(): boolean;

  // Initialisation de la configuration
  initialize(config: ProviderConfig): void;
}

Tout Provider implémentant cette interface peut s’intégrer. Au démarrage, le système scanne et enregistre automatiquement :

// Mécanisme d'enregistrement des plugins
class ProviderRegistry {
  private providers = new Map<string, LLMProvider>();

  register(provider: LLMProvider) {
    this.providers.set(provider.name, provider);
  }

  get(name: string): LLMProvider {
    return this.providers.get(name);
  }
}

// Découverte et enregistrement automatiques
const registry = new ProviderRegistry();
registry.register(new AnthropicProvider());
registry.register(new OpenAIProvider());
registry.register(new OllamaProvider());

Avantage : nouveau modèle ? Écrire une classe Provider, l’enregistrer — sans toucher au code central.

Différences entre les Providers principaux

L’interface est unifiée, mais les détails d’implémentation varient. Quelques pièges que j’ai rencontrés :

Provider Anthropic (Claude)

• Streaming natif (stream: true)
• Format Tool Use particulier (tableau tools)
• Grande fenêtre de contexte (Claude 3.5 jusqu’à 200k tokens)

Provider OpenAI (ChatGPT)

• Function Calling et Tool Use sont deux API (ancienne version functions, nouvelle tools)
• Le streaming retourne des fragments delta à concaténer manuellement
• Limites de taux strictes (RPM/TPM à contrôler)

Provider Ollama (modèles locaux)

• Pas de clé API, appel HTTP direct au service local
• Performance très dépendante du matériel (CPU lent, GPU recommandé)
• Support des outils variable selon le modèle (llama3 oui, qwen parfois non)

J’ai voulu faire tourner Llama3 en local via Ollama — le format d’appel d’outils diffère totalement de Claude, adaptation laborieuse.

Mécanisme Tool Use en détail

Le Tool Use (appel d’outils) est une fonction centrale de la couche LLM : permettre à l’IA d’« appeler des fonctions ».

Exemple : « Quelle heure est-il à Pékin ? » L’IA va :

1. Décider d’appeler l’outil get_current_time
2. Retourner la requête d’appel : {"name": "get_current_time", "args": {"city": "Pékin"}}
3. OpenClaw exécute l’outil et retourne : {"time": "2026-02-05 20:30"}
4. L’IA génère la réponse : « Il est 20 h 30 à Pékin. »

Mécanisme d’enregistrement des outils dans OpenClaw :

// Définition des outils
const tools = [
  {
    name: 'get_current_time',
    description: 'Obtenir l\'heure actuelle d\'une ville',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'Nom de la ville' }
      },
      required: ['city']
    }
  }
];

// Exécution des outils
async function executeTool(toolName, args) {
  const handlers = {
    'get_current_time': (args) => {
      // L'implémentation réelle peut appeler une API
      return { time: new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' }) };
    }
  };

  return handlers[toolName](args);
}

Important : l’exécution des outils doit être isolée en sandbox — sinon l’IA pourrait demander rm -rf /. OpenClaw intègre un contrôle de permissions n’autorisant que les outils prédéfinis.

Pratique : étendre l’architecture OpenClaw

La théorie est posée, passons à la pratique. Deux exemples complets : développer un Channel Discord et un Provider Kimi.

Développer un Channel personnalisé : intégration Discord

Discord diffère de WhatsApp : WebSocket pour recevoir, REST API pour envoyer.

Étape 1 : implémenter l’interface Channel

import { Client, GatewayIntentBits } from 'discord.js';

class DiscordChannel implements Channel {
  private client: Client;
  private gateway: Gateway; // Instance Gateway OpenClaw

  async start() {
    // Initialiser le client Discord
    this.client = new Client({
      intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMessages,
        GatewayIntentBits.DirectMessages
      ]
    });

    // Écouter les messages
    this.client.on('messageCreate', async (msg) => {
      if (msg.author.bot) return; // Ignorer les messages de bots

      // Convertir au format standard
      const standardMsg = this.adaptMessage(msg);

      // Confier au Gateway
      const response = await this.gateway.handleMessage(standardMsg);

      // Envoyer la réponse
      await msg.reply(response.content);
    });

    // Connexion
    await this.client.login(process.env.DISCORD_TOKEN);
  }

  adaptMessage(discordMsg): StandardMessage {
    return {
      userId: discordMsg.author.id,
      channelId: 'discord',
      content: discordMsg.content,
      timestamp: discordMsg.createdTimestamp,
      metadata: {
        guildId: discordMsg.guildId,
        channelType: discordMsg.channel.type
      }
    };
  }

  async sendMessage(userId: string, content: string) {
    const user = await this.client.users.fetch(userId);
    await user.send(content);
  }
}

Étape 2 : enregistrer dans OpenClaw

Dans config.json :

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "dmPolicy": "open"
    }
  }
}

Dans le script de démarrage :

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

import { DiscordChannel } from './channels/discord';

const gateway = new Gateway(config);
const discordChannel = new DiscordChannel(gateway, config.channels.discord);
gateway.registerChannel('discord', discordChannel);

await discordChannel.start();

Étape 3 : tester

1. Créer un Bot sur la plateforme développeur Discord, obtenir le Token
2. Inviter le Bot sur votre serveur
3. Démarrer OpenClaw, envoyer un message privé au Bot
4. Vérifier les logs pour confirmer le flux de messages

Piège rencontré : le système de permissions Discord est complexe — le Bot doit avoir Send Messages et Read Message History, sinon l’envoi échoue.

Développer un Provider personnalisé : intégration Kimi

L’API Kimi (Moonshot AI) ressemble à OpenAI, avec quelques différences.

Implémentation Provider :

class KimiProvider implements LLMProvider {
  name = 'kimi';
  private apiKey: string;
  private baseURL = 'https://api.moonshot.cn/v1';

  initialize(config: ProviderConfig) {
    this.apiKey = config.apiKey;
  }

  async *chat(messages: Message[], options: ChatOptions) {
    const response = await fetch(`${this.baseURL}/chat/completions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: options.model || 'moonshot-v1-8k',
        messages: messages.map(m => ({
          role: m.role,
          content: m.content
        })),
        stream: true,
        temperature: options.temperature || 0.7
      })
    });

    // Traiter la réponse en streaming
    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n').filter(line => line.trim());

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') continue;

          const parsed = JSON.parse(data);
          const content = parsed.choices[0]?.delta?.content;
          if (content) {
            yield content;
          }
        }
      }
    }
  }

  supportTools(): boolean {
    return false; // Kimi ne supporte pas encore Function Calling
  }
}

Enregistrer le Provider :

const registry = new ProviderRegistry();
registry.register(new KimiProvider());

// Configuration d'utilisation
const config = {
  llm: {
    provider: 'kimi',
    apiKey: process.env.KIMI_API_KEY,
    model: 'moonshot-v1-32k'
  }
};

Retours d’expérience :

• Le format de streaming Kimi est identique à OpenAI, réutilisable directement
• La gestion d’erreurs diffère — le timeout ne retourne pas de code d’erreur standard
• Pas de Function Calling pour l’instant — inutilisable si votre application en dépend

Pratiques d’optimisation des performances

Faire fonctionner le code n’est qu’une première étape ; l’optimisation est le vrai travail. Quelques points testés :

Optimisation du cache Session
Par défaut, la Session est en mémoire — perdue au redémarrage. Intégration Redis possible :

class RedisSessionStore {
  private redis: Redis;

  async get(userId: string, channelId: string): Promise<Session> {
    const key = `session:${channelId}:${userId}`;
    const data = await this.redis.get(key);
    return data ? JSON.parse(data) : null;
  }

  async set(session: Session) {
    const key = `session:${session.channelId}:${session.userId}`;
    await this.redis.setex(key, 3600, JSON.stringify(session)); // expiration 1 h
  }
}

Réglage de la file de messages
En haute concurrence, la file en mémoire ne suffit pas — Bull (file de tâches Redis) :

import Queue from 'bull';

const messageQueue = new Queue('openclaw-messages', {
  redis: { host: 'localhost', port: 6379 }
});

messageQueue.process(10, async (job) => { // 10 concurrents max
  const { session, message } = job.data;
  return await gateway.processMessage(session, message);
});

Contrôle du nombre de connexions concurrentes
Les API LLM ont des limites de taux (ex. OpenAI 60 RPM). Bibliothèque p-limit :

import pLimit from 'p-limit';

const limit = pLimit(10); // 10 requêtes concurrentes max

const tasks = messages.map(msg =>
  limit(() => provider.chat(msg))
);

await Promise.all(tasks);

Comparaison avant/après optimisation (mes mesures) :

• Avant : 100 requêtes concurrentes, temps de réponse moyen 8 s, taux d’échec 15 %
• Après : 100 requêtes concurrentes, temps de réponse moyen 3 s, taux d’échec < 1 %

Conclusion

De Gateway à Channel puis LLM, l’architecture en trois couches d’OpenClaw est remarquablement claire. Chaque couche a sa responsabilité, les frontières sont nettes, l’extension est simple.

Une fois ce cadre compris, développer de nouvelles fonctionnalités devient plus fluide. Nouvelle plateforme ? Écrire un Channel Adapter. Nouveau modèle ? Implémenter un Provider. Optimiser les performances ? Identifier la couche concernée et agir de façon ciblée.

Si vous comptez personnaliser OpenClaw en profondeur, clonez d’abord le code source et parcourez-le en suivant la logique de cet article. Session Gateway, routage Channel, enregistrement Provider — ces trois blocs sont le cœur du système.

Maîtriser cela, vous ne « copiez plus la config de la doc » — vous comprenez le système et pouvez l’étendre et l’optimiser librement.

Essayez ensuite un Channel personnalisé simple (WeCom, Lark/Feishu) : la pratique approfondit la compréhension. La communauté open source OpenClaw est active — les GitHub Issues accueillent vos questions.

Prochaines lectures

• Guide de configuration OpenClaw : openclaw.json complet
• Configuration multi-plateforme OpenClaw : 13 Channels unifiés
• Guide d’installation OpenClaw 2026 : déploiement de zéro