Installer OpenClaw sur un VPS Linux : guide pratique et premiers pas

1. Pourquoi installer OpenClaw sur un VPS Linux

OpenClaw permet d’exécuter un agent IA sur votre propre serveur Linux, avec votre configuration, vos clés API et vos intégrations. Sur un VPS, cela permet de garder la main sur l’environnement d’exécution tout en laissant l’agent tourner en continu.

Ce type de déploiement est utile si vous voulez :

centraliser plusieurs outils derrière une seule interface IA
faire tourner un bot ou un assistant en continu
garder les données et la configuration côté serveur
accéder au dashboard à distance sans dépendre d’un ordinateur local allumé

Dans ce guide, nous allons voir l’installation, l’accès distant, la configuration du provider IA, la gestion du service, la maintenance et les points de sécurité importants pour un VPS.

2. Préparer votre VPS Linux

Pour suivre ce tutoriel, il vous faut :

un VPS Linux avec un accès SSH
un utilisateur capable d’installer des paquets si nécessaire
curl et git si vous utilisez le script d’installation ou l’installation depuis les sources
corepack si vous comptez lancer la méthode avancée depuis le dépôt Git avec pnpm
une clé API de fournisseur de modèle pour terminer la configuration

Côté runtime, OpenClaw recommande Node 24. Node 22 reste compatible à partir de Node 22.16.

Sur Debian ou Ubuntu, vous pouvez installer les utilitaires de base si besoin :

sudo apt update
sudo apt install -y curl git

3. Installation rapide avec le script d’installation

Si vous voulez la méthode la plus simple, le script d’installation officiel peut préparer l’environnement et lancer l’installation automatiquement.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Sur un VPS Linux, ce script détecte la distribution, installe Node si nécessaire, puis installe OpenClaw.

Si vous préférez installer OpenClaw sans lancer immédiatement l’onboarding :

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

Vous pourrez ensuite terminer l’installation avec la commande recommandée pour un VPS :

openclaw onboard --install-daemon

4. Installation manuelle recommandée via Node et npm

Si vous préférez garder la main sur chaque étape, installez d’abord Node, puis le CLI OpenClaw.

Commencez par vérifier votre version de Node :

node -v

Si Node n’est pas encore installé, installez Node 24, ou au minimum Node 22.16, avec la méthode adaptée à votre distribution.

Ensuite :

npm i -g openclaw@latest
openclaw onboard --install-daemon

La commande d’onboarding configure OpenClaw puis installe le daemon de la passerelle, ce qui convient à la majorité des déploiements VPS.

5. Installation depuis les sources, cas avancé

Si vous avez une raison précise de lancer OpenClaw depuis le dépôt Git plutôt que depuis le paquet npm, voici la méthode :

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
corepack prepare pnpm@latest --activate
pnpm install
pnpm build
pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

Pour un VPS classique, gardez plutôt l’installation npm vue plus haut.

6. Accéder au dashboard à distance en toute sécurité

Sur un VPS, la bonne pratique consiste à garder la passerelle OpenClaw accessible uniquement en local, puis à ouvrir un tunnel depuis votre ordinateur.

Commencez par vérifier l’état du Gateway et le port réellement configuré :

openclaw gateway status

Si vous avez besoin d’un accès distant, privilégiez un tunnel SSH :

ssh -N -L 18789:127.0.0.1:18789 user@your-vps

Ensuite, ouvrez dans votre navigateur local :

http://127.0.0.1:18789/

Vous utiliserez alors le token ou le mot de passe configuré pendant l’onboarding pour vous authentifier.

Sur l’écran de connexion Gateway, vérifiez l’URL WebSocket locale, le mode d’authentification et le secret de connexion. Avec un tunnel SSH, gardez une URL locale de type :

ws://127.0.0.1:18789

Évitez de remplacer ce champ par l’IP publique brute du VPS.

Une fois la connexion appliquée, le dashboard doit afficher un état de connexion correct. Si l’interface ne se connecte pas, revérifiez d’abord le tunnel SSH, le secret de connexion et le port Gateway avant de modifier la configuration.

Si vous préférez une URL publique plutôt qu’un tunnel SSH, la variante Nginx + HTTPS ci-dessous permet de publier l’accès proprement sans exposer directement le port du Gateway.

6.1. Accès public avec Nginx et HTTPS

Si vous préférez un accès navigateur via une URL publique plutôt qu’un tunnel SSH, n’exposez pas directement le port du Gateway sur Internet. Gardez OpenClaw à l’écoute sur 127.0.0.1:18789, puis placez Nginx devant avec HTTPS.

Vous obtenez ainsi une URL simple comme :

https://openclaw.example.com

tout en gardant le vrai service OpenClaw privé sur le VPS.

Architecture recommandée :

Internet
↓
Nginx en HTTPS
↓
OpenClaw Gateway en local sur 127.0.0.1:18789

Avant de commencer, faites pointer le domaine ou sous-domaine choisi vers l’adresse IP publique du VPS.

Installez les paquets nécessaires :

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

Créez ensuite un vhost Nginx dédié :

sudo nano /etc/nginx/sites-available/openclaw

Commencez par une configuration HTTP simple pour laisser Certbot émettre le certificat :

server {
    listen 80;
    server_name openclaw.example.com;

    location / {
        return 200 "OpenClaw Nginx vhost is ready\n";
        add_header Content-Type text/plain;
    }
}

Activez le site, vérifiez la configuration, rechargez Nginx, puis générez le certificat HTTPS :

sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/openclaw
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d openclaw.example.com

Une fois le certificat généré, remplacez la configuration par cette version finale :

server {
    listen 80;
    server_name openclaw.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name openclaw.example.com;

    ssl_certificate /etc/letsencrypt/live/openclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.example.com/privkey.pem;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:18789;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

Vérifiez puis rechargez Nginx :

sudo nginx -t
sudo systemctl reload nginx

Pour un accès via domaine public, ajoutez aussi l’origine HTTPS autorisée dans la configuration OpenClaw. Si le fichier n’existe pas encore, créez-le :

nano ~/.openclaw/openclaw.json

Exemple minimal pour un Nginx installé sur le même VPS qu’OpenClaw :

{
  gateway: {
    controlUi: {
      allowedOrigins: ["https://openclaw.example.com"]
    },
    trustedProxies: ["127.0.0.1/32", "::1/128"]
  }
}

Ouvrez ~/.openclaw/openclaw.json et ajoutez ces clés dans la configuration existante. N’écrasez pas tout le fichier avec cet exemple.

Dans ce tutoriel, avec Nginx installé sur le même VPS qu’OpenClaw, configurez toujours ces trois points :

gateway.controlUi.allowedOrigins avec votre domaine HTTPS public
gateway.trustedProxies avec 127.0.0.1/32 et ::1/128
l’authentification native du Gateway par mot de passe ou token

trustedProxies est requis dans ce scénario Nginx local → OpenClaw. Sans lui, la première connexion web publique peut être traitée comme non fiable, avec des erreurs de pairing ou d’autorisation difficiles à comprendre.

Si votre proxy HTTPS termine sur une autre machine, remplacez 127.0.0.1/32 et ::1/128 par l’IP ou le CIDR réel de ce proxy.

Redémarrez ensuite le Gateway :

openclaw gateway restart

Quand vous ouvrez le dashboard depuis l’URL publique, utilisez :

https://openclaw.example.com

Si l’interface vous demande une URL WebSocket Gateway, utilisez plutôt :

wss://openclaw.example.com

N’utilisez pas l’IP publique brute du VPS comme URL Gateway. Dans cette configuration, l’accès public doit passer par le domaine HTTPS exposé par Nginx : c’est lui qui correspond au certificat TLS, à gateway.controlUi.allowedOrigins et au proxy public configuré en amont. Avec l’IP brute, vous risquez surtout un échec de certificat, un échec d’origine ou un contournement du chemin d’accès réellement prévu pour le Gateway.

Si vous voulez ajouter plus tard une Basic Auth HTTP côté Nginx, faites-le seulement après avoir validé le fonctionnement du couple HTTPS + auth native OpenClaw. Selon le client ou le navigateur, une surcouche HTTP supplémentaire peut perturber le flux WebSocket du Control UI si elle est mal placée ou mal testée.

6.2. Première connexion publique et pairing du navigateur

Sur la première ouverture depuis un nouveau navigateur, OpenClaw peut demander une approbation one-shot du device avant d’ouvrir complètement le Control UI public. Ce comportement est normal.

Si l’interface affiche Device pairing required, connectez-vous en SSH sur le VPS puis lancez d’abord :

openclaw devices list

Ensuite, approuvez la demande la plus récente :

openclaw devices approve --latest

Si vous voulez approuver une demande précise, vous pouvez aussi utiliser l’identifiant exact de la requête :

openclaw devices approve <requestId>

Et si le CLI vous demande explicitement le secret du Gateway, ajoutez simplement le mot de passe configuré pendant l’onboarding :

openclaw devices approve --latest --password 'your-gateway-password'

Une fois l’approbation terminée, rechargez la page ou cliquez de nouveau sur Connect. Cette validation ne doit en général être faite qu’une seule fois par navigateur ou device approuvé.

Si vous utilisez UFW, vérifiez d’abord son état :

sudo ufw status

Si UFW est déjà actif, ajoutez simplement les règles utiles. Le profil OpenSSH sert uniquement à conserver votre accès SSH d’administration au VPS et le tunnel montré plus haut, pas OpenClaw lui-même :

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw deny 18789/tcp

Si UFW n’est pas encore activé sur votre VPS et que vous voulez l’utiliser, activez-le ensuite :

sudo ufw enable

Si vous gérez déjà votre filtrage directement avec iptables, gardez la même logique : laissez passer SSH, HTTP et HTTPS, puis bloquez le port 18789 depuis l’extérieur. Ne bloquez pas le trafic local loopback, car Nginx doit encore pouvoir joindre OpenClaw sur 127.0.0.1.

Si votre SSH écoute sur un port différent, remplacez 22 par la bonne valeur.

Exemple :

sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT ! -i lo -p tcp --dport 18789 -j DROP

Si vous voulez rester sur un accès purement privé, le tunnel SSH reste l’option la plus simple. Un VPN privé ou un réseau privé maillé du même type est aussi une bonne alternative si vous voulez un accès privé plus permanent, sans exposer directement le Gateway sur Internet.

7. Vérifier l’installation et faire un premier test

Une fois OpenClaw installé, voici les commandes les plus utiles :

openclaw --version
openclaw doctor
openclaw status
openclaw gateway status --deep

Ces commandes permettent de repérer rapidement un problème de PATH, de version Node, de configuration ou de passerelle.

Elles permettent de vérifier :

que le CLI est bien disponible dans le PATH
que la configuration ne contient pas d’erreur évidente
que la passerelle est bien installée et répond correctement

Pour consulter les logs en direct :

openclaw logs --follow

L’idée n’est pas de lire toute la sortie ligne par ligne, mais de confirmer qu’aucune erreur bloquante ne remonte au démarrage. Si le CLI est sain et que le dashboard s’ouvre correctement, vous pouvez passer à la configuration du provider avant le premier vrai test dans le chat.

7.1. Configurer le provider IA et la clé API avant le premier test

L’endroit à connaître pour brancher OpenAI ou un autre provider se trouve dans Paramètres > IA et agents > Models. C’est dans cette vue que vous ajoutez ou éditez une entrée de provider, puis que vous indiquez à OpenClaw comment parler à votre backend IA.

Le champ Model Provider API Adapter sert à choisir le protocole attendu par votre fournisseur. Pour un backend OpenAI compatible, vous choisirez généralement openai-responses ou azure-openai-responses. Pour Anthropic, la valeur attendue sera plutôt anthropic-messages, et pour Gemini google-generative-ai.

Juste en dessous, Model Provider API Key est l’emplacement où coller votre clé API. La même carte permet aussi d’ajuster le mode d’authentification, l’URL de base du provider et la liste de modèles exposés à l’interface.

Le parcours à retenir est simple : ouvrez Paramètres, allez dans IA et agents, basculez sur Models, puis modifiez votre entrée de provider avant d’enregistrer. C’est là que vous reliez OpenClaw à votre clé OpenAI, Anthropic, Gemini ou à tout autre backend compatible.

Une fois cette configuration enregistrée, revenez dans l’onglet Chat. C’est à ce moment-là que vous pouvez lancer un premier échange utile et vérifier que l’interface répond réellement avec le provider que vous venez de brancher.

8. Gérer le service sur un VPS

Sur un VPS classique, il n’est généralement pas nécessaire d’écrire un service systemd à la main. Les commandes suivantes couvrent le cas standard :

openclaw onboard --install-daemon

openclaw gateway install

Pour les opérations courantes sur le service :

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

Ces commandes permettent de vérifier l’état du service, de le redémarrer proprement et de suivre immédiatement les logs.

Sur Linux, OpenClaw installe généralement une unité systemd utilisateur. Si le service ne reste pas actif après votre déconnexion SSH, activez le linger pour votre compte :

sudo loginctl enable-linger $USER

Sur un VPS headless, vérifiez ce point si le service s’arrête après votre déconnexion SSH.

Pour confirmer visuellement qu’OpenClaw conserve bien vos conversations côté interface, la vue Sessions donne un aperçu rapide des sessions actives actuellement suivies par l’agent.

Si vous devez réactiver explicitement l’unité utilisateur :

systemctl --user enable --now openclaw-gateway.service

Si vous utilisez un profil OpenClaw nommé, le nom du service peut ressembler à :

systemctl --user enable --now openclaw-gateway-<profile>.service

Si vous voulez un service système dédié, vous pouvez aussi créer une unité manuelle sous /etc/systemd/system/openclaw-gateway.service au lieu de vous reposer uniquement sur l’unité utilisateur.

9. Maintenance, mise à jour et désinstallation

Pour maintenir votre instance à jour :

openclaw update
openclaw doctor
openclaw gateway restart

Si vous voulez désinstaller proprement OpenClaw, commencez par voir ce qui sera supprimé :

openclaw uninstall --dry-run

Puis lancez la désinstallation si le résultat vous convient :

openclaw uninstall

10. Sécuriser les canaux de messagerie

Si vous connectez OpenClaw à Discord, Telegram, WhatsApp, Slack ou d’autres canaux, n’ouvrez pas les DMs publiquement sans garde-fous.

Gardez ces règles simples :

gardez une politique de type pairing ou allowlist pour les messages privés
n’autorisez explicitement que les expéditeurs ou comptes attendus
évitez le mode ouvert tant que vous n’avez pas validé votre configuration d’accès
séparez bien l’accès utilisateur simple des actions d’administration ou d’approbation

Sur plusieurs intégrations, le mode pairing est justement prévu pour éviter qu’un expéditeur inconnu puisse dialoguer librement avec votre agent dès le premier message.

11. Problèmes fréquents et solutions

11.1. `openclaw: command not found`

Le CLI n’est généralement pas dans votre PATH.

Vérifiez d’abord le préfixe npm global :

npm prefix -g

Ajoutez ensuite le dossier bin associé dans votre profil shell :

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Puis retestez :

openclaw --version

11.2. Version de Node trop ancienne

Vérifiez votre version :

node -v

Si vous êtes en dessous de Node 22.16, mettez Node à jour avant de relancer l’installation.

11.3. La passerelle ne démarre pas ou le port est occupé

Les commandes les plus utiles sont :

openclaw gateway status
openclaw gateway status --deep
openclaw doctor

Vérifiez d’abord le port réellement configuré, puis adaptez votre tunnel SSH ou votre configuration si ce port est déjà utilisé par un autre service.

11.4. Le service s’arrête après la déconnexion SSH

Sur un serveur headless, vérifiez que le linger systemd utilisateur est bien actif :

sudo loginctl enable-linger $USER

11.5. Erreurs de permission sur `~/.openclaw`

Si vous voyez un Permission denied ou un EACCES, assurez-vous d’utiliser toujours le même utilisateur pour lancer OpenClaw, puis corrigez les droits :

sudo chown -R $USER:$USER ~/.openclaw

12. Bonnes pratiques de sécurité

Pour un déploiement VPS propre :

gardez la passerelle liée à 127.0.0.1
privilégiez le tunnel SSH, ou un VPN privé ou un réseau privé maillé du même type si vous voulez un accès privé plus permanent
si vous exposez une URL publique, passez par HTTPS, Nginx et l’authentification native du Gateway OpenClaw
si vous ajoutez une surcouche d’authentification en frontal, revalidez toujours le flux WebSocket du Control UI avant de la garder en production
ne publiez jamais directement le port Gateway OpenClaw sur Internet
vérifiez toujours le mode d’authentification du Gateway avant d’ouvrir un accès distant
sauvegardez régulièrement ~/.openclaw
évitez de mélanger plusieurs usages sensibles sous le même compte système

13. Et ensuite

Une fois OpenClaw opérationnel sur votre VPS, vous pourrez ajouter des canaux, connecter vos outils et faire évoluer votre agent selon vos besoins. Si vous voulez tester cette installation sur une machine adaptée à ce type d’usage, vous pouvez lancer votre serveur VPS gratuitement et reprendre les étapes de ce guide.

Rejoignez la discussion

Laisser un commentaire