2026 OpenClaw sur Linux systemd après mise à jour : dérive HOME, configuration vide, doctor

Après une mise à niveau majeure ou un déplacement du paquet CLI, vos services systemd --user peuvent rester verts tout en lisant une openclaw.json squelettique depuis un couple HOME et variables XDG distincts de votre session SSH interactive. Traitez d’abord l’incident comme une dérive d’environnement puis comme un problème de fusion JSON documentée avant d’incriminer réseaux ou fournisseurs modèles. Ce guide concerne Linux bare-metal ou machines virtuelles avec unités utilisateur persistantes, pas uniquement une stack conteneurisée où ~/.config/systemd/user est irrélevant.

1. Triple symptômes : processus vivant, passerelle RPC incohérente, interface presque vide

Couche processus : systemctl --user affiche encore actif, pourtant le démon résout une version minimale de openclaw.json puisque la unit n’expose pas les mêmes variables que votre shell personnel. Redémarrer ne corrige pas l’empreinte fichier si HOME diffère au boot.

Couche RPC : openclaw gateway status peut afficher révision ou arborescence hors alignement avec le binaire invoqué en interactif ; consultez le guide split brain avant suppression agressive.

Couche interface : le tableau de charge statique se peint tandis que les WebSockets échouent ou restent dépourvus d’identité parce que stock secret et mappage canaux pointent ailleurs. La « échelle » officielle exige preuves processus et RPC avant simple rafraîchissement navigateur.

1. Capturez au moins deux cents lignes de journal juste après redémarrage contrôlé et filtrez ENOENT, jetons HOME et chemins configuration explicites.
2. Comparez trois environnements : shell login, shell non-login via su ou compte technique, et sortie systemctl --user show … liée au fragment openclaw.
3. Archivez systématiquement arbres ~/.openclaw et ~/.config/openclaw avant merge structurel ou gateway install --force.

Une socket TCP listée par ss -lntp prouve seulement qu’un binaire écoute, non qu’il charge le même fichier que celui que vous éditez dans votre répertoire personnel. Quand l’installation globale s’est faite via privilèges élevés mais que la maintenance se fait via compte déploiement, deux HOME coexistent et le service peut servir du trafic depuis un squelette pendant que vos canaux restent invisibles.

Les variables XDG dictent si la recherche privilégie ~/.config/openclaw, ~/.local/state ou repli historique ~/.openclaw ; un mineur amont peut réordonner l’ordre de découverte. Si XDG_CONFIG_HOME manque uniquement côté service, vous obtenez divergence silencieuse. Notez chemins absolus dans le ticket, jamais de tildes ambiguës.

Plugins visibles disparus mais fichiers présents suggèrent seconde instance cron, root ou script hérité. Croisez systemctl --user list-units 'openclaw*' et pgrep -af openclaw pour éviter de déboguer le mauvais PID.

Supprimer brutalement un squelette risque d’effacer métadonnées migrées automatiquement, dont meta.lastTouchedVersion, cruciales pour le guide split brain.

2. Inspecter systemd avant d’accuser le fournisseur modèle

Enchaîner statut, commandes gateway, journaux filtrés puis openclaw doctor réduit les hypothèses croisées. Changer de modèle pendant une dérive HOME crée bruit diagnostic inutile.

Les unités systemd --user n’héritent ni ~/.bashrc ni profils Zsh. Exports PAM session graphique, liste AcceptEnv SSH et fragments systemd se combinent ; un HOME absent pousse runtimes vers répertoires packagés, générant JSON apparemment vierge pendant que votre fichier « vrai » demeure sous le compte SSH.

Référence autoritaire : systemctl --user show UNIT -p Environment -p WorkingDirectory -p FragmentPath -p User. Confrontez à printenv HOME XDG_CONFIG_HOME XDG_STATE_HOME depuis login, non-login et runners CI ayant préparé l’hôte. Une seule divergence suffit pour justifier drop-in ciblé plutôt que copie massive d’arborescence.

WorkingDirectory influence chemins relatifs dans ExecStart. Unit obsolète pointant vers ancien checkout ou layout npm global déplacé charge extensions par défaut donnant interface vide. Journalisez chemin absolu retourné par statut gateway après chaque reboot.

Sans loginctl enable-linger sur hôte headless, le gestionnaire utilisateur meurt quand la dernière session se ferme, produisant symptômes intermittents. Correlez journalctl --user -u UNIT -b avec horodatage paquets.

Si SemVer CLI et démon divergent, priorisez runbook split-brain : corriger HOME seul laisse canaux semi-enregistrés.

Déplacez secrets en dernier : un merge partiel touchant OAuth ou jetons peut verrouiller fournisseurs messagerie tandis que l’UI demi-rendue persiste. Conservez deux archives horodatées UTC et nom court machine avant et après doctor réussi.

Pour flottes, figez image de base avant mineur modifiant résolution chemins ; versionnez SHA256 drop-in et version paquet dans même fiche changement. gateway install --force appartient à fenêtre annoncée avec rollback unitaire versionné, pas à improvisation nocturne.

Stacks Compose ou Kubernetes injectent variables via manifestes, pas via drop-ins home. Mélange bare-metal et compose sur un nœud impose étiquetage ticket pour ne pas appliquer recettes Linux à conteneur HOME=/root.

Exploitants macOS consultent parallèlement article launchd : symptômes semblables, outils launchctl vs loginctl. Gardez séparation nette dans runbooks.

Budgetez quinze minutes post-merge pour sondes canaux et message synthétique par fournisseur. Sans cela, régressions silencieuses survivent à doctor sortant zéro. En cas d’échec, collectez codes HTTP et fermetures WebSocket avant ticket support tiers.

Industrialisez : fragment unitaire dans gestionnaire config avec hash reflété billet évite edits locaux furtifs.

Approchez JSON comme données semi-structurées : validez chaque bloc comme en CI OAuth ; vérifiez permissions UNIX réelles puisque démon court souvent non-root.

Multiplication EnvironmentFile=- ou proxys imbriqués crée cascades précédences : documentez chaîne effective entière dans incident.

3. Matrice : simple redémarrage, fusion, installation forcée

Appliquez la matrice dans une fenêtre de maintenance annoncée : figez l’empreinte image système ainsi que fichier de verrouillage paquets lorsque plusieurs hôtes subissent le même playbook. Réévaluez la ligne sélectionnée si le journal devient bruyant immédiatement après systemctl --user daemon-reload, car un fragment syntaxiquement valide peut encore publier une variable erronée. Les canaris doivent ouvrir la vague avant tout déploiement massif ; dès que le squelette resurgit, annexez au incident la triple comparaison d’environnement plutôt que propager aveuglément une unit template.

Les étiquettes de risque restent relatives : même action « faible » casse automatisation sans reload correct. Associez toujours trois gestes synchrones : recharge démon utilisateur, redémarrage du service sous observation, tarball de retour disponible avant toute tentative destructive. Une installation forcée « élevée » nécessite relecture croisée des fragments systemd générés.

Inclure un commentaire changelog interne reliant version mineure OpenClaw et comportement systemd aide les équipes transversales à éviter duplication d’hypothèses réseau.

Quand journalctl révèle accès fichier à très haute fréquence juste après boot, envisagez chemin relatifs dans plugin manifest mal résolus plutôt qu’instantanément suspecter attaque distribuée : la mesure précède narration sécuritaire.

Documentez quotas disque utilisateur avant merge : passer à squelette peut provenir défaillance écriture silencieuse si partition pleine alors que syslog mentionne vaguement erreurs génériques entrée-sortie.

Les équipes hybrides doivent préciser également si pare-feu local redirige encore vers ancienne incarnation passerelle encore attachée ancien utilisateur systemd ; redirection persistante trompe santé tant que backlog applicatif différent absorbe encore trafic.

4. Séquence merge en sept étapes opérables sous stress

systemctl --user show openclaw-gateway.service -p Environment -p WorkingDirectory -p FragmentPath
echo "$HOME" "$XDG_CONFIG_HOME" "$XDG_STATE_HOME"
tar czf ~/openclaw-premerge-$(date +%Y%m%d%H%M).tgz ~/.openclaw ~/.config/openclaw 2>/dev/null

1. Gelez collaborations concurrentes : suspendez pipelines CI susceptibles de réinstaller CLI ou éditer le même fichier JSON durant fenêtre courte.
2. Exportez trois dumps texte environnement (root pertinent, login, unité systemd) avec horodateur pour éviter erreurs transcription quand pager sonne déjà.
3. Privilégiez chemins rapportés par openclaw gateway status tant que service tourne encore, même contradiction apparente avec intuition.
4. Transportez bloc par bloc dans l’ordre canaux, extensions, puis identifiants ; validez parse JSON après chaque segment.
5. Exécutez openclaw doctor, conservez flux standard et erreurs, puis recapturez immédiatement openclaw gateway status comme preuve différentielle.
6. Vérifiez loginctl show-user "$USER" -p Linger sur machines sans session graphique persistante afin que user manager survive coupures SSH.
7. Consignez numéros version CLI et démon, empreinte fragment, chemin rollback et minute UTC redémarrage dans outil ticketing pour passeration claire vers astreinte suivante.

Après exécution de la liste, ouvrez un court post-mortem interne même si résolution succès : liste les signaux précoces HOME versus ceux véritablement résiduels semver.

Prévoyez espace disque temporaire dédié staging JSON : copier blocs dans fichier intermédiaire validé avant substitution finale réduit fenêtre corruption si éditeur plante milieu opération.

5. Liste imprimable : points de contrôle et commandes

Réservez cet encadré comme fiche laminée opérationnaire ; serrez tolérance quand données réglementaires transitent dans passerelle OpenClaw.

Conservez extraits journal sept jours calendaires suivant résolution même si santé retrouvé : ils servent graphe spectral futur upgrade. Associez sommes contrôle fichiers artefacts à identifiants changement infra pour corrélation inter-outils.

Pour environnements critique, précisez dans politique évolution fenêtres où patch sécurité noyau interdit hors coordination afin éviter collisions redémarrage non liées merge.

Alignez fuseaux avant incident : désynchronisations NTP créent narration erronée ordre package upgrade contre restart systemd.

6. Délimitations avec split-brain, conteneurs, macOS

Runbook split-brain détaille alignement semver, champ meta.lastTouchedVersion étendu lorsque désaccord perdure après fixation HOME ; consultez-le dès lorsque doctor signale divergence versions malgré chemins désormais uniques.

Article compose token explique rattachements OPENCLAW_GATEWAY_TOKEN et websocket interne dockerisé ; ne copiez pas littéralement lignes systemd dans YAML compose—traduisez intention via variables natives orchestrateur et secret manager.

Note macOS couvre plist launchd recharge et chemins préfix Node ; problèmes ressemblent visuellement à Linux mais outillage diffère fondamentalement.

Gardez chaque famille incident dans rubrique séparée : systemd Linux explicite lignes utilisateur linger ; macOS plist ; orchestrateur conteneur manifeste environnement isolé du home interactif.

Notez encore que politiques SELinux ou AppArmor peuvent rejeter lectures fichiers même si permissions UNIX classic semblent correctes ; un refus AVC silencieux se traduit par JSON apparemment incomplet jusqu’à analyse logs sécurité spécialisés.

7. Foire aux questions rapides

Q Puis-je supprimer dossier squelette puis recopier ? R Arrêtez service, archives complètes, évitez écritures concurrent gateway actif ; fusion dirigée meilleure suppression aveugle.

Q Deux passerelles distinctes root utilisateur régulier ? R Conflits ports garantis ; désignez personnalité officielle avec User= explicite et désactivation unit parasite.

Q Publication hebdomadaire mineure production ? R Acceptable uniquement via automation snapshots et canaris ; sinon dérive surcharge humaine.

8. Synthèse & passerelle SFTPMAC

Passer du voyant systemd vert à configuration véridique impose synchronisation littérale HOME/XDG avec vérité systemctl --user show puis preuves RPC ordonnées plutôt que boucles redémarrage isolées.

Linux maison conserve dette cumulative drop-in versionné et hygiène merge ; cadence upstream rapide sanctionne laxité traces. Établissez une revue trimestrielle en lecture seule comparant l’empreinte runtime des fragments à celle du dépôt d’infrastructure afin qu’une divergence accidentelle soit détectée avant tout symptôme opérationnel.

Si passerelles long cours sur Apple silicon ou trajectoire chemins mieux cloisonnés réduiraient combustion merge hebdomadaire, confrontez vos coûts d’astreinte interne aux plans SFTPMAC Mac distant hébergé, réunissant artefacts fichiers SFTP/rsync avec identité service stable prévisible documentation.