Premier démarrage passerelle OpenClaw sur macOS en 2026 : PATH, gestionnaires Node, blocs d’environnement LaunchAgent et smoke tests reproductibles sur Mac mini cloud

Les pannes OpenClaw les plus cruelles surviennent après que le tutoriel a fonctionné dans votre Terminal : le LaunchAgent se réveille au boot, hérite d’un PATH squelettique, ne trouve pas node, et votre passerelle respawn en silence jusqu’à ce que les consommateurs d’API voient des chaînes 502 erratiques. En 2026, traitez macOS launchd comme un système différent de zsh—il ignore vos exports .zprofile, ne connaît pas nvm sans câblage explicite, et exécute volontiers des binaires avec mauvais linker dynamique si les symlinks sont négligés. Ce playbook explique comment épingler une toolchain, figer les variables d’environnement dans la plist et répéter des smoke tests sur un Mac mini loué avant de pointer la production.

Liez cet article à openclaw doctor diagnostics passerelle pour un triage profond, profils JSON d’environnement pour le calque des secrets, et Mac mini cloud partagé et isolation lorsque plusieurs ingénieurs partagent un siège passerelle.

Pourquoi launchd casse les hypothèses interactives

Les shells interactifs chargent rc, hooks direnv et intégrations d’éditeur. Les jobs launchd héritent d’un environnement documenté dans le schéma plist Apple—tout le reste est indéfini. C’est pourquoi which node dans tmux montre /opt/homebrew/bin/node tandis que les logs LaunchAgent du même utilisateur se plaignent node: command not found. Ce n’est pas du hasard : ce sont deux graphes de démarrage distincts.

Un autre piège est HOME : les comptes d’automatisation tournent parfois avec un home différent si vous avez cloné une image fournisseur. OpenClaw stocke l’état sous ~/.openclaw ou $OPENCLAW_HOME ; si HOME dérive, la passerelle écrit des configs introuvables pendant les incidents. Fixez HOME explicitement lorsque vous supportez des images clonées.

Les exports LANG/TZ manquent souvent ; cela influence horodatage des logs et parfois la résolution TLS. Matérialisez-les lorsque vos profils JSON en dépendent.

Node Homebrew versus nvm versus tarballs épinglés

Homebrew installe des chemins stables sous /opt/homebrew sur Apple Silicon et maintient des symlinks—idéal pour LaunchAgents car ProgramArguments peut référencer /opt/homebrew/bin/node directement. nvm est ergonomique pour les humains mais fragile pour les démons : les changements de version dépendent de fonctions shell, pas de fichiers attendus par launchd. Si vous tenez à nvm, matérialisez un script wrapper qui exporte un chemin de version fixe et appelez ce script depuis la plist—jamais source /.nvm/nvm.sh && nvm use inline dans ProgramArguments sans shell de login.

Les tarballs épinglés depuis nodejs.org sont populaires dans les environnements réglementés : sommez l’archive, décompressez sous /usr/local/node-20.11.1, pointez la plist sur ce binaire. Les montées de version deviennent des remplacements de fichiers délibérés plutôt que des relocalisations automatiques de brew. Budgetisez trente minutes par trimestre pour ré-épingler et relancer les smoke ; l’omettre invite une dérive silencieuse quand les correctifs sécurité arrivent.

Volta, asdf et fnm demandent tous des wrappers explicites si launchd ne charge pas votre shell hooké. Documentez la stratégie choisie dans l’onboarding pour éviter qu’un nouveau contributeur ne fasse « juste nvm install » et casse la production.

LaunchEnvironmentVariables et WorkingDirectory

Utilisez WorkingDirectory pour que les chemins relatifs dans les configs OpenClaw se résolvent de façon prévisible—pointez vers le répertoire contenant openclaw.json ou la racine de config approuvée. Associez LaunchEnvironmentVariables pour PATH, NODE_OPTIONS (si autorisé) et emplacements SDK. Gardez la liste sous douze clés pour limiter la fatigue d’audit ; les longues listes masquent les fautes de frappe.

StandardErrorPath et StandardOutPath doivent aboutir à des logs service avec rotation ; Console.app est sympathique mais difficile à greper en CI. 50 Mo par fichier avec cinq générations est un défaut raisonnable avant logging centralisé.

Ajoutez ThrottleInterval et des politiques KeepAlive sensées pour éviter que des boucles de crash ne monopolisent le CPU. Documentez les codes de sortie qu’OpenClaw utilise intentionnellement pour que le SRE distingue « redémarrage sain » de « pager ».

Matrice de décision pour la toolchain

Approche	Convivialité démon	Frottement upgrade	Meilleur cas
Node Homebrew	Élevée	Moyenne—churn de chemins	Petites équipes, une passerelle par hôte
Alias nvm par défaut	Faible sans wrapper	Faible pour humains	Portables seulement, pas LaunchAgents
Tarball épinglé	Très élevée	Élevée—dépaquetage manuel	Environnements compliance lourds

Protocole smoke de cinq minutes

1. Exécutez launchctl print gui/$UID/com.votreorg.openclaw.gateway et vérifiez que la dernière raison de sortie est zéro.
2. Interrogez l’endpoint de santé avec curl -fsS deux fois, séparées par 10 secondes de sommeil, pour attraper les rechargements TLS paresseux.
3. Déclenchez un appel d’outil inoffensif qui exécute /usr/bin/true via sous-processus pour valider le PATH des enfants.
4. Faites tourner les logs une fois pour confirmer les droits d’append après troncature.
5. Arrêtez le job via launchctl bootout, redémarrez et assurez-vous que la passerelle rebind le même port en moins de 30 secondes.

Automatisez la séquence avec un script shell versionné dans votre dépôt infra ; les humains oublient l’étape quatre jusqu’à ce que le disque soit plein la veille d’une démo.

Étendez avec des pings WebSocket et un outil synthétique qui ouvre du trafic réseau pour valider les proxys—les hôtes cloud routent IPv6 différemment des laptops locaux.

Contrôles doctor qui attrapent la dérive PATH

La commande openclaw doctor surface le décalage de versions, les binaires manquants et les environnements suspects vides. Lancez-la depuis le même compte qui possède le LaunchAgent—interactivement et via sudo -u si vous séparez les rôles admin. Comparez les sorties : si doctor interactif montre Node 20.11 mais les logs plist 18.19, deux toolchains se battent encore.

Lorsque doctor signale des problèmes de magasin TLS, corrigez la confiance Keychain avant de poursuivre OpenClaw—les mises à jour macOS déplacent parfois des certificats intermédiaires et les passerelles échouent avec de faux « upstream 403 ».

Combinez doctor avec des logs JSON structurés pour archiver des instantanés PATH à chaque démarrage de processus—cela accélère les post-mortems après Patch Tuesday Node.

Permissions fichiers et surprises umask

Les LaunchAgents tournent avec l’umask par défaut de l’utilisateur, qui diffère souvent du 0022 supposé lors d’un chmod interactif. Si OpenClaw écrit des sockets de domaine Unix ou des fichiers PID dans un répertoire partagé, vérifiez explicitement la lisibilité de groupe plutôt que de compter sur « ça marchait hier ». Sur mini partagés, alignez un groupe POSIX unique, utilisez les ACL avec parcimonie et documentez les répertoires lisibles par le monde—les revues sécurité poseront la question.

Surveillez aussi les attributs de quarantaine Gatekeeper sur les binaires passerelle téléchargés : com.apple.quarantine peut bloquer l’exécution jusqu’à approbation, ce qui ressemble à une erreur PATH dans des logs maigres. Retirez la quarantaine intentionnellement après vérification de somme plutôt que de tout xattr -d aveuglément.

Vérifiez les limites SIP et TCC pour les utilitaires qu’OpenClaw lance via outils—les profils sandbox diffèrent entre Terminal.app et les processus lancés par launchd.

Fenêtres de montée de version sans plist orphelines

Coordonnez les montées Node avec les releases OpenClaw : bump la runtime d’abord en staging, relancez les smoke, puis promouvez la production pendant une fenêtre de maintenance avec rollback écrit incluant la stanza ProgramArguments précédente. Conservez au moins deux générations de plist dans Git avec dates pour que l’astreinte diff rapidement.

Si vous dépendez d’installations npm globales, rappelez-vous que les chemins npm -g diffèrent entre foyers Intel et Apple Silicon. Ne copiez jamais du texte plist d’un Mac Intel vers Apple Silicon sans revoir chaque chemin absolu.

Communiquez aux consommateurs d’API lorsque les sondes de santé rougissent intentionnellement pendant la fenêtre—la transparence réduit les escalades erronées.

FAQ

Pourquoi OpenClaw fonctionne dans Terminal mais échoue sous LaunchAgent ?

Parce que Terminal charge vos fichiers de démarrage shell ; launchd non. PATH et découverte de toolchain doivent être explicites dans la plist ou un wrapper.

Dois-je appeler nvm use dans une plist ?

Évitez. Utilisez des binaires absolus ou un wrapper qui fixe NODE_HOME sans sourcing interactif.

Combien de temps durer les smoke tests de premier run ?

Au moins cinq minutes de charge régulière plus un cycle de redémarrage pour imports paresseux et invites de permission.

Où les invites TCC apparaissent-elles encore ?

Les fonctionnalités caméra, micro, contacts ou AppleScript peuvent exiger une approbation GUI une fois par utilisateur—répétez sur une machine avec VNC.

La stabilité du premier run est un problème façonné par le matériel : vous avez besoin du même comportement Apple Silicon, du même trousseau et de la même courbe de ventilateur silencieuse que la production. Louer un Mac mini chez MacHTML pour environ 16,9 $ par jour fournit cette machine de référence sans délai d’achat. SSH pour éditer les plist, VNC lorsque TCC exige un clic, arrêt après la fenêtre smoke—la capacité élastique bat un portable développeur qui dort la nuit et coupe les websockets.

L’efficacité Apple Silicon compte aussi lorsque les scripts doctor et le trafic synthétique tournent des heures : la machine reste froide, la consommation prévisible, et vous ne simulez pas macOS depuis un conteneur Linux qui ment sur le verrouillage de fichiers.