2026 OpenClaw passerelle distante : dérive CLI versus service, gateway.remote.url et matrice des sondes

Douleurs : la passerelle distante est un contrat d’exploitation

Douleur 1 : double cerveau. Lorsque openclaw gateway status affiche des chemins Config (cli) et Config (service) différents, vous éditez un JSON tandis que systemd ou launchd pointe encore une autre copie via HOME ou EnvironmentFile.

Douleur 2 : URL obsolète. Rotation de VM ou nouveaux conteneurs sans mise à jour de gateway.remote.url : l’UI peut toucher un bord CDN alors que la sonde vise une IP privée retirée.

Douleur 3 : confondre pairing. Les problèmes d’appairage coupent aussi le tableau de bord ; commencez par l’échelle status.

Douleur 4 : RPC vs silence canal. Sonde rouge : transport ; sonde verte mais Telegram muet : runbook canaux.

Couches : CLI, RPC, canaux

L0 versions. Harmoniser openclaw --version entre portable et hôte passerelle.

L1 gateway status. Noter runtime, URL cible de sonde, SNI TLS attendu, comparer à gateway.remote.url.

L2 doctor. Lever les blocages avant d’innocenter le réseau.

L3 canaux. Après L1 vert, lancer channels status --probe.

Champs ticket chiffrés

Chaque ticket inclut : résumés de chemins duaux, URL remote, préfixes de jeton masqués, noms d’unité, horodatage du dernier RPC vert, notAfter TLS, RTT admin→passerelle, snapshots horaires durant upgrade.

Capacité : sessions UI simultanées chargent les WebSockets ; tracez p95 séparément de la latence modèle.

Procédure en sept étapes

1. Geler : capture gateway status redigée.
2. Vérifier sémantique remote : gateway.mode et gateway.remote.url selon doc.
3. Aligner jetons CLI/UI/service.
4. Quartet reverse-proxy : TLS, WebSocket, allowedOrigins, keepalive.
5. openclaw gateway install --force + gateway restart avec noms d’unité.
6. doctor sans bloqueurs ; extrait dans le ticket.
7. Baseline : p95 sondes + action UI réussie.

openclaw --version
openclaw gateway status
openclaw config get gateway.remote.url
openclaw doctor

Approfondissement : causes réelles, pas de remplissage

systemd --user, linger et HOME cohérent

Un service systemd --user meurt quand la session SSH disparaît si linger n’est pas activé. Le statut gateway peut sembler sain tant que la session vit, puis échouer sans changement apparent de configuration. Vérifiez loginctl show-user, comparez $XDG_RUNTIME_DIR entre shell interactif et unité, et confirmez que le même compte Unix possède le JSON que vous modifiez. Installer l’unité sous root tout en éditant les fichiers d’un utilisateur standard est une erreur classique qui recrée la double lecture observée dans Config (cli) vs Config (service).

launchd : variables explicites plutôt que .zshrc

Sur macOS, launchd n’importe pas automatiquement votre .zshrc. Les chemins Node et binaires openclaw diffèrent donc entre Terminal et agent. Déclarez EnvironmentVariables dans le plist, journalisez stdout/stderr, évitez les chemins relatifs vers la configuration. Après chaque point release macOS, rejouez un smoke test court : redémarrage contrôlé, capture de gateway status, comparaison des chemins avant toute modification DNS ou proxy.

Reverse-proxy : SNI, WebSocket et timeouts

Le nom présenté au client TLS doit correspondre à gateway.remote.url et à la sonde RPC. Sinon, TLS échoue silencieusement ou bascule sur un certificat générique. Contrôlez la table de correspondance upgrade WebSocket, augmentez raisonnablement proxy_read_timeout pour les sessions longues, et assurez-vous que les healthchecks upstream visent le même port que le processus réel. Ajoutez upstream_addr aux logs pour prouver quel nœud a servi le trafic pendant l’incident.

Jetons, modes bind et exposition hors loopback

Les garde-fous récents refusent souvent d’écouter sur LAN sans secret cohérent. Une rotation partielle — UI mise à jour, service encore sur l’ancien EnvironmentFile — produit des erreurs d’authentification confuses. Définissez une source unique (gestionnaire de secrets, drop-in systemd chiffré, JSON unique), arrêtez le service, appliquez le secret, exécutez gateway install --force, redémarrez froid, puis seulement mettez à jour les clients. Cette séquence évite les fenêtres où les navigateurs envoient un jeton neuf vers un serveur vieux.

Observabilité : découpler handshake, première RPC et LLM

Séparez métriques de handshake TLS, upgrade WebSocket, première réponse RPC et latence modèle. Si seule la dernière augmente, le gateway est sain. Si l’upgrade chute, ne déclenchez pas de rotation de jetons inutile. Pour RGPD, tracez quelles lignes de logs peuvent contenir des secrets et leur durée de rétention ; cela clarifie l’audit sans paraphrases creuses.

DNS, TTL et bascule blue-green

Changer gateway.remote.url implique TTL DNS, caches navigateur et éventuels anciens nœuds encore vivants. Des TTL courts facilitent le rollback mais chargent les résolveurs. Prévoyez une fenêtre où deux cibles sont valides, notez l’heure officielle de coupure, reliez les tableaux de bord qui doivent passer au vert. Les post-mortems gagneraient en clarté si chaque bascule portait ces horodatages plutôt que des paragraphes répétitifs.

Pairing vs dérive remote

Les problèmes d’appairage partagent parfois le même symptôme UI mais exigent d’autres commandes. Suivez la échelle officielle status → gateway → logs avant de réapprouver des appareils, sinon vous perdez la traçabilité. La dérive remote reste un problème de transport et de fichiers de configuration ; documentez quelle couche est tombée en premier pour éviter les disputes entre réseau et produit.

Chaos contrôlé et rollback

Retirez volontairement une EnvironmentFile en staging pour vérifier que les alertes se déclenchent. Le rollback est le chemin inverse documenté, pas un empilement de correctifs improvisés. Chaque étape horodatée remplace des pages wiki remplies de phrases dupliquées sans signal.

Mac distant géré : quand louer réduit le risque

Si vous ne pouvez pas suivre en continu drift systemd/launchd, cycles TLS et mises à jour proxy, louer un Mac toujours allumé avec observabilité standard peut coûter moins que des astreintes répétées. Vous gardez politiques de jetons et agents, externalisez matériel et sondes de base. Comparez minutes d’indisponibilité RPC par trimestre au coût horaire réel de l’astreinte pour trancher.

RACI et les quinze premières minutes

Collectez d’abord un jeu minimal de preuves : extrait complet de gateway status avec jetons masqués, horodatage de la dernière sonde RPC verte, lignes proxy montrant l’upstream réel, et les deux chemiers de configuration en conflit. Séparez la personne qui consigne des personnes qui modifient DNS, unités ou certificats ; sinon l’historique devient indéchiffrable. Une validation croisée avant reload évite les doubles corrections contradictoires observées lors d’incidents nocturnes.

Résolveurs et caches DNS asymétriques

Le poste d’un opérateur peut encore pointer vers une ancienne IP privée alors que le serveur distant voit déjà le nouvel enregistrement. Testez avec le résolveur réellement utilisé par le navigateur ou l’outil de sonde, pas uniquement avec un dig sur le bastion. Notez TTL et caches négatifs : ils expliquent des retours à la normale retardés après un déploiement correct. Avec un nom interne dans gateway.remote.url, vérifiez aussi le split DNS entre VLAN.

Chaînes TLS, stapling et magasins différents

Après rotation d’intermédiaire, Nginx peut présenter une chaîne complète tandis que le démon ne charge qu’une feuille, ou l’inverse. Comparez openssl s_client depuis la même plage source que la sonde automatisée. Les erreurs d’OCSP stapling n’apparaissent souvent qu’à charge ; un seul handshake manuel ne suffit pas à valider la résilience.

Rafales de reconnexion

Après une coupure courte, de nombreux clients rouvrent des WebSockets simultanément. Sans backoff côté client et sans limites d’acceptation côté proxy, le processus passerelle peut saturer le CPU malgré un transport sain. Simulez ce scénario en préproduction avant de choisir une fenêtre de maintenance.

Cardinalité des métriques

Étiqueter chaque série par identifiant de canal ou d’utilisateur gonfle le coût et n’aide guère pour les pannes de transport. Gardez des dimensions grossières par défaut : environnement, rôle d’hôte, version majeure. Activez le drill-down fin uniquement pendant l’incident, puis coupez-le pour garder des tableaux de bord lisibles.

Post-mortem actionnable

Chaque action doit avoir un propriétaire, une échéance et un lien ticket ou PR. Remplacer les paragraphes vagues sur « l’importance du monitoring » par une mesure concrète : quelle sonde ou quel diff de configuration manquait, et comment il sera ajouté automatiquement.

Fenêtre de mise à jour et portes de readiness

Appliquez d’abord la config proxy stable, redémarrez ensuite le démon passerelle, puis seulement informez les clients UI. Inverser l’ordre laisse des WebSockets mi-chemin sur un nœud qui garde d’anciennes cartes upstream. Exigez trois sondes vertes consécutives depuis deux réseaux sources différents avant de clôturer l’incident.

Pare-feu stateful et sessions longues

Certaines appliances ferment silencieusement des sessions TCP peu actives côté contrôle alors que le WebSocket semble sain. Recensez tous les idle timeouts et alignez-les sur les heartbeats applicatifs et les timeouts proxy ; sinon vous corrigez TLS alors que la couche intermédiaire coupe le flux.

SLA fournisseur vs observabilité interne

Si le Mac distant est loué, listez ce que couvre le SLA (panne matérielle typiquement) et ce qui reste votre responsabilité (tempêtes de reconnexion, dérive de config). Gardez des runbooks exécutables sans compte fournisseur pour les heures creuses.

Rotation des secrets sans doubles vérités

Une seule source doit créer les jetons ; propagez-les proprement vers portable, unité de service et UI. Trois correctifs parallèles mènent à la dernière écriture gagnante alors que les journaux montrent encore d’anciens préfixes. Après rotation, enchaînez immédiatement gateway status et une sonde RPC, et archivez un hash du JSON concerné pour trancher les débats ultérieurs.

Lecture associée

Pairing : runbook pairing. Installation : install passerelle. TLS/WebSocket : reverse proxy. Silence canal : runbook canaux. Audit 4.14 : audit.

Remote règle transport/auth ; une sonde verte ne remplace pas le debug canal ou quotas.