Sur Windows 11, OpenClaw se joue à trois couches qui se mordent la queue : le binaire CLI réellement invoqué, le répertoire utilisateur où vit openclaw.json, et le service qui relance la Gateway après veille ou mise à jour silencieuse de Node. Sans script unique versionné, chaque poste finit avec un PATH différent — « ça marche dans PowerShell mais pas dans le terminal VS Code » — et les tickets s'empilent. Ce guide fixe une procédure reproductible, compare WSL2 au hôte Windows pour la passerelle, et aligne le dépannage sur des paliers doctor cohérents avec ce que nous décrivons déjà côté Linux dans 2026 — OpenClaw Linux, dépannage permanent : systemd, journaux openclaw et sondes de port passerelle — FAQ par paliers. Pour la discipline des caches et artefacts reproductibles sur nœuds Mac cloud, la matrice CI Mac cloud 2026 à cycle court : caches de build distants (DerivedData, Pods, sccache) vs disque local du nœud — cold start, bande passante de synchronisation et matrice de réutilisation (paramètres exécutables) reste le pendant « build » de la même exigence de baseline.
Installation reproductible : un script PowerShell comme contrat
Évitez les copier-coller de dix lignes dans le chat interne. Centralisez : téléchargement ou canal MSI/NuGet validé par l'équipe, emplacement d'installation figé (par exemple sous %ProgramFiles% ou un préfixe outillage), variable d'environnement machine pour OPENCLAW_HOME si vous en utilisez une, et enfin openclaw onboard en mode non interactif uniquement après une première passe humaine sur ports et auth. Logguez la version CLI, le hachage du script et l'identité du compte de service dans votre dépôt d'ops ; restaurez toujours à partir de ces trois champs avant d'accuser une régression produit.
# Exécuter en PowerShell 7+, stratégie d'exécution contrôlée $ErrorActionPreference = 'Stop' # Install-OpenClaw.ps1 — figer URL, emplacement, compte de service # ... téléchargement vérifié (empreinte attendue) ... openclaw --version openclaw onboard --non-interactive # seulement après validation humaine initiale openclaw config validate openclaw doctor
WSL2 ou hôte Windows : où faire tourner la Gateway ?
WSL2 apporte systemd sur les distros récentes et des habitudes proches d'un VPS Linux, mais la pile réseau est une traduction : ports publiés, résolution DNS et sens des pare-feu Windows Defender diffèrent du hôte. Si votre passerelle doit être jointe depuis d'autres machines du LAN ou une interface tailnet installée sur Windows, héberger la Gateway sur le hôte évite une couche NAT et des surprises de « localhost » qui ne signifie pas la même chose des deux côtés. Réservez WSL2 aux flux style worker Linux ou tests d'intégration ; documentez explicitement si la prod Windows reste sur le hôte ou dans la distro, sans mélanger les deux sur le même port.
| Critère | Hôte Windows (PowerShell natif) | WSL2 (Ubuntu, etc.) |
|---|---|---|
| Réseau vers LAN / tailnet | Ports et pare-feu Windows explicites, moins de NAT implicite | Publication de ports et règles à dupliquer côté Windows |
| Résidence du service | Tâche planifiée / NSSM / service Windows documenté | systemd dans la distro, mais dépend du démarrage de WSL |
| PATH et binaires | Profils PowerShell, Terminal, VS Code à harmoniser | PATH Linux distinct ; risque de double installation Node |
| Meilleur cas d'usage | Gateway « bord bureau » exposée aux clients du poste | Parité scripts Linux, tests, agents secondaires |
openclaw doctor --deep signale déjà côté Unix.
PATH fragmenté et doctor : paliers 0 → 2
Palier 0 — identité du binaire. Dans la même session que vos automatisations, exécutez Get-Command openclaw | Format-List * et comparez au chemin attendu par le script d'install. Si VS Code ou Windows Terminal injecte un autre profil, corrigez l'ordre des chemins machine avant tout --fix.
Palier 1 — cohérence de config. openclaw config validate, puis openclaw gateway status et une sonde loopback (curl vers 127.0.0.1 sur le port affiché) avant d'ouvrir le pare-feu vers l'extérieur. Vérifiez que les jetons ne viennent pas d'une variable utilisateur différente de celle du service.
Palier 2 — réparation contrôlée. openclaw doctor --repair (alias --fix) avec --non-interactive seulement dans les pipelines ; sur poste humain, gardez l'interactivité pour lire les migrations. --deep lorsque des installations Gateway fantômes traînent après des essais multi-comptes.
openclaw vers l'une pendant que le service utilise l'autre. Figez le chemin Node dans la définition du service et supprimez les mises à jour silencieuses hors maintenance.
FAQ courte
Faut-il administrer la Gateway en tant qu'administrateur ? Non par défaut : créez un compte de service least-privilege avec droits d'écriture limités à %ProgramData%\OpenClaw (exemple) et au dossier workspace ; n'élevez les privilèges que pour l'installation initiale.
Le pare-feu bloque tout alors que loopback répond : ouvrez uniquement le profil domaine ou privé correspondant au LAN réel ; évitez « public » ouvert. Testez avec Test-NetConnection depuis une autre machine avant d'élargir.
Peut-on sauter WSL2 si l'équipe est 100 % Windows ? Oui si la passerelle vit sur le hôte et que les workers Linux restent sur vos VPS documentés ailleurs — gardez une ligne claire dans le runbook pour éviter le flou « Linux de bureau ».
Check-list avant d'ouvrir le LAN ou le tailnet
Ne publiez pas le port Gateway tant que les points suivants ne sont pas cochés sur un poste pilote : même build CLI que la CI interne, compte de service distinct du vôtre, sauvegarde chiffrée de openclaw.json et des secrets externes, redémarrage simulé (reboot + première minute) pour vérifier l'ordre de montage des disques réseau, et corrélation des journaux Windows (canal Application ou fichier rotatif) avec ce que vous attendez de openclaw logs. Documentez le rollback : réinstaller la build précédente, restaurer le fichier de config et réinscrire le service — si la procédure dépasse dix minutes, votre périmètre de sauvegarde est trop étroit.
Quand la pile Windows fatigue, un Mac cloud stabilise le poste opérateur
Ce guide réduit la dérive des postes Windows, mais le travail humain — navigateur, IDE, captures, outils MCP — reste sensible aux conflits de PATH, aux mises à jour de politique et aux doubles piles Node. Un Mac mini M4 dans le cloud offre un terminal Unix cohérent, des caches locaux rapides grâce à la mémoire unifiée Apple Silicon, et une consommation idle d'environ 4W pour les sessions longues sans ventilateur agressif.
macOS combine stabilité d'interface, Gatekeeper et SIP pour réduire le risque « drive-by » par rapport à beaucoup de laptops d'administration Windows, et l'écosystème Homebrew / SSH / outils natifs évite la fracture WSL2 pour les tâches quotidiennes. Le coût total de possession d'un mini silencieux reste compétitif lorsqu'on compte le temps ingénieur perdu en dépannage PATH.
Si vous voulez déplacer la partie « travail sérieux » hors des conflits de bureau Windows tout en gardant vos passerelles sur VPS Linux, le Mac mini M4 cloud VPSSpark est un point d'entrée pragmatique — découvrez les offres maintenant et gardez Windows pour les usages qui le méritent vraiment.