OpenClaw ne s'installe pas ? J'ai déjà tombé dans ces 7 pièges

Mise à jour du 2026-06-08 : les noms de modèles dans les exemples de configuration utilisent désormais des versions actuelles (Anthropic claude-sonnet-4-6, OpenAI gpt-5) ; les prérequis Node (v22.14+, v24 recommandé), les ressources et les commandes de diagnostic ont été revérifiés en juin 2026. Référez-vous toujours à docs.openclaw.ai/install.

Pour la Nième fois, des messages d’erreur rouges s’affichent dans le terminal. Vous vouliez simplement essayer OpenClaw, ce nouvel outil — et voilà que depuis le soir jusqu’à maintenant, erreurs de permissions npm, conteneur Docker qui redémarre en boucle, clé API qui refuse de fonctionner… Chaque problème résolu en fait surgir trois autres. En parcourant les GitHub Issues, vous réalisez que beaucoup posent les mêmes questions : le seuil d’installation est bien plus élevé qu’on ne l’imagine.

Vous avez suivi la doc officielle pas à pas, et pourtant rien ne démarre. La pile d’erreurs dans le terminal donne le vertige — par où commencer ?

Bonne nouvelle : après un week-end entier à tout tester, j’ai touché tous les pièges. Cet article est un « guide anti-embûches » — il couvre les 7 grandes catégories de problèmes les plus fréquents à l’installation d’OpenClaw, avec pour chacune des étapes de diagnostic claires et des solutions. Pas seulement le « comment faire », mais aussi le « pourquoi ça casse », pour savoir où chercher la prochaine fois.

Guide low-cost « élever la crevette » : ArkClaw démocratise les agents IA

OpenClaw (homard) est populaire mais la config rebute ? ArkClaw de ByteDance Volcano Engine abaisse le seuil au minimum. Sans serveur ni tokens à bricoler : un agent en ligne 24 h/24 qui contrôle le navigateur, exécute des scripts et gère l’agenda en un clic.

Le prix compte : 9,9 ¥/mois ; avec mon code d’invitation ZLKUK54M (inscription ici) seulement 8,9 ¥. Développeur ? Le Coding Plan Pro peut même inclure ArkClaw gratuitement.

Problèmes de version Node.js (le plus fréquent)

La première chose à vérifier pour installer OpenClaw, c’est la version de Node.js. J’avais au départ le Node 16 du système — et une flopée d’erreurs de syntaxe incompréhensibles.

Vérifiez d’abord votre version :

node -v

Si la version est clairement ancienne, suspectez cette piste en priorité. Selon docs.openclaw.ai/install : minimum Node.js v22.14+, Node.js v24 recommandé ; une version trop basse provoque des incompatibilités de syntaxe ou d’API runtime.

Les erreurs typiques d’incompatibilité ressemblent à ceci :

SyntaxError: Unexpected token '?'
TypeError: fetch is not a function

La première apparaît souvent quand le runtime est trop ancien et ne supporte pas l’optional chaining ; la seconde quand le minimum officiel Node (v22.14+) n’est pas atteint ou que l’environnement / le shell n’utilise pas le bon node, d’où un décalage sur fetch et autres API. Ce genre de message ? Ne vous posez pas de questions : dans neuf cas sur dix, c’est la version ou le PATH/nvm mal configuré.

La solution la plus simple : gérer les versions avec nvm.

Je recommande fortement nvm (Node Version Manager) : basculer entre versions sans impacter les autres projets.

🪟 Utilisateurs Windows :

Téléchargez l’installateur sur nvm-windows. Avant l’installation, désinstallez proprement Node.js déjà présent, sinon conflit de PATH.

🐧 Utilisateurs Linux/macOS :

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

Après nvm, installez Node.js 24 (aligné sur la recommandation officielle, et au-dessus du minimum v22.14+) :

nvm install 24
nvm use 24
nvm alias default 24

La dernière commande fixe la 24 par défaut ; les nouveaux terminaux l’utiliseront automatiquement.

Erreurs de permissions npm (fréquent sous WSL2/Linux)

Les erreurs de permissions npm m’ont vraiment épuisé — surtout sous WSL2 : à chaque npm install, EACCES, et c’est agaçant.

À quoi ressemble l’erreur :

EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'
EACCES: permission denied, open 'package.json'

La première survient à l’installation globale ; la seconde, souvent sous /mnt/c dans WSL2.

❌ N’utilisez pas ces méthodes (vraiment) :

• Pas de sudo npm install — propriété des fichiers en désordre, encore pire ensuite
• Pas de chmod 777 — vous ouvrez la porte aux attaquants
• Pas de npm config set unsafe-perm true — pansement, pas la cause

✅ Trois solutions correctes, selon votre cas :

Option A : répertoire global npm personnalisé (recommandé, tous Linux)

L’idée : placer le répertoire d’installation global npm dans votre home — plus de souci de permissions.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Rouvrez un terminal et retentez l’installation npm : l’erreur de permission devrait disparaître.

Option B : corriger les permissions du système de fichiers WSL2 (spécifique WSL2)

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

🔧 Gros piège WSL2 : le système de fichiers Windows monté (/mnt/c) n’a pas le même modèle de permissions — npm y échoue souvent.

Configurez /etc/wsl.conf :

sudo nano /etc/wsl.conf

Ajoutez :

[automount]
options = "metadata,umask=22,fmask=11"

Enregistrez, puis dans PowerShell sous Windows :

wsl.exe --shutdown

Rouvrez WSL2 : les problèmes de permissions sont en général réglés.

Option C : travailler dans le home WSL (le plus direct)

Franchement, le plus simple est de ne pas développer sous /mnt/c. Utilisez un répertoire natif WSL comme ~/projects : npm est plus rapide et sans permissions bizarres.

mkdir ~/projects
cd ~/projects
# Installez OpenClaw ici

Problèmes Docker

Docker peut prêter à confusion — j’y ai bloqué un moment. Les causes d’échec au démarrage du conteneur sont nombreuses ; il faut avancer pas à pas.

Comment diagnostiquer :

# Étape 1 : état des conteneurs
docker compose ps

# Étape 2 : consulter les logs
docker compose logs openclaw-gateway

# Étape 3 : filtrer les erreurs
docker compose logs openclaw-gateway | grep -i "error"

Ces trois étapes localisent rapidement le problème.

Problème A : échec du health check, conteneur qui redémarre en boucle

Symptôme : le conteneur s’arrête au bout de quelques secondes, redémarre, et ainsi de suite.

Dans les logs, vous verrez par exemple :

Health check failed: container unhealthy
Container openclaw-gateway exited with code 137

Dans neuf cas sur dix, ressources insuffisantes. OpenClaw recommande au minimum 2 vCPU / 4 Go RAM, idéalement 4 vCPU / 8 Go RAM.

Comment ajuster les ressources Docker ?

🪟 Windows/Mac : Docker Desktop → Settings → Resources, augmentez CPU et mémoire.

🐧 Linux : en général pas de config dédiée ; Docker utilise les ressources de l’hôte.

Si la machine est vraiment limitée, vous pouvez désactiver temporairement le health check (déconseillé, mais utile en urgence) :

# Éditez docker-compose.yml
healthcheck:
  disable: true

Problème B : erreur de permissions Docker (spécifique Linux)

Erreur possible :

permission denied while trying to connect to the Docker daemon socket

Votre utilisateur n’est pas dans le groupe docker. Solution :

sudo usermod -aG docker $USER
newgrp docker

⚠️ Sécurité : ajouter un utilisateur au groupe docker équivaut à des privilèges proches de root ; en production ou serveur partagé, préférez rootless Docker.

Problème C : port 18789 déjà utilisé

Parfois un ancien processus OpenClaw n’est pas arrêté proprement.

🐧 Diagnostic Linux/Mac :

lsof -i :18789

🪟 Diagnostic Windows :

netstat -ano | findstr 18789

Une fois le PID identifié, arrêt propre :

openclaw gateway stop

Ou arrêt forcé (remplacez PID par la valeur trouvée) :

kill -9 <PID>

Problème D : architecture ARM64 (Mac Apple Silicon)

Sur Mac M1/M2, un chemin Chromium incompatible peut survenir — rare mais pénible.

Solution : Dockerfile personnalisé avec le chemin Chromium ARM64. Cherchez dans les GitHub Issues OpenClaw ; des configs complètes circulent déjà.

Configuration des clés API

Les clés API m’ont aussi pris la tête : clé pourtant dans le fichier de config, et OpenClaw ne la trouve pas.

Erreurs fréquentes :

No API key found for anthropic
Invalid API key format
API key validation failed

Ne paniquez pas : suivez la checklist ci-dessous.

Point 1 : les variables d’environnement sont-elles correctes ?

Vérifiez qu’elles sont bien actives :

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

Sortie vide = variable mal définie.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Définition correcte :

# Temporaire (terminal courant)
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# Permanent (fichier de config)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

🔧 Utilisateurs WSL2 : les variables WSL2 et Windows ne sont pas partagées — ne configurez pas seulement côté Windows puis cherchez la clé dans WSL2.

Point 2 : le format du fichier de config est-il valide ?

En mode fichier (~/.openclaw/openclaw.json), le JSON doit être strict. Config principale et répertoire d’état actuels : ~/.openclaw/ ; si vous utilisez encore l’ancien ~/.clawdbot/, lisez d’abord l’article de la série sur le renommage OpenClaw avant migration.

Erreurs les plus vues :

• espaces ou guillemets en trop
• virgule oubliée
• virgule après le dernier élément

Validez le JSON :

cat ~/.openclaw/openclaw.json | jq .

Si jq échoue, le JSON est invalide. Installez jq si besoin :

# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq

Point 3 : la clé API elle-même est-elle valide ?

Parfois ce n’est pas la config : clé expirée ou révoquée.

• Anthropic Claude : https://console.anthropic.com/settings/keys
• OpenAI GPT : https://platform.openai.com/api-keys

Vérifiez le statut Active et les limites d’usage.

Astuce : différences entre fournisseurs API

Pour changer le modèle par défaut, dans le fichier de config :

{
  "defaultProvider": "anthropic",
  "anthropic": {
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-sonnet-4-6"
  },
  "openai": {
    "apiKey": "sk-xxxxx",
    "model": "gpt-5"
  }
}

Configuration spécifique à l’environnement WSL2

Sous Windows avec WSL2, beaucoup de tutos Linux ne s’appliquent pas tel quel. WSL2 diffère du Linux natif — on le découvre à ses dépens.

Trois différences majeures :

1. Modèle de permissions fichiers différent — voir la section npm ci-dessus
2. Pile réseau isolée — localhost n’est pas toujours partagé
3. Intégration Docker Desktop — Docker partagé Windows/WSL2 peut poser problème

Configuration WSL2 : /etc/wsl.conf complet

Je conseille une config complète pour éviter bien des soucis :

sudo nano /etc/wsl.conf

Contenu :

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[interop]
enabled = true
appendWindowsPath = true

[network]
generateResolvConf = true

Puis redémarrez WSL2 :

# Dans PowerShell Windows
wsl.exe --shutdown

Intégration Docker Desktop for Windows

Avec Docker Desktop, activez l’intégration WSL2 :

1. Ouvrez Docker Desktop
2. Settings → Resources → WSL Integration
3. Cochez votre distribution WSL2 (ex. Ubuntu)
4. Apply & Restart

Performance : évitez les opérations cross-filesystem

Piège que j’ai le plus creusé : code sur le disque D Windows (/mnt/d dans WSL2) — npm install interminable.

Les accès cross-filesystem (WSL2 → fichiers Windows) perdent 50 à 90 % de performance — chiffre réel, pas exagéré.

La bonne pratique :

# Travaillez dans le home WSL2
cd ~
mkdir projects
cd projects
git clone https://github.com/openclaw/openclaw.git

Tout dans le système de fichiers natif WSL2 (/home/username) : bien plus rapide.

Limitation des ressources (optionnel)

Si la RAM manque, limitez WSL2 via .wslconfig dans le profil Windows :

# C:\Users\VotreNomUtilisateur\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB

OpenClaw consomme déjà pas mal ; trop limiter WSL2 peut empêcher le démarrage.

Timeout d’installation des skills et problèmes de dépendances

J’ai aussi eu des timeouts à l’installation de skills — surtout la première fois, attente interminable, on croit que tout est bloqué.

Diagnostiquez d’abord :

openclaw skill check <skill-name>

Cette commande indique l’état du skill et les erreurs détaillées.

Les logs Gateway aident aussi :

docker compose logs openclaw-gateway | grep -i "skill"

Problèmes de dépendances courants :

Problème A : binaire ou dépendance système manquante

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Certains skills exigent Go ou autre ; sans eux, le skill ne charge pas.

Si les logs signalent une dépendance, installez-la :

# Ex. Go manquant
sudo apt install golang-go

# Ou dépendances Python
sudo apt install python3-dev

Problème B : timeout réseau

Le plus fréquent. À la première installation, OpenClaw télécharge des dépendances ; réseau faible = timeout.

Symptômes : barre de progression figée, logs avec timeout ou connection refused.

Solution simple : réessayer.

openclaw skill install <skill-name>

En Chine, accélérez avec un miroir npm :

npm config set registry https://registry.npmmirror.com

Les miroirs Docker en Chine sont bien documentés ailleurs — je n’en développe pas ici.

Problème C : configuration OS incompatible

Certains skills sont testés sur une distro précise (ex. Ubuntu 22.04) ; autre distro = soucis possibles.

Consultez les GitHub Issues pour des contournements.

Astuce :

Les skills avec dépendances Go peuvent prendre 5 à 10 minutes la première fois — soyez patient. Tant que les logs défilent, c’est normal ; évitez Ctrl+C trop tôt.

Processus de dépannage systématique (diagnostic global)

Après tous ces cas concrets, voici un flux systématique. Perdu sur par où commencer ? Suivez cet ordre.

Commandes de diagnostic intégrées OpenClaw :

# État du service
openclaw status

# Health check
openclaw health

# Diagnostic complet (recommandé)
openclaw doctor

openclaw doctor vérifie automatiquement version Node.js, état Docker, clés API, ports occupés, etc., et produit un rapport.

Analyser les logs :

Ne vous laissez pas noyer par le volume ; concentrez-vous sur :

• Messages niveau ERROR — filtrez avec grep -i "error"
• La première erreur — les suivantes sont souvent en cascade
• Stack trace — localise la ligne de code en cause

Quand ouvrir une GitHub Issue ?

Si après ce parcours le problème persiste, vous avez peut-être un vrai bug.

Avant de poster, préparez :

• OS et version (Windows 11 + WSL2 Ubuntu 22.04 / macOS 14 / Ubuntu 22.04)
• Version Node.js (node -v)
• Version OpenClaw (openclaw --version)
• Logs d’erreur complets (en bloc de code)
• Étapes de reproduction

Plus c’est détaillé, plus les mainteneurs peuvent vous aider.

Conclusion

Récapitulatif rapide des sept catégories :

1. Version Node.js — nvm + Node 24 (ou au minimum v22.14+), aligné sur la doc officielle
2. Permissions npm — répertoire global dans le home, ou travail en répertoire natif WSL
3. Docker — logs d’abord ; souvent ressources ou conflit de port
4. Clés API — variables d’environnement, JSON, validité de la clé
5. Config WSL2 — wsl.conf, pas de dev cross-filesystem
6. Installation des skills — réessayer si timeout réseau, installer les dépendances manquantes
7. Dépannage systématique — openclaw doctor, puis contrôle ordonné

Installer OpenClaw demande un peu d’effort, mais chaque piège ne se prend qu’une fois. L’essentiel : une méthode de diagnostic — ne pas paniquer à la première erreur, identifier l’étape en cause, appliquer le bon correctif.

Gardez cette checklist ; la prochaine fois, vous irez plus vite. Si cet article vous a débloqué, partagez-le avec d’autres qui peinent sur OpenClaw.

Un cas non couvert ? Commentez — je mettrai à jour ce guide anti-embûches.