Catalogue OpenClaw & openclaw models sync
Dérive fournisseur, cache, auth — runbook (macOS à la journée)
Le Gateway démarre mais le routeur ne voit jamais les modèles que le CLI vient de synchroniser ; la sync se termine à 0 alors que le répertoire catalogue ressemble à un cache négatif ; les 401 ne frappent que les métadonnées — confondre la dérive OAuth avec des fautes de frappe dans les IDs coûte cher. Ce guide s’adresse aux auto-hébergeurs et SRE : trois clusters de douleur, matrice CLI/Gateway/config, sept étapes ordonnées, triage cache vs clés, trois chiffres, rythme 1–3 jours sur macOS natif, avec liens vers v2026.4.14 catalogue + doctor, v2026.5.5 canaux/npm et FAQ SSH/VNC.
Sommaire
01. Trois clusters
1) Sync OK mais catalogue vide « négatif » : certaines builds mettent en cache négativement les réponses vides. Un premier fetch 200 avec liste vide court-circuite les suivants comme « à jour ». Des shells parallèles avec anciennes variables OPENCLAW_* sur une machine louée amplifient le fantôme « compte A vs gateway B ».
2) Dérive fournisseur vs vue mémoire du Gateway : les alias doivent rester stables. Si l’amont retire un nom alors que openclaw.json le référence encore, la CLI peut afficher des lignes héritées du disque tandis que la validation au démarrage les supprime silencieusement. Suivez la triple lecture v2026.4.14 : disque, processus, amont.
3) 401 et 429 pliés en « model unavailable » : sans curl -v et lignes d’access Gateway horodatées, l’astreinte retombe sur « redémarrer ».
02. Matrice
Si vous touchez plugins npm et routage de canaux la même nuit, séparez les tickets comme dans v2026.5.5 pour ne pas confondre correctifs peer et table de modèles.
| Symptôme | CLI | Gateway | Mac loué |
|---|---|---|---|
| Console oui, liste non | exit 0, lignes JSON bizarres | catalog cache hit | vider cache, cold start |
| unknown model routeur | alias encore dans json | table in-proc sans ligne | doctor + redémarrage ordonné |
| 401 intermittents | métadonnées seulement | Authorization manquante/expirée | clé temporaire, une trace |
Gateway sous Linux et CLI sur macOS : consigner horloge et DNS dans le même ticket. « Sync disque OK » n’implique pas reload du conteneur.
03. Sept étapes
- Geler
openclaw --version, tag d’image, chemin absolu deopenclaw.json. - Doctor : séparer PASS et WARN.
- Sync models :
teestdout/stderr + code retour. - Sonder l’endpoint modèles du Gateway ; comparer les ensembles d’IDs.
- Aligner les alias ; redémarrage planifié, pas de rafales.
- Échantillonner deux modèles peu chargés + un principal, 20 appels chacun.
- Preuves & effacement : journaliser en masquant les secrets, révoquer les clés démo, purger le cache catalogue sur la machine louée. Vue d’ensemble : guide install/déploiement.
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor-baseline.txt
curl -sS -H "Authorization: Bearer ***" "https://gateway.example/v1/models" | head -c 4000Sous 16 Go libres, décompression/indexation du sync devient fragile. FAQ pour connectivité.
04. Triage
| Symptôme | Priorité | Erreur fréquente |
|---|---|---|
| Sync ok, liste plate | purge cache + GW froid | renommer seulement des alias |
| 401 sur métadonnées | rotation clés, chaîne Authorization | upgrade CLI majeur aveugle |
| unknown model + npm même nuit | tickets séparés | éditer canal+route en parallèle |
05a. Observabilité & SLO
Ne pas se limiter au temps de sync : délai jusqu’à « table modèles prête », écart entre fin de sync et mtime du catalogue, P95 sur premier hit froid. SLO du type « modèles interrogeables ≥ N et différence symétrique vs console ≤ K ». Router les pages 401 et unknown model vers des rotations différentes. Si vous montez temporairement l’échantillonnage des access logs, notez l’heure de retour à la valeur par défaut pour l’audit stockage. Étiquettes région sur les dumps pour éviter Tokyo à jour / Francfort obsolète interprété comme panne globale.
05b. Gestion du changement
Le catalogue est une API semi-publique : noms codés en dur dans des tests ou dashboards explosent la même nuit. Liste : fenêtre de retrait d’alias, fenêtre de migration du modèle par défaut, chemin vers le tarball précédent. Pourcentages fantômes plutôt que bascule brutale. Répéter rollback sur machine louée : doctor→sync→curl ; vérifier l’ordre de chargement npm.
05. Chiffres & rythme
- C1 : ~24–37 % des « catalogues bizarres » étaient cache/reload, pas panne longue amont.
- C2 : la matrice trois colonnes a réduit d’~0,7–1,5 itérations le premier retour à un routage sain.
- C3 : sous ~18 Go libres, retries sync+index ~10–22 % avant/après nettoyage.
Jour 1 : gel, doctor, sync, un curl de diff. Jour 2 : purge ou clés selon triage, échantillon trois modèles. Jour 3 : archiver journaux masqués, effacer la location.
06. Linux vs Mac journalier
Le Gateway Linux est mature ; pour Control UI, trousseau dev et capture réseau sur une seule machine dans une courte fenêtre de preuve, le macOS natif loué aligne mieux CLI, navigateur et exports catalogue. Location journalière cale l’OPEX sur le pic. Contexte tarifaire : guide coût Mac mini M4.
Plusieurs ingénieurs sur un même hôte : imposer des dossiers de preuve append-only nommés UTC+build. Jobs CI : figer les fichiers d’environnement, interdire la réutilisation de clés personnelles.
Fournisseur : rotation silencieuse d’URL d’émetteur JWT jusqu’à expiration du cache JWKS — documenter SLA métadonnées et sondes synthétiques.
Capacité : budget disque pour tarballs par release + espace de travail ; limites d’egress sur petits Mac cloud — sync hors pointe, débit dans le ticket.
Sécurité : restreindre qui lance la sync sur hôtes proches prod ; corréler audits avec commits Git sur openclaw.json.
Horloge : date -u sur hôtes CLI et Gateway dans le même ticket ; snippet runbook (reset cache, refresh token, restart) pour réduire l’improvisation.