2026 — OpenClaw passerelle distante : connexion & dépannage d’appairage — gateway.remote, OPENCLAW_GATEWAY_TOKEN, tableau décisionnel Pairing/Relay + checklist SSH Mac exclusif reproductible + FAQ
Lorsque le plan de contrôle OpenClaw et la passerelle HTTP ne sont pas sur le même hôte, la plupart des incidents se classent en trois familles : URL distante incorrecte (gateway.remote), incohérence de jeton (OPENCLAW_GATEWAY_TOKEN), ou sémantique transport (validation d’appairage vs chemin relais/WebSocket). Ce guide propose des tableaux de triage « style 2026 » prêts à coller dans un runbook, plus une checklist SSH reproductible sur un Mac distant exclusif pour arrêter de deviner quelle couche a cassé en premier.
TL;DR — Points clés
- Prouver l’atteignabilité avant l’auth : depuis l’hôte client,
curl -vsur la même URL de base que celle configurée dansgateway.remote(ou équivalent). Si TLS ou DNS échoue ici, les jetons d’appairage ne changeront rien. - Une seule source de vérité pour le jeton : définir
OPENCLAW_GATEWAY_TOKEN(ou la référence secrète documentée) dans exactement le runtime qui initie la session passerelle — plist LaunchAgent, profil shell ou secret CI — et vérifier que les deux côtés voient la même valeur après redémarrage. - L’appairage est une machine à états : les erreurs « en attente / expiré / déjà lié » pointent souvent vers dérive d’horloge, réutilisation d’ID d’installation ou second client qui court après le même code — pas un « simple » problème réseau.
- Les erreurs de relais sont souvent liées au chemin ou au proxy : mises à niveau WebSocket bloquées par des proxies d’entreprise et double terminaison TLS en bordure de tunnel sont les suspects habituels quand les sondes HTTP passent mais les flux se coupent.
Pour le positionnement passerelle/agents sur une flotte, voir Intégration entreprise OpenClaw sur Mac mini distant (SSH / R&D). Pour l’autostart de base et le durcissement SSH, croiser avec Guide complet 2026 : déploiement et exécution stable d’OpenClaw sur Mac mini — sécurité SSH et automatisation 24/7.
1. Modèle mental : agent local vs passerelle distante
Considérez la pile comme deux processus coopératifs : (A) le worker côté macOS qui possède les outils Apple, et (B) la passerelle qui expose une surface HTTP/WebSocket aux clients. Quand (B) est distant, votre Mac est un nœud backend qui doit établir la connexion sortante ou être joint via un point d’entrée contrôlé (tunnel SSH, Tailscale, Cloudflare Tunnel, etc.). Des clés comme gateway.remote ne sont que l’adresse stable de (B) ; elles ne remplacent ni la politique réseau ni la confiance TLS.
Les Mac distants exclusifs gagnent quand il vous faut un accès Trousseau déterministe, des chemins Xcode stables et l’absence de voisins bruyants sur CPU ou disque — au prix de gérer vous-même l’atteignabilité et la distribution des secrets de bout en bout.
2. gateway.remote & OPENCLAW_GATEWAY_TOKEN — tableau de configuration
Utilisez ce tableau lorsque les journaux sont vagues mais que vous savez quel hôte exécute le client et lequel héberge la passerelle.
| Objectif | Configurer / vérifier | Erreur fréquente |
|---|---|---|
| Passerelle sur un autre hôte du LAN | gateway.remote = https://10.x.x.x:PORT (ou nom d’hôte HTTPS sur DNS LAN) |
Utiliser un nom public qui résout différemment dans le LAN (surprise split DNS) |
| Passerelle derrière tunnel inverse | L’URL correspond au domaine frontal du tunnel ; le SAN du certificat correspond à ce nom d’hôte | Sonde de santé sur 127.0.0.1 du Mac alors que gateway.remote pointe encore vers un ancien DNS |
| Sessions passerelle authentifiées | Même jeton littéral côté passerelle et client : OPENCLAW_GATEWAY_TOKEN |
Jeton défini dans le shell interactif mais absent des EnvironmentVariables du LaunchAgent |
| Rotation sécurisée des identifiants | Mettre à jour la passerelle en premier, redémarrer, puis faire tourner les clients ; fenêtre de chevauchement si supportée | Redémarrage partiel — un seul côté a pris le nouveau jeton |
3. Appairage vs relais — symptôme → piste → action
| Symptôme | Couche probable | Premières actions |
|---|---|---|
| 401/403 immédiatement à la connexion | Jeton ou middleware d’auth | Afficher l’environnement effectif du service en cours (pas votre terminal) ; comparer aux journaux passerelle « bad token » |
| Code d’appairage « introuvable » ou expiré | État d’appairage / horloge | Vérifier NTP sur les deux hôtes ; éviter de réutiliser un code UI périmé ; révoquer d’anciens appairages si le produit le permet |
| HTTP 200 puis flux coupé ; retries « relay » | WebSocket / proxy / timeout d’inactivité | Tester avec wscat ou équivalent sur le même chemin ; augmenter le keepalive ; inspecter les limites d’inactivité du tunnel |
| Erreurs TLS uniquement depuis clients distants | Chaîne de certificats ou SNI | openssl s_client -connect hôte:443 -servername hôte depuis le réseau client |
| Fonctionne en Wi‑Fi, échoue sur VPN | Split tunnel / DNS | Comparer la résolution (dig / scutil --dns) sur le Mac pour le nom de la passerelle |
4. Mac distant exclusif — checklist SSH reproductible
Exécutez ces étapes dans l’ordre sur un Mac distant dédié (pas d’utilisateur GUI partagé) pour que vos notes soient reproductibles pour l’équipe.
- Base SSH : authentification par clé,
AllowUsersrestreint, optionnellementMatch UseravecChrootDirectorydésactivé pour les outils de dev (ne cassez pas les chemins Xcode). - Prouver les briques passerelle locales (s’il y en a) :
curl -sf http://127.0.0.1:PORT/healthou la sonde documentée. - Prouver l’URL distante : depuis le Mac,
curl -v "$GATEWAY_URL"avec le même schéma/hôte quegateway.remote. - Geler l’environnement pour launchd : refléter
OPENCLAW_GATEWAY_TOKENet l’URL distante dans le plist LaunchAgent ;launchctl bootout/bootstrapcomme déjà documenté pour les services OpenClaw. - Capturer les journaux une fois : rediriger stderr/stdout vers un fichier rotatif ou utiliser des prédicats
log streamconvenus dans l’org — assez pour distinguer appairage vs relais sans PII. - Bascule de retour arrière : conserver l’ancien jeton « bon état » dans un gestionnaire de secrets scellé ; documenter le rollback en deux étapes (passerelle → clients).
5. FAQ
Faut-il à la fois un flux d’appairage et un jeton longue durée ?
Souvent oui : l’appairage amorce la confiance pour un appareil ou un ID d’installation, tandis que OPENCLAW_GATEWAY_TOKEN (ou équivalent) authentifie les appels API courants. Si vous faites tourner les jetons, attendez-vous à ré-appairer ou ré-enregistrer les clients selon la doc produit.
Pourquoi l’erreur de relais disparaît sur un chemin Ethernet direct ?
Le Wi‑Fi grand public ou les réseaux invités filtrent parfois les WebSockets longue durée ou injectent des portails captifs. Ethernet ou un VPN d’entreprise avec règles explicites retire ces variables — confirmez par un A/B contrôlé.
Puis-je pointer gateway.remote vers localhost via SSH -L ?
Oui, si le processus OpenClaw sur le Mac résout cette URL vers le port forwardé. Préférez 127.0.0.1 explicite et documentez le port local pour éviter les collisions entre plusieurs tunnels.
Pourquoi ancrer cette bordure passerelle sur un Mac mini ?
Le dépannage d’une passerelle distante repose surtout sur un réseau stable, des horloges fiables et des démons longue durée. Un Mac mini Apple Silicon consomme très peu au repos, reste silencieux et exécute macOS avec Gatekeeper, SIP et FileVault — surface d’attaque opérationnelle souvent plus réduite qu’un hôte Windows « toujours allumé » générique. OpenSSH natif, outillage TLS via Homebrew et chemins Xcode prévisibles rendent le schéma Mac exclusif plus simple à supporter qu’un parc multi-OS pour l’automatisation centrée Apple.
Si vous voulez que l’appairage, le relais et la rotation des jetons « tiennent tout seuls » pendant que vous vous concentrez sur le produit, le Mac mini M4 constitue un ancrage pratique — utilisez le CTA ci-dessous pour comparer des offres adaptées à votre tailnet ou à votre design de tunnel.