Si vous tentez de faire fonctionner OpenClaw (souvent désigné dans les versions dérivées ou les paquets communautaires sous le nom de Moltbot/Clawdbot) en local, le plus difficile n'est généralement pas de cloner le dépôt, mais de gérer les versions du runtime, les variables d'environnement et les problèmes de compilation spécifiques à la plateforme.
Ce guide vous offre un chemin d'installation pratique et multiplateforme, avec des étapes de débogage pour vous aider lorsque les choses tournent mal.
Ce qu'implique généralement la configuration d'OpenClaw
La plupart des distributions OpenClaw suivent le même modèle de déploiement :
- Cloner le code source depuis Git.
- Installer les dépendances de langage/runtime.
- Configurer un fichier
.env(jetons, base de données, clés API). - Initialiser le stockage (SQLite/Postgres/Redis selon la version).
- Exécuter les scripts de migration/amorçage.
- Démarrer le service et valider les points de terminaison de santé.
Même si votre version dérivée spécifique diffère, cette liste de contrôle correspond à presque toutes les installations.
Prérequis (tous systèmes d'exploitation)
Avant les étapes spécifiques à l'OS, confirmez ces bases :
- Git : pour le clonage et la récupération des mises à jour.
- Runtime : généralement Node.js (LTS) ou Python (3.10+), selon la version dérivée.
- Gestionnaire de paquets : npm/pnpm/yarn pour Node, pip/poetry pour Python.
- Base de données (facultatif) : SQLite pour un démarrage rapide en local, Postgres pour une utilisation en équipe/staging.
- Shell de terminal : PowerShell (Windows), zsh/bash (macOS/Linux).
Vérifiez vos outils
bash git --version node -v npm -v python3 --version pip --version
Si la documentation de votre projet spécifie des versions exactes, épinglez-les maintenant. La dérive de version est la principale cause des échecs d'installation de type "ça marche sur ma machine".
Installer OpenClaw sur macOS/Linux
Sur macOS ou Linux, exécutez l'installateur unifié :
curl -fsSL https://openclaw.ai/install.sh | bash
Pour les méthodes d'installation alternatives et les exigences système détaillées, consultez la section Installation.
1. Exécutez l'assistant d'intégration (Onboarding Wizard)
openclaw onboard --install-daemon
Cet assistant configure l'authentification, la passerelle et tous les canaux de messagerie optionnels (WhatsApp, Telegram, etc.).
Pour une présentation complète, consultez la documentation de l'assistant d'intégration.
2. Vérifiez la passerelle
Si vous avez installé le service d'arrière-plan (démon), il devrait déjà être en cours d'exécution. Vérifiez son statut avec :
openclaw gateway status
3. Ouvrez l'interface utilisateur de contrôle
Lancez le tableau de bord :
openclaw dashboard
Vous pouvez maintenant accéder à votre instance OpenClaw via l'interface utilisateur de contrôle basée sur le navigateur.
Installer OpenClaw sur Windows
Sur Windows (avec PowerShell), exécutez l'installateur unifié :
iwr -useb https://openclaw.ai/install.ps1 | iexPour les méthodes d'installation alternatives et les exigences système détaillées, consultez la section Installation.
1. Exécutez l'assistant d'intégration (Onboarding Wizard)
openclaw onboard --install-daemon
Cet assistant configure l'authentification, la passerelle et tous les canaux de messagerie optionnels (WhatsApp, Telegram, etc.).
Pour une présentation complète, consultez la documentation de l'assistant d'intégration.
2. Vérifiez la passerelle
Si vous avez installé le service d'arrière-plan (démon), il devrait déjà être en cours d'exécution. Vérifiez son statut avec :
openclaw gateway status
3. Ouvrez l'interface utilisateur de contrôle
Lancez le tableau de bord :
openclaw dashboard
Vous pouvez maintenant accéder à votre instance OpenClaw via l'interface utilisateur de contrôle basée sur le navigateur.
Installation basée sur Docker (recommandée pour la cohérence)
Si vous souhaitez moins de problèmes de dépendances au niveau de l'hôte, exécutez OpenClaw avec Docker Compose.
Exemple de modèle docker-compose.yml :
yaml version: '3.9' services: app: build: . ports: - "3000:3000" env_file: - .env depends_on: - db - redis
db: image: postgres:15 environment: POSTGRES_USER: openclaw POSTGRES_PASSWORD: openclaw POSTGRES_DB: openclaw ports: - "5432:5432"
redis: image: redis:7 ports: - "6379:6379"
Démarrer :
bash docker compose up --build
Cette approche offre des environnements reproductibles sur macOS, Windows et Linux, en particulier pour les équipes.
Erreurs d'installation courantes et corrections
1) Erreurs MODULE_NOT_FOUND ou d'importation
Cause : dépendances non installées, fichier de verrouillage incorrect ou runtime incompatible.
Correction :
- Supprimez
node_moduleset réinstallez avecnpm ci. - Faites correspondre le runtime à la documentation du projet (
.nvmrc,pyproject.toml,runtime.txt). - Ne mélangez pas les gestionnaires de paquets à moins que le dépôt ne le supporte.
2) Connexion à la base de données refusée
Cause : Le service de la base de données est arrêté ou DATABASE_URL est incorrect.
Correction :
- Confirmez l'état du service (
systemctl status postgresql,brew services list). - Validez l'hôte/port/utilisateur/mot de passe/nom de la base de données.
- Testez la connexion indépendamment avec
psql.
3) Port déjà utilisé
Correction : trouvez et arrêtez le processus en conflit.
macOS/Linux :
bash lsof -i :3000 kill -9
Windows :
powershell netstat -ano | findstr :3000 taskkill /PID /F
4) Permission refusée sur Linux/macOS
Cause : Le script manque de permission d'exécution.
bash chmod +x ./scripts/*.sh
Évitez d'exécuter les commandes de l'application avec sudo sauf si cela est absolument nécessaire.
5) Variable d'environnement non chargée
Correction :
- Assurez-vous que
.envest à la racine du projet. - Redémarrez le processus après une modification de
.env. - Vérifiez que le paquet de chargement (
dotenv) est initialisé tôt.
Liste de contrôle de durcissement post-installation
Une fois qu'OpenClaw démarre avec succès, effectuez ces vérifications avant de le partager avec vos coéquipiers :
- Changez les secrets par défaut.
- Appliquez des jetons API forts.
- Restreignez les URL CORS et de rappel.
- Définissez des niveaux de journalisation sécurisés pour la production.
- Ajoutez des sondes de santé/préparation.
- Configurez une stratégie de sauvegarde pour les volumes de la base de données.
Si vous l'exposez au-delà de localhost, placez-le derrière un proxy inverse (Nginx/Caddy) avec TLS.
Valider et tester rapidement les API OpenClaw
Après l'installation, vous devriez vérifier le comportement des points de terminaison – et pas seulement le démarrage du processus.
Un modèle rapide :
- Importez le fichier OpenAPI d'OpenClaw (si fourni).
- Créez des variables d'environnement pour les URL locales/de staging.
- Établissez des vérifications de régression pour l'authentification, le CRUD et les points de terminaison de webhook.
C'est là qu'Apidog aide à réduire les frictions. Vous pouvez concevoir, déboguer, tester et documenter des API dans un seul espace de travail, afin que la validation de la configuration ne s'éparpille pas entre plusieurs outils.
Flux de travail pratique dans Apidog :
- Importez le schéma et générez des collections de requêtes.
- Ajoutez des tests automatisés avec des assertions basées sur des scénarios.
- Simulez les dépendances manquantes avec des réponses dynamiques.
- Partagez des documents interactifs avec votre équipe une fois stable.
Si vous testez des versions dérivées d'OpenClaw avec des changements fréquents, ce flux de travail unique est plus rapide que de maintenir manuellement des scripts et des documents séparés.
Stratégie de mise à niveau pour les versions dérivées d'OpenClaw
Les versions dérivées (forks) de bots/outils open-source évoluent rapidement. Utilisez un chemin de mise à jour reproductible :
bash git fetch origin git checkout main git pull npm ci npm run migrate npm test npm run dev
Pour les versions Python :
bash pip install -r requirements.txt python manage.py migrate pytest
Utilisez des tests basés sur des branches avant de fusionner les modifications en amont. Si votre équipe utilise des contrats d'API, les vérifications de différence de schéma évitent les changements de rupture silencieux.
Réflexions finales
L'installation d'OpenClaw (Moltbot/Clawdbot) sur macOS, Windows ou Linux est simple une fois que vous maîtrisez trois variables : la version du runtime, la configuration de l'environnement et les dépendances du service.
Si vous installez pour une équipe, Docker Compose est généralement la base la plus fiable. Si vous installez pour le développement local, une configuration native convient – il suffit d'épingler les versions et de commiter les scripts d'intégration.
Une fois qu'OpenClaw est en cours d'exécution, considérez la validation de l'API comme faisant partie intégrante de l'installation réussie. Vous pouvez importer et tester les points de terminaison dans Apidog, créer des vérifications automatisées et maintenir la documentation synchronisée à mesure que votre version dérivée évolue.
Essayez-le gratuitement – aucune carte de crédit requise – et utilisez-le pour sécuriser votre flux de travail API OpenClaw, du premier démarrage aux tests de régression.