Compatible avec OpenClaw v2026.2 | Cet article s’adresse aux utilisateurs ayant terminé la configuration de base et souhaitant comprendre l’architecture en profondeur. Il est recommandé d’avoir suivi les 3 premiers tutoriels.

TL;DR : Le Gateway est le plan de contrôle central d’OpenClaw. La Session est le conteneur de contexte de conversation (main/channel/group), le Message Router détermine le routage des messages, le Tool Registry gère les permissions des outils, et les Skills sont des extensions de capacités pré-packagées. Point d’accès WebSocket : ws://127.0.0.1:18789/ws, commandes courantes : openclaw gateway/doctor/config. Comprendre ces concepts est la base de la configuration avancée.

Vue d’ensemble de l’architecture

Architecture globale

flowchart TB
    subgraph Clients["Couche client"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    subgraph Gateway["Couche Gateway"]
        WS[WebSocket Server]
        HTTP[HTTP Server]
        MR[Message Router]
        SM[Session Manager]
        TR[Tool Registry]
        EM[Event Manager]
        CFG[Config Store]
    end
    
    subgraph Agent["Couche Agent"]
        PI[Pi Agent]
        PROMPT[Prompt Engine]
        TOOLS[Tool Executor]
        SKILLS[Skills Manager]
    end
    
    subgraph External["Services externes"]
        FS[Système de fichiers]
        BR[Navigateur]
        API[Services API]
        DB[Base de données]
        CAL[Planificateur Cron]
    end
    
    Clients --> WS
    Clients --> HTTP
    WS --> MR
    HTTP --> MR
    MR --> SM
    SM --> PI
    PI --> PROMPT
    PI --> TOOLS
    PI --> SKILLS
    TOOLS --> TR
    TR --> External
    EM --> MR
    CFG --> SM
    CFG --> TR

Responsabilités des composants

Flux de données

sequenceDiagram
    participant U as Utilisateur
    participant C as Canal
    participant WS as WebSocket
    participant MR as Router
    participant SM as Session
    participant A as Agent
    participant T as Outils
    
    U->>C: Envoie un message
    C->>WS: Transmet le message
    WS->>MR: Requête de routage
    MR->>SM: Recherche/création de session
    SM-->>MR: Retourne la session
    MR->>A: Délivre le message
    A->>A: Traite le message
    A->>T: Appel d'outil (optionnel)
    T-->>A: Retourne le résultat
    A-->>MR: Génère la réponse
    MR->>WS: Envoie la réponse
    WS->>C: Transmet la réponse
    C-->>U: Affiche le message

Modèle de Session

Qu’est-ce qu’une Session ?

La Session est l’un des concepts les plus fondamentaux d’OpenClaw. Chaque Session représente un contexte de conversation indépendant, comprenant :

Types de Session

{
  "sessions": {
    "main": {
      "type": "main",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "high",
      "channel": null,
      "created": "2026-02-26T10:00:00Z"
    },
    "telegram:user:123456789": {
      "type": "channel",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "normal",
      "channel": "telegram",
      "sender": "123456789",
      "created": "2026-02-26T10:05:00Z"
    },
    "telegram:group:-100123456789": {
      "type": "group",
      "model": "anthropic/claude-sonnet-4",
      "thinkingLevel": "minimal",
      "channel": "telegram",
      "groupId": "-100123456789",
      "created": "2026-02-26T10:10:00Z"
    }
  }
}

Cycle de vie d’une Session

stateDiagram-v2
    [*] --> Created: Message reçu
    Created --> Active: Première réponse
    Active --> Active: Échange de messages
    Active --> Idle: Inactivité
    Idle --> Active: Nouveau message
    Idle --> Compacted: Compression automatique
    Compacted --> Active: Reprise de conversation
    Active --> Reset: Commande /reset
    Reset --> Created: Redémarrage
    Active --> Pruned: Nettoyage de session
    Idle --> Pruned: Nettoyage par timeout
    Pruned --> [*]

Commandes de Session

Envoyez les commandes suivantes dans le chat pour gérer les sessions :

Configuration des Sessions

{
  "sessionPruning": {
    "enabled": true,
    "maxAge": 86400000,
    "maxSize": 100,
    "pruneOnStartup": true
  },
  "sessionCompression": {
    "enabled": true,
    "threshold": 50000,
    "targetRatio": 0.3
  }
}

Message Router — Routage des messages

Règles de routage

Le Message Router est chargé de router les messages reçus vers la bonne Session :

flowchart TB
    MSG[Message reçu] --> CH{Type de canal ?}
    CH -->|Message privé| DM[Extraire l'ID expéditeur]
    CH -->|Groupe| GRP[Extraire l'ID du groupe]
    CH -->|WebChat/CLI| MAIN[Utiliser la session main]
    
    DM --> SID[Session : channel:user:id]
    GRP --> GID[Session : channel:group:id]
    
    SID --> EXISTS{Session existante ?}
    GID --> EXISTS
    
    EXISTS -->|Oui| LOAD[Charger la session]
    EXISTS -->|Non| CREATE[Créer une nouvelle session]
    
    CREATE --> LOAD
    LOAD --> AGENT[Délivrer à l'Agent]

Configuration du routage

{
  "messageRouting": {
    "defaultSession": "main",
    "channelMapping": {
      "telegram": {
        "userPrefix": "telegram:user",
        "groupPrefix": "telegram:group"
      },
      "whatsapp": {
        "userPrefix": "whatsapp:user",
        "groupPrefix": "whatsapp:group"
      }
    },
    "groupActivation": {
      "mode": "mention",
      "mentionPatterns": ["@bot", "/bot"]
    }
  }
}

Stratégies d’activation des groupes

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-100WORKGROUP": {
          "requireMention": false,
          "activationMode": "always"
        }
      }
    }
  }
}

Tool Registry — Registre des outils

Outils intégrés

OpenClaw inclut un ensemble riche d’outils intégrés :

Contrôle des permissions des outils

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off",
        "allowlist": ["read", "write", "bash", "web_search"],
        "denylist": []
      }
    }
  }
}

Configuration détaillée du sandbox

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history"
        ],
        "denylist": [
          "browser",
          "canvas",
          "camera",
          "screen_record"
        ]
      }
    }
  }
}

Système de Skills

Architecture des Skills

flowchart LR
    subgraph Skills["Répertoire Skills"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["Skills Manager"]
        DISC[Découverte]
        LOAD[Chargement]
        EXEC[Exécution]
    end
    
    subgraph Agent["Agent"]
        PROMPT[Injection Prompt]
        TOOLS[Enregistrement Tools]
        RES[Retour résultat]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Structure du répertoire Skills

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # Définition du skill
│   ├── package.json      # Dépendances (optionnel)
│   └── src/
│       └── index.js      # Implémentation (optionnel)
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

Structure d’un SKILL.md

# Gmail Skill

## Description
Send and read Gmail messages through OpenClaw.

## Triggers
- email
- gmail
- mail
- send email
- read email

## Instructions
When the user wants to send an email:
1. Ask for recipient, subject, and body
2. Use the gmail_send tool
3. Confirm the email was sent

When the user wants to check emails:
1. Use the gmail_list tool
2. Summarize the results

## Tools
- gmail_list: List recent emails
- gmail_send: Send an email
- gmail_read: Read a specific email

## Examples
User: "Check my email"
Action: Use gmail_list tool

User: "Send an email to [email protected]"
Action: Ask for subject and body, then use gmail_send

Méthodes d’installation des Skills

# Installer depuis ClawHub
openclaw skill install gmail

# Installer depuis GitHub
openclaw skill install github:user/repo/skill-name

# Installation manuelle
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

Configuration des Skills

{
  "skills": {
    "bundled": true,
    "managed": true,
    "workspace": true,
    "installGating": true
  }
}

Protocole WebSocket

Point d’accès

ws://127.0.0.1:18789/ws

Format des messages

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // Contenu du message
  }
}

Types de messages client

Types de messages serveur

Exemple : envoyer un message

// Connexion WebSocket
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// Envoyer un message
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: 'Bonjour, peux-tu te présenter ?'
  }
}));

// Recevoir la réponse
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // Exemple de sortie :
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: 'Bonjour ! Je suis votre assistant OpenClaw...',
  //     session: 'main'
  //   }
  // }
};

Système d’événements

Événements intégrés

Configuration des Webhooks

{
  "webhooks": [
    {
      "url": "https://your-server.com/webhook/openclaw",
      "events": ["message.received", "tool.invoked"],
      "secret": "your_webhook_secret",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Charge utile des Webhooks

{
  "event": "message.received",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "channel": "telegram",
    "sender": "123456789",
    "session": "telegram:user:123456789",
    "message": "Bonjour",
    "metadata": {
      "messageId": "msg_abc123",
      "timestamp": "2026-02-26T10:30:00Z"
    }
  },
  "signature": "sha256=..."
}

Tâches planifiées Cron

Exemple de configuration

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "Donne-moi mon planning du jour",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "Génère un résumé de travail de la semaine",
      "enabled": true
    }
  ]
}

Expression Cron

┌───────────── minute (0 - 59)
│ ┌───────────── heure (0 - 23)
│ │ ┌───────────── jour du mois (1 - 31)
│ │ │ ┌───────────── mois (1 - 12)
│ │ │ │ ┌───────────── jour de la semaine (0 - 6, 0 = dimanche)
│ │ │ │ │
* * * * *

Exemples courants

Hiérarchie et priorité de la configuration

Ordre de priorité

Paramètres CLI > Variables d'environnement > Fichier de configuration > Valeurs par défaut

Sources de configuration

Exemple de fusion de configuration

// ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

# Surcharge par variable d'environnement
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# Surcharge par paramètre CLI (priorité maximale)
openclaw gateway --model "anthropic/claude-opus-4"

Mise à jour à chaud de la configuration

# Mettre à jour la configuration (sans redémarrage)
openclaw config set agent.model "anthropic/claude-sonnet-4"

# Recharger le fichier de configuration
openclaw config reload

# Vérifier la configuration
openclaw config get agent.model

Aide-mémoire des commandes

Gestion du Gateway

# Démarrer le Gateway
openclaw gateway

# Spécifier un port
openclaw gateway --port 18790

# Exécution en arrière-plan
openclaw gateway --daemon

# Logs détaillés
openclaw gateway --verbose

# Vérification de santé
openclaw health

Gestion des sessions

# Lister toutes les sessions
openclaw session list

# Voir les détails d'une session
openclaw session show main
openclaw session show telegram:user:123456789

# Réinitialiser une session
openclaw session reset main

# Supprimer une session
openclaw session delete telegram:user:123456789

Gestion de la configuration

# Voir la configuration
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# Définir la configuration
openclaw config set agent.thinkingLevel high

# Lister toutes les configurations
openclaw config list

# Valider la configuration
openclaw config validate

Outils de diagnostic

# Diagnostic complet
openclaw doctor

# Vérifier un élément spécifique
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# Consulter les logs
openclaw logs
openclaw logs --follow
openclaw logs --level error

Dépannage

Le Gateway ne démarre pas

# Vérifier l'occupation du port
lsof -i :18789
netstat -tlnp | grep 18789

# Vérifier la syntaxe de la configuration
openclaw config validate

# Voir les erreurs détaillées
openclaw gateway --verbose 2>&1 | tee gateway.log

Perte de session

# Vérifier le répertoire des sessions
ls -la ~/.openclaw/sessions/

# Vérifier la configuration de nettoyage
openclaw config get sessionPruning

# Désactiver le nettoyage automatique
openclaw config set sessionPruning.enabled false

Échec d’appel d’outil

# Vérifier la configuration du sandbox
openclaw config get agents.defaults.sandbox

# Désactiver temporairement le sandbox
openclaw config set agents.defaults.sandbox.mode off

# Consulter les logs des outils
openclaw logs --filter tool

Échec de connexion WebSocket

# Vérifier l'état du Gateway
curl http://127.0.0.1:18789/health

# Vérifier le point d'accès WebSocket
wscat -c ws://127.0.0.1:18789/ws

# Vérifier le pare-feu
sudo ufw status
sudo iptables -L -n | grep 18789

Résumé

Comprendre les concepts fondamentaux du Gateway est la clé pour maîtriser OpenClaw :

• Session : conteneur de contexte de conversation, avec isolation par type
• Message Router : cœur du routage des messages, détermine leur destination
• Tool Registry : centre d’enregistrement des outils, contrôle les capacités de l’Agent
• Skills : système d’extension des compétences, pour enrichir rapidement les fonctionnalités
• WebSocket : protocole de communication en temps réel, supporte les clients personnalisés
• Système d’événements : mécanisme de distribution d’événements, supporte Webhooks et Cron

Ces concepts reviendront régulièrement dans les articles suivants. Les comprendre en profondeur vous aidera à mieux configurer et utiliser OpenClaw.

Résumé de cet article :

• Maîtrise de l’architecture globale du Gateway et des responsabilités des composants
• Compréhension du modèle de Session et de son cycle de vie
• Apprentissage du routage des messages et des stratégies d’activation des groupes
• Connaissance des permissions des outils et de la configuration du sandbox
• Maîtrise du protocole WebSocket et du système d’événements

Historique des mises à jour :

• 26/02/2026 : publication initiale, basée sur OpenClaw v2026.2

Navigation de la série :

• ← Précédent : Configuration des canaux : en commençant par Telegram
• → Suivant : Configuration et basculement multi-modèles