Installer OpenClaw : agent IA auto-hébergé sur Linux pas à pas

OpenClaw est un agent IA personnel que vous faites tourner sur votre propre machine : il lit et écrit des fichiers, lance des commandes, interroge des API et vous répond dans la messagerie que vous utilisez déjà. Avant de lui brancher un cerveau ou une messagerie, il faut l’installer proprement. C’est l’objet de ce tutoriel : partir d’une machine Linux vierge et obtenir un agent qui démarre, répond et survit aux redémarrages.

🎯 Ce que vous allez apprendre

• Préparer une machine Linux avec la bonne version de Node.js pour OpenClaw.
• Installer l’agent en une commande et lancer l’assistant d’onboarding.
• Comprendre où vivent la configuration et l’espace de travail de l’agent.
• Démarrer la passerelle (Gateway) comme service persistant et vérifier qu’elle tourne.
• Mettre à jour, arrêter et relancer l’agent en toute sécurité.

🛠️ Ce que vous allez construire

À la fin, vous aurez un agent OpenClaw installé en global, sa passerelle lancée en arrière-plan via un service système, et un répertoire de travail prêt à recevoir un modèle de langage et une messagerie. C’est la fondation de l’assistant personnel que la suite de la série va peu à peu équiper.

Prérequis

• Un Linux récent (Ubuntu 24.04 LTS ou Debian 12 conviennent), en local ou sur un petit serveur distant.
• Un accès terminal avec un utilisateur non-root disposant de sudo.
• Node.js 24 (recommandé) ou au minimum Node 22.19. OpenClaw refuse de démarrer sous une version trop ancienne.
• Niveau : débutant à l’aise en ligne de commande. Test express : si vous savez lancer ssh et éditer un fichier avec nano, vous êtes prêt.
• ⏱️ Temps estimé : ~25 minutes.

Étape 1 — Vérifier (ou installer) la bonne version de Node.js

OpenClaw est écrit en TypeScript et s’exécute sur Node.js. La contrainte de version n’est pas cosmétique : l’agent utilise des API récentes du runtime, et une version trop vieille provoque des erreurs obscures au démarrage. Commencez donc par contrôler ce qui est installé.

node --version
# Sortie attendue : v24.x.x  (ou au minimum v22.19.x)

Si la commande renvoie command not found ou une version inférieure à 22.19, installez une version moderne. La voie la plus souple est nvm, qui permet de cohabiter plusieurs versions sans toucher au Node du système.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
# Rechargez le shell, puis :
nvm install 24
nvm use 24
node --version   # doit afficher v24.x.x

Vous devez maintenant voir une version 24 (ou 22.19+). Si nvm n’est pas reconnu après l’installation, fermez puis rouvrez votre terminal : le script ajoute des lignes à votre ~/.bashrc qui ne sont chargées qu’à l’ouverture d’une nouvelle session.

✅ Point d’étape — node --version affiche v24 (ou ≥ v22.19) et npm --version répond sans erreur. Si ce n’est pas le cas, ne continuez pas : tout le reste en dépend.

Étape 2 — Installer OpenClaw en global

L’agent se distribue comme un paquet npm. On l’installe en global (-g) pour disposer de la commande openclaw partout dans le terminal. Le tag @latest garantit la dernière version stable publiée.

npm install -g openclaw@latest

Selon votre installation de Node, npm peut réclamer des droits pour écrire dans le répertoire global. Avec nvm, ce répertoire appartient à votre utilisateur : aucune élévation n’est nécessaire et c’est plus sûr que de préfixer par sudo. Si vous préférez un autre gestionnaire, OpenClaw s’installe aussi avec pnpm add -g openclaw@latest ou avec bun.

Vérifiez que la commande est disponible :

openclaw --version

Un numéro de version s’affiche : l’agent est installé. Tant que cette commande échoue, inutile d’aller plus loin — vérifiez que le dossier des binaires npm globaux est bien dans votre PATH.

Étape 3 — Lancer l’assistant d’onboarding

OpenClaw fournit un assistant interactif qui crée la configuration initiale, choisit le fournisseur de modèle et, surtout, installe la passerelle comme service système. Le drapeau --install-daemon est ce qui rend l’agent persistant : sans lui, la passerelle ne tournerait que tant que votre terminal reste ouvert.

openclaw onboard --install-daemon

L’assistant vous pose quelques questions (fournisseur de modèle, clé d’API, première messagerie). Vous pouvez tout valider par défaut pour l’instant : la configuration du modèle et de la messagerie est détaillée dans les tutoriels suivants. Ce qui compte ici, c’est qu’à la fin l’assistant ait écrit votre fichier de configuration et déclaré le service.

✅ Point d’étape — l’onboarding se termine sans erreur et mentionne la création d’un service (systemd sous Linux). Le fichier ~/.openclaw/openclaw.json doit désormais exister.

Étape 4 — Comprendre l’arborescence créée

Avant de manipuler l’agent, prenez deux minutes pour savoir où il range ses affaires. Tout vit sous ~/.openclaw/ dans votre dossier personnel. Connaître ces emplacements vous évitera de chercher à l’aveugle quand il faudra ajuster un réglage ou ajouter une compétence.

ls -la ~/.openclaw
# openclaw.json        -> la configuration principale (format JSON5, commentaires tolérés)
# workspace/           -> l'espace de travail de l'agent (fichiers, compétences)

Le fichier openclaw.json est le centre de gravité : channels, modèle, sécurité, tout y passe. L’espace de travail ~/.openclaw/workspace/ contient notamment le dossier skills/ (les compétences que l’agent sait exécuter) et accueille des fichiers d’instructions injectés dans le contexte de l’agent, comme AGENTS.md, SOUL.md et TOOLS.md. Vous n’avez rien à y modifier pour l’instant ; sachez simplement que c’est là que la personnalité et les capacités de l’agent se définissent.

Étape 5 — Démarrer et vérifier la passerelle

La passerelle (Gateway) est le plan de contrôle d’OpenClaw : elle gère les sessions, les messageries, les outils et les événements. C’est elle qui doit tourner en permanence pour que l’agent réponde. Si le service a été installé à l’étape 3, il démarre déjà ; vérifions-le explicitement.

openclaw gateway status

La commande indique si la passerelle est active. Si elle ne l’est pas, démarrez-la au premier plan le temps d’un test, ce qui affiche les journaux en direct et aide à diagnostiquer un éventuel problème de configuration :

openclaw gateway

Vous voyez défiler les lignes de démarrage : chargement de la configuration, initialisation des channels, passerelle en écoute. Coupez avec Ctrl+C une fois que vous avez confirmé qu’elle démarre — le service système prendra le relais en arrière-plan. Pour piloter finement la passerelle, les sessions et les commandes intégrées, reportez-vous au tutoriel Piloter OpenClaw en ligne de commande.

✅ Point d’étape — openclaw gateway status rapporte une passerelle active. Votre agent est techniquement « en ligne » ; il lui manque encore un modèle et une messagerie, que nous ajoutons dans les tutoriels suivants.

Étape 6 — Mettre à jour, arrêter, relancer

Un agent auto-hébergé se maintient. OpenClaw publie sur plusieurs canaux de distribution, et vous restez maître de quand mettre à jour. Cette commande récupère la dernière version du canal choisi.

openclaw update --channel stable
# Canaux disponibles : stable | beta | dev

Restez sur stable pour un usage quotidien ; beta et dev sont réservés aux tests des nouveautés. Pour arrêter proprement la passerelle (par exemple avant une maintenance), utilisez :

openclaw gateway stop

Après une mise à jour ou un changement de configuration, relancez la passerelle pour que les modifications soient prises en compte. La règle est simple : on édite openclaw.json, on relance la passerelle, on vérifie le statut.

Étape 7 — Vérification finale de bout en bout

Bouclez l’installation par un contrôle qui prouve que tout est en place. Ces trois commandes constituent votre routine de diagnostic à garder sous la main.

openclaw --version          # l'agent est installé
openclaw gateway status     # la passerelle tourne
ls ~/.openclaw/openclaw.json # la configuration existe

Si les trois répondent correctement, la fondation est posée. La prochaine étape logique consiste à donner un cerveau à l’agent en branchant un modèle de langage, puis à le rendre joignable depuis une messagerie.

🐞 Pièges fréquents

🌍 Déployer à moindre coût

Pas besoin d’une grosse machine. OpenClaw tourne très bien sur un VPS d’entrée de gamme (1 vCPU, 1 à 2 Go de RAM) facturé quelques milliers de FCFA par mois, le calcul lourd étant délégué au modèle de langage distant via API. Si votre connexion locale est intermittente ou si l’électricité coupe, héberger l’agent sur un petit serveur distant garantit qu’il reste joignable jour et nuit, pendant que vous le pilotez depuis votre téléphone. Beaucoup d’hébergeurs acceptent un règlement par mobile money, ce qui évite d’avoir une carte internationale. Surveillez surtout votre consommation d’API, facturée à l’usage par le fournisseur du modèle : c’est là, et non sur le serveur, que se situe le vrai coût.

✅ Récapitulatif

Vous êtes parti d’une machine vierge et vous avez : vérifié Node, installé OpenClaw en global, lancé l’onboarding avec service persistant, situé la configuration et l’espace de travail, démarré et vérifié la passerelle, puis appris à mettre à jour et relancer. L’agent est « vivant » mais encore muet et sourd : il lui faut un modèle (son cerveau) et une messagerie (sa bouche et ses oreilles), ce que couvrent les tutoriels suivants.

🧾 Aide-mémoire

💪 À vous de jouer

Défi : faites en sorte que la passerelle redémarre automatiquement si le serveur reboote, et confirmez-le sans redémarrer manuellement la machine.

systemctl --user enable openclaw       # ou le nom exact affiché par l'onboarding
systemctl --user status openclaw

Tutoriels frères

• Configurer un modèle LLM dans OpenClaw (Claude, GPT, DeepSeek) — donner un cerveau à l’agent.
• Connecter OpenClaw à Telegram — rendre l’agent joignable depuis votre téléphone.

Pour aller plus loin

• 🔝 Retour au guide principal : OpenClaw, panorama et mise en route.
• Dépôt officiel et documentation : github.com/openclaw/openclaw et docs.openclaw.ai.

Local ou serveur distant : que choisir ?

La même installation fonctionne sur votre poste de travail comme sur un serveur loué, mais le choix a des conséquences concrètes. Sur votre machine, vous gardez tout sous la main et ne payez rien d’autre que l’API du modèle ; en revanche, l’agent ne répond que lorsque l’ordinateur est allumé et connecté. Sur un serveur distant, l’agent devient un service joignable en permanence, ce qui est le vrai intérêt d’un assistant personnel : lui écrire un message depuis votre téléphone à 23 h et obtenir une réponse même si votre poste est éteint.

La bascule recommandée est progressive : faites vos premiers pas en local pour comprendre l’outil sans risque, puis répliquez l’installation sur un petit serveur une fois que la configuration vous satisfait. Comme tout vit dans ~/.openclaw/, migrer revient essentiellement à reproduire les étapes de ce tutoriel sur la nouvelle machine et à recopier votre openclaw.json — en régénérant les clés d’API et les jetons de messagerie plutôt qu’en les copiant tels quels, par hygiène de sécurité.

Comprendre le « cerveau » et la « personnalité » de l’agent

L’espace de travail contient des fichiers d’instructions qui ne sont pas du code mais du texte en langage naturel, injecté dans le contexte de l’agent à chaque échange. C’est ce qui distingue un agent d’un simple appel d’API. Les trois principaux méritent qu’on sache à quoi ils servent, même si on ne les édite pas tout de suite.

• AGENTS.md — les règles de travail de l’agent : comment il doit raisonner, quelles conventions suivre, ce qu’il a le droit de faire.
• SOUL.md — la « personnalité » : ton, style, préférences de réponse. C’est ici qu’on rend l’assistant concis ou pédagogue.
• TOOLS.md — des notes sur les outils disponibles et la manière de les employer.

Retenez surtout le principe : modifier le comportement de l’agent passe davantage par ces fichiers d’instructions et par les compétences (le dossier skills/) que par du développement classique. Nous y reviendrons en détail au moment d’écrire une compétence sur mesure.

FAQ

Faut-il installer OpenClaw en root ?
Non, et c’est même déconseillé. Installez Node via nvm sous votre utilisateur courant : l’agent et ses fichiers restent dans votre dossier personnel, ce qui limite les dégâts en cas de problème.

OpenClaw fonctionne-t-il sur macOS ou Windows ?
Oui, le projet est multiplateforme. La logique d’installation par npm est identique ; seul le mécanisme de service en arrière-plan diffère (launchd sur macOS, par exemple). Ce tutoriel cible Linux, le terrain le plus courant pour un agent auto-hébergé en continu.

Combien coûte OpenClaw ?
Le logiciel est libre et gratuit (licence MIT). Le coût réel vient de l’API du modèle de langage que vous y branchez, facturée à l’usage par le fournisseur.

Dois-je laisser mon ordinateur allumé en permanence ?
Seulement si vous voulez que l’agent reste joignable. Pour une disponibilité continue sans laisser votre poste allumé, hébergez la passerelle sur un petit serveur distant.