Accueil › OpenClaw › Installation

OpenClaw Installation : déployer votre assistant IA personnel

OpenClaw est un assistant IA personnel open source (MIT) que vous hébergez sur vos propres appareils. Il se connecte à vos apps de messagerie (WhatsApp, Telegram, Discord, Slack, Signal, iMessage et 15+ autres), tourne en continu en arrière-plan, et exécute des tâches réelles : fichiers, navigateur, shell, cron, webhooks. L’installation prend environ 30 minutes, dont 5 pour le CLI et 25 pour la configuration des canaux.

Comprendre l’architecture avant d’installer

OpenClaw n’est pas un chatbot dans un navigateur. C’est un runtime d’agent qui tourne en permanence sur votre machine. Comprendre son architecture vous évitera des erreurs de configuration.

Au centre se trouve le Gateway : un processus Node.js toujours actif qui gère les sessions, le routage des canaux, le dispatch des outils et les événements. C’est le plan de contrôle. Il écoute sur un WebSocket local (ws://127.0.0.1:18789).

Autour du Gateway, trois couches s’articulent. Les canaux connectent vos apps de messagerie (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, etc.). Les outils donnent à l’agent des capacités système : navigateur via Playwright, accès au filesystem, exécution shell, cron jobs, webhooks, caméra/écran. Les skills étendent les capacités avec des workflows spécialisés (email, analyse de données, contrôle domotique, etc.).

Quand un message arrive sur un canal, le Gateway le route vers une session d’agent, qui invoque le LLM configuré (Claude, GPT, modèle local), exécute éventuellement des outils ou skills, et renvoie la réponse par le canal d’origine. Toute la boucle prend quelques secondes.

Prérequis

Système

Vérifiez votre version de Node.js :

node --version
# Doit retourner v22.x.x ou supérieur

Si Node.js n’est pas installé ou est trop ancien, le one-liner d’installation le détecte et l’installe automatiquement.

Clé API ou modèle local

OpenClaw a besoin d’un fournisseur LLM pour fonctionner. Trois options principales :

Anthropic (recommandé) : clé API commençant par sk-ant-... depuis la console Anthropic. Ou authentification OAuth avec un abonnement Claude Pro/Max. Claude Opus 4.6 donne les meilleurs résultats, Sonnet 4.6 offre un bon équilibre coût/qualité.

OpenAI : clé API depuis la plateforme OpenAI, ou OAuth avec un abonnement Codex.

Modèle local : via Ollama pour une expérience 100% locale sans frais API. La qualité dépend du modèle et de votre matériel.

Méthode 1 : One-liner (recommandé)

C’est la méthode la plus simple. Un script unique gère la détection de Node.js, l’installation et le lancement du wizard d’onboarding.

macOS et Linux

curl -fsSL https://openclaw.ai/install.sh | bash

Le script installe OpenClaw, puis lance automatiquement le wizard d’onboarding interactif. Suivez les étapes :

1. Avertissement de sécurité. OpenClaw vous informe qu’il a un accès réel à votre système. Lisez les risques, puis sélectionnez « Yes » pour continuer.

2. Mode d’installation. Choisissez Quick Start pour aller vite, ou Manual pour un contrôle total.

3. Fournisseur IA. Sélectionnez Anthropic API Key (recommandé), OpenAI API Key, OAuth (abonnement Claude Pro/Max), ou Ollama pour du local.

4. Modèle par défaut. Choisissez votre modèle. Claude Opus 4.6 donne la meilleure qualité, Sonnet 4.6 est plus économique.

5. Canaux. Configurez vos canaux de messagerie. Vous pouvez sauter cette étape et les ajouter plus tard. Telegram est le plus rapide à configurer (juste un token de bot).

6. Skills. Le wizard propose d’installer des skills. Sélectionnez « No » pour l’instant : vous pourrez les ajouter plus tard une fois que vous aurez expérimenté.

7. Daemon. Le wizard enregistre OpenClaw comme service en arrière-plan via launchd (macOS) ou systemd (Linux).

Windows

Windows ne supporte pas OpenClaw nativement. WSL2 est requis.

# Dans PowerShell (Administrateur)
iwr -useb https://openclaw.ai/install.ps1 | iex

Ou installez via WSL2 :

# Dans le terminal WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

Méthode 2 : npm / pnpm

Pour ceux qui préfèrent un contrôle explicite sur l’installation.

# Via npm
npm install -g openclaw@latest

# Ou via pnpm (recommandé)
pnpm add -g openclaw@latest

# Vérifier l'installation
openclaw --version

# Lancer l'onboarding avec daemon
openclaw onboard --install-daemon

Si vous rencontrez des erreurs de permissions EACCES (fréquent sur macOS) :

# Créer un répertoire dédié pour npm global
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Réinstaller
npm install -g openclaw@latest

Méthode 3 : Docker (meilleure isolation)

Docker est la méthode recommandée pour les déploiements qui nécessitent une isolation complète. Le container empêche un agent compromis d’affecter votre système hôte.

Installation rapide avec le script

# Cloner le repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Lancer le setup (build + onboarding automatique)
./scripts/docker/setup.sh

Pour utiliser une image pré-construite au lieu de builder localement :

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Les images pré-construites sont publiées sur le GitHub Container Registry. Tags courants : main, latest, <version> (ex: 2026.3.11).

Docker Compose

# Onboarding dans le container
docker compose run --rm openclaw-cli onboard

# Démarrer le Gateway
docker compose up -d openclaw-gateway

# Connecter WhatsApp (QR code)
docker compose run --rm openclaw-cli channels login

# Connecter Telegram
docker compose run --rm openclaw-cli channels add 
  --channel telegram --token "VOTRE_TOKEN_BOT"

Persistance des données

Docker Compose bind-mount automatiquement OPENCLAW_CONFIG_DIR vers /home/node/.openclaw et OPENCLAW_WORKSPACE_DIR vers /home/node/.openclaw/workspace. Ces chemins survivent au remplacement du container.

Points de surveillance pour la croissance du disque : le dossier media/, les fichiers de session JSONL, les logs de cron dans cron/runs/*.jsonl, et les logs rotatifs sous /tmp/openclaw/.

Pour le sandboxing à l’intérieur de Docker :

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

Méthode 4 : Depuis les sources

Pour les développeurs qui veulent contribuer ou personnaliser OpenClaw.

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Avec pnpm (recommandé)
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon

# Mode développement avec rechargement automatique
pnpm gateway:watch

Après le build, pnpm link --global rend la commande openclaw disponible globalement.

Vérification post-installation

Après l’installation, trois commandes pour valider que tout fonctionne.

# 1. Vérifier le status du Gateway
openclaw gateway status
# Doit afficher : Gateway listening on ws://127.0.0.1:18789

# 2. Ouvrir le dashboard (Control UI)
openclaw dashboard
# S'ouvre dans le navigateur. Si ça charge, tout fonctionne.

# 3. Diagnostic complet
openclaw doctor
# Vérifie l'installation, les permissions, les canaux

Tapez un message dans le chat du Control UI. Si vous recevez une réponse IA, l’installation est complète.

Connecter votre premier canal

Le canal le plus rapide à configurer est Telegram : vous avez juste besoin d’un token de bot via @BotFather. WhatsApp est le plus populaire mais nécessite de scanner un QR code via Linked Devices.

# Telegram : avec un token de bot
openclaw channels add --channel telegram --token "VOTRE_TOKEN"

# WhatsApp : scan du QR code
openclaw channels login

# Discord : avec un token de bot
openclaw channels add --channel discord --token "VOTRE_TOKEN"

Par défaut, OpenClaw utilise un système d’appairage (pairing) pour empêcher les accès non autorisés. Quand quelqu’un vous écrit pour la première fois, il doit fournir un code d’appairage avant de pouvoir interagir avec l’agent.

Gestion du Gateway

# Démarrer le Gateway
openclaw gateway start

# Arrêter
openclaw gateway stop

# Redémarrer (après changement de config)
openclaw gateway restart

# Status
openclaw gateway status

# Mettre à jour OpenClaw
openclaw update

# Prévisualiser la mise à jour sans l'appliquer
openclaw update --dry-run

# Changer de canal de release
openclaw update --channel stable|beta|dev

# Sauvegarde
openclaw backup create

# Diagnostic
openclaw doctor
openclaw doctor --fix

La configuration d’OpenClaw est stockée dans ~/.openclaw/openclaw.json. Vous pouvez surcharger les chemins avec les variables d’environnement OPENCLAW_HOME, OPENCLAW_STATE_DIR, et OPENCLAW_CONFIG_PATH.

Configuration du modèle IA

OpenClaw supporte plusieurs fournisseurs LLM. Voici les modèles recommandés par cas d’usage.

Le profil d’outils (tools profile) dans la config détermine les capacités de l’agent. Trois niveaux : messaging (chat seul), coding (fichiers + shell), full (tout activé, y compris navigateur). Si votre agent répond mais ne lit jamais de fichiers ni n’exécute de commandes, vérifiez que tools.profile n’est pas sur messaging.

Dépannage courant

Erreur EACCES lors de npm install

Problème de permissions du répertoire npm global, fréquent sur macOS. Solution : créez un répertoire dédié avec mkdir ~/.npm-global et reconfigurez le prefix npm (voir section npm ci-dessus).

Le wizard onboard plante ou échoue

Relancez openclaw onboard : vous pouvez refaire uniquement l’étape qui a échoué. Si le Gateway se comporte bizarrement, lancez openclaw doctor --fix pour les migrations et corrections automatiques.

L’agent répond mais n’exécute rien

Le profil d’outils est probablement sur messaging (chat seul). Modifiez la config pour passer en full : "tools": { "profile": "full" }.

Problèmes réseau / API inaccessible

Les APIs Anthropic et OpenAI nécessitent un accès internet sortant. Si vous êtes derrière un proxy, configurez HTTPS_PROXY et HTTP_PROXY. Vérifiez que votre clé API est valide avec openclaw doctor.

WhatsApp ne se connecte pas

Le QR code expire rapidement. Relancez openclaw channels login et scannez immédiatement. Assurez-vous que WhatsApp sur votre téléphone est à jour. Si la connexion se coupe régulièrement, votre téléphone doit rester connecté à internet (WhatsApp Linked Devices nécessite le téléphone principal en ligne).

Déploiement sur VPS

Pour un assistant disponible 24/7 sans laisser un ordinateur allumé en permanence, un VPS (Virtual Private Server) est l’option la plus fiable. Un serveur à 5-10 $/mois chez DigitalOcean, Hetzner ou OVH suffit largement.

Configuration recommandée

Un VPS avec 2 vCPU, 2 Go de RAM et 40 Go de stockage SSD convient pour un usage personnel. Si vous utilisez le navigateur Playwright pour l’automatisation web, montez à 4 Go de RAM. L’image Docker est la méthode d’installation recommandée pour les VPS car elle offre une isolation complète.

# Sur votre VPS fraîchement provisionné
apt update && apt install -y docker.io docker-compose-v2

# Installer OpenClaw via Docker
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh

Pour l’accès distant au dashboard, deux options principales : Tailscale Serve/Funnel pour un accès sécurisé sans configuration de reverse proxy, ou un reverse proxy Nginx/Caddy avec TLS pour un accès via votre propre domaine.

Mac Mini comme serveur dédié

Un Mac Mini M1/M2 est une option intéressante pour les utilisateurs Apple. Faible consommation électrique, silencieux, performance suffisante. Les images Docker officielles d’OpenClaw supportent nativement ARM64 (Apple Silicon) sans traduction Rosetta. Plusieurs utilisateurs rapportent des mois de fonctionnement stable sur Mac Mini.

Prochaines étapes

Une fois OpenClaw installé et votre premier canal connecté, explorez ces guides pour aller plus loin :

Configurez WhatsApp ou Telegram en profondeur. Installez vos premières skills pour étendre les capacités de l’agent. Comprenez les modèles supportés et optimisez le rapport qualité/coût. Sécurisez votre déploiement avec le guide sécurité. Et si vous avez besoin d’isolation, déployez avec Docker.

Questions fréquentes