Quand un Gateway OpenClaw tombe, la cause est rarement « magique ». Dans la vraie vie, on retrouve surtout des conflits de ports, une configuration incomplète, ou une chaîne réseau/TLS mal alignée. Ce guide propose une méthode reproductible pour résoudre les 90 % de cas les plus fréquents.
Avant la mise en production, séparez clairement déploiement, charge OpenHuman et rôle Runner : ../openclaw-mac-distant-us-est-ouest-m4/openclaw-mac-distant-us-est-ouest-m4.html, ../openhuman-memory-tree-mac-cloud-openclaw/openhuman-memory-tree-mac-cloud-openclaw.html, ../github-actions-ios-ci-lent-mac-self-hosted-runner/github-actions-ios-ci-lent-mac-self-hosted-runner.html. Cette séparation réduit fortement les collisions de ressources.
1. Classer le symptôme avant de corriger
Sans typologie claire, le troubleshooting devient aléatoire. Utilisez ce tableau comme étape 1 de votre runbook d’astreinte.
| Symptôme | Cause probable | Premier geste |
|---|---|---|
| Le service démarre puis s’arrête | Port occupé, erreur de config | Lancer doctor puis vérifier les sockets |
| Accessible en local, pas depuis l’extérieur | Firewall/Security Group non aligné | Comparer bind réel et ports ouverts |
| 502 / timeout intermittents | Lenteur upstream, probes trop strictes | Corréler logs de santé et upstream |
| Échec de handshake TLS | Chaîne cert incomplète, SNI incohérent | Tester avec openssl |
2. Triage en 5 minutes avec doctor
Commencez par les vérifications officielles : Gateway Troubleshooting et Gateway Doctor.
openclaw gateway doctor --verbose # Check: config path, bind address, upstream checks, TLS warnings
ps aux | rg "openclaw|gateway" lsof -nP -iTCP -sTCP:LISTEN | rg ":(3000|8080|8443)" netstat -an | rg "LISTEN|3000|8080|8443"
| Sortie doctor | Interprétation | Action |
|---|---|---|
| config file not found | Chemin faux ou volume absent | Corriger le chemin, redémarrer proprement |
| bind failed | Conflit de port ou droits insuffisants | Libérer le port ou modifier la config |
| upstream unhealthy | Backend non prêt | Stabiliser l’upstream puis retester |
| tls chain invalid | Chaîne certificat invalide | Recomposer fullchain et revérifier |
3. Conflits de ports : la panne la plus banale
Sur une machine mutualisée, Gateway, Runner et outils annexes se battent souvent pour les mêmes ports par défaut.
PORT=8080 lsof -nP -iTCP:$PORT -sTCP:LISTEN sudo kill -15 <PID> sleep 2 lsof -nP -iTCP:$PORT -sTCP:LISTEN || echo "port released"
| Composant | Port conseillé | Remarque |
|---|---|---|
| OpenClaw Gateway | 8080 ou 8443 | Port stable en production |
| Interface d’admin locale | 3000 | Bind localhost uniquement |
| Callback Runner | 9090+ | Éviter chevauchement Gateway |
| Services de dev | 5173 / 3001 | Séparer des ports prod |
Pour les équipes APAC, gardez un profil région dédié (Hong Kong) au lieu de cloner les règles US : ../japan-vs-hong-kong-mac-distant-ci/japan-vs-hong-kong-mac-distant-ci.html.
4. Lire doctor en profondeur
Un warning n’est pas toujours anodin. Certains signaux annoncent des incidents sous charge quelques heures plus tard.
| Check | Criticité | Traitement recommandé |
|---|---|---|
| Clock skew > 3s | Élevée | Corriger NTP, sinon échecs token intermittents |
| DNS fallback actif | Élevée | Fixer les resolvers, réduire latence DNS |
| Retry budget low | Moyenne+ | Revoir timeout/retry côté upstream |
| Deprecated key | Moyenne | Planifier migration au prochain lot de changements |
mkdir -p ./diag
openclaw gateway doctor --format json > ./diag/doctor-$(date +%F-%H%M).json
jq '.checks[] | {name,status,message}' ./diag/doctor-*.json
5. Corrélation logs + health checks
Un log isolé ne raconte pas l’incident. Ce qui marche : une fenêtre de 15 minutes avec corrélation access/error/upstream.
| Indicateur | Seuil d’alerte | Action prioritaire |
|---|---|---|
| Latence p95 upstream | > 1.5s | Vérifier capacité backend et pool de connexions |
| Taux 5xx | > 1% | Segmenter par code (502/503/504) |
| Flapping healthcheck | > 3 / 10 min | Assouplir timeout/fréquence des probes |
| TLS handshake errors | Hausse continue | Contrôler SNI, chaîne cert et expiration |
6. Réseau et TLS de bout en bout
Le classique « interne OK, externe KO » vient souvent d’une couche supplémentaire (WAF, LB, CDN). Validez chaque saut séparément.
curl -Iv https://gateway.example.com/health openssl s_client -connect gateway.example.com:443 -servername gateway.example.com dig +short gateway.example.com traceroute gateway.example.com
Référence réseau officielle : Gateway Networking.
7. Choisir la bonne topologie de déploiement
Une part importante des incidents n’est pas un bug logiciel, mais un mauvais choix d’architecture pour le niveau de charge réel.
| Topologie | Contexte adapté | Risque principal |
|---|---|---|
| Monohôte | PoC, faible trafic | Conflits de ressources rapides |
| Gateway séparé du Runner | CI fréquente, trafic moyen | Supervision et routage plus complexes |
| Gateway dual-région | Utilisateurs multi-zones | Sync configuration/tokens plus délicate |
| Gateway séparé d’OpenHuman | Charges agent + mémoire parallèles | Coût supérieur, stabilité nettement meilleure |
Pour arbitrer capacité/coût, utilisez : ../../../tarifs-mac-mini.html.
8. Conclusion : standardiser les 90 % de pannes évitables
La fiabilité d’un Gateway OpenClaw vient d’une méthode, pas d’actions improvisées : triage initial, hygiène des ports, lecture fine de doctor, corrélation des logs et validation réseau/TLS. Cette discipline permet d’isoler la majorité des incidents dès le premier passage.
Maintenez votre runbook versionné et alignez chaque évolution avec la doc officielle : Gateway Configuration.
Q1 : doctor est vert, pourquoi j’ai encore des timeouts ?
doctor valide surtout la base ; la saturation upstream reste possible en charge.
Q2 : Gateway et Runner sur la même machine, acceptable ?
Oui, avec ports dédiés, limites CPU/RAM et fenêtres de charge contrôlées.
Q3 : Changer de port améliore automatiquement la sécurité ?
Non, la sécurité dépend surtout de TLS, ACL, secrets et moindre privilège.
Q4 : Pourquoi redémarrer aide puis le problème revient ?
Le redémarrage masque la cause racine (DNS, conflit de process, etc.) sans la corriger.
Q5 : Une seule config pour toutes les régions ?
Base commune oui, mais overrides régionaux recommandés (DNS, firewall, upstream).
Q6 : Je commence où pour un incident TLS ?
Expiration certificat, fullchain, puis correspondance SNI/hostname.
Q7 : Quand passer en blue/green ?
Dès que vous avez besoin de mises à jour sans interruption visible.
Q8 : Durée de rétention des données de diagnostic ?
14 à 30 jours minimum pour comparer avant/après et détecter les cycles.
Planifiez la stabilité avec le budget : parcours de déploiement ../openclaw-mac-distant-us-est-ouest-m4/openclaw-mac-distant-us-est-ouest-m4.html, séparation OpenHuman/Runner via ../openhuman-memory-tree-mac-cloud-openclaw/openhuman-memory-tree-mac-cloud-openclaw.html et ../github-actions-ios-ci-lent-mac-self-hosted-runner/github-actions-ios-ci-lent-mac-self-hosted-runner.html, options régionales ../japan-vs-hong-kong-mac-distant-ci/japan-vs-hong-kong-mac-distant-ci.html, et estimation globale depuis ../../../tarifs-mac-mini.html.