La plupart des guides d'installation OpenClaw s'arrêtent à `npm install` et une capture d'écran du wizard. Résultat : vous avez un agent qui tourne, mais qui répond de manière générique, sans personnalité, et avec des configurations de sécurité qui laisseraient n'importe quel ops tech lever les yeux au ciel.
Ce guide couvre l'installation de bout en bout — prérequis, 3 méthodes selon votre profil, onboarding pas à pas, sécurité production, soul.md et MEMORY.md, erreurs courantes et coûts réels. À la fin, vous avez un agent fonctionnel, sécurisé, et avec une vraie identité. Si vous n'avez pas encore lu notre article sur ce qu'est OpenClaw et comment ça marche, commencez par là — ça vous évitera des questions en cours de route.
Pas de surprise désagréable au milieu de l'installation. Trois prérequis, dans l'ordre d'importance.
Node.js 22 minimum — le prérequis non-négociable
C'est la cause numéro 1 des échecs d'installation, de loin. Vérifiez votre version avant tout : `node -v`. Si vous voyez v20.x.x ou moins, mettez à jour. La façon la plus propre est via nvm (Node Version Manager), qui n'interfère pas avec votre environnement existant :
`curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash` puis `nvm install 22 && nvm use 22`. Vérifiez ensuite : `node -v` doit afficher v22.x.x. Et mettez npm à jour tant qu'on y est : `npm install -g npm@latest`.
Une clé API LLM
Depuis janvier 2026, l'authentification OAuth d'Anthropic a été coupée. La seule façon de connecter OpenClaw à Claude est une clé API pay-as-you-go. Si vous partez sur Anthropic (recommandé) : rendez-vous sur console.anthropic.com → Settings → API Keys → Create Key. Copiez-la immédiatement — elle n'est affichée qu'une seule fois. OpenAI, Gemini, Mistral et les modèles locaux via Ollama sont aussi supportés.
Une machine dédiée — le point le plus ignoré
OpenClaw a accès à votre terminal, vos fichiers, et potentiellement votre navigateur. Le déployer sur votre machine de travail principale avec vos clés SSH, vos credentials clients et vos fichiers sensibles n'est pas une bonne idée. L'idéal : un Mac mini, un Raspberry Pi, ou un VPS à 5–10€/mois dédié. Vous lui donnez accès complet sans risque. C'est un investissement de 5€/mois qui vous évite des situations inconfortables.
Prérequis validés — passons à l'installation.
Trois voies selon votre profil. La méthode 1 couvre 95% des cas. Les méthodes 2 et 3 sont pour des contextes spécifiques.
Méthode 1 — Le script officiel (recommandée)
C'est le chemin recommandé par la doc officielle. Le script détecte automatiquement votre OS, installe les dépendances manquantes, et lance le wizard d'onboarding. Temps estimé : moins de 5 minutes.
macOS / Linux / WSL2 : `curl -fsSL https://openclaw.ai/install.sh | bash`. Windows PowerShell : `iwr -useb https://openclaw.ai/install.ps1 | iex`.
Méthode 2 — npm / pnpm (si Node 22+ déjà installé)
Si Node 22 est déjà en place et que vous préférez passer par npm : `npm install -g openclaw@latest` puis `openclaw onboard --install-daemon`. Avec pnpm : `pnpm add -g openclaw@latest`, `pnpm approve-builds -g`, puis `openclaw onboard --install-daemon`.
Erreur fréquente sur macOS si vous avez libvips installé sur votre système : le build de sharp peut échouer. Solution : `SHARPIGNOREGLOBAL_LIBVIPS=1 npm install -g openclaw@latest`.
Méthode 3 — Depuis les sources (contributeurs et configurations custom)
`git clone https://github.com/openclaw/openclaw.git`, puis `cd openclaw`, `pnpm install`, `pnpm ui:build`, `pnpm build`, `pnpm link --global`, et enfin `openclaw onboard --install-daemon`. Cette voie est utile si vous voulez modifier le code source — c'est ce qu'on fait chez Volteyr pour certaines personnalisations internes. Pour 95% des cas d'usage, les méthodes 1 ou 2 suffisent.
Installation terminée. Le wizard d'onboarding prend le relais.
La commande `openclaw onboard --install-daemon` lance un wizard interactif (TUI ou Web UI selon votre préférence). Il configure quatre choses dans l'ordre.
1. Le provider LLM et la clé API
Choisissez votre provider dans le wizard. Pour Anthropic, deux options : directement dans l'interface TUI, ou via variable d'environnement (plus sécurisé). Méthode recommandée : `export ANTHROPICAPIKEY="sk-ant-api03-..."` dans votre terminal. Pour la rendre permanente : `echo 'export ANTHROPICAPIKEY="sk-ant-api03-..."' >> ~/.zshrc` puis `source ~/.zshrc`.
2. Le canal de messagerie
Telegram est le plus simple à configurer. Procédure : ouvrez @BotFather sur Telegram, tapez `/newbot`, donnez un nom et un username à votre bot, copiez le token API fourni, collez-le dans le wizard. C'est tout. Pour Slack, la procédure est plus longue (création d'une app Slack, configuration des OAuth scopes `chat:write`, `im:history`, `im:read`) — la doc officielle sur docs.openclaw.ai/channels détaille ça étape par étape.
3. Le workspace
Le wizard crée votre dossier de travail (`~/.openclaw/` par défaut) avec les fichiers fondamentaux : `agents.md` (configuration de l'agent), `soul.md` (personnalité et mémoire long terme — on y revient en section 5), `HEARTBEAT.md` (ce que l'agent vérifie proactivement), et `TOOLS.md` (les outils autorisés).
4. Installation du daemon
Le flag `--install-daemon` installe OpenClaw comme service système : LaunchAgent sur macOS (démarrage automatique au login), service systemd sur Linux. Résultat : votre agent tourne en permanence en arrière-plan, même quand vous ne l'utilisez pas.
Vérifier que tout fonctionne
Lancez `openclaw gateway status`. Puis ouvrez le dashboard : `openclaw dashboard` ou directement `http://127.0.0.1:18789/` depuis la machine hôte. Dans votre Telegram ou Slack, envoyez `/status` à votre bot — il doit répondre avec le modèle actif et l'état de la session. Si quelque chose ne fonctionne pas, `openclaw doctor` identifie et propose de corriger la majorité des configurations mal initialisées.
Agent démarré, connexion vérifiée. Avant de passer à soul.md, trois points de sécurité non-négociables.
La plupart des guides passent cette partie en deux lignes. C'est une erreur — OpenClaw est installé avec un accès étendu à votre machine, et mal configuré, c'est un risque opérationnel réel.
1. Fixer le binding réseau
Par défaut, OpenClaw bind sur `0.0.0.0` — n'importe quelle machine sur votre réseau local peut accéder à votre interface. Ce comportement est documenté dans la GitHub Issue #5263, fermée par les mainteneurs sans correction prévue. Corrigez-le manuellement dans `~/.openclaw/openclaw.json` : forcez `"bind": "loopback"` avec le port 18789. Redémarrez OpenClaw. L'accès est désormais restreint à localhost uniquement.
2. Configurer les tool policies
C'est le point le plus important pour un déploiement en entreprise. Définissez précisément ce que l'agent peut faire sans vous demander. Configuration raisonnable pour démarrer : lire des fichiers, des emails, des données CRM → autonome. Envoyer un email, créer un événement Calendar, modifier un fichier → approbation requise. Exécuter des commandes shell → approbation requise, limité au workspace dédié. La doc officielle sur docs.openclaw.ai/tools détaille la syntaxe complète des tool policies.
3. Vérifier les skills ClawHub avant de les installer
Une analyse Snyk a identifié que 13–17% des skills disponibles sur ClawHub contiennent des problèmes de sécurité significatifs. Avant d'installer une skill : lisez le code source (format YAML + Markdown, 2 minutes max), vérifiez les permissions demandées (une skill de traduction n'a aucune raison d'accéder à vos clés SSH), et privilégiez les skills officielles ou très bien notées. Notre approche chez Volteyr : on crée nos skills nous-mêmes — on décrit notre workflow à l'agent en langage naturel et on lui demande de générer la skill. Le résultat est toujours plus adapté à notre contexte, et on sait exactement ce qu'elle fait. Traitez aussi toujours le contenu lu sur le web ou dans des emails comme non-fiable — la prompt injection via email malveillant est le vecteur d'attaque le plus courant sur OpenClaw.
soul.md est le fichier le plus important de votre installation OpenClaw. Bien construit dès le départ, il fait la différence entre un bot générique et un vrai collaborateur.
Sécurité en place. La vraie valeur d'OpenClaw commence maintenant — dans soul.md.
Une fois OpenClaw installé, la plupart des gens envoient un premier message à leur bot Telegram, reçoivent une réponse générique, et concluent que c'est juste un ChatGPT qu'on héberge soi-même. C'est là qu'ils passent à côté de l'essentiel.
soul.md est un fichier Markdown dans `~/.openclaw/workspace/SOUL.md`. À chaque session, avant de traiter le moindre message, l'agent le lit intégralement — il se lit lui-même pour savoir qui il est. Pas de fine-tuning, pas de magie. Juste un prompt bien construit, injecté en système à chaque démarrage. Ce qui le rend différent d'un system prompt classique : il évolue. L'agent peut le modifier, y consigner des préférences apprises. Si vous lui dites "souviens-toi que je préfère les réponses courtes", il l'écrit dans soul.md et s'en souvient la prochaine fois.
La structure en 5 blocs qui fonctionne
soul.md est libre — du Markdown pur, sans schéma imposé. La communauté a convergé vers 5 blocs : Identité (qui est l'agent, pour qui il travaille), Caractère (ton, comportements concrets, ce qu'il ne fait pas), Contexte de l'entreprise (stack, clients, vocabulaire interne, process récurrents), Règles absolues (ce que l'agent ne fera jamais sans approbation), Mémoire (instructions sur comment et quoi mémoriser). Si vous voulez partir d'une base solide, OpenClaw propose aussi son template officiel SOUL.md, très utile pour structurer une première version propre rapidement.
Ce qui fait la différence entre chaque bloc
Le Caractère doit être comportemental, pas abstrait. "Sois concis" est inutile. "Tes réponses tiennent en 3 lignes maximum sauf si on te demande explicitement plus" est mesurable et applicable. "Sois professionnel" ne veut rien dire. "Pas de 'Bien sûr !', pas de 'Excellente question !'. Tu réponds directement." fonctionne. La règle d'or : si vous ne pouvez pas mesurer si l'agent respecte une instruction, reformulez-la.
Le Contexte de l'entreprise est le vrai différenciateur. Un agent qui connaît votre stack, vos clients par nom, votre vocabulaire interne, vos process de relance — c'est un agent qui ne vous fait pas perdre du temps à réexpliquer le contexte à chaque conversation. Intégrez les noms de vos clients actifs et leurs contextes clés, vos process récurrents, votre vocabulaire métier spécifique.
Les Règles absolues doivent couvrir tout ce qui a un effet dans le monde réel. En production, la règle de base : tout envoi d'email, modification de données, ou message externe nécessite une confirmation explicite. Formulez en positif quand possible — "demande confirmation avant d'envoyer" est plus robuste que "ne pas envoyer sans permission".
La section Mémoire est celle que presque tout le monde oublie. Sans instructions explicites sur comment mémoriser, l'agent apprend des choses utiles et les perd à la session suivante. Définissez un format précis — par exemple `[DATE] [Contexte] : [Information apprise]` — et l'agent construira progressivement une base de connaissance sur votre entreprise qui s'enrichit à chaque interaction.
Un soul.md bien structuré en 5 blocs — c'est ce qui transforme un bot générique en collaborateur reconnaissable.
Les fichiers complémentaires : AGENTS.md et MEMORY.md
soul.md ne travaille pas seul. AGENTS.md gère la configuration technique : quel modèle utiliser, quels outils sont disponibles, comment gérer les sessions. C'est la couche paramètres là où soul.md est la couche personnalité. MEMORY.md est la mémoire long terme structurée : préférences utilisateur, informations clients, corrections passées, décisions prises. C'est ce fichier qui crée l'effet de compound — un agent qui tourne depuis 3 mois a un MEMORY.md qui le rend exponentiellement plus utile qu'au jour 1.
Versionner soul.md avec Git
Un conseil pratique que peu de guides mentionnent : versionner vos fichiers workspace. `git init` dans `~/.openclaw/workspace/`, puis `git add SOUL.md AGENTS.md MEMORY.md HEARTBEAT.md` et un commit initial. soul.md évolue, MEMORY.md s'enrichit — sans versioning, vous n'avez aucun moyen de revenir en arrière si l'agent modifie accidentellement son propre soul. On a eu besoin de revenir en arrière deux fois chez Volteyr. Certains membres de la communauté synchronisent leur workspace entier vers GitHub privé chaque nuit via cron.
Pour les déploiements en production avec des données sensibles, passez soul.md et MEMORY.md en lecture seule : `chmod 444 ~/.openclaw/workspace/SOUL.md`. L'agent ne pourra plus se modifier lui-même — c'est le compromis à accepter quand l'exposition externe est élevée.
Sur les déploiements OpenClaw qu'on a accompagnés, 100% des agents abandonnés en moins de 3 semaines avaient un soul.md de moins de 10 lignes. 100% des agents encore actifs après 2 mois avaient un soul.md avec au moins les 5 sections complètes.
Ce n'est pas une corrélation anodine. Un soul.md pauvre crée un agent générique que les équipes n'ont pas envie d'utiliser. Un soul.md précis crée un collaborateur avec une personnalité — et les équipes interagissent naturellement avec lui, sans formation.
soul.md bien configuré. Voyons maintenant les erreurs courantes qui font échouer les installations.
Les 6 erreurs qu'on voit revenir systématiquement, avec leur cause et leur solution.
Erreurs courantes et solutions
Les problèmes les plus fréquents à l'installation et à la configuration d'OpenClaw.
| Erreur | Cause probable | Solution |
|---|---|---|
| engine node@X: wanted >=22 | Node trop ancien | nvm install 22 && nvm use 22 |
| command not found: openclaw (Windows) | PATH non rechargé | Fermer et rouvrir le terminal |
| sharp build failure | Conflit libvips sur macOS | SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest |
| Wizard quitte sans finir | Erreur de config canal | Relancer openclaw onboard — reprend depuis le point de blocage |
| L'agent répond mais n'exécute pas d'outils | Profile trop restrictif | Vérifier tools.profile dans la config, passer à full ou coding |
| Gateway inaccessible | Daemon non démarré | openclaw gateway --port 18789 pour démarrer en foreground et voir les logs |
Pour les problèmes persistants : openclaw doctor --fix résout la majorité des configurations mal initialisées.
Erreurs résolues. Dernière étape avant de passer à la production : comprendre les coûts réels.
Deux variables à maîtriser : l'infrastructure et le LLM. La deuxième est beaucoup plus difficile à prévoir.
Coûts d'infrastructure selon le mode de déploiement
De la machine locale au VPS prod-ready — les options et leurs coûts réels.
| Déploiement | Option | Coût mensuel |
|---|---|---|
| Machine locale existante | Mac / Linux perso | 0€ |
| VPS dédié (recommandé) | Hetzner CX21 ou OVH VPS Starter | 5–10€/mois |
| DigitalOcean 1-Click | Image renforcée, prod-ready | 12–20€/mois |
| Hostinger OpenClaw VPS | Configuré avec Docker, clé en main | 8–15€/mois |
Pour un premier déploiement PME : VPS Hetzner à 5€/mois. Suffisant pour un usage typique, facile à upgrader.
Le coût LLM : la variable critique
OpenClaw est agentique — une seule tâche peut déclencher 5 à 10 appels API enchaînés (lecture de fichiers, exécution d'outils, raisonnement, révisions). Une réponse qui semble simple peut consommer 50 fois plus de tokens qu'une conversation directe sur Claude.ai. C'est la variable la plus difficile à prévoir et la plus facile à sous-estimer.
Estimations de coût LLM selon le profil d'usage
Coûts mensuels constatés sur nos déploiements — hors infrastructure.
| Profil | Description | Coût LLM mensuel estimé |
|---|---|---|
| Usage léger | Résumés, réponses simples, heartbeat | 3–15€/mois |
| Usage typique PME | Reporting, emails, gestion agenda, CRM | 20–60€/mois |
| Usage intensif dev | Coding, debugging, pipelines automatisés | 200–1000€/mois |
Ces estimations supposent une utilisation mixte Haiku (tâches légères) + Sonnet (tâches complexes). Utiliser Sonnet pour tout multipliera ces chiffres par 3 à 5.
Trois règles pour contrôler les coûts. D'abord, posez une limite de dépenses immédiatement dans Anthropic Console (Settings → Billing → Set spend limit) — un heartbeat mal configuré ou une boucle infinie peut générer des centaines d'euros en quelques heures. Ensuite, utilisez le bon modèle pour la bonne tâche : Haiku ou GPT-4o mini pour les heartbeats et les résumés simples, Sonnet pour les tâches complexes — jamais Opus pour tout (c'est 1,7x plus cher que Sonnet pour le même workload). Enfin, démarrez de nouvelles sessions régulièrement : l'accumulation de contexte est le principal driver de coût à l'usage intensif.
Notre retour chez Volteyr : on tourne principalement sur Claude Haiku pour les tâches automatiques (heartbeats, routing, résumés) et on réserve Sonnet pour les tâches qui demandent de la personnalité et du raisonnement. C'est le meilleur rapport qualité/prix qu'on ait trouvé — et les agents Anthropic ont une cohérence de personnalité sur la durée qu'on n'a pas retrouvée ailleurs.
