OpenClaw 2026 sur Mac distant : installation native, tunnel SSH et diagnostic doctor

Quand la passerelle OpenClaw vit sur un Mac distant (studio, rack léger ou nœud loué), le problème n’est plus « installer un paquet » mais aligner trois surfaces : binaire et runtime visibles de launchd, connectivité réelle entre vos clients MCP et le port d’écoute, et enfin la vérité terrain que doctor affiche hors session interactive. En 2026, beaucoup d’équipes épinglent Node 22 pour rester sur une branche LTS prévisible tout en préparant la montée de gamme ; côté réseau, le tunnel SSH reste l’outil le plus honnête pour traverser NAT, bastions et politiques IP fixes sans réécrire immédiatement tout le edge. Ce guide condense un runbook : installation native, LocalForward/RemoteForward, démon onboard et FAQ doctor. Pour le socle macOS local (TCC, State, iCloud, alignement Node et passerelle), prolongez avec OpenClaw sur macOS local (Apple Silicon) : installation, TCC, répertoire State, passerelle launchd et doctor ; pour la stabilité launchd et la triade doctor / status / journaux, reliez au manuel Manuel de stabilité launchd pour la passerelle OpenClaw : doctor, ports occupés et doubles LaunchAgent.

1. Installation native sur le Mac distant : Node 22, PATH figé et premier onboard

Sur Apple Silicon, évitez la double vérité « node interactif versus node launchd ». Installez Node 22 LTS via le gestionnaire validé par votre équipe (fnm, asdf ou paquet interne), puis référencez le chemin absolu dans le plist du service ou dans un wrapper shell minimal. Lancez une première passe onboard depuis une session SSH avec les mêmes variables que le service : cela initialise répertoires, permissions attendues et messages que doctor réutilisera. Documentez la triple version (macOS, build OpenClaw, Node) dans le ticket de changement — c’est la seule façon de comparer deux captures doctor sans dérive sémantique.

Règle d’or : ce que doctor voit après bootstrap doit être reproductible depuis ssh non interactif, pas seulement depuis Terminal.app.

2. Tunnel SSH vers la passerelle : LocalForward, RemoteForward et garde-fous

Deux motifs reviennent : exposer le port local du Mac distant vers votre poste (-L) ou publier un port d’écoute distant vers un bastion (-R) lorsque seuls les rebonds SSH sont autorisés. Dans les deux cas, verrouillez l’interface d’écoute (127.0.0.1 plutôt que 0.0.0.0 sauf besoin explicite), activez ServerAliveInterval pour éviter les tunnels « muets », et logguez RTT + pertes sur la session. Pour les équipes qui chaînent plusieurs sauts, préférez ProxyJump à l’empilement manuel de ssh : moins de surprises sur les chemins known_hosts et les clés hôte. Après ouverture du tunnel, validez avec un curl local vers le port mappé avant d’attaquer les clients MCP — cela sépare problèmes réseau et problèmes applicatifs.

Si la passerelle doit survivre aux coupures Wi‑Fi du portable qui initiait la session, déportez la persistance : soit un service systemd sur un petit Linux de confiance qui maintient le tunnel, soit un LaunchAgent sur un second Mac stable qui rouvre ssh avec les mêmes options. L’objectif est que le Mac distant ne dépende pas d’une fenêtre Terminal ouverte sur le genou d’un développeur — exactement le même principe que pour les workers CI qui doivent redémarrer sans cliquer sur « Reprendre ».

3. Démon onboard : démarrage, idempotence et interaction avec launchd

Le flux recommandé reste onboard → doctor → correctifs ciblés. Si onboard réécrit des fichiers pendant qu’un LaunchAgent recharge la passerelle, vous obtiendrez des courses : figez une fenêtre de maintenance ou désactivez temporairement KeepAlive agressif. Gardez les journaux stdout/stderr sur un volume non synchronisé (évitez Bureau/Documents iCloud pour les sockets chauds). Lorsque le démon signale des étapes « déjà satisfaites », archivez quand même la sortie : elle sert de preuve d’alignement pour l’audit interne.

4. FAQ doctor : symptômes fréquents sur Mac distant

Les WARN qui deviennent ERROR après reboot touchent surtout PATH incomplet, port déjà lié ou cwd absent pour un outil MCP. Si doctor annonce un binaire introuvable alors que which répond en interactif, comparez les variables du plist avec celles de ssh user@host 'env'. Pour les ports, utilisez lsof -nP -iTCP côté distant ; pour TCC, rappelez-vous que le binaire réellement exécuté par launchd doit porter l’autorisation, pas un shim temporaire. Enfin, séparez les erreurs « réseau tunnel » (timeout client) des erreurs « passerelle OK mais outil MCP lent » en traçant trois timestamps : entrée SSH, handshake HTTP/MCP, première réponse outil.

Lorsque doctor seul semble incohérent, capturez deux sorties complètes — avant et après sudo launchctl kickstart -k gui/$(id -u)/… — puis différez-les. Les messages qui n’apparaissent qu’après rechargement signalent souvent un double plist ou un binaire mis à jour sans redémarrage du service ; ceux qui disparaissent uniquement lorsque le tunnel est actif pointent vers une dépendance réseau mal modélisée dans la configuration.

5. Observabilité minimale : tracer le tunnel, la passerelle et les outils MCP

Avant d’élargir l’accès à toute l’équipe, instrumentez trois séries temporelles : état du processus SSH (redémarrages, code de sortie), latence de la passerelle (temps jusqu’au premier octet après authentification), et durée des appels MCP côté outil. Sur macOS distant, corrélez avec log show --style syslog filtré sur le binaire de la passerelle plutôt que de multiplier les tail -f ad hoc. Côté client, gardez une trace anonymisée des sessions qui échouent après exactement N secondes : c’est souvent la signature d’un idle timeout réseau mal aligné avec le keepalive SSH. L’objectif n’est pas un SaaS d’observabilité complet, mais une chaîne de preuve qui relie tickets P1, extraits doctor et captures réseau sans recompiler mentalement l’incident trois jours plus tard.

6. Liste courte avant de basculer en production

  • Node 22 référencé par chemin absolu dans le service ; doctor identique en SSH non interactif.
  • Tunnel SSH avec bind localhost, keepalive et monitoring RTT ; procédure de rotation des clés documentée.
  • Journaux et état hors dossiers iCloud ; onboard idempotent pendant fenêtres de maintenance.
  • Runbook d’incident reliant codes doctor, extraits journaux et version des paquets.

Pourquoi un Mac mini sous macOS reste le meilleur socle pour cette pile distante

Une passerelle derrière tunnel SSH a besoin d’un hôte qui ne ment pas sur l’heure système, les interfaces réseau et la persistance des fichiers : macOS sur Mac mini Apple Silicon combine mémoire unifiée rapide, SSD NVMe pour les journaux MCP, et une consommation au repos de l’ordre de quelques watts — idéal pour un nœud 24/7 qui ne doit pas réveiller toute une salle serveur. Gatekeeper, SIP et FileVault donnent à la sécurité des leviers natifs contre l’exécution opportuniste de binaires, ce qui compte lorsque des tunnels ouvrent des surfaces d’accès indirectes.

Si vous voulez aligner région, bande passante et classe de machine avec des builds Xcode ou des runners voisins sans bruit superflu, le Mac mini M4 reste en 2026 l’un des points d’entrée les plus équilibrés pour industrialiser ce schéma avant de multiplier les nœuds. Pour comparer les offres Macstripe et monter un Mac distant prêt SSH/VNC en quelques minutes, ouvrez la page d’accueil Macstripe : c’est le moment idéal pour valider latence réelle, tunnel et diagnostic doctor sur du matériel dédié plutôt que sur un poste portable saturé.