Vous maîtrisez peut-être déjà les guides « lourds » du site, Ubuntu 24.04 + systemd + Tunnel et Docker Compose production, mais il reste à poser proprement OpenClaw CLI et Gateway sur Windows, macOS ou Linux généraliste, à les enregistrer comme service et à valider les contrôles de santé. Cet article complète cette couche avec prérequis communs, un tableau comparatif par OS, six étapes ordonnées de l’installation au démon, les erreurs fréquentes en phase d’install et des limites claires vis-à-vis des deux guides production, afin de reproduire le même modèle mental sur portable, WSL2 ou petit VPS.
OpenClaw Gateway est un service longue durée combiné à une chaîne d’outils CLI. Si les bases divergent, systemd, Compose ou le tunnel seront corrects et échoueront tout de même de façon opaque. Les motifs ci-dessous reviennent sans cesse en triage multiplateforme ; consignez-les dans un runbook interne plutôt que dans des fils de discussion.
Dérive de version Node : un portable sur une ancienne LTS, l’intégration continue sur une autre ; les scripts de démarrage passent sur l’hôte A et cassent sur B (syntaxe ou dépendances). Avant installation, figer la runtime avec les binaires officiels ou nvm/fnm et documenter la plage mineure autorisée.
Répertoire d’état dans un volume synchronisé : placer ~/.openclaw ou l’équivalent dans iCloud Drive, OneDrive ou autre sync multiplie verrous, droits et conflits. Disque local et stratégie de sauvegarde séparée.
Mélange Windows natif et WSL2 sur le PATH : CLI installée dans PowerShell invoquée depuis WSL, ou l’inverse : commandes introuvables, chemins de certificats faux. Choisir une surface d’exécution principale et l’uniformiser.
TCC macOS et emplacement : lancer depuis Téléchargements déclenche après mise à jour système des invites Accessibilité ou Automatisation qui bloquent l’administration sans tête. Préférer /Applications ou chemins stables et revérifier les autorisations après grosses versions macOS.
Pas de boucle de contrôle de santé : s’arrêter à « le processus tourne », sans curl en boucle ni tableau de bord, laisse des 502 après changement réseau en production.
Écoute par défaut sur 0.0.0.0 : exposer la surface d’admin sur toutes les interfaces simplifie cinq minutes et complique audits et scanners. Associer boucle locale, tunnel ou reverse proxy.
Jetons dans l’historique shell : export interactif ou captures d’écran équivalent à partager des clés. Fichiers à permissions strictes ou gestionnaire de secrets.
Validez la liste avant le tableau comparatif pour réduire la friction « même commande, trois résultats ». Pour builds iOS ou sessions graphiques permanentes, laissez Gateway sur Linux ou poste de travail et déplacez la charge Apple Silicon vers des nœuds Mac distants dédiés.
Un second coût caché est la dispersion documentaire : README, wiki interne, captures vieilles de mois. Une seule source de vérité sur mineures Node, chemin d’état et sous-commande d’installation du démon vaut mieux que de longs chapitres conceptuels.
Prévoyez une fenêtre de retour arrière : sauvegarder l’arborescence de configuration et les fichiers de jeton avant patch CLI ou Gateway ; si l’enregistrement du démon échoue, revenir au binaire précédent ou au digest d’image antérieur. Les équipes qui célèbrent seulement « ça démarre » découvrent souvent des clés de config retirées au milieu de la nuit ; notes de version et onboard en préproduction anticipent cela.
Avec plusieurs lignes produits agents, séparez « install manuelle dev » et « prod systemd/Compose » par étiquettes ou espaces de noms pour ne pas synchroniser des répertoires de plugins expérimentaux vers l’état de production. Minimum : préfixe isolé en dev, montages de configuration en lecture seule et volumes de données en écriture en prod, sans liens symboliques croisés.
Sur une VM de rechange, entraînez-vous à tuer le processus et à faire tourner une clé API : le runbook doit lister status, journaux et désinstallation du démon. En exploitation, les check-lists l’emportent sur les schémas marketing.
Les trois plateformes exécutent le même Gateway logique mais diffèrent sur la supervision des processus, les journaux et le rollback. Le tableau fige ces écarts pour éviter de confondre services Windows et LaunchAgents en revue d’architecture.
| Plateforme | Entrée d’installation courante | Approche démon / service | Pièges typiques |
|---|---|---|---|
| Windows | Installateur officiel, script PowerShell, gestionnaire de paquets | Service Windows ou Planificateur de tâches avec ACL explicites sur les journaux | Natif contre WSL2, faux positifs antivirus, chemins avec espaces |
| macOS | Homebrew, installateur curl, publications amont | LaunchAgent ou LaunchDaemon selon besoin de session de connexion | TCC, Gatekeeper, propriété du répertoire d’état |
| Linux (générique) | Paquets distro, binaires statiques, npm global selon recommandation amont | Unités systemd utilisateur ou système (modèles dans le guide bare metal) | SELinux/AppArmor, images minimales sans bibliothèques, boucle 127.0.0.1 abîmée par iptables/nftables |
Ce qui reste transversal n’est pas quel installateur vous cliquez : versions figées, état local, surface d’écoute réduite et contrôles de santé scriptables.
Pour Tunnel et fichiers d’unité de niveau production sous Linux, passez au tutoriel Ubuntu 24.04 + systemd + Tunnel. Pour digests d’image et volumes nommés, suivez l’article Docker Compose production. Ce texte s’arrête à « CLI/Gateway correctement installés et daemonisés » pour que les trois guides ne se volent pas le périmètre.
La séquence suppose que l’amont fournit onboard et une sous-commande d’installation de démon ; si les noms diffèrent, suivez votre --help local mais gardez l’ordre.
Figez la runtime :node -v aligné sur l’amont ; mettre à jour Node avant Gateway si besoin.
Installez la CLI : canal recommandé par OS ; ne mélangez pas installations globales sudo et utilisateur sur le même compte.
Secrets : clés fournisseurs de modèles dans fichier env ou coffre, mode 600 ; pas de commit dans le dépôt partagé.
Onboard : générer ou valider config et jetons Gateway ; noter les chemins dans le runbook.
Démon : commande type install-daemon pour redémarrage sur incident et répertoire de journaux en une fois.
Recette : enchaîner status, health si disponible, curl boucle locale pour éviter un « running » trompeur.
node -v openclaw --version openclaw onboard --install-daemon openclaw gateway status openclaw dashboard
Note : si status est sain mais pas l’URL publique, séparez problème de processus et problème de routage : boucle locale d’abord, puis tunnel ou reverse proxy, comme dans le long article Linux.
Windows : si le développement vit surtout dans WSL2, installez CLI et Gateway dans cette distro pour aligner les chemins sur les scripts Linux de prod. DrvFs vers fichiers Windows : IO et droits particuliers. Services natifs : ACL explicites pour état et journaux.
macOS : binaires stables, pas d’exécution permanente depuis Téléchargements ; après upgrade OS, revérifier Automatisation et Accessibilité. Sans interface, privilégier LaunchDaemon sauf exigence UI amont.
Linux : si vous écrivez déjà des unités systemd, sautez vers le guide bare metal ; avec Docker, documentez qui possède la boucle locale et le sidecar tunnel pour éviter deux Gateways sur le même port.
En triage : symptôme, preuve, hypothèse ; monter temporairement la verbosité des journaux (pas en continu), reproduire sur la même semver ; si un seul hôte échoue, comparer variables d’environnement, proxy et décalage d’horloge. Le décalage casse jetons et TLS sans lien avec la logique métier.
« Le tableau de bord s’ouvre » n’équivaut pas à prêt pour la prod. Avant bascule, enchaîner une tâche minimale de bout en bout via Gateway avec auth, routage, rappels, nouvelles tentatives et limites de débit.
Avertissement : en 2026, les interfaces d’administration Gateway exposées publiquement restent une erreur classique. Partez du principe qu’elles seront scannées ; listes d’autorisation, tunnel, mTLS ou réseau privé comme base, pas option.
Ces éléments aident l’alignement interne ; ils ne constituent pas d’engagement envers des projets tiers. La référence reste l’aide et les notes de version de votre build installée.
Faire tourner Gateway uniquement sur portable ou petite VM suffit pour une démo, mais veille, disque et Wi-Fi rendent les flux d’agents imprévisibles ; rack Mac maison ajoute amortissement et exploitation salle. Pour une couche d’exécution Apple Silicon stable (builds, signature scriptée, automation à côté de Gateway), déporter la charge lourde vers des Mac distants dédiés sous contrat colle souvent mieux à la prod. Compte tenu de la complexité d’installation et de l’exploitation longue durée, la location de Mac mini cloud NodeMini complète raisonnablement votre plan de contrôle existant.
Parler de « nœuds » facilite aussi finance et achats : région, niveau disque, durée de bail. Quand le trafic OpenClaw monte, vous scalez l’exécution sans rebâtir chaque image développeur.
Propriétaires de rotation des jetons, approbateurs d’exceptions pare-feu et URL de tableau de bord faisant foi : les écrire noir sur blanc réduit les incidents plus que des drapeaux de fonctionnalités supplémentaires.
Cet article traite l’installation multiplateforme et la validation du démon. Le guide Ubuntu systemd et l’article Docker décrivent la topologie de production. Plus de contenus via le filtre catégorie OpenClaw.
Version de Node, répertoire d’état hors disque synchronisé, shell Windows natif contre WSL2. Pour la capacité parallèle, voir les tarifs de location.
Consultez le centre d’aide pour SSH, VNC et réseau. Pour routage Gateway et tunnels, recoupez avec les deux guides production ci-dessus.