En 2026, certaines équipes imposent volontairement une seule région pour la passerelle OpenClaw : un Mac mini M4 loué au Canada, traité comme plan de contrôle canonique pour l’Amérique du Nord, tandis que des ingénieurs à Tokyo, Singapour ou en Californie se connectent depuis des portables macOS. La contrainte paraît simple jusqu’à ce qu’il faille ouvrir le Dashboard, garder cohérent le listener TCP 18789 avec les sondes de santé, et expliquer à la finance pourquoi trois personnes partagent le même gateway.remote.token sans le coller dans Slack. Ce billet est un tutoriel linéaire : comment enfiler l’accès Remote via SSH et via un tailnet Tailscale, comment ces choix interagissent avec une posture loopback d’abord, et comment persister la passerelle sous un LaunchAgent utilisateur pour que les redémarrages ne rendent pas caduque la preuve de fonctionnement de la veille. Pour le socle d’installation (Homebrew, Docker, chemins) et les arbitrages transpacifiques sur le disque workspace, croisez avec OpenClaw 2026 sur un Mac mini M4 distant au Canada : Docker hébergé contre install.sh / Homebrew natifs — comment trancher pour payer moins de collaboration transpacifique en temps humain, sécuriser le Gateway TCP 18789, surveiller le workspace au fil de l’eau disque, et piloter une extension parallèle (HowTo + FAQ). Si vous migrez un nœud existant plutôt que du neuf, alignez les phases de bascule sur OpenClaw 2026 : migrer d'un Mac local ou d'un ancien nœud vers un Mac M4 distant au Canada — bascule stable du Gateway sur le port 18789, empaquetage du workspace, reconstruction LaunchDaemon, recette SSH/VNC transpacifique et plan de retour arrière.
Pourquoi « Canada seul » change l’histoire réseau
Lorsque le produit et la sécurité exigent qu’aucune passerelle secondaire ne tourne en APAC pour des raisons de coût ou de résidence des données, chaque ingénieur macOS devient opérateur distant d’une machine qui dort dans un fuseau juridique différent. Le processus passerelle a toujours besoin d’un DNS prévisible pour les canaux, d’un disque stable pour les instantanés de workspace, et d’une matrice d’écoute que les auditeurs peuvent imprimer. Concrètement, documentez trois adresses : l’IPv4 routable du fournisseur (SSH, partage d’écran, synchronisation de gros fichiers), l’adresse Tailscale 100.x dans votre tailnet, et 127.0.0.1 sur l’hôte lui-même, là où OpenClaw préfère se lier tant que vous n’élargissez pas volontairement. Mélanger ces adresses sans tableau de correspondance produit le classique « ça marche sur mon tunnel » pendant qu’un collègue à Singapour voit des 502 intermittents sur le Dashboard parce que son navigateur pointe encore vers un port transféré la veille.
Le mode « Canada seul » recadre aussi l’acceptation de latence. Le SSH transpacifique reste utilisable pour le shell et scp, mais traîner des artefacts multi-gigaoctets pousse les équipes vers rsync sur tailnet ou un stockage objet proche du Mac. Le canal de contrôle passerelle, lui, reste modeste : keepalives, messages JSON, flux de journaux occasionnels. C’est pourquoi beaucoup de boutiques gardent 18789 sur loopback et le transfèrent, tout en déplaçant le gros débit ailleurs. Les sections suivantes détaillent deux chemins clients qui respectent cette posture.
Voie A : SSH LocalForward pour le break-glass et le débogage solo
Le port forwarding SSH local mappe un port de votre portable vers un port de l’hôte distant dans le tunnel chiffré SSH. Le motif canonique reste ssh -N -L 18789:127.0.0.1:18789 utilisateur@mac-canada, avec en option -L 9234:127.0.0.1:9234 si votre serveur de développement Dashboard écoute aussi en local pendant les mises à jour. Sur le portable vous pointez alors le client OpenClaw macOS ou un navigateur vers http://127.0.0.1:18789 (ou la variante HTTPS documentée par votre build) et le trafic termine sur la boucle locale du Mac Canada comme si vous étiez à la console. Forces : pas de SKU VPN supplémentaire, compatibilité avec la plupart des Wi-Fi d’hôtel, passerelle invisible depuis Internet public si le démon n’écoute que 127.0.0.1. Faiblesses : le tunnel meurt quand le portable dort, le réglage ServerAliveInterval devient une norme culturelle, et vous ne partagez pas un tunnel entre cinq collègues sans accepter un motif bastion.
Configuration SSH qui survit aux longues sessions transpacifiques
Encouragez les ingénieurs à figer les hôtes dans ~/.ssh/config avec Host hashvps-canada-gateway, Hostname, User, IdentityFile, ServerAliveInterval 30, ServerAliveCountMax 6, et ExitOnForwardFailure yes pour qu’un forward cassé échoue vite plutôt qu’à demi ouvert. N’activez ControlMaster auto que si vous maîtrisez le multiplexage de connexions ; sinon restez simple. Documentez que les actifs du Dashboard peuvent supposer des upgrades WebSocket ; les proxies HTTP d’entreprise côté client cassent encore ces flux même lorsque le port 22 est autorisé.
ssh -N -L 18789:127.0.0.1:18789 -i ~/.ssh/id_ed25519 vous@votre-mac-canada.exemple
Voie B : tailnet Tailscale pour un accès équipe permanent
Tailscale construit un tailnet privé où chaque machine approuvée reçoit une adresse 100.x stable et des routes de sous-réseau optionnelles. Installez Tailscale sur le Mac Canada et sur chaque portable opérateur, approuvez les machines dans la console d’administration, et vous joignez l’adresse tailscale ip -4 du serveur depuis Singapour sans ouvrir SSH au monde entier. Pour OpenClaw, on lie souvent encore la passerelle à 127.0.0.1:18789 et l’on place soit une session SSH dans le tailnet, soit un petit reverse proxy local qui écoute sur l’IP tailnet et transfère vers la boucle locale ; d’autres équipes lient la passerelle à l’IP tailnet après durcissement des contrôles de jeton, ce qui déplace le modèle de menace vers « pair tailnet compromis » plutôt que « détenteur de clé SSH compromis ». Il n’y a pas de gagnant universel ; le tableau comparatif ci-dessous est le bloc à coller dans votre wiki d’onboarding.
Quand la finance demande pourquoi vous payez Tailscale et un fournisseur de cloud Mac, répondez par la réduction des tickets support : le tailnet supprime les casse-têtes de NAT en épinglage, fournit des noms MagicDNS alignés sur votre wiki interne, et permet de révoquer un portable perdu en secondes sans faire tourner le mot de passe racine du fournisseur. Pour les intégrations SaaS en liste blanche, reliez les sorties aux attentes d’IP native documentées par votre bailleur afin que les webhooks sortants conservent une IPv4 stable même lorsque le trafic de contrôle transite par le maillage.
/ sur 18789 est la page marketing.
Câbler le Dashboard et 18789 de bout en bout
Commencez sur l’hôte Canada lui-même. Exécutez curl -fsS http://127.0.0.1:18789/health (ou le chemin de santé documenté) avant d’impliquer les portables. Si cela échoue, aucune édition d’ACL Tailscale ne sauvera la situation. Une fois la santé loopback verte, superposez le chemin client : pour SSH, validez le forward avec nc -vz 127.0.0.1 18789 sur le portable tant que le tunnel est actif ; pour Tailscale, répétez le test contre l’adresse 100.x du Mac ou le nom MagicDNS. Ouvrez ensuite l’URL du Dashboard dans Safari ou Chrome. Capturez captures d’écran de la chaîne de version passerelle et du hash de build pour votre journal de changement ; les équipes transpacifiques dépannent plus vite lorsque chacun colle les mêmes deux lignes dans le canal d’incident.
Si vous exposez une écoute hors loopback pour un accès tailnet direct, relancez lsof -nP -iTCP:18789 -sTCP:LISTEN après chaque reboot et après un brew upgrade qui tire un nouveau runtime Node. Les doubles écoutes signifient généralement à la fois un openclaw gateway start manuel oublié dans un tmux et un LaunchAgent qui revendique la même famille d’étiquettes. Arrêtez les instances en trop, puis consolidez sous un seul plist pour que les métriques et la rotation des journaux restent attachées à un seul arbre de PID.
Tableau : SSH forward, tailnet direct, loopback seul
| Mode | Idéal pour | Visibilité de 18789 | Caveats opérationnels |
|---|---|---|---|
SSH LocalForward |
Astreinte break-glass, prestataires sans siège tailnet | Uniquement sur le loopback du portable via tunnel | Cycle de vie lié au sommeil du portable ; former sur ServerAliveInterval |
| Tailscale vers IP tailnet + proxy vers loopback | Équipes distribuées, CI depuis des pairs tailnet | Joignable sur 100.x (ou localhost d’un routeur de sous-réseau) | Les revues d’ACL deviennent partie intégrante de chaque embauche ; étiqueter les appareils par rôle |
| Loopback seul + console physique / fournisseur | Verrouillage maximal pendant la stabilisation des mises à jour | 127.0.0.1 sur le Mac Canada uniquement |
Nécessite un bureau à distance hors bande ou une console série fournisseur pour les réparations |
| Bind routable public (défaut déconseillé) | Intégrations héritées sans chemin VPN | Exposé à Internet sauf pare-feu strict | Rotation de jetons obligatoire, WAF ou liste blanche IP, journalisation d’audit |
Gouvernance transpacifique du gateway.remote.token
Les secrets partagés à travers les océans pourrissent plus vite que dans un seul bureau : les portables franchissent des frontières, les captures d’écran fuient dans des decks PowerPoint, et les prestataires tournent chaque semaine. Traitez gateway.remote.token comme un mot de passe de base de production : stockez-le dans le coffre-fort d’entreprise (1Password, Vault, fichier soutenu par un KMS), injectez-le au déploiement dans le dictionnaire EnvironmentVariables du plist ou le fichier de configuration que le démon lit, et interdisez le collage dans le chat. Pour la rotation, mettez en scène deux jetons pendant la fenêtre de recouvrement : la passerelle accepte les deux pendant une durée définie, vous mettez à jour les clients continent par continent, puis vous retirez l’ancienne valeur. Documentez la minute exacte où le jeton hérité disparaît pour que l’équipe APAC n’interprète pas un refus d’accès comme un rollback silencieux.
Comme les LaunchAgents macOS s’exécutent dans le domaine utilisateur graphique, assurez-vous que l’export du coffre atterrit dans un chemin lisible uniquement par l’UID de ce compte ; évitez les dépôts world-readable dans /tmp. Si la conformité impose des identifiants par ingénieur plutôt qu’un jeton d’équipe unique, évaluez si votre build OpenClaw supporte des clés par client ; sinon segmentez par étiquettes tailnet pour que seul le tag role:gateway-client atteigne le port 18789 au niveau réseau même lorsque la couche application continue de vérifier un jeton porteur.
LaunchAgent et persistance de la passerelle (domaine utilisateur)
Les LaunchAgents se chargent dans le domaine launchd par utilisateur (gui/$uid) et restent le défaut raisonnable lorsque la passerelle OpenClaw doit démarrer à la connexion du compte principal du Mac loué, sans exiger de LaunchDaemons root. Créez ~/Library/LaunchAgents/com.openclaw.gateway.plist avec une étiquette DNS inverse unique, des chemins absolus dans ProgramArguments, des EnvironmentVariables explicites pour PATH et les clés de jeton, ainsi que StandardOutPath / StandardErrorPath sous ~/Library/Logs/ pour que le support puisse suivre à distance via SSH. Après édition, enchaînez launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist puis launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist sur macOS Ventura et plus récent (les systèmes plus anciens utilisaient unload/load). Validez avec launchctl print gui/$(id -u)/com.openclaw.gateway et confirmez que le processus hérite du même environnement qu’un outil non interactif verrait ; les shells interactifs mentent.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.openclaw.gateway</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>/Users/votre-utilisateur-bail</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
<key>OPENCLAW_GATEWAY_TOKEN_FILE</key>
<string>/Users/votre-utilisateur-bail/.openclaw/gateway.token</string>
</dict>
<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/openclaw</string>
<string>gateway</string>
<string>start</string>
</array>
<key>StandardOutPath</key>
<string>/Users/votre-utilisateur-bail/Library/Logs/openclaw-gateway.log</string>
<key>StandardErrorPath</key>
<string>/Users/votre-utilisateur-bail/Library/Logs/openclaw-gateway.err.log</string>
</dict>
</plist>
Ce plist est illustratif : substituez le vrai emplacement du CLI issu de which openclaw, alignez les verbes d’arguments sur votre version installée d’OpenClaw, et préférez lire le jeton depuis un fichier utilisateur ou root-owned plutôt que d’embarquer le secret en clair. Si votre fournisseur redémarre l’instance pour maintenance, RunAtLoad ramène la passerelle sans attendre qu’on ouvre Terminal en VNC. Couplez l’agent à une sonde HTTP synthétique légère depuis une CI dans chaque géographie pour détecter les régressions de routage régional avant la mêlée du lundi matin. Pour les équipes qui enchaînent plusieurs fuseaux sur un même bail, reliez la discipline de passation à Équipes APAC 2026 (quatre zones) et Mac distant Canada en « suivre le soleil » : nœud nord-américain de nuit, M4 16 Go / 256 Go vs 24 Go / 512 Go, extensions 1 To / 2 To et sièges parallèles — checklist de passation, matrice et FAQ.
Matrice de vérification avant de déclarer la bascule « terminée »
| Contrôle | Commande ou action | Critère de réussite |
|---|---|---|
| Santé loopback | curl sur l’URL de santé depuis SSH sur l’hôte Canada |
HTTP 200, JSON de version aligné sur les notes de version |
| Écoute unique | lsof -nP -iTCP:18789 -sTCP:LISTEN |
Exactement un PID propriétaire après reboot |
| Chemin SSH forward | Forward + nc depuis le portable |
Connexion TCP réussie en moins de 2 s, Dashboard se charge |
| Chemin tailnet | ping + même curl via 100.x ou MagicDNS |
Comportement identique au loopback modulo avertissements TLS |
| Environnement LaunchAgent | Script sonde non-login affichant la présence du fichier jeton | Chemin lisible, pas de Permission denied dans le journal stderr |
| Répétition générale de rotation | Fenêtre à double jeton sur Mac de staging | Aucun continent client ne perd l’accès pendant le recouvrement |
FAQ
Pourquoi garder 18789 sur loopback si Tailscale chiffre déjà ?
Défense en profondeur : un pair tailnet compromis ne doit pas obtenir immédiatement un listener en clair sur toutes les interfaces. Loopback plus proxy explicite ou ACL étiquetée réduit la surface d’explosion et colle aux exemples amont d’OpenClaw.
Faut-il laisser la connexion à distance SSH activée pour toujours ?
Si les forwards SSH font partie du chemin approuvé, oui pour ce workflow ; les boutiques tailnet-only désactivent parfois SSH au pare-feu fournisseur et s’appuient sur Tailscale SSH. Documentez une posture par environnement, pas deux au hasard.
LaunchAgent ou LaunchDaemon pour OpenClaw ?
Les LaunchAgents suivent la session utilisateur connectée ; les LaunchDaemon tournent root tôt au boot. Choisissez LaunchAgent lorsque le compte de bail possède le workspace et que vous voulez des motifs d’accès au trousseau proches d’un utilisateur humain principal. Passez en LaunchDaemon lorsque la politique impose des services root et une journalisation centralisée.
Le Dashboard se charge mais les WebSockets échouent : pourquoi ?
Inspectez reverse proxies et inspection SSL d’entreprise. Les WebSockets exigent une compatibilité de bout en bout ; les chemins tailnet passent souvent là où les VPN split-tunnel échouent. Vérifiez aussi les règles de contenu mixte si le Dashboard est en HTTPS tandis que 18789 reste HTTP en local.
Comment des ingénieurs APAC « partagent » légalement un tunnel SSH ?
Ils ne le devraient pas. Utilisez un bastion partagé ou le tailnet ; les forwards personnels servent au débogage individuel. Partager des tunnels multiplie la dette de révocation.
Que se passe-t-il si le Mac Canada redémarre pendant une rotation de jeton ?
Le LaunchAgent doit redémarrer avec le nouveau fichier jeton ; si le plist référence encore d’anciennes variables d’environnement, la passerelle sort avec une erreur d’authentification lisible dans les journaux. Gardez les deux jetons actifs jusqu’au premier redémarrage automatisé réussi en production.
Puis-je lier le Dashboard à un port différent de 18789 ?
Certains builds autorisent des overrides via drapeaux de configuration ou variables d’environnement ; si vous changez les défauts, mettez à jour chaque ligne de runbook, chaque health check et chaque gabarit de scan de sécurité pour éviter que la moitié de l’équipe reste sur d’anciens favoris.