---
title: "Guia de Migração — Mover para Novo Servidor"
url: "https://openclaw.ia.br/guias/migracao/"
markdown_url: "https://openclaw.ia.br/guias/migracao.MD"
description: "Como migrar OpenClaw para novo servidor. Backup, transferência e restauração completa."
date: ""
author: ""
---

# Guia de Migração — Mover para Novo Servidor

Como migrar OpenClaw para novo servidor. Backup, transferência e restauração completa.


# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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)**

```bash
# 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)**

```bash
# 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)**

```bash
# 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

```bash
# 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

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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

```bash
# 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

```bash
# 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):

```bash
# 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:

```bash
# 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:

```bash
# 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](/guias/backup/) — Configure backups automáticos no novo servidor imediatamente
- [Guia de Segurança](/guias/seguranca/) — Hardening do novo servidor
- [Pos-Instalação](/guias/pos-instalacao/) — Checklist de configuração completa
- [Debugging](/guias/debugging/) — Diagnose problemas que surgirem após a migração
- [Canais](/canais/) — Reconecte e configure canais de comunicação