OpenClaw
Dépannage15 min de lecture

Erreurs courantes d'OpenClaw et comment les corriger

Guide complet pour diagnostiquer et corriger les erreurs courantes d'OpenClaw, y compris les problemes d'installation, les erreurs API, les problemes de canaux et les problemes de performance.

O

OpenClaw Guides

Tutorial Authors

Diagnostics rapides

Avant de plonger dans les erreurs specifiques, executez ces diagnostics :

bash
# Verifier le statut general
openclaw status

# Verifier la configuration
openclaw config validate

# Verifier les logs pour les erreurs recentes
openclaw logs --tail 50 --level error

# Executer une verification de sante
openclaw doctor

Erreurs d'installation

Erreur : "Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

Solution :

bash
# En utilisant nvm (recommande)
nvm install 22
nvm use 22
nvm alias default 22

# Ou en utilisant Homebrew (macOS)
brew install node@22

# Verifier
node --version  # Devrait afficher v22.x.x

Erreur : "EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solution : N'utilisez pas sudo. Corrigez plutot les permissions npm :

bash
# Option 1 : Utiliser nvm (recommande)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Option 2 : Changer le repertoire par defaut de npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Puis reinstaller
npm install -g openclaw@latest

Erreur : "Cannot find module"

Error: Cannot find module '@openclaw/core'

Solution :

bash
# Vider le cache npm et reinstaller
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# Ou utiliser le script d'installation
curl -fsSL https://openclaw.ai/install.sh | bash

Erreur : "gyp ERR! build error" (Modules natifs)

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Solution : Installez les outils de compilation :

bash
# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

Erreurs API et authentification

Erreur : "401 Unauthorized"

Error: API request failed with status 401: Invalid API key

Solution :

bash
# Verifier que votre cle API est definie
openclaw config get api-key

# Si vide ou incorrecte, la redefinir
openclaw config set api-key

# Verifier le format de la cle (les cles Anthropic commencent par sk-ant-)
# Assurez-vous qu'il n'y a pas d'espaces ou de guillemets supplementaires

Erreur : "429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

Solution :

json
// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

Pour une limitation de debit persistante, envisagez de passer a un niveau API superieur ou d'utiliser un modele different :

bash
openclaw config set default-model claude-3-5-haiku

Erreur : "402 Payment Required"

Error: API request failed: Insufficient credits

Solution :

  1. Verifiez le solde de votre fournisseur API
  2. Ajoutez des credits a votre compte
  3. Ou configurez des limites d'utilisation :
json
// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

Erreur : "Connection Refused" vers l'API

Error: connect ECONNREFUSED api.anthropic.com:443

Solution :

bash
# Verifier la connexion internet
ping api.anthropic.com

# Verifier si derriere un proxy
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Configurer le proxy si necessaire
openclaw config set proxy http://your-proxy:8080

# Ou verifier les parametres du pare-feu/VPN

Erreurs de passerelle

Erreur : "EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

Solution :

bash
# Trouver ce qui utilise le port
lsof -i :18789

# Terminer le processus
kill -9 <PID>

# Ou utiliser un port different
openclaw gateway start --port 18790

# Mettre a jour la configuration pour utiliser le nouveau port
openclaw config set gateway-port 18790

Erreur : "Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

Solution :

bash
# Valider la syntaxe du fichier de configuration
openclaw config validate

# Si corrompu, reinitialiser aux valeurs par defaut
openclaw config reset --confirm

# Puis reconfigurer
openclaw onboard

Erreur : "Gateway not responding"

bash
# Verifier si la passerelle fonctionne
openclaw status

# Si arretee, verifier pourquoi
openclaw logs --tail 100

# Essayer de redemarrer
openclaw gateway restart

# Si ca echoue toujours, verifier les ressources systeme
free -h  # Memoire
df -h    # Espace disque

Erreurs specifiques aux canaux

WhatsApp : "Session expired"

Error: WhatsApp session invalid or expired

Solution :

bash
# Re-authentifier
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# Scanner le nouveau QR code

WhatsApp : "QR code not generating"

bash
# Verifier si une autre session est active
pkill -f "openclaw.*whatsapp"

# Effacer les anciennes donnees de session
rm -rf ~/.openclaw/whatsapp-session

# Reessayer
openclaw channel connect whatsapp

Telegram : "Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

Une autre instance utilise le meme token de bot.

Solution :

bash
# Arreter toutes les instances OpenClaw
pkill -f openclaw

# Verifier les autres instances en cours
ps aux | grep openclaw

# Demarrer a nouveau
openclaw gateway start

Discord : "Invalid token"

Error: An invalid token was provided

Solution :

bash
# Regenerer le token dans le portail developpeur Discord
# Bot → Reset Token

# Mettre a jour OpenClaw
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord : "Missing intents"

Error: Disallowed intents specified

Solution :

  1. Allez sur le portail developpeur Discord
  2. Selectionnez votre application → Bot
  3. Activez les intents requis sous "Privileged Gateway Intents"
  4. Sauvegardez et redemarrez OpenClaw

Erreurs de memoire et de performance

Erreur : "JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solution :

bash
# Augmenter la limite de memoire Node.js
export NODE_OPTIONS="--max-old-space-size=4096"

# Ajouter a votre profil shell pour la persistance
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# Redemarrer OpenClaw
openclaw gateway restart

Erreur : "Too many open files"

Error: EMFILE: too many open files

Solution :

bash
# Verifier la limite actuelle
ulimit -n

# Augmenter la limite (temporaire)
ulimit -n 65535

# Augmenter la limite (permanent - Linux)
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

Temps de reponse lents

Diagnostiquer :

bash
# Verifier la latence du modele
openclaw benchmark

# Verifier les ressources systeme
openclaw stats

Solution :

json
// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

Erreurs de configuration

Erreur : "Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

Solution :

bash
# Valider le YAML
openclaw config validate

# Problemes courants :
# - Tabulations au lieu d'espaces (utilisez 2 espaces)
# - Deux-points manquants apres les cles
# - Caracteres speciaux non echappes

# Corriger ou reinitialiser
openclaw config edit
# ou
openclaw config reset --confirm

Erreur : "Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

Solution :

bash
# Verifier les options disponibles
openclaw config list

# Supprimer les cles inconnues
openclaw config edit

Erreur : "Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

Solution :

bash
# Ajouter au fichier .env
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# Ou exporter dans le shell
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Ajouter au profil shell pour la persistance
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

Erreurs de base de donnees et de stockage

Erreur : "Database locked"

Error: SQLITE_BUSY: database is locked

Solution :

bash
# Arreter OpenClaw
openclaw gateway stop

# Verifier les fichiers de verrouillage
ls -la ~/.openclaw/*.lock

# Supprimer les verrouillages obsoletes
rm ~/.openclaw/*.lock

# Redemarrer
openclaw gateway start

Erreur : "Disk quota exceeded"

Error: ENOSPC: no space left on device

Solution :

bash
# Verifier l'utilisation du disque
df -h

# Nettoyer les logs et le cache OpenClaw
openclaw cache clear
openclaw logs clear --older-than 7d

# Nettoyer les anciennes sessions
rm -rf ~/.openclaw/sessions/*.old

Obtenir plus d'aide

Activer les logs de debogage

bash
# Definir le mode debug
export OPENCLAW_DEBUG=true
openclaw gateway start

# Ou dans la configuration
openclaw config set logLevel debug

Generer un rapport de diagnostic

bash
openclaw doctor --report > diagnostic-report.txt

Support communautaire

Soumettre un rapport de bug

Lors du signalement de problemes, incluez :

bash
# Informations systeme
openclaw --version
node --version
uname -a

# Configuration (masquer les donnees sensibles)
openclaw config show --redact

# Logs recents
openclaw logs --tail 100

Prochaines etapes