Lorsque votre passerelle OpenClaw ne tourne que sur un Mac mini M4 loué au Canada et que des collègues en APAC veulent faire rejoindre des iPhone, iPad ou appareils Android en tant que nœuds (role: node), la question n’est pas de savoir si l’application mobile s’installe — c’est de savoir si le WebSocket du téléphone atteint un point de terminaison wss:// conforme sur un hôte toujours en ligne, et si les opérateurs alignent l’approbation CLI avec gateway.mode: "remote". Cette page est un runbook d’appairage de nœuds piloté par la passerelle pour 2026. Pour les clients macOS barre de menu, les favoris Dashboard et 18789 via SSH/Tailnet, lisez OpenClaw 2026 : passerelle unique au Canada sur Mac M4 — SSH, tailnet, Dashboard, 18789, jetons équipe, loopback, LaunchAgent — cet article câble les opérateurs ; celui-ci câble les téléphones. Si la passerelle n’est pas encore installée, terminez d’abord OpenClaw 2026 sur Mac distant : installation, déploiement et dépannage — openclaw onboard, démon Gateway et planification des ressources M4 Canada.
Pourquoi un M4 Canada doit être la seule passerelle pour les nœuds mobiles
Dans le modèle distant OpenClaw, chaque hôte ne doit exécuter qu’un processus Gateway sauf si vous isolez volontairement des profils. La passerelle possède les sessions, les canaux, l’auth et l’état agent ; les apps iOS/Android n’hébergent pas de Gateway — elles se connectent en nœuds périphériques via le WebSocket Gateway et échangent des RPC node.*. Un Mac mini M4 loué au Canada correspond au rôle « toujours en ligne » : les portables dorment, mais les files d’appairage Telegram/Slack et les canaux ne devraient pas s’arrêter. Les téléphones fournissent caméra, capteurs ou actions terrain ; le M4 fournit la continuité.
Le mode d’échec classique des équipes transpacifiques est de monter une deuxième Gateway sur un portable APAC, ce qui divise les jetons, laisse expirer les demandes d’appairage sur le mauvais hôte et rend openclaw nodes pending vide pendant que le téléphone tourne. Le correctif : une Gateway Canada + chaque CLI et nœud en remote, avec le personnel APAC qui administre l’hôte via SSH ou tailnet plutôt qu’une Gateway locale.
Appairage possédé par la passerelle en 2026 (ce qui a changé)
Depuis le modèle gateway-owned pairing, la Gateway est la source de vérité pour les nœuds autorisés. Le flux : le nœud se connecte en WebSocket → la Gateway stocke une demande pending et émet node.pair.requested → l’opérateur exécute openclaw nodes approve <requestId> (ou l’UI équivalente) → la Gateway délivre un jeton → le nœud se reconnecte en appairé. Les entrées pending expirent après cinq minutes ; regénérez QR ou codes de configuration plutôt que de poursuivre des demandes périmées.
Depuis le 31 mars 2026, les commandes nœud restent désactivées tant que l’appairage nœud n’est pas approuvé — l’appairage appareil seul ne suffit pas pour exposer les commandes nœud déclarées. Traitez openclaw devices approve et openclaw nodes approve comme des portes liées mais distinctes : les téléphones peuvent apparaître dans les listes appareils alors que le RPC nœud renvoie encore 1008: pairing required tant que le store nœud n’affiche pas approuvé. Si openclaw nodes pending reste vide après un scan, passez à une build qui écrit l’état d’appairage WebSocket dans le store nœud (correctifs 2026.2.28+ documentés en amont) avant d’ouvrir un ticket réseau.
Côté protocole, les opérateurs interagissent avec node.pair.list, node.pair.approve et node.pair.reject via les wrappers CLI ci-dessus ; les UI sont des clients fins sur la même vérité Gateway. Cela compte pour l’audit : le journal d’appairage de l’hôte Canada est faisant foi, pas le dernier portable ayant ouvert l’app mobile.
gateway.mode remote et priorité des identifiants
Sur l’hôte Canada, la Gateway doit écouter sur 127.0.0.1:18789 (confirmez le défaut de votre build ; documentez un port pour l’équipe). Sur les portables opérateur APAC, définissez gateway.mode: "remote" pour que openclaw health, openclaw nodes pending et les commandes approve ciblent le Canada via SSH ou Tailscale, pas un port local vide.
Guide distant officiel : lorsque la Gateway est loopback uniquement, gardez gateway.remote.url sur ws://127.0.0.1:18789 et établissez le forwarding SSH local avant la CLI. Pour un accès tailnet direct, utilisez transport: "direct" avec une URL privée ws:// ou wss://. Règle critique : --url ne réutilise pas implicitement le jeton de config — passez --token ou --password explicitement en surchargeant l’URL.
{
gateway: {
mode: "remote",
remote: {
url: "ws://127.0.0.1:18789",
token: "<gateway-token>",
sshTarget: "ca-m4-gateway",
},
},
}
{
gateway: {
mode: "remote",
remote: {
transport: "direct",
url: "wss://ca-m4.votre-tailnet.ts.net",
token: "<gateway-token>",
},
},
}
| Source d’identifiant | Priorité | Erreur typique |
|---|---|---|
CLI --token / --password |
La plus haute si fourni | Supposer que --url reprend le jeton config |
Env OPENCLAW_GATEWAY_TOKEN |
Override fichier pour un shell | LaunchAgent sans le même env que SSH |
gateway.remote.token en config |
Défaut mode remote | Jeton roté sur l’hôte mais pas sur les téléphones |
| Profil « Remote » app macOS | Store UI séparé | CLI verte alors que l’app garde l’ancien jeton |
Runbook d’appairage : loopback verte jusqu’à nodes approve
Supposez la Gateway déjà gérée par launchd sur le M4 Canada. Ne pointez pas les téléphones vers un ws:// public en clair si une étape ci-dessous échoue.
Étape 1 — Santé loopback sur l’hôte Gateway
SSH vers le Mac Canada et vérifiez l’écoute + santé :
curl -fsS "http://127.0.0.1:18789/health" && echo OK lsof -nP -iTCP:18789 -sTCP:LISTEN
Étape 2 — Entrée WebSocket sécurisée pour les téléphones
Pour l’appairage mobile inter-réseau, iOS/Android refusent le ws:// en clair. Exposez du TLS réel en wss://<magicdns> via Tailscale Serve (préféré tant que la Gateway reste sur loopback) ou un reverse proxy d’entreprise avec chaîne de certificats de confiance. Le débogage LAN bureau peut utiliser ws:// ; les téléphones transpacifiques sur Internet public, non.
Étape 3 — QR / code de configuration et node pending
Sur l’hôte (ou sur un portable avec tunnel actif) :
openclaw qr openclaw qr --remote openclaw nodes pending openclaw nodes approve <requestId> openclaw nodes status
Après le scan du téléphone, confirmez que la ligne pending apparaît avant approbation. Liez les approbations aux ID de ticket dans la doc d’astreinte pour que les prestataires de minuit n’approuvent pas des empreintes inconnues.
Étape 4 — Test fumée RPC nœud
Déclenchez un appel node.* minimal côté Gateway (ou un workflow canal qui exige des outils nœud). Un RTT Pacifique élevé seul n’est pas un échec ; des déconnexions fréquentes pointent vers le chemin tailnet, MTU ou économie d’énergie du téléphone — pas forcément une réinstallation de l’app.
Matrice de décision d’entrée sécurisée (téléphones vs opérateurs)
Les téléphones n’ont pas de tunnel SSH ; les opérateurs souvent oui. Séparez ces chemins dans les runbooks.
| Type d’entrée | Protocole téléphone | Usage typique | Risque |
|---|---|---|---|
LAN ws://192.168.x.x:18789 |
ws en clair (LAN privé) | Débogage Wi-Fi bureau | Pas pour Internet transpacifique public |
Tailscale Serve wss://*.ts.net |
wss + identité tailnet | Téléphones APAC + Gateway Canada | Revue ACL à chaque embauche ; hôte de confiance |
| wss proxy CA privée / entreprise | wss + jeton porteur | Politiques d’épinglage certificat | iOS exige CA de confiance ou config pin |
IP publique ws:// |
Appairage distant refusé | — | Fail-closed par conception ; ne pas exposer 18789 brut |
-L, favoris tailnet) est dans le tutoriel passerelle unique SSH/Tailnet. Cet article couvre l’appairage wss des nœuds mobiles et nodes approve — ne réutilisez pas le même ordre d’acceptation (« ouvrir Dashboard d’abord ») pour les tickets d’appairage mobile.
SSH transpacifique : approuver des nœuds quand les téléphones ne sont pas encore sur le tailnet
Les téléphones de prestataires qui ne peuvent pas s’inscrire à Tailscale ont toujours besoin d’un point de terminaison wss:// (Serve ou proxy d’entreprise). SSH aide les opérateurs à lancer approve sur loopback après tunnel — il ne remplace pas le chemin TLS du téléphone.
ssh -N -L 18789:127.0.0.1:18789 user@ca-m4-host # Nouveau terminal : config remote pointe vers ws://127.0.0.1:18789 openclaw health --token "<gateway-token>" openclaw nodes pending openclaw nodes approve <requestId>
Pour des tunnels 24/7, persistez ssh -N dans un LaunchAgent sur le Mac opérateur et stockez gateway.remote.token en config, pas dans les profils shell. L’hôte Canada garde la Gateway en loopback uniquement. Pour l’installation initiale et les chemins Homebrew/npm, voir aussi OpenClaw 2026 sur Mac distant : chemins d’installation pour install.sh, Homebrew et npm — planification du Gateway 18789 sur nœud M4 Canada.
| Rôle | Chemin recommandé | Commandes d’appairage | Si échec, vérifier |
|---|---|---|---|
| M4 Canada (Gateway) | loopback + launchd | openclaw qr, nodes pending |
lsof -i :18789, journaux Gateway |
| Mac opérateur APAC | SSH -L + mode remote |
nodes approve, doctor |
Tunnel vivant ? Jeton explicite ? |
| iOS / Android | wss:// tailnet ou Serve |
Scan app, badge nœud en ligne | ws public mal utilisé, confiance cert |
Capacité M4 : une Gateway, plusieurs nœuds téléphone
Un M4 Canada 24 Go / 512 Go héberge confortablement une Gateway plus plusieurs nœuds appairés si canaux et instantanés workspace sont bornés. Ajoutez 1 To / 2 To quand rétention de journaux, médias de canaux et exports workspace concurrencent l’APFS. Un second M4 loué se justifie pour des profils Gateway isolés (nœuds prod vs staging), pas parce que trois téléphones « saturent » un hôte Apple Silicon — les téléphones partagent sessions et quotas, ils ne dupliquent pas le processus Gateway.
Étiquetez chaque appareil approuvé dans votre CMDB ; l’appairage sans propriétaire devient inauditable entre fuseaux. Pour disque et extension parallèle quand les canaux grossissent, voir OpenClaw 2026 Canada M4 : disque nœud prod, renouvellement canaux et FAQ Gateway. Pour les mises à niveau maîtrisées et sondes santé, croisez avec OpenClaw 2026 : mise à niveau maîtrisée et exploitation stable sur Mac distant M4 au Canada.
Playbook de tickets openclaw doctor
Traitez openclaw doctor (et --lint / --deep si disponibles) comme le snapshot unique des tickets : exécutez sur la session SSH de l’hôte Gateway et à nouveau depuis une CLI remote tunnelée ; comparez les sorties. Doctor verte mais téléphone encore pending signifie en général pas de nodes approve ou mauvais hôte wss ciblé par le téléphone. Erreurs auth doctor = surfaces de jeton mélangées local/remote.
Champs de ticket suggérés
Joignez : horodatage UTC, openclaw --version, curl santé Gateway, openclaw nodes pending / nodes status expurgés, texte d’erreur téléphone (secure endpoint required ?), et si Serve vs SSH seul vs tailnet direct est en jeu. Le VNC est rare sauf débogage TCC macOS pour outils caméra nœud.
Arbre symptôme → action
A. Téléphone exige un point de terminaison sécurisé → configurez wss:// (Tailscale Serve d’abord) ; arrêtez de publier du ws en clair sur IP publique.
B. Pending vide mais téléphone tourne → QR expiré, mauvais hôte Gateway, ou bug appairage WebSocket corrigé en 2026.2.28+ (mettez à niveau avant debug profond).
C. CLI connection refused → vérifiez loopback Canada, puis lsof -i :18789 sur le portable pendant le forward SSH.
D. Approuvé puis chute immédiate → ACL tailnet, économiseur batterie téléphone, OOM Gateway ; capturez la version avant redémarrage.
openclaw doctor openclaw doctor --lint openclaw gateway status openclaw nodes pending openclaw nodes status curl -fsS "http://127.0.0.1:18789/health" || true
Cas d’usage : téléphone d’astreinte APAC déclenche l’automation Canada
Un ingénieur d’astreinte à Singapour appaire un nœud iPhone à la Gateway Canada via wss://ca-m4.equipe.ts.net. Une commande slash Slack routée via les canaux OpenClaw demande un instantané caméra via RPC node.* ; la Gateway orchestre sur le M4 pendant que le téléphone fournit le capteur. La latence est dominée par le leg Pacifique, mais la Gateway reste debout quand le MacBook de l’ingénieur dort. Les approbations sont journalisées avec ID de ticket ; les jetons tournent trimestriellement sans reposter de secrets dans le chat.
Ce schéma ne fonctionne que si appairage, canaux et ACL tailnet sont portés par la même équipe plateforme. Si les canaux tournent déjà sur l’hôte Canada mais les téléphones n’ont jamais complété nodes approve, les opérateurs voient Slack sain alors que chaque outil nœud échoue en erreur d’appairage — un motif support fréquent que les snapshots doctor exposent vite quand vous joignez nodes status et santé canal dans un seul ticket.
FAQ
iOS ou Android peuvent-ils héberger la Gateway ?
Non. Les apps mobiles sont nœuds uniquement. Gardez le M4 Canada comme Gateway canonique sauf profils isolés volontaires sur un autre hôte.
Pourquoi wss est-il obligatoire pour l’appairage téléphone distant ?
L’appairage mobile inter-réseau refuse le ws:// en clair pour protéger identifiants et empreintes. LAN et exceptions simulateur documentées sont en amont.
gateway.mode remote change-t-il l’hôte Gateway lui-même ?
remote est un réglage client. Le Mac Canada exécute toujours une Gateway locale. Ne pointez pas la config du M4 en remote vers son propre loopback.
Tunnel SSH seul, pas de Tailscale sur le téléphone ?
Les téléphones ont toujours besoin d’un wss:// joignable (souvent Tailscale Serve ou proxy d’entreprise). SSH sert la CLI opérateur et approve ; il ne remplace pas le TLS pour le terminal.
openclaw qr vs openclaw qr --remote ?
--remote encode une configuration visant l’URL Gateway distante — utilisez sur une machine opérateur tunnelée ou joignable tailnet pour que le QR ne référence pas le loopback du portable par erreur.
Plusieurs téléphones « se disputent-ils » la Gateway ?
Ils partagent un processus Gateway et des quotas ; ils ne lancent pas de démons dupliqués. Étiquetez les appareils et tenez une piste d’audit d’approbation.
Appairage OK mais outils nœud en timeout ?
Séparez WebSocket vivant et RPC lent. Vérifiez CPU Gateway, disque et files de canaux avant de réinstaller les apps mobiles.
Doctor verte en SSH mais le téléphone échoue encore ?
Doctor peut valider le chemin tunnel alors que le téléphone utilise un autre hostname wss ou un QR expiré. Alignez l’URL wss du téléphone avec la config Serve et relancez nodes pending après scan.