Redémarrage de la passerelle OpenClaw et récupération LaunchAgent en 2026 sur Mac cloud

La passerelle OpenClaw sous macOS se comporte en général comme une plomberie invisible — jusqu’à ce qu’un Mac mini cloud loué redémarre, qu’un agent d’automatisation déclenche un redémarrage ou qu’une mise à jour CLI laisse un plist LaunchAgent obsolète. Ce guide couvre les échecs silencieux, les redémarrages invoqués par les agents, les commandes launchctl utiles, le moment d’exécuter openclaw gateway install --force, un motif nohup pour les courses au login et le décalage de version entre la CLI et le binaire passerelle longue durée. Lisez-le avec l’onboarding passerelle et TCC, les diagnostics doctor et les schémas de planification LaunchAgent pour que les étapes de récupération restent alignées sur votre installation du démon.

Symptômes : échec silencieux vs redémarrage agent

Les échecs silencieux ressemblent à « tout marchait hier » sans stderr : le port de la passerelle n’accepte plus les connexions, les health checks passent au rouge et Console.app n’enregistre qu’une fin brutale de processus. Déclencheurs fréquents sur Mac cloud : cycles veille/réveil sur hôtes partagés, timeouts d’inactivité agressifs qui tuent les processus orphelins, snapshots disque qui restaurent ~/.openclaw alors que le LaunchAgent pointe encore vers un binaire supprimé.

Les redémarrages invoqués par les agents sont plus visibles si bien journalisés — votre automatisation appelle openclaw gateway restart ou encapsule launchctl kickstart — mais échouent tout de même si le label du job a changé entre versions. Symptômes : boucles de redémarrage toutes les quelques minutes, écouteurs dupliqués sur des ports voisins, ou invites TCC qui n’apparaissent jamais car la session de l’agent n’a pas le contexte accessibilité. Distinguez les deux en corrélant les horodatages : sorties silencieuses alignées sur l’alimentation ; boucles alignées sur cron ou l’agenda des agents décrit dans le guide cron LaunchAgent.

Inspection launchctl et kickstart

Commencez par la visibilité, pas par forcer. Exécutez launchctl print gui/$UID/ai.openclaw.gateway (remplacez le label si vous l’avez personnalisé) pour lire les arguments du programme, le répertoire de travail et le dernier code de sortie. Si le job est chargé mais inactif, launchctl kickstart -k gui/$UID/ai.openclaw.gateway demande à launchd de tuer et relancer proprement — préférez ceci à un pkill manuel quand c’est possible, car launchd maintient le contrat.

# Inspecter le LaunchAgent utilisateur
launchctl print gui/$UID/ai.openclaw.gateway

# Forcer un redémarrage supervisé
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

Lors de la désinstallation ou du remplacement des plists, launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist supprime l’ancienne inscription avant de copier le nouveau fichier, ce qui évite les jobs dupliqués. Sur Mac cloud ouverts en parallèle, coordonnez-vous pour ne pas faire un bootout pendant la démo d’un collègue. Capturez toujours log show --predicate 'process == "openclaw"' --last 30m pour les rapports de bugs en amont ; des repros minimales façon WebKit aident davantage les mainteneurs que des captures seules.

openclaw gateway install --force

Quand les plists dérivent ou que des mises à jour partielles laissent des chemins incohérents, exécutez openclaw gateway install --force depuis la même chaîne d’outils qu’en production. Le drapeau régénère les métadonnées du service et réimpose l’emplacement du binaire passerelle, ce qui corrige la majorité des cas « marche en SSH, échoue en session GUI » sur minis loués. Associez la check-list d’onboarding sensible au TCC pour que les invites confidentialité réapparaissent dans le bon contexte utilisateur.

N’enchaînez pas --force aveuglément entre versions majeures : lisez les notes de version, exportez votre configuration ~/.openclaw et snapshottez le disque si le fournisseur le permet. Les listes blanches d’IP statiques et les extrémités de tunnel dans les fichiers d’environnement se perdent facilement quand l’automatisation relance les scripts d’installation. Documentez la chaîne exacte de version CLI en pied de runbook.

Motif nohup pour courses au login

Les images Mac cloud démarrent parfois les LaunchAgents avant le réseau ou le déverrouillage du trousseau. Un motif pragmatique enveloppe le démarrage de la passerelle d’un court sleep dans un shell invoqué par nohup, laissant le temps aux démons Wi-Fi et VPN de se stabiliser :

nohup sh -c 'sleep 15; openclaw gateway run' >/tmp/openclaw-gateway.log 2>&1 &

Ajustez le délai : les VPN d’entreprise peuvent exiger 30–45 secondes ; journalisez toujours stdout/stderr dans un fichier rotatif. Ce n’est pas un substitut à un ThrottleInterval LaunchAgent correct — c’est un pont tant que vous ne pouvez pas modifier le plist. Déplacez le délai dans ProgramArguments du plist une fois validé pour que launchd supervise l’arbre de processus.

Décalage versions CLI / passerelle

Le décalage de version mord quand une installation npm globale met à jour la CLI alors que le LaunchAgent pointe encore vers un ancien binaire passerelle, ou quand Homebrew épingle un chemin différent de celui attendu par votre automatisation. Exécutez openclaw doctor avec les contrôles passerelle détaillés dans les diagnostics passerelle ; alignez les versions en réinstallant depuis un seul gestionnaire de paquets. En CI, épinglez un SHA ou semver et propagez le même artefact vers les Mac cloud via rsync ou une archive mise en cache.

Signe	Cause probable	Atténuation
Erreurs de drapeau inconnu dans les logs	CLI plus récente que la passerelle	Réinstaller la passerelle avec la CLI correspondante
Chemin de socket obsolète	Config migrée, service non mis à jour	install --force + doctor
Invites d’autorisation aléatoires	Chemin du binaire modifié	Réinitialiser les entrées TCC avec prudence selon le doc d’onboarding

Notes opérationnelles Mac cloud

Les minis loués diffèrent des portables : l’accès physique au mode récupération peut manquer, donc chaque action de récupération doit être scriptée et idempotente. Gardez un second compte admin pour « casser la glace » — les LaunchAgents sont par utilisateur et les invites GUI n’apparaissent que pour l’utilisateur console connecté. Snapshot avant --force sur tenants partagés ; la facturation est horaire, mais le stockage de snapshots coûte moins qu’une journée perdue à reconstruire les clés.

Les politiques de sortie réseau sur hôtes cloud bloquent parfois les health checks WebSocket ; vérifiez les règles sortantes avant d’accuser la passerelle. Croisez les logs passerelle avec des sondes synthétiques sur le même VLAN que vos agents. Quand plusieurs ingénieurs partagent un mini, isolez les fichiers log par ingénieur pour éviter les conflits de droits chmod.

Sécurité : la rotation des clés API ne devrait pas exiger de redémarrage complet ; si c’est le cas, votre gestionnaire de processus est trop fragile. Utilisez des jetons à courte durée là où OpenClaw le permet et ne redémarrez que le job passerelle. Documentez quels secrets vivent dans le trousseau par rapport aux fichiers d’environnement — les auditeurs le demandent.

Performance : évitez de redémarrer pendant des charges agent lourdes ; planifiez les redémarrages en fenêtres de maintenance. Si le marketing planifie des démos, gèle les changements d’automatisation pendant 24 heures. Mesurez la durée de redémarrage ; visez moins de 10 secondes d’indisponibilité de l’écouteur.

Reprise après sinistre : archivez ~/.openclaw chaque nuit vers un stockage objet avec chiffrement côté client. Testez les restaurations trimestriellement sur un mini jetable. Le plist LaunchAgent doit référencer des chemins absolus résilients aux changements de nom d’utilisateur ; les fournisseurs cloud clonent parfois des images avec de nouveaux UID.

Observabilité : envoyez les logs vers un réceptacle centralisé si la politique du tenant le permet. Masquez les tokens en périphérie — voir d’autres articles MacHTML sur l’hygiène des logs. Déclenchez des alertes sur le nombre de redémarrages par heure, pas sur des pics isolés.

Collaboration : les post-mortems doivent noter la version CLI, le hash du plist et si les invites TCC sont apparues. Cette triade résout la plupart des tickets répétés.

Enfin, enseignez aux agents d’escalader : si deux redémarrages automatiques échouent, prévenez un humain. Les boucles silencieuses d’automatisation ont fait tomber des passerelles partagées quand chacun supposait qu’un autre possédait la session console.

FAQ

Pourquoi ma passerelle échoue silencieusement après reboot d’un Mac cloud ?

LaunchAgent peut se charger avant le réseau ou les invites TCC ; le processus quitte sans journal utile. Vérifiez la Console, les chemins plist, puis réinstallez avec --force une fois la session stabilisée.

Les agents doivent-ils appeler directement openclaw gateway restart ?

Préférez launchctl kickstart -k après vérification du label ; un restart aveugle boucle si le binaire a changé lors d’une mise à jour CLI.

Comment corriger un décalage entre CLI et passerelle ?

Épinglez une seule chaîne d’outils en CI, réinstallez la passerelle depuis cette CLI et lancez doctor jusqu’à alignement des versions.

Le Mac mini reste le foyer pratique pour les passerelles OpenClaw qui touchent les vrais services macOS. MacHTML loue des minis Apple Silicon avec SSH/VNC pour que les équipes répètent la récupération LaunchAgent sans acheter de matériel — montez l’instance, validez, démontez une fois au vert.