English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Maintenance

Guia de migração

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

Importar de outro sistema de agente

Use os provedores de migração incluídos para trazer instruções, servidores MCP, Skills, configuração de modelo e chaves de API (opcional) para o OpenClaw. Os planos são pré-visualizados antes de qualquer alteração, segredos são redigidos 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 configuração do Hermes, provedores, servidores MCP, memória, Skills e chaves .env compatíveis.

O ponto de entrada da CLI é openclaw migrate. O onboarding também pode oferecer migração quando detecta 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 workspace para preservar:

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

Etapas da migração

  • Pare o Gateway e faça backup

    Na máquina antiga, pare o Gateway para que os arquivos não mudem durante a cópia e, em seguida, arquive:

    openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw

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

  • Instale o OpenClaw na nova máquina

    Instale a CLI (e o Node, se necessário) na nova máquina. Não há problema se o onboarding criar um ~/.openclaw/ novo. Você o substituirá em seguida.

  • Copie o diretório de estado e o workspace

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

    cd ~
tar -xzf openclaw-state.tgz

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

  • Execute o Doctor e verifique

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

    openclaw doctor
openclaw gateway restart
openclaw status

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

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

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

    Problemas 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 aparecerão desconectados e as sessões ficarã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. Perfis de autenticação de modelo ficam em agents/<agentId>/agent/auth-profiles.json, e o estado de canais e provedores fica em credentials/. Sempre migre o diretório de estado inteiro.

    Permissões e propriedade

    Se você copiou como root ou trocou de usuário, o Gateway pode falhar ao ler credenciais. Garanta que o diretório de estado e o workspace pertençam ao usuário que executa o Gateway.

    Modo remoto

    Se sua UI aponta para um Gateway remoto, o host remoto é dono das sessões e do workspace. Migre o próprio host do Gateway, não seu laptop local. Consulte as Perguntas frequentes.

    Segredos em backups

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

    Lista de verificação

    Na nova máquina, confirme:

    • [ ] openclaw status mostra o Gateway em execução.
    • [ ] Os canais ainda estão conectados (sem necessidade de parear novamente).
    • [ ] O dashboard abre e mostra as sessões existentes.
    • [ ] Arquivos do workspace (memória, configurações) estão presentes.

    Atualizar um Plugin no local

    Atualizações de Plugin no local preservam o mesmo ID de Plugin e as mesmas chaves de configuração, mas podem mover o estado em disco para o layout atual. Guias de atualização específicos de Plugin ficam junto aos seus canais:

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

    Relacionado