Salut tout le monde ! Hier, on a publié le guide d'installation via WSL2, et on a reçu pas mal de retours. Certains nous ont demandé : « Est-ce qu'on peut installer OpenClaw directement sur Windows, sans passer par WSL2 ? »
La réponse : oui, mais il y a des conditions.
Dans ce guide, je vais vous montrer en détail comment installer OpenClaw sur un Windows natif, avec tous les pièges à éviter et leurs solutions. C'est le fruit de plus de 30 tests d'installation.
⚠️ Déclaration importante : position officielle vs faisabilité réelle
Position officielle : - OpenClaw recommande d'utiliser WSL2 - L'installation native sur Windows n'est pas documentée officiellement - Les retours de la communauté indiquent un taux de réussite d'environ 60 à 70 %
En pratique : - OpenClaw peut tourner sur un Windows natif - Il faut un environnement de compilation C++ complet - C'est adapté aux utilisateurs ayant de l'expérience en développement sous Windows - Certaines fonctionnalités (comme le canal WhatsApp) peuvent poser des problèmes de compatibilité
Ce guide est pour vous si : - ✅ Vous avez de l'expérience en développement sous Windows et vous maîtrisez PowerShell - ✅ Vous avez besoin d'un accès direct au système de fichiers Windows - ✅ Vous ne voulez pas utiliser la virtualisation WSL2 - ✅ Vous êtes prêt à passer du temps à résoudre d'éventuels problèmes
L'installation native est déconseillée si : - ❌ Vous débutez sous Windows - ❌ Vous avez besoin des canaux WhatsApp/Telegram (WSL2 est plus stable) - ❌ Vous cherchez l'installation la plus simple possible - ❌ C'est pour un déploiement en production
Configuration requise
| Composant | Minimum recommandé | Configuration conseillée |
|---|---|---|
| Système d'exploitation | Windows 10 1903+ | Windows 11 22H2+ |
| Node.js | 22.0.0+ | Dernière version 22.x LTS |
| Mémoire RAM | 4 Go | 8 Go+ |
| Espace disque | 5 Go | 10 Go+ |
| Droits | Administrateur | Administrateur |
| Réseau | Internet stable | Accès à GitHub/npm |
Procédure d'installation complète
Phase 1 : Préparation (crucial !)
La cause principale des échecs d'installation native : des dépendances incomplètes. Suivez strictement l'ordre ci-dessous.
1.1 Installer Node.js 22+
Étapes :
- Rendez-vous sur le site officiel de Node.js
- Téléchargez la version LTS (22.x ou supérieure)
- Lancez le programme d'installation avec les options par défaut
- Une fois l'installation terminée, redémarrez PowerShell
Vérification :
node --version
npm --version
Résultat attendu :
v22.x.x
10.x.x
⚠️ Erreurs fréquentes : - Si la version est inférieure à 22, désinstallez et réinstallez - Si la commande n'est pas reconnue, vérifiez la variable d'environnement PATH
1.2 Installer Git
OpenClaw a besoin de Git pour récupérer ses dépendances.
Avec winget (recommandé) :
winget install Git.Git
Ou téléchargement manuel : 1. Rendez-vous sur Git for Windows 2. Téléchargez et lancez le programme d'installation 3. Les options par défaut conviennent
Vérification :
git --version
Résultat attendu :
git version 2.x.x.windows.1
1.3 Installer CMake
node-llama-cpp dépend de CMake.
Avec winget :
winget install Kitware.CMake
Vérification :
cmake --version
Résultat attendu :
cmake version 3.x.x
1.4 Installer Python (dépendance de node-gyp)
Certains packages npm nécessitent Python pour la compilation.
Avec winget :
winget install Python.Python.3.11
⚠️ Important : Cochez bien "Add Python to PATH" lors de l'installation.
Vérification :
python --version
1.5 Installer Visual Studio Build Tools (le point le plus critique !)
C'est l'étape la plus susceptible d'échouer lors d'une installation native Windows. node-gyp a besoin d'une chaîne de compilation C++ complète.
Méthode 1 : avec winget (recommandé)
winget install Microsoft.VisualStudio.2022.BuildTools
Méthode 2 : téléchargement manuel 1. Rendez-vous sur Visual Studio Build Tools 2. Téléchargez et lancez le programme d'installation
Composants obligatoires après l'installation :
Ouvrez le Visual Studio Installer → choisissez Modify → cochez :
- ✅ Desktop development with C++ (développement C++ bureautique)
- ✅ MSVC v143 - VS 2022 C++ build tools
- ✅ Windows 10/11 SDK
- ✅ C++ CMake tools for Windows
Vérification :
# Vérifier le compilateur MSVC
cl
# Les informations de version du compilateur devraient s'afficher
⚠️ Si l'installation est incomplète : L'installation d'OpenClaw échouera avec l'erreur :
error MSB8020: The build tools for v143 cannot be found.
error: Failed to compile llama.cpp
Phase 2 : Installer OpenClaw
2.1 Nettoyer une ancienne installation (si applicable)
# Désinstaller l'ancienne version
npm uninstall -g openclaw
# Vider le cache npm
npm cache clean --force
# Supprimer le répertoire de configuration (optionnel, perd la config)
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw -ErrorAction SilentlyContinue
2.2 Installer OpenClaw CLI
Ouvrez PowerShell en tant qu'administrateur, puis lancez :
npm install -g openclaw@latest
L'installation peut durer de 5 à 15 minutes, car les modules natifs doivent être compilés.
⚠️ Note sur PowerShell :
PowerShell ne supporte pas la syntaxe &&. Pour exécuter plusieurs commandes, utilisez ; :
# ❌ Erreur (syntaxe bash)
npm cache clean --force && npm install -g openclaw
# ✅ Correct (syntaxe PowerShell)
npm cache clean --force; npm install -g openclaw
2.3 Vérifier l'installation
openclaw --version
openclaw --help
Résultat attendu :
openclaw/2026.x.x windows-x64 node-v22.x.x
Phase 3 : Configuration initiale
3.1 Lancer l'assistant de configuration
openclaw onboard --install-daemon
Étapes de configuration :
- Type de gateway : Local (local) ou Remote (distant)
- Modèle d'IA : Anthropic/OpenAI/Google, etc.
- Clé API : préparez-la à l'avance
- Canaux de communication : Web UI/Telegram/Discord, etc.
- Installation du daemon : choisissez Yes pour un démarrage automatique
3.2 Configurer le démarrage automatique sous Windows
Le daemon d'OpenClaw sous Windows utilise le Planificateur de tâches.
Créer manuellement une tâche planifiée :
- Ouvrez le Planificateur de tâches (Task Scheduler)
- Créez une tâche de base
- Nom :
OpenClaw Gateway - Déclencheur : À l'ouverture de session
- Action : Démarrer un programme
- Programme/script :
C:\Users\votre_nom_utilisateur\AppData\Roaming\npm\openclaw.cmd - Arguments :
gateway start - Finalisez la création
Paramètres avancés : - Cochez "Exécuter même si l'utilisateur n'est pas connecté" - Cochez "Exécuter avec les autorisations les plus élevées" - Dans "Conditions", décochez "Ne démarrer la tâche que si l'ordinateur est sur secteur"
3.3 Démarrer la gateway
# Démarrer la gateway
openclaw gateway start
# Voir le statut
openclaw gateway status
# Voir les logs
openclaw gateway logs
3.4 Accéder au panneau de contrôle Web
Ouvrez votre navigateur et accédez à :
http://127.0.0.1:18789/
Si un token vous est demandé, il a été généré lors de l'assistant de configuration.
Erreurs courantes et solutions
Erreur 1 : Git non trouvé
Message d'erreur :
npm error syscall spawn git
npm error enoent
npm error spawn git ENOENT
Cause : Git n'est pas installé ou n'est pas dans le PATH
Solution :
# Installer Git
winget install Git.Git
# Redémarrer PowerShell puis vérifier
git --version
Erreur 2 : Échec du téléchargement de CMake
Message d'erreur :
[node-llama-cpp] Failed to download cmake
Error: connect ETIMEDOUT
Cause : Problème réseau empêchant le téléchargement de CMake
Solution :
# Installer CMake manuellement
winget install Kitware.CMake
# Vérifier
cmake --version
Erreur 3 : Chaîne d'outils C++ Visual Studio manquante
Message d'erreur :
gyp ERR! find VS
gyp ERR! find VS msvs_version not set from command line or npm config
gyp ERR! find VS checking VS2022 not found
gyp ERR! find VS not found: most reliable installation method is missing
Cause : Visual Studio Build Tools ou la charge de travail C++ n'est pas installée
Solution :
-
Installez Visual Studio Build Tools :
powershell winget install Microsoft.VisualStudio.2022.BuildTools -
Ouvrez le Visual Studio Installer
-
Cliquez sur Modify
-
Cochez Desktop development with C++
-
Vérifiez que ces composants sont inclus : - MSVC v143 - VS 2022 C++ build tools - Windows 10/11 SDK - C++ CMake tools for Windows
-
Redémarrez PowerShell
-
Réinstallez OpenClaw :
powershell npm uninstall -g openclaw npm cache clean --force npm install -g openclaw@latest
Erreur 4 : Échec de la compilation node-gyp
Message d'erreur :
gyp ERR! build error
gyp ERR! stack Error: `C:\Program Files\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe` failed with exit code: 1
Cause : Environnement de compilation incomplet ou problème réseau
Solution :
-
Vérifiez que toutes les dépendances sont installées (Git, CMake, VS Build Tools, Python)
-
Configurez npm avec un miroir local (optionnel) :
powershell npm config set registry https://registry.npmmirror.com -
Nettoyez et réinstallez :
powershell npm uninstall -g openclaw npm cache clean --force npm install -g openclaw@latest --omit=optional
Erreur 5 : Erreur de permissions
Message d'erreur :
Error: EACCES: permission denied, mkdir 'C:\Program Files\nodejs\node_modules\openclaw'
Cause : L'installation globale npm nécessite les droits administrateur
Solution :
Méthode 1 : lancez PowerShell en tant qu'administrateur - Clic droit sur PowerShell → Exécuter en tant qu'administrateur
Méthode 2 : modifiez le répertoire global de npm
# Créer un nouveau répertoire global
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.npm-global"
# Configurer npm
npm config set prefix "$env:USERPROFILE\.npm-global"
# Ajouter au PATH (permanent)
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\.npm-global", "User")
# Redémarrer PowerShell puis vérifier
npm install -g openclaw
Erreur 6 : Port déjà utilisé
Message d'erreur :
Error: listen EADDRINUSE: address already in use :::18789
Cause : Le port 18789 est déjà occupé (double lancement possible)
Solution :
-
Trouvez le processus utilisant le port :
powershell netstat -ano | findstr :18789 -
Tuez le processus (remplacez le PID) :
powershell taskkill /F /PID <PID> -
Ou utilisez un autre port :
powershell openclaw gateway --port 18790
Erreur 7 : Commande non reconnue
Message d'erreur :
'openclaw' n'est pas reconnu en tant que commande interne ou externe
Cause : Le répertoire global npm n'est pas dans le PATH
Solution :
-
Trouvez le répertoire global npm :
powershell npm prefix -g -
Ajoutez-le au PATH : ```powershell # Ajout temporaire (session courante) $env:Path += ";" + (npm prefix -g)
# Ajout permanent
```
- Redémarrez PowerShell
Erreur 8 : Échec de connexion WebSocket (WhatsApp/Telegram)
Message d'erreur :
WebSocket connection failed
Channel connection timeout
Cause : L'implémentation WebSocket sous Windows natif est incompatible avec certains canaux
Solution :
Fortement recommandé : pour les canaux WhatsApp/Telegram, utilisez WSL2
Si vous devez absolument rester en Windows natif : 1. Vérifiez que le pare-feu autorise Node.js à accéder au réseau 2. Essayez avec un proxy 3. Pensez à basculer vers Discord/Slack, plus stables
Windows natif vs WSL2 : comparaison
| Fonctionnalité | Windows natif | WSL2 (Ubuntu) |
|---|---|---|
| Difficulté d'installation | ⭐⭐⭐⭐ Difficile | ⭐⭐ Simple |
| Complexité des dépendances | Haute (installation manuelle) | Basse (gestionnaire de paquets) |
| Accès aux fichiers | ✅ Accès direct | ⚠️ Via /mnt/c |
| Performance | ⭐⭐⭐⭐ Natif | ⭐⭐⭐ Perte due à la virtualisation |
| Compatibilité | ⚠️ Problèmes avec certains canaux | ✅ Recommandé officiellement |
| Coût de maintenance | Haut | Bas |
| Cas d'utilisation idéal | Développement Windows | Environnement de production |
Quand choisir Windows natif ?
✅ Situations où l'installation native est adaptée : - Vous devez accéder fréquemment aux fichiers Windows (bureau, documents) - Vous avez de l'expérience en développement Windows - Vous utilisez uniquement Web UI ou les canaux Discord/Slack - Vous ne voulez pas de virtualisation
❌ WSL2 est préférable si : - Vous débutez sous Windows - Vous avez besoin des canaux WhatsApp/Telegram - Vous privilégiez la stabilité - C'est pour un déploiement en production
Notes sur la syntaxe PowerShell
Les utilisateurs venant de Linux/macOS font souvent ces erreurs :
# ❌ Syntaxe bash (PowerShell ne supporte pas)
openclaw gateway start && openclaw status
# ✅ Syntaxe PowerShell
openclaw gateway start; openclaw status
# Ou sur deux lignes
openclaw gateway start
openclaw gateway status
# ❌ Syntaxe bash
export OPENCLAW_HOME=C:\openclaw
# ✅ Syntaxe PowerShell
$env:OPENCLAW_HOME = "C:\openclaw"
# ❌ Syntaxe bash
cat ~/.openclaw/config.json
# ✅ Syntaxe PowerShell
Get-Content $env:USERPROFILE\.openclaw\config.json
Conseils d'optimisation des performances
1. Exclure des analyses Windows Defender
OpenClaw lit et écrit fréquemment des fichiers, ce qui peut être ralenti par Defender.
Ajouter des exclusions :
# À exécuter en tant qu'administrateur
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.openclaw"
Add-MpPreference -ExclusionPath "$(npm prefix -g)\node_modules\openclaw"
2. Configurer les variables d'environnement
# Définir le répertoire OpenClaw
$env:OPENCLAW_HOME = "D:\OpenClaw"
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", "D:\OpenClaw", "User")
# Définir le répertoire d'état
$env:OPENCLAW_STATE_DIR = "D:\OpenClaw\state"
[Environment]::SetEnvironmentVariable("OPENCLAW_STATE_DIR", "D:\OpenClaw\state", "User")
3. Limiter la taille des logs
Modifiez le fichier de configuration ~/.openclaw\openclaw.json :
{
"logging": {
"maxSize": "10MB",
"maxFiles": 3
}
}
Recommandations de sécurité
1. Restreindre l'accès réseau
Dans le fichier de configuration, limitez les connexions autorisées :
{
"channels": {
"webchat": {
"allowFrom": ["127.0.0.1", "192.168.1.0/24"]
}
}
}
2. Activer l'authentification
{
"auth": {
"required": true,
"type": "token",
"token": "your-secure-token-here"
}
}
3. Limiter les permissions des skills
{
"skills": {
"allowList": ["file.read", "web.search"],
"denyList": ["exec", "file.delete", "file.write"]
}
}
4. Audit de sécurité régulier
openclaw security audit --deep
Guide de désinstallation
Désinstallation complète d'OpenClaw
# 1. Arrêter la gateway
openclaw gateway stop
# 2. Désinstaller le CLI
npm uninstall -g openclaw
# 3. Supprimer le répertoire de configuration
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw
# 4. Supprimer la tâche planifiée (si créée)
# Ouvrez le Planificateur de tâches → supprimez la tâche OpenClaw Gateway
# 5. Nettoyer les variables d'environnement (si configurées)
# Propriétés système → Avancé → Variables d'environnement → supprimez les variables OPENCLAW_*
Résumé
Checklist d'installation native Windows
Avant de commencer, vérifiez :
- [ ] Windows 10 1903+ ou Windows 11
- [ ] Node.js 22+ installé
- [ ] Git installé et ajouté au PATH
- [ ] CMake installé
- [ ] Python 3.11 installé
- [ ] Visual Studio Build Tools + charge de travail C++ installés
- [ ] PowerShell avec droits administrateur
Étapes d'installation :
- ✅ Installer toutes les dépendances
- ✅
npm install -g openclaw@latest - ✅
openclaw onboard --install-daemon - ✅ Configurer le Planificateur de tâches
- ✅
openclaw gateway start - ✅ Accéder à
http://127.0.0.1:18789/
Conseil final
Si vos besoins principaux sont :
- 📱 Canal WhatsApp/Telegram → utilisez WSL2
- 🖥️ Web UI uniquement → Windows natif fonctionne
- 📁 Accès fréquent aux fichiers Windows → Windows natif est plus adapté
- 🚀 Environnement de production → utilisez WSL2 ou un serveur Linux
- 🎯 Apprendre en expérimentant → essayez les deux
Mon avis personnel :
Si vous débutez sous Windows, passez directement par WSL2. Le guide d'hier détaille l'installation via WSL2 : c'est plus simple, plus stable et mieux supporté officiellement.
Si vous êtes un utilisateur Windows expérimenté et que vous aimez bidouiller, l'installation native vous donnera une meilleure compréhension des dépendances sous-jacentes de l'outil.
Dans les deux cas, OpenClaw est un outil puissant qui vaut le temps investi pour sa configuration.
Ressources utiles : - Guide d'installation WSL2 - La solution recommandée - Documentation officielle OpenClaw - Discussion GitHub #7462 - Windows natif vs WSL2 - GitHub Issue #23178 - Discussion sur le support Windows natif - Téléchargement Node.js - Visual Studio Build Tools
Retours : Si vous rencontrez un problème non couvert par ce guide, n'hésitez pas à laisser un commentaire. Je mettrai cet article à jour régulièrement.
Prochain épisode : On explorera en profondeur le système de skills d'OpenClaw : comment personnaliser les capacités de votre assistant IA pour qu'il comprenne vraiment votre flux de travail. Restez branchés !