Surveillance de la santé de la passerelle OpenClaw en 2026 sur Mac mini cloud loué

La passerelle OpenClaw sur macOS passe inaperçue tant qu’elle tourne : un LaunchAgent maintient un processus sur un port, les agents parlent en loopback, les journaux restent calmes. Après un reboot hyperviseur, une rotation TLS ou une mise à jour CLI partielle, le démon se bloque souvent en silence jusqu’à ce que le trafic client s’arrête. Ce guide décrit une surveillance de santé adaptée aux Mac mini cloud loués : sondes synthétiques, budgets de latence, corrélation avec openclaw doctor et runbooks alignés sur le redémarrage. Commencez par OpenClaw doctor : diagnostic passerelle pour que les sondes vérifient les mêmes invariants que la triage humaine, et gardez redémarrage passerelle et recovery LaunchAgent ouvert : les alertes doivent s’y terminer, pas dans l’historique shell improvisé.

Signaux avant défaillance

Une passerelle saine répond de façon stable aux handshakes HTTP ou WebSocket, émet des logs structurés sans pics d’erreurs et garde un CPU régulier. Une passerelle malade montre souvent une latence p95 qui grimpe avant la panne totale, des erreurs TLS répétées après changement de certificats, ou des sorties brutales quand macOS refuse une permission TCC auparavant mise en cache.

Traitez openclaw doctor comme un contrat : doctor vert et sondes rouges suggèrent un chemin réseau ou un port forwarding hors binaire. Sondes vertes avec avertissements de décalage de version signalent une future incompatibilité. Conservez les deux signaux sur la même ligne de temps d’incident.

La télémétrie des petites équipes sur mini partagés montre encore 5–8% des alertes hebdomadaires liées à des fenêtres de maintenance bénignes—snapshots, réseau hébergeur—donc calibrez les seuils pour éviter la fatigue de pager tout en détectant les vraies régressions en quelques minutes.

Surveillez les descripteurs de fichiers et la rotation des logs : sans plafond, un journal qui gonfle peut faire chuter les health checks avant toute panne «métier». En multi-locataire, isolez utilisateurs, ports et répertoires de logs pour éviter qu’un voisin épuise les FD communs.

Archivez les sorties doctor versionnées : le diff entre deux releases révèle souvent de nouveaux contrôles que les sondes doivent refléter rapidement.

Concevoir des sondes

Les sondes efficaces imitent la plus petite interaction réussie : authentification si besoin, route health ou socket, en-tête de version, code de sortie non nul sur timeout. Trois points de vue : localhost sur le mini (liaison et démon), bastion ou VPN (routage), externe seulement si vous exposez volontairement la passerelle—ce que la plupart des équipes évitent.

Lancez les sondes via launchd avec limitation : une passerelle bloquée ne doit pas lancer des centaines de curls concurrents. Jitter et backoff exponentiel limitent l’auto-déni de service pendant les incidents.

Sécurité : pas de jetons longue durée dans des commandes journalisées. Préférez des identifiants à courte durée, des fichiers d’environnement stricts ou le trousseau macOS via un utilisateur sonde miroir de la prod.

Ajoutez en staging des tests négatifs (tokens invalides) pour distinguer 401/403 attendus de 5xx inattendus.

Esquisse de script

Fragment shell illustratif ; adaptez ports et en-têtes.

#!/bin/bash
set -euo pipefail
URL="http://127.0.0.1:18789/health"
START=$(python3 - <<'PY'
import time; print(int(time.time()*1000))
PY
)
code=$(curl -sS -o /tmp/ocgw_probe.json -w "%{http_code}" "$URL" || true)
END=$(python3 - <<'PY'
import time; print(int(time.time()*1000))
PY
)
lat=$((END-START))
echo "openclaw_probe http=$code latency_ms=$lat"
[[ "$code" == "200" ]] || exit 1

Redirigez la ligne structurée vers votre collecteur de logs ou exporter métrique. Gardez la durée sous une seconde en succès.

Tableau SLO

Utilisez ce tableau en revue de service ; ajustez selon vos engagements.

Métrique	Cible	Notes
Disponibilité mensuelle	99,5 %+	Excluez les fenêtres planifiées communiquées.
Latence p95 sonde	< 300 ms localhost	Les pics précèdent souvent l’épuisement de sockets.
Sondes en échec	< 5–8 % / semaine	Cherchez des motifs, pas des points isolés.
Dérive doctor	0 avertissement	Le décalage de version doit pager avant les clients.

Couplez SLO quantitatifs et contrôles qualitatifs : une fois par sprint, exécutez doctor manuellement et vérifiez les horodatages dans ~/Library/Logs.

Exploitation hebdomadaire sur Mac cloud

Les mini loués redémarrent lors de migrations ou patchs noyau. Après chaque reboot, vérifiez l’ordre des LaunchAgents, l’accès aux secrets, puis relancez doctor.

Prévoyez 30–45 minutes par semaine : tableaux de bord, rotation d’identifiants courts, snapshot avant upgrades risqués. Sans matériel de rechange, louez un Mac mini Apple Silicon avec SSH/VNC pour environ 16,9 $/jour pendant les semaines chargées—moins cher que des laptops express.

Documentez les routes d’alerte : canal Slack, service PagerDuty, script de reprovisionnement. Multi-tenant : utilisateurs sonde isolés par client.

Boucle fermée : alerte → doctor → redémarrage launchctl → réinstallation binaire seulement si la dérive plist/chemin est prouvée.

Corrélation > rouge/vert : latence qui monte avec HTTP 200 invite à chercher des blocages de boucle événementielle, JSON massifs, I/O disque synchrone ou antivirus sur des logs frais. Joignez des extraits sample/spindump aux tickets.

Traitez les scripts de monitoring comme du code produit : revue, versions, interpréteurs épinglés, checksums surveillés.

Tuile exécutive : uptime, latence médiane, incidents ouverts. Les trois en même temps : problème d’infrastructure, pas de prompt.

Formez l’astreinte avec les deux articles liés : doctor pour la preuve, restart pour le levier maîtrisé.

Si la passerelle est derrière un reverse proxy local, faites exécuter des sondes à la fois sur le port loopback du démon et sur le chemin public du proxy. Vous distinguerez plus vite un problème de certificat entre proxy et backend, ce qu’une simple sonde TCP sur 127.0.0.1 peut masquer.

Les fournisseurs de mini cloud appliquent parfois des mises à jour silencieuses des pare-feu. Après chaque annonce de maintenance, vérifiez que les règles locales autorisent toujours le port health—doctor peut rester vert s’il emprunte un autre chemin que votre curl planifié.

Documentez pour les audits un bundle par incident : sorties doctor, plist LaunchAgent, version CLI. Les équipes conformité veulent surtout prouver que la reprod staging a suivi la même séquence que la prod.

Planifiez des game days légers (charge artificielle, révocation de token simulée) pour valider dashboards et runbooks avant qu’un client réel ne déclenche le premier stress test.

Gardez la majorité des sondes sur localhost et n’ajoutez des pings externes que si vous exposez réellement la passerelle : les sondes SaaS peuvent coûter plus cher que la location du mini si elles tournent en permanence.

Étiquetez chaque tuile de tableau de bord avec l’instance OPENCLAW_HOME mesurée : un voyant vert sans contexte masque les mélanges entre staging et production sur un même hôte loué.

Complétez les sondes automatisées par un contrôle manuel occasionnel via curl avec des en-têtes réalistes ; certaines anomalies TLS ou HTTP/2 n’apparaissent qu’avec de vrais user-agents.

FAQ

Les health checks doivent-ils tourner en root ou en utilisateur passerelle ?

Alignez-vous sur l’utilisateur LaunchAgent. Root peut masquer des permissions ; un mauvais UID rate trousseau ou sockets.

À quelle fréquence frapper la passerelle ?

Au moins une minute pour la disponibilité ; canaries plus fréquents seulement avec backoff. Calquez sur le budget d’erreur SLO.

Le moyen le plus rapide de récupérer une passerelle bloquée ?

Doctor d’abord, redémarrage LaunchAgent ensuite, réinstallation seulement si dérive—documentez l’ordre.

Le Mac mini Apple Silicon reste le socle pratique pour des passerelles OpenClaw avec permissions durables et launchd prévisible. MacHTML loue des mini bare-metal cloud SSH/VNC pour câbler des sondes, répéter des incidents et démanteler des environnements sans nouveau CapEx.