2026 — Migration OpenClaw et runbook de démarrage à froid : de la copie de dossiers au premier lien Gateway (systemd vs launchd)

1. Points douloureux : des arbres copiés ne s’exécutent pas tout seuls

Les équipes qui migrent depuis des portables ou d’anciens VPS supposent souvent que si la liste des fichiers correspond, le comportement suivra. OpenClaw dépend en réalité de quatre couches couplées : quel binaire openclaw l’emporte sur le PATH, l’arborescence de configuration sur disque sous ~/.openclaw, les ressources relatives au workspace, et le contexte du superviseur fourni par systemd ou launchd. Si l’une de ces couches manque ou diverge, vous obtenez des symptômes intermittents : un Gateway qui tourne correctement dans une session SSH mais disparaît après déconnexion ou redémarrage, des journaux vides alors que le processus est chargé, ou des erreurs « commande introuvable » qui n’apparaissent que pour l’utilisateur du service.

La migration n’est donc pas un simple transfert de bits : c’est un exercice d’alignement contractuel entre ce que l’opérateur croit avoir copié et ce que le superviseur injecte réellement comme variables d’environnement, répertoire de travail et identité utilisateur. Sur Mac cloud, les images « propres » omettent souvent les préfixes de gestionnaires de versions que les postes de développeurs accumulent au fil des années ; sur Linux, les unités utilisateur peuvent imposer un HOME différent de celui attendu par des scripts écrits pour un shell interactif. Ces écarts se manifestent tard, au moment où personne n’est connecté en SSH pour corriger à la volée.

1. Dérive de la CLI entre machines : l’ancien hôte peut avoir utilisé npm global alors que la nouvelle image Mac cloud ne fournit que des chemins Homebrew ou une disposition issue d’un script d’installation statique. Copier du JSON n’installe pas les binaires. Les workspaces pnpm mélangés à des paquets globaux peuvent même afficher des numéros de version identiques tout en chargeant des bibliothèques dynamiques différentes.
2. Contexte de démon rompu : sous Linux, les unités systemd --user déclarent souvent Environment=HOME=... explicitement. Sous macOS, les LaunchAgents n’héritent pas des fichiers rc du shell de connexion : les préfixes façon nvm disparaissent sauf si vous encodez des chemins absolus ou un script enveloppeur mince. Un mauvais WorkingDirectory oriente silencieusement journaux et recherches de secrets vers un mauvais emplacement.
3. Mauvais ordre de triage : passer au couplage des canaux avant de valider la syntaxe de openclaw.json et l’écoute sur le port 18789 fait perdre des heures. Les sondes locales doivent être vertes avant de toucher aux surfaces de messagerie en amont.
4. Propriété après rsync : des arbres copiés en root puis remis à un utilisateur applicatif peuvent rester lisibles mais non inscriptibles pour les journaux d’erreur standard, ce qui produit des échecs silencieux ressemblant à des blocages mystérieux.

Documenter ces quatre familles de risques dans le ticket de changement évite les débats en salle de guerre quand la fenêtre de maintenance se rétrécit. L’objectif n’est pas d’accumuler des procédures pour elles-mêmes, mais de donner au responsable d’astreinte une séquence vérifiable, reproductible, et indépendante du poste de travail personnel de l’ingénieur qui a préparé la migration.

2. Matrice d’environnement systemd contre launchd

Utilisez le tableau comme annexe à votre demande de changement. La colonne « premier arrêt » indique ce que les opérateurs doivent vérifier sur l’hôte avant d’accuser les fournisseurs de chat, les pare-feu ou les proxys d’entreprise. Elle sert aussi de grille de lecture pour les revues post-mortem : la plupart des incidents « Gateway fantôme » se résolvent en réconciliant ce que pense systemd ou launchd avec ce que suppose votre documentation interne.

Si la destination est une instance Mac cloud longue durée, verrouillez d’abord les chemins absolus et les fichiers journaux dans launchd, puis décidez si le partitionnement Docker vaut la complexité supplémentaire de volumes et d’UID. Sur Linux, si vous exécutez déjà d’autres démons utilisateur sous systemd --user, alignez OpenClaw sur les mêmes limites de slice afin qu’un voisin gourmand en xcodebuild ne prive pas le Gateway de capacité de réponse. L’alignement des limites de ressources n’est pas une optimisation de luxe : c’est une barrière contre les migrations qui « marchent en labo » mais s’effondrent sous charge réelle.

Les opérateurs doivent aussi distinguer ce qui relève du domaine de bootstrap macOS (utilisateur graphique, arrière-plan, démon système) de ce qui relève d’une session SSH interactive : un test réussi dans SSH ne prouve pas que launchd injectera les mêmes variables au prochain reboot. Pour cette raison, les redémarrages à froid planifiés restent le juge de paix ultime des runbooks sérieux.

3. Sept étapes de démarrage à froid jusqu’au premier lien réussi

Ces étapes mettent volontairement en avant des signaux lisibles par un humain et repoussent tout ce qui exige un compte externe. Pour les bascules de nuit, indiquez le nombre de minutes attendu par étape dans la fenêtre de maintenance : le chef d’incident peut ainsi choisir poursuivre ou revenir en arrière sans redébattre du périmètre à chaud. Une granularité temporelle honnête protège aussi les équipes produit : elles savent quand la messagerie redeviendra fiable.

1. Geler la version et le support : consigner openclaw --version, npm contre pnpm contre script d’installation contre digest d’image sur l’ancien hôte. Choisissez un seul point d’entrée sur le nouvel hôte en vous appuyant sur l’article des chemins d’installation avant de copier les arbres, afin de ne jamais exécuter deux binaires par accident.
2. Synchroniser les répertoires : utiliser rsync -aH ou équivalent pour ~/.openclaw et le workspace, en respectant les exclusions d’équipe pour les caches volumineux. Comparez immédiatement dates de modification et tailles des fichiers critiques pour détecter tôt un transfert partiel.
3. Permissions et accessibilité des secrets : exécuter ls -la ~/.openclaw. Pour les flux Docker, revalider les montages bind et le mappage d’UID en suivant la section Docker du guide d’installation.
4. Rédiger l’unité de service : Linux reçoit une unité systemd --user avec lignes d’environnement explicites ; macOS reçoit un LaunchAgent dont les ProgramArguments pointent en chemins absolus vers openclaw. Encodez l’adresse d’écoute et le port lorsque les défauts changent entre versions.
5. Charger et démarrer à froid : systemctl --user daemon-reload && restart ou launchctl bootstrap suivi de kickstart. Vérifiez que le processus parent est systemd ou launchd, pas une session SSH.
6. Sondes locales : lsof -i :18789, validation JSON minimale, puis openclaw doctor en suivant l’article en échelle. Ne faites pas tourner les jetons de canaux tant que les sondes sont rouges.
7. Test de fumée des canaux : seulement lorsque les journaux du Gateway semblent sains, réparez le couplage. Capturez les transcriptions de commandes dans la fiche de changement pour les auditeurs.

Entre les étapes cinq et six, il est utile de laisser quelques minutes de « trempe » : certains effets de cache et de verrouillage de fichiers n’apparaissent qu’après le premier cycle complet d’écriture des journaux. Si vous automatisez ces vérifications, journalisez l’horodatage et l’UID effectif pour éviter les ambiguïtés lors des investigations croisées fuseaux horaires.

4. Références : chemins, port 18789, champs d’audit

Cette section tient lieu d’annexe wiki ; les étapes numérotées ci-dessus portent le récit. Ensemble, elles offrent à la fois une séquence et une profondeur de checklist pour les post-mortems. Les équipes conformes peuvent y mapper directement leurs exigences de traçabilité sans réinventer une nomenclature à chaque migration.

• Source de vérité unique pour le JSON : documenter quelle machine détient le openclaw.json canonique et comment les sauvegardes sont prises. Après migration, différenciez les fichiers ancien contre nouveau avant de démarrer les services pour éviter des fusions à moitié écrites.
• Conflit de ports : plusieurs gateways de laboratoire sur un même hôte Mac cloud doivent utiliser des ports distincts ou des labels arrêtés ; la contention se déguise souvent en connectivité erratique.
• Minimum d’audit : support d’installation, semver, unité ou label plist, digest d’image si conteneurisé, premier résumé doctor vert, identifiant de compte canal, horodatage de couplage, identifiants opérateurs pour les environnements réglementés.
• Retour arrière : conserver le dernier fichier d’unité connu bon et l’étiquette paquet ou image sur l’ancien hôte. Des exercices trimestriels garantissent que les clés renouvelées depuis cet instantané peuvent encore être restaurées dans le RTO.
• Risques en amont : une fois les couches installation et superviseur validées, traitez la chaîne d’approvisionnement des compétences ClawHub avec la grille d’audit d’avril 2026 déjà publiée sur le blog.
• Fuseaux horaires : avant d’inférer la causalité à partir de journaux fichier, alignez NTP et les fuseaux affichés entre régions.

Enfin, reliez explicitement chaque artefact d’audit à un propriétaire nommé : un runbook sans responsable devient vite une coquille vide lorsque l’équipe tourne. La combinaison « artefact + propriétaire + date de validité » suffit souvent à satisfaire les contrôles internes sans alourdir inutilement la documentation.

5. FAQ

Q : je n’ai copié que le workspace, pas ~/.openclaw. Le Gateway peut-il démarrer ?
Il vous manquera clés et état local. Migrez les deux volumes ou reconstruisez les secrets de manière délibérée avec une checklist d’export en lecture seule depuis l’ancien hôte.

Q : launchctl indique chargé mais rien n’écoute sur 18789 ?
Inspectez StandardErrorPath, WorkingDirectory et le PATH de la plist. Des fichiers d’erreur vides peuvent signifier que les journaux pointent vers un chemin non inscriptible.

Q : puis-je réutiliser mon unité systemd Linux sur macOS ?
Non. Réécrivez-la en LaunchAgent et revalidez variables d’environnement et chemins de journaux ligne par ligne.

Q : le canal est silencieux alors que 18789 répond en local ?
Lisez d’abord les journaux du Gateway, puis le réseau en amont et les listes d’autorisation. Évitez d’effacer toute la configuration avant d’écarter les incohérences d’adresse de liaison après une modification récente.

Q : je veux une instance ancienne côte à côte pour comparer ?
Utilisez des ports et labels distincts et interdisez à l’unité de labo d’écrire le JSON de production pour éviter la corruption par double écrivain.

6. Du pilote à la production sur Mac cloud natif

La complexité du runbook suit l’écart entre l’accès SSH de laboratoire et la production réelle. La virtualisation imbriquée amplifie les surprises de PATH, de volumes et de permissions. Un hôte Mac cloud dédié dont launchd est aligné sur le guide d’installation offre le chemin le plus court vers des démarrages à froid auditable. N’ajoutez des bac à sable Docker qu’après que le chemin natif soit d’une fiabilité routinière, pas pendant la première fenêtre de migration.

Traitez les gateways OpenClaw longue durée comme des pairs d’infrastructure aux exécuteurs CI : réservez le disque, faites tourner les journaux, étiquetez les nœuds et branchez l’audit de connexion. Lorsque chaque membre d’équipe suit le même contrat de plist et de répertoires, les migrations futures répètent un jeu connu au lieu d’improviser par portable.

Sur le long terme, investir une journée dans des exercices de bascule trimestriels coûte moins cher qu’une seule nuit blanche où personne ne sait plus quel binaire répond sur le port 18789. Les équipes qui documentent systématiquement le « premier succès » — horodatage, commande, UID — transforment le runbook en patrimoine technique plutôt qu’en PDF figé.