Points de friction : stable dans le cloud Linux, fragile sous WSL2
1. Deux localhost. Lier le service à 127.0.0.1 est sûr, mais un téléphone sur le Wi-Fi n’atteindra pas l’écouteur dans WSL tant que Windows ne republie pas le port ou que le bord ne migre pas vers une vraie interface. Symptôme classique : curl dans Ubuntu réussit, Postman sous Windows échoue, car tout le monde suppose « une » pile TCP.
2. systemd absent de PID 1. Les unités copiées depuis un VPS ne démarrent pas sans init ; on retombe sur tmux et des shells manuels, ce qui casse le récit opérationnel de la matrice de résidence launchd/systemd.
3. Veille et VPN. Les transports de chat longue durée tombent silencieusement ; le processus passerelle vit encore pendant que les workers de canaux sont bloqués. D’où l’insistance, dans l’exploitation passerelle, à corréler doctor avec les journaux de canaux plutôt qu’avec une simple sonde HTTP verte.
4. Ambiguïté TLS. Terminaison TLS sur Windows, texte clair vers WSL, puis HTTP côté OpenClaw peut supprimer les en-têtes nécessaires aux WebSockets. Croisez le guide proxy inversé : WSL ajoute un saut à nommer dans le runbook.
5. Dérive des chemins. Node installé sous Windows, nvm dans WSL, plusieurs binaires openclaw : après upgrade, ExecStart pointe encore vers un ancien préfixe. Les remèdes sont décrits près de l’installation et le rollback.
6. « Mettons Docker Desktop ». Encore une couche NAT ; pertinent si toute l’équipe vit en Compose, pas automatiquement plus simple qu’un systemd natif dans WSL pour un seul processus passerelle. Décidez avec des métriques, pas des slogans.
Les modes d’économie d’énergie Windows retardent parfois les heartbeats ; documentez si la passerelle est autorisée sur batterie. Fuseaux et locales décalent les horodatages : UTC côté appli facilite la corrélation avec les webhooks du fournisseur. Les équipes mixtes macOS/WSL ont besoin d’un runbook unique ou d’un scénario « doré ».
Il est utile d’avoir un bot de test à trafic limité pour valider le contour réseau sans risquer les conversations de production ; les bascules de jetons doivent être explicites dans la configuration pour éviter qu’un token de test ne se retrouve dans une unit marquée prod.
Enfin, fixez une latence attendue entre l’événement fournisseur et la réponse passerelle sur votre LAN ; sans ligne de base, on confond dégradation du modèle et simple queue réseau côté client ou WSL.
Espaces de noms WSL2 : où atterrissent réellement les paquets
WSL2 exécute une VM utilitaire légère : interfaces et tables de routage distinctes de l’hôte Windows. 127.0.0.1 dans Ubuntu est le loopback de la VM, pas celui de Windows. Un service lié uniquement à Windows n’apparaît pas « magiquement » dans Linux sans redirection ou mécanisme documenté d’accès hôte.
Le mode réseau miroir améliore l’ergonomie du localhost partagé sur certaines builds, mais n’élimine pas le besoin de documenter l’interface d’ingress webhook, le profil pare-feu et l’URL dans la console du fournisseur. Dessinez deux boîtes tant que le chemin n’est pas prouvé de bout en bout.
Le NAT sortant depuis WSL fonctionne généralement : modèles et appels sortants Telegram passent, les webhooks entrants échouent — signe typique d’une chaîne entrante incomplète, pas d’aléa OpenClaw.
Pour tester depuis le LAN, 0.0.0.0 dans WSL ne suffit pas : il faut portproxy Windows et règles pare-feu. Plus sûr : loopback contrôlé, reverse proxy sur Windows, petite VM, ou Mac distant hébergé SFTPMAC avec une histoire réseau plus simple.
Le DNS scindé d’entreprise sur Windows peut diverger de systemd-resolved dans WSL ; capturez les réponses des deux résolveurs lors d’incidents récurrents.
La dérive d’horloge dans la VM est rare mais casse OAuth ; comparez la synchro Windows si seuls les webhooks signés échouent sur les hôtes WSL.
L’IPv6 pur ou le CGNAT domestique compliquent le rebouclage : précisez IPv4/IPv6/tunnel pour les callbacks. L’antivirus ou l’EDR peut étouffer le trafic localhost ou sortant de WSL sans trace côté Linux : ajoutez ces contrôles au même checklist que pare-feu et portproxy.
Dans le README, indiquez si l’endpoint est « WSL seulement », « LAN » ou « public avec mTLS » pour éviter les mêmes questions à chaque astreinte.
Les politiques « interdiction d’entrée Internet » entrent souvent en conflit avec Telegram : il faut un chemin officiel — reverse proxy en DMZ, tunnel, ou passerelle sur une plateforme à ingress approuvé — sinon chaque développeur invente un contournement hors audit.
Les essais de charge sur batterie diffèrent du secteur : throttling CPU et latence radio modifient les temporisations de reconnexion. Si vous promettez un SLO de latence bot, notez le matériel et l’alimentation utilisés pour le mesurer.
systemd dans WSL : transformer vos unités en supervision réelle
Les WSL récents permettent systemd comme init : /etc/wsl.conf, section [boot], systemd=true, puis wsl --shutdown depuis Windows avant de rouvrir la distribution. Sans ce redémarrage complet, les fichiers unit se parsent mais ne s’attachent pas à PID 1.
Ensuite, appliquez la discipline serveur : daemon-reload après édition, User= et WorkingDirectory= explicites, Restart=on-failure avec backoff, LimitNOFILE aligné sur les appels d’outils concurrents. Croisez avec la « échelle de santé » de la doc résidence : active (running) n’implique pas des canaux sains.
Les unités système et utilisateur lisent des EnvironmentFile différents ; les secrets sur /mnt/c exigent attention aux permissions et aux fins de ligne CRLF.
Si la politique interdit systemd dans WSL, il faut un superviseur alternatif avec politique de redémarrage, pas un terminal interactif. L’analogie launchd dans l’article résidence tient : l’intégration OS est indispensable pour des passerelles 24/7.
Configurez journalctl avec journal persistant si vous investiguez des reconnexions des jours plus tard ; rotez assez pour ne pas remplir le VHDX des portables.
Mettez à jour par étapes : exportez la dernière sortie propre de openclaw doctor, appliquez les paquets, rechargez les unités, repassez l’échelle. Liez cela au rollback décrit dans le guide install/Docker pour éviter CLI et démon désalignés.
Après une feature update Windows, revérifiez portproxy : les règles peuvent disparaître silencieusement. Sauvegardez unit et wsl.conf. L’observabilité doit distinguer CPU modèle, appels d’outils et boucles de reconnexion infinies.
Lors d’un changement de poste, copier le dépôt ne suffit pas : sans les mêmes unités, variables et schéma réseau, les webhooks « cessent mystérieusement » malgré un code identique. L’onboarding doit inclure la couche WSL, pas seulement git clone.
Les versions noyau WSL et distribution influencent systemd et sockets ; figez des versions minimales supportées pour éviter les surprises du vendredi soir.
Matrice : adresses d’écoute, redirection Windows, reverse proxy
| Modèle | Atout | Risque | Cas OpenClaw |
|---|---|---|---|
| Loopback uniquement dans WSL | Exposition minimale ; pare-feu simple | Pas de test LAN/téléphone direct | Développement avec agents CLI locaux |
| Toutes interfaces WSL + portproxy Windows | Chemin explicite depuis le LAN | Sur-exposition facile ; règles qui vieillissent | Homelab avec liste blanche serrée |
| TLS sur proxy Windows vers amont WSL | Certificats centralisés ; bord cohérent | Erreurs WebSocket / en-têtes | Préproduction « prod-like » sur un PC |
| Tunnel SSH depuis une VM cloud | Pas d’écoute publique sur la box domicile | Complexité ; tunnels instables | Expérimentations personnelles |
| Passerelle sur Mac distant hébergé | Alimentation stable ; réseau plus simple | Choix fournisseur ; politique réseau | Équipes qui priorisent l’uptime |
| Docker Desktop | Images reproductibles | Encore du NAT ; volumes capricieux | Équipes 100 % Compose |
Choisissez un modèle principal par environnement et nommez-le dans l’onboarding. Les hybrides cassent quand moitié de l’équipe teste le loopback et l’autre suppose le LAN sans lire la table portproxy.
Jeux d’incident : coupez le VPN, mettez la machine en veille, relevez alertes et temps de récupération — mieux qu’un schéma décoratif.
Pour chaque ligne de la matrice, désignez un propriétaire : qui renouvelle les certificats sur le proxy Windows, qui recharge l’unit dans WSL, qui met à jour l’URL dans la console Telegram. Un flou « équipe plateforme » mène aux certificats expirés en plein jour férié parce que chacun pensait que ce n’était pas son périmètre.
Si vous avez plusieurs bots ou workspaces Slack, séparez-les par port ou hostname en périphérie ; sinon logs et métriques se mélangent. Gardez WSL simple et concentrez la complexité sur un reverse proxy mesurable.
Échelle de commandes : du boot WSL aux preuves doctor
# 1) Activer systemd (fragment — voir la doc de votre distro)
# sudo tee /etc/wsl.conf <<'EOF'
# [boot]
# systemd=true
# EOF
# Sous Windows : wsl --shutdown
# 2) Vérifier init et unité
# ps -p 1 -o comm=
# systemctl status openclaw-gateway.service
# 3) Écouteurs dans WSL (adapter le port)
# ss -lntp | head
# 4) Exemple portproxy Windows (PowerShell élevé)
# netsh interface portproxy add v4tov4 listenport=8443 listenaddress=0.0.0.0 connectport=8443 connectaddress=<IP-WSL>
# 5) Diagnostics OpenClaw (flags selon votre version)
# openclaw status
# openclaw gateway status
# openclaw doctor
# openclaw logs --follow
Joignez au ticket toutes les sorties ensemble ; une capture d’écran de silence Telegram ne remplace pas le journal montrant l’échec de rafraîchissement du jeton.
Ordre de lecture et durcissement adjacent
Commencez par le déploiement Windows, macOS et Linux, alignez le mode longue durée avec la résidence launchd/systemd. Si les canaux déraillent, passez à l’exploitation et les canaux avant de réécrire la configuration. Pour les webhooks derrière TLS, lisez proxy inversé et WebSocket. Gardez ouvert installation, Docker et rollback pendant les mises à jour.
Enchaînez openclaw doctor après chaque changement de frontière : systemd, portproxy, certificats, VPN. Si doctor est vert mais Telegram tombe, creusez les journaux transport plutôt que les paramètres du modèle.
Les boucles Slack suivent souvent des timeouts socket ou un proxy d’entreprise Windows ; répliquez les variables côté WSL si nécessaire.
Le staging doit copier le même schéma d’écoute que la prod : loopback uniquement en test et hostname public en prod évite de masquer allowedOrigins jusqu’au go-live.
Sur desktop, provisionnez le CPU : des appels d’outils concurrents affament les heartbeats des canaux. La revue sécurité demande un schéma d’une page : Windows, WSL, écouteur, certificats, URL de callback.
Dans la revue de changement, notez qui modifie portproxy et pare-feu. Playbook d’astreinte : obtenir l’IP WSL, afficher portproxy, vérifier l’écoute dans la VM et sur l’hôte. Plusieurs distros : documentez laquelle porte le rôle « quasi prod » et comment wsl -d est fixé dans les scripts. Comparez le coût horaire du débogage WSL à la location d’un Mac distant managé.
Pour la conformité, attachez au ticket la sortie de openclaw doctor et un extrait de netsh interface portproxy show all à chaque changement d’ingress : les relecteurs voient avant/après, pas seulement le diff Git.
Si l’organisation exige la séparation des environnements, ne mélangez pas secrets prod et préprod dans le même home WSL : comptes Linux ou distros séparés réduisent la fuite croisée.
Enfin, l’astreinte lit rarement un runbook de cinquante pages à 3 h du matin : une page « cinq minutes » plus un lien vers le détail réduit le MTTR mieux qu’un tableau de bord sans procédure.
FAQ, limites et pont vers le Mac distant hébergé SFTPMAC
Le réseau miroir règle-t-il tous les webhooks localhost ?
Non : il faut toujours documenter l’écoute, le pare-feu et l’URL de callback, puis valider avec un client externe qui reproduit le chemin Telegram ou Slack.
doctor est vert mais les canaux restent silencieux après veille
Corrélez les horodatages systemd avec les événements de veille, inspectez les sockets dans les journaux des canaux, redémarrez la passerelle ; ajoutez si besoin des dépendances vers network-online.
Une passerelle de prod sur le portable d’un développeur ?
En général non : veille, mises à jour, VPN. Pour l’uptime, privilégiez une infra fixe ou un Mac distant managé.
Nous codons déjà dans WSL : à quoi sert un Mac ?
Séparation des rôles : IDE et builds dans WSL, passerelle OpenClaw sur un Mac distant hébergé SFTPMAC avec alimentation stable et livraisons SSH/SFTP familières ; moins de portproxy et de risque lié à la veille Windows. Les artefacts suivent la même histoire opérationnelle sans exiger le portproxy chez chaque développeur, ce qui réduit les incidents « ça ne se reproduit pas chez moi » lorsque le bord réseau ne dépend plus d’un laptop précis.
Résumé : WSL2 impose une frontière d’espace de noms et un systemd optionnel. Traitez localhost, redirection et TLS comme des choix de conception ; exécutez openclaw doctor après chaque changement de frontière et corrélez les canaux avec des journaux structurés. Mesurez le succès par le délai jusqu’à une preuve convaincante, pas seulement par l’uptime ou le nombre de redémarrages inexpliqués.
Limites : On ne peut pas couvrir toutes les builds Windows, VPN et interactions Docker Desktop. Quand le coût d’intégration dépasse le gain, déplacez la passerelle vers une infra macOS hébergée tout en gardant le développement Linux sur le desktop. Prévoyez aussi les conflits Hyper-V, d’autres hyperviseurs et l’inspection TLS d’entreprise qui casse les WebSocket ; les canaux Windows Dev versus Retail, les politiques MDM et certains anti-triche agressifs sur machines personnelles peuvent surprendre.
Évaluez SFTPMAC si vous voulez des passerelles OpenClaw stables sur Mac distants avec moins de portproxy WSL et moins de risque lié à la veille — utile aux équipes déjà investies dans les chaînes de build Apple et qui cherchent un hôte unique pour agents et artefacts.