Sur macOS, le gateway OpenClaw est souvent supervisé par launchd. Opérateurs—et parfois des agents—tentent de « simplement redémarrer le gateway » depuis la même session qui en dépend. Ce schéma peut décharger le LaunchAgent pendant que l’RPC initiateur est encore attaché, ce qui correspond à des rapports réels de gateways qui ne reviennent qu’après connexion avec un shell séparé. Ce runbook explique pourquoi, propose une table de décision actions sûres vs risquées, six étapes narratives alignées sur le HowTo JSON-LD à sept étapes, et relie la récupération et la concurrence.
Avant toute modification, lisez la récupération LaunchAgent du gateway et chat interactif vs jobs longs pour éviter que les redémarrages ne heurtent les tâches workspace lourdes. Les premières installations suivent l’installation et le déploiement. Questions de compte : aide ; pour séparer gateway et CI sur deux hôtes NodeMac : tarifs. La dérive de tokens et plist est couverte par auth, tokens et dérive launchagent.
Mode défaillance : auto-décapitation sous launchd
Le gateway est à la fois le serveur et la dépendance de la commande que vous exécutez. Lorsqu’un agent envoie openclaw gateway restart (ou un wrapper équivalent) via le même canal RPC que le processus gateway, launchd peut bootout le job avant une passation de relais propre. La session CLI qui a initié le redémarrage peut se terminer par une erreur transport, et aucun superviseur ne garantit un bootstrap sain—surtout en headless où personne ne regarde l’écran physique.
- Symptôme A :
gateway statusoscille de « running » à « missing » dans la même seconde où l’agent a invoqué le restart. - Symptôme B : les logs montrent des lignes unload launchd immédiatement à côté d’erreurs de déconnexion RPC.
- Symptôme C : les sondes externes (HTTP health ou TCP connect) expirent plusieurs minutes alors que loginwindow n’a pas démarré de session utilisateur—fréquent sur hôtes SSH-only.
Matrice : qui peut redémarrer le gateway
| Acteur | Contexte typique | Verdict | Alternative plus sûre |
|---|---|---|---|
| Opérateur humain (2e SSH) | Screen ou ssh user@host | Préféré | Séquence bootout/bootstrap documentée ; capture des logs |
| Agent d’automatisation dans OpenClaw | Appel d’outil pendant le chat | Éviter le restart | Émettre un ticket ; orchestrateur externe après mutex |
| LaunchAgent planifié | Réparation nocturne de dérive | Autorisé si plist isolé | Décaler les pics chat ; voir alignement tâches planifiées |
| Job CI sur le même Mac | Étape pipeline « bounce gateway » | Déconseillé | File d’admin dédiée avec identifiants séparés |
Deuxième matrice : checklist pré-redémarrage
| Contrôle | Critère de passage |
|---|---|
| Propriété du listener | Exactement un PID sur la famille de ports gateway configurée ; noter le PID pour rollback |
| Espace disque journaux | Au moins 8 Go libres sur le volume d’état et de logs pour éviter un restart interrompu |
| Mutex avec jobs longs | Aucun job workspace ne détient le palier mutex de maintenance gateway que vous avez défini |
| Continuité du token d’auth | Les clients peuvent recharger le token depuis le disque sans invite GUI interactive |
Chiffres opérationnels à journaliser
- Budget cold start : jusqu’à 90 secondes après bootstrap avant échec déclaré, plus si antivirus ou Full Disk Access attend une validation.
- Intervalle de sonde RPC : toutes les 5 secondes la première minute, puis backoff exponentiel.
- Actions admin concurrentes : plafond une opération modifiant le gateway par hôte ; les éditions plist parallèles perdent la trace du changement fautif.
Astuce headless : si des dialogues de permissions GUI sont suspects, connectez-vous temporairement via VNC, validez une fois, puis revenez au SSH-only.
Six étapes sur l’hôte (expansion du HowTo à sept étapes JSON-LD)
- Arrêtez les commandes via le gateway malade. Ouvrez une deuxième connexion SSH vers le même Mac mini M4 ; cette session ne doit pas dépendre du RPC que vous allez recycler.
- Collectez les preuves : statut, journaux récents, chemin plist jugé autoritaire—comparez avec la dérive de configuration.
- Vérifiez le listener avec
lsofpour ne pasbootoutle mauvais PID lorsque plusieurs expériences partagent un lab. - Déchargez avec la sémantique launchd adaptée à votre version macOS, puis bootstrap depuis le disque pour appliquer EnvironmentVariables et WorkingDirectory.
- Sondez la santé jusqu’à succès RPC depuis le shell externe ; reconnectez ensuite les clients chat.
- Publiez une note d’incident d’une ligne avec horodatage, raison et impact chat/CI—la corrélation avec les rate limits 429 devient triviale.
FAQ
Puis-je automatiser les redémarrages avec Ansible ?
Oui, si le playbook utilise toujours une connexion de contrôle qui ne route pas via le processus gateway que vous recyclez. Traitez le gateway comme une base de données : rebond depuis le plan d’orchestration, pas depuis une requête client.
Et plusieurs gateways dev / prod ?
Plists, ports et répertoires d’état séparés. Documentez quel label LaunchAgent correspond à quel environnement pour que les bootout ne frappent jamais le mauvais label.
Quand scinder complètement les hôtes ?
Lorsque le SLO chat et la préemption CI se battent malgré les paliers mutex—ajoutez un second Mac mini M4 dédié NodeMac plutôt que d’empiler des cycles de vie incompatibles sur un seul graphe launchd.
OpenClaw fiable profite de la même histoire matérielle que vos builds : un Mac mini M4 dédié offre les performances Apple Silicon avec macOS natif, SSH pour la maintenance headless et VNC lorsque des invites de permissions GUI apparaissent, plus un choix géographique entre Hong Kong, le Japon, la Corée, Singapour et les États-Unis pour rapprocher les opérateurs des machines qu’ils réveillent à 03 h. Louer plutôt qu’acheter rend économiquement raisonnable un second hôte « gateway only » lorsque ce runbook prouve qu’il ne faut jamais partager des graphes launchd entre agents expérimentaux et chat production. Comparez les offres par région avant d’empiler un risque de plus sur un seul plist.