2026 — OpenClaw Node pour VS Code sur une passerelle Mac physique distant : runbook reproductible — installer l'extension, se connecter au port 18789, boucle locale contre redirection SSH et frictions TCC (triage + FAQ)
Les équipes qui louent un Mac physique sans écran pour OpenClaw réussissent souvent le SSH et un curl depuis la machine, puis échouent lorsque l'extension VS Code tourne sur un portable et pointe encore vers 127.0.0.1. Ce runbook livre une matrice de transport, une checklist en sept étapes, des diagnostics prêts à coller, des paramètres réutilisables et une FAQ alignée sur les passerelles de production sur nœuds type ZoneMac.
Introduction : trois questions auxquelles cet article répond
Qui — ingénieurs plateforme qui raccordent OpenClaw sur un Mac distant dédié ou mutualisé. Quoi — un chemin reproductible du Marketplace jusqu'à un plan de contrôle HTTP stable sur le port 18789 (ou votre port surchargé) sans confondre un succès en boucle locale avec une preuve de bout en bout. Structure — irritants, matrice, sept étapes, chiffres réutilisables, triage, FAQ, puis pourquoi un Mac mini Apple Silicon convient aux passerelles sans présence humaine.
Pour la stabilité OpenClaw en CI et le rôle du Mac nu, voir OpenClaw en CI : pourquoi le Mac physique est plus stable ? Pour arbitrer les régions de nœuds macOS dans une flotte distribuée, voir Guide de déploiement mondial 2026 : choisir le meilleur nœud macOS par région.
1. Trois irritants
- La boucle locale n'est pas transitive. Prouver
curl http://127.0.0.1:18789/healthsur le serveur ne prouve que le processus passerelle et le pare-feu macOS sur cet hôte. Une fenêtre VS Code sur une autre machine exige un tunnel explicite, un DNS scindé ou un chemin proxy inverse — sinon l'extension dialogue avec sa propre boucle et expire. - Les refus de permission imitent un « mauvais port ». TCC peut bloquer des lectures trousseau, le contrôle d'Automatisation du Terminal ou des écritures sous des répertoires protégés alors que
lsofaffiche encore LISTEN. L'astreinte chasse nginx pendant des heures alors que la vraie cause estEPERMsur stderr. - Dérive silencieuse entre JSON, plist et UI. Quand quelqu'un modifie l'écoute dans
openclaw.jsonmais pas lesProgramArgumentsdu LaunchAgent, ou que l'espace VS Code gardehttp://127.0.0.1:18789alors que la production est passée au TLS surlocalhost:8443, les régressions semblent intermittentes car chaque membre charge un blob de synchronisation différent.
2. Matrice : comment l'extension VS Code doit-elle joindre la passerelle ?
Retenez un transport principal par environnement ; mélanger à l'aveugle des redirections SSH ad hoc et des amonts nginx partagés sans documentation, c'est condamner l'astreinte aux week-ends.
| Schéma | Idéal pour | Points de vigilance |
|---|---|---|
| Boucle locale directe sur le Mac | Automatisations, cron, scripts doctor locaux | Invisible depuis les portables distants ; lier à 127.0.0.1 pour éviter une exposition WAN accidentelle |
SSH -L (redirection locale) |
Développeurs qui attachent VS Code depuis le domicile ou un hôtel | Keepalive et bastions alignés sur la politique d'entreprise ; documenter le port local (ex. 18789 → portable 18789) |
| nginx / Caddy en boucle locale + TLS | Équipes exigeant mTLS, en-têtes SSO ou routage par chemin vers plusieurs démons | Renouvellement des certificats et fautes de proxy_pass ; aligner l'URL de base de l'extension sur le nom d'hôte public, pas sur le 18789 brut |
3. Runbook en sept étapes
- Tracer l'écoute. Sur le Mac distant :
lsof -nP -iTCP:18789 -sTCP:LISTENetcurl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/(adapter le chemin si votre install utilise un sous-préfixe). - Installer OpenClaw Node dans VS Code. Épingler la version d'extension dans un fichier
extensions.jsonde recommandations pour partager le même schéma RPC. - Publier le contrat d'URL de base. Documenter si les développeurs doivent régler la passerelle sur
http://127.0.0.1:18789aprèsssh -L 18789:127.0.0.1:18789 user@passerelle, ou sur un vhosthttps://openclaw.interne. - Durcir launchd. Utiliser
RunAtLoad,ThrottleIntervalet unWorkingDirectoryexplicite ; charger l'environnement depuis un fragment plist lisible par root, pas depuis des dotfiles modifiables par tous. - Parcourir TCC méthodiquement. Si la passerelle exécute AppleScript ou lit des certificats développeur, pré-approuver le binaire dans Confidentialité et capture d'écran pour la revue sécurité interne.
- Acceptation côté client. Depuis le portable développeur :
nc -vz 127.0.0.1 18789une fois le tunnel levé ; si frontal TLS,openssl s_client -connect openclaw.interne:443 -servername openclaw.interne. - Verrouiller la baseline. Committer extraits JSON + plist dans le dépôt plateforme ; taguer une release lorsque les semver passerelle et extension sont validés ensemble.
4. Paramètres prêts à citer
- 18789 — convention pour le plan HTTP local OpenClaw dans beaucoup de gabarits 2026 ; traiter comme configurable, pas comme magie.
- 127.0.0.1 contre 0.0.0.0 — l'écoute en boucle locale évite l'exposition WAN accidentelle ; lier toutes les interfaces impose pare-feu / règles VPC et est rare pour l'intégration VS Code.
- ~30 à 60 s — budget typique de démarrage à froid du LaunchAgent après reboot avant de pager l'astreinte ; coupler avec
ThrottleIntervalpour éviter les tempêtes de redémarrage.
5. Aide-mémoire de dépannage
| Symptôme | Cause probable | Première commande ou correctif |
|---|---|---|
| ECONNREFUSED depuis le portable seulement | Pas de redirection SSH / mauvais port local | Relancer SSH avec -v ; vérifier LocalForward dans ~/.ssh/config |
| HTTP 502 depuis nginx | Amont absent ou mauvais socket | curl -v http://127.0.0.1:18789 directement sur le Mac ; lire la fin du journal d'erreur |
| Processus sort avec le code 1, port libre | TCC / secret manquant | Console.app filtrée par sous-système ; ajouter l'accès disque complet pour le chemin du binaire ; recharger la plist |
6. FAQ
Quel rôle joue le port 18789 ?
C'est la surface HTTP locale par défaut pour la gestion et le trafic extension dans beaucoup de bundles OpenClaw — confirmez toujours dans votre openclaw.json et LaunchAgent.
curl distant fonctionne ; VS Code non — pourquoi ?
Des domaines de boucle différents. Tunnel ou modifiez l'URL de base de l'extension vers un nom d'hôte qui résout vers le chemin relayé que vous avez validé.
Puis-je exposer 18789 sur Internet public ?
Fortement déconseillé sans TLS, authentification/autorisation et limitation de débit. Préférez VPN, Tailscale ou redirection SSH pour les portables opérateurs ; gardez le port brut sur 127.0.0.1 derrière nginx si des navigateurs doivent l'atteindre.
Plusieurs instances sur un seul Mac ?
Attribuez des ports et des labels plist disjoints ; grepez LISTEN avant chaque déploiement.
7. Exécuter cette pile passerelle sur un Mac mini Apple Silicon
OpenClaw couplé à l'automatisation pilotée par VS Code gagne une machine qui reste allumée discrètement : le Mac mini Apple Silicon consomme de l'ordre de 4 W en veille active tout en exposant l'outillage Unix natif, launchd et l'intégration trousseau sans surcoût d'hyperviseur. Gatekeeper, SIP et FileVault macOS dessinent une frontière de confiance plus nette pour des clés API longue durée que sur des jump boxes Windows ou Linux typiques.
La mémoire unifiée absorbe des pics simultanés — passerelles Node, nginx et agents CI légers — lorsque les sondes doctor, le RPC extension et l'expédition des journaux montent en charge. Si vous voulez ce flux sans monter votre propre colocation, louer un Mac mini dédié reste le moyen le plus rapide d'obtenir du métal reproductible avec les mêmes sémantiques plist que ci-dessus.
Si vous standardisez des passerelles OpenClaw pour une équipe distribuée, le Mac mini M4 est en 2026 l'une des ancres les plus rentables pour l'automatisation macOS 24/7 — utilisez le bloc CTA ci-dessous pour aligner capacité, région et contraintes de conformité.
Besoin d'un Mac passerelle aujourd'hui ?
Démarrez un nœud Apple Silicon ZoneMac avec SSH, images compatibles launchd et les mêmes sémantiques de port que vos tests sur 18789.