Migrare OpenClaw su una nuova macchina

Questa guida migra un Gateway OpenClaw da una macchina a un’altra senza rifare l’onboarding.

La migrazione e concettualmente semplice:

Copia la directory di stato ($OPENCLAW_STATE_DIR, default: ~/.openclaw/) — include configurazione, autenticazione, sessioni e stato dei canali.
Copia il tuo workspace (~/.openclaw/workspace/ di default) — include i file dell’agente (memoria, prompt, ecc.).

Ma ci sono insidie comuni riguardanti profili, permessi e copie parziali.

Prima di iniziare (cosa stai migrando)

1) Identifica la tua directory di stato

La maggior parte delle installazioni usa il default:

Directory di stato: ~/.openclaw/

Ma potrebbe essere diverso se usi:

--profile <name> (spesso diventa ~/.openclaw-<profile>/)
OPENCLAW_STATE_DIR=/some/path

Se non sei sicuro, esegui sulla vecchia macchina:

openclaw status

Cerca menzioni di OPENCLAW_STATE_DIR / profilo nell’output. Se esegui piu gateway, ripeti per ogni profilo.

2) Identifica il tuo workspace

Default comuni:

~/.openclaw/workspace/ (workspace consigliato)
una cartella personalizzata che hai creato

Il tuo workspace e dove si trovano file come MEMORY.md, USER.md e memory/*.md.

3) Comprendi cosa conserverai

Se copi sia la directory di stato che il workspace, conservi:

Configurazione del gateway (openclaw.json)
Profili di autenticazione / chiavi API / token OAuth
Cronologia sessioni + stato dell’agente
Stato dei canali (es. login/sessione WhatsApp)
I tuoi file workspace (memoria, note skill, ecc.)

Se copi solo il workspace (es. via Git), non conservi:

sessioni
credenziali
login dei canali

Questi risiedono sotto $OPENCLAW_STATE_DIR.

Passi della migrazione (consigliati)

Passo 0 — Fai un backup (vecchia macchina)

Sulla vecchia macchina, ferma prima il gateway cosi i file non cambiano durante la copia:

openclaw gateway stop

(Opzionale ma consigliato) archivia la directory di stato e il workspace:

# Aggiusta i percorsi se usi un profilo o posizioni personalizzate
cd ~
tar -czf openclaw-state.tgz .openclaw

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

Se hai piu profili/directory di stato (es. ~/.openclaw-main, ~/.openclaw-work), archivia ciascuno.

Passo 1 — Installa OpenClaw sulla nuova macchina

Sulla nuova macchina, installa la CLI (e Node se necessario):

Vedi: Installazione

A questo punto, va bene se l’onboarding crea un ~/.openclaw/ nuovo — lo sovrascriverai nel passo successivo.

Passo 2 — Copia la directory di stato + workspace sulla nuova macchina

Copia entrambi:

$OPENCLAW_STATE_DIR (default ~/.openclaw/)
il tuo workspace (default ~/.openclaw/workspace/)

Approcci comuni:

scp dei tarball ed estrarre
rsync -a via SSH
drive esterno

Dopo la copia, assicurati che:

Le directory nascoste siano incluse (es. .openclaw/)
La proprieta dei file sia corretta per l’utente che esegue il gateway

Passo 3 — Esegui Doctor (migrazioni + riparazione servizi)

Sulla nuova macchina:

openclaw doctor

Doctor e il comando “sicuro e noioso”. Ripara i servizi, applica le migrazioni della configurazione e avvisa delle incongruenze.

Poi:

openclaw gateway restart
openclaw status

Insidie comuni (e come evitarle)

Insidia: mismatch profilo / directory di stato

Se il vecchio gateway usava un profilo (o OPENCLAW_STATE_DIR), e il nuovo gateway ne usa uno diverso, vedrai sintomi come:

le modifiche alla configurazione non hanno effetto
canali mancanti / disconnessi
cronologia sessioni vuota

Soluzione: esegui il gateway/servizio usando lo stesso profilo/directory di stato che hai migrato, poi riesegui:

openclaw doctor

Insidia: copiare solo `openclaw.json`

openclaw.json non e sufficiente. Molti provider memorizzano lo stato sotto:

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

Migra sempre l’intera cartella $OPENCLAW_STATE_DIR.

Insidia: permessi / proprieta

Se hai copiato come root o cambiato utente, il gateway potrebbe non riuscire a leggere credenziali/sessioni.

Soluzione: assicurati che la directory di stato + workspace siano di proprieta dell’utente che esegue il gateway.

Insidia: migrazione tra modalita remota/locale

Se la tua UI (WebUI/TUI) punta a un gateway remoto, l’host remoto possiede il session store + workspace.
Migrare il tuo laptop non spostara lo stato del gateway remoto.

Se sei in modalita remota, migra l’host del gateway.

Insidia: segreti nei backup

$OPENCLAW_STATE_DIR contiene segreti (chiavi API, token OAuth, credenziali WhatsApp). Tratta i backup come segreti di produzione:

conservali crittografati
evita di condividerli su canali non sicuri
ruota le chiavi se sospetti un’esposizione

Checklist di verifica

Sulla nuova macchina, conferma:

openclaw status mostra il gateway in esecuzione
I tuoi canali sono ancora connessi (es. WhatsApp non richiede un nuovo pairing)
La dashboard si apre e mostra le sessioni esistenti
I tuoi file workspace (memoria, configurazioni) sono presenti