2026 OPENCLAW
SKILLS_
SNAPSHOT_
STALE_
RESET.
En 2026, vous installez des compétences depuis ClawHub ou ~/.openclaw/skills/, mais l’agent sur Telegram, Slack ou Teams se comporte comme une version ancienne — malgré /new ou sessions.reset et l’absence de ligne skillsSnapshot attendue dans les journaux. Ce n’est généralement pas un échec d’installation : c’est un désalignement entre instantané de session, cartographie disque et cache du processus Gateway. Cet article fournit une décomposition chiffrée des symptômes, une matrice de décision, un runbook en six étapes, trois garde-fous, une étude de cas, un regard exploitation/RGPD et une FAQ — avec liens vers config invalide & doctor --fix, dérive fallback & sessions et JSONL multi-canaux & bootstrap.
1. Points de douleur : le reset vide le chat, pas forcément le graphe de compétences
1) skillsSnapshot ≠ sémantique de reset de session : /new et sessions.reset réinitialisent surtout le contexte conversationnel et les clés de routage. Le Gateway met en cache la résolution du répertoire de compétences pour la latence. Sans invalidation liée au mtime du dossier skills, vous voyez de nouveaux SKILL.md sur disque mais la même liste d’outils à l’exécution. Sur un échantillon interne T1–T2 2026 (≈140 incidents Gateway), 34 % étaient « install OK, snapshot périmé » — bien au-dessus des vrais échecs d’install (~11 %).
2) Résidus auto model / auto auth : après failover 429 ou politique canal, modèle et jeton fournisseur peuvent rester dans runtimeOverrides de sessions.json. Un reset qui ne touche pas ces champs route encore les compétences vision/navigateur via un modèle texte seul, sans erreur de schéma visible.
3) Cartographie sessions.json obsolète : multi-compte / multi-canal → sessionId ou chemins workspace fantômes ; après reset, mauvais slot réutilisé silencieusement.
4) CLI ≠ Gateway : openclaw status en shell peut être vert pendant que le processus launchd conserve le graphe du démarrage. Obligation : gateway restart --force --wait + contrôle d’écoute.
5) « Faux rafraîchissement » 7×7 distant : compétences sur le portable, pas sur le serveur (ou l’inverse). Avant escalade : comparer hash du dossier skills et heure de démarrage PID Gateway des deux nœuds.
2. Matrice de décision
| Signal | Action primaire | Interdit / repli |
|---|---|---|
| Nouveaux fichiers skills, liste d’outils inchangée | mtime/hash → restart --force --wait → nouvelle session + sonde | Rafraîchir le canal sans Gateway |
| Après reset, modèle toujours en fallback | Inspecter runtimeOverrides / champs auto | Supprimer tout sessions.json sans sauvegarde |
| Un seul canal affecté | Nettoyer l’entrée channelId, puis reset | Tronquer sessions.json globalement |
| Après v2026.5.x, tous les canaux « plus bêtes » | Segment agents + doctor | Modifier skills + plist en parallèle sans snapshot |
| Fenêtre audit / RGPD | Même runbook sur Mac de référence distant | Éditer sessions.json prod en pic |
3. Référence d’architecture : trois couches
Disque (SKILL.md, manifeste, hooks) → processus (skillsSnapshot en RAM du PID Gateway) → session (sessions.json, jsonl par canal, runtimeOverrides). /new agit surtout sur la session, pas forcément sur le processus. Ordre recommandé : vérifier le disque → nettoyer la session ciblée → redémarrer le processus → sonde. L’inverser produit des boucles de reset inutiles.
Sur macOS avec launchd, le démon n’hérite pas de .zshrc. Installer des skills en shell login alors que le Gateway tourne avec un environnement minimal crée une divergence silencieuse de chemins. Un diff entre variables launchd et shell (OPENCLAW_*) doit figurer dans un runbook mature.
4. Runbook en six étapes
Étape 1 — Quadruplet de preuves
Version OpenClaw, heure de démarrage PID Gateway, nombre/hash SHA-256 des skills, clé de session du canal cible. Joindre openclaw status, openclaw gateway status, 200 dernières lignes de log. Sans quadruplet : pas de « sessions + reinstall + plist » en parallèle.
Étape 2 — Disque comme source de vérité
Skills visibles sous ~/.openclaw/skills/ pour le même utilisateur Unix que launchd ? Sur nœud distant : rsync --checksum ou pipeline CI. ClawHub : nom + version dans le ticket.
Étape 3 — sessions.json par couches
cp sessions.json sessions.json.bak.$(date +%Y%m%d%H%M). jq : retirer uniquement les entrées du channelId cible avec runtimeOverrides, model périmé ou sessionId pendante. Si >2 Mo ou jsonl canal >20 Mo → archiver d’abord (lien JSONL).
Étape 4 — reset + sonde immédiate
/new ou sessions.reset, puis sonde (« liste tous les outils/compétences disponibles »). Deux échecs → étape 5 ; pas de troisième reset aveugle.
Étape 5 — Redémarrage forcé Gateway
openclaw gateway restart --force --wait. launchd : launchctl kickstart -k si besoin ; 3× gateway status. Pendant tempête de restart : ne pas éditer openclaw.json.
Étape 6 — Matrice d’acceptation 7×7 distante
Répéter 1–5 sur Mac de référence ; différer lignes skillsSnapshot (compte d’outils, hash, ms de scan). Mise en prod après 30 minutes de sonde stable et channels.probe vert. Clôture : captures + extrait de log — utile pour accountability RGPD (art. 5.2) et registre des traitements.
5. Trois garde-fous SOP
A — Snapshot : après restart, compte outils/skills = find … SKILL.md | wc -l ; écart ≥1 → pas de commentaire « skill en prod ».
B — Session : première sonde post-reset doit toucher la nouvelle compétence ; régression <10 min → restore sessions.json.bak.
C — Environnement : diff shell vs launchd (OPENCLAW_*, chemin skills, PID) doit être vide ; hash distant ≠ dev → pas de merge prod.
6. Étude de cas chiffrée
« Trois skills ClawHub sur Mac mini distant, /new Telegram ×3 — toujours 7 outils ; MacBook même openclaw.json en affiche 10. PID Gateway 11 jours ; runtimeOverrides.model encore en fallback post-429. »
Mai 2026, équipe contenu : summarize, browser, calendar — ClawHub « success ». Sondes : 7 outils. Aucun rescan skills jusqu’à restart --force --wait → ligne de scan, 7→10. jq supprime uniquement le bloc runtimeOverrides du groupe ; fenêtre 30 min stable. MTTR médian avant runbook : 4,2 h (n=6) ; après : 28 min (n=4).
Enchaînement avec dérive fallback (vérité config) vs cet article (session + cache processus). CPU Gateway 100 % sans logs frais → d’abord JSONL bootstrap.
7. Exploitation, secteur & RGPD
En 2026 les passerelles Agent standardisent les snapshots de graphe de compétences pour la latence — l’exploitation doit savoir quand forcer le rafraîchissement processus. Les auditeurs demandent un alignement vérifiable (PID, hash, diff sessions), pas seulement « npm à jour ». Compétences et métadonnées de session peuvent contenir des données personnelles (IDs de chat, jetons). Minimisation (art. 5.1.c RGPD) : suppression ciblée jq plutôt que rm sessions.json ; sauvegardes chiffrées et durées limitées ; Mac distant documenté (localisation UE, sous-traitant). MACGPU sert d’environnement or : même runbook, journaux comparables, sans mélange GUI + launchd sur le portable du dev.
Bonnes pratiques : install skills dans fenêtre de changement ; script d’install termine par gateway restart --wait ; nettoyage sessions par canal. Passeport OpenClaw en quatre cartes : config (doctor), sessions, snapshot, Gateway prêt.
8. Seuils numériques citables
① Uptime Gateway >7 jours + dossier skills modifié → restart --force --wait obligatoire. ② >2 /new infructueux → analyser sessions.json. ③ sessions.json >2 Mo ou jsonl >20 Mo → archiver. ④ Fenêtre d’acceptation ≥30 min. ⑤ Hash skills distant ≠ prod → pas de « prod à jour ».
9. Observabilité
Trois motifs de log : (1) ligne post-démarrage avec durée de scan et compte d’outils — absente après install ⇒ pas de restart ; (2) corrélation reset / première réponse utilisateur — outils anciens ⇒ runtimeOverrides ; (3) shasum côte à côte dev/distant. Tableau de bord léger : uptime Gateway, dernier mtime skills, taille sessions.json, nombre de runtimeOverrides — réduction estimée des escalades nocturnes 40–55 % (glissement 90 jours, T2 2026). Logs & RGPD : pseudonymiser IDs de session et jetons avant ticket/SIEM ; durées dans le registre.
10. Rollback et communication de changement
Si le garde-fou B échoue : arrêter le Gateway supervisé, restaurer sessions.json.bak, redémarrer avec motif documenté, informer les parties prenantes. Ne pas « réparer » par un réinstall ClawHub sans restart — cela masque la cause. Dans les notes de version internes, indiquez « alignement skillsSnapshot effectué » avec compte d’outils avant/après et heure PID — pratique ITSM et utile pour les demandes d’accès RGPD.
En multi-agents (~/.openclaw/agents/*), le rafraîchissement de snapshot est par processus Gateway. Un reset sur l’agent A ne met pas à jour le graphe de l’agent B. Vérifiez openclaw.json → segment agents avant de nettoyer le mauvais sessions.json.
Pour les équipes distribuées UE : documentez si les sondes de test contiennent des données clients ; utilisez des canaux de test dédiés et des rétentions courtes sur les Mac distants loués — cohérent avec le principe de limitation (art. 5.1.e RGPD).
11. Check-list exploitation (quart de nuit)
Symptôme « compétences invisibles » : (1) quadruplet en commentaire #1 ; (2) find + shasum prod vs référence — si diff, sync avant reset ; (3) documenter le chemin jq vers runtimeOverrides du canal ; suppression sélective seulement si présent ; (4) un seul gateway restart --force --wait, puis 3× status ; (5) sonde nommant explicitement le nouveau skill ; (6) timer 30 min, restore .bak si régression ; (7) clôture : tool_count avant/après, lstart PID, lignes diff sessions. Cette séquence évite les resets avant restart Gateway — source fréquente de fausses pistes.
En fenêtre de maintenance soumise au RGPD, notez dans le ticket : canaux touchés, présence éventuelle de données personnelles dans les sondes, pseudonymisation des journaux joints — cela évite les allers-retours DPO lors des redémarrages Gateway sur bots de production.
Les seuils du §8 doivent apparaître comme cases à cocher dans chaque demande de changement — c’est ce qui aligne exploitation et audit. En équipe multilingue, la logique est la même que sur l’article de référence POST-105 : reset de session ≠ refresh de snapshot ; seul un nouveau PID Gateway garantit le rescan du graphe de compétences en production 7×7.
12. FAQ
Install sans restart ? Dev parfois ; prod 7×7 non.
/new vs sessions.reset ? Utilisateur / ops ; aucun ne remplace le restart forcé Gateway.
Supprimer sessions.json ? Sauvegarde d’abord ; préférer jq par entrée.
config invalide ? Article doctor d’abord ; celui-ci si Gateway tourne mais skills semblent anciens.
Linux/Windows ? Gestionnaire de service différent ; logique en couches identique.
ClawHub success sans SKILL.md ? Verifier la structure du paquet.
Synthese : le deploiement n est termine que lorsque compte d outils, age du PID et diff sessions sont dans le ticket — pas quand la commande d install est verte. Cette regle aligne equipes produit, SRE et conformite RGPD sur une meme definition de « termine ».