1. Décomposition de la douleur : copier le dépôt ≠ copier le runtime
(1) Répertoire d'état vs workspace : les équipes gardent skills, prompts et openclaw.json versionné dans le dépôt, alors que sessions, liaisons de canaux et caches passerelle vivent sous le profil utilisateur. Ne migrer que Git restaure la CLI mais laisse des sessions fantômes ou un état de canal vide. (2) Secrets et jetons OAuth : Slack, Discord et messageries d'entreprise peuvent stocker des jetons en clair et dans des magasins runtime chiffrés ; ne sauvegarder qu'une couche impose une ré-autorisation ; si l'ancienne passerelle tourne encore, deux extrémités se disputent la même session bot. (3) launchd vs shell interactif : launchd n'hérite pas des exports de .zshrc ; clés API seulement dans le profil terminal et plist vide — le classique « foreground OK, daemon planifié sans variables ». (4) Frontières utilisateur sur Mac distant : le compte Screen Sharing/SSH doit être celui qui exécute la passerelle ; mélanger root et utilisateur de login casse propriété et trousseau.
Matérialisez ces quatre axes sur une page wiki interne : version OpenClaw, checksum d'archive, ticket et ordre d'arrêt. Si des sous-dossiers de ~/.openclaw changent de nom entre releases, notez le chemin upstream au moment du snapshot. En passant d'un portable à un Mac en colocation, revérifiez DHCP, VPN split et domaines de recherche DNS — des API « stables » hier changent de résolution et les webhooks partent dans le vide.
Conservez des preuves d'installation : gestionnaire de paquets, runtime Node, fichier Compose actif sur la source — sinon la cible est « plus neuve » que votre snapshot et la CLI dérive. Liez dans le ticket la matrice d'installation et l'onboarding pour que les relecteurs voient les mêmes guides.
2. Matrice : que mettre dans le bundle froid (2026)
| Objet | Chemin / sens | Dans le bundle ? |
|---|---|---|
| Arbre d'état utilisateur | ~/.openclaw (noms peuvent varier — doc amont) | Oui : liaisons, caches, secrets locaux |
| Workspace | Skills, scripts, openclaw.json versionné | Oui : même horodatage de snapshot que l'état |
| Job launchd | Plist passerelle dans ~/Library/LaunchAgents/ | Oui : utilisateur runtime, répertoire de travail, noms d'ENV |
| Volumes Docker | Volumes nommés ou bind mounts | Conditionnel : aligné avec votre Docker production |
| Trousseau macOS | Certains canaux y stockent des refresh tokens | Prudent : préférer le flux ré-auth vendeur à l'export sauvage |
3. Cinq étapes : geler → empaqueter → vérifier → démarrage à froid → re-pairer
Étape 1 — Geler les écrivains : arrêtez passerelle, jobs launchd ou pile Compose sur l'hôte source pour que SQLite et verrous ne bougent pas pendant l'archive ; archiver pendant des écritures actives corrompt après restauration. Documentez l'ordre d'arrêt ; certaines équipes coupent aussi cron/CI qui relancent l'agent. Plusieurs projets Compose s'arrêtent selon les dépendances ; gardez docker ps comme preuve d'un plancher propre.
Étape 2 — Apparier les snapshots : capturez ~/.openclaw et le workspace au même instant, lockfiles inclus ; avec Docker, exportez volume ou digest d'image pour aligner trois horodatages. Sur volumes sensibles à la casse ou fermes de symlinks, résolvez les chemins réels avant tarball. Décidez si caches pnpm/npm font partie du bundle ou seront reconstruits — mélanger ancien état et dépendances fraîches sans note produit des heisenbugs lors des tests canaux.
Étape 3 — Vérifier et nettoyer : checksum de l'archive avant dépaquetage ; remplacez anciens hôtes, chemins absolus, URLs LAN-only par des cibles joignables depuis le nouveau ou le Mac distant ; mettez à jour périphériques série USB, poids de modèles locaux, montages Samba ; grep des littéraux IP — DHCP résidentiel bouge souvent les webhooks.
Étape 4 — Démarrage à froid : surface minimale d'abord (loopback admin), openclaw doctor ou échelon projet, vérifiez logs, droits, listeners selon contrat plist. Laissez le premier canal désactivé tant que doctor n'est pas vert ; OAuth partiel avec ENV incomplet laisse un état partiel chez le vendeur. Mesurez CPU/RAM de référence et cherchez des drapeaux debug oubliés.
Étape 5 — Re-pairage canaux : suivez OAuth/webhooks vendeur ; deux bots actifs avec les mêmes identifiants sont souvent interdits — retirez complètement l'ancienne instance avant la nouvelle pour éviter doubles livraisons et conflits de signature. Faites tourner les secrets d'app si possible pour la piste d'audit ; après re-pairage, utilisez des sondes scriptées plutôt que des clics ad hoc.
Optionnel : notez la TTL DNS externe et les bascules de fournisseur de tunnel afin qu'après changement d'IP ou d'hôte personne ne résolve encore l'ancienne extrémité par cache.
CHIFFRES / SEUILS (CITABLES)
① Trio snapshot : ~/.openclaw + workspace + plist (ou compose + manifeste volumes). Manquer un maillon = migration incomplète.
② Environnement : les EnvironmentVariables launchd doivent matcher explicitement le shell — clés API, proxy, fuseau au minimum.
③ Bascule canal : fenêtre de refroidissement entre ancien et nouveau bot ; silence vendeur = souvent déploiement gris minute-scale.
④ Mac distant : utilisateur SSH = utilisateur passerelle ; ne mélangez pas UID entre GUI et launchd sans tête.
⑤ Retour arrière : archive read-only de l'hôte source au moins un cycle de release avant de détruire les copies modifiables.
4. Paramètres : pourquoi « processus OK » peut laisser les canaux silencieux
Mode le plus trompeur : processus sains, sondes vertes, mais aucun message entrant. Liaisons : passage 127.0.0.1 → IP LAN sans mettre à jour reverse proxy/pare-feu. Webhooks : consoles doivent pointer vers le nouveau tunnel ou egress statique ; callbacks Slack/Feishu oubliés = drop silencieux. Horloge/TLS : dérive NTP ou inspection TLS casse les signatures. tools.profile : chemins binaires absolus de l'ancien hôte — parcourez le guide sessions_spawn & sous-agents et ajustez les listes blanches.
Si le mystère persiste, rassemblez quatre artefacts avant ticket : plist redactée, URL publique exacte, trace tcpdump/proxy sur handshake TLS, extrait de logs couvrant un ID d'événement entrant. Cela sépare « HTTP jamais reçu » de « reçu, signature rejetée ». Tenez un glossaire court champs dashboard ↔ clés config.
Répétez trimestriellement : dépaquetez l'archive du trimestre précédent sur un Mac de test, doctor, sondes webhook. Les équipes avec snapshots appariés récupèrent en heures ; « repo seul » passe des journées à diff l'état invisible. Traitez le silence d'abord comme problème réseau et identité.
Ajoutez une ligne dans votre runbook pour les webhooks sortants : si l'agent doit rappeler des API internes derrière VPN, vérifiez que le Mac distant possède les mêmes routes split-tunnel et certificats racine entreprise que le portable source — sinon les appels « fonctionnaient hier » échouent avec des erreurs TLS déguisées en timeouts applicatifs. Documentez aussi les dépendances optionnelles (OCR, binaires système) que tools.profile autorise : une migration est souvent le moment où l'on découvre qu'un binaire n'était présent que sur l'ancienne machine.
5. Tableau de décision : portable vs Mac distant dédié
Le tableau résume les compromis ; en pratique la garde on-call et l'existence d'accès remote tracés décident. Un Mac dédié vaut le coup quand les webhooks deviennent critiques et que les minutes d'indisponibilité sont comptées.
| Axe | Portable local | Mac distant dédié |
|---|---|---|
| Disponibilité | couvercle, sommeil, voyage | frontière 24/7 plus nette pour la charge canaux |
| Permissions | debug GUI facile | discipline headless — pas de prompts bloquants |
| Réseau | IP résidentielle instable | egress stable ou domaine tunnel utile aux webhooks |
| Coût | amortissement caché | location transparente pour équipes SLA |
6. FAQ
Les questions ci-dessous couvrent les cas les plus fréquents observés sur des migrations OpenClaw en 2026 ; adaptez les réponses à votre secteur réglementé si vous manipulez des données personnelles, de santé ou financières soumises à audit externe.
Q : synchroniser seulement le workspace ? Ok pour CLI pure, déconseillé fortement si canaux ou continuité — vous perdez plus de temps que la taille du tarball n'économise. Q : Docker vers bare metal ? Traitez comme changement de stack + migration, une forme cible documentée. Q : clés API en clair dans plist ? Ça marche mais hygiene faible ; fichiers env verrouillés ou backend de secrets. Q : Screen Sharing toujours ? SSH au quotidien ; VNC pour OAuth initial ou outils GUI, avec ticket. Q : effacer l'ancien portable tout de suite ? Observation parallèle un cycle business.
Q : tester canaux sans prod ? Utilisez apps staging ou workspaces restreints mais reproduisez chemins webhook/TLS réalistes — tests unitaires ne remplacent pas DNS/TLS. Q : Apple IDs mélangés ? Clarifiez quel utilisateur possède launchd ; logins GUI multiples brouillent la propriété et donnent des EACCES ressemblant à du réseau. Q : emporter overrides Compose ? Oui, versionnez-les avec l'archive et référencez-les au ticket.
Q : upgrader OpenClaw dans la même fenêtre ? Migrez d'abord même version, validez canaux, puis upgrade en ticket séparé avec rollback — sinon chaque incident est 2D. Q : Mac verrouillés MDM ? Coordonnez plists, helpers, extensions réseau. Q : multi-région ? Documentez la souveraineté des logs/jetons ; copier l'état peut heurter la résidence des données.
7. Plongée : migrer, c'est déplacer état et identité ensemble
Les agents OpenClaw 2026 se jugent moins sur « ça s'installe » que sur qui lit/écrit l'état et comment les identités externes mappent les sessions. Déplacer le code sans l'état, c'est déménager sans coffre. openclaw.json encode l'intention ; le profil tient les accords tiers — les deux doivent voyager dans la même transaction logique sinon passerelle verte et canaux muets.
launchd vs shells : clés dans .zshrc, plist vide — 401 flous ; plist surchargée sans ownership des logs bloque la rotation. Croisez chaque variable sensible entre plist, profil shell et CI.
Re-pairage impose un seul endpoint actif ; bots doubles dupliquent et déclenchent abus. Runbooks sérieux : décommission instance ancienne puis promotion nouvelle avec fenêtre grise. WeChat, Feishu, Slack, Discord : cooldowns et IP différents — un modèle unique rarement suffit.
Sur Mac loués, séparez sessions GUI OAuth et services sans tête relançables — alignement Apple Silicon headless. Les nœuds MACGPU fixent la topologie ; les portables redeviennent créatifs au lieu de serveurs thermiquement bridés — comme npm vs Docker : fixez la vérité, puis branchez canaux et SLA.
Excellence opérationnelle : répétitions d'échec trimestrielles — archive, doctor, sondes. Équipes avec snapshots gagnent des heures ; « repo seul » perd des jours. Silence post-migration : egress mal configuré se fait passer pour « l'IA réfléchit ».
Backlog d'acceptation par canal : latence attendue, taux d'erreur, escalade si webhooks absents trop longtemps ; tickets auto quand healthchecks verts mais pas de charge réelle. Calendrier de maintenance avec mises à jour Apple : reboot surprise sans ordre plist/volumes peut créer le même silence qu'un mauvais jeton. Migration n'est pas ponctuelle : rituel récurrent à qualité mesurable.
Observabilité tôt : logs structurés hors Mac, version OpenClaw et SHA git des skills sur chaque alerte, tag « post-migration » jusqu'à fin de période de rodage. Coût faible en semaine calme, prix payé la nuit du patch sécurité ou lors d'un incident client sans marge de diagnostic ni journaux exploitables. Ce n'est pas que des fichiers : restaurer la confiance en alignant jetons, URLs, certificats une fois sur le nouveau métal.
Documentez des couloirs de capacité : canaux simultanés, pics pièces jointes, budget mémoire unifiée à côté d'autres services. Un Mac distant sous-dimensionné montre des timeouts sporadiques semblables à des pannes vendeur. Reliez ces métriques aux guides systemd/launchd et Docker production pour un langage commun lors du prochain renouvellement matériel.
8. Clôture : aller vite exige quand même toutes les étapes
(1) Limites : la disposition d'état peut changer entre majors — semver sur chaque archive ; la conformité peut interdire de cloner la trousseau entière, prévoyez des fenêtres ré-auth. (2) Pourquoi le Mac distant gagne : utilisateur, egress et classe matérielle fixes réduisent la longue traîne du « portable serveur ». (3) MACGPU : répétez l'hébergement passerelle sur nœud Apple Silicon loué avant de figer la topologie — page d'accueil, offres, aide. Chaque migration est un dress rehearsal : aucun raccourci sur le bundle d'état — la police d'assurance la moins chère contre les rechutes nocturnes, les astreintes évitables et les tickets de support sans signal clair.