Une fois OpenClaw installé sur un Mac mini M4 loué au Canada, la prochaine décision n’est pas cosmétique : atteindre le Gateway local sur TCP 18789 via un tunnel SSH, ou traiter la machine comme un petit nœud de bordure et appeler la passerelle telle que votre fournisseur la publie ? Ce choix modifie les règles de pare-feu, la manière de stocker gateway.remote.token, la nécessité d’exporter un PATH complet sous launchd, et ce qui apparaît dans les journaux quand tout casse à trois heures du matin. Ce billet condense un guide de décision, une procédure par étapes et un tableau de dépannage prêt à coller dans un wiki interne ; pour les scripts d’onboarding, LaunchDaemon et la grille journaux détaillée, croisez avec OpenClaw 2026 sur Mac distant : scripts d’installation, onboard, Gateway 18789, jeton, LaunchDaemon, journaux et déploiement M4 Canada 7×24.
Quand le tunnel SSH l’emporte — et quand la passerelle directe est préférable
Le port forwarding SSH local (par exemple ssh -L 18789:127.0.0.1:18789 utilisateur@mac-canada) laisse le Gateway lié au loopback côté serveur pendant que votre portable parle à localhost:18789. C’est idéal pour un opérateur seul, le débogage de courte durée ou les politiques qui interdisent d’exposer les ports d’agent sur une interface routable. L’inconvénient est opérationnel : le tunnel meurt avec la session SSH, les reconnexions peuvent entrer en course avec les sondes de santé, et vous dépendez toujours d’un SSH stable. Pour le positionnement régional Canada / Amérique du Nord et les arbitrages transpacifiques sur l’accès distant, reliez ce mode à Choisir un Mac distant en 2026 : Singapour, Japon, Corée, Hong Kong et Canada — complément Amérique du Nord, M4, stockage et dev/test.
La passerelle directe signifie que votre plan de contrôle ou un autre service appelle le point de terminaison du Gateway sans l’envelopper dans SSH — souvent en TLS devant 18789, ou sur un chemin géré par le fournisseur. Ce modèle passe mieux à l’échelle pour les agents permanents, plusieurs clients et l’automatisation qui ne peut pas garder un shell interactif ouvert. Il vous pousse à raisonner comme une infrastructure : attentes de sortie statique, rotation de jetons qui ne dépend pas du portable d’un développeur, et documentation explicite du bind address.
launchd possède le processus et que des clients 7×24 doivent joindre le service sans session humaine.
gateway.remote.token et où il doit vivre
Dans les profils OpenClaw récents, gateway.remote.token (ou la clé équivalente après openclaw onboard) est le secret partagé entre clients distants et Gateway. Il doit être lisible par le même contexte utilisateur que celui qui exécute le Gateway — en général le compte qui a terminé l’onboarding — et ne doit pas n’exister que dans un profil de shell interactif. Stockez-le dans le fichier de configuration que le démon charge, ou exportez-le depuis le dictionnaire EnvironmentVariables du plist si votre modèle de sécurité l’autorise. Après toute modification, vérifiez depuis une sonde hors login interactif (par exemple un court script invoqué par launchctl) que le processus voit bien la variable ; un SSH interactif peut masquer complètement l’absence d’environnement plist.
Port 18789 : adresse d’écoute, pare-feu et double écoute
La plupart des builds laissent encore le Gateway sur 127.0.0.1:18789 jusqu’à ce que vous élargissiez explicitement le bind pour l’accès distant — ce qui est cohérent avec une stratégie « tunnel d’abord ». Si vous passez en accès direct, documentez si l’écoute reste en loopback derrière un reverse proxy ou migre vers une adresse LAN ; dans tous les cas, exécutez lsof -iTCP:18789 -sTCP:LISTEN après reboot et après mise à jour. Deux processus signalent un doublon : arrêtez avec openclaw gateway stop, supprimez les LaunchAgents obsolètes, puis ne gardez qu’un seul plist pour que les health checks cessent de fluctuer.
PATH et launchd : étapes sur Mac sans écran
Les jobs launchd héritent d’un environnement minimal ; openclaw peut ne pas se résoudre comme dans Terminal.app. Sur l’hôte Canada, enchaînez ainsi : 1) résolvez le chemin absolu du CLI avec which openclaw dans une session SSH alignée sur l’utilisateur du démon. 2) Dans ProgramArguments du LaunchAgent, préférez le binaire absolu plutôt qu’un wrapper shell. 3) Si vous devez envelopper avec /bin/zsh -lc, préfixez PATH dans la chaîne de commande, par exemple PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin;/opt/homebrew/bin/openclaw gateway start, pour que Node et les utilitaires soient trouvés sans dépendre de ~/.zshrc. 4) Chargez avec launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/votre.openclaw.gateway.plist (adaptez le domaine si votre runbook diffère), puis confirmez via launchctl print gui/$(id -u)/votre.label que le job tourne. 5) Suivez le chemin de log documenté par votre build pendant une requête client unique ; corrigez PATH ou jeton avant d’ouvrir l’écoute sur une interface publique. Si Node, navigateurs automatisés et caches tournent en continu, prévoyez une marge RAM/SSD confortable sur le M4 pour éviter le swap nocturne qui fausse les sondes de santé.
ssh -N -L 18789:127.0.0.1:18789 -i ~/.ssh/id_ed25519 [email protected]
Tableau de dépannage : symptôme → cause probable → premier correctif
| Symptôme | Cause probable | Premier correctif |
|---|---|---|
| Fonctionne dans le shell SSH, échoue après reboot | PATH ou jeton uniquement dans le profil interactif |
Chemins absolus + EnvironmentVariables dans le plist ; recharger le LaunchAgent |
| Tunnel actif, le client subit des réinitialisations | Timeout SSH idle ou keepalive TCP absent | ServerAliveInterval dans la config SSH ; ou migration vers passerelle directe |
Mode direct : réponse 401 du Gateway |
Décalage sur gateway.remote.token ou mauvais en-tête |
Aligner le jeton côté client et serveur ; rotation si fuite |
EADDRINUSE sur 18789 |
Double instance du Gateway ou processus Node orphelin | openclaw gateway stop ; lsof ; retirer le plist en double |
Connection refused sur IP publique |
Écoute toujours sur 127.0.0.1 uniquement |
Ajouter un reverse proxy ou ajuster le bind selon la doc fournisseur ; ne pas exposer brutalement le port |
Synthèse
Sur une pile OpenClaw 2026 au Canada, choisissez le tunnel SSH lorsque vous avez besoin d’un tuyau temporaire et sûr vers 127.0.0.1:18789, puis migrez vers la passerelle directe avec jetons et politique réseau explicites lorsque l’automatisation doit survivre aux veilles, reboots et appelants multiples. Injectez gateway.remote.token dans le même contexte que launchd, gardez le PATH explicite et absolu, et traitez le tableau ci-dessus comme la première page de votre runbook d’astreinte.