← RETOUR À L'INDEX

Agent Telegram — notifications et commandes depuis son téléphone

Déployer un agent OpenClaw accessible via Telegram ou WhatsApp pour interagir avec son écosystème IA depuis son téléphone.

⚠️ Archivé — Ce tuto documente OpenClaw, framework remplacé par Hermes Agent (Nous Research, MIT License) depuis mai 2026. Contenu conservé à titre de référence historique. Voir 20-hermes/architecture pour l’écosystème actuel.

Temps estimé : 45 min

Résultat final : Un agent OpenClaw répond à tes messages Telegram, exécute des actions domotiques sur validation humaine, et ignore silencieusement tout compte non-autorisé.

Prérequis :

• TUTO-03 complété — OpenClaw opérationnel, agent telegram-agent configuré
• TUTO-05 complété — OpenClaw connecté à Home Assistant via Tailscale
• Un compte Telegram actif
• Variables d’environnement prêtes : TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID

---

Objectif

Connecter OpenClaw à Telegram pour :

• Envoyer et recevoir des messages via un bot dédié
• Déclencher des actions domotiques (HA) par commande textuelle
• Bloquer toute interaction depuis un compte non-autorisé
• Appliquer une validation humaine avant toute action irréversible

---

Étape 1 : Créer le bot Telegram via BotFather

1. Ouvre Telegram → recherche @BotFather
2. Envoie /newbot
3. Suis les instructions :
   • Nom du bot : ex. MonAssistant IA
   • Username : ex. mon_assistant_ocbot (doit se terminer par bot)
4. BotFather retourne un token de la forme 123456789:AAHxxxxxxxxxxxxxxxxxxxxxx

# Ajouter le token dans les variables d'environnement
echo 'export TELEGRAM_BOT_TOKEN="123456789:AAHxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.openclaw.env
source ~/.openclaw.env

# Vérifier que la variable est chargée
echo "${TELEGRAM_BOT_TOKEN:0:10}..."
# Doit afficher les 10 premiers caractères du token

5. Récupérer ton chat_id personnel :
   • Envoie un message quelconque à ton bot
   • Puis exécute :

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  | jq '.result[0].message.chat.id'

# Ajouter le chat_id dans les variables d'environnement
echo 'export TELEGRAM_CHAT_ID="TON_CHAT_ID"' >> ~/.openclaw.env
source ~/.openclaw.env

Checklist étape 1 :

• Bot créé via BotFather
• TELEGRAM_BOT_TOKEN dans ~/.openclaw.env
• TELEGRAM_CHAT_ID dans ~/.openclaw.env
• Variables sourcées et vérifiées

---

Étape 2 : Configurer l’allowlist Telegram dans openclaw.json

Sans allowlist, n’importe qui connaissant le username de ton bot peut interagir avec ton agent.

# Ouvrir openclaw.json
nano ~/.openclaw/openclaw.json

Section à configurer pour telegram-agent :

{
  "agents": {
    "telegram-agent": {
      "transport": "telegram",
      "telegram": {
        "botToken": "${TELEGRAM_BOT_TOKEN}",
        "allowedChatIds": ["${TELEGRAM_CHAT_ID}"],
        "silentRejectUnknown": true,
        "webhookMode": false
      },
      "tools": {
        "exec": {"security": "none"},
        "web_search": {"security": "read"},
        "ha_api": {"security": "read"}
      }
    }
  }
}

# Vérifier que la config JSON est valide
cat ~/.openclaw/openclaw.json | jq '.agents["telegram-agent"]'

# Recharger OpenClaw pour appliquer la config
openclaw restart telegram-agent

Checklist étape 2 :

• botToken = "${TELEGRAM_BOT_TOKEN}" (jamais la valeur brute)
• allowedChatIds contient uniquement "${TELEGRAM_CHAT_ID}"
• silentRejectUnknown = true
• exec = "none" pour telegram-agent
• openclaw restart telegram-agent → pas d’erreur

---

Étape 3 : Configurer WhatsApp Business API (optionnel — avancé)

⚠️ Niveau avancé : cette étape nécessite un numéro de téléphone dédié, un compte Meta Business vérifié, et ~30 min supplémentaires. Telegram est suffisant pour 95% des cas d’usage. Passer à l’étape 4 si non nécessaire.

Prérequis WhatsApp

• Compte Meta Business Manager vérifié
• Numéro de téléphone dédié (pas ton numéro personnel)
• Token d’accès permanent WhatsApp Cloud API

# Ajouter le token WhatsApp dans les variables d'environnement
echo 'export WHATSAPP_TOKEN="EAAxxxxx..."' >> ~/.openclaw.env
echo 'export WHATSAPP_PHONE_ID="1234567890"' >> ~/.openclaw.env
source ~/.openclaw.env

Configuration dans openclaw.json :

{
  "agents": {
    "whatsapp-agent": {
      "transport": "whatsapp",
      "whatsapp": {
        "accessToken": "${WHATSAPP_TOKEN}",
        "phoneNumberId": "${WHATSAPP_PHONE_ID}",
        "allowedNumbers": ["+33XXXXXXXXX"],
        "webhookVerifyToken": "${WHATSAPP_WEBHOOK_SECRET}"
      }
    }
  }
}

Checklist étape 3 (WhatsApp) :

• Compte Meta Business vérifié
• Numéro dédié (pas perso)
• WHATSAPP_TOKEN et WHATSAPP_PHONE_ID dans ~/.openclaw.env
• allowedNumbers configuré avec ton seul numéro
• webhookVerifyToken généré via openssl rand -hex 32

---

Étape 4 : Tests de messagerie bidirectionnelle

Test 1 — Réception de message

# Vérifier que le bot répond à un message simple
# Envoie "ping" depuis Telegram → le bot doit répondre
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  | jq '.result[-1] | {from: .message.from.username, text: .message.text}'

Test 2 — Envoi depuis OpenClaw vers Telegram

# Tester l'envoi d'un message depuis le VPS
curl -s -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d "{
    \"chat_id\": \"${TELEGRAM_CHAT_ID}\",
    \"text\": \"✅ Test OpenClaw → Telegram OK\"
  }" | jq '.ok'
# Attendu : true

Test 3 — Rejet d’un compte non-autorisé (cf. TUTO-02d Vecteur 3)

# Demander à un ami (ou utiliser un compte test) d'envoyer un message au bot
# ✅ Attendu : aucune réponse du bot
# ❌ Si le bot répond : silentRejectUnknown non appliqué — revoir étape 2

# Vérifier dans les logs OpenClaw que le rejet est loggé en interne
tail -20 ~/.openclaw/logs/telegram-agent.log | grep "rejected\|unauthorized"

Checklist étape 4 :

• Message “ping” → réponse reçue depuis ton compte
• Envoi VPS → Telegram : .ok = true
• Test compte tiers : aucune réponse
• Log de rejet présent dans telegram-agent.log

---

Étape 5 : Sécuriser — rate limiting, allowlist, validation humaine pour actions HA

Rate limiting

nano ~/.openclaw/openclaw.json

Ajouter dans la config telegram-agent :

"rateLimit": {
  "messagesPerMinute": 10,
  "actionsPerHour": 20,
  "onExceeded": "silent_drop"
}

Validation humaine avant actions HA

Ajouter dans la config telegram-agent :

"humanValidation": {
  "enabled": true,
  "requiredFor": [
    "ha.services.call",
    "ha.states.set",
    "file.delete",
    "git.push",
    "git.merge"
  ],
  "confirmationTimeout": 60,
  "confirmationKeyword": "oui",
  "cancellationKeyword": "non",
  "logFile": "~/.openclaw/logs/human-validation.log"
}

Vérification finale de la config exec

# Vérifier que exec est bien désactivé pour telegram-agent
cat ~/.openclaw/openclaw.json | jq '.agents["telegram-agent"].tools.exec'
# Attendu : "none"
# ❌ Si absent ou différent : corriger AVANT de connecter Telegram à HA

# Recharger la config
openclaw restart telegram-agent

# Test de validation humaine
# Envoie depuis Telegram : "allume la lumière du salon"
# → L'agent doit répondre : "Action prévue : ha.services.call light.turn_on salon. Confirmer ? (oui/non)"
# → Réponds "oui" → l'action s'exécute
# → Réponds "non" → l'action est annulée et loggée

Checklist étape 5 :

• Rate limiting configuré (messagesPerMinute: 10)
• humanValidation.enabled: true
• Actions HA dans requiredFor
• exec = "none" pour telegram-agent — vérifié via jq
• Test validation humaine : oui → exécution, non → annulation
• Log human-validation.log actif

---

Checklist finale TUTO-06

Bot et authentification

• Bot Telegram créé via BotFather
• TELEGRAM_BOT_TOKEN dans ~/.openclaw.env (jamais en dur)
• TELEGRAM_CHAT_ID dans ~/.openclaw.env

Sécurité agent

• allowedChatIds = uniquement ton chat_id
• silentRejectUnknown: true
• exec: "none" pour telegram-agent — vérifié
• Rate limiting actif
• Validation humaine pour toutes les actions HA

Tests validés

• Message reçu depuis ton compte → réponse
• Envoi VPS → Telegram : .ok = true
• Compte tiers → aucune réponse (rejet silencieux)
• Action HA via Telegram avec confirmation humaine : fonctionnelle

---

Dépannage

Le bot ne répond pas à mes messages

# Vérifier que le token est valide
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe" | jq '.ok, .result.username'
# Attendu : true + le username du bot

# Vérifier les logs OpenClaw
tail -50 ~/.openclaw/logs/telegram-agent.log

getUpdates retourne un tableau vide

Envoie d’abord un message au bot depuis Telegram, puis relance. Le polling getUpdates n’a pas de backfill.

chat_id retourne null avec jq

# Afficher le retour complet pour diagnostic
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | jq '.'
# Si .result est vide : envoyer un message au bot d'abord

Validation humaine ne se déclenche pas

# Vérifier la config humanValidation dans openclaw.json
cat ~/.openclaw/openclaw.json | jq '.agents["telegram-agent"].humanValidation'
# Vérifier que openclaw a bien rechargé la config
openclaw status telegram-agent

---

Références

• Telegram BotFather : https://core.telegram.org/bots#botfather
• Telegram Bot API : https://core.telegram.org/bots/api
• WhatsApp Cloud API : https://developers.facebook.com/docs/whatsapp/cloud-api
• TUTO-02d Vecteur 3 — Allowlist Telegram : TUTO-02d

---

Tuto suivant : TUTO-07