Installer OpenClaw sur Windows avec WSL2
Installez OpenClaw sur Windows avec Windows Hub, PowerShell ou WSL2, puis vérifiez le Gateway, le service et le port 18789.
Introduction
Le parcours OpenClaw Windows ne se limite plus à bricoler une installation Python dans Ubuntu. Trois voies actuelles existent : Windows Hub pour une expérience graphique intégrée, l’installateur PowerShell pour la CLI native, et WSL2 pour un Gateway très proche de Linux. Windows Hub est utile pour la majorité des utilisateurs ; WSL2 reste pertinent pour l’exploitation et les outils Linux. Il vaut mieux éviter un Gateway persistant sur un PC qui dort souvent : un VPS sera plus fiable. Ce tutoriel explique les trois options, puis détaille WSL2, le service, le port 18789, le pairing et les vérifications sans sortie inventée.
Résumé rapide
- Choisir Windows Hub pour le parcours le plus simple et les capacités natives.
- Choisir PowerShell pour une CLI et un Gateway natifs.
- Choisir WSL2 pour la compatibilité Linux et systemd.
- Installer avec les scripts officiels, puis lancer l’onboarding.
- Vérifier
doctor,gateway statuset le pairing avant d’ajouter des canaux.
Choisir entre Windows Hub, PowerShell et WSL2
Windows Hub est l’application compagnon recommandée. Elle peut provisionner au premier lancement une distribution WSL nommée OpenClawGateway, gérée par l’application et distincte de votre Ubuntu existant. Elle fournit une icône de zone de notification, le démarrage à la connexion, le chat, les diagnostics, les connexions à un Gateway local ou distant et le mode node Windows. Ce mode expose uniquement les capacités déclarées et autorisées, comme certaines commandes d’écran, de caméra, de notification ou de statut appareil.
La CLI native s’installe directement depuis PowerShell. Le service géré repose d’abord sur une tâche planifiée Windows, avec un élément de démarrage par utilisateur en solution de repli si la création de tâche est refusée. Cette voie convient à une utilisation terminal-first sans couche Linux.
WSL2 reste le runtime le plus compatible avec les procédures Linux. On y installe le Gateway avec le script shell officiel, puis OpenClaw utilise un service systemd utilisateur. Gardez alors le state dir et le workspace dans le système de fichiers Linux, sous ~/.openclaw, et non sous /mnt/c. Ce choix évite les différences de permissions et les coûts d’accès croisé.
Dans les trois cas, le cœur reste le même Gateway Node/TypeScript. Le fichier canonique est ~/.openclaw/openclaw.json, le port local par défaut est 18789 et les clients communiquent en WebSocket. Les anciens parcours fondés sur un package Python, une configuration YAML ou une commande de démarrage sur le port 3000 sont obsolètes.
Installer OpenClaw sur Windows pas à pas
Option A — Windows Hub
Installez l’application signée correspondant à l’architecture x64 ou arm64 depuis la page de releases officielle, puis lancez OpenClaw Companion. Au premier démarrage, choisissez la configuration locale si vous n’avez pas encore de Gateway. L’application crée sa propre distribution WSL, installe le Gateway et associe le client.
Lorsque l’icône devient verte, ouvrez le centre de commandes. Vérifiez la connexion, le pairing, les nodes et l’état des canaux. Si vous avez déjà un Gateway, utilisez la configuration avancée pour vous connecter à une URL locale, distante ou atteinte par tunnel SSH. Un Gateway public doit utiliser wss://; un tunnel vers loopback reste une option plus simple.
Le mode node Windows est séparé du rôle opérateur. Les commandes sensibles de capture d’écran ou de caméra demandent une autorisation explicite dans la politique Gateway. N’activez pas une famille de capacités uniquement parce qu’elle est disponible dans l’application.
Option B — CLI PowerShell native
Ouvrez PowerShell dans votre session utilisateur et lancez :
iwr -useb https://openclaw.ai/install.ps1 | iex
L’installateur provisionne les prérequis, installe la CLI et démarre l’onboarding. Vérifiez ensuite :
openclaw --version
openclaw doctor
openclaw gateway status --json
Pour installer ou réinstaller le service géré :
openclaw gateway install
openclaw gateway status --json
N’écrivez pas une tâche planifiée à la main sauf exigence particulière. La CLI connaît le chemin de son runtime, l’identité du profil et le state dir. Doctor sait inspecter l’état numérique de la tâche indépendamment de la langue de Windows.
Option C — Gateway WSL2 manuel
Dans PowerShell administrateur, installez WSL et une distribution :
wsl --install
wsl --list --online
wsl --install -d Ubuntu-24.04
Redémarrez si Windows le demande, puis vérifiez :
wsl --list --verbose
La distribution choisie doit apparaître en version 2. Dans Ubuntu, activez systemd via /etc/wsl.conf :
[boot]
systemd=true
Fermez la distribution, puis redémarrez WSL depuis PowerShell :
wsl --shutdown
Rouvrez Ubuntu et installez OpenClaw avec la voie Linux :
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw gateway status
Le script installe Node et la CLI ; n’installez pas Python, pip ou virtualenv. Si l’onboarding n’a pas installé le daemon, utilisez :
openclaw gateway install
openclaw gateway status
Garder WSL actif avant la connexion Windows
Pour un usage headless, systemd utilisateur a besoin du linger et la distribution doit être démarrée au boot Windows. Dans WSL :
sudo apt-get install -y dbus-x11
sudo loginctl enable-linger "$(whoami)"
openclaw gateway install
Une tâche Windows peut amorcer WSL au démarrage :
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec dbus-launch true" /sc onstart /ru "$env:USERNAME"
Adaptez Ubuntu au nom exact retourné par wsl --list --verbose. Après redémarrage, vérifiez dans WSL :
systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager
Accéder au Control UI
Sur le même PC, exécutez :
openclaw dashboard
Le navigateur Windows peut atteindre le Gateway local sur 127.0.0.1:18789. Si une demande d’appareil apparaît :
openclaw devices list
openclaw devices approve <requestId>
Un token Gateway et le pairing sont deux protections différentes. Le token authentifie la connexion au plan de contrôle ; le pairing autorise un appareil et lui attribue des rôles ou scopes.
Connecter un canal et vérifier
Dans PowerShell natif ou WSL, selon l’emplacement du Gateway :
openclaw channels add --channel telegram
openclaw channels status --probe
openclaw status --all
openclaw security audit
Les commandes doivent être lancées dans l’environnement qui possède le state dir du Gateway. Évitez d’installer une seconde CLI dans WSL si Windows Hub possède une distribution dédiée que vous n’avez pas choisi d’administrer manuellement.
Accès distant
Pour un Gateway sur un VPS, ouvrez un tunnel depuis Windows :
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
Le Control UI reste alors accessible comme une ressource locale. Pour un service WSL publié sur le LAN, une règle portproxy peut être nécessaire parce que l’adresse WSL change, mais cette exposition demande une authentification, un pare-feu et idéalement TLS. Pour un usage permanent, suivez plutôt le guide VPS OpenClaw.
Checklist de validation
- La méthode choisie correspond à l’usage : Hub, natif ou WSL2.
-
openclaw doctorne signale pas de configuration cassée. - Le Gateway géré est actif et écoute sur le port attendu.
- Le navigateur ou Windows Hub est appairé avec les bons scopes.
- Les fichiers WSL résident dans le home Linux.
- Aucun port du Gateway n’est exposé publiquement sans auth et TLS.
Exemple concret : Windows Hub relié à un VPS
Une utilisatrice de Windows 11 veut un assistant disponible même lorsque son laptop est fermé. Elle installe Windows Hub, mais ne crée pas de Gateway local persistant. À la place, elle déploie le Gateway sur un VPS, le laisse lié à loopback et ouvre un tunnel SSH depuis Windows :
ssh -N -L 18789:127.0.0.1:18789 ops@vps
Dans l’onglet Connections de Windows Hub, elle sélectionne le Gateway atteint par le tunnel et utilise l’URL WebSocket locale. Elle fournit le token du Gateway, puis approuve la demande d’appareil depuis le VPS. Le centre de commandes doit ensuite montrer la connexion et le canal Telegram en bonne santé.
Elle active le mode node Windows uniquement pour les notifications, pas pour la caméra ou l’exécution système. Cette limitation est volontaire : le Gateway distant peut demander une capacité, mais le node n’annonce et n’autorise que le sous-ensemble prévu. Après un redémarrage du laptop, elle rétablit le tunnel et vérifie openclaw status --deep côté serveur. Ce montage sépare disponibilité et interface : le VPS possède les sessions et canaux, tandis que Windows reste un client et éventuellement un périphérique.
Bonnes pratiques
N’entremêlez pas les trois installations. Windows Hub, la CLI native et une distribution Ubuntu personnelle peuvent chacune créer un state dir ou un service différent. Avant une commande de réparation, identifiez l’installation propriétaire avec gateway status et conservez le même profil. Une divergence de chemins produit des symptômes trompeurs : une CLI saine peut interroger le mauvais Gateway.
Dans WSL, stockez le workspace sous ~/, activez systemd et utilisez le service installé par OpenClaw. Ne laissez pas une console gateway run comme mécanisme de production. Pour les secrets, utilisez l’environnement du service ou des SecretRefs et ne placez jamais un token dans un fichier partagé Windows.
Enfin, préférez un Gateway distant pour les besoins 24/7. Windows Hub est un excellent client et node, mais la mise en veille d’un laptop interrompt un Gateway local. Les bonnes pratiques de production OpenClaw restent applicables quelle que soit l’interface.
Questions fréquentes
OpenClaw fonctionne-t-il nativement sur Windows ?
Oui. La CLI dispose d’un installateur PowerShell et le service géré utilise une tâche planifiée Windows. Windows Hub fournit en plus une application compagnon. WSL2 reste supporté et offre la plus forte compatibilité Linux, mais ce n’est plus la seule voie fiable comme l’affirmaient certains anciens tutoriels.
Faut-il choisir OpenClaw WSL2 ou Windows Hub ?
Choisissez Windows Hub pour l’installation guidée, le chat, le centre de commandes et le mode node. Choisissez un Gateway WSL2 manuel si vous administrez déjà Linux et voulez systemd ou des outils Unix. Pour une disponibilité continue, placez plutôt le Gateway sur un VPS et utilisez Windows Hub comme client.
Quel est le port d’OpenClaw sur Windows ?
Le Gateway utilise par défaut 127.0.0.1:18789, en natif comme dans le parcours WSL. Le Control UI partage ce serveur. Les anciens ports 3000 ou 8080 ne sont pas des valeurs canoniques. Un accès public doit passer par un transport sécurisé et une authentification Gateway.
Comment réparer un Gateway OpenClaw Windows ?
Commencez par openclaw gateway status --json, puis openclaw doctor. Doctor inspecte la tâche planifiée, le runtime, le port, la configuration et le pairing. Utilisez openclaw doctor --fix seulement après lecture des constats. Pour Windows Hub, consultez aussi le journal de setup depuis l’application avant de supprimer sa distribution gérée.
Articles liés
Windows peut héberger ou piloter OpenClaw, mais le bon choix dépend de la disponibilité recherchée. Gardez Windows Hub pour l’expérience desktop, WSL2 pour l’administration Linux et un VPS pour un Gateway toujours actif.
Restez informé sur les agents IA
Nouveaux tutoriels, comparatifs et guides pratiques directement dans votre boîte mail.