Migrer OpenClaw vers une nouvelle machine

Ce guide migre une passerelle OpenClaw d’une machine a une autre sans refaire l’accueil.

La migration est conceptuellement simple :

Copiez le repertoire d’etat ($OPENCLAW_STATE_DIR, par defaut : ~/.openclaw/) — cela inclut la configuration, l’authentification, les sessions et l’etat des canaux.
Copiez votre espace de travail (~/.openclaw/workspace/ par defaut) — cela inclut vos fichiers d’agent (memoire, prompts, etc.).

Mais il y a des pieges courants autour des profils, des permissions et des copies partielles.

Avant de commencer (ce que vous migrez)

1) Identifier votre repertoire d’etat

La plupart des installations utilisent la valeur par defaut :

Repertoire d’etat : ~/.openclaw/

Mais il peut etre different si vous utilisez :

--profile <name> (devient souvent ~/.openclaw-<profile>/)
OPENCLAW_STATE_DIR=/some/path

Si vous n’etes pas sur, executez sur l’ancienne machine :

openclaw status

Cherchez les mentions de OPENCLAW_STATE_DIR / profile dans la sortie. Si vous executez plusieurs passerelles, repetez pour chaque profil.

2) Identifier votre espace de travail

Valeurs par defaut courantes :

~/.openclaw/workspace/ (espace de travail recommande)
un dossier personnalise que vous avez cree

Votre espace de travail est l’endroit ou resident les fichiers comme MEMORY.md, USER.md et memory/*.md.

3) Comprendre ce que vous preservez

Si vous copiez a la fois le repertoire d’etat et l’espace de travail, vous conservez :

La configuration de la passerelle (openclaw.json)
Les profils d’authentification / cles API / tokens OAuth
L’historique des sessions + l’etat de l’agent
L’etat des canaux (par ex. connexion/session WhatsApp)
Vos fichiers d’espace de travail (memoire, notes de competences, etc.)

Si vous copiez uniquement l’espace de travail (par ex. via Git), vous ne preservez pas :

les sessions
les identifiants
les connexions aux canaux

Ceux-ci resident sous $OPENCLAW_STATE_DIR.

Etapes de migration (recommandees)

Etape 0 — Faire une sauvegarde (ancienne machine)

Sur l’ancienne machine, arretez d’abord la passerelle pour que les fichiers ne changent pas en cours de copie :

openclaw gateway stop

(Optionnel mais recommande) archivez le repertoire d’etat et l’espace de travail :

# Ajustez les chemins si vous utilisez un profil ou des emplacements personnalises
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

Si vous avez plusieurs profils/repertoires d’etat (par ex. ~/.openclaw-main, ~/.openclaw-work), archivez chacun.

Etape 1 — Installer OpenClaw sur la nouvelle machine

Sur la nouvelle machine, installez le CLI (et Node si necessaire) :

Consultez : Installation

A ce stade, ce n’est pas grave si l’accueil cree un nouveau ~/.openclaw/ — vous l’ecraserez a l’etape suivante.

Etape 2 — Copier le repertoire d’etat + l’espace de travail sur la nouvelle machine

Copiez les deux :

$OPENCLAW_STATE_DIR (par defaut ~/.openclaw/)
votre espace de travail (par defaut ~/.openclaw/workspace/)

Approches courantes :

scp des archives et extraction
rsync -a via SSH
disque externe

Apres la copie, assurez-vous que :

Les repertoires caches ont ete inclus (par ex. .openclaw/)
La propriete des fichiers est correcte pour l’utilisateur executant la passerelle

Etape 3 — Executer Doctor (migrations + reparation du service)

Sur la nouvelle machine :

openclaw doctor

Doctor est la commande “sure et ennuyeuse”. Il repare les services, applique les migrations de configuration et avertit des incompatibilites.

Puis :

openclaw gateway restart
openclaw status

Pieges courants (et comment les eviter)

Piege : incompatibilite de profil / repertoire d’etat

Si vous avez execute l’ancienne passerelle avec un profil (ou OPENCLAW_STATE_DIR), et que la nouvelle passerelle utilise un autre, vous verrez des symptomes comme :

les changements de configuration ne prennent pas effet
les canaux sont manquants / deconnectes
l’historique des sessions est vide

Correction : executez la passerelle/le service en utilisant le meme profil/repertoire d’etat que celui que vous avez migre, puis relancez :

openclaw doctor

Piege : copier uniquement `openclaw.json`

openclaw.json ne suffit pas. Beaucoup de fournisseurs stockent leur etat sous :

$OPENCLAW_STATE_DIR/credentials/
$OPENCLAW_STATE_DIR/agents/<agentId>/...

Migrez toujours l’integralite du dossier $OPENCLAW_STATE_DIR.

Piege : permissions / propriete

Si vous avez copie en tant que root ou change d’utilisateur, la passerelle peut echouer a lire les identifiants/sessions.

Correction : assurez-vous que le repertoire d’etat + l’espace de travail appartiennent a l’utilisateur executant la passerelle.

Piege : migration entre modes distant/local

Si votre UI (WebUI/TUI) pointe vers une passerelle distante, l’hote distant possede le magasin de sessions + l’espace de travail.
Migrer votre portable ne deplacera pas l’etat de la passerelle distante.

Si vous etes en mode distant, migrez l’hote de la passerelle.

Piege : secrets dans les sauvegardes

$OPENCLAW_STATE_DIR contient des secrets (cles API, tokens OAuth, identifiants WhatsApp). Traitez les sauvegardes comme des secrets de production :

stockez-les chiffrees
evitez de les partager via des canaux non securises
effectuez une rotation des cles en cas de suspicion d’exposition

Liste de verification

Sur la nouvelle machine, confirmez que :

openclaw status montre la passerelle en fonctionnement
Vos canaux sont toujours connectes (par ex. WhatsApp ne necessite pas de re-appairage)
Le tableau de bord s’ouvre et affiche les sessions existantes
Vos fichiers d’espace de travail (memoire, configurations) sont presents