Vous faites tourner OpenClaw Gateway sur un VPS ou un serveur à la maison sans exposer le port 18789 sur Internet, tout en voulant que portable, autre machine Linux ou nœud mobile accèdent au CLI ou au WebSocket comme à un service interne. Cet article clarifie la topologie avec Tailscale et l’écoute loopback par défaut, les jetons et variables d’environnement, les chemins CLI distants, et le dépannage ciblé lorsque le tunnel est joignable mais que la session ou le RPC se comporte mal. Vous verrez comment cela se positionne par rapport à l’article Cloudflare Tunnel et systemd du site, et comment en charge lourde enchaîner naturellement avec un Mac distant dédié.
OpenClaw Gateway lie le plan de contrôle à 127.0.0.1 par défaut afin de réduire la surface d’attaque au périmètre que le système d’exploitation garantit déjà : seuls les processus locaux touchent directement le WebSocket ou le HTTP de contrôle. Beaucoup de premiers déploiements modifient l’écoute en 0.0.0.0 pour pouvoir lancer openclaw à distance, puis comblent avec des règles de pare-feu ; cela peut suffire en démo, mais en production cela agrège scans non autorisés, fuite de jeton et erreurs CORS.
Surface de scan : dès que le port est joignable depuis Internet, les balayages automatisés arrivent en quelques heures ; même avec un jeton fort, les journaux sont bruités et les alertes SOC difficiles à traiter.
Incohérence avec le durcissement : le guide « sécuriser le Gateway » du site insiste sur loopback, rotation des jetons et validation d’exécution ; ouvrir le bind sur toutes les interfaces annule la première barrière.
Signaux de dépannage pollués : sur le chemin public s’ajoutent CDN, NAT opérateur et proxy d’entreprise ; on attribue tort à OpenClaw des symptômes liés à half-close ou MTU.
Audit et conformité : tracer « quel humain depuis quelle IP publique a atteint le plan d’agent » est ardu ; l’identité tailnet (machine + ACL) se documente mieux.
Multi-Gateway : une seconde instance sur le même hôte augmente les risques de collision de port et de mélange de jetons.
Mac distant : le besoin durable de charge, c’est Xcode, simulateur et gros caches ; le Gateway reste léger et orchestre vers un nœud exclusif.
La bonne intuition : garder le Gateway en loopback et résoudre l’atteignabilité avec une couche réseau contrôlée (Tailscale, etc.), comme pour une base liée à 127.0.0.1 et atteinte par tunnel SSH. Si Cloudflare Tunnel vous est familier, comparez d’abord Linux VPS, systemd et Cloudflare Tunnel pour distinguer « entrée en périphérie » et « tailnet pur ».
| Axe | Loopback + Tailscale | Bind public nu | Cloudflare Tunnel |
|---|---|---|---|
| Confiance | Identité tailnet + ACL, réseau privé par défaut | Pare-feu + jeton, surface large | Identité en périphérie et identifiants de tunnel, entrée orientée Internet |
| Exploitation | Moyenne : ACL et noms d’hôte | Démarrage simple, risque long terme | Élevée : DNS, certificats, politique d’origine |
| Alignement avec OpenClaw | Fort : pas besoin de changer le bind | Faible : pousse souvent à ouvrir le bind | Moyen : le tunnel pointe vers le port loopback |
| Public type | Individu et petite équipe en réseau privé | Non recommandé en production | Entrée Internet contrôlée |
« Le tunnel règle le routage, pas l’authentification : jetons et validation d’exécution restent obligatoires. »
Tailscale place les machines dans un même domaine de confiance et offre des noms stables vers la plage 100.x ; cela ne remplace pas le jeton côté Gateway. Une ACL trop large (par ex. *:*) recrée un « petit Internet » à l’intérieur du tailnet.
En 2026 on croise souvent routeur de sous-réseau et nœud de sortie : le premier expose un segment LAN au tailnet ; le second fait transiter la sortie d’appareils choisis. Si le Gateway et la base sont dans un VPC et que le portable n’a que le tailnet, il faut dessiner quels src peuvent atteindre le port base, sinon on voit « curl OK depuis le serveur, CLI distante qui renvoie parfois 500 » par asymétrie ACL ou routage.
Un détail fréquent : MagicDNS et domaines de recherche ; certains réseaux d’entreprise détournent *.ts.net. Comparez dig vers un résolveur public et le résolveur tailnet avant d’imputer à OpenClaw une session « instable ».
Après installation et connexion sur l’hôte Gateway, vérifiez depuis un portable du même tailnet le ping et le RTT via tailscale ping ; dans la console Admin, contrôlez tags, MagicDNS et une ACL qui autorise explicitement TCP 18789 (ou votre port) des rôles d’exploitation vers le rôle Gateway.
// Exemple d’extrait ACL : machines tag:ops uniquement vers le port 18789 du nœud Gateway
{
"groups": { "group:ops": ["alice@github", "bob@github"] },
"tagOwners": { "tag:gateway": ["group:ops"] },
"acls": [
{
"action": "accept",
"src": ["tag:ops"],
"dst": ["tag:gateway:18789"]
}
]
}
Attention : l’exemple illustre la forme seulement. Une ACL réelle doit couvrir nœud de sortie, routes de sous-réseau et mobile avec le minimum de privilèges ; après modification, reconnectez le tailnet sur un appareil de test avant de valider.
Cochez dans le journal de changement : 1. le processus Gateway écoute toujours 127.0.0.1:18789 ; 2. depuis la machine d’exploitation, un health check HTTP cohérent avec votre version est accessible via l’IP tailnet (hors simple forward SSH local) ; 3. aucun groupe de sécurité public n’ouvre l’entrée 18789. Pour les symptômes « canal en ligne mais pas de messages », croisez avec sonde des canaux et politique dmPolicy.
On suppose openclaw doctor vert sur l’hôte ; sinon commencez par installation multiplateforme et premier lancement.
Adresse d’écoute : sur le serveur, lsof -nP -iTCP:18789 -sTCP:LISTEN doit montrer 127.0.0.1. Si vous voyez *:18789, revenez à la config avant d’optimiser le tunnel.
Source du jeton : privilégiez OPENCLAW_GATEWAY_TOKEN via l’environnement plutôt qu’un dépôt synchronisé contenant des secrets longue durée.
Bloc remote sur le portable : dans ~/.openclaw/openclaw.json, pointez vers le nom d’hôte tailnet et le port ; l’URL WebSocket en ws:// ou wss:// doit respecter la politique TLS interne.
Port explicite : si vous n’utilisez pas le port par défaut, alignez OPENCLAW_GATEWAY_PORT côté service et session client pour éviter « doctor OK, CLI sur le mauvais port ».
Terminaison TLS : derrière un reverse proxy sur le tailnet, vérifiez que la négociation WebSocket n’est pas cassée par le middleware.
Empreinte de session réussie : conservez dans un ticket gateway status, doctor et une trace d’échec pour comparer après montée de version.
// Exemple client ~/.openclaw/openclaw.json (champs selon la CLI officielle)
{
"gateway": {
"remote": {
"url": "ws://openclaw-gateway.tailnet-1234.ts.net:18789",
"token": "preferer-environnement-ou-trousseau-plutot-que-texte-brut"
}
}
}
Rappel : évitez de colocaliser Gateway et grosses compilations sur un petit VPS ; si l’agent doit lancer xcodebuild ou de gros caches, basculez l’exécution vers un Mac distant exclusif et laissez le Gateway orchestrer. Pour les gammes disque et région, voir les tarifs de location Mac Mini.
| Symptôme | Piste prioritaire | Action |
|---|---|---|
tailscale ping OK, CLI en timeout | Port absent de l’ACL ou pare-feu local sur la chaîne de forward vers la loopback | Valider d’abord en local sur loopback, puis élargir |
| HTTP 401 | Jeton différent ou variable non injectée dans l’unité systemd | Aligner Environment= de l’unité et le shell courant |
| WebSocket qui coupe / code 1000 | Incompatibilité de portée ou de session après upgrade | Se reporter à l’article « gateway closed » pour jeton et portée |
| Canal en ligne, pas de messages | Pas d’appariement ou dmPolicy | Lancer la sonde canaux et relire la matrice de politique |
Après une montée mineure, si le même ACL et le même jeton ne cassent que sur la CLI distante, lisez d’abord les changements incompatibles des notes de version et le tableau des ports par défaut ; rebaselinez sur la dernière version saine avant de retoucher en boucle les ACL.
18789 pour le plan de contrôle multiplexé (vérifier les release notes) ; toute dérive doit se répercuter dans systemd, Compose et le remote client.tag:gateway permet de faire croître les ACL proprement ; le manuel doit exiger révocation d’appareil et retrait des comptes à chaque départ.S’appuyer sur un bind public nu ou sur des ACL tailnet trop larges rend le plan d’agent difficile à auditer en 2026 ; charger toute la charge lourde sur le même petit VPS heurte mémoire et disque. La combinaison plus saine : Gateway léger en permanence, accès restreint via tailnet, travaux lourds sur un nœud macOS dédié. Quand il faut une chaîne Xcode stable, des sessions longues et un niveau de disque contractuel, la location de Mac Mini cloud NodeMini reste en pratique un bon candidat.
Une fois le paquet arrivé sur l’hôte via le tailnet, la pile locale achemine vers 127.0.0.1:18789 ; il n’est pas nécessaire d’écouter sur toutes les interfaces. Restent déterminants ACL, pare-feu local et jeton. Pour comparer les offres Mac, ouvrez la page des tarifs de location.
L’article Tunnel traite de l’entrée Internet vers un service interne ; celui-ci traite de l’accès strictement privé dans le tailnet avec loopback. Choisissez selon le besoin ou superposez en comprenant la chaîne d’authentification.
Parcourez la liste des articles OpenClaw sur le blog ; pour comptes et connexion, voir aussi le centre d’aide (SSH et puissance distante).