OpenClaw est un agent IA open source auto-hébergé. Sa pièce centrale est la passerelle (Gateway) : un processus qui reste en fonctionnement, relie vos canaux de messagerie (Telegram, Discord, WhatsApp) à un modèle de langage et exécute des outils pour votre compte. Pour qu'il réponde à toute heure, il lui faut une machine toujours allumée : un VPS Linux est le support naturel. Le risque, lui, est tout aussi clair : un agent capable de lancer des commandes shell ne doit jamais être joignable depuis Internet sans contrôle.
Ce tutoriel installe OpenClaw sur un VPS Linux Debian ou Ubuntu (systèmes de type Unix), de deux façons (service systemd ou Docker), garde ses données de façon persistante, et donne accès à l'interface de contrôle uniquement par tunnel SSH ou Tailscale. Le projet publie des versions rapprochées : installez donc toujours la dernière version stable, et relisez ses notes de version avant chaque mise à jour.
Les notions à connaître
- Passerelle (Gateway) : le démon OpenClaw. Il écoute sur le port 18789 et sert à la fois l'API WebSocket et l'interface de contrôle.
- Interface de contrôle (Control UI) : l'interface web d'administration, servie par la passerelle sur ce même port. La passerelle joue alors le rôle d'un serveur Web pour cette interface.
- Onboarding : l'assistant de première configuration (
openclaw onboard). - Provider : la source du modèle, API d'un éditeur ou serveur Ollama local.
- Boucle locale (loopback) : l'adresse 127.0.0.1, inaccessible depuis l'extérieur du serveur.
- Tunnel SSH : une redirection de port chiffrée entre votre poste et le VPS.
- Terminal : la fenêtre dans laquelle vous saisissez des commandes. La ligne de commande désigne cette saisie de commandes en texte, sans interface graphique.
- Adresse IP : le numéro qui identifie le VPS sur Internet. Le tunnel SSH s'appuie sur cette adresse.
- Pare-feu (firewall) : le filtre qui laisse entrer uniquement les ports autorisés sur le serveur.
- Machine virtuelle : un serveur logique qui tourne sur une machine physique partagée grâce à la virtualisation. Un VPS en est un exemple.
- Redémarrage (restart) : arrêt puis relance d'un service ou du serveur, nécessaire pour appliquer certaines modifications.
- Logs (journaux) : les traces écrites par un service, à consulter en cas de problème.
- Sauvegarde (backup) : une copie des données, pour les restaurer en cas de perte.
Prérequis du VPS
D'après la documentation d'installation, OpenClaw demande Node 24.16.0 ou supérieur (branche 24.x) ou Node 26.1.0 ou supérieur, Node 26 étant recommandé. La page conseille, pour la sécurité, de viser au moins 24.22.1 ou 26.12.1. Vérifiez ces seuils au moment de l'installation, ils évoluent avec les versions.
Prévoyez un VPS Ubuntu ou Debian à jour (paquets système compris), un accès SSH par clé et un pare-feu actif, qui ne laisse ouvert que le port SSH. Si ce n'est pas fait, commencez par sécuriser SSH. Côté ressources, la documentation Docker indique au moins 6 Go de RAM pour compiler l'image localement : une image pré-compilée évite cette contrainte.
Créer un utilisateur dédié
Ne faites jamais tourner un agent en root, le compte administrateur du système. Créez un compte sans privilèges sudo, qui ne possédera que l'état d'OpenClaw :
sudo adduser --disabled-password --gecos "" openclaw
sudo loginctl enable-linger openclaw
La seconde commande permet aux services utilisateur systemd de continuer à tourner sans session ouverte, ce qui est indispensable pour un service « 24 h sur 24 ». Ouvrez ensuite une session en ligne de commande sous ce compte :
sudo machinectl shell openclaw@
Si machinectl n'est pas disponible, utilisez sudo -iu openclaw en vous assurant que la variable XDG_RUNTIME_DIR est définie pour les commandes systemctl --user.
Méthode 1 : service systemd
Installer OpenClaw
La méthode recommandée par la documentation est le script officiel :
curl -fsSL https://openclaw.ai/install.sh | bash
Par prudence, téléchargez le script, relisez-le, puis exécutez-le, plutôt que de l'enchaîner directement dans un shell. Ajoutez -- --no-onboard si vous préférez lancer l'onboarding séparément. L'alternative est le gestionnaire de paquets npm :
npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon
Avec npm 11.15 ou antérieur, retirez l'option --allow-scripts=openclaw (npm 12 bloque par défaut les scripts de cycle de vie non approuvés). Pour Node lui-même, voir installer et sécuriser Node.js avec nvm.
Installer le démon
L'option --install-daemon installe le service géré par le système : sous Linux, un service utilisateur systemd. Pendant l'onboarding, vous configurez OpenClaw : vous choisissez un provider de modèle et fournissez ses identifiants. Vérifiez ensuite :
openclaw --version
openclaw doctor
openclaw gateway status
systemctl --user status
openclaw doctor détecte les problèmes de configuration, openclaw gateway status confirme que la passerelle tourne. Si la commande openclaw est introuvable, le répertoire global de npm n'est probablement pas dans votre PATH. Dans ce cas, ouvrez une nouvelle session dans votre terminal après l'installation, puis relancez la commande.
Méthode 2 : Docker
Docker est facultatif, mais utile pour isoler la passerelle. Il faut Docker Engine et Compose v2 (voir installer Docker sur un VPS). Selon la documentation Docker d'OpenClaw, la procédure part du dépôt cloné :
./scripts/docker/setup.sh
Le script construit l'image openclaw:local, ou utilise une image pré-compilée si vous définissez OPENCLAW_IMAGE (par exemple ghcr.io/openclaw/openclaw:latest, le registre GHCR étant le registre principal). Évitez les miroirs non officiels. Le script demande les clés API, génère un token de passerelle dans le fichier .env et démarre la passerelle avec Compose.
Persistance des données
Le conteneur s'exécute avec l'utilisateur node et stocke son état dans un volume monté sur /home/node/.openclaw. Conservez ce volume entre les mises à jour, gardez un seul réplica de passerelle par volume d'état, et arrêtez l'ancien conteneur avant d'en lancer un nouveau. Pour comprendre les volumes et les fichiers Compose, voir Docker Compose sur un VPS Linux.
Attention aux ports publiés
La documentation signale que, sur un VPS public, il faut consulter la page de durcissement, en particulier la chaîne de pare-feu DOCKER-USER. Raison : Docker insère ses propres règles de redirection, qui peuvent contourner UFW. Publiez le port uniquement sur la boucle locale, par exemple 127.0.0.1:18789:18789, et jamais 0.0.0.0:18789. Vérifiez le résultat avec ss -tlnp (voir lister les ports en écoute).
Comparatif des deux méthodes
| Critère | Service systemd | Docker |
|---|---|---|
| Mise en place | Script ou npm, puis --install-daemon | Script setup.sh et Compose |
| Données | ~/.openclaw de l'utilisateur | Volume sur /home/node/.openclaw |
| Isolation | Utilisateur dédié | Conteneur, utilisateur node |
| Mise à jour | openclaw update | docker compose pull, redémarrage |
| Point de vigilance | Lingering systemd | Ports publiés et DOCKER-USER |
Accéder à l'interface sans l'exposer
Par défaut, la passerelle écoute sur la boucle locale, port 18789. C'est le bon réglage : ne le changez pas. Deux méthodes pour atteindre l'interface depuis votre poste.
Tunnel SSH
La documentation d'accès distant décrit cette redirection :
ssh -N -L 18789:127.0.0.1:18789 openclaw@IP_DU_VPS
Le tunnel passe par l'adresse IP du VPS : il ne demande ni nom de domaine ni enregistrement DNS. Tant que le tunnel est ouvert, ouvrez http://127.0.0.1:18789/ dans votre navigateur local et collez le token de la passerelle (celui du fichier .env en Docker, ou le mot de passe si vous en avez configuré un). Pour le détail du principe, voir créer un tunnel SSH vers un service interne.
Tailscale
La documentation recommande de garder la liaison sur la boucle locale (gateway.bind à loopback) et d'utiliser Tailscale Serve pour l'interface de contrôle, le tunnel SSH servant de solution de repli. Vous obtenez un accès depuis tous vos appareils du réseau privé, sans ouvrir de port public. L'installation de Tailscale côté VPS est détaillée dans Tailscale sur un VPS Linux. Gardez Tailscale à jour : voir aussi les failles Tailscale SSH signalées.
Dans tous les cas, laissez le pare-feu fermé sur 18789 et vérifiez-le depuis l'extérieur.
Comparatif des accès à l'interface
Ce tableau résume les trois façons d'atteindre l'interface de contrôle. Seule la première et la deuxième sont recommandées.
| Méthode | Exposition sur Internet | Usage conseillé |
|---|---|---|
| Tunnel SSH | Aucun port public ouvert pour OpenClaw | Accès ponctuel depuis un poste |
| Tailscale Serve | Aucun port public, accès via le réseau privé | Accès depuis plusieurs appareils |
| Port 18789 publié sur 0.0.0.0 | Interface joignable depuis tout Internet | À éviter |
Brancher un modèle : Ollama ou API
Modèle local avec Ollama
Installez d'abord Ollama (guide Ollama sur un VPS). Selon la documentation d'Ollama, la commande suivante configure OpenClaw pour utiliser Ollama et démarre la passerelle :
ollama launch openclaw
L'intégration existe depuis Ollama 0.17.0 : une version plus ancienne répond « unknown integration ». L'option --config modifie seulement la configuration sans lancer la passerelle, et --model choisit le modèle. Ollama recommande une fenêtre de contexte d'au moins 64 000 tokens.
Si vous configurez le provider à la main, la page provider Ollama est claire : utilisez l'API native, avec baseUrl sans /v1 (par exemple http://127.0.0.1:11434). L'URL compatible OpenAI casse l'appel d'outils, et le modèle peut afficher le JSON de l'appel comme du simple texte.
Soyez réaliste : sans GPU, un VPS fait tourner de petits modèles, avec de la mémoire à prévoir pour un contexte de 64 000 tokens. Pour choisir, voir quel modèle LLM tourne sur votre serveur, gérer les modèles Ollama et l'exemple de LFM3 avec Ollama. Le serveur Ollama doit lui aussi rester sur 127.0.0.1.
Modèle via une API
Sur un VPS modeste, une API distante est souvent plus efficace : l'onboarding vous demande le provider et sa clé. Le prompt et le contexte quittent alors votre serveur : tenez-en compte si vous traitez des données personnelles. Pour centraliser plusieurs clés et fournisseurs, un proxy comme LiteLLM peut s'intercaler entre votre serveur et les fournisseurs.
Durcir l'installation
Un agent exécute des actions : traitez-le comme un compte à privilèges limités et surveillé.
- Utilisateur dédié, sans sudo. Si l'agent est détourné, il ne touche pas au reste du serveur.
- Outils shell limités. N'activez que les outils nécessaires et préférez un espace de travail restreint. Pour une isolation plus forte des commandes générées par l'agent, voir Docker Sandboxes et microVM. Les faiblesses d'un agent échappé de son bac à sable rappellent pourquoi.
- Secrets. Gardez clés API et tokens hors des dépôts et des journaux. Restreignez les droits :
chmod 700 ~/.openclaw. Utilisez un token de passerelle fort et révoquez les clés qui ont fuité. Voir l'exemple des secrets commités par un assistant de code. - Réseau. Aucun port ouvert pour 18789 ni pour Ollama (11434). Ne laissez ouvert que SSH, avec clés et Fail2ban. Règles de base : UFW.
- Canaux. Limitez qui peut parler à l'agent (liste d'utilisateurs autorisés) : un bot Telegram ou Discord ouvert à tous est une porte d'entrée.
- Sauvegardes. Le dossier
~/.openclawcontient votre configuration et vos profils : sauvegardez-le (la sauvegarde est proposée en option chez ElypseCloud). Voir sauvegarder un VPS avec rsync.
Comparez aussi avec un autre agent auto-hébergé : installer Hermes Agent sur un VPS suit la même logique de service isolé.
Mises à jour et supervision
Le projet publie souvent. Avant toute mise à jour, sauvegardez ~/.openclaw.
- npm ou script :
openclaw update(la documentation décrit aussiopenclaw update --channel stableou--channel devpour changer de canal), puisopenclaw doctoretopenclaw gateway status. - Docker :
docker compose pull openclaw-gateway openclaw-cli
docker compose stop openclaw-gateway
docker compose up -d openclaw-gateway
Au démarrage d'une nouvelle image, openclaw doctor --fix s'exécute automatiquement. Pour la supervision, la passerelle expose /healthz (vivacité), /startupz et /readyz sur le port 18789, utilisables avec Uptime Kuma depuis le serveur lui-même. Consultez les logs (journaux) avec journalctl --user (voir analyser des logs avec journalctl). Mettez aussi à jour le système : mises à jour de sécurité automatiques sous Ubuntu.
Checklist finale
- Version de Node conforme aux seuils de la documentation.
- Service actif après un redémarrage (restart) du VPS.
ss -tlnp: 18789 uniquement sur 127.0.0.1.- Accès à l'interface par tunnel SSH ou Tailscale uniquement.
- Utilisateur dédié, sans sudo, et
~/.openclawen 700. - Ollama sur 127.0.0.1, avec
baseUrlsans/v1. - Sauvegarde de
~/.openclawtestée.
Pour un agent qui tourne en continu avec un accès root pour préparer l'environnement, un VPS Linux est le bon point de départ ; un serveur de jeu géré depuis un panel ne convient pas à cet usage.
FiveM
Minecraft
Rust
RedM
Hytale