OpenClaw 2026 Gateway distant : tunnel SSH, Health Check macOS et checkliste LaunchAgent

En 2026, OpenClaw sur macOS propose deux modes : Local (Gateway et app sur la même machine) et Remote (Gateway sur un autre Mac, accès par tunnel SSH ou WebSocket direct). En production, le Gateway tourne souvent sur un Mac bare metal JEXCLOUD en 127.0.0.1:18789, le portable n’étant que la « télécommande ». Cela complète choix de nœud et dépannage launchd Token : là-bas « comment installer et choisir le nœud », ici « comment se connecter, maintenir et vérifier ».

En revue, ces cinq points sont souvent sous-estimés :

• Tunnel non permanent :la session SSH se coupe, l’app affiche un état obsolète jusqu’au timeout du Health Check.
• Double piste de token :écart entre launchctl, ~/.openclaw et le token saisi dans l’app → erreurs pairing / device token.
• Port ou forward incorrect :le port 18789 est occupé ou le LocalForward pointe ailleurs — CLI OK sur le distant, localhost refusé sur le portable.
• UI en retard sur la CLI :Health CLI OK, UI macOS encore pending (openclaw#66306).
• Surface d’attaque :Gateway sur 0.0.0.0 sans mTLS sur IP publique est risqué ; préférer 127.0.0.1 + SSH/Tailscale.

Règle mnémotechnique : « Gateway en loopback seulement, tunnel pour sortir, un seul token source de vérité ». Contourner une de ces règles coûte souvent des heures de debug.

Dans les réglages OpenClaw, zone OpenClaw runs, le transport est en général SSH tunnel ou Direct (ws/wss). Pas d’option universelle — seulement celle qui correspond à votre pare-feu, couverture Tailscale et habitudes ops.

Avec clé SSH du centre d’aide et Gateway en loopback uniquement : prioriser le tunnel SSH. Direct seulement si wss://gateway.example.ts.net est stable et « Test remote » reste vert.

Le distant doit exécuter OpenClaw CLI en shell non interactif (pnpm link --global, puis symlink vers /opt/homebrew/bin ou /usr/local/bin). Fichier token en 600, propriétaire = utilisateur du Gateway.

Host jex-openclaw-sg
  HostName your-instance.jexcloud.com
  User macuser
  IdentityFile ~/.ssh/jexcloud_ed25519
  LocalForward 18789 127.0.0.1:18789
  ServerAliveInterval 30
  ServerAliveCountMax 3

<key>Label</key>
<string>ai.openclaw.ssh-tunnel</string>
<key>ProgramArguments</key>
<array>
  <string>/usr/bin/ssh</string>
  <string>-N</string>
  <string>jex-openclaw-sg</string>
</array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>

Le Gateway via LaunchAgent ai.openclaw.gateway ; OPENCLAW_GATEWAY_TOKEN via launchctl setenv ou EnvironmentVariables dans le plist — pas en double dans le profil shell et le plist.

1. CLI + Gateway sur le distant :sur l’instance JEXCLOUD, openclaw gateway install ; lsof -i :18789 n’écoute que 127.0.0.1.
2. Écrire et valider le token :générer le token, chmod 600 ; launchctl setenv OPENCLAW_GATEWAY_TOKEN '…' puis redémarrer l’agent Gateway.
3. SSH sur le portable :ajouter LocalForward 18789 dans ~/.ssh/config, lancer ssh -N jex-openclaw-sg, puis dans un autre terminal curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health → 200.
4. LaunchAgent tunnel :launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist — tunnel auto après connexion.
5. Client macOS :Réglages → OpenClaw runs → Remote + SSH tunnel, user@host ou alias Host, Test remote jusqu’au vert.
6. Patrouille :script Health avec StartInterval (300 s) ou job CI SSH ; en échec launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel et journaliser le code de sortie.

Après appairage, valider le canal Agent en onboarding ; si CLI OK et UI pending, voir le tableau ci-dessous — ne pas réinstaller le Gateway à l’aveugle.

En production, assert HTTP 200 par script, pas seulement les voyants UI. Points citables (pratique communauté et observation JEXCLOUD 2026, sans SLA) :

• Port Gateway par défaut :18789(LocalForward aligné ; multi-instances : ports supplémentaires selon la doc).
• Endpoint Health :souvent /health avec Bearer Token ; monitoring en échec si ≠ 200.
• Auto-guérison tunnel :KeepAlive + ServerAliveInterval 30 → reprise souvent 30–90 s.
• RTT APAC :Asie de l’Est → nœuds SG/JP/HK en SSH souvent 15–35 ms ; surcoût tunnel < 5 ms en général.
• Droits fichier token :toujours 600 ; mauvais propriétaire → launchd peut refuser silencieusement.

#!/bin/bash
TOKEN="${OPENCLAW_GATEWAY_TOKEN:?}"
CODE=$(curl -sf -o /dev/null -w '%{http_code}' \
  -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health)
[[ "$CODE" == "200" ]] || exit 1

Fibre domestique ou Wi‑Fi instable en entrée tunnel 7×24 provoque souvent « vert le matin, rouge l’après-midi » (NAT, veille). Gateway sur VPS partagé ou virtualisation sursouscrite : Health intermittent sous charge voisine ; Mac local : mises à jour et popups Keychain. Les équipes qui veulent télécommande stable, tokens auditables, tunnel auto-réparant placent le Gateway sur Mac bare metal JEXCLOUD multi-région avec SSH loopback + LaunchAgent : Apple Silicon dédié, livraison ~120 s, M4 Pro si besoin. Tarifs : page tarifs JEXCLOUD ; dépannage graphique : VNC.