macOS · Linux · WSL2 · Docker · launchd · systemd · vérifications reproductibles
Les équipes qui doivent maintenir la passerelle OpenClaw sur portables, Linux bare metal, WSL2 ou dans des conteneurs échouent rarement faute de clés de modèle. Elles échouent parce que Node diffère entre shell interactif et démon, les unités utilisateur systemd n'héritent pas du même bloc d'environnement, ou Docker lie une mauvaise adresse loopback. Cet article propose des contrôles prévol par plateforme avec réussite ou échec, un tableau de décision à quatre voies script officiel contre gestionnaire de paquets contre source contre conteneur, des commandes concrètes pour openclaw onboard et --install-daemon sous launchd macOS et systemd Linux, un garde-fou version, état Gateway et surface de liaison, et un Runbook avant de standardiser sur des nœuds Mac toujours actifs. Les traces d'erreur profondes vont dans le guide d'installation et de dépannage Gateway ; le vocabulaire processus et disponibilité s'aligne sur le playbook de déploiement cloud persistant ; l'exposition et les listes blanches sont couvertes par la checklist de durcissement production ; capacité et achat sont sur les pages tarifs de location et commander.
Les installateurs OpenClaw en 2026 sont volontairement courts ; le coût réel est la compréhension du contexte du démon. Une session zsh interactive peut afficher le bon node -v tandis que launchd ou systemd lance un processus avec un PATH réduit, un autre répertoire personnel ou des clés API absentes. WSL2 empile Defender Windows, redirection de ports et DNS au-dessus des hypothèses Linux. Docker ajoute montages de volumes, UID numériques, ports publiés et sémantique loopback : le tableau de bord répond en local mais les webhooks entrants échouent. Les cinq lacunes ci-dessous dominent le support ; les capturer en revue d'architecture économise plus de temps que réinstaller deux fois un CLI global.
Traitez chaque lacune comme un portail binaire. En cas d'échec, suspendez les fonctionnalités et réparez d'abord le contrat d'environnement. Les équipes qui sautent cette séquence célèbrent un script vert vendredi soir et découvrent un démon silencieux samedi matin parce que personne n'a redémarré ni exécuté wsl --shutdown avant de déclarer la victoire.
Node LTS et dérive binaire : Upstream attend un Node LTS actuel. Mélanger nvm, fnm, asdf et paquets distro donne souvent un terminal doré et une binaire périmée sous superviseur. Réussite : sous le même utilisateur UNIX que le service, afficher which node, la version, et concilier avec openclaw doctor ou la commande santé équivalente. Échec si les chemins divergent.
WSL2 et hypothèses systemd : Certaines distributions exigent systemd explicite ou lingering utilisateur avant que les unités utilisateur survivent sans login interactif. Réussite : après redémarrage WSL complet sans session shell manuelle, l'unité reste active. Échec si SSH ou un terminal doit réveiller le service une fois.
Volumes Docker contre couches inscriptibles : Ne stocker la config que dans la couche conteneur signifie que le prochain pull d'image efface secrets et état. Réussite : bind mounts ou volumes nommés pour le répertoire de configuration et les fichiers d'environnement, avec sauvegarde et restauration documentées avant upgrades.
Écoute par défaut : Se lier à 0.0.0.0 est commode en développement et devient un tableau de bord public en production. Réussite : les Runbooks production exigent loopback ou terminaison TLS derrière reverse proxy, alignés sur l'article de durcissement.
Journaux et rotation : Tout envoyer sur stdout sans rotation remplit les petits disques cloud et efface les preuves pendant incidents. Réussite : destinations de logs, jours de rétention et compatibilité avec journalisation centralisée définis avant trafic client.
Notez les cinq lignes réussite ou échec, puis passez au choix de chemin d'installation. La grille indique si vous expérimentez sur portable jetable ou construisez une topologie porteuse de canaux, webhooks et audits.
Si votre groupe maintient des builds iOS avec l'automatisation d'agent, placez la source de vérité Node, la source de vérité configuration et les répertoires de logs sur la même diapositive d'architecture. Un vocabulaire partagé avec les documents chaîne de tâches et pool de build évite de répéter la leçon PATH-contre-démon à chaque post-mortem.
Chaque chemin optimise une contrainte : temps jusqu'au premier succès, auditabilité, vélocité de patch ou isolation des dépendances. Les installateurs curl et PowerShell réduisent la main-d'œuvre mais heurtent les miroirs air-gap. Les npm globaux alignent les plateformes JavaScript mais amplifient les forks PATH sous démons. Les builds source débloquent correctifs et drapeaux personnalisés au prix du temps CI. Les conteneurs isolent les bibliothèques tout en imposant réseau, cartographie UID et sauvegardes de volumes explicites. Aucun n'est universel ; la bonne réponse est celle que gestion du changement, conformité et astreinte peuvent soutenir.
Quand plusieurs chemins attirent, prototypez en parallèle sur hôtes jetables mais gardez une autorité de configuration unique. Des expériences parallèles sans stratégie de secrets partagée garantissent des .env divergents et des faux positifs doctor.
| Chemin | Avantage principal | Risque principal | Mieux quand |
|---|---|---|---|
| Script curl ou ps1 officiel | Peu d'étapes manuelles, suit les défauts upstream | Miroirs sur réseaux privés ; versions à journaliser séparément | Solo et équipes de moins de cinq personnes pour prouver la valeur vite |
| npm, pnpm ou bun global | Familier aux plateformes JS, semver simple | Forks PATH et permissions sous démons | Organisations avec chaîne Node validée |
| Build source | Patchs et arguments de lancement | Charge de build et CI | Équipes sécurité qui forkent ou livrent correctifs d'urgence |
| Docker ou Podman | Isole les dépendances, essais horizontaux rapides | Complexité volumes, UID, loopback et ports hôte | Bac à sable multi-locataires ou pics temporaires |
Le succès d'installation signifie que le démon passe les mêmes commandes de vérification après démarrage à froid, pas seulement après une session terminal interactive.
Portables macOS, instances Linux cloud, WSL2 et conteneurs peuvent coexister dans une migration, mais autorité de configuration et injection des secrets doivent rester unifiées. Copier des fragments .env sans checklist garantit la dérive en une semaine.
Ces étapes restent indépendantes d'un fournisseur CI unique. Chaque étape produit un artefact : sortie de commande, capture d'état d'unité ou somme de contrôle des fichiers de configuration sur le ticket de changement. En cas d'échec, revenir à la section un avant de plonger dans les logs. Réduire l'inconnu avec le guide de dépannage doctor une fois les portails d'environnement verts.
Documentez les noms de paquets ou tags de conteneur à côté de chaque commande. Vous futur et l'ingénieur d'astreinte ne doivent pas deviner quelle semver était bénie le jour de l'installation.
Verrouiller Node et le gestionnaire de paquets : Installer LTS sous l'utilisateur du service, désactiver les hooks shell qui réécrivent PATH silencieusement, noter node -v et npm -v ou équivalents pnpm et bun dans l'annexe Runbook.
Exécuter l'installateur supporté : Sur hôtes de type Unix suivre le script officiel ou le flux paquet documenté pour votre release. Sous Windows préférer WSL2 ou le chemin PowerShell documenté ; éviter deux runtimes qui croient chacun posséder les modules globaux.
Terminer onboard pour secrets et modèles : Écrire clés API, racines d'espace de travail et paliers de modèle par défaut dans les fichiers convenus. Ne jamais s'appuyer sur l'historique shell ou des fichiers temporaires lisibles par tous pour les secrets.
Exécuter openclaw onboard --install-daemon : Noter les labels d'unité affichés par l'installateur. Sous macOS inspecter launchctl ; sous Linux comparer systemctl --user ou chemins système à la doc upstream de votre version.
Preuve de démarrage à froid : Redémarrer l'OS ou lancer wsl --shutdown, puis confirmer le service actif sans ouvrir de shell de login. S'il ne démarre qu'après SSH, le scénario lingering utilisateur est incomplet.
Ancres de retour arrière : Avant upgrades, instantanés d'images disque, tags conteneur ou sauvegardes tarball de l'ancien arbre de config. Le rollback restaure une unité connue bonne, pas une édition nocturne de plist ou fichiers unit.
openclaw --version openclaw gateway status # macOS : labels de démons chargés (remplacer par votre nom d'unité) launchctl list | grep -i openclaw || true # Linux : exemple systemd utilisateur systemctl --user status openclaw-gateway.service || true
Conseil : Les sous-commandes et noms d'unité changent entre releases. Traitez l'extrait comme schéma de couches, pas comme chaîne figée, et suivez la sortie de la version installée.
Un démon actif prouve un PID, pas que écouteurs, terminaison TLS ou en-têtes reverse-proxy sont corrects. Utilisez le tableau comme portail de release avant canaux publics. Le sauter laisse une zone grise entre chat fonctionnel et audit réussi.
Exécutez le garde-fou après chaque upgrade Node, rotation de certificat ou changement d'infrastructure, pas seulement à l'installation. Les régressions viennent souvent d'une mise à jour silencieuse de paquet plutôt que d'un déploiement applicatif.
| Contrôle | Attendu | Signal d'échec fréquent |
|---|---|---|
openclaw --version | Correspond à la semver épinglée Runbook | Fork PATH charge deux builds |
gateway status | Sain ou code d'erreur documenté | Erreurs d'analyse config ignorées car stdout bruyant |
| Interface d'écoute | Loopback en production ou terminaison au proxy | Tableau de bord joignable depuis Internet public |
| Chemin LLM sortant | Sondes curl ou SDK réussies depuis l'environnement démon | Variables proxy d'entreprise absentes pour systemd |
Attention : Appliquer listes blanches et audits de compétences de la checklist de durcissement seulement après stabilisation Gateway et adaptateurs. L'ordre inverse ouvre une fenêtre où le trafic arrive pendant que les contrôles restrictifs sont encore désactivés.
Les trois puces ne sont pas des benchmarks synthétiques mais des questions d'alignement avant projet pour finance, sécurité et plateforme. Remplacez les seuils qualitatifs par des chiffres issus de télémétrie et du système de tickets avant signature des SLA.
Les portables subissent veille, fermeture du capot, mises à jour macOS et invites de trousseau interactives. Ils excellent en développement et échouent comme seul hôte pour un agent sept jours sur sept. L'auto-hébergement déplace le coût vers baie, correctifs et mains à distance. Placer Gateway sur un Mac Mini cloud contractuel transforme démarrage à froid, semver et politique d'écoute en clauses vérifiables à l'achat.
Piège fréquent : Prendre fonctionne chez moi pour fonctionne pour toute l'équipe sans noms d'unité partagés, blocs d'environnement et autorité de configuration réduit les incidents à des captures collées dans le chat.
Quand la capacité de build iOS et macOS doit partager l'automatisation nocturne avec OpenClaw, le matériel personnel et les machines prêtées satisfont rarement pistes d'audit ou objectifs de disponibilité. Les équipes qui veulent moins de friction opérationnelle, régions choisissables et conditions de location flexibles aboutissent souvent à la location cloud Mac Mini VpsMesh : exécuter démons et politique de canal sur hôtes dédiés, puis aligner l'onboarding avec le centre d'aide et la page de commande plutôt que de lutter indéfiniment contre les politiques de veille des portables.
Choisir WSL2 lorsque les chaînes Windows desktop sont couplées étroitement et valider noyau et systemd. Préférer Linux natif pour livraison serveur dédiée. Les habitudes d'accès distant et la connectivité sont dans le centre d'aide avec les billets de blog associés.
Commencer par le guide d'installation et de dépannage Gateway pour chemins Node, permissions, ordre de configuration et ports occupés, puis revenir ici pour revérifier le démarrage à froid des unités.
Terminer la checklist de durcissement production et multi-canal avant d'exposer le trafic public. Pour matériel dédié, choisir région et durée sur la page de commande.