Playbook 2026 : récupération LaunchAgent de la passerelle OpenClaw sur macOS après mises à jour

La passerelle OpenClaw sur macOS doit survivre aux reboots via launchd, mais les mises à jour rapides du canal 2026.x laissent parfois une panne silencieuse : le binaire monte de version, le LaunchAgent ne recharge jamais, et chaque pont de messagerie cesse de répondre. Ce playbook relie symptômes et correctifs, compare les tactiques de récupération dans une matrice, et détaille neuf étapes reproductibles en SSH sur un Mac mini M4 NodeMac sans deviner les chemins.

Complétez avec le runbook opérations OpenClaw pour les journaux et la politique de mise à jour, et avec l’installation macOS initiale si vous repartez de zéro.

Signes d’un décalage LaunchAgent—pas simplement « l’IA est en panne »

• Processus absent sans dialogue de crash : ps ne montre aucun worker gateway alors que le CPU est au repos—agent non chargé typique.
• HTTP 401 de chaque fournisseur après reboot : les clés existent dans un dotenv, mais le démon a hérité d’un environnement vide car la plist n’embarquait pas les variables requises.
• Démarrage CLI manuel OK, autostart KO : les opérateurs lancent la passerelle dans un terminal avec succès ; après déconnexion le service s’arrête car le LaunchAgent pointe vers un répertoire de travail obsolète ou un nom d’entrée d’une ancienne structure.

Matrice des options de récupération

Variables d’environnement : où elles doivent vivre pour les daemons

Les shells interactifs lisent .zshrc ; les LaunchAgents non. Si vos clés fournisseur ne sont que dans un fichier ignoré par la plist, la passerelle démarre non authentifiée et journalise des 401 déroutants.

1. Lister les clés requises (jetons API, URL proxy optionnelles) dans un extrait runbook que les ops collent après rotation.
2. Les refléter dans EnvironmentVariables de la plist ou utiliser un wrapper supporté qui charge explicitement dotenv au démarrage—une stratégie par machine, pas les deux à moitié.
3. Test reboot : planifier trimestriellement ; attraper les variables manquantes dans les 24 heures suivant une rotation d’identifiants.
4. Restreindre les permissions plist à l’utilisateur service ; les plists lisibles par tous fuient des secrets.
5. Documenter le domaine actif (gui/$(id -u) vs arrière-plan) pour éviter qu’un intervenant décharge le mauvais job.

Pourquoi les mises à jour cassent l’autostart alors que le binaire est bon

Les mises à jour peuvent modifier trois points fragiles à la fois : le chemin exécutable dans ProgramArguments, le répertoire de travail où se résolvent les configs relatives, et la version Node.js attendue par le bundle gateway. Un seul décalage suffit : launchd considère toujours le job « configuré » alors qu’il quitte immédiatement—cases cochées dans une UI qui n’a jamais vraiment tenu.

Traitez chaque upgrade comme une mini-migration : snapshot de plist, checksums du script d’entrée gateway, tarball précédent conservé au moins sept jours. Sur Mac cloud vous payez l’uptime que le bot réponde ou non ; intégrer cette discipline au calendrier des changements se rembourse dès le premier vendredi soir qui bloque l’automation client.

• Limiter les upgrades automatiques sur les gateways prod ; laisser une canary en staging prendre la build la plus récente en premier.
• Aligner les majeures Node sur la doc éditeur—des majeures incorrectes apparaissent souvent comme erreurs obscures de résolution de modules sur la première ligne de log.
• Centraliser la rotation des secrets pour que les edits plist se fassent une fois par flotte plutôt qu’à chaque incident.

Runbook en neuf étapes (SSH sur Mac mini M4)

1. Confirmer la connectivité avec le même utilisateur SSH que le LaunchAgent ; incohérences de permissions expliquent souvent « manuel OK, boot KO ».
2. Capturer la sortie de launchctl print gui/$(id -u) avec les notes d’incident pour diff.
3. Localiser la plist sous ~/Library/LaunchAgents/ ; vérifier que les chemins ProgramArguments existent.
4. Exécuter kickstart avec -k pour forcer le respawn ; attendre 30 secondes et contrôler les ports en écoute.
5. Si toujours down, unload/load propre de la plist ; vérifier les copies obsolètes sous /Library/LaunchDaemons si vous aviez expérimenté.
6. Réconcilier les variables d’environnement ; injecter les clés manquantes, recharger.
7. Tailer les logs gateway deux minutes pour boucles de crash—reculer vers rollback si la même stack trace se répète plus de trois fois.
8. Smoke test d’intégration (message test sur le canal le moins risqué) avant d’annoncer le vert.
9. Mettre à jour la doc interne avec les commandes exactes ; les flottes cloud HK, JP, KR, SG et US partagent une page de recovery canonique.

Journaux, health checks et escalade

Après redémarrage, ne vous contentez pas de « processus actif » : vérifiez des lignes de log utiles—poignées de main fournisseur réussies, WebSocket stables, absence de stack traces répétées. Ajoutez un health check HTTP simple (si la passerelle le supporte) rattaché au même monitoring que vos autres services prod pour distinguer « launchd pense que le job va bien » des ponts qui répondent réellement au trafic.

Pour les équipes distribuées, activez l’agrégation centralisée des logs (rsyslog, agent, etc.) seulement après modèle de menace et validation conformité—les clés API ne doivent jamais atterrir brutes dans un index partagé. Sur machines NodeMac, restez proches de l’hôte via SSH et éventuellement VNC ; complétez par de courts « diffs plist » hebdomadaires après chaque mise à jour éditeur pour voir la dérive avant le ticket client.

Fil d’escalade : d’abord kickstart, puis reload plist, puis réinstallation CLI, puis rollback—documentez cet ordre pour que la garde de nuit n’improvise pas. Si deux releases consécutives échouent, figez la version prod et ouvrez un ticket éditeur avec plist jointe et journaux expurgés.

Post-mortem et contrôle des changements

Après chaque incident, enregistrez hash de plist, version gateway et les commandes launchctl efficaces dans votre outil de tickets. Liez les changements à une demande formelle pour éviter les expérimentations du vendredi soir sur la production. Sur des machines NodeMac dédiées, groupez ces politiques par hôte et appliquez le même modèle d’accès SSH que dans la documentation d’aide.

Checklist avant d’accuser le fournisseur de modèle

FAQ

Pourquoi OpenClaw disparaît-il de la barre de menus après une mise à jour ?

Le processus gateway peut s’arrêter pendant que launchd ne recharge jamais la plist LaunchAgent, ou la plist pointe encore vers un ancien chemin après changement de layout du paquet. Corrigez en validant la plist, en rechargeant l’agent et en confirmant que les variables d’environnement survivent au reboot.

Est-il sûr d’exécuter kickstart sur une passerelle de production ?

Oui si vous acceptez quelques secondes d’indisponibilité ; préférez des fenêtres de maintenance pour les équipes dépendant des ponts de messagerie. Suivez toujours les logs pendant la première minute après redémarrage.

Besoin de gateways toujours actifs sans surveiller des portables ? Comparez les tarifs NodeMac pour des Mac mini M4 dédiés avec SSH/VNC dans les régions de vos utilisateurs, puis appliquez ce playbook comme checklist standard après mise à jour.

Le matériel Mac mini M4 rend la récupération de daemon ennuyeuse au bon sens : la marge de performance Apple Silicon permet de faire coexister passerelle, helpers locaux et automatisation légère sans swap, tandis que la mémoire unifiée limite les crashs OOM lors de pics de logs. NodeMac fournit des machines physiques dédiées—pas des VM partagées—avec SSH et VNC à Hong Kong, Japon, Corée, Singapour et États-Unis, pour exécuter ce playbook à distance dès qu’une mise à jour arrive. La location évite le CapEx pendant que vous affinez les politiques LaunchAgent, et s’accorde avec les docs d’aide plateforme pour l’hygiène d’accès sur la flotte.