App macOS OpenClaw + CLI externe + passation LaunchAgent ai.openclaw.gateway sur Mac cloud loué

Les opérateurs qui traitaient l’app de bureau OpenClaw comme un univers autonome se réveillent avec des voyants vides après une mise à niveau npm — le binaire de passerelle a bougé, Node est passé de 22 à 24, et le LaunchAgent pointe encore vers un chemin Cellar supprimé. L’empaquetage macOS amont suppose désormais que vous installez vous-même la CLI openclaw pendant que l’interface orchestre attacher/détacher et active le LaunchAgent par utilisateur couramment nommé ai.openclaw.gateway. Ce runbook de mai 2026 explique pourquoi cette séparation existe, comment lire l’intention du plist sans deviner, comment traquer le décalage de version entre UI et CLI, comment exécuter une passation en neuf étapes sur les mini MacLogin de Hong Kong aux États-Unis, et quand les passerelles distantes via SSH méritent d’autres budgets de latence.

Approfondissements : dépannage du démon, onboarding sans tête, hub thématique collection OpenClaw. Ancres produit : aide, tarifs, VNC.

Pourquoi le modèle CLI externe compte sur des locations Apple Silicon

Embarquer Node/Bun dans l’app de bureau simplifiait les démos mais doublait les cycles de correctifs — la sécurité exigeait des réponses CVE plus rapides que le rythme des releases GUI. Les installations CLI externes permettent d’épingler la semver par flotte, de mettre en miroir les artefacts en interne et d’aligner les runners CI avec les portables développeurs. Sur des Mac mini loués vous SSH souvent sans tête ; l’interface peut ne jamais démarrer, pourtant le même LaunchAgent maintient la passerelle pour les charges pilotées par API.

Anatomie du plist LaunchAgent à vérifier

La plupart des installs déposent ~/Library/LaunchAgents/ai.openclaw.gateway.plist. Champs critiques :

• ProgramArguments : chemin absolu vers openclaw plus sous-commande — confirmez quel shebang Node résout.
• WorkingDirectory : doit correspondre aux racines workspace référencées par les configs JSON5.
• EnvironmentVariables : PATH, NODE_OPTIONS, jetons API — un PATH mal aligné est le premier tueur silencieux après les upgrades brew.
• ThrottleInterval / KeepAlive : associez aux guides de boucle de crash lorsque la passerelle redémarre plus vite que les journaux ne se vident.

Matrice de décalage de version app vs CLI

Symptôme	Décalage probable	Première instrumentation	Stabilisation
L’UI affiche hors ligne mais curl localhost réussit	PID obsolète mis en cache par l’app	Redémarrer l’app ; vérifier que le port santé correspond à la config	Épingler la semver CLI dans le wiki interne
doctor signale un moteur incompatible	Dérive Node 22 vs 24	which node vs PATH du plist	Aligner l’épinglage brew + export plist
La passerelle quitte immédiatement	Droits workspace manquants	Suivre les journaux unifiés pour sandbox/TCC	Corriger les ACL du répertoire workspace

Runbook de passation en neuf étapes (bureau ↔ CLI ↔ launchd)

1. Instantané de openclaw doctor --json et stocker le SHA-256.
2. Décharger proprement launchctl bootout gui/$(id -u)/ai.openclaw.gateway.
3. Mettre à niveau la CLI via le gestionnaire de paquets approuvé ; rejeter les miroirs dérivés.
4. Diff ProgramArguments du plist vs nouvel emplacement du binaire.
5. Recharger le plist via les drapeaux d’onboarding documentés — évitez les fautes de frappe copier-coller.
6. Démarrer le LaunchAgent et confirmer les ports d’écoute via la section config.
7. Attacher l’app de bureau (si utilisée) en capturant des captures pour la KB.
8. Exécuter un webhook synthétique ou une invocation d’outil pour prouver le flux bout en bout.
9. Archiver journaux + doctor JSON avec l’ID du ticket de changement.

Flux passerelle distants via SSH / Tailscale

Les locataires MacLogin exploitent souvent des mini sans tête via SSH tandis que les designers gardent l’app macOS localement. Les chemins d’attachement distant doivent préserver les attentes mTLS — documentez si les forwards SSH terminent sur localhost ou un socket Unix et vérifiez que les keepalives correspondent au guide keepalive SSH.

Schémas de journaux unifiés pour les échecs d’attache passerelle

Filtrez les journaux unifiés autour des fenêtres de redémarrage de passerelle avec une enveloppe ±90 secondes ; corrélez les codes de sortie launchd avec les traces Node. Lorsque les journaux tournent agressivement, associez cet article à votre politique de rotation JSONL des billets précédents sur la journalisation passerelle.

Liens croisés dans l’écosystème passerelle

Liez les mises à niveau à la discipline de rechargement de config, aux notes de fiabilité webhook dans clés d’idempotence, et aux attentes de backoff fournisseur lorsque des tempêtes de reconnexion frappent.

FAQ

Les passerelles prod doivent-elles rester sans tête ? Souvent oui — planifiez l’attache interactif seulement pendant les enquêtes pour limiter les redémarrages accidentels pilotés par la GUI.

Où comparer les régions pour des passerelles sensibles à la latence ? Commencez par tarifs et mesurez RTT empiriquement.

Le personnel MacLogin peut-il corriger mon plist ? Les locataires maintiennent les configs OpenClaw ; nous fournissons l’atteignabilité documentée sur aide.

Pourquoi le Mac mini loué reste l’empreinte pragmatique OpenClaw

Les enveloppes de consommation au repos d’Apple Silicon conviennent aux passerelles toujours actives sans surprises thermiques — critique quand l’automatisation Séoul s’exécute la nuit tandis que la Californie s’attache à distance. Mieux vaut scaler horizontalement : ajoutez un autre mini JP pour les rafales webhook et laissez les nœuds SG intacts pour les charges Studio ; revisitez tarifs lorsque la profondeur de file grimpe semaine après semaine.