2026 OpenClaw Gateway : dépannage en échelle status → logs → doctor (port 18789 & canaux)

1. Ordre

Une ligne runtime: running ne prouve pas que 18789 écoute correctement, que le pairing est valide ni que les webhooks IM arrivent. Ajuster le modèle avant status, ou lancer doctor --fix avant d'avoir lu les JSONL dans l'ordre, mélange souvent permissions de canal et « modèle paresseux ». Discipline minimale : sauver status et une fenêtre de logs bornée avant tout redémarrage.

La découpe en couches évite qu'un même timeout soit attribué au mauvais plan : RTT passerelle, callback IM bloqué par pare-feu, ou socket fournisseur bloqué. Étiquetez incidents contrôle / données / canal pour des post-mortems alignés dans le temps.

2. Couches

1. Plan de contrôle : en gateway.mode=remote, un processus local peut tourner à vide ; vérifiez bind, listeners et sondes.
2. Plan données : sans ordre de lecture, vous noyez dans les INFO ; filtrez WARN/ERROR puis request id ; JSONL si disponible.
3. Canal : « connecté mais muet » suit mentions, droits de groupe, pairing expiré, scopes bot—pas toujours ERROR dans doctor.

Cette grille évite de régler la température quand le webhook n'a jamais atteint votre processus—scénario fréquent lorsqu'un scope OAuth manque dans Slack ou Discord.

3. Table

Si curl loopback échoue, ne faites pas tourner les tokens de canal tant que l'écoute n'est pas prouvée. DM ok mais pas le groupe : restez sur le plan canal et comparez les règles de mention.

4. Étapes

Même ordre sur Linux, macOS ou Mac cloud. Sous Docker, exécutez dans le même namespace ; comparez doctor hôte/conteneur seulement si les mêmes fichiers sont montés.

1. openclaw status : runtime, mode, bind ; si remote, URL amont et santé.
2. openclaw logs : ±10 minutes autour des releases ; WARN/ERROR d'abord ; TLS/DNS avant tokens.
3. openclaw doctor : lire sans --fix ; sauvegarder ~/.openclaw ou volumes avant correctifs auto.
4. 18789 : trouver le processus ; loopback + tunnel SSH ou reverse-proxy plutôt que port public nu.
5. Canaux : status/probe selon version ; re-pairing ; scopes bot et mentions groupe.
6. Régression : sonde DM minimale, puis outils, puis charge.

Archivez des extraits « connus bons » dans le runbook pour diff futures.

5. Faits

• 18789 : port local par défaut—voir release notes ; conflits = instances dupliquées.
• Pairing : fenêtre courte—valider côté IM immédiatement.
• Corrélation : request id, canal, codes fournisseur vs facturation tokens.
• Upgrade/rollback : lire migrations ; garder extraits de logs.
• Audit : chemins JSONL + rotation.
• Docker : écarts doctor → volumes/uid avant secrets canal.
• Dérive d'horloge : casse TLS/OAuth—sync temps hôte et conteneur.
• Rafales de retry : masquent la première ligne utile ; redémarrage contrôlé après incident.
• Concurrence org : plusieurs agents derrière une IP peuvent déclencher des 429 partagés.

6. Mac cloud

Passer du portable au 24/7 change supervision, persistance des logs et exposition. Sans tunnel, les accès navigateur cassent au reboot ; 18789 public attire les scans. SSH ou zero-trust réduisent la surface mais exigent rotation de clés. Windows ou petit VPS Linux peuvent suffire en test, pas pour des démons longue durée ni la parité outillage Apple. Pour macOS natif, launchd et la même échelle de triage, un nœud Mac cloud VPSMAC dédié est souvent plus prévisible. Guide express : article « cinq minutes » sur le site.

Docker sur Linux héberge OpenClaw mais ajoute uid/volumes et double vérité de configuration ; un nœud Mac réduit les couches de traduction.

Gardez tableaux fournisseurs et consoles IM comme chaîne de preuve : captures d'écran de rate limits + request ids JSONL pour une seule timeline finance/sécurité/ingénierie.

Planifiez un « chaos light » semestriel : couper un canal volontairement, vérifier alertes et runbook. Sans exercice, on surestime le MTTD.

Alignez versions mineures entre staging et prod pour éviter doctor vert côté staging uniquement grâce à une variable d'environnement absente en production.

Créez un glossaire interne : qui renouvelle pairing, où sont les IDs de canal, qui autorise la rotation des tokens—moins de friction Slack, plus de minutes pour l'analyse.

Formez d'abord à lire les logs, pas à réécrire les prompts : la plupart des pannes restent config ou canal.

Ajoutez un test e2e qui simule un pairing expiré pour valider les alarmes réalistes.

Enfin, notez les drapeaux CLI réellement supportés par votre build—les aides changent plus vite que les blogs.

Ce guide doit servir de manuel d'exploitation : alignez-le sur vos sorties réelles pour retrouver vite des messages stables, sur Mac mini local ou nœud M4 loué.

En bonus, planifiez des revues hebdomadaires courtes de quinze minutes en vous appuyant sur ces sections pour éviter les mauvaises surprises.

Les équipes réseau apprécieront que vous fournissiez cinq lignes de journal horodatées avec l'ASN sortant lorsque des erreurs TLS intermittentes apparaissent : c'est plus simple qu'un ticket « tout est lent » sans preuve.

Pour l'observabilité minimaliste, une feuille partagée avec date, version de passerelle, latence moyenne du premier jeton et nombre de WARN par heure suffit souvent à repérer une dérive deux semaines avant la facture.

Si vous multipliez les workspaces Slack ou Discord, dupliquez aussi la checklist minimale : bot invité, commande slash enregistrée, URL d'événements joignable depuis le même egress que la passerelle.

Les healthchecks verts ne garantissent pas que le chemin RPC utilisé par vos outils soit sain : ajoutez un appel synthétique qui reproduit le chemin productif, pas seulement un ping HTTP générique.

En cas d'incident récurrent le lundi matin, vérifiez d'abord si un bind ou une URL distante n'a pas glissé pendant le week-end lors d'un déploiement partiel.

Documentez enfin quels canaux sont critiques pour le business et lesquels sont expérimentaux : en période de crise, cette distinction évite de tout traiter avec la même urgence et dilue vos équipes.

Les journaux de rotation agressive peuvent masquer un pic d'erreurs : conservez au moins vingt-quatre heures de WARN sur disque ou dans un agrégateur avant de purger.

Si vous utilisez plusieurs profils de passerelle (prod, staging, sandbox), alignez les numéros de port et les noms DNS pour éviter qu'un script de déploiement ne pointe vers l'environnement de test par erreur.

Les équipes QA peuvent simuler des coupures réseau courtes avec des pare-feu de laboratoire : c'est plus instructif qu'un simple redémarrage de service.

Quand le doctor signale un plugin obsolète, planifiez la mise à jour pendant une fenêtre où le trafic d'événements est faible et gardez un rollback prêt.

Enfin, reliez chaque incident à une action corrective dans votre backlog : sans ce lien, les post-mortems deviennent des rituels sans effet sur la fiabilité réelle.