Vous avez une Gateway stable sur un VPS ou Mac cloud, mais sur le portable openclaw affiche des outils inactifs ou des échecs de sonde RPC alors que les journaux serveur restent suspects de calme. Cet article s'adresse aux équipes qui traitent OpenClaw comme une passerelle de production : d'abord sept points de contrôle distinguent gateway.mode=remote, l'exposition Tailscale et le port forwarding SSH ; ensuite une matrice à quatre lignes aligne emplacement du processus, cible du client, TLS et validation des jetons ; enfin un runbook en six étapes (URL distante, wss, double gateway status, gateway install --force, doctor, sondes de santé), avec des liens vers les articles exposition privée Tailscale, dépannage d'installation multiplateforme et gateway closed(1000) pour garder chaque sujet dans le bon guide.
La FAQ officielle résume local / remote en quelques lignes, mais en production le temps part surtout en URL de sonde qui ne correspond pas au listener réel et sur des unités systemd utilisateur qui divergent des shells interactifs. Les sept éléments ci-dessous ramènent le débat de « j'ai un ping » vers une grille d'acceptation signable.
Confondre mode distant et alias de tunnel SSH : SSH -L corrige surtout le chemin navigateur vers l'UI ; le mode distant change la cible par défaut des sondes du CLI. Les deux se cumulent, mais la sémantique diffère.
Assimiler Tailscale Serve au mode distant : Tailscale rend la Gateway locale joignable sur le tailnet ; le mode distant fait parler le CLI portable avec une Gateway sur un autre hôte. Lisez le tableau des frontières dans l'article Tailscale.
Ne modifier que gateway.remote.url et oublier gateway.mode : si le mode reste local, le CLI peut continuer à sonder un port local vide et produire des timeouts « mystérieux ».
Mélanger http et wss : si le proxy inverse termine le TLS et que l'URL client ne colle pas à votre récit trusted-proxy, attendez-vous à des 401 ou des tempêtes de reconnexion ; passez la revue avec votre checklist durcissement.
Ignorer la paire Config (cli) / Config (service) : après upgrade on édite souvent en root alors que le service tourne sous --profile dev avec un autre répertoire d'état.
Ne noter le jeton que d'un côté : la Gateway a fait tourner gateway.auth.token mais l'UI Control du portable garde l'ancienne valeur en cache ; croisez avec le tableau des jetons dans gateway closed(1000).
Sans cas d'acceptation distant minimal : tester le chat sans la chaîne d'outils masque la dérive des scopes RPC jusqu'à un upgrade modèle ; figez une commande en lecture seule comme canari.
La cause racine commune est de traiter OpenClaw comme une application web monolithique plutôt que comme un système à deux bouts avec superviseur local et routage de session distant. L'équipe plateforme doit tenir un registre auditable de profil, répertoire d'état, URL distante et fenêtre de rotation par poste développeur, comme pour les contextes kubeconfig.
Enchaînez avec le dépannage d'installation multiplateforme : si openclaw doctor n'a jamais été vert à l'installation, ne basculez pas précipitamment en distant sinon chaque ticket mélange « install cassée » et « mauvaise instance ».
Si votre organisation standardise en 2026 « Gateway dans le nuage, IDE sur portable », documentez la dégradation hors ligne : le CLI peut-il retomber en lecture seule, interdit-on les bascules de mode implicites pour éviter une accroche production accidentelle.
Avec un Mac distant dédié, un schéma fréquent est Gateway sur VPS Linux et exécution des outils sur un nœud macOS loué : l'URL distante pointe toujours vers le VPS. Ne collez pas l'adresse SSH vers le Mac comme URL Gateway sauf si une seconde Gateway tourne réellement sur ce Mac.
Enfin, les proxys d'entreprise qui coupent les WebSocket longue durée amplifient les déconnexions intermittentes : inscrivez heartbeat, reconnexion et purge de cache client dans le runbook plutôt que d'accuser le modèle de perdre en qualité.
En revue, coupez sur l'emplacement du processus et la cible par défaut du client pour aligner rapidement sécurité et ownership opérationnel.
| Mode | Où tourne Gateway | Clients typiques | Risques principaux |
|---|---|---|---|
| local (défaut) | Cette machine | CLI / UI locales | Ports locaux, jetons, sessions personnelles entremêlées |
| remote | Hôte distant | CLI / UI locales visant wss://… | Dérive d'URL, double configuration, coupures proxy |
| Exposition Tailscale / tunnel | Toujours loopback ou bind sur la cible | Navigateur ou CLI après chemin tailnet/tunnel | ACL, MagicDNS, combinaison jeton et bind |
| Forward local SSH | Hôte cible | Mappe le port distant sur 127.0.0.1 du portable | Durée de session, droits bastion, mauvaise concaténation avec l'URL distante |
Le mode distant règle le pointage du plan de contrôle : le même CLI sur un portable dialogue de façon fiable avec le superviseur et le registre d'outils sur une autre machine. Il ne remplace ni TLS ni le modèle de jetons à lui seul.
Quand il faut à la fois une Gateway 7j/7 en datacenter ou VPS et des ingénieurs qui ne portent qu'un CLI léger, le mode distant est un défaut raisonnable. Si vous avez aussi besoin d'un accès zero trust à l'UI, superposez Tailscale Serve sur l'hôte distant plutôt que de fusionner les deux besoins en un seul interrupteur.
Croisez avec l'article RPC / 1000 : en mode distant, confirmez quelle instance de Gateway utilise réellement la session CLI avant de débattre scopes et listes blanches d'outils, sinon vous modifiez toujours le mauvais hôte.
L'ordre ci-dessous insiste sur « valider l'hôte distant, puis le mode client, puis une commande canari », aligné sur le guide de dépannage amont.
Sur l'hôte distant, en tant qu'utilisateur du service : lancez openclaw gateway status et vérifiez Runtime: running avec sondes RPC saines.
Consignez l'URL WebSocket distante et le point de terminaison TLS : avec proxy inverse, documentez préfixes de chemin et URL de health-check pour éviter une couche de path tapée à la main.
Sur le portable, sauvegardez le profil courant : exportez openclaw.json ou le chemin d'état équivalent pour revenir à local en une étape.
Définissez gateway.mode=remote et gateway.remote.url : via openclaw config set officiel ou modèle contrôlé ; interdisez les retouches éparses.
Exécutez openclaw status / openclaw health : contrôlez cibles de sonde et latence ; si double config diverge, passez à l'étape suivante.
Dans le même contexte que le service, openclaw gateway install --force puis openclaw gateway restart : uniquement si vous maintenez réellement un service local ; les clients purement distants peuvent sauter install et s'appuyer sur doctor pour effacer la dérive.
openclaw config set gateway.mode remote openclaw config set gateway.remote.url "wss://gateway.example.internal/v1/ws" openclaw config get gateway.mode openclaw config get gateway.remote.url openclaw status openclaw doctor
Astuce : si Tailscale Serve est aussi actif sur l'hôte distant, relisez les sections ACL et jetons dans exposition privée Tailscale pour que le point de terminaison wss corresponde au DNS interne.
Inscrivez le retour arrière dans le ticket de changement : snapshot de l'ancienne config local et fenêtre horaire ; les jours de release majeure, figez l'URL distante jusqu'à canari vert, puis poussez les configs client en masse.
Avec plusieurs profils (staging/prod), affichez OPENCLAW_PROFILE actif au démarrage du shell pour éviter l'illusion d'être sur staging alors qu'on est accroché à la prod.
Mapper les symptômes sur les couches client, passerelle et proxy réduit les redémarrages inutiles.
401 / non autorisé : alignez d'abord les jetons entre Control UI et CLI ; en mode distant le portable garde souvent un jeton d'appareil obsolète, suivez la rotation officielle ou la ré-autorisation.
Runtime running mais RPC probe failed : comparez avec gateway closed(1000) pour séparer mauvaise instance et bonne instance au scope insuffisant ; capturez openclaw logs --follow sur l'hôte distant sur la même fenêtre temporelle.
Attention : sans adresse d'écoute distante confirmée, ne martelez pas gateway restart sur le portable : cela ne fait tourner qu'un processus local inutile et salit les journaux de triage.
Ça marchait hier après upgrade : vérifiez les notes de version pour durcissement d'auth par défaut ou changement de chemin WebSocket ; consignez versions distantes et clientes ainsi que digests dans le ticket plutôt que de n'upgrader qu'un côté.
Par rapport au silence de type canal, les soucis de mode distant sont plutôt couche connexion et session ; si vous suspectez le flux de messages, lisez l'article sur les sondes canaux au lieu de bricoler l'URL distante.
Pour les équipes 24/7, exportez taux d'échec des sondes et intervalle de reconnexion vers votre observabilité : même si OpenClaw est sain, le jitter réseau d'entreprise doit être visible.
Les puces ci-dessous servent d'alignement interne ; ajustez les seuils à votre volumétrie et vos régions.
wss doivent être localisables en 60 secondes par couches (DNS, TCP, TLS, WSS).Config (cli) et Config (service) divergent, chemin par défaut même utilisateur install --force, restart, doctor et journaliser le répertoire d'état.Une Gateway sur portable en veille se bat avec les applis de visioconférence pour les ports ; un CLI purement distant sans plan de contrôle stablement joignable tombe en masse lors des à-coups VPN. Placer la Gateway sur un Mac cloud ou VPS dédié, toujours allumé et maintenable en SSH, tout en standardisant les portables comme clients distants, est le compromis 2026 le plus courant. Par rapport à coincer le superviseur dans des conteneurs instables ou une virtualisation opaque, la location cloud de Mac Mini NodeMini offre des baselines SSH plus lisibles, des paliers prévisibles et des images de nœud reproductibles pour gouverner OpenClaw comme infrastructure de prod. Pour comparer fiches et tarifs, commencez par les tarifs de location Mac Mini et le centre d'aide pour l'onboarding. Parcourez les autres billets OpenClaw via le filtre catégorie OpenClaw.
Au déploiement, rattachez ce runbook aux niveaux d'environnement internes : dev, préprod et prod ont chacun une URL distante et un rythme de rotation des jetons ; ne copiez jamais à la main une URL de prod dans un profil personnel.
Le mode distant fait joindre le CLI à une Gateway sur une autre machine. Tailscale répond surtout à la question d'exposer en sécurité sur le tailnet une Gateway qui écoute déjà localement. Les deux se combinent. Autres sujets OpenClaw : filtre OpenClaw du blog.
Sous le même utilisateur et le même répertoire d'état que le service, exécutez openclaw gateway install --force puis redémarrage, puis openclaw doctor. Pour nœuds et facturation, voir le centre d'aide.
Variables d'environnement, restes dans les profils shell, et si gateway.mode reste local. Pour garder la Gateway en permanence dans le nuage, comparez les paliers sur les tarifs de location Mac Mini.