Guia de Migração — Mover para Novo Servidor
Migração do OpenClaw para Novo Servidor
Introdução
Migrar o OpenClaw para um novo servidor é uma das tarefas que eventualmente todo usuário enfrenta — seja para atualizar o hardware, trocar de provedor cloud, reduzir custos ou consolidar infraestrutura. A boa notícia é que, feita com planejamento, a migração é relativamente simples e pode ser completada em 30-60 minutos com tempo de inatividade mínimo.
A chave para uma migração bem-sucedida é entender exatamente o que precisa ser transferido. O OpenClaw armazena seu estado em arquivos locais: configurações, memória do agente, personalidade definida no SOUL.md, skills personalizadas e, dependendo do canal, sessões autenticadas. Tudo isso precisa ser copiado para o novo servidor antes de encerrar o antigo.
Existem cenários diferentes que requerem atenção específica: migração entre servidores com mesmo sistema operacional (mais simples), migração entre sistemas diferentes (Linux para Linux normalmente é tranquilo), e migração com necessidade de reautenticação de canais como WhatsApp (que requer reconexão via QR code). Este guia cobre todos eles.
Pré-requisitos
Antes de iniciar a migração, certifique-se de ter:
- Acesso SSH aos dois servidores (antigo e novo)
- Espaço suficiente no novo servidor (pelo menos 2x o tamanho atual do workspace)
- Node.js instalado no novo servidor (mesma versão ou compatível)
- Backup recente do OpenClaw (procedimento de segurança antes de qualquer migração)
- Pelo menos 1 hora disponível sem interrupções
Planejamento da Migração
Checklist Pré-Migração
Antes de começar, verifique:
# No servidor ANTIGO
# 1. Verificar versão atual do OpenClaw
openclaw --version
# Anote: vX.X.X
# 2. Verificar versão do Node.js
node --version
# Anote: vX.X.X
# 3. Ver o que está instalado e configurado
openclaw doctor
openclaw skills list
openclaw channel status
# 4. Verificar tamanho total dos dados
du -sh ~/.openclaw/ ~/clawd/
# Ex: 450MB no total
# 5. Verificar última vez que o backup foi feito
ls -lh ~/backups/openclaw/ 2>/dev/null || echo "Sem backups encontrados"
Criar Backup Completo Antes de Migrar
Sempre crie um backup fresco antes de migrar:
# No servidor ANTIGO
tar -czvf openclaw-pre-migration-$(date +%Y%m%d-%H%M).tar.gz \
~/.openclaw/ \
~/clawd/
# Verificar que o backup está completo
tar -tzvf openclaw-pre-migration-*.tar.gz | wc -l
# Deve listar todos os arquivos
# Copiar backup para local seguro (fora de ambos os servidores)
scp openclaw-pre-migration-*.tar.gz usuario@storage-externo:~/
Migração Passo a Passo
Passo 1: Preparar o Novo Servidor
# No servidor NOVO
# Atualizar sistema
sudo apt update && sudo apt upgrade -y # Ubuntu/Debian
# ou
sudo yum update -y # CentOS/RHEL
# Instalar Node.js (mesma versão do servidor antigo ou mais recente compatível)
# Recomendado: Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Verificar versão
node --version
# Instalar OpenClaw globalmente
npm install -g openclaw
# Verificar instalação
openclaw --version
Passo 2: Exportar os Dados do Servidor Antigo
# No servidor ANTIGO
# Parar o gateway para garantir consistência dos dados
openclaw gateway stop
# Criar arquivo de migração completo
tar -czvf openclaw-migration.tar.gz \
~/.openclaw/ \
~/clawd/
echo "Tamanho do arquivo de migração:"
ls -lh openclaw-migration.tar.gz
# Verificar integridade
tar -tzvf openclaw-migration.tar.gz | grep -E "SOUL.md|MEMORY.md|config.yaml"
# Deve listar esses arquivos
Passo 3: Transferir para o Novo Servidor
Opção A: Transferência direta via SCP (mais simples)
# No servidor ANTIGO — enviar para o novo
scp openclaw-migration.tar.gz usuario@novo-servidor.com:~/
# Ou, do servidor NOVO — puxar do antigo
scp usuario@servidor-antigo.com:~/openclaw-migration.tar.gz ~/
Opção B: Sincronização direta via rsync (mais rápido para arquivos grandes)
# Do servidor NOVO — sincronizar diretamente
rsync -avz --progress \
usuario@servidor-antigo.com:~/.openclaw/ ~/.openclaw/
rsync -avz --progress \
usuario@servidor-antigo.com:~/clawd/ ~/clawd/
Opção C: Via storage intermediário (para servidores sem comunicação direta)
# No servidor ANTIGO: enviar para S3/cloud
aws s3 cp openclaw-migration.tar.gz s3://meu-bucket/migrations/
# No servidor NOVO: baixar do S3
aws s3 cp s3://meu-bucket/migrations/openclaw-migration.tar.gz ~/
Passo 4: Restaurar no Novo Servidor
# No servidor NOVO
# Extrair o arquivo de migração
tar -xzvf openclaw-migration.tar.gz -C /
# Verificar que os arquivos estão no lugar certo
ls -la ~/.openclaw/
ls -la ~/clawd/
cat ~/clawd/SOUL.md | head -5 # Verificar conteúdo
# Corrigir permissões
chmod 600 ~/.openclaw/config.yaml
chmod 700 ~/clawd
chmod 600 ~/clawd/SOUL.md
chmod 600 ~/clawd/MEMORY.md
Passo 5: Configurar e Verificar
# No servidor NOVO
# Verificar diagnóstico completo
openclaw doctor
# Verificar se API keys estão configuradas
openclaw auth status
# Se as keys foram movidas como variáveis de ambiente, reconfigure:
export ANTHROPIC_API_KEY="sua-key"
echo 'export ANTHROPIC_API_KEY="sua-key"' >> ~/.bashrc
# Iniciar gateway
openclaw gateway start
# Verificar que está funcionando
openclaw gateway status
openclaw status
Passo 6: Reconectar Canais
Alguns canais precisam de reautenticação após migração:
WhatsApp:
# Reconectar WhatsApp (necessário novo QR code na maioria dos casos)
openclaw channel reconnect whatsapp
# 1. QR code aparece no terminal
# 2. Abra WhatsApp > Configurações > Dispositivos Conectados
# 3. Escaneie o código
# 4. Aguarde confirmação
Telegram:
# Telegram normalmente não precisa de reconexão
openclaw channel status telegram
# Se aparecer como conectado: ótimo, não precisa fazer nada
# Se precisar reconectar:
openclaw channel reconnect telegram
Discord e Slack:
# Esses canais usam tokens estáticos — se o token está no config.yaml, funcionam automaticamente
openclaw channel status discord
openclaw channel status slack
Passo 7: Teste Completo
# No servidor NOVO — teste completo antes de encerrar o antigo
# 1. Teste de conectividade básica
openclaw ping
# 2. Envie mensagem de teste pelo canal principal
# (via WhatsApp, Telegram, ou outro canal configurado)
# Teste: "Olá, funcionou a migração?"
# 3. Verificar que memória está acessível
openclaw context show | head -20
# 4. Testar skills instaladas
openclaw skills list
openclaw skills test nome-da-skill
# 5. Verificar logs para erros
openclaw gateway logs --last 50
Passo 8: Configurar para Iniciar Automaticamente
# No servidor NOVO — configurar início automático
# Usando systemd (recomendado para Linux)
openclaw service install
# Habilitar e iniciar
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway
# Verificar status
systemctl --user status openclaw-gateway
# Configurar para iniciar com o sistema (sem login necessário)
sudo loginctl enable-linger $USER
Configurações Específicas por Cenário
Migração Ubuntu → Ubuntu (Mesmo OS)
O processo padrão funciona perfeitamente. Certifique-se de usar a mesma versão do Node.js ou uma versão mais recente compatível.
Migração entre Provedores Cloud
Se você está saindo de um provedor que usa nome de usuário diferente (ex: ubuntu na AWS, root no Hetzner):
# Ajustar paths se necessário
# Se o usuário mudou, os paths absolutos no config.yaml podem precisar de ajuste
sed -i 's|/home/ubuntu/|/home/novo-usuario/|g' ~/.openclaw/config.yaml
sed -i 's|/home/ubuntu/|/home/novo-usuario/|g' ~/clawd/HEARTBEAT.md
Migração com Downtime Zero
Para operações críticas onde você não pode ter downtime:
# 1. Configure e teste o novo servidor ANTES de parar o antigo
# 2. Faça a migração dos dados com o antigo ainda rodando (rsync)
# 3. Pare o antigo
# 4. Faça rsync final para pegar mudanças recentes
# 5. Inicie o novo
# Script para sync final rápido
rsync -avz --progress \
usuario@servidor-antigo.com:~/clawd/memory/ ~/clawd/memory/
rsync -avz --progress \
usuario@servidor-antigo.com:~/clawd/MEMORY.md ~/clawd/MEMORY.md
Erros Comuns e Soluções
| Erro | Causa Provável | Solução |
|---|---|---|
SOUL.md not found após migração | Arquivo não foi transferido | Verifique se tar -xzvf incluiu ~/clawd/; confira path |
| API keys inválidas no novo servidor | Variáveis de ambiente não configuradas | Re-adicione ao ~/.bashrc e execute source ~/.bashrc |
| WhatsApp não conecta | Session expirada ou número já logado em outro dispositivo | Reconecte com novo QR code |
| Gateway não inicia | Porta já em uso por outro processo | lsof -i :3434; mate o processo ou mude a porta |
| Permissão negada ao ler config | Permissões incorretas após extração | chmod 600 ~/.openclaw/config.yaml |
| Skills não encontradas | Path das skills hardcoded no config | Atualize paths no config.yaml para o novo servidor |
Verificação Pós-Migração
Após a migração completa, execute este checklist:
# Checklist completo de verificação
echo "=== Verificação Pós-Migração ==="
echo "1. Versão instalada:"
openclaw --version
echo "2. Status do gateway:"
openclaw gateway status
echo "3. Diagnóstico completo:"
openclaw doctor
echo "4. Status dos canais:"
openclaw channel status
echo "5. Skills disponíveis:"
openclaw skills list
echo "6. Últimas linhas do log:"
openclaw gateway logs --last 10
Boas Práticas
Nunca encerre o servidor antigo antes de confirmar que o novo está funcionando: Mantenha o antigo em standby por pelo menos 24 horas após a migração. Se algo der errado, você pode reverter rapidamente.
Documente a migração: Anote no MEMORY.md que a migração foi feita, a data, e qual servidor foi o destino. Parece óbvio, mas meses depois essa informação vai ter valor.
Atualize DNS e IPs se necessário: Se você usa IP fixo para webhooks ou integrações, atualize os registros nos serviços externos (GitHub webhooks, Stripe webhooks, etc.).
Teste cada canal individualmente: Não assuma que porque um canal funciona todos funcionam. Teste explicitamente cada canal configurado.
Mantenha o backup da migração por 30 dias: Depois de confirmar que o novo servidor está funcionando bem, ainda mantenha o backup da migração por 30 dias antes de deletar. Problemas às vezes surgem semanas depois.
Migre nos horários de menor uso: Se o OpenClaw está em produção para uma equipe, faça a migração fora do horário de trabalho para minimizar impacto.
Perguntas Frequentes
Preciso reinstalar todas as skills após migração?
Não, se você incluiu ~/clawd/skills/ no backup. As skills são apenas arquivos/pastas e são copiadas junto com o resto. Verifique com openclaw skills list após a migração.
As conversas históricas são preservadas?
Sim, se você incluiu ~/.openclaw/sessions/ no backup. Note que sessions do WhatsApp são tecnicamente diferentes — os arquivos são preservados, mas o WhatsApp pode exigir reconexão de qualquer forma.
E se eu mudar o IP do servidor? Webhooks configurados no GitHub, Stripe e outros serviços precisarão ser atualizados com o novo IP ou domínio. Faça um inventário de todos os webhooks configurados antes de migrar.
Posso migrar enquanto o assistente está sendo usado? É possível mas não recomendado. Mensagens enviadas durante a migração podem ser perdidas ou processadas pelo servidor antigo sem replicar para o novo. Se precisar de uptime mínimo, avise os usuários e migre em janela de manutenção.
Como verificar se há diferença entre o que foi migrado e o original?
Use checksums: md5sum ~/clawd/MEMORY.md nos dois servidores e compare. Para verificação completa: find ~/clawd -type f | sort | xargs md5sum > checksums.txt e compare os arquivos.
Próximos Passos
- Guia de Backup — Configure backups automáticos no novo servidor imediatamente
- Guia de Segurança — Hardening do novo servidor
- Pos-Instalação — Checklist de configuração completa
- Debugging — Diagnose problemas que surgirem após a migração
- Canais — Reconecte e configure canais de comunicação