Les opérateurs qui installent OpenClaw sur des Mac mini M4 NodeMac headless voient souvent la CLI réussir alors que le LaunchAgent passerelle quitte après une mise à niveau Node Homebrew. Cette matrice du 2026-05-21 relie les symptômes d'échec d'installation aux causes racines, compare les runtimes Node bundle et Homebrew, liste huit étapes d'alignement reproductibles et inclut des réponses FAQ à coller dans les tickets d'incident.
Les installateurs amont peuvent placer Node.js sous ~/.openclaw/tools/node/bin/node, tandis que votre session SSH peut résoudre d'abord /opt/homebrew/bin/node. Le démon passerelle lancé par launchd avec le label ai.openclaw.gateway hérite encore d'un autre PATH. Quand ces trois binaires divergent, les add-ons natifs se chargent dans la CLI mais échouent sous le démon—exactement la classe de bugs signalée contre l'installation passerelle qui ignore le Node bundle sur macOS vierges en 2026.
Échecs d'installation qui ressemblent à « OpenClaw cassé » mais sont une dérive PATH
- CLI saine, passerelle arrêtée :
openclaw doctorpasse en SSH maislaunchctl print gui/$(id -u)/ai.openclaw.gatewayaffiche le code de sortie 78 aprèsbrew upgrade node. - Triple décalage de version :
node -vaffiche v24.x en SSH, le plist pointe vers v22.19, les outils bundle rapportent un autre niveau de patch. - npm EACCES à l'installation :
npm i -g openclawéchoue avec des erreurs de permission car le préfixe global n'est pas accessible en écriture pour l'utilisateur de service. - git manquant sur macOS propre : l'installation npm s'arrête car git est requis pour récupérer les dépendances—fréquent sur les images NodeMac fraîches avant l'application des paquets de base.
Commencez par la checklist d'onboarding headless et d'acceptation du démon s'il s'agit d'une première installation. Pour la région et le placement SSH/VNC, voir le guide régions et SSH/VNC du 2026-05-19. Diagnostics approfondis : OpenClaw doctor et diagnostics de santé. Configuration du compte : centre d'aide et tarifs.
Matrice symptôme → cause → correctif (à copier dans les runbooks)
Utilisez ce tableau pendant les incidents en direct sur des nœuds Mac mini M4 loués. Chaque ligne se termine par une commande exécutable en SSH sans ouvrir VNC.
| Symptôme | Cause probable | Premier correctif (SSH) | Vérifier |
|---|---|---|---|
| npm EACCES | Préfixe global non accessible en écriture | npm config set prefix ~/.npm-global |
which openclaw |
| Passerelle exit 78 | Node plist ≠ node CLI | Modifier le chemin node dans ProgramArguments de ~/Library/LaunchAgents/ai.openclaw.gateway.plist |
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway |
| doctor avertit Node | Inférieur à 22.19 | Installer Node 22 via l'installateur ou figer le chemin bundle | node -v ≥ 22.19 |
| npm install failed | git manquant | xcode-select --install ou brew install git |
git --version |
| Timeout santé | Socket up, plugins en crash | Suivre ~/.openclaw/logs/gateway.log |
Appel santé 3000 ms OK |
Comparaison des sources runtime : quel Node doit posséder la passerelle ?
Choisissez une runtime primaire par hôte et documentez-la dans votre registre de flotte. Mélanger les sources sans chemins plist explicites est le mode d'échec dominant sur les locations Mac mini M4 headless en 2026.
| Source runtime | Chemin typique | Avantages sur NodeMac | Inconvénients |
|---|---|---|---|
| Bundle (install-cli) | ~/.openclaw/tools/node/bin/node |
Correspond à la matrice de tests amont ; survit au churn brew | Facile à ignorer si le plist pointe encore vers Homebrew |
| Homebrew node@22 | /opt/homebrew/opt/node@22/bin/node |
Familier pour les admins macOS ; correctifs sécurité rapides | brew upgrade peut désynchroniser la passerelle |
| npm-global utilisateur | ~/.npm-global/bin/openclaw |
Corrige EACCES sans sudo | launchd doit hériter explicitement des exports PATH |
Procédure d'alignement en huit étapes (reproductible en SSH)
- Capturer trois chemins Node : exécuter
which node; node -v; plutil -extract ProgramArguments xml1 -o - ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null | headet coller dans le ticket. - Lancer doctor d'abord : exécuter
openclaw doctor(ajouter les flags fix seulement après lecture du rapport). - Figez Node ≥ 22.19 : installer ou sélectionner Node qui respecte le minimum amont ; bloquer les rétrogradations majeures accidentelles.
- Corriger le préfixe npm : pour EACCES, définir
npm config set prefix ~/.npm-globalet exporter PATH dans~/.zprofilede l'utilisateur de service. - Aligner le chemin node du plist : pointer la première entrée ProgramArguments vers le binaire node choisi ; exécuter
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plistpuis rebootstrap. - Ré-onboarder le démon : exécuter
openclaw onboard --install-daemondepuis le même PATH shell que vous comptez conserver. - Probe santé : appeler la santé loopback avec un délai de 3000 ms ; archiver la sortie à côté du numéro de série de l'hôte.
- Garde-fou CMDB : enregistrer la source runtime choisie (bundle / brew / npm-global) et interdire les fenêtres brew upgrade sans test fumée de passerelle.
Note workflow métier : les équipes support qui routent les tickets Slack via OpenClaw sur un Mac mini M4 à Singapour échouent encore si les chemins Node dérivent—corrigez l'alignement runtime avant d'optimiser les prompts modèle. La disponibilité stable de la passerelle compte plus que gagner 50 ms d'inférence une fois les messages en file derrière un démon crashé.
FAQ : PATH Node.js OpenClaw sur Mac mini M4
Préférer Node bundle ou Homebrew ?
Préférez Node bundle sur les passerelles de production si vous voulez que install-cli et launchd restent sur le même binaire. N'utilisez Homebrew que si vous figez explicitement le chemin plist après chaque brew upgrade.
VNC aide-t-il pour les erreurs npm install ?
Rarement. Les correctifs PATH et permissions sont des tâches SSH. Utilisez VNC uniquement pour les invites de confidentialité macOS qui bloquent les assistants d'automatisation—pas pour npm EACCES.
Quels chiffres vont dans l'annexe du runbook ?
Enregistrez la semver Node, le chemin du préfixe npm, le chemin absolu node du plist, le délai santé 3000 ms et le dernier hash openclaw doctor réussi pour que la prochaine astreinte ne redébatte pas des versions.
Corriger les chemins d'installation OpenClaw sur NodeMac va plus vite si vous traitez le Mac mini M4 comme un appliance passerelle durable, pas un portable jetable. Apple Silicon M4 offre une mémoire unifiée pour les chaînes d'outils Node ; macOS natif respecte les hypothèses plateforme d'OpenClaw ; SSH et VNC permettent d'aligner plist et shell sans expédier du matériel. Louer à Hong Kong, Japon, Corée, Singapour ou aux États-Unis place les passerelles près des API Slack et LLM sans CAPEX, et le métal dédié évite que le bruit voisin ressemble à des « échecs npm aléatoires ». Comparez le coût mensuel des nœuds sur la page tarifs avant de perdre une autre journée sur des binaires Node mal assortis.