Installer OpenClaw sur Ubuntu : guide complet

Introduction

Installer OpenClaw Ubuntu consiste aujourd’hui à déployer un Gateway Node/TypeScript, pas un paquet Python. Ubuntu 22.04 et 24.04 sont adaptés à un poste de développement, un serveur domestique ou un VPS qui doit rester disponible. Cette approche est utile si vous voulez gérer directement le service, les fichiers d’état et les canaux. Elle est à éviter si vous cherchez seulement un appel LLM ponctuel, pour lequel un script plus simple suffit. Ce tutoriel utilise l’installateur officiel, l’onboarding CLI, le service systemd utilisateur, le Control UI local et les commandes de diagnostic actuelles, sans pip, virtualenv ni classe Agent fictive.

Résumé rapide

1. Mettre Ubuntu à jour et installer curl ainsi que les certificats système.
2. Lancer l’installateur Linux officiel, qui provisionne Node si nécessaire.
3. Exécuter l’onboarding et installer le daemon du Gateway.
4. Vérifier openclaw doctor, openclaw gateway status et le port 18789.
5. Garder le bind loopback et utiliser un tunnel pour l’accès distant.

Ce qu’Ubuntu exécute réellement

OpenClaw est un assistant self-hosted organisé autour d’un Gateway persistant. Ce processus conserve les sessions, ouvre les connexions aux canaux, route les messages vers les agents et sert le Control UI. Les clients de contrôle et les nodes communiquent avec lui en WebSocket. Par défaut, le Gateway écoute sur 127.0.0.1:18789, une valeur sûre pour une installation locale.

Le runtime recommandé est Node 26. Les branches actuellement documentées acceptent aussi certaines versions minimales de Node 22, 24 et 25, mais il est préférable de laisser l’installateur choisir un runtime supporté. Sur Linux, celui-ci provisionne Node lorsqu’il manque et installe la CLI npm. pnpm n’est nécessaire que pour construire le projet depuis ses sources.

L’état canonique se trouve sous ~/.openclaw. Le fichier principal est ~/.openclaw/openclaw.json, au format JSON5. Le workspace par défaut est ~/.openclaw/workspace; les agents secondaires ont leurs propres workspaces, répertoires d’état et historiques SQLite. Les skills sont des dossiers contenant SKILL.md, pas des classes Python. Cette architecture explique pourquoi pip install openclaw, openclaw.yaml et python agent.py ne doivent plus apparaître dans un setup Linux.

Ubuntu apporte systemd, mais OpenClaw installe son propre service utilisateur. Il n’est normalement pas nécessaire d’écrire à la main une unité système pointant vers un binaire inventé. Le guide de configuration OpenClaw complète ce modèle mental avant les réglages avancés.

Installer OpenClaw pas à pas sur Ubuntu

1. Préparer le système

Mettez à jour les index et installez les utilitaires nécessaires au téléchargement sécurisé :

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ca-certificates

Un redémarrage peut être pertinent après une mise à jour du noyau. OpenClaw n’exige ni python3-pip, ni python3-venv, ni PPA Python. Pour un usage natif, Docker n’est pas requis non plus.

2. Installer avec le script officiel

L’installation recommandée sur Linux est :

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

Le script détecte le système, installe un Node compatible si nécessaire, installe OpenClaw et lance l’onboarding. Si vous voulez séparer installation et configuration :

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
openclaw onboard --install-daemon

Une alternative existe pour les utilisateurs qui gèrent déjà Node :

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

L’option --allow-scripts=openclaw concerne npm récent. L’installateur reste le choix le plus robuste, notamment parce qu’il réduit les problèmes de PATH et de runtime utilisé par le service.

3. Terminer l’onboarding

L’assistant peut réutiliser une connexion Claude Code ou Codex CLI existante, ou configurer une clé de fournisseur. Le démarrage rapide convient à une instance personnelle. Le mode personnalisé permet de choisir plus précisément modèle, auth Gateway et canaux. Vous pourrez reprendre les réglages plus tard :

openclaw configure

L’onboarding écrit notamment gateway.mode: "local". Le Gateway refuse de démarrer avec une configuration existante qui a perdu ce champ, plutôt que de deviner. Dans ce cas, relancez l’onboarding ou réparez avec Doctor.

4. Vérifier le service géré

Contrôlez la CLI, la configuration et le daemon :

openclaw --version
openclaw doctor
openclaw gateway status

Pour une vérification automatisable sans mutation :

openclaw doctor --lint --json
openclaw gateway status --json
openclaw status --all

Sur Linux, le daemon est une unité systemd utilisateur installée par OpenClaw. Utilisez openclaw gateway start, stop, restart et status pour respecter l’identité et l’environnement du service. Si le service doit survivre à la fermeture de session sur un serveur, Doctor vérifie le linger systemd et signale le correctif nécessaire.

5. Ouvrir le Control UI

Lancez :

openclaw dashboard

Le navigateur ouvre l’interface servie par le Gateway local. Il n’existe pas de serveur FastAPI séparé ni de port 3000 obligatoire. Le Control UI utilise le même serveur que le WebSocket sur le port 18789.

Sur Ubuntu Server sans navigateur, utilisez un tunnel depuis votre poste :

ssh -N -L 18789:127.0.0.1:18789 user@serveur

Ouvrez ensuite l’adresse loopback sur votre poste. Cette méthode conserve gateway.bind en loopback et évite d’exposer le plan de contrôle.

6. Ajouter un canal

La CLI inventorie les canaux installés et configurés :

openclaw channels list --all
openclaw channels add --channel telegram
openclaw channels status --probe

Le setup Telegram demande le token du bot. WhatsApp utilise openclaw channels login et un flux d’association. Les expéditeurs inconnus sont généralement soumis au pairing ou à une allowlist. Listez puis approuvez une demande avec :

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Ne passez jamais directement à une politique DM ouverte. Le pairing contrôle qui peut déclencher l’assistant ; l’auth Gateway protège les clients du plan de contrôle. Ce sont deux couches distinctes.

7. Adapter le pare-feu

Pour une instance locale, n’ouvrez aucun port. Sur un serveur accessible par SSH, autorisez d’abord SSH puis activez UFW :

sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

N’ajoutez pas de règle publique pour 18789 lorsque vous utilisez un tunnel. Si vous choisissez volontairement un bind lan, tailnet ou custom, le Gateway bloque le démarrage sans authentification. Préférez Tailscale Serve, un tunnel SSH ou un frontal TLS correctement configuré à une exposition directe.

8. Mettre à jour et diagnostiquer

La commande supportée détecte la méthode d’installation, valide un candidat puis active la mise à jour :

openclaw update --dry-run
openclaw update

Après intervention, exécutez openclaw health, openclaw gateway status --deep --json et openclaw doctor --lint --json. En cas de problème, openclaw doctor propose des réparations ; openclaw doctor --fix applique les corrections non liées au service selon sa politique. Consultez aussi les logs OpenClaw avant de modifier la configuration à l’aveugle.

Checklist de validation

• La CLI provient du script officiel ou du paquet npm openclaw.
• Node est supporté et aucun virtualenv Python n’est impliqué.
• Le service utilisateur du Gateway est actif.
• Le Control UI répond sur loopback au port 18789.
• Les canaux configurés passent channels status --probe.
• Doctor lint et l’audit de sécurité ne signalent aucun blocage.

Exemple concret : Ubuntu Server accessible par tunnel

Un développeur installe OpenClaw sur Ubuntu 24.04 pour maintenir un assistant Telegram disponible en continu. Après la mise à jour d’APT, il lance le script officiel, choisit l’onboarding personnalisé et installe le daemon. Il garde le Gateway sur 127.0.0.1:18789, autorise seulement SSH dans UFW et ajoute Telegram avec la CLI.

Depuis son ordinateur, il établit le tunnel suivant :

ssh -N -L 18789:127.0.0.1:18789 admin@serveur

Il ouvre le dashboard local, contrôle les demandes de pairing et vérifie le canal :

openclaw gateway status
openclaw channels status --probe
openclaw security audit --deep

Le test est concluant si le service reste actif après déconnexion SSH, si Telegram répond uniquement aux expéditeurs approuvés et si le port 18789 n’est pas joignable publiquement. Le développeur sauvegarde ensuite ~/.openclaw et teste une restauration sur une machine distincte. Ce scénario montre qu’un setup openclaw Linux fiable ne demande pas un faux service Python : la continuité dépend du daemon Gateway, de l’état persistant, du contrôle d’accès et d’un chemin d’administration privé.

Bonnes pratiques

N’exécutez pas l’installateur ou le Gateway quotidien sous sudo. Les fichiers seraient créés dans le mauvais home et le service utilisateur ne retrouverait plus sa configuration. Évitez également un Node fourni uniquement par un gestionnaire de versions chargé dans .bashrc : un service systemd ne reproduit pas toujours votre shell interactif. Doctor détecte plusieurs de ces divergences.

Sauvegardez l’ensemble du state dir et vérifiez les bases SQLite, plutôt que de copier uniquement openclaw.json. Fixez des permissions strictes sur les secrets. Pour plusieurs personnes qui ne se font pas mutuellement confiance, séparez les Gateways ou les comptes OS ; plusieurs agents d’un Gateway ne créent pas une frontière hostile.

Enfin, activez les canaux un par un. Après chaque changement, passez channels status --probe, status --all et security audit. Cette discipline limite les régressions en production et rend les diagnostics reproductibles.

Questions fréquentes

OpenClaw est-il compatible avec Ubuntu 22.04 et 24.04 ?

Oui, car l’installateur Linux provisionne un runtime Node supporté lorsque nécessaire. La compatibilité ne dépend pas de la version Python livrée par Ubuntu. Sur les deux LTS, utilisez le script officiel, puis vérifiez le runtime, Doctor et le service Gateway plutôt que d’installer un paquet avec pip.

Comment installer OpenClaw Ubuntu sans pip ?

Vous ne devez précisément pas utiliser pip. Exécutez le script Linux officiel, ou installez openclaw@latest globalement avec npm si vous gérez déjà Node. OpenClaw est un projet Node/TypeScript piloté par une CLI et un Gateway, pas une bibliothèque Python destinée à un environnement virtuel.

Quel port faut-il ouvrir pour OpenClaw sur Ubuntu ?

Aucun port public n’est nécessaire pour un usage local ou administré par tunnel SSH. Le Gateway écoute par défaut sur 127.0.0.1:18789. Les canaux sortants fonctionnent sans exposer ce port. Si vous liez le service au LAN ou à une tailnet, activez obligatoirement une authentification et limitez le réseau autorisé.

Comment démarrer OpenClaw automatiquement sur Ubuntu ?

Utilisez openclaw gateway install ou l’option openclaw onboard --install-daemon. OpenClaw installe alors une unité systemd utilisateur cohérente avec son runtime et son state dir. Contrôlez-la avec openclaw gateway status. Une unité écrite manuellement n’est utile que si un superviseur externe possède explicitement le cycle de vie.

Articles liés

Ubuntu fournit une base stable pour un Gateway personnel ou serveur, à condition de conserver le bind privé et l’état complet. La prochaine étape consiste à configurer les canaux, puis à ajouter les contrôles de production adaptés à la criticité.

• Installer OpenClaw : parcours général
• Configurer OpenClaw et son Gateway
• Déployer OpenClaw sur un VPS
• Conteneuriser OpenClaw avec Docker
• Sécuriser une instance OpenClaw
• Comprendre OpenClaw