Migrando o OpenClaw para uma nova maquina

Este guia migra um Gateway OpenClaw de uma maquina para outra sem refazer o onboarding.

A migracao e conceitualmente simples:

Copie o diretorio de estado ($OPENCLAW_STATE_DIR, padrao: ~/.openclaw/) — isso inclui configuracao, autenticacao, sessoes e estado dos canais.
Copie seu workspace (~/.openclaw/workspace/ por padrao) — isso inclui seus arquivos de agente (memoria, prompts, etc.).

Mas existem armadilhas comuns relacionadas a perfis, permissoes e copias parciais.

Antes de comecar (o que voce esta migrando)

1) Identifique seu diretorio de estado

A maioria das instalacoes usa o padrao:

Diretorio de estado: ~/.openclaw/

Mas pode ser diferente se voce usa:

--profile <name> (frequentemente se torna ~/.openclaw-<profile>/)
OPENCLAW_STATE_DIR=/some/path

Se nao tem certeza, execute na maquina antiga:

openclaw status

Procure mencoes de OPENCLAW_STATE_DIR / profile na saida. Se voce roda multiplos gateways, repita para cada perfil.

2) Identifique seu workspace

Padroes comuns:

~/.openclaw/workspace/ (workspace recomendado)
uma pasta personalizada que voce criou

Seu workspace e onde ficam arquivos como MEMORY.md, USER.md e memory/*.md.

3) Entenda o que voce vai preservar

Se voce copiar ambos o diretorio de estado e o workspace, voce mantem:

Configuracao do gateway (openclaw.json)
Perfis de autenticacao / chaves API / tokens OAuth
Historico de sessoes + estado do agente
Estado dos canais (por ex. login/sessao WhatsApp)
Seus arquivos de workspace (memoria, notas de skills, etc.)

Se voce copiar apenas o workspace (por ex. via Git), voce nao preserva:

sessoes
credenciais
logins dos canais

Esses ficam em $OPENCLAW_STATE_DIR.

Etapas de migracao (recomendadas)

Etapa 0 — Faca um backup (maquina antiga)

Na maquina antiga, pare o gateway primeiro para que os arquivos nao mudem durante a copia:

openclaw gateway stop

(Opcional, mas recomendado) arquive o diretorio de estado e o workspace:

# Ajuste os caminhos se voce usa perfil ou localizacoes personalizadas
cd ~
tar -czf openclaw-state.tgz .openclaw

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

Se voce tem multiplos perfis/diretorios de estado (por ex. ~/.openclaw-main, ~/.openclaw-work), arquive cada um.

Etapa 1 — Instale o OpenClaw na nova maquina

Na nova maquina, instale o CLI (e o Node se necessario):

Consulte: Instalacao

Nesta etapa, nao tem problema se o onboarding criar um novo ~/.openclaw/ — voce vai sobrescreve-lo na proxima etapa.

Etapa 2 — Copie o diretorio de estado + workspace para a nova maquina

Copie ambos:

$OPENCLAW_STATE_DIR (padrao ~/.openclaw/)
seu workspace (padrao ~/.openclaw/workspace/)

Abordagens comuns:

scp dos arquivos compactados e extracoes
rsync -a via SSH
disco externo

Apos a copia, garanta que:

Diretorios ocultos foram incluidos (por ex. .openclaw/)
A propriedade dos arquivos esta correta para o usuario que roda o gateway

Etapa 3 — Execute o Doctor (migracoes + reparo do servico)

Na nova maquina:

openclaw doctor

O Doctor e o comando “seguro e chato”. Ele repara servicos, aplica migracoes de configuracao e avisa sobre incompatibilidades.

Depois:

openclaw gateway restart
openclaw status

Armadilhas comuns (e como evita-las)

Armadilha: incompatibilidade de perfil / diretorio de estado

Se voce rodou o gateway antigo com um perfil (ou OPENCLAW_STATE_DIR), e o novo gateway usa um diferente, voce vera sintomas como:

mudancas de configuracao nao surtem efeito
canais ausentes / desconectados
historico de sessoes vazio

Correcao: rode o gateway/servico usando o mesmo perfil/diretorio de estado que voce migrou, depois execute novamente:

openclaw doctor

Armadilha: copiar apenas `openclaw.json`

openclaw.json nao e suficiente. Muitos provedores armazenam estado em:

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

Sempre migre a pasta $OPENCLAW_STATE_DIR inteira.

Armadilha: permissoes / propriedade

Se voce copiou como root ou mudou de usuario, o gateway pode falhar ao ler credenciais/sessoes.

Correcao: garanta que o diretorio de estado + workspace pertencam ao usuario que roda o gateway.

Armadilha: migrando entre modos remoto/local

Se sua UI (WebUI/TUI) aponta para um gateway remoto, o host remoto e dono do armazenamento de sessoes + workspace.
Migrar seu notebook nao vai mover o estado do gateway remoto.

Se voce esta no modo remoto, migre o host do gateway.

Armadilha: segredos em backups

$OPENCLAW_STATE_DIR contem segredos (chaves API, tokens OAuth, credenciais WhatsApp). Trate backups como segredos de producao:

armazene criptografados
evite compartilhar por canais inseguros
faca rotacao das chaves em caso de suspeita de exposicao

Lista de verificacao

Na nova maquina, confirme que:

openclaw status mostra o gateway rodando
Seus canais ainda estao conectados (por ex. WhatsApp nao exige re-pareamento)
O dashboard abre e mostra sessoes existentes
Seus arquivos de workspace (memoria, configs) estao presentes