Guide de migration

Migration de OpenClaw vers une nouvelle machine

Ce guide déplace une passerelle OpenClaw vers une nouvelle machine sans avoir à refaire l’onboarding.

Ce qui est migré

Lorsque vous copiez le répertoire d’état (~/.openclaw/ par défaut) et votre espace de travail, vous conservez :

Config — openclaw.json et tous les paramètres de la passerelle
Auth — clés API, jetons OAuth, profils d’identification
Sessions — historique des conversations et état de l’agent
État du canal — connexion WhatsApp, session Telegram, etc.
Fichiers de l’espace de travail — MEMORY.md, USER.md, compétences et invites

Étapes de migration

Arrêter la passerelle et sauvegarder
Sur l’ancienne machine, arrêtez la passerelle afin que les fichiers ne changent pas en cours de copie, puis archivez :
Fenêtre de terminal
```
openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw
```
Si vous utilisez plusieurs profils (p. ex. ~/.openclaw-work), archivez-les chacun séparément.
Installer OpenClaw sur la nouvelle machine
Installez la CLI (et Node si nécessaire) sur la nouvelle machine. C’est normal si l’onboarding crée un nouveau ~/.openclaw/ — vous l’écraserez ensuite.
Copier le répertoire d'état et l'espace de travail
Transférez l’archive via scp, rsync -a ou un disque externe, puis extrayez :
Fenêtre de terminal
```
cd ~
tar -xzf openclaw-state.tgz
```
Assurez-vous que les répertoires cachés ont été inclus et que la propriété des fichiers correspond à l’utilisateur qui exécutera la passerelle.
Exécuter le docteur et vérifier
Sur la nouvelle machine, exécutez Doctor pour appliquer les migrations de configuration et réparer les services :
Fenêtre de terminal
```
openclaw doctor
openclaw gateway restart
openclaw status
```

Pièges courants

Profil ou répertoire d'état incohérent

Si l’ancienne passerelle utilisait --profile ou OPENCLAW_STATE_DIR et que la nouvelle ne les utilise pas, les canaux apparaîtront déconnectés et les sessions seront vides. Lancez la passerelle avec le même profil ou répertoire d’état que celui que vous avez migré, puis réexécutez openclaw doctor.

Copier uniquement openclaw.

Le fichier de configuration seul ne suffit pas. Les identifiants se trouvent sous credentials/, et l’état de l’agent se trouve sous agents/. Migrez toujours le répertoire d’état entier.

Autorisations et propriété

Si vous avez copié en tant que root ou changé d’utilisateur, la passerelle risque de ne pas pouvoir lire les identifiants. Assurez-vous que le répertoire d’état et l’espace de travail appartiennent à l’utilisateur exécutant la passerelle.

Mode distant

Si votre interface pointe vers une passerelle distante, l’hôte distant possède les sessions et l’espace de travail. Migrez l’hôte de la passerelle lui-même, et non votre ordinateur portable local. Voir FAQ.

Secrets dans les sauvegardes

Le répertoire d’état contient des clés API, des jetons OAuth et des identifiants de canal. Stockez les sauvegardes de manière chiffrée, évitez les canaux de transfert non sécurisés et faites tourner les clés si vous soupçonnez une exposition.

Liste de vérification

Sur la nouvelle machine, confirmez :

openclaw status indique que la passerelle est en cours d’exécution
Les canaux sont toujours connectés (aucun ré-appairage nécessaire)
Le tableau de bord s’ouvre et affiche les sessions existantes
Les fichiers de l’espace de travail (mémoire, configurations) sont présents