2026 — Tutoriel reproductible OpenClaw passerelle multicanale : openclaw doctor, sondes santé et échecs Telegram/Discord — rechargement openclaw.json, conflit port 18789 et runbook Mac physique (FAQ)
Si vous faites tourner Telegram et Discord sur un Mac physique distant et voyez « un canal OK, l’autre mort » ou des sondes qui clignotent, ce guide rattache les pannes à la config, aux ports ou au réseau via openclaw doctor et les sondes. Vous obtenez une matrice symptôme → action, un runbook en sept étapes, trois chiffres réutilisables pour les SLO et une FAQ. Pour le chemin d’accès distant et les tunnels, voir aussi SSH local forward vs Tailscale Serve ; pour cadrer le choix de nœud, matrice de sélection des nœuds Mac distants 2026.
1. Trois points de friction récurrents (où les passerelles multicanales cassent)
1) Frontières floues du rechargement à chaud : vous modifiez openclaw.json et attendez un effet immédiat, mais secrets webhook, chemins de certificats TLS ou jetons de bot peuvent rester dans l’ancien processus — les journaux affichent donc des erreurs périmées alors que le fichier « semble correct ».
2) Port 18789 et instances dupliquées : l’HTTP local d’admin/diagnostic (cet article prend 18789 comme défaut courant ; remplacez par votre port réel) entre en collision si une autre passerelle, un vieux job launchd ou une session interactive écoute encore. Les sondes alternent alors entre connection refused et rafales 503, ce qui imite une panne Telegram/Discord amont.
3) Pannes asymétriques par canal : Telegram utilise souvent le long polling tandis que Discord mélange WebSocket et REST. Si la sortie d’entreprise, le proxy système et HTTP(S)_PROXY diffèrent entre launchd et votre shell de login, vous obtenez un classique « un canal time-out toujours, l’autre nickel » trompeur.
Avant de réécrire les configs canaux, vérifiez que l’installation de la passerelle correspond au layout attendu par l’éditeur — un décalage de version est le moyen le plus rapide de prendre une sortie doctor pour une panne réseau.
2. Matrice symptôme → action (classer avant de rebooter)
Croisez openclaw doctor avec les sondes et le tableau ci-dessous pour éviter « trois redémarrages puis pourquoi ? ».
| Ce que vous voyez | Faire d’abord | Famille de cause probable |
|---|---|---|
doctor indique HTTP local HS ; curl vers 127.0.0.1:18789 échoue |
Cartographier les listeners, tuer les processus obsolètes, réinstaller le plist via install-daemon |
Conflit de port / pas d’écoute |
Les deux canaux rouges ; la partie réseau de doctor échoue globalement |
Vérifier DNS, proxys et pare-feu sortant dans un environnement non interactif | Sortie / proxy |
| Discord seul échoue ; Telegram OK | Valider jeton + intents ; sonde TLS/SNI vers discord.com sous le même utilisateur que launchd | Identifiants / droits / chemin API |
| Changement JSON « partiellement appliqué » | Classer les clés redémarrage froid vs rechargement ; relancer doctor pour comparer |
Champs hors périmètre de reload |
3. Runbook Mac physique distant en 7 étapes (à coller dans le playbook)
- Instantané de base : exécuter
openclaw doctor, archiver la transcription complète, la semver de la passerelle et le hachage deopenclaw.json(par ex.shasum) pour des diffs de rollback triviaux. - Stabiliser les sondes : frapper l’URL de readiness au moins dix fois avec 3 s d’écart — un seul 200 ne suffit pas. Alignez avec les fenêtres de backoff KeepAlive de launchd.
- Matrice d’écoute 18789 :
lsof -nP -iTCP:18789 -sTCP:LISTEN(adaptez le port). S’il reste plusieurs PID liés à OpenClaw, ne gardez qu’une instance primaire. - Tests fumée par canal : Telegram : appel léger type getMe ; Discord : état shard/socket dans les journaux ou REST minimal. Ne masquez jamais l’échec d’un canal derrière un booléen « global healthy ».
- Rechargement à chaud vs démarrage à froid : étiqueter chaque clé JSON ; pour les champs sensibles, préférez un redémarrage contrôlé aux rafales de SIGHUP.
- Redémarrage contrôlé : arrêt via
launchctlou le fluxinstall-daemon, confirmer zéro listener, boot, puistaildes 200 premières lignes structurées. - Clôturer l’incident : dans les 30 minutes, relancer doctor, sondes et un vrai message utilisateur sur chaque canal — trois captures dans le ticket suffisent.
Pour la cartographie launchd / install-daemon / openclaw health, empilez ce runbook sur votre guide passerelle 7×24 existant — la cadence des sondes et le vocabulaire KeepAlive doivent être alignés mot pour mot.
4. Seuils et checklist (à coller dans les docs SLO)
- Intervalle de sonde : pour une readiness « passerelle », interroger toutes les 30 à 60 secondes ; sous ~15 s vous faussez positif sur les pics GC.
- Règle de succès consécutifs : exiger au moins cinq HTTP 2xx d’affilée avant « sain », sinon vous courez après du flap.
- Fenêtre de régression : après toute modification de config, boucler des messages de bout en bout sur les deux canaux dans les 30 minutes — barre minimum pour clôturer.
5. FAQ
Après édition d’openclaw.json, faut-il toujours redémarrer la passerelle ?
Identifiants de canaux, webhooks et champs TLS nécessitent en principe un redémarrage processus complet. Certaines versions rechargent des bascules sans listener, mais en production exécutez openclaw doctor puis un redémarrage contrôlé pour éviter des listeners à moitié chargés.
À quoi ressemble la contention sur le port 18789 ?
L’HTTP admin/diagnostic échoue à se lier ou se dégrade ; les sondes renvoient connection refused. Utilisez lsof, terminez les jobs passerelle obsolètes et redémarrez une fois le port libre.
Telegram OK, Discord HS — trois seaux de config à vérifier ?
Jeton et intents, listes blanches proxy pour les API Discord, résolution DNS de discord.com pour le compte utilisé par launchd. Combinez curl -I et la sortie doctor par canal pour isoler TLS/DNS et bugs applicatifs.
6. Pourquoi Mac mini facilite l’exploitation de cette pile passerelle
Le triage multicanal échoue quand les environnements divergent : votre shell interactif atteint Internet alors que le job launchd n’a ni proxy ni confiance AC personnalisée. macOS sur Apple Silicon offre une empreinte Node longue durée stable avec mémoire unifiée — moins de pics mémoire « mystère » la nuit. Le Mac mini M4 consomme environ 4 W au repos, idéal pour une passerelle placard ou baie, et Gatekeeper, SIP et FileVault réduisent la surface d’attaque par rapport à un hôte utilitaire Windows typique.
Si vous fan-out Telegram et Discord pour un public mondial, ancrer les passerelles sur des pools Mac physiques audités et épinglés par région évite le drame sortie mono-région et le débat « ça marche sur mon laptop, pas sur le serveur ».
Pour exécuter ce runbook sur du matériel silencieux, frais et prévisible, le Mac mini M4 reste l’un des meilleurs rapports prix/stabilité — découvrez les nœuds ZoneMac et alignez les sondes doctor avec un macOS de production dès le premier jour.
Besoin d’un Mac physique pour OpenClaw 7×24 ?
ZoneMac propose des Mac mini sélectionnables par région pour passerelles toujours allumées, CI et exploitation compatible conformité.