Recuperação após reinicialização

Reiniciar o Gateway não causa perda do estado do agente. Conversas, transcrições, tarefas agendadas, registros de tarefas em segundo plano e mensagens de saída na fila ficam armazenados em disco, e o trabalho interrompido durante um turno é detectado e retomado automaticamente depois que o Gateway volta a funcionar. Nenhuma intervenção manual é necessária e não há nada para configurar: a recuperação está sempre ativada.

Esta página descreve o que sobrevive a uma reinicialização, como o trabalho interrompido é detectado e como funciona a retomada automática.

O que sobrevive a uma reinicialização

Reinicializações normais aguardam a conclusão primeiro

Uma reinicialização solicitada (openclaw gateway restart, uma alteração de configuração que exige uma reinicialização ou uma atualização do Gateway) não encerra imediatamente o trabalho em andamento. O Gateway deixa de aceitar novos trabalhos e aguarda a conclusão dos turnos ativos dos agentes e das tarefas em segundo plano, até o limite de tempo de esvaziamento (5 minutos por padrão). Portanto, a maioria das reinicializações não interrompe nenhum trabalho.

Somente o trabalho que não consegue terminar dentro do limite de esvaziamento (ou qualquer execução interrompida por uma reinicialização forçada ou falha) é abortado — e, antes disso, cada sessão afetada é marcada para recuperação.

Como o trabalho interrompido é detectado

Dois mecanismos complementares marcam as sessões cujo turno não foi concluído:

• No encerramento: durante o esvaziamento para reinicialização, cada sessão com uma execução ativa recebe um marcador de recuperação no armazenamento de sessões antes que a execução seja abortada.
• Na inicialização: o Gateway verifica os armazenamentos de sessões em busca de sessões que ainda declaram estar em execução, mas não têm um proprietário ativo no novo processo. Isso detecta falhas graves e encerramentos nos quais nenhum código de desligamento foi executado. Arquivos obsoletos de bloqueio de transcrição são removidos ao mesmo tempo.

Retomada automática

Alguns segundos após a inicialização, o Gateway despacha novamente cada sessão marcada com uma mensagem sintética do sistema informando ao agente que seu turno anterior foi interrompido por uma reinicialização e que ele deve continuar a partir da transcrição existente. Se uma resposta final já tiver sido produzida, mas não entregue, o texto dela será incluído para que o agente possa entregá-la em vez de refazer o trabalho. A recuperação faz até 3 tentativas com espera exponencial.

Antes de retomar, o Gateway verifica se é seguro continuar a partir do fim da transcrição. Caso não seja (por exemplo, se o turno tiver terminado em uma aprovação pendente obsoleta), a sessão não será executada novamente às cegas; em vez disso, o agente publicará um breve aviso solicitando que o usuário reenvie a última solicitação.

O OpenClaw também pode reconstruir trabalhos somente leitura do Modo de Código que tenham sido interrompidos. O Modo de Código marca essas execuções como seguras para reinicialização e rejeita ferramentas de catálogo ou namespaces de plugins que causem efeitos colaterais antes que sejam executados. Se uma reinicialização ocorrer no controle wait, o novo Gateway reconstruirá o turno a partir de sua transcrição e obrigará a execução reconstruída a permanecer segura para reinicialização, mesmo que o modelo omita ou desative esse sinalizador. O host restringe todo o turno reconstruído às ferramentas principais auditadas somente leitura e às ferramentas de plugins explicitamente seguras para repetição, inclusive quando o Modo de Código é desativado após a reinicialização. Trabalhos com efeitos colaterais continuam protegidos pelo aviso de reenvio, em vez de correr o risco de uma gravação duplicada.

Subagentes

As execuções de subagentes são armazenadas no banco de dados de estado compartilhado SQLite, portanto o registro de subagentes sobrevive ao processo. Na inicialização, o registro é restaurado e as sessões interrompidas de subagentes são retomadas com o contexto original da tarefa. Duas proteções se aplicam:

• Execuções interrompidas há mais de 2 horas são finalizadas em vez de retomadas, para que um Gateway que tenha ficado inativo durante a noite não reative trabalhos obsoletos.
• Uma sessão que falha repetidamente na recuperação recebe uma marca permanente de travamento para que a recuperação não entre em um ciclo infinito.

Tarefas em segundo plano

O registro de tarefas em segundo plano usa SQLite e é reconciliado na inicialização e em intervalos periódicos: resultados duráveis registrados por execuções concluídas são recuperados, e execuções cujo processo proprietário desapareceu são marcadas como perdidas após um período de carência, em vez de ficarem bloqueadas indefinidamente.

Reinicializações solicitadas pelo agente

Quando o próprio agente aciona uma reinicialização (ao aplicar uma alteração de configuração, atualizar o Gateway ou fazer uma solicitação explícita de reinicialização), uma sentinela de reinicialização é gravada no SQLite antes de o processo ser encerrado. Após a inicialização, o Gateway publica o resultado de volta no chat de origem e despacha um turno único de continuação para que o agente retome exatamente de onde parou, no mesmo canal e tópico.

Proteções e observabilidade

• Disjuntor de ciclo de falhas: 3 inicializações anormais em um intervalo de 5 minutos acionam um disjuntor que impede a inicialização automática de serviços auxiliares na próxima inicialização, para que um Gateway com falhas não amplifique o problema. Ele se recupera quando o intervalo de inicializações anormais termina.
• Métricas: a atividade de recuperação é exportada pelo Prometheus como openclaw_session_recovery_total e openclaw_session_recovery_age_seconds.
• Logs: as decisões de recuperação são registradas nos subsistemas main-session-restart-recovery e subagent-interrupted-resume.

O que não é retomado

• Sessões excluídas da recuperação da sessão principal porque outro proprietário já cuida delas: sessões de subagentes (recuperação de subagentes), sessões cron (o agendador as executa novamente conforme o agendamento) e sessões gerenciadas por ACP (o IDE ou cliente conectado é responsável pela retomada).
• Sessões cujo fim da transcrição não permite uma continuação segura; elas recebem o aviso de reenvio descrito acima, em vez de uma nova execução silenciosa.
• Trabalho que nunca foi aceito: mensagens recebidas durante o período de esvaziamento são rejeitadas com um erro explícito de reinicialização, em vez de serem silenciosamente adicionadas à fila de um processo que está sendo encerrado.