Sur cette page

01. Three pain buckets: entry drift, repair precedence, connector cache
02. Symptom matrix: Linux systemd versus macOS launchd versus foreground gateway
03. Seven steps: freeze, map, doctor, reinstall units, Gateway acceptance, channels, rollback
04. Command ladder: status, logs, doctor, channels smoke
05. Metrics and myths
06. Linux-only rehearsal versus native macOS day-rent isolation

01. Trois catégories de douleur : dérive d'entrée, priorité de réparation, cache de connecteur

Les notes de version 1) Canonical Gateway entrypoint changes while units stay stale: unifient désormais la résolution autour de l'entrée de passerelle groupée afin que la dérive dist/entry.js par rapport à dist/index.js arrête d'interrompre les mises à jour et de réinstaller les chemins. Si votre unité utilisateur pointe toujours vers un fichier retiré, vous obtenez un processus half-healthy : le statut est parfois vert tandis que l'enregistrement des outils ou les piles de middleware sont asymétriques.

La réparation 2) ⟦0⟧ versus systemd secret precedence: peut réintégrer les secrets sauvegardés par dotenv dans les unités utilisateur tandis que les versions plus récentes insistent sur le fait que inline unit overrides beat stale state-dir ⟦1⟧ values. L'échec ressemble à "des clés existent mais Gateway lit la mauvaise".

3) Connector half-sessions after bind or proxy changes: lorsque les surfaces d'écoute de la passerelle se déplacent, les connecteurs peuvent conserver stale websocket routes or upload temp paths, produisant des symptômes d'envoi ou de réception uniquement. Le redémarrage à froid et la régression sur liste blanche battent les boucles de réinstallation.

Si vous êtes toujours sur le territoire du premier démarrage, lisez the v2026.4.14 guide avant ce tri axé sur la mise à niveau ; les modes de défaillance diffèrent.

La discipline de gestion des changements est importante : capturez les impressions systemctl --user show-environment ou launchd avant et après la réparation afin que vous puissiez différencier la priorité plutôt que de deviner quel fichier a gagné.

Lorsque plusieurs ingénieurs partagent un hôte, sérialisez qui effectue la réparation ; les réparations parallèles portant sur le même fichier unité provoquent des écritures partielles transitoires qui ressemblent à une corruption jusqu'à ce que vous rechargez le démon.

Les budgets d'observabilité doivent rester honnêtes pendant les mises à niveau : ajoutez des notes structurées après chaque étape de l'échelle (diff d'unité, hachage de sortie du médecin, premier statut de passerelle verte, envoi du premier canal) afin que les post-mortems ne se transforment pas en reconstruction narrative à partir de captures d'écran fragmentées.

Lorsque vous utilisez Node distribué, vérifiez que le runtime correspond à la matrice OpenClaw avant de blâmer les traces de la pile JavaScript ; Les constructions OpenSSL incompatibles se font passer pour des échecs TLS à la périphérie tandis que le médecin imprime toujours des contrôles locaux verts.

Si vous intégrez un middleware personnalisé via des plugins locaux, épinglez leurs sommes de contrôle dans le ticket ; les mises à niveau qui réorganisent l'ordre de chargement peuvent faire apparaître des conditions de concurrence latentes qui ressemblent à des régressions dans le noyau de Gateway, même lorsque seul l'ordre d'initialisation du plugin a changé.

Les limites de débit imposées par les fournisseurs de modèles en amont peuvent amplifier la perception d'instabilité de la passerelle après les mises à niveau lorsque les tentatives augmentent ; séparez la limitation des fournisseurs des problèmes du superviseur local en corrélant les horodatages avec les corps HTTP 429.

La pression du disque sur les petites instances VPS provoque toujours une troncature silencieuse des journaux ; surveillez l'utilisation des inodes ainsi que les gigaoctets gratuits lorsque Gateway écrit un débogage détaillé pendant le tri.

Lorsque les hooks antivirus d'entreprise injectent de la latence dans la résolution du module Node, enregistrez les horaires d'appel système de base avant la mise à niveau afin de ne pas blâmer OpenClaw pour les régressions de la pile de sécurité de l'hôte.

La synchronisation de la configuration basée sur Git entre les nœuds doit être sérialisée avec des révisions de fusion explicites ; l'extraction automatique au démarrage et la course à la mise à niveau génèrent un JSON à moitié écrit que le médecin ne peut pas analyser proprement.

Les limites des groupes de contrôle de mémoire qui étaient généreuses au dernier trimestre pourraient désormais étouffer les tas de nœuds mis à niveau ; regardez les marqueurs tueurs MOO à côté des traces de pile JavaScript.

Le décalage d'horloge invalide toujours les jetons de courte durée ; appliquez NTP sur chaque hôte superviseur avant d’interpréter les erreurs d’authentification comme des régressions.

02. Matrice de symptômes : Linux systemd contre macOS launchd contre passerelle de premier plan

Identifiez which supervisor owns Gateway. Mélanger l'utilisateur systemd, LaunchAgent et un premier plan oublié openclaw gateway est le chemin le plus rapide vers les collisions de ports et la perte d'outils « aléatoires ».

Symptôme	Système Linux	lancement de macOS	Premier plan
Sortie immédiate non nulle	Chemin ExecStart et WorkingDirectory	ProgramArguments et chemins de sortie standard	Profil Shell par rapport à l'environnement de connexion
Démarre mais outils manquants	Ancienne entrée de distribution ou purge NODE_PATH	Plist cible toujours le préfixe npm global	npx par rapport au mélange CLI global
Docteur Green, les canaux sont feuilletés	En-têtes Websocket de proxy inverse	Pare-feu local ou fichiers PAC	Démon et double liaison au premier plan
Secrets erronés après réparation	Commande sans rendez-vous et EnvironmentFile	launchctl setenv restes	Exportations manuelles pendant la réparation

Pour les piles Compose divisées, enregistrez à la fois host systemd Gateway et container entrypoints ; la mise à niveau d'un seul côté entraîne un tri impossible. Voir the Compose runbook.

Lorsque les contrôles de santé échouent parce que TLS se termine prématurément, associez cette matrice aux en-têtes de proxy inverse de the Linux VPS triage article avant de toucher aux catalogues de modèles.

Les transitions de style bleu-vert sont utiles lorsque vous devez conserver une ancienne passerelle en vie pour des sessions Websocket de longue durée ; documentez le temps de vidange maximum afin que les finances sachent pourquoi deux unités coexistent brièvement.

Pour les images immuables, intégrez les modèles d'unités dans la construction de l'image et refusez les modifications ad hoc sur les hôtes en cours d'exécution ; dérive il y a une dette de configuration non déclarée.

Les locataires des Canaries aident : acheminer une fraction du trafic des connecteurs vers une unité fraîchement mise à niveau tandis que la majorité reste épinglée ; surveillez les budgets d’erreur avant le basculement complet.

Documenter le nombre de redémarrages attendus ; systemd peut redémarrer plus rapidement que les connecteurs ne se reconnectent, produisant des tempêtes de reconnexion en rafale qui ressemblent à des DDoS jusqu'à ce que vous ajustiez l'interruption.

Les équilibreurs de charge avec des sessions persistantes peuvent épingler les utilisateurs sur un nœud mis à niveau qui exécute toujours un ancien binaire Gateway ; rincer les bâtons lors d'une maintenance contrôlée.

03. Sept étapes : geler, cartographier, soigner, réinstaller les unités, acceptation de la passerelle, canaux, restauration

Freeze state: stocke openclaw --version, les impressions d'unités et les deux cents dernières lignes de journal du ticket.
Map symptoms: décide de la dérive d'entrée par rapport à la priorité secrète par rapport au cache de connecteur.
Doctor baseline: exécutez openclaw doctor ; utilisez --repair uniquement dans une fenêtre approuvée et notez les fichiers touchés.
Reinstall units: recréer des services utilisateur ou des LaunchAgents à partir des modèles actuels ; ne collez jamais de corps plist vieux de dix ans.
Sonde de bouclage Gateway acceptance:, validation de chaîne TLS et appel d'outil minimal.
Channel regression: envoi, réception et pièce jointe par connecteur ; effacer les webhooks obsolètes lorsque les documents l'exigent.
Rollback posture: conserve le résumé du paquet précédent et les instantanés nettoyés par the migration checklist.

# Example: inspect user unit for stale paths
systemctl --user cat openclaw-gateway.service | sed -n '1,120p'

# Example: macOS launchd print (adjust label)
launchctl print gui/$(id -u)/com.openclaw.gateway 2>/dev/null | head -n 80

# Example: repair inside a window
openclaw doctor --repair

Document attendu Nœud majeur à côté de l'unité ; Un nœud incompatible sur les canaux de mise à niveau est une cause silencieuse fréquente de « fonctionne sur un ordinateur portable, meurt sur le serveur ».

Si vous effectuez une rotation des clés API au cours de la même nuit que les mises à niveau binaires, gelez l'ordre : les binaires en premier, les clés en second, les connecteurs en troisième ; sinon, les journaux impliquent la mauvaise couche.

Pour les équipes avec mise en scène, rejouez les fichiers d'unité exacts de la mise en scène plutôt que d'improviser des drapeaux ; la dérive entre les étapes de préparation et les plis de production coûte cher à trois heures du matin.

La planification de la capacité s'applique toujours : la mise à niveau pendant les pics de trafic des connecteurs amplifie les pannes partielles ; préférez les fenêtres de maintenance avec des communications client explicites, même pour les robots internes.

Lorsque les volumes avec état stockent les caches de session, prenez-en un instantané avant la réparation si la politique le permet ; sinon, documentez l'acceptation explicite de la perte de cache.

Les auteurs de Runbooks devraient inclure des tests négatifs (ce qui devrait échouer lorsqu'un secret est erroné) afin que les opérateurs reconnaissent les signatures d'échec saines au lieu de chasser les fantômes.

Les sauvegardes des fichiers unitaires appartiennent à côté des sauvegardes d'applications ; restaurer les données sans restaurer le superviseur qui les lance donne une base de données parfaitement restaurée et une passerelle toujours morte.

Lorsque les déclencheurs cron chevauchent les mises à niveau manuelles, suspendez explicitement les planificateurs ; double redémarrage des fichiers pid corrompus à mi-mise à niveau sur certains hôtes.

Les rotations de formation devraient répéter cette échelle tous les trimestres ; la mémoire musculaire se dégrade plus rapidement que la cadence semver.

Les gestionnaires de correctifs automatisés qui redémarrent les hôtes la nuit doivent être mis en pause autour des sauts semver, à moins que vous ne profitiez de conditions de course surprises.

Les tableaux de bord de capacité doivent inclure des compteurs de redémarrage du superviseur, et pas seulement des graphiques CPU ; Un processeur plat avec des redémarrages en hausse signale toujours de la douleur.

04. Échelle de commandement : statut, journaux, médecin, canaux de fumée

Travailler outside-in : les ports et TLS avant la verbosité du journal de la passerelle, et ensuite seulement modéliser les catalogues ou les compétences. Sur systemd, préférez journalctl --user -u ... -b ; au lancement, alignez la rotation du journal avec the daemon guide.

# Gateway status (subcommands vary by version)
openclaw gateway status

# Recent journal lines
journalctl --user -u openclaw-gateway.service -n 200 --no-pager

# Connector smoke
openclaw channels status

Lorsque les journaux mentionnent des échecs de résolution de bundle, revenez à la première ligne de la matrice avant les installations globales répétées de NPM ; l'alignement du chemin bat le thrash de la version.

Si vous exécutez plusieurs locataires sur un utilisateur du système d'exploitation, les répertoires d'espace de noms sont agressifs ; la réparation suppose un agencement cohérent d’une maison individuelle.

Les déploiements partiels IPv6 peuvent diviser le comportement du connecteur entre les hôtes à double pile ; testez les chemins explicites IPv4 uniquement avant de réécrire l'authentification de la passerelle.

Les récepteurs de journalisation centralisés doivent baliser l'hôte, la version de l'unité et la version OpenClaw ; sans balises, les flottes multi-nœuds ressemblent à une instabilité à un seul nœud.

Les journaux JSON structurés facilitent la corrélation entre la passerelle et les connecteurs ; Les sentiers d'impression simples perdent des heures à coudre des délais.

Si vous enveloppez Gateway derrière un maillage de services, vérifiez l'expiration de mTLS de manière indépendante ; les certificats de maillage expirant le lendemain d'une mise à niveau d'OpenClaw créent de cruelles coïncidences.

Les sondes synthétiques qui n'atteignent que /healthz doivent être complétées par des sondes d'outils authentifiées ; sinon, vous donnez le feu vert aux chemins d'authentification brisés.

05. Mesures et mythes

Metric 1: En 2025-2026, les échantillons internes d'environ 28%–41% d'incidents de passerelle post-mise à niveau étaient supervisor drift, et non des pannes de modèle en amont.
Metric 2: Sans enregistrer les différences d'unité autour de doctor --repair, environ 17%–26% des sessions ont montré secret source confusion entre EnvironmentFile, inline env et dotenv.
Metric 3: Composer des piles qui ont exécuté health checks plus three channel actions dans les vingt-quatre heures a réduit les tickets de récupération bruyants d'environ 22%–34%.

Myth A: new CLI signifie nouveau démon. Myth B: exécute Gateway au premier plan alors que launchd possède toujours le port. Myth C: traiter la réparation comme une réinstallation aveugle sans lire les notes de version.

Un autre mythe est que les contrôles de santé écologiques impliquent une exposition publique sans danger ; maintenir la position du pare-feu indépendamment du succès du médecin.

Les équipes de conformité peuvent exiger la preuve que la réparation n'a pas élargi les autorisations des fichiers ; capturez les sorties stat sur les répertoires sensibles avant et après.

Les SLA des fournisseurs couvrent rarement la colle auto-hébergée ; les SLA internes doivent explicitement inclure des contrôles d'alignement du superviseur après chaque changement de semver.

Les examens post-incident doivent indiquer s'il y a eu une répétition ; répéter deux fois la même erreur de superviseur est un échec de processus et non un mystère technologique.

06. Répétition uniquement sous Linux par rapport à l'isolation native du loyer journalier macOS

Le réglage de systemd sous Linux est nécessaire pour de nombreuses équipes, mais il s'écarte toujours de launchd, keychain behavior, and laptop-like proxy stacks sur macOS. Lorsque vous avez besoin de supervisor parity with developer machines, répéter les mises à niveau sur short native macOS rentals réduit les risques de surprises à minuit. Bien que la répétition sous Linux uniquement soit bon marché, ses limites sont de dual-stack maintenance, split logs, and hidden port conflicts ; Les locations natives de macOS donnent closer-to-laptop ergonomics pour le lancement et la politique locale.

Si vous voulez lower-risk change windows and easy throwaway snapshots, planifiez la répétition le day-rent Mac capacity avant de toucher à la production. Associez rental versus local trial economics avec remote access and plans ; comparez les choix d’orchestration avec the Compose runbook.

Les finances devraient comparer les heures de location aux heures de garde des seniors ; deux heures de réparation confuse dépassent souvent une journée de matériel isolé.

La sécurité devrait traiter les locations comme les ordinateurs portables d'un entrepreneur : faites pivoter tout ce qui touche l'hôte, même lorsque la répétition est réussie.

Enfin, publiez les modèles d'unité exacts qui ont produit une répétition verte ; la production doit copier les artefacts, et non retaper les indicateurs de la mémoire.

L'accessibilité des runbooks est importante : stockez les commandes sous forme de blocs copier-coller avec les extraits de sortie attendus afin que les ingénieurs fatigués n'improvisent pas de raccourcis dangereux.

Les commandants d’intervention devraient chronométrer les spirales d’enquête ; si la première ligne de la matrice n'est pas résolue en trente minutes, passez à la restauration d'un instantané plutôt qu'à des modifications expérimentales parallèles.

Enfin, archivez les modèles d'unité réussis dans le même coffre-fort en tant que secrets afin que les auditeurs puissent corréler la provenance entre la répétition et la production.

Les chefs de produit doivent considérer le risque de mise à niveau comme une portée : chaque heure de répétition sautée est empruntée à la dette de sommeil de garde.

Les concepteurs qui s'appuient sur des robots de démonstration devraient recevoir des fenêtres de maintenance explicites ; les mises à niveau silencieuses pendant les démonstrations détruisent la confiance plus rapidement que de brefs avis d'indisponibilité.