Configuration du Bot Telegram OpenClaw : Commandes, Routage et Sessions Multi-Agents

Salut les créateurs d'automatisation — si vous connectez OpenClaw à Telegram et vous vous demandez comment le routage fonctionne réellement lorsque les messages affluent depuis les DMs, les groupes et les sujets, restez à l'écoute.

J'ai passé les deux dernières semaines à faire fonctionner OpenClaw via Telegram dans trois configurations différentes : DMs personnels, groupes d'équipe et sujets de forum. Pas des scénarios de démonstration. De vrais tests de routage où j'ai délibérément cassé l'isolation des sessions, saturé avec des requêtes simultanées, et observé comment la passerelle gérait les configurations multi-comptes.

La question qui revenait sans cesse : Cela peut-il réellement maintenir des limites de session claires lorsque vous jonglez avec plusieurs discussions, ou tout s'effondre-t-il en un seul fil de conversation désordonné ?

Voici ce que j'ai découvert, ainsi que les schémas de configuration exacts qui ont tenu le coup.

Pour contexte, OpenClaw (précédemment Moltbot et Clawdbot) a gagné plus de 100 000 étoiles sur GitHub au début de 2026 en tant qu'assistant AI autonome open-source. Créé par Peter Steinberger, il connecte des plateformes de messagerie comme Telegram à des agents AI fonctionnant localement ou sur des serveurs privés.

Créer un Bot Telegram (BotFather)

Every OpenClaw Telegram setup starts with @BotFather, Telegram's official bot creation interface. This hasn't changed since Telegram launched bots — it's still the only way to generate API tokens.

What you'll need:

• Active Telegram account (phone verification required)
• 3 minutes for initial setup
• Bot token stored somewhere secure (I use a password manager)

Step-by-step bot creation

1. Open Telegram and search for @BotFather
   1. Verified account has a blue checkmark
   2. Send /start to see available commands
2. Create new bot with /newbot
   1. Bot name: What users see in conversations (can include spaces)
   2. Username: Must end with bot (e.g., YourProjectBot)
   3. Username must be globally unique across Telegram
3. Save your API token immediately
   1. Format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
   2. Treat this like a password — anyone with this token controls your bot
   3. If compromised, use /revoke in BotFather to generate a new one

Critical BotFather settings (optional but recommended):

/setjoingroups  → Allow/deny adding bot to groups
/setprivacy     → OFF = bot sees all group messages
                  ON = bot only sees mentions and commands

I learned this the hard way: if you set privacy to ON and wonder why your bot ignores group messages, that's why. OpenClaw's routing expects full message access by default.

Connect Token + Verify Updates

Getting the token into OpenClaw is where most setup guides stop — but that's where real testing should start.

Basic connection config

OpenClaw supports two token input methods:

Environment variable (quick testing):

export TELEGRAM_BOT_TOKEN="your_token_here"
openclaw gateway

Config file (production approach):

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      "dmPolicy": "pairing"
    }
  }
}

Verification test sequence

Here's the sequence I run every time to confirm the Gateway actually sees Telegram updates:

1. Start Gateway with logging:

openclaw gateway --log-level debug

1. Send /start to your bot in Telegram
   1. Should trigger pairing flow if dmPolicy: "pairing"
   2. Check terminal for incoming update logs
2. Monitor update stream:

openclaw logs --follow

Common failure point: Bot token typo. If you see 401 Unauthorized in logs, regenerate the token in BotFather and update your config. Don't waste an hour troubleshooting like I did.

Remarque de sécurité : Pour les déploiements en production, envisagez d'utiliser l'image OpenClaw sécurisée de DigitalOcean qui inclut des règles de pare-feu, une isolation des conteneurs et une exécution en tant qu'utilisateur non-root par défaut.

Conception de commandes à grande échelle

Le système de commandes d'OpenClaw est là où la logique de routage commence à prendre de l'importance. Le Gateway reconnaît les commandes slash sur tous les canaux, mais Telegram ajoute sa propre couche d'autocomplétion des commandes.

Le dépôt officiel d'OpenClaw documente l'ensemble complet des commandes, mais après des tests en conditions réelles, seules quelques-unes s'avèrent essentielles.

Modèles de commandes de base

Voici les commandes que j'utilise réellement dans les configurations de production (ce n'est pas la liste complète — juste celles qui survivent à l'usage réel) :

Important: /activation always only affects the current session. To persist it, add it to your config's requireMention settings.

Setting up custom commands in BotFather

This is what makes your bot feel native in Telegram:

1. In BotFather: /mybots → Select your bot → Edit Commands
2. Send command list (one per line):

new - Start fresh sessionstatus - Check session statehelp - Show all commands

1. These appear in Telegram's / autocomplete menu

Reality check: I initially set up 15 commands. After two weeks, I only use 4. Start minimal.

For deeper understanding of Telegram's bot architecture, see the official Telegram Bot tutorial which covers the Bot API fundamentals.

Routing by Chat/User/Topic

This is where OpenClaw's session architecture either makes sense or falls apart. Session keys determine whether conversations stay isolated or bleed together.

Session key structure

OpenClaw generates session keys using this pattern:

agent:<agentId>:telegram:<chatType>:<chatId>[:topic:<topicId>]

Breakdown:

• DMs: All messages from one user → shared main session
• Groups: Each group → isolated session (telegram:group:<chatId>)
• Forum topics: Each topic → separate session (:topic:<threadId> suffix)

Multi-account routing config

Here's a real config I ran for testing three separate Telegram bots routing to different agents:

{
  "channels": {
    "telegram": {
      "accounts": [
        {
          "name": "personal",
          "botToken": "token1...",
          "routing": { "agent": "main" }
        },
        {
          "name": "work",
          "botToken": "token2...",
          "routing": { "agent": "work-agent" }
        },
        {
          "name": "testing",
          "botToken": "token3...",
          "routing": { "agent": "sandbox" }
        }
      ]
    }
  }
}

Each account routes to a separate agent workspace with independent memory and tools. No cross-contamination.

Group routing with mention controls

Default behavior: groups require @mention to trigger responses. Override per-group:

{
  "channels": {
    "telegram": {
      "groups": {
        "*": { "requireMention": true },
        "-1001234567890": { 
          "requireMention": false 
        }
      }
    }
  }
}

Group ID discovery: Add bot to group, send a message, check openclaw logs --follow for the chat.id value (always negative for groups).

Forum topic isolation

Telegram forums add message_thread_id to messages. OpenClaw appends :topic:<threadId> to session keys automatically.

Critical edge case I hit: Topic ID 1 (general topic) requires special handling. OpenClaw omits message_thread_id when sending to topic 1 because Telegram rejects it.

Config example for per-topic system prompts:

{
  "telegram": {
    "groups": {
      "-1003595003457": {
        "requireMention": false,
        "topics": {
          "14": {
            "requireMention": false,
            "systemPrompt": "You are a coding assistant."
          },
          "27": {
            "systemPrompt": "You focus on deployment issues."
          }
        }
      }
    }
  }
}

Each topic maintains isolated conversation history.

Debugging Missed Messages

When messages disappear into the void, it's usually one of these three culprits.

Diagnostic checklist

1. Check BotFather privacy settings

/mybots → Your Bot → Bot Settings → Group Privacy → OFF

1. If ON, bot only sees mentions — not regular messages.
2. Verify group whitelist

openclaw logs --follow | grep "skipping group message"

1. If channels.telegram.groups is defined, unlisted groups are ignored.
2. Confirm bot membership
   1. Bot must be added as a member (not just admin with no read access)
   2. Test: send a message, check if bot's "last seen" timestamp updates
3. Review Gateway logs

openclaw logs --level debug --filter telegram

Common routing failures

Session hygiene checks

I run this sequence weekly to catch routing drift:

# List active sessions
openclaw sessions list
# Check specific session state
openclaw sessions show <sessionKey>
# Force session cleanup (last resort)
openclaw sessions prune --older-than 7d

When sessions leak: If you see context bleeding between chats, it's usually a config error where multiple chats map to the same session key. Review channels.telegram.accounts[].routing.agent settings.

What Actually Worked Long-Term

After two weeks of daily use across three different Telegram setups, here's what survived:

Stable config pattern

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "env:TELEGRAM_BOT_TOKEN",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Why this works:

• DM pairing prevents unauthorized access
• Wildcard group policy with mention requirement = safe defaults
• Token from env var = easier rotation without touching config

What didn't scale

• Custom commands beyond /new, /status, /help — Users forget them
• Per-topic system prompts — Maintenance burden grows fast
• Multiple accounts without clear routing rules — Session chaos

Boundary conditions

OpenClaw Telegram routing is solid for:

• Personal DM automation (single user)
• Small team groups (< 20 active members)
• Forum topics with distinct purposes

It gets messy when:

• You're managing 10+ groups without config discipline
• Users expect instant responses (add queue monitoring)
• Session state matters across Gateway restarts (implement persistence checks)

Security reminder: As noted in security analysis, OpenClaw stores session transcripts and credentials locally. Treat your ~/.openclaw directory as sensitive — use encrypted drives and restrict file permissions.

Si OpenClaw + Telegram vous emmène là où vous devez aller, utilisez-le. Gardez simplement les clés de session propres et sachez quels groupes obtiennent quel agent.

Chez Macaron, nous gérons les mêmes défis de routage automatiquement — isolation des sessions sur les plateformes, pas de configuration manuelle à modifier lorsque vous ajoutez des canaux. Si vous voulez tester le routage multi-plateforme sans reconstruire les configurations à chaque fois que vous évoluez, essayez-le avec un vrai workflow et voyez comment il gère votre configuration.

FAQ

Q : Mon bot ne répond pas du tout aux messages de groupe. Où dois-je vérifier en premier ? Paramètres de confidentialité de BotFather. S'il est activé, le bot ne voit que les @mentions directes — tout le reste est silencieusement ignoré. Allez à BotFather → /mybots → Paramètres du bot → Confidentialité du groupe → désactivez-le. C'est la raison la plus courante du « pourquoi ça ne fonctionne pas » pour les configurations de groupe.

Q : Comment puis-je trouver l'ID de chat de mon groupe ? Ajoutez le bot au groupe, envoyez un message quelconque, puis exécutez openclaw logs --follow. Le chat.id apparaît dans la mise à jour entrante — ce sera un nombre négatif pour les groupes. C'est la valeur que vous mettez dans votre configuration de liste blanche.

Q : Ai-je besoin d'un jeton de bot distinct pour chaque compte Telegram que je route ? Oui. Chaque entrée dans channels.telegram.accounts[] nécessite son propre jeton BotFather. Un jeton, une identité de bot. Si vous gérez plusieurs bots et que les choses se mélangent, la référence de configuration de la passerelle OpenClaw explique comment l'isolation de routage au niveau du compte fonctionne réellement.

Q : Sujets de forum — dois-je configurer chacun manuellement ? Seulement si vous souhaitez des invites système par sujet. OpenClaw gère automatiquement l'isolation des clés de session (:topic:<threadId> suffixe), donc les conversations restent séparées sans aucune configuration. La configuration manuelle n'est nécessaire que si vous voulez un comportement d'agent différent par sujet.

Q : Les sessions perdent leur contexte après les redémarrages de Gateway. Est-ce normal ? Par défaut, oui — l'état de la session ne persiste pas après les redémarrages à moins que vous n'ayez configuré la persistance. Si c'est un problème pour votre cas d'utilisation, consultez le guide de démarrage rapide OpenClaw pour les options de persistance disponibles au niveau de Gateway.

Q : Je mets cela en place sur un VPS. Y a-t-il quelque chose de spécifique à Telegram que je devrais savoir ? Assurez-vous que les connexions sortantes de votre serveur vers api.telegram.org ne sont pas bloquées — certains fournisseurs de VPS bon marché restreignent cela. Au-delà de cela, les pratiques habituelles de sécurisation s'appliquent : exécution sans privilèges root, règles de pare-feu, token dans les variables d'environnement et non en dur. Le guide de déploiement OpenClaw sur VPS couvre l'ensemble de la configuration si vous partez de zéro.

Q : J'utilisais Moltbot pour Telegram. La migration est-elle simple ? Principalement oui, mais la structure de configuration a changé. Si vous rencontrez des conflits ou un comportement inattendu après le changement, la comparaison de configuration Moltbot pour Telegram vaut la peine d'être vérifiée — elle détaille ce qui a changé entre les deux.