OpenClaw no Docker Perde Configuração? Confira os Volumes

Se o OpenClaw perde configuração ao recriar o container Docker, confira primeiro os mounts: os dados precisam estar fora da camada descartável do container, no diretório ou volume correto. No Compose oficial atual, o estado fica em /home/node/.openclaw, o workspace em /home/node/.openclaw/workspace e há um mount separado para segredos de perfis de autenticação. Um diretório vazio montado no lugar do antigo pode parecer perda de dados mesmo quando a cópia original ainda existe no host.

Este guia resolve um problema específico: o assistente funcionava, mas voltou ao onboarding, perdeu arquivos ou pediu nova autenticação depois de uma recriação. Não é um tutorial de instalação nem uma receita para apagar e começar de novo. Os caminhos abaixo foram conferidos no Compose oficial e na documentação de Docker do OpenClaw em 7 de outubro de 2026. Confira também os arquivos da versão que você instalou: o branch main pode mudar.

Diagnóstico rápido: o que realmente desapareceu?

Uma sessão revogada pelo provedor não volta apenas restaurando arquivos. Já um workspace vazio pode ser simplesmente o workspace errado. Separe esses casos antes de reinstalar.

Container, imagem e dados persistentes não são a mesma coisa

A imagem contém o software. O container é uma instância em execução, com uma camada gravável própria. O bind mount liga um diretório do host a um caminho interno; o volume nomeado é armazenamento administrado pelo Docker.

Recriar o container substitui sua camada gravável. Dados guardados exclusivamente nela podem desaparecer quando o container antigo é removido. Os bind mounts e volumes corretamente reutilizados permitem manter dados entre recriações.

Mas persistência não é backup. Se o agente apaga um arquivo no diretório montado, a exclusão também chega ao host. Se um volume é removido, sua existência anterior não garante recuperação. Mantenha uma cópia separada e teste a restauração, como explica o guia de backup do OpenClaw.

1. Use exatamente o mesmo projeto Compose

Abra o terminal no host onde o Docker executa e entre no diretório da instalação. Os exemplos usam os serviços oficiais openclaw-gateway e openclaw-cli, com Docker Compose v2:

docker compose version
docker compose ps -a

Se sua instalação usa arquivos adicionais, repita os mesmos argumentos em todos os comandos deste guia. Por exemplo, quando há um override próprio e um arquivo extra gerado pelo setup:

docker compose -f docker-compose.yml \
  -f docker-compose.override.yml \
  -f docker-compose.extra.yml ps -a

Inclua somente arquivos que realmente existam e pertençam à sua instalação. Não omita um overlay que define volumes ou diretórios. Da mesma forma, preserve o nome de projeto se você usa -p ou COMPOSE_PROJECT_NAME: trocar esse nome pode selecionar volumes nomeados diferentes.

Não execute novamente o setup apenas para descobrir onde estão os dados. A documentação atual alerta que o setup pode reescrever .env a partir do ambiente do shell e dos valores padrão. Primeiro inspecione a instalação existente.

2. Veja quais diretórios o container realmente montou

Para obter o ID e inspecionar apenas os mounts, sem imprimir todas as variáveis do container:

CID=$(docker compose ps -a -q openclaw-gateway)

Confirme que a variável recebeu exatamente um ID. Se ficou vazia, você pode estar no projeto errado ou o container já foi removido. Se houver mais de uma instância, identifique a correta antes de prosseguir.

docker inspect "$CID" --format \
  '{{range .Mounts}}{{printf "%s | %s -> %s | RW=%t\n" .Type .Source .Destination .RW}}{{end}}'

O resultado mostra:

• Type: bind ou volume, entre outros tipos;
• Source: origem no host ou localização do volume;
• Destination: caminho dentro do container;
• RW: se o mount permite escrita.

Para instalações personalizadas, compare esses destinos com o caminho de estado e workspace efetivamente configurado. Um mount em /app/data não preserva automaticamente arquivos gravados em /home/node/.openclaw.

Evite compartilhar a saída completa de docker inspect ou docker compose config: elas podem revelar credenciais. Até caminhos e nomes de projetos podem conter informações privadas. Ao pedir ajuda, compartilhe apenas os campos necessários, com dados sensíveis ocultados.

3. Compare estado, workspace e segredos separadamente

O Compose oficial consultado usa os seguintes destinos nos serviços Gateway e CLI:

No arquivo atual, o destino de configuração é fixado em /home/node/.openclaw/openclaw.json. As variáveis usadas para selecionar diretórios do host não significam que o processo deva procurar esses mesmos caminhos dentro do container.

Por exemplo, um caminho /Users/ana/... pode fazer sentido no macOS anfitrião, mas não como caminho de trabalho do processo Linux interno. Essa distinção é importante em Compose personalizado que importa .env para o ambiente do container.

Há outro detalhe: o workspace tem um mount próprio dentro do diretório de estado. Esse mount específico cobre o conteúdo que existiria naquele subdiretório do mount pai. Portanto, encontrar arquivos em workspace dentro da pasta de estado no host não prova que o agente os está vendo. Confira também a origem do mount de workspace.

Se o Gateway e a CLI usam origens diferentes, o onboarding pode escrever em uma pasta enquanto o Gateway lê outra. Compare ambos os serviços no Compose da sua versão.

4. Procure a cópia original antes de criar dados novos

Consulte os caminhos definidos na sua instalação e verifique se os diretórios esperados existem. Veja nomes, tamanhos e datas dos arquivos localmente; não publique o conteúdo de openclaw.json, credenciais ou sessões.

As perguntas úteis são:

1. A pasta montada agora foi criada justamente na data da recriação?
2. Existe uma pasta antiga usada por outra conta de usuário?
3. O workspace está em outro disco ou diretório?
4. O armazenamento externo estava montado quando o container iniciou?
5. Algum override trocou um bind mount por volume nomeado?

Não copie arquivos por cima da nova pasta ainda. Primeiro preserve uma cópia tanto do estado antigo quanto do atual. Assim você não perde mensagens ou alterações recentes ao tentar recuperar o ambiente anterior.

Se os dados estavam apenas na camada gravável de um container antigo que ainda existe, não o remova. Avalie copiar os arquivos necessários com docker cp a partir dele. Se o container foi removido e não havia mount ou backup, corrigir o Compose evita uma nova perda, mas não recria os dados anteriores.

5. Verifique permissões sem recorrer a chmod 777

Veja os logs recentes:

docker compose logs --tail=100 openclaw-gateway

Se o serviço está em execução, confira a identidade do processo e a capacidade de escrita nos caminhos principais:

docker compose exec openclaw-gateway sh -lc '
  id
  for p in /home/node/.openclaw /home/node/.openclaw/workspace; do
    if test -w "$p"; then
      printf "gravável: %s\n" "$p"
    else
      printf "sem escrita: %s\n" "$p"
    fi
  done
'

Se o container não inicia, exec não funcionará; use os logs e examine as permissões da origem no host. O teste de diretório também não garante permissão em cada arquivo existente: um arquivo de configuração com proprietário diferente ainda pode falhar.

Ajuste propriedade ou permissões somente nos diretórios identificados, conforme UID/GID efetivo, sistema de arquivos e modo de execução do Docker. Docker rootless, compartilhamentos de rede e políticas como SELinux podem exigir tratamento específico.

Não aplique chmod -R 777 nem chown em todo o diretório pessoal. Isso amplia acesso a segredos e pode afetar arquivos de outros serviços. O guia de segurança complementa os cuidados de acesso.

6. Corrija a origem, recrie e faça um teste de persistência

Depois de localizar os dados e fazer backup, pare o Gateway para evitar escrita durante a recuperação:

docker compose stop openclaw-gateway

A parada interrompe o atendimento: faça em uma janela de manutenção. Corrija no Compose ou .env a origem de cada mount que estiver errada, preservando os destinos internos esperados pela sua versão. Se for restaurar um backup, use o procedimento adequado ao tipo de armazenamento e mantenha a cópia atual separada.

Recrie o serviço com os mesmos arquivos e projeto:

docker compose up -d --force-recreate openclaw-gateway
docker compose ps
docker compose logs --tail=100 openclaw-gateway

Esse comando recria o container, não constitui uma atualização de imagem. Para atualizar software, siga o fluxo de imagem da sua instalação e o guia de atualização sem perda de configuração.

Para verificar a persistência, crie um arquivo inofensivo no workspace pelo host, depois de confirmar sua origem. Confira se ele aparece no container; recrie novamente em manutenção e confira se continua lá. Não use tokens ou dados de clientes no teste.

Complete a validação com um roteiro funcional:

• abra o dashboard do OpenClaw;
• confira a configuração esperada sem expor credenciais;
• envie uma mensagem pelo canal autorizado;
• confirme que um arquivo de contexto conhecido está disponível;
• verifique uma automação existente antes de habilitar novas tarefas.

Não use docker compose down -v como tentativa genérica de conserto. A opção pode remover volumes nomeados declarados e volumes anônimos anexados; bind mounts têm comportamento diferente. Também não rode limpeza de volumes sem inventário e backup.

Checklist para a próxima recriação

• Registrei os arquivos Compose e o nome do projeto utilizados.
• Identifiquei as origens reais de estado, workspace e segredos necessários.
• Gateway e CLI acessam o mesmo conjunto de dados.
• Fiz backup fora da origem, com proteção adequada para credenciais.
• Verifiquei permissões com a identidade efetiva do container.
• Testei a persistência depois de recriar, não só depois de reiniciar.
• Confirmei uma mensagem real e uma leitura de contexto.

Se o problema restante for autenticação no WhatsApp, consulte WhatsApp desconectando. Se o container reinicia antes de carregar os dados, separe esse diagnóstico do problema de persistência e confira o troubleshooting de crash no Docker.

Perguntas frequentes

Reiniciar o container apaga a configuração do OpenClaw?

Um reinício normal não substitui a camada gravável do container. A recriação substitui o container e exige persistência externa para manter os dados. Se a configuração muda até num reinício simples, investigue scripts de inicialização, caminhos selecionados e permissões, além dos mounts.

Basta montar o workspace para preservar tudo?

Não. O workspace preserva seus arquivos, mas configuração, estado e segredos necessários podem estar em outros caminhos. O Compose oficial atual possui mounts separados para estado, workspace e segredos de perfis de autenticação. Confira também variáveis usadas por integrações.

Por que os arquivos existem no host, mas o agente não os vê?

O container pode montar outra origem, um mount de workspace pode cobrir o subdiretório do estado ou o processo pode usar um caminho diferente. Compare Source, Destination e a configuração efetiva antes de copiar ou excluir arquivos.

Um volume Docker substitui o backup?

Não. Um volume permite persistência entre containers, mas não protege sozinho contra exclusão, corrupção ou perda do host. Backup precisa de uma cópia separada, proteção para segredos e teste de restauração.

Preciso escanear novamente o QR code do WhatsApp após recriar?

Não deve ser uma conclusão automática. Primeiro verifique se o estado e as credenciais foram preservados e se o Gateway consegue acessá-los. Se a sessão foi revogada ou o estado necessário realmente se perdeu, uma nova autenticação pode ser necessária.

Posso corrigir o problema reinstalando o OpenClaw?

Reinstalar o software não corrige uma origem de mount errada nem recupera arquivos apagados. Identifique os dados, preserve uma cópia e ajuste o armazenamento primeiro. Para uma instalação nova, use a documentação oficial e a página de instalação.