Les mises à niveau de la passerelle OpenClaw sur Mac mini M4 échouent en silence quand les équipes sautent le drain, relancent le LaunchAgent pendant des webhooks actifs ou traitent openclaw config validate comme un simple spectacle. Cette matrice du 2026-04-29 enchaîne drain d’entrée → instantané d’état → validate → redémarrage → doctor → fumée avec deux tableaux qui associent symptômes et leviers de rollback—pour que les trains de correctifs d’avril cessent de rouvrir le même incident de pont.
Associez le rituel à épinglage de version CLI et mise à niveau / rollback non interactifs, redémarrage LaunchAgent et runbook shell externe, fumée post-installation et preuves de santé, et runbook opérations pour journaux, mises à niveau et rollback.
Pourquoi « brew upgrade && kick launchd » n’est pas une stratégie
Les passerelles colocalisent des sessions TLS longues, des bac à sable d’outils et l’état des permissions macOS. Un simple remplacement de binaire sans drain laisse des corps de webhooks semi-signés en mémoire pendant que le nouveau code attend des valeurs par défaut de schéma différentes. Sur Apple Silicon, la pression mémoire unifiée due à d’anciens bac à sable navigateur fait paraître le nouveau processus « lent » alors que la faute réelle est l’ordre de mise à niveau.
- Course à l’entrée : webhooks acceptés par l’ancien code après chargement du nouveau plist corrompent les caches d’idempotence.
- Dérive d’identité :
openclaw --versionaffiche les nouveaux bits tandis queopenclaw gateway statusmontre encore d’anciens écouteurs après un redémarrage partiel. - Décalage de config silencieux : validate ignoré ; au démarrage, des écritures rognent des listes d’autorisation personnalisées que vous pensiez persistantes.
Règle opérateur : si le ticket de changement n’a pas d’horodatages pour le début du drain, la réussite de validate et le rejouage fumée, la mise à niveau n’est pas close—quel que soit le vert des bots de chat.
Matrice A — phase vs signal de réussite vs artefact
| Phase | Signal de réussite | Artefact de preuve |
|---|---|---|
| Drain | Profondeur de file zéro et aucune entrée nouvelle pendant N minutes | Extrait de journal horodaté ou capture de métrique proxy |
| Validate | openclaw config validate se termine avec code zéro |
stdout masqué dans le stockage objet |
| Fumée | Rejeu signé + doctor propre + gateway status attendu | Identifiants de rejeu liés au ticket |
Matrice B — symptôme vs bug d’ordre probable vs rollback
| Symptôme | Bug d’ordre | Levier de rollback |
|---|---|---|
| Tempête de 401 juste après redémarrage | Redémarrage avant validate ayant réécrit les chemins de config | Restaurer plist + instantané d’état ; relancer validate avant les écouteurs. |
| Exécutions d’outils en double | Trafic réactivé avant que les caches d’idempotence ne chauffent | Drainer à nouveau ; rejouer les clés de dédup depuis l’export pré-mise à niveau. |
| Invites GUI sur hôte sans tête | Checklist TCC post-mise à niveau ignorée | Suivre le bris de glace VNC documenté ; geler les mises à niveau suivantes. |
Garde-fous chiffrés pour les fenêtres de changement
- Patience du drain : attendre au moins 5 minutes sans aucune entrée nouvelle après file vide avant redémarrage.
- Budget validate : si validate échoue plus de deux fois, arrêter et revenir aux binaires—pas de troisième édition silencieuse.
- Couverture fumée : rejouer au moins trois formes de webhook distinctes avant de déclarer la prod saine.
Huit étapes HowTo (reflétées dans le JSON-LD)
- Geler le périmètre avec semver, propriétaires et responsable rollback dans le ticket.
- Drainer l’entrée via drapeaux proxy ou promotion d’un hôte secondaire—documenter le basculement.
- Instantané d’état des répertoires et de l’environnement plist avant tout mouvement de binaires.
- Appliquer les binaires par votre chemin paquet approuvé ; ne jamais mélanger copies manuelles et artefacts CI sans preuve de somme de contrôle.
- Lancer
openclaw config validateet joindre stdout avant tout redémarrage d’écouteur. - Redémarrer LaunchAgent ; capturer
openclaw gateway statusprouvant les adresses d’écoute attendues. - Lancer
openclaw doctorpuis la fumée webhooks staging dans cet ordre. - Réactiver le trafic progressivement avec alarmes de taux d’erreur et une fenêtre de veille de quinze minutes.
FAQ
Faut-il un Mac de secours pour chaque passerelle ?
Pour l’entrée chat de production, oui—soit un hôte chaud de secours, soit une file en périphérie capable de mettre en buffer les événements signés pendant que le primaire draine.
Où placer SSH par rapport à VNC ?
Utilisez l’automatisation SSH en premier pour validate et redémarrage ; utilisez VNC seulement lorsque macOS bloque la récupération des permissions sans tête après mise à niveau.
Comment ajouter de la capacité sans partager les secrets prod ?
Consultez les tarifs pour un autre hôte dédié à Hong Kong, au Japon, en Corée, à Singapour ou aux États-Unis et gardez les mises à niveau staging une génération en avance.
Des mises à niveau OpenClaw reproductibles sur macOS natif sont un problème de chorégraphie : le drain supprime les courses d’entrée, openclaw config validate attrape la dérive de schéma avant que les écouteurs ne se réveillent, et des rejouages fumée structurés prouvent que l’idempotence a survécu au saut. Tourner sur une capacité Mac mini M4 louée à travers Hong Kong, le Japon, la Corée, Singapour et les États-Unis permet de séparer physiquement staging et production tout en ne partageant que les runbooks—pas les secrets. Quand les matrices montrent des bugs d’ordre répétés, resserrez les exigences de preuve avant de courir après une autre semver ; vos utilisateurs préfèrent des webhooks stables à des notes de version longues.