OpenClaw sur macOS : quand openclaw gateway restart réussit mais les listeners restent obsolètes

Cet article suppose que vous croisez d’abord le dépannage officiel en échelle, puis les guides installation, réinstallation forcée et launchd, split-brain, lastTouchedVersion et chemins profonds, CLI distante, dérive et sondes de santé, canal vert, absence de réponse et 429, régressions mémoire/session jsonl et rollback, Compose, jeton d’auth et appariement WebSocket.

Les équipes qui pilotent des Mac distants avec OpenClaw en 2026 confient au gateway l’orchestration des extensions, des probes de santé et des poignées de pairing. Le motif le plus irritant reste inchangé : `openclaw gateway restart` renvoie zéro, les journaux sont polis, mais les ports d’écoute, les sockets UNIX ou les en-têtes d’administration restent figés sur une build d’hier. Ce n’est presque jamais du « réseau fantôme » : c’est souvent `launchd` qui conserve un LaunchAgent utilisateur avec d’anciens `ProgramArguments`, un `WorkingDirectory` incohérent ou un environnement figé, tandis qu'il ne recycle qu'un processus enfant.

Les sessions SSH non interactives et la session console GUI n’héritent pas du même PATH ni des mêmes trousseaux. Un redémarrage lancé depuis votre shell interactif peut donc sembler réussir alors que l’agent utilisateur exécute encore un binaire absolu pointant vers une arborescence déplacée après upgrade. D’où l’impératif d’inspecter `~/Library/LaunchAgents/com.openclaw.gateway.plist` avec `plutil -p` après chaque fenêtre de mise à jour.

Avant toute opération `bootout`, la passerelle officielle de dépannage doit produire des artefacts horodatés. Elle distingue extensions, limites 429, identifiants et dérive pure `launchd`. Sauter cette échelle brûle des heures en fausses pistes et masque des incidents fournisseurs qui coïncident avec vos tentatives de recycle.

Le label `com.openclaw.gateway` est la source de vérité d’exécution au login et au bootstrap. macOS exige des verbes `launchd` conscients du domaine. Le couple `launchctl bootout` puis `bootstrap` sur le plist remet la table d’agents d’aplomb ; un simple `kick` peut laisser des arguments déjà matérialisés inchangés, d’où des listeners « stale » malgré un exit code propre.

Quand les métadonnées divergent du layout installé, `gateway install --force` devient pertinent, mais uniquement après sauvegarde des jetons, JSON de pairing et arborescences d’extensions personnalisées. L’alignement semver entre CLI, binaire gateway et métadonnées persistantes évite les symptômes split-brain qui imitent un recycle inefficace.

Les packs d’extensions font partie du contrat de version. Un core neuf avec extensions compilées contre une API ancienne produit des demi-succès qui ressemblent à des ports figés. Documentez les surfaces d’écoute admin versus LAN, surtout si Compose ou pare-feu macOS publient des interfaces différentes de ce que la CLI suppose.

Pour les stacks Docker-adjacents, synchronisez ports publiés et secrets WebSocket avec la matrice d’appariement. Un recycle local peut réussir pendant qu’un reverse-proxy conserve un amont obsolète. Ajoutez aux preuves quatre mesures : semver attendue, semver réelle, mtime du plist, exports de l’échelle officielle.

Inventoriez TCP, sockets UNIX et namespaces attendus. Si le restart ne fait pas churner les listeners, le processus lié n’est probablement pas celui que vous croyez. Comparez empreintes ou versions entre le binaire invoqué par la CLI et celui référencé par le LaunchAgent jusqu’à convergence dans le corridor semver convenu.

Les rollbacks silencieux arrivent quand un nouveau binaire est posé mais qu’un wrapper ancien subsiste. La CLI peut sembler neuve pendant que `launchd` exécute encore un shim obsolète. Il faut alors une lecture forensique, pas une boucle de restarts.

Classez les incidents selon la fenêtre de mise à jour : clusters frais suggèrent des scripts de migration incomplets pour les métadonnées LaunchAgent ; dérives sporadiques pointent vers des éditions plist manuelles ou une automatisation indisciplinée. Séparez impact utilisateur et impact opérateur : certains clients voient une authentification cassée lorsque des secrets WebSocket tournent alors que des listeners conservent d’anciennes valeurs.

Quand les extensions semblent chargées sans changement de comportement, capturez les versions de manifeste distinctes du core. Les canaux preview et les mélanges npm/vendor amplifient ce risque. Consultez le guide canaux avant d’accuser `launchd`, car des oscillations 429 imitent des daemons morts.

Après `bootstrap`, vérifiez que le job tourne dans le domaine GUI attendu, pas dans un domaine éphémère de session SSH. Les administrateurs distants confondent souvent les domaines `sudo` et utilisateur. Diffez les plists entre hôtes sains et malades lorsque la flotte diverge.

Ménage : clés `Disabled` dupliquées, intervalles de throttle orphelins, dictionnaires `KeepAlive` hérités peuvent accepter des signaux de restart tout en conservant des descripteurs liés à d’anciens hôtes d’extensions. Évitez l’édition XML au `sed` ; versionnez les gabarits plist par release et validez des sommes de contrôle.

Opérationnalisez une baseline post-récupération : extraits semver, empreinte plist, `launchctl print` pour `com.openclaw.gateway`, inventaire d’écoute, résumé doctor, probes minimales et profondes. Archivez avec identité d’hôte et canal de release. Des diffs hebdomadaires révèlent une pourriture lente, par exemple un PATH modifié par de nouveaux outils de développement.

Séparez « SSH fonctionne » de « le gateway reste stable ». Partage d’écran et MDM peuvent donner un shell sans garantir des LaunchAgents GUI fiables. Les sauvegardes avant force-install doivent être testées, pas décoratives. Intégrez des alertes issues des guides canaux, y compris les classes 429 signalant du throttling fournisseur plutôt que des listeners locaux figés.

Rédigez une chaîne d’escalade d’une page : propriétaire de l’échelle, plateforme pour `bootout`, sécurité pour rotation de jetons, release pour fenêtres de force-install. L’hygiène de tickets justifie le budget quand la finance questionne les heures Mac. Formez en binôme sur un staging réel avant les incidents de production.

Injectez trimestriellement des fautes contrôlées sur des clones non prod pour garder la mémoire musculaire sans risquer le trafic revenu. Préférez les journaux structurés aux galeries de captures informelles qui vieillissent vite.

La paire semver n’est pas un luxe : les conflits `lastTouchedVersion` et la dérive de chemins profonds produisent des bannières vertes avec comportements cassés. Centralisez les upgrades avec sommes de contrôle et un hook post-install qui valide `ProgramArguments` contre le binaire installé. Si une série de patchs régresse, examinez le rollback avant de forcer indéfiniment vers l’avant.

Le pilotage distant exige des preuves reproductibles malgré la latence d’écran partagé. L’échelle officielle fournit ces preuves si vous ne la sautez pas. `bootout`/`bootstrap` sur `~/Library/LaunchAgents/com.openclaw.gateway.plist` réaligne `launchd` ; `gateway install --force` reconstruit les artefacts d’installateur lorsque les métadonnées sont réellement perdues.

Le reset de pairing est le levier final quand les listeners sont neufs mais que les clients voient encore d’anciens secrets. Coordonnez les interruptions clients. Pour Compose, synchronisez secrets WebSocket et ports publiés avec la matrice d’appariement afin d’éviter de faux succès.

Questions fréquentes : exit zéro n’implique pas que `launchd` a rechargé ; `bootout` est bref, annoncez une micro-maintenance ; le force-install ne remplace pas une panne fournisseur ; les healthchecks superficiels restent verts pendant que des routes authentifiées restent anciennes ; ne supprimez pas le plist sans plan de remplacement.

Conclusion : traitez l’incident comme rupture de contrat entre l’état enregistré par `launchd` et le layout réellement installé. Marchez l’échelle officielle, réparez `com.openclaw.gateway` de façon déterministe, n’escaladez au force-install qu’avec discipline de sauvegarde, ancrez la paire semver dans la supervision. Pour une capacité Mac distante planifiable avec des défauts robustes, croisez ces runbooks avec les offres SFTPMAC.

Gouvernance supplémentaire : imposez un ticket « pas de bootout sans export d’échelle ». Des hooks peuvent vérifier la présence de trois artefacts : sortie doctor, probe canal, hash plist. Cela évite les nuits de régression improvisées.

Pour les flottes mixtes Linux/macOS, synchronisez les politiques semver entre dépôts. Un Linux à CLI neuve et un LaunchAgent macOS ancien génère des tickets où chaque côté est « vert » car il répond à des questions différentes. Centralisez la matrice de versions et propagez-la via labels CI.

Exercez-vous à restaurer des exports de jetons dans un compte isolé. Si la restauration échoue, votre rollback de force-install est incomplet. Listez explicitement les fichiers jamais versionnés pour éviter les fuites dans les tickets tout en capturant assez de métadonnées pour détecter la dérive.

Observez les événements filesystem sur le plist : certains gestionnaires écrivent atomiquement. Dans de rares courses, `launchd` peut voir un état partiel ; un `bootout` après remplacement atomique est plus sûr que des `kick` répétés.

Intégrez les notes de version vendeur dans les contrôles post-install. Si une release renomme des clés LaunchAgent, votre playbook doit refléter le même renommage. Sinon une clé obsolète reste active tandis que la CLI attend déjà de nouveaux défauts.

Pour le support, créez des macros demandant les quatre faits (semver attendue, semver réelle, mtime plist, export d’échelle). Cela raccourcit la triage et évite les restarts aveugles.

Avec reverse-proxy, validez sticky sessions et upgrades WebSocket séparément de `launchd`. Un recycle gateway ne sert à rien si le proxy met en cache d’anciens amonts. Ajoutez les logs proxy au même dossier de preuve.

Planifiez les fenêtres de maintenance pour éviter un `bootout` pendant des téléchargements d’extensions. Des téléchargements interrompus laissent des artefacts partiels qui oscillent vert/rouge et ressemblent à des listeners figés.

Terminez avec un go/no-go clair : fermez l’incident seulement si la matrice classe `bootstrap` comme suffisant et si l’échelle ne montre plus d’avertissements 429 ou d’identifiants. Sinon documentez le risque résiduel au lieu de masquer avec un autre restart.

Culture d’exploitation : apprenez aux nouveaux opérateurs à lire exit zéro avec scepticisme. Sinon se développe l’habitude de répéter des commandes au lieu de comparer l’état. Couplez la formation à une sandbox avec plist volontairement obsolète pour rendre le motif tangible.

Quand la finance challenge les heures Mac, montrez le gain de temps grâce aux artefacts standardisés de l’échelle. C’est souvent plus convaincant que la seule disponibilité. Documentez aussi le coût d’un mauvais domaine : un `bootout` erroné peut coûter plus longtemps que la réparation si personne ne remarque que l’agent GUI est intact.

Automatisez des alertes lorsque `lastTouchedVersion` diverge de la chaîne du binaire. Un diff quotidien entre version attendue et rapportée attrape la dérive avant les utilisateurs.

Enfin, traitez OpenClaw sur macOS comme une double vérité : layout du gestionnaire de paquets et enregistrement `launchd`. Tant qu’ils ne marchent pas ensemble, `openclaw gateway restart` restera poliment réussi pendant que la réalité client reste obstinément ancienne. Avec l’échelle officielle, un `bootout`/`bootstrap` propre, un force-install discipliné et une paire semver, la plateforme redevient ennuyeuse — et l’ennui est le compliment ultime.

1. Symptômes trompeurs

Un code de sortie nul n’est pas une sonde de santé. Les LaunchAgents utilisateur peuvent recycler un wrapper pendant qu’un sidecar conserve d’anciens sockets.

Les rechargements partiels imitent des passerelles saines alors que les routes profondes restent obsolètes.

2. Échelle officielle avant launchd

Sauter l’échelle mélange extensions, quotas 429, identifiants et dérive launchd.

Horodatez chaque étape pour les handoffs distants.

3. plist, bootout et bootstrap

`~/Library/LaunchAgents/com.openclaw.gateway.plist` doit refléter le binaire réel. Après édition, préférez `bootout`/`bootstrap` à un `kick` ambigu.

4. Procédure numérotée

1. Capturez semver attendue, semver réelle, mtime du plist et exports de l’échelle.
2. Exécutez l’échelle officielle avant toute opération launchd.
3. Lisez `ProgramArguments` via `plutil -p` sur le plist utilisateur.
4. Choisissez le domaine bootstrap correct, puis `bootout` et `bootstrap`.
5. Filtrez `launchctl print` pour `com.openclaw.gateway` et validez les chemins.
6. Si le layout diverge, sauvegardez les jetons puis envisagez `gateway install --force`.
7. Relancez probes superficielles et profondes après alignement.

# 1) D'abord l'échelle officielle (doctor, probes, extensions)
#    Voir: 20260506-openclaw-depannage-officiel-sondes-gateway-extensions-429-guide-2026-fr.html

# 2) Inspecter le LaunchAgent utilisateur
/usr/bin/plutil -p ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 3) Adapter DOMAIN puis ré-enregistrer
/usr/bin/launchctl bootout DOMAIN ~/Library/LaunchAgents/com.openclaw.gateway.plist || true
/usr/bin/launchctl bootstrap DOMAIN ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 4) Vérifier le label com.openclaw.gateway
/usr/bin/launchctl print DOMAIN | /usr/bin/grep -n "com.openclaw.gateway" || true

# 5) Si ProgramArguments diverge encore: sauvegarder puis
#    openclaw gateway install --force

5. Matrice de décision

Choisissez la plus petite action qui rétablit les invariants.

6. Paires semver et dérive distante

CLI, passerelle et métadonnées persistantes doivent bouger ensemble. Les divergences `lastTouchedVersion` imitent des restarts inefficaces.

Les flottes distantes mettent à jour à des vitesses différentes : automatisez la validation des chemins plist après chaque déploiement.

7. Baseline Mac distant

Après remédiation, archivez semver, empreinte plist, extrait `launchctl print`, inventaire d’écoute, doctor, probes minimales et profondes.

Planifiez une exécution hebdomadaire et après tout changement de toolchain.

8. Points de douleur numérotés

1. Sortie zéro mais génération d’en-têtes incohérente.
2. Confusion entre domaine GUI et domaine SSH.
3. Semver alignée visuellement, extensions sur une API ancienne.
4. Jetons neufs mais secrets d’écoute obsolètes côté clients.

9. FAQ

Question : `bootout` immédiat ? Réponse : courte coupure ; excluez d’abord 429 et identifiants.

Question : `gateway install --force` universel ? Réponse : utile pour incohérences d’install, pas pour pannes fournisseur.

Question : Santé toujours verte ? Réponse : approfondissez les routes authentifiées.

10. Conclusion et Mac hébergés

Traitez l’incident comme un écart entre l’enregistrement launchd et le layout installé : échelle officielle, `bootout`/`bootstrap`, force-install discipliné, paire semver.

Les preuves standardisées accélèrent les revues et réduisent les nuits blanches.

Pour une capacité Mac distante prévisible, explorez aussi les offres Mac hébergées SFTPMAC en parallèle des runbooks cités.