OpenClaw 2026, de la première installation au retour arrière sûr : install.sh, npm/pnpm, Docker Compose et la check-list doctor

Trois douleurs récurrentes qui ressemblent à « OpenClaw est cassé »

Les équipes ouvrent rarement un ticket intitulé « mauvais choix d’empaquetage ». Elles écrivent plutôt « le tableau de bord marchait hier » ou « npm install ne finit jamais sur le bastion ». Ces plaintes recouvrent trois schémas d’ingénierie qui traversent install.sh, npm, pnpm et Docker jusqu’à ce que vous standardisiez les attentes et les chemins sur disque.

1) Désalignement de voie entre opérateurs. Un collègue suit le script officiel, un autre installe une interface en ligne de commande globale avec npm, un troisième récupère un Compose depuis un fork ou un gist. Chaque méthode place configuration, caches et identifiants à des emplacements légèrement différents. Lorsque la passerelle tombe après un correctif système, personne ne s’accorde sur le répertoire à sauvegarder ni sur l’unité systemd ou launchd qui lance réellement le processus. L’incident devient une chasse au trésor dans les répertoires personnels au lieu d’un retour arrière répété.

2) Mise à niveau sans contrat de données. Les passerelles OpenClaw accumulent de l’état : configuration locale, répertoires de cache de modèles, jetons de canaux et ressources téléchargées. Promouvoir une nouvelle version sans copier les bons dossiers vers l’avant produit un comportement de « installation propre » qui ressemble à une perte de données. Revenir en arrière sans instantanés produit l’inverse : des binaires obsolètes qui lisent des schémas incompatibles. Traitez le répertoire de données comme une surface de migration de premier plan, pas comme une note de bas de page.

3) Sauter l’échelle de diagnostic. Lorsque les messages cessent de circuler, la réinstallation réflexe fait perdre des heures. La séquence productive vérifie d’abord le processus et le port d’écoute, confirme la joignabilité HTTP de la passerelle et l’injection d’environnement, exécute openclaw doctor pour la cohérence statique, puis capture les journaux pendant une reproduction contrôlée du défaut. Passer directement à « supprimer node_modules » avant de savoir si le conteneur monte bien le fichier de configuration que vous avez modifié déplace simplement la couche fautive.

Instrumentez les installations comme la production : enregistrez la version de Node, les fichiers de verrouillage du gestionnaire de paquets ou les empreintes d’images, le commit exact de tout script d’installation, et une archive de configuration avant toute montée de version. Cette discipline paie dès la première fois où vous devez prouvoir qu’une régression vient du code applicatif, des quotas fournisseur ou d’un changement de permissions accidentel sur le volume de données. Documentez aussi qui peut modifier les variables d’environnement partagées : beaucoup d’incidents « fantômes » ne sont qu’un .env écrasé sans revue.

La voie install.sh : ce qu’elle optimise et où votre discipline reste indispensable

Les scripts d’installation curatés existent pour compresser des dizaines d’étapes de documentation en une commande auditable. Ils gèrent en général la détection de shell, les indices de dépendances et l’échafaudage initial des répertoires. Ils ne remplacent pas votre obligation de vérifier les sommes de contrôle, de stocker les secrets hors de l’historique shell ou de respecter les règles de proxy d’entreprise. Avant d’exécuter un script sur un bastion partagé, lisez les sections qui modifient les profils shell ou installent des binaires globaux ; ces effets secondaires persistent pour chaque utilisateur futur qui se connecte.

Traitez le script comme une infrastructure versionnée : téléchargez-le vers un nom de fichier adressé par contenu, consignez le SHA-256 dans votre journal des changements, et exécutez-le dans une fenêtre de maintenance lorsque c’est possible. Capturez la transcription complète du terminal. Si le script propose des drapeaux non interactifs, utilisez-les en automatisation afin que l’intégration continue et les humains produisent des arborescences identiques. À la fin, lancez immédiatement openclaw doctor et une sonde HTTP locale contre le port de passerelle documenté pour votre train de release, couramment 18789 dans les guides 2026, en l’ajustant si votre équipe standardise un autre port derrière un proxy inverse.

Les modes de défaillance fréquents incluent des caches sudo obsolètes qui masquent des erreurs de permission, l’inspection SSL d’entreprise qui casse curl au milieu du script, et les réglages de locale qui altèrent l’analyse des chemins sur des images cloud minimales. Lorsque le script se termine mais que la passerelle n’écoute pas, comparez l’utilisateur qui a lancé le script avec l’utilisateur du superviseur de processus. Les comptes incohérents expliquent souvent « ça marche en SSH, mort après reboot ». Gardez un staging qui reflète la cible réelle ; reliez les symptômes au guide passerelle et doctor avant d’incriminer le script seul.

La voie npm et pnpm : épinglage de Node, compromis CLI globale et hygiène des permissions

Les installations via gestionnaire de paquets brillent lorsque les ingénieurs ont besoin de cycles de mise à niveau rapides et d’une intégration étroite avec des dépôts JavaScript existants. Elles pénalisent lorsque l’équipe confond un npm install -g avec une chaîne locale au projet, ou lorsque plusieurs versions de Node se disputent un même hôte. Standardisez un gestionnaire de versions et documentez la branche majeure de Node que votre distribution OpenClaw supporte ; dériver vers l’avant pour des projets sans rapport est la manière habituelle dont les passerelles de production héritent de modules natifs incompatibles.

Le magasin adressé par contenu de pnpm réduit l’usure disque lorsque plusieurs services partagent des dépendances, ce qui compte sur de petits disques cloud. npm reste omniprésent pour les prestataires qui ne doivent pas apprendre une autre chaîne sous la pression d’un incident. Dans les deux cas, exécutez la passerelle sous un compte Unix dédié avec répertoire personnel et chemins de données que vous contrôlez, pas sous une session personnelle qui lance aussi des navigateurs et met la machine en veille.

Atténuez les délais d’attente du registre npm et la latence géographique avec un miroir interne ou un drapeau documenté ; ces détails appartiennent au même runbook que les règles de pare-feu. Après l’installation, vérifiez que which openclaw pointe vers l’emplacement voulu, puis lancez doctor avant d’exposer un écouteur public. Si votre organisation interdit les installations globales, enveloppez l’interface avec npx ou un script de paquet versionné, mais gardez l’enveloppe stable entre les versions. En CI, cachez les dépendances de façon déterministe et séparez les jetons de publication de ceux de l’exécution ; croisez avec le guide de stabilité pour éviter qu’un bump ne devienne une panne de week-end.

La voie Docker Compose : volumes, ports, politiques de redémarrage et planchers de ressources

Compose concentre le gain de reproductibilité : le même YAML décrit images, fichiers d’environnement, ports publiés et politiques de redémarrage. Le mode de défaillance se déplace vers la configuration mal montée et les écarts d’UID entre utilisateur conteneur et liaisons sur l’hôte. Nommez chaque volume dans la documentation et rattachez-le à une tâche de sauvegarde. Traitez les fichiers .env comme des artefacts porteurs de secrets avec des playbooks de rotation, et non comme des notes informelles.

Publiez uniquement les ports dont votre entrée a réellement besoin ; placez la terminaison TLS sur un proxy inverse avec contrôles de santé plutôt que d’exposer largement des écouteurs Node bruts. Fixez des limites mémoire suffisantes pour les rafales conversationnelles — environ 1,5 gibioctet de marge RAM libre reste une base pratique pour un petit nœud, aux côtés des seuils évoqués dans les guides d’exploitation de passerelle — tout en laissant de la marge au noyau hôte. Utilisez unless-stopped ou l’équivalent pour que les pannes transitoires se réparent sans SSH manuel.

Dans l’espace de noms du conteneur, exécutez la même séquence openclaw status, doctor et suivi de journaux que sur bare metal. Si doctor réussit sur le portable mais échoue dans le conteneur, suspectez répertoires de travail, montages manquants ou variables injectées seulement en shell interactif. Alignez les healthchecks Compose avec la sonde HTTP du répartiteur. Validez sur la même famille de noyau que la production ; le guide multi-plateforme aide à tracer les écarts macOS ou Windows.

openclaw status
curl -sS -m 5 http://127.0.0.1:18789/health || echo "gateway probe failed"
openclaw doctor
openclaw health --json > /tmp/openclaw-health-$(date +%Y%m%d%H%M).json
openclaw logs --follow

Mise à niveau, retour arrière, ordre de triage et quand un Mac distant hébergé aide

Avant toute montée de version, sauvegardez le répertoire de configuration, les fichiers d’environnement, l’export des jetons de canaux depuis votre coffre de secrets — jamais depuis des journaux de discussion — et les répertoires de modèles ou de caches que votre équipe juge coûteux à reconstruire. Conservez une archive datée à côté de l’empreinte d’image conteneur précédente ou du fichier de verrou npm. Faites avancer dans un environnement de préproduction avec le même Compose ou les mêmes drapeaux de script, relancez doctor et capturez un JSON de santé, puis promouvez pendant une fenêtre de faible trafic.

Le retour arrière signifie restaurer ces artefacts et redémarrer avec l’étiquette d’image ou la version de paquet antérieure, pas réinstaller de mémoire. Si des migrations de schéma apparaissent entre versions, lisez les notes de version avant de rétrograder ; des migrations partielles peuvent exiger des réparations manuelles de fichiers ou de bases que doctor seul ne peut annuler.

Lorsque les incidents frappent, suivez l’échelle : status prouve qu’un processus détient le port ; HTTP passerelle prouve que les écouteurs et les proxys s’alignent ; doctor attrape la mauvaise configuration statique ; les journaux expliquent ce qui s’est passé pour un événement utilisateur réel. Ne montez chez le fournisseur qu’après avoir corrélationné des preuves locales horodatées. Cet ordre prolonge l’histoire opérationnelle de l’article passerelle et débogage canal tout en reconnaissant que la santé HTTP et les vérifications de couche passerelle ont leur place entre l’état brut du processus et la validation statique de doctor.

• npm ci bloqué : suspectez miroirs de registre, problèmes de MTU ou limitation CPU sur de minuscules instances avant d’accuser OpenClaw.
• Doctor vert mais canaux silencieux : passez aux journaux de pont et aux jetons ; les actifs statiques de l’interface peuvent tromper.
• Mise à niveau Compose qui casse les montages : différenciez anciens et nouveaux chemins de volume avant de toucher aux répertoires de données.

Résumé : Trois voies d’installation échangent vitesse d’onboarding, ergonomie d’itération et reproductibilité ; elles ne « échouent proprement » que lorsque sauvegardes, épinglage de Node et ordre de triage sont des contrats d’équipe explicites.

Limitation : Les portables qui dorment, les comptes personnels partagés avec la production et les modifications manuelles non documentées restent la classe dominante d’échecs même lorsque l’empaquetage est irréprochable.

Angle SFTPMAC : Un Mac distant hébergé offre une alimentation stable, des chaînes d’outils natives Apple et la colocalisation avec des flux d’artefacts SFTP que de nombreuses équipes utilisent déjà à côté des agents. Lorsque votre passerelle OpenClaw doit rester en ligne près des mêmes chemins rsync ou SFTP dont votre pipeline de release dépend, quitter une machine personnelle fragile réduit les déconnexions dues à la veille et la dérive des permissions sans sacrifier la compatibilité macOS.

Nous mettons l’accent sur des nœuds joignables et des permissions de fichiers prévisibles afin que la sortie de doctor et le JSON de santé restent comparables entre environnements. Si la fiabilité prime sur la réutilisation de matériel retiré du service, standardisez une infrastructure conçue pour l’exploitation continue et un retour arrière répété.