Points de douleur : preuves avant le récit
Douleur 1 : prendre un titre de fil pour une note de version.
Douleur 2 : analyser la mémoire sans mesurer l’I/O JSONL.
Douleur 3 : répondre au gel de canal par un kill brutal.
Douleur 4 : oublier TLS et en-têtes du proxy.
Douleur 5 : tenter un rollback sans snapshot.
Grappes de symptômes observés dans les rapports publics
Une frise unique pour JSON, binaire et proxy
Les fils sur OpenClaw 2026.4.5 mélangent souvent trois plans : le fichier JSON réellement lu, le redémarrage du processus gateway et les réécritures d’en-têtes WebSocket par un reverse proxy. Sans frise commune (empreintes, sortie doctor, métriques), on sur-réagit sur semver.
Mémoire : séparer tas et I/O JSONL
Une RSS qui monte peut venir de grosses sessions .jsonl, de processus enfants MCP ou des deux. Mesurez I/O wait, descripteurs ouverts et rotation des logs avant de décider d’un downgrade.
WebSocket derrière inspection TLS
Comparez chemin LAN direct et chemin nginx/Caddy (guide TLS/WebSocket) avant d’incriminer le binaire passerelle.
MCP stdio et redémarrages complets
Si des enfants survivent aux reloads, il faut un cycle complet documenté dans le runbook MCP.
Rollback raisonné
Épingler 4.4.x est une décision produit : canaris, fenêtre d’observation, minimisation des données dans les archives conformément au RGPD.
Matrice de décision
| Voie | Quand | Avantage | Risque |
|---|---|---|---|
| Rester en 2026.4.5 + hygiène | rotation JSONL et cycles MCP suffisent | derniers correctifs | observabilité continue |
| Corriger la config seule | doctor montre un renommage | rayon minimal | cause binaire possible |
| Pin 4.4.x | canari stable | stabilité réglementée | dette technique |
| Restauration snapshot | état corrompu | état global connu | fenêtre d’indisponibilité |
Procédure en six étapes
# Exemple de paquet de preuves
# date > /tmp/openclaw-incident.txt
# ps aux | grep -i openclaw >> /tmp/openclaw-incident.txt
# shasum openclaw.json >> /tmp/openclaw-incident.txt
# ls -lh ./sessions/*.jsonl >> /tmp/openclaw-incident.txt
Étape 1 : figer versions, unités, variables d’environnement et hachages.
Étape 2 : exécuter status→gateway→logs→doctor.
Étape 3 : aligner JSON disque et sondes runtime, valider les clés proches de cliBackends.
Étape 4 : mesurer JSONL, rotation en fenêtre, comparer la latence.
Étape 5 : tester WebSocket direct et via proxy, TLS et Authorization.
Étape 6 : si besoin, pin 4.4.x sur canari, observer RSS et reconnexions 24 h.
Raffiner l’exploitation des pools Mac partagés
Quand plusieurs équipes partagent un même Mac distant, les chemins JSONL et les logs gateway ne devraient pas vivre dans le home d’un seul utilisateur mais sur des volumes structurés avec ACL. Cela évite qu’un job d’indexation agressif vole le débit disque aux intégrations chat.
Pour les builds Apple Silicon, séparez clairement cache d’artefacts et sortie de signature. Le cache peut être volatile ; les signatures exigent des chemins déterministes et des manifestes de checksum. Les sessions OpenClaw qui reflètent de gros segments binaires dans JSONL ne doivent pas mélanger ces chemins.
Mesurez le délai entre démarrage gateway et première poignée de main WebSocket réussie. Une bosse soudaine après mise à jour proxy pointe souvent vers limites d’en-têtes ou buffering, pas vers une fuite mémoire du noyau.
Fixez par environnement un minimal de commandes CLI que le support peut exécuter avant escalade. Trop long, la liste est ignorée ; trop courte, il manque des preuves.
Planifiez les fenêtres de maintenance pour éviter collision entre rotation JSONL et nuits de release iOS. Les corrélations accidentelles accusent semver à tort.
Documentez quelle version Node le processus gateway utilise réellement, chemin compris via launchctl print ou systemctl status. Un second Node dans le PATH après upgrade est un piège fréquent.
Si vous chargez dynamiquement des serveurs MCP, tracez l’ordre d’initialisation. Les races au démarrage se manifestent par erreurs WebSocket sporadiques difficiles à reproduire.
Pour les certificats TLS derrière CA internes, notez séparément expiration et chaîne du cycle gateway. Une rotation TLS mal coordonnée imite une régression produit.
Tenez une liste blanche des endpoints externes contactés par le gateway. Les nouvelles fonctionnalités ajoutant des hôtes doivent prévenir l’équipe pare-feu, sinon timeouts artificiels.
Formez l’astreinte à arrêter proprement les processus MCP sans perdre les sessions actives. Les kills brutaux aggravent la corruption JSONL.
Liez les changements openclaw.json à des modèles de PR exigeant hashes et sorties doctor. La dérive de configuration reste visible.
Surveillez la taille des réponses d’outils dans les logs. De très gros payloads bloquent des canaux même si la RSS semble stable.
Testez la panne IdP OIDC pendant cinq minutes : la réponse doit décrire une dégradation contrôlée, pas seulement un redémarrage.
Archivez chaque incident avec semver, version proxy et hash de snapshot JSONL pour accélérer les tests de régression ultérieurs.
Définissez le seuil JSONL au-delà duquel compression ou externalisation automatique s’applique, afin d’éviter des scripts ad hoc divergents.
Intégrez les alertes au système de tickets avec corrélation hôte/environnement pour éviter de fermer des doublons alors que d’autres nœuds restent impactés.
Réévaluez périodiquement si un pin permanent 4.4.x reste justifié lorsque des correctifs upstream sont documentés. La dette technique grossit silencieusement.
Pour les équipes créatives utilisant OpenClaw avec médias, les gros pièces jointes font exploser la session. Des pipelines d’upload séparés soulagent le chemin chat.
Assurez que les sauvegardes ne concourent pas avec la rotation JSONL sur le même stockage. Sérialisez les tâches d’entretien.
Rédigez des playbooks VPN versus accès direct avec en-têtes WebSocket attendus. Beaucoup de régressions viennent du changement réseau, pas de la release.
Documentez les limites mémoire du gateway par rapport au parallélisme attendu des canaux. Sous-dimensionner provoque des tempêtes GC ressemblant à des soucis d’auth.
Listez les mesures d’urgence interdites, comme suppression globale de JSONL sans sauvegarde. La culture protège plus que les outils.
Métriques et alarmes
Croiser RSS, octets JSONL, reconnexions WebSocket, p95 des canaux et semver sur une même frise ; chaque mesure doit se prouver dans le tableau de bord.
Fixez des seuils par environnement : la production alerte plus tôt sur la croissance JSONL que le staging, car la charge diffère. Évitez les seuils globaux qui ne font que du bruit.
Corrélez les redémarrages gateway avec les déploiements et le SHA Git du dépôt de configuration. Des redémarrages sans commit pointent souvent hors semver.
Pour Telegram/Slack/Webchat, suivez longueur de file et taux d’erreur séparément du CPU ; cela isole plus vite les quotas API externes.
Maturité opérationnelle sans pinning permanent
Un pin semver permanent se comprend, mais coûte : correctifs tardifs, dépendances divergentes, perte de confiance dans les upgrades. Prévoyez des revues trimestrielles montrant si l’hygiène a déjà calmé les symptômes.
Intégrez la rotation JSONL aux changements normaux, pas seulement aux incidents. Si elle n’arrive qu’après panne, la courbe de taille masque la tendance.
Créez des tests de charge synthétiques avec grosses réponses d’outils pour voir les goulots de canaux tôt, loin des données prod mais à taille comparable.
Documentez la matrice gateway-version / Node-version. Monter l’un sans l’autre est une source fréquente de codes WebSocket obscurs.
Pour les équipes globales, indiquez fuseaux et fenêtres dans les runbooks afin d’éviter collisions de changements et fausses régressions.
Exigez dans les PR un paragraphe « impact observabilité » décrivant métriques ou logs. Sinon la visibilité reste derrière les feature flags.
Planifiez la rétention des archives de session avec validation juridique. La rotation technique sans base légale crée du risque.
Répétez les rollbacks sur staging avec volumes proches de la prod. Un staging vide ment sur la stabilité.
Tenez une liste des manipulations d’en-têtes proxy connues dans l’entreprise pour accélérer le diagnostic post-release.
Corrélez métriques gateway et coûts infra : si JSONL croît avec le stockage, la priorisation devient évidente.
Formez les nouveaux avec un incident fictif et de vraies commandes sur données synthétiques pour réduire la friction autour de doctor.
Définissez des critères de sortie pour canaries : quelles métriques doivent tenir 24 h avant d’étendre le pin. Sans critères, les canaries restent isolés indéfiniment.
Archivez les post-mortems avec versions des serveurs MCP. Beaucoup d’instabilités viennent des plugins, pas du cœur.
Vérifiez périodiquement les vieux LaunchAgents ou unités systemd pointant vers d’anciens chemins. Les zombies provoquent des redémarrages « aléatoires ».
Dédupliquez les alertes pour éviter dix tickets identiques sur JSONL. Le bruit tue l’attention.
Favorisez petites releases fréquentes plutôt que big-bangs rares pour lier symptômes et changements.
Donnez aux équipes proxy une mini-checklist pour upgrades gateway. La communication cross-fonction évite les configs fantômes.
Documentez les limites des vieux navigateurs pour le webchat. Les dettes client sont hors semver mais cassent l’expérience.
Prévoyez du temps humain pour analyser JSONL si l’automatisation échoue. L’expertise reste nécessaire mais ne doit pas être permanente.
Clôturez chaque revue d’incident avec un seul ticket de suivi concret plutôt qu’avec « plus de monitoring » vague.
Playbooks quand plusieurs équipes partagent la responsabilité
Si gateway, réseau et IdP ont des KPI différents, les playbooks d’incident doivent dire qui fournit les logs, qui teste le proxy et qui tranche semver. Sinon le MTTR s’allonge.
Fixez un fil unique par incident, pas plusieurs chats parallèles, pour ne pas disperser les preuves.
Définissez la durée maximale des feature flags expérimentaux en production avant retrait automatique. Sans échéance, la config fantôme croît.
Construisez une mini-bibliothèque de sorties doctor typiques avec interprétation courte pour accélérer l’onboarding.
Après chaque release majeure, vérifiez que les tableaux de bord pointent encore vers les bons noms de métriques. Les renommages cassent silencieusement les vues.
Standardisez la feuille de passation entre astreintes : canaris actifs, pins ouverts, déploiements attendus. La perte de contexte entre shifts est fréquente.
Ajoutez un rappel hebdomadaire pour inspecter la taille JSONL, pas seulement lors d’alertes. La prévention coûte moins que l’urgence.
Listez les télémétries SaaS externes autorisées. Une télémétrie surprise peut violer la conformité et gonfler JSONL.
Formez les PO : releases rapides augmentent la charge d’observabilité. Budgétisez la maintenance des dashboards.
Tenez sous la main les pages de statut fournisseurs à consulter avant rollback interne.
Évaluez les serveurs MCP comme des services prod : versions, signatures, chemin de rollback.
Définissez la rétention des traces WebSocket brutes : trop long augmente stockage et risque, trop court complique l’analyse.
Planifiez des chaos tests ciblés sur erreurs proxy pour vérifier que les runbooks fonctionnent, pas seulement que le système tombe.
Archivez les mitigations réussies comme modèles réutilisables pour symptômes similaires.
Exigez après incident une note sur les tests manquants pour détecter plus tôt la prochaine fois.
Intégrez le coût stockage JSONL au budget projet pour financer l’hygiène long terme.
Vérifiez que la rotation des secrets CI couvre aussi les tokens côté gateway. Sinon défaillances partielles étranges.
Clôturez les revues trimestrielles avec une liste unique : risques acceptés vs atténués pour clarifier les décisions semver.
FAQ et pourquoi des Mac distants managés aident
Chaque symptôme cliBackends est-il un bug avéré ?
Non ; doctor et hachages doivent prouver la configuration effective.
Supprimer un JSONL géant en ligne ?
Risqué ; préférer rotation avec sauvegarde.
Downgrade immédiat si WebSocket échoue ?
Isoler d’abord proxy et TLS.
Synthèse : structurer les symptômes publics, collecter des preuves, appliquer l’hygiène, puis décider du semver.
Limite : stockage hétérogène et proxys d’entreprise exigent un réglage continu.
Contraste : SFTPMAC réduit souvent la variance disque/réseau sur Mac distants managés, ce qui rend JSONL et canaux plus prévisibles.
Instantané, doctor, rotation JSONL, contrôle TLS, puis décision de semver.