invalid-key, checkpoints et hot-reload passerelle. Liens : embeddings / RAG, doctor & rollback. Sans compte : accueil, tarifs, aide, blog.
Trois tensions
- Runtime Node : un runner resté en 20.x masque des erreurs de schéma derrière des exceptions de parsing qui n’affichent pas le
schema_pathattendu. - Hot-reload : deux jobs écrivent le même fichier pendant qu’un reload est annoncé ; la sonde
/healthrepasse au vert avant la fin réelle du rechargement des routes. - Traçabilité : sans checkpoint horodaté, la MR ne peut pas prouver quelle version YAML a produit l’échec
invalid-keycôté passerelle.
À partir de 2026.3.x, le validateur rejette davantage de clés héritées des anciens packs de compétences ; versionnez donc le schéma attendu à côté du dépôt principal et annoncez toute fenêtre où la passerelle recharge ses routes pendant un merge automatisé. Sur runner partagé, journalisez le hachage du répertoire de configuration et la révision openclaw pour rattacher chaque nouveau invalid-key à un commit précis sans interroger l’astreinte à la main.
Liste de prérequis
Activez validate seulement si chaque job pointe vers le même OPENCLAW_CONFIG versionné, sans résidu dans ~. Vérifiez aussi que le daemon launchd ou l’agent CI n’injecte pas une variable d’environnement fantôme qui court-circuiterait le chemin attendu par la revue.
| Prérequis | Cible | Contrôle rapide |
|---|---|---|
| OpenClaw | branche 2026.3.x figée | openclaw --version + commit SHA dans le log CI. |
| Node.js | 22.12+ | node -v puis comparer semver au seuil. |
| Passerelle | port loopback documenté | curl -fsS http://127.0.0.1:${PORT}/health après reload. |
| Secrets | fichiers montés read-only | aucune clé brute dans le dépôt ; variables injectées par le orchestrateur. |
Commandes pas à pas
Ordre : prévol, checkpoint, doctor, validate, pause reload, /health. Adaptez CI_ARTIFACT_DIR à votre CI.
Sleep : laisse finir le hot-reload avant /health ; montez OPENCLAW_RELOAD_GRACE_SEC si NVMe partagé.
- Fixer
OPENCLAW_CONFIGsous le dépôt. tarcheckpoint avant toute édition.doctor --deep.gateway validate --format json.- Reload puis attente puis
/health. - Pousser logs et tarball en artefacts.
Signatures d’erreur fréquentes et dépannage
Croiser chaque signature avec schema_path dans validate.json.
| Signature | Interprétation | Piste |
|---|---|---|
invalid-key + schema_path | clé YAML hors schéma 2026.3.x | retirer la clé expérimentale ou la placer derrière un flag documenté. |
ECONNRESET sur reload | socket fermée pendant hot-reload | réessayer après grâce ; ne pas paralléliser deux reloads. |
Cannot find module interne | Node trop ancien ou cache npm corrompu | vérifier 22.12+ puis npm ci sur lockfile figé. |
401 sur route outil | jeton absent après reload | confirmer que les secrets restent montés après rotation. |
Si réseau et schéma se mélangent, rejouez validate sur le checkpoint seul ; voir auth modèle.
Pour le hot-reload, évitez de lire la configuration depuis un volume réseau pendant la fenêtre de reload : macOS peut signaler la fin d’écriture avant que le validateur interne n’ait relu le buffer ; copiez d’abord le fichier vers un chemin APFS local, validez, puis synchronisez vers la cible partagée si votre politique de sécurité l’exige.
Artéfacts CI et archivage
Joignez validate, checkpoint et doctor à chaque pipeline ; jamais de secrets en clair. Les équipes juridiques acceptent plus volontiers une rétention courte si le bundle contient déjà les empreintes cryptographiques et un index lisible des fichiers inclus, ce qui simplifie les audits croisés avec le dépôt Git principal.
| Artéfact | Rôle | Rétention indicative |
|---|---|---|
validate.json | preuve machine de conformité | 30–90 jours selon politique SOC. |
checkpoint.tgz + .sha256 | rollback byte-à-byte | même durée que la MR associée. |
doctor.log | contexte daemon et permissions | 14 jours si volumineux. |
health.json | preuve post-reload | alignée sur sprint courant. |
- Échec si
validatenon nul ouinvalid-keysans correctif. - Bot MR cite « fichier:ligne ».
- Deux
/healthaprès reload.
Informations retenues pour cadrage interne
- 2026.3.x aligné sur le lockfile npm infra.
- Node 22.12+ pour journaux validateur lisibles.
- Trois artefacts coupent le MTTR des régressions passerelle.
FAQ
Faut-il désactiver le hot-reload sur Mac multi-tenant ?
Sérialisez les écritures config et le reload ; voir durcissement passerelle.
Que faire si invalid-key n’affiche pas de ligne ?
JSON + Node 22.12+ ; sinon le parseur peut tronquer avant le schéma.
Le checkpoint remplace-t-il Git ?
Non : Git reste la vérité YAML ; le tarball sert au rollback runner.