2026 — OpenClaw Telegram : long polling ou webhook sur Mac physique distant ? Proxy HTTPS inverse, enregistrement et runbook 409 / timeout TLS reproductibles (extraits openclaw.json + FAQ)

2. Points de friction

1. Sous-estimer le HTTPS public pour les webhooks. Telegram attend une chaîne vérifiable et un point de terminaison HTTPS joignable (souvent le port 443). Certificats auto-signés, intermédiaires manquants ou DNS visibles seulement sur le LAN se traduisent par des erreurs TLS ou une non-livraison silencieuse.
2. Le HTTP 409 n’est pas du bruit. Partager un jeton de bot entre préproduction et production, ou laisser un ancien nœud sans deleteWebhook, provoque des conflits setWebhook — la cause est l’état d’enregistrement, pas la logique métier d’OpenClaw.
3. Le long polling n’est pas gratuit. RTT transfrontalier et connexions longues amplifient le jitter ; certains opérateurs limitent le débit. Idéal en PoC ; la production revient en général au webhook avec un bord sain.

3. Matrice de décision : long polling vs webhook

Utilisez-la comme mini « feu vert architecture » pour les nœuds ZoneMac distants.

4. Extraits openclaw.json (illustratifs)

Exemple structurel uniquement — les noms de clés et l’imbrication doivent correspondre à votre version d’OpenClaw. Sauvegardez les fichiers de production et fusionnez manuellement avec les sections gateway et identifiants existants.

4.1 Canal Telegram : webhook et écoute locale

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botTokenRef": "env:TELEGRAM_BOT_TOKEN",
      "transport": "webhook",
      "webhook": {
        "publicUrl": "https://bot.example.com/openclaw/telegram/webhook",
        "path": "/openclaw/telegram/webhook",
        "secretTokenRef": "env:TELEGRAM_WEBHOOK_SECRET",
        "maxConnections": 40,
        "dropPendingUpdates": false
      },
      "localServer": {
        "bind": "127.0.0.1",
        "port": 18789,
        "readTimeoutSeconds": 30,
        "writeTimeoutSeconds": 30
      }
    }
  },
  "gateway": {
    "reverseProxy": {
      "trustedProxies": ["10.0.0.0/8"],
      "forwardedHeaders": ["X-Forwarded-For", "X-Forwarded-Proto"]
    }
  }
}

Pour le long polling, réglez transport sur "longPolling" (ou l’équivalent de votre release) et fournissez les options getUpdates telles que timeout / allowed_updates ; assurez-vous que Telegram ne pointe plus un webhook vers une ancienne URL.

4.2 Proxy inverse (esquisse Caddy)

# TLS terminé au bord ; proxy vers 127.0.0.1:18789 sur le Mac.
# Cohérence Host/chemin avec OpenClaw ; limitez le corps selon la doc passerelle.

bot.example.com {
  reverse_proxy 127.0.0.1:18789 {
    header_up X-Forwarded-Proto {scheme}
    header_up X-Forwarded-For {remote_host}
  }
}

5. Runbook en sept étapes (Mac physique distant)

1. Geler le mode de transport. Un seul chemin actif. En passant du long polling au webhook, arrêtez d’abord le processus de polling pour éviter une double livraison.
2. Valider le TLS de bout en bout. Depuis Internet, testez le 443 : chaîne complète, SNI correct, règles pare-feu pour les plages Telegram (selon la doc officielle).
3. Fusionner openclaw.json. cp openclaw.json openclaw.json.bak.$(date +%Y%m%d%H%M) ; définir publicUrl, références secrètes et bind local.
4. Nettoyer l’ancien webhook. getWebhookInfo → si l’URL est incorrecte, deleteWebhook → setWebhook depuis un seul endroit pour limiter les 409.
5. Recharger et vérifier la santé. Rechargez selon votre méthode ; confirmez le port d’écoute et l’absence de boucles crash dans launchd.
6. Tests positifs et négatifs. Message de test ; un secret_token erroné doit échouer vite ; surveillez pending_update_count.
7. Archiver. Notez domaine, propriétaire du renouvellement de certificat, paramètres setWebhook et retour possible au long polling.

6. Triage 409 et timeout TLS

7. Chiffres et repères vérifiables

• Long poll getUpdates : le timeout est en général 0–50 secondes selon la doc Bot API ; partez prudent sur les liens à RTT élevé.
• HTTP local : l’exemple 127.0.0.1:18789 reste en loopback ; le proxy porte le TLS et la face publique — cohérent avec les nœuds ZoneMac « SSH d’abord ».
• Concurrence webhook : dimensionnez maxConnections avec les workers passerelle et le débit modèle amont pour ne pas accepter plus vite que le cœur ne vide.

8. FAQ

9. Synthèse et pourquoi le Mac mini colle à cette pile

Long polling contre webhook ne se résume pas au « plus récent » : il s’agit d’accepter ou non un HTTPS de niveau production et une seule source de vérité pour l’enregistrement. Les webhooks déplacent l’observabilité vers getWebhookInfo ; le long polling concentre la complexité sur les chemins sortants et la surveillance de processus.

Sur un Mac physique distant ZoneMac, un nœud de type Mac mini M4 combine faible puissance en veille (de l’ordre de quelques watts), services de type Unix natifs et démons compatibles launchd — la même machine peut héberger proxy inverse et OpenClaw, idéale pour passerelles sans opérateur. Le durcissement macOS (Gatekeeper, SIP, FileVault) réduit aussi l’inquiétude d’exposition prolongée par rapport à un hôte Windows « utilitaire » typique.

Si vous voulez l’ingress Telegram, le TLS et OpenClaw sur un matériel silencieux et prévisible, le Mac mini M4 reste un excellent rapport prix-stabilité pour démarrer — louez un Mac physique distant chez ZoneMac et répétez ce runbook sur du métal réel.