Notes de modification · matrice de décision · runbook en huit étapes · lignes de tickets · console VNC
OpenClaw v2026.4.25 place le démarrage des plugins sur un registre persistant « froid » : au lancement, l’agent lit des métadonnées cadrées plutôt que de parcourir tout l’arbre d’extensions, ce qui rend install et MAJ plus prévisibles mais crée de nouveaux cas de panne. Les opérateurs voient des volets plugins apparemment vides, des premiers démarrages froids longs après upgrade, et une dérive entre les build npm globaux et l’UI Gateway. Les notes de version exigent aussi un durcissement install/MAJ et une vérification de Gateway en versions mixtes : la CLI, le processus Gateway et le chemin de paquet dans votre plist launchd doivent raconter la même version. Ce guide complète, sur un axe orthogonal, l’article v2026.4.25 jumelage canaux et sécurité Gateway : ici on stabilise le plan « plugins » pendant que le QR et Mission Control restent hors chemin critique. Lisez-le avec exploitation sous releases fréquentes (gel, staging, retour), le Docker Compose officiel, le breaking upgrade v2026.4.5 et le guide dix erreurs fréquentes pour séparer « le canal de messagerie est vert » de « le registre d’extensions est sain ».
Les expressions « registre à froid », « réparation des métadonnées » et « vérification de version mixte » décrivent un comportement mesurable.Premièrement, le démarrage est une lecture à froid.Si l'index sur le disque est à moitié migré, vous n'obtiendrez pas de ligne d'erreur indiquant « registre corrompu » ; vous verrez un écran de plugin vide ou un blocage de plusieurs minutes pendant que Node reconstruit l'index, en particulier sur un Mac distant avec un petit SSD et des E/S co-locataires.Deuxièmement, les chemins d'installation s'appuient désormais sur les métadonnées d'installation localesqui doit survivre aux téléchargements partiels de npm. Une archive tar qui s'arrête en cours de vol peut laisser une ligne de plugin avec une étiquette de version mais aucun binaire exécutable - exactement la classe de bogue quiopenclaw plugins repairet les commandes de réindexation associées sont destinées à résoudre ce problème.Troisièmement, les versions mixtes constituent un problème de topologie d'exécution.La CLI dans votre shell peut se résoudre à/opt/homebrew/...pendant que launchd pointe toujoursProgramArgumentschez un aînédist/index.jssous un préfixe précédent, ou un conteneur Docker monte une racine de configuration différente de celle de l'hôte sur lequel vous venez d'effectuer une réparation. Jusqu'à ce que ces chemins convergent, la console sur le port 18789 lit une version différente de celle que vous pensez avoir installée.
Les cinq éléments ci-dessous sont ceux qui apparaissent dans les tickets lorsque les équipes sautent la collecte de preuves et passent à « tout réinstaller ». Vous pouvez les copier dans une demande de modification en tant que section des coûts cachés.
Pics de démarrage à froid :la première passe d'indexation complète ou de réparation peut épingler le processeur et la boucle d'événements de nœud ; sur une instance distante de 32 Go avec un disque voisin bruyant, la session semble bloquée même si le processus est toujours en train de réécrire les fichiers de partition.
Plugins à moitié installés :un réseau abandonné lors de la récupération d'un bundle peut créer des lignes de manifeste faisant référence aux modules natifs manquants, qui apparaissent dans l'interface utilisateur comme « version connue, activer le commutateur ne fait rien » jusqu'à ce que la réparation réconcilie l'arborescence.
Racines d'installation multiples :Homebrew/opt/homebrew, héritage/usr/local, et un enregistrementnode_modulesL'arbre dans une caisse de développeur peut tous héberger une version OpenClaw. La tâche launchd peut toujours être liée au chemin le plus ancien, ce qui déclenche des avertissements de versions mixtes dans les journaux alors que votre shell interactif est déjà sur 4.25.
Autorisation et sandboxing :un assistant qui ne peut pas créer de fichiers dans le répertoire de cache du registre enregistre souvent un « échec de chargement du plugin » générique au lieu d'un EPERM clair, vous avez donc toujours besoin du même TCC et du même laissez-passer de propriété que vous feriez pour n'importe quel agent de longue durée sur macOS. Associez-le avec leListe de contrôle TCC Mac à distancesi vos symptômes impliquent une automatisation touchant les surfaces de l'interface utilisateur.
La santé du canal n’est pas la santé du plugin.Un chemin QR IM réussi prouve la livraison pour un connecteur ; ça faitpasprouver que le registre et Gateway sont d'accord. Signez ces lignes d'acceptation sur des éléments de travail distincts afin de ne pas fermer un ticket « prêt pour la production » pendant que les extensions échouent silencieusement.
Un registre froid récompensesurfaces d'installation reproductibles. Docker peut épingler le moteur Node et le package openclaw dans une seule couche d'image, mais lier les montages à l'hôte peut réintroduire des racines mixtes si vous réparez sur l'hôte et laissez le conteneur lire un volume obsolète. Métal nunpm install -gest rapide à mettre en œuvre mais exige de la discipline : chaque réparation, exécution médicale et modification de plist doit utiliser lemême utilisateur macOScela finira par afficher l'interface utilisateur 18789, sinon le registre sur le disque et le cache par utilisateur divergent. Utilisez le tableau comme pièce jointe à un enregistrement de modification ; c'est également le moyen le plus rapide de prouver qu'un incident est dû à une inadéquation de volume et non à une panne de modèle.
| Dimension | NPM ou pnpm sur système nu | Docker Composer | Erreur de lecture courante |
|---|---|---|---|
| Alignement des versions | Dépend de launchd, PATH et de vos fichiers d'initialisation du shell | Dépend de la balise d'image et du répertoire de configuration monté | Seulement vérifieropenclaw --versiondans une session SSH, ne correspondant jamais à la passerelle en directargv |
| Scénario de réparation | Fonctionne sur le registre hôte en place | Doit exécuter la commande équivalente à l'intérieur du conteneur sur le même volume | Réparation sur l'hôte alors que le conteneur pointe toujours vers un chemin gelé à l'intérieur de l'image |
| Vitesse de restauration | Restaurez une archive tar connue et verrouillez le semver rapidement | Re-étiquetez l'image etdocker compose up | Mise à niveau de l'hôte et de l'image sans instantané, puis débogage de deux couches défectueuses à la fois |
| Observabilité | Flux de journaux macOS et navigateur local vers 127.0.0.1:18789 | Ajouterdocker logset curl local du conteneur | SSHtailseulement, sans jamais ouvrir DevTools pour comparer les hachages de bundle |
Règle:le processus qui lance Gateway définit la version du produit. La CLI n'est qu'un autre client.
L'ordre est volontairement strict :preuve avant la mutation. Si vous avez un trafic intense, annoncez à l'avance une fenêtre de gel et empruntez le langage dugel et exceptionsection du guide des opérations. Capturez l'espace libre du disque ; le travail de registre à froid est sensible à tout ce qui est gratuit en dessous d'environ dix à quinze pour cent sur APFS. Après avoir modifié les packages, continuez à enfileropenclaw doctord'abord afin que le support obtienne quelque chose de consultable avant de toucher aux sous-commandes de longue durée. Lorsque la note de version mentionne un verbe de réparation, utilisez celui standardisé par votre organisation :reindex, repair, ou les deux, et conservez stderr complet, car un succès partiel laisse toujours derrière lui des métadonnées mixtes.
Redémarrez uniquement la passerelleaprèsvous êtes sûr que la CLI, le plist et le point d'entrée du conteneur sont d'accord. Le redémarrage d'un ancien processus sur un nouveau registre permet aux équipes de créer des erreurs de verrouillage déroutantes qui ressemblent à une corruption. La surface HTTP doit exposer une chaîne de construction cohérente : comparez/versionou la bannière dans les journaux, le volet À propos de l'interface utilisateur et la première ligne deopenclaw --version. Si l’un des trois diffère, vous n’avez pas terminé.
Sauvegarde:exportez la racine de configuration OpenClaw, le répertoire de données du plugin et la liste launchd. Enregistreropenclaw --versionet la passerelle complèteargvdepuispsavant la bosse.
Freeze écrit :pendant la fenêtre, pause automatiqueskill updateles travaux et les installations de plugins ad hoc d'autres responsables afin de ne pas entrelacer deux migrations.
Bump le paquet :déplacez le canal pris en charge vers la v2026.4.25. Pour le npm global, confirmezwhich openclawet le lancementProgramArgumentsfaire référence au même préfixe.
Exécutez le docteur :collez textuellement toutes les lignes de plug-in, de registre ou de passerelle dans le ticket, y compris les avertissements de synchronisation.
Exécutez la réparation ou la réindexation des plugins :regarder l'heure de l'horloge murale et les écritures sur disque ; en cas d'échec, conservez stderr complet, pas une capture d'écran des trois dernières lignes.
Redémarrez la passerelle :uniquement lorsque les versions s'alignent, de sorte que l'ancien processus ne détient pas de verrou obsolète sur la nouvelle mise en page.
Vérification des versions mixtes :comparez l'interface CLI, le point de terminaison de la version HTTP et la zone À propos ou le pied de page de l'interface utilisateur.
Acceptation VNC :dans une session graphique, ouvrezhttp://127.0.0.1:18789(ou votre tunnel documenté), validez la liste d'extensions, les cartes d'autorisation des modèles et le tiroir d'erreurs. Joignez une capture d'écran à la modification.
Tri versions mixtes en trois vérifications : 1) CLI : openclaw --version 2) Processus : ps — chemin dist/index.js dans argv 3) UI : pied de page / À propos, en-têtes de réponse DevTools
Note:pour Docker, documentez où la réparation et le médecin s'exécutent (hôte vsdocker compose exec) dans le runbook et faites-le correspondre à la disposition du volume dans lecomposer un guidedonc une session SSH bien intentionnée ne désynchronise pas un conteneur.
Prudence:ne sautez pas les versions majeures, ne réécrivez pas SecretRef et ne reconfigurez pas le routage des canaux en un week-end sans sauvegardes. Si cela entre en conflit avec l'ordre de sécurité dans lev2026.4.5 changement avec rupturearticle, prenez le chemin le plus strict.
SSH reste le bon outil pourdoctor, repairet des journaux structurés.Contrôler l'interface utilisateur, le consentement de l'extension du navigateur et savoir si une bascule a réellement persistévous avez toujours besoin de la session de bureau du même utilisateur propriétaire du travail launchd. La grille ci-dessous est dimensionnée pour un seul passage d'astreinte sur VNC. Si vous êtes bloqué sur un module natif ou une erreur de chargement cryptique, ouvrez ledix modèles d'erreur courantsguide, mappez votre mot-clé, puis revenez à l'étape cinq de ce runbook pour voir si un deuxième démarrage à froid reproduit l'échec.
| Vérifier | Ce qu'il faut faire | Critères de réussite |
|---|---|---|
| Version triangulaire | Comparez la CLI, traitez argv et À propos ou le pied de page dans l'interface utilisateur sur 18789 | Tous les trois affichent les mêmes majeur et mineur que vous aviez l'intention d'expédier. |
| Liste des plugins | Après un démarrage à froid, ouvrez une fois la page d'extension et attendez que la liste se stabilise | Le nombre correspond à une référence avant la modification ou le delta est documenté dans l'enregistrement de la modification. |
| Modèle d'autorisation | Déclenchez les chemins d'actualisation OAuth sur lesquels vous comptez ; surveillez les bannières de limite de débit | Pas de boucles 401 ou 429 illimitées dans la zone temporelle |
| Disque et E/S | Utilisez Activity Monitor pour surveiller la lecture/écriture pendant la réindexation s'il est toujours en cours d'exécution | La pointe se désintègre, l'espace libre reste au-dessus de la marge de sécurité |
| Fumée de régression | Envoyez une petite sonde sur votre canal le moins risqué | L'état du canal est un élément de campagne distinct de l'état du plugin, comme dans la section 01. |
Intégration de messagerie instantanée, modèles de sécurité 18789 et redirection de port SSH à côté du même plan de contrôle.
Lire →Gelez les lignes, quand les rompre, et annulez les arbres lorsque les versions sont expédiées rapidement.
Lire →Contrats de volume, port 18789 et vérification de l'interface utilisateur dans un conteneur sur un hôte VNC.
Lire →Exécutez Doctor, puis réparez ou réindexez et prouvez que vous n'êtes pas dans un état de version mixte. Une réinstallation aveugle de Gateway ne fait que retarder le prochain démarrage à froid et vous perdez le diff qui aurait montré un plist ou un volume obsolète.
launchd pointe toujours vers un anciendisttandis que votre shell interactif utilise une installation globale plus récente, ou un chemin d'hôte Docker et un chemin de conteneur voient différentes arborescences sous les montages de liaison.
CLI et journaux, oui. La surface de contrôle et quelques autorisations macOS nécessitent toujours la session graphique. Utilisez la table de la section 05 avec VNC dans le même compte utilisateur que le processus Gateway.
Le registre froid échange « analyser l'intégralité de l'arborescence à chaque démarrage » contre « posséder vos métadonnées d'installation et votre ligne de version ». Le suivi opérationnel estpics d'E/S prévisiblespendant la réindexation,couplage plus étroit entre les préfixes launchd et npm, etacceptation qui doit avoir lieu dans une session de navigateur, vous pouvez voir. Si vous ne lisez que les journaux SSH, vous fusionnerez « le canal va bien » et « les extensions vont bien » sur un seul ticket, puis perdrez des jours à chasser un fantôme alors que seulement la moitié de la pile a été validée.
Un Mac sous votre bureau a toujours besoin de quelqu'un pour gérer la veille, l'alimentation et les thermiques Apple Silicon. UNMac cloud loué avec SSH et VNC programméest souvent le moyen le plus simple d'obtenir une deuxième paire d'yeux sur 18789 sans envoyer quelqu'un dans un placard. L’aspect économique concerne la question de savoir qui effectue les remplacements de disques de fin de soirée et les collaborateurs, et non la question de savoir si OpenClaw est « facile ».
Pour louer un nœud Apple Silicon à l'échelle du projet qui correspond à ces listes de contrôle, utilisezVNCMac: leachat cloud Macpage pour les plans, et lapage d'accueilpour le contexte du produit. Gardez leappariementetDockerarticles dans le même dossier d'exécution afin que toute l'équipe partage une carte des pixels à la liste des processus.