OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Maintenance

Guia de migração

OpenClaw oferece três caminhos de migração: importar de outro sistema de agentes, mover uma instalação existente para uma nova máquina e atualizar um plugin no local.

Importar de outro sistema de agentes

Os provedores de migração incluídos trazem instruções, servidores MCP, Skills, configuração de modelos e chaves de API (mediante adesão) para o OpenClaw. Os planos são visualizados antes de qualquer alteração, os segredos são ocultados nos relatórios e a aplicação é respaldada por um backup verificado.

Migrando do Claude

Importe o estado do Claude Code e do Claude Desktop, incluindo CLAUDE.md, servidores MCP, Skills e comandos de projeto.
Migrando do Hermes

Importe a configuração do Hermes, provedores, servidores MCP, memória, Skills e chaves compatíveis do .env.

O ponto de entrada da CLI é openclaw migrate. A integração inicial também pode oferecer a migração ao detectar uma origem conhecida (openclaw onboard --flow import).

Mover o OpenClaw para uma nova máquina

Copie o diretório de estado (~/.openclaw/ por padrão) e seu espaço de trabalho para preservar:

  • Configuração — openclaw.json e todas as configurações do Gateway.
  • Autenticação — auth-profiles.json por agente (chaves de API e OAuth), além de qualquer estado de canal ou provedor em credentials/.
  • Sessões — histórico de conversas e estado do agente.
  • Estado dos canais — login do WhatsApp, sessão do Telegram e similares.
  • Arquivos do espaço de trabalho — MEMORY.md, USER.md, Skills e prompts.

Etapas da migração

  • Interromper o Gateway e fazer backup

    Na máquina antiga, interrompa o Gateway para que os arquivos não sejam alterados durante a cópia e, em seguida, crie o arquivo compactado:

    bash
    openclaw gateway stopcd ~tar -czf openclaw-state.tgz .openclaw

    Se você usa vários perfis (por exemplo, ~/.openclaw-work), arquive cada um separadamente.

  • Instalar o OpenClaw na nova máquina

    Instale a CLI (e o Node, se necessário) na nova máquina. Não há problema se a integração inicial criar um novo ~/.openclaw/ — você o substituirá na próxima etapa.

  • Copiar o diretório de estado e o espaço de trabalho

    Transfira o arquivo compactado por scp, rsync -a ou uma unidade externa e, em seguida, extraia-o:

    bash
    cd ~tar -xzf openclaw-state.tgz

    Confirme que os diretórios ocultos foram incluídos e que a propriedade dos arquivos corresponde ao usuário que executará o Gateway.

  • Executar o Doctor e verificar

    Na nova máquina, execute o Doctor para aplicar migrações de configuração e reparar os serviços:

    bash
    openclaw doctoropenclaw gateway restartopenclaw status

    • Se o Telegram ou o Discord usar o fallback padrão de variáveis de ambiente (TELEGRAM_BOT_TOKEN ou DISCORD_BOT_TOKEN), verifique se o .env do diretório de estado migrado contém essas chaves sem exibir os valores secretos:

    bash
    awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

    O openclaw doctor também avisa quando uma conta padrão habilitada do Telegram ou Discord não tem um token configurado e a variável de ambiente correspondente não está disponível para o processo do Doctor.

    Armadilhas comuns

    Incompatibilidade de perfil ou diretório de estado

    Se o Gateway antigo usava --profile ou OPENCLAW_STATE_DIR e o novo não usa, os canais parecerão desconectados e as sessões estarão vazias. Inicie o Gateway com o mesmo perfil ou diretório de estado que você migrou e execute openclaw doctor novamente.

    Copiar apenas openclaw.json

    O arquivo de configuração sozinho não é suficiente. Os perfis de autenticação dos modelos ficam em agents/<agentId>/agent/auth-profiles.json, e o estado dos canais e provedores fica em credentials/. Sempre migre o diretório de estado inteiro.

    Permissões e propriedade

    Se você fez a cópia como root ou trocou de usuário, o Gateway pode não conseguir ler as credenciais. Certifique-se de que o diretório de estado e o espaço de trabalho pertençam ao usuário que executa o Gateway.

    Modo remoto

    Se sua interface aponta para um Gateway remoto, o host remoto mantém as sessões e o espaço de trabalho. Migre o próprio host do Gateway, não seu laptop local. Consulte as Perguntas frequentes.

    Segredos nos backups

    O diretório de estado contém perfis de autenticação, credenciais de canais e outros estados de provedores. Armazene os backups de forma criptografada, evite canais de transferência inseguros e revogue e substitua as chaves se suspeitar de exposição.

    Lista de verificação

    Na nova máquina, confirme:

    • [ ] openclaw status mostra que o Gateway está em execução.
    • [ ] Os canais continuam conectados (sem necessidade de novo pareamento).
    • [ ] O painel abre e mostra as sessões existentes.
    • [ ] Os arquivos do espaço de trabalho (memória e configurações) estão presentes.

    Atualizar um plugin no local

    As atualizações de plugins no local preservam o mesmo ID do plugin e as mesmas chaves de configuração, mas podem mover o estado armazenado em disco para o layout atual. Os guias de atualização específicos de plugins ficam junto aos respectivos canais:

    • Migração do Matrix: limites de recuperação do estado criptografado, comportamento de snapshots automáticos e comandos de recuperação manual.

    Relacionados

    Was this useful?
    On this page

    On this page