Points de douleur : pourquoi la passerelle disparaît la nuit
Attachement de session. Les processus lancés depuis ssh ou Terminal héritent du cycle de vie de cette session. Déconnexion, fermeture de fenêtre ou perte réseau tuent souvent tout l’arbre, et la passerelle semble aléatoirement absente. L’exploitation lit cela comme bug applicatif alors que la cause est l’absence de démonisation.
Dérive de chemins et de versions. Après une mise à jour globale npm, un changement de canal ou une reconstruction Docker, which openclaw pointe ailleurs que la plist ou l’unit encore chargée. Symptôme : échecs de démarrage sporadiques visibles surtout après reboot, pas après un simple reload.
Limites de descripteurs et ressources. Une passerelle avec nombreux canaux et outils ouvre beaucoup de fichiers et de sockets. Sans limites relevées dans l’unit ou configuration ulimit cohérente, les processus meurent silencieusement ou avec des codes de sortie génériques difficiles à corréler.
Couche proxy sans amont stable. Même un terminateur TLS impeccable renvoie 502 si OpenClaw fluctue. L’analyse commence donc par un processus gateway stable avant de douter des en-têtes documentés dans Nginx et Caddy.
Mélange conteneur et bare metal. Docker en local, systemd sur le serveur, premier plan sur le Mac sans règle claire produisent des doubles mécanismes de redémarrage ou aucun. La politique du guide de production stable doit désigner une source autoritaire pour le runtime.
Premier plan n’est pas production : sessions, journaux, fenêtres
La production exige des redémarrages déterministes, des sorties capturées dans des fichiers ou journaux structurés, et des étapes de mise à niveau documentées. Le premier plan offre un feedback rapide mais aucune garantie après mise à jour noyau, coupure électrique ou pression mémoire. Les tests fonctionnels dans le terminal ignorent la gestion des signaux et le comportement à la déconnexion.
Les journaux doivent être rotatifs et corrélables aux sorties openclaw doctor. Sans cela, les post-mortems s’effilochent. Le diagnostic de canaux reste la référence dans l’exploitation de passerelle; la résidence rend ces vérifications répétables parce que le processus ne disparaît pas.
Les fenêtres de maintenance nécessitent une séquence : réduire le trafic ou drainer l’amont, arrêter proprement la passerelle, mettre à jour binaires ou images, valider la configuration, recharger le démon, valider les healthchecks, puis seulement invalider caches proxy ou CDN. Cette discipline s’aligne sur install.sh, npm et Docker où figurent stratégies de chemins et rollbacks.
L’observabilité sépare alertes d’état de processus et signaux métier. Une unit systemd active avec file d’attente vide n’est pas le même incident qu’un arrêt volontaire pendant release. Les runbooks doivent distinguer ces cas.
Les profils développeur et production doivent isoler variables et fichiers de configuration. Un drapeau debug laissé sur le démon consomme du CPU et masque les vrais problèmes de performance derrière un flot de logs.
macOS : launchd avec chemins absolus et domaine clair
launchd attend des ProgramArguments explicites sans interprétation shell. Chaque hypothèse implicite sur PATH échoue après le prochain correctif. Définissez EnvironmentVariables avec PATH, LANG et préfixes projet; ancrez NODE_BINARY si votre installation l’exige.
KeepAlive peut attendre une sortie réussie ou relancer systématiquement; combinez avec ThrottleInterval pour limiter les boucles de crash. Les agents utilisateur vivent souvent dans ~/Library/LaunchAgents; les Mac sans tête peuvent nécessiter des agents globaux avec impacts sur veille et énergie.
Les sorties standard et erreur doivent viser des chemins rotatifs, pas des fichiers illimités dans le home sans équivalent logrotate. Quand c’est possible, branchez des pipelines centralisés déjà prévus pour l’exploitation de Mac distants.
Modifier la plist impose bootout puis bootstrap ou un kickstart -k ciblé selon la version macOS et le domaine. Documentez les commandes exactes pour éviter l’improvisation en astreinte.
L’interaction avec Gatekeeper et la signature sort du périmètre, mais un binaire non trouvé ressemble à un blocage de signature. Versionnez les empreintes attendues et comparez aux instructions d’installation.
Power Nap, sommeil et capot sont réels pour portables. Pour passerelles 24/7 sur Mac bureau ou rack, figez profils énergétiques pour éviter que la gestion d’énergie ne bride la pile réseau.
Les environnements multi-utilisateurs exigent des LaunchAgents séparés par contexte. Ne mélangez pas démons globaux et chemins utilisateurs sous peine d’erreurs de permissions sur jetons ou trousseaux.
Sauvegardez et versionnez les plists comme tout artefact d’infrastructure; sans contrôle de version, l’équipe perd la trace de la mineure Node attendue en production.
Linux : unit systemd, politique Restart et ressources
Le fichier unit doit inclure User, Group, WorkingDirectory et ExecStart en chemin absolu. Restart=always ou on-failure décide si les arrêts courts manuels restent possibles. Ajoutez RestartSec pour éviter le thundering herd quand API ou base flanche.
LimitNOFILE, TasksMax et MemoryMax protègent contre la consommation implicite. Une passerelle qui épuise les descripteurs meurt avec un symptôme flou; calibre les limites sur la charge réelle de canaux et d’outils.
EnvironmentFile sépare les secrets de l’unit et permet la rotation sans réécrire tout le fichier. Permissions 600 et propriété du compte service. Après modification, toujours daemon-reload avant restart.
Journald fournit des journaux structurés; des champs filtrables aident à corréler avec proxy et application. Pour rétention longue, expédiez vers Loki, Elasticsearch ou un service managé, aligné sur la conformité du guide de stabilité.
L’activation par socket est rarement nécessaire pour une passerelle toujours connectée; toute exception doit être écrite noir sur blanc.
Units utilisateur versus système changent chemins et logique de démarrage. Sans session interactive, les units système sont souvent plus robustes si permissions nettes.
Surveillez pression cgroup et événements OOM. Un processus qui heurte constamment MemoryMax mérite un travail d’architecture, pas seulement une limite plus haute.
Les mises à jour noyau et bibliothèques imposent des redémarrages planifiés. Coordonnez-les avec les fenêtres annoncées et informez les consommateurs de canaux si des coupures brèves sont inévitables.
Matrice : launchd, systemd ou conteneur
| Environnement | Choix principal | Gain | Pièges |
|---|---|---|---|
| Mac distant 24/7 | launchd et journaux rotatifs | Indépendance du shell, domaine d’agent clair | Dérive de chemins et d’énergie |
| VPS Linux | systemd | Journal unifié, limites cgroup | Mélange units utilisateur et système |
| Isolement multi-instance | Conteneurs avec Compose | Images reproductibles | Mappage volumes pour secrets et config |
| Pure investigation | Premier plan ou tmux | Itération rapide | Pas de reprise après crash |
| Exploitation mixte | Une couche de supervision | Responsabilité nette | Doubles redémarrages ou aucun |
La matrice ne remplace pas les tests de charge. Injectez trafic et outillage réels avant de figer les limites. En cas de doute, revenez à l’exploitation passerelle et aux recommandations proxy TLS.
Squelettes : fragments plist et unit
# macOS : ~/Library/LaunchAgents/com.example.openclaw.gateway.plist
# ProgramArguments : /chemin/absolu/vers/openclaw gateway
# KeepAlive : true ou SuccessfulExit
# StandardOutPath / StandardErrorPath → répertoires rotatifs
# launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.openclaw.gateway.plist
# Linux : /etc/systemd/system/openclaw-gateway.service
# ExecStart=/usr/bin/env openclaw gateway
# Restart=always
# RestartSec=5
# LimitNOFILE=65535
# systemctl daemon-reload && systemctl enable --now openclaw-gateway
Fragments volontairement minimaux. Complétez durcissement, sécurité et dépendances selon votre politique. Après chaque upgrade, validez les chemins comme dans le guide d’installation.
Contrôles de santé : status, gateway, doctor, journaux
Commencez par openclaw status pour écarter erreurs CLI et contexte. Poursuivez avec les sous-commandes gateway pour configuration et écouteurs. Seulement ensuite creusez les journaux. L’ordre reflète l’exploitation passerelle et évite de traiter le proxy avant la base.
Traitez les avertissements openclaw doctor comme des lots de travail, pas comme du cosmétique. Archivez les sorties versionnées à côté des tags de release pour rendre la dérive visible entre environnements.
Ports et WebSocket doivent correspondre au reverse proxy documenté dans TLS et WebSocket. Validez les mises à niveau en préproduction avec la même unit ou plist.
Combinez alertes : processus actif mais doctor critique, ou processus actif mais files saturées. Une métrique seule ment souvent.
Les runbooks doivent préciser l’escalade quand plusieurs alertes coexistent, par exemple après upgrade OS et paquets simultanés.
Gardez le temps synchronisé; sans NTP fiable, la corrélation des journaux semble aléatoire et complique les post-mortems multi-équipes.
Sauvegardez la configuration avant chaque release pour réduire le temps de restauration; croisez avec les rollbacks décrits dans installation.
Les healthchecks doivent respecter les arrêts planifiés sans bruit excessif; utilisez des drapeaux de maintenance ou des fenêtres silencieuses dans la supervision.
La conservation longue des sorties doctor peut toucher la vie privée; minimisez les champs et purgez les sections sensibles selon la politique.
Les tests d’intégration après reload doivent inclure upgrades WebSocket et négociations TLS, pas seulement HTTP 200.
Clôturez les post-mortems avec actions concrètes sur les paramètres d’unit plutôt qu’avec de vagues injonctions de vigilance.
Avant pics de charge, exécutez tests synthétiques de canaux, appels d’outils contrôlés et vérifiez que les jobs d’arrière-plan ne volent pas les mêmes ressources que la passerelle. Documentez latences attendues pour éviter de mauvaises priorités support.
Dans des équipes mélangées macOS et Linux, harmonisez le vocabulaire des états de processus pour éviter les quiproquos dans les canaux d’incident.
L’observation longue durée révèle saisonnalité et fins de trimestre; intégrez ces motifs à la planification capacitaire plutôt que de scaler uniquement en réaction.
Les formations doivent montrer de vrais extraits journal ou logrotate afin d’aligner théorie et pratique et réduire l’onboarding.
Des checklists courtes sur chaque nœud limitent les erreurs humaines lors des rotations d’astreinte.
Fenêtres de mise à niveau et coexistence Docker
Planifiez ensemble mineures Node et releases OpenClaw pour éviter les écarts ABI entre deux fenêtres. Consignez effets attendus depuis les notes de version dans vos checklists internes.
Si des conteneurs coexistent, évitez ports en conflit et double supervision. Soit le conteneur est autoritaire, soit l’unit hôte, pas un compromis flou.
Les migrations de données entre chemins hôte et conteneur sont fragiles; centralisez les chemins dans un manifest versionné.
Les déploiements canary peuvent écouter un port distinct avant bascule de trafic. Documentez explicitement le rollback.
Communiquez interruptions attendues ou files ralenties aux utilisateurs internes pour éviter un support saturé de faux positifs.
L’ensemble doit rester cohérent avec le guide de production stable, y compris sauvegardes et rotation des secrets.
Après grosses mises à jour OS, relancez doctor et revérifiez les limites; les paramètres noyau peuvent changer et adapter les valeurs par défaut des units existantes.
Automatisez des tests d’units en CI pour éviter erreurs de templating sur les chemins.
Listez dépendances aux services tiers pour ne pas attribuer à tort une panne externe à votre passerelle.
Capturez des baselines de performance avant et après upgrades pour décider objectivement des ajustements de ressources.
Terminez chaque fenêtre par un bref rapport : métriques atteintes, risques résiduels, prochaines revues.
FAQ
cron suffit pour relancer ?
Pas comme stratégie principale; systemd et launchd offrent une meilleure sémantique.
Port 18789 occupé ?
Vérifiez localement puis conflits proxy ou seconde passerelle; voir exploitation passerelle.
Deux superviseurs ?
Évitez; choisissez une couche et documentez-la.
Conteneur plutôt que systemd ?
Si la reproductibilité prime sur I/O direct; détails dans Docker.
Synthèse et exploitation Mac distant
Synthèse : la résidence résout sessions et crashs en confiant le cycle de vie au système d’exploitation. La matrice aide à choisir launchd, systemd ou conteneur sans responsabilités doublonnées.
Limites : même des units parfaites ne remplacent pas proxys testés et chaînes TLS; combinez avec le guide proxy et la stabilité de production.
SFTPMAC aide les équipes via Mac distants hébergés pour expérimenter ces runbooks sans friction matérielle locale. L’objectif reste moins de redémarrages nocturnes et plus de résultats reproductibles.
Mac distants pris en charge et runbooks clairs réduisent la friction opérationnelle.