OPENCLAW_2026.4.x
SESSION_
OAUTH_CRON_FIX.

Après les releases 2026.4.x rapides, trois symptômes se confondent : un canal vous salue comme un nouvel utilisateur, la Control UI signale un historique omis malgré un contexte faible, les logs affichent refresh_token_reused, et les tâches cron échouent silencieusement sur des schémas. Ce runbook impose sauvegarde, chirurgie JSON minimale sur sessions.json, OAuth sérialisé sans refresh concurrent, hygiène jsonl avec matrice de propriétaires, validation en couches doctor→probe→logs, y compris sur Mac distant sous launchd où les plist et le shell interactif doivent exposer les mêmes variables OPENCLAW_*. Pour les équipes RGPD, documentez finalité, sous-traitance et lieu des sorties cron, idéalement dans un stockage objet avec règles de cycle de vie plutôt que des dossiers locaux qui grossissent sans limite.

1. Modes de défaillance après itération 4.x rapide

D’abord, des overrides de session issus d’anciens builds peuvent figer modelOverride ou providerOverride sur des identifiants supprimés : un canal semble amnésique pendant que les autres restent sains. Ensuite, des flux de refresh parallèles entre un laptop CLI et une passerelle distante partagent le même jeton OAuth et produisent des 401 intermittents plutôt qu’un offline propre. Troisièmement, les cron volumineux génèrent des milliers de petits jsonl ; le démarrage à froid passe des secondes à les énumérer, ce qui ressemble à une lenteur globale. Quatrièmement, des EnvironmentVariables launchd différentes du shell interactif ressemblent à une dérive de config alors qu’il s’agit de deux sources de vérité. Nommer ces seaux avant d’éditer des fichiers évite les resets destructeurs.

Cinquièmement, les points de compaction dans sessions.json explosent quand l’UI avertit qu’historique a été omis ; certaines équipes accusent le modèle alors que pression disque, pruning agressif et messages surdimensionnés interagissent. Sixièmement, les déploiements multi-agents avec sous-arborescences sessions rendent facile la suppression du mauvais arbre sans carte propriétaire-métier. Septièmement, les reverse proxies qui retirent les en-têtes WebSocket imitent une corruption de session : la Control UI tombe alors que les sondes canal restent vertes en loopback. Huitièmement, l’antivirus Windows ou macOS verrouille parfois un jsonl en cours d’écriture et laisse du JSON partiel—toujours checksommer avant et après modification.

La télémétrie doit afficher version passerelle, SHA git si build source, version Node et espace disque libre sur le même tableau de bord que les erreurs OAuth. Sans ces dimensions, on chasse des fantômes entre environnements. Standardiser sur des images MACGPU Mac distant fige ces dimensions pour la durée du contrat ; la finance accepte mieux une ligne horaire lisible que des factures GPU cloud opaques dont la région change chaque mois. Croisez avec les articles MACGPU sur upgrades breaking avec doctor et gouvernance MEMORY.md pour ne pas confondre mémoire longue durée et état de session volatile.

2. Matrice symptôme → cause

Visible utilisateur	Piste suspecte	Première preuve
Un canal réinitialise le ton	Bloc empoisonné dans sessions.json	grep modelOverride, openclaw logs --follow
Disque occupé, CPU calme	Explosion cron jsonl	du -sh sous-répertoires sessions, comptage fichiers
OAuth fluctue après changement de modèle	refresh_token_reused	console fournisseur, openclaw models status
Schéma cron rejeté	Décalage payload agentTurn	openclaw cron runs --limit 20

Une matrice à quatre champs (canal payant vs données personnelles) réduit la fatigue du changement. Des champs ticket pour la catégorie racine (session, OAuth, cron, réseau, horloge) accélèrent les post-mortems et évitent qu’une escalade se termine toujours par « reset complet » avant d’évoquer un rollback basé sur diff.

3. Récupération en cinq étapes

Étape 01 Geler et sauvegarder

Arrêter la passerelle, copier sessions.json vers sessions.json.bak, archiver tout l’arbre sessions plus openclaw.json en tarball. Pas d’édition in-place sans chemin de restauration. Hasher et horodater le ticket pour aligner révision et mtime disque.

Étape 02 Chirurgie JSON minimale

Trouver le plus petit objet fautif pour la clé canal cassée et ne supprimer que celui-ci. Effacer tout l’index seulement si la direction accepte le coût complet de re-pairing. Avant commit, montrer diff -u contre la sauvegarde et obtenir validation d’un pair.

Étape 03 Sérialiser OAuth

Révoquer les refresh obsolètes chez le fournisseur, onboarder un hôte à la fois, garder les nœuds secondaires arrêtés jusqu’à fin du refresh primaire. refresh_token_reused signifie presque toujours des refresh concurrents, pas du malware. Documentez quel hôte détient d’abord le jeton pour rendre les rotations auditables.

Étape 04 Hygiène cron jsonl

Inventorier répertoires avec propriétaire et politique de rétention ; supprimer uniquement les historiques cron redondamment confirmés ; vérifier les pointeurs sessions.json contre chemins réels. Puis cron list et échantillon cron runs. Si des jobs disparaissent après nettoyage, restaurer le JSON registre depuis sauvegarde plutôt que deviner des champs à la main.

Étape 05 Validation en couches

Exécuter openclaw doctor, channels status --probe, redémarrer la passerelle, envoyer messages de sonde. Sur Mac distant, comparer EnvironmentVariables de la plist au shell utilisé pour déboguer ; kickstart après modifications. Corriger NTP avant que les erreurs OAuth ne s’amplifient.

4. Garde-fous numériques

Si sessions.json dépasse vingt mégaoctets et le scan à froid dépasse huit secondes en p95, planifier archivage structuré plutôt qu’une croissance infinie. Si un bloc canal code en dur un modèle différent des défauts et s’associe à deux erreurs OAuth, supprimer ce bloc avant reset global. Si le nombre de jsonl dépasse mille cinq cents avec trente pour cent de croissance sur sept jours, déplacer la sortie cron vers stockage objet ou rotation par date. Si l’horloge dérive de plus de cent vingt secondes, réparer NTP d’abord.

5b. Instrumentation (extraits)

Ajoutez un cron nocturne hors OpenClaw—ironique mais utile—qui journalise du -sh par sous-arbre sessions vers un fichier métrique déjà scrapé par votre stack. Alerte si la croissance semaine sur semaine dépasse vingt pour cent sans lancement de feature associé. Ajoutez en CI une ligne jq qui casse le build si les fixtures tests font grossir sessions.json au-delà des seuils policy. Ces garde-fous coûtent quelques minutes et économisent des heures d’incident en distinguant trafic organique d’un job fou. Taguer chaque mesure avec semver passerelle pour corréler pics et fenêtres de déploiement. Chaque édition JSON manuelle exige une entrée changelog avec identifiant ticket.

5. Étude de cas : alerte sécurité, cause override obsolète

Une équipe de cinq personnes est passée en 2026.4.11 et a vu WebChat et Telegram signaler un historique omis avec compteurs de contexte bas. L’incident a démarré jusqu’à ce qu’un ingénieur fouille sessions.json et trouve rotations rapides plus modelOverride obsolète. Après suppression du bloc et refresh OAuth sérialisé, les symptômes disparaissent. Les dumps cron migrent vers stockage objet et l’hygiène jsonl trimestrielle devient obligatoire. Moralité : les diffs JSON avec empreintes battent la panique narrative et raccourcissent la validation juridique.

Le rétro ajoute des modèles de communication pour la direction qui ne voit que des captures Telegram. Un jour d’exercice injecte volontairement un bloc synthétique en staging et mesure combien de temps le second on-call met à documenter un rollback basé sur diff. Les clients MACGPU peuvent demander des images préconfigurées pour cet exercice afin que les nouveaux n’apprennent pas sur incident réel.

À long terme, la leçon nourrit la planification capacité : chaque jsonl conservé coûte des inodes et des entrées d’annuaire lors de l’énumération. Même sur APFS, les métadonnées coûtent quand les charges utiles sont minuscules. L’archivage par préfixe de date en bundles compressés bat l’infini de micro-fichiers. Les hôtes distants NVMe avec fenêtres de maintenance planifiées rendent cela viable sans réveiller un portable à trois heures du matin.

6. FAQ et fenêtres de temps

Ne supprimez pas tout l’arbre sessions sans accepter le re-pairing complet. Si la Control UI demande pairing alors que les sondes sont vertes, vider les données de site ou fenêtre privée et vérifier gateway.bind derrière reverse proxy. Préférez doctor passerelle arrêtée pour éviter faux négatifs liés aux verrous fichiers.

Docker Desktop change les chemins : les montages volume peuvent masquer la même sessions.json que l’éditeur hôte prétend modifier—vérifiez toujours le home conteneur. Tailscale MagicDNS peut brouiller le pairing : journalisez l’URL exacte de la Control UI et comparez à gateway.remote.url. Upgrade Node sans redémarrage launchd laisse souvent des binaires partiellement anciens—ajustez ProgramArguments ou kickstart après toolchain.

Les équipes multi-régions documentent quel fuseau possède les définitions cron et si heartbeat.quietHours masque des échecs silencieux ; exposez ces fenêtres sur le tableau on-call. Documentez les chaînes de repli modèle : quand Anthropic refuse les longs contextes, l’agent peut changer de modèle et réécrire les métadonnées session—ce saut doit apparaître dans les logs avant suppression de blocs.

Boîte de réponse : zéro à quinze minutes inspection lecture seule, quinze à quarante-cinq minutes reproduire suppressions sur copie, reset global seulement avec justification ticket. Changements de nuit : revue à quatre yeux. Tabletop trimestriel : injecter bloc synthétique, pager le second on-call, mesurer le temps jusqu’au rollback documenté par diff.

7. Vue métier et déport vers Mac

En 2026, les agents compétitifs seront jugés sur la gouvernance du magasin de sessions, pas sur le nombre de canaux. Traitez sessions.json comme infrastructure versionnée à côté de MEMORY.md pour la connaissance longue durée. Les passerelles Mac distant exigent snapshots plus vérité plist alignée sur les shells—sinon les portables dorment à travers des OAuth à moitié finis. Les seuls laptops suffisent pour itérer en solo ; les équipes avec preuves de changement signées et stabilité vingt-quatre sur sept déplacent souvent la passerelle vers Apple Silicon hébergé comme les nœuds MACGPU avec images figées et disques surveillés.

Si vous avez validé OpenClaw sur Windows ou Linux mais heurtez la stabilité longue durée, les compétences multimédia adjacentes ou la compatibilité toolchain, un Mac distant sépare les expériences du plan de contrôle toujours joignable avec alimentation prévisible. Cela complète l’hygiène sans la remplacer. Pour moins de serveurs possédés et une passerelle résiliente, louez la capacité MACGPU et gardez les CLI locales légères.

La conformité demande de plus en plus des preuves de rétention sur données conversationnelles. Quand les dumps cron vont dans l’objet avec règles de cycle de vie, vous montrez une politique de bucket plutôt qu’un dossier laptop qui gonfle. Le juridique surveille l’export : un Mac Studio loué dans la bonne juridiction sous DPA se défend mieux que des régions GPU qui changent au gré du vent. L’ingénierie gagne en reproductibilité : images MACGPU figées donnent les mêmes sorties doctor en staging et prod et réduisent la fenêtre de blâme après upgrade.

L’observabilité doit encapsuler démarrage et arrêt passerelle avec logs structurés envoyés hors machine. Suivre hebdomadairement durée de démarrage à froid, nombre jsonl, taille sessions.json, taxonomie erreurs OAuth et taux d’échec cron. Accrocher les alertes à des seuils dérivés de cet article plutôt qu’à des défauts arbitraires. Lier métriques à des tickets lisibles référencant hachages de diff JSON pour éviter que les post-mortems ne deviennent opinion.

Note capacité : chaque jsonl retenu coûte inodes et entrées d’annuaire ; APFS paie aussi les métadonnées sur petites charges. D’où l’intérêt des bundles archivés par date plutôt que des milliers de fichiers. Les hôtes distants NVMe avec fenêtres de maintenance rendent l’archivage pratique sans réveiller les portables à trois heures du matin. MACGPU peut intégrer ces fenêtres dans la description de service et réduire la charge pager.

Comparaison finale : tout réinitialiser est vite émotionnellement, cher contractuellement. Triage en couches, sauvegardes, OAuth sérialisé et nettoyage jsonl mesuré préservent pistes d’audit et confiance client. Si votre organisation veut la stabilité native Apple sans posséder des baies, la location Mac distant MACGPU complète pragmatiquement ce runbook. Documentez les éditions JSON manuelles avec identifiant ticket et mtime fichier pour aligner révision et système de fichiers.

Les équipes conformité exigent des rapports hebdomadaires avec p95 démarrage à froid, taux d’échec cron et classes d’erreurs OAuth ; dépassement de seuil ouvre automatiquement des tickets plateforme. Injectez trimestriellement des blocs empoisonnés synthétiques en staging et maintenez un score on-call pour rollback par diff. Mettez à jour les contacts d’urgence en parallèle de la documentation.

Pratique opérationnelle additionnelle : versionnez les snapshots sessions.json avec la même étiquette que la release passerelle pour que les rollbacks ne devinent pas quel état correspond à quelle binaire. Attribuez à chaque canal un propriétaire technique et un propriétaire métier pour éviter les disputes marketing-plateforme sur suppressions. Utilisez des comptes diagnostic en lecture seule autorisés seulement doctor et logs pour éviter des refresh OAuth accidentels depuis laptops curieux. Documentez explicitement quelles variables d’environnement shell valent pour les sessions interactives et ce que launchd impose, y compris PATH et HOME sous changement rapide d’utilisateur. Si plusieurs instances OpenClaw cohabitent sur un hôte, séparez strictement les répertoires de travail et interdisez les chemins sessions partagés dans la doc et le lint CI. Pour équipes EU-US mélangées, centralisez fuseaux et durées de rétention dans un calendrier unique afin que l’hygiène cron ne parte pas par erreur hors fenêtre de maintenance et reste silencieuse côté pager.

Enfin, gardez notes de release et runbook dans le même contrôle de version que l’infrastructure-as-code pour rendre le rollforward aussi auditable que le rollback. Des modèles de post-mortem courts avec champs obligatoires catégorie cause racine, hachages de fichiers impactés et temps jusqu’à première sonde verte réduisent le temps de réunion et accélèrent la montée en compétence des nouveaux ingénieurs.

Rappel : des sauvegardes sans test de restauration sont décoratives—planifiez chaque trimestre une restauration contrôlée sur hôte jetable et mesurez la durée jusqu’à passerelle joignable, en documentant explicitement les écarts.