Skip to main content
Procurando agendamento? Consulte Automação para escolher o mecanismo adequado. Esta página é o registro de atividades do trabalho em segundo plano, não o agendador.
As tarefas em segundo plano acompanham o trabalho executado fora da sua sessão de conversa principal: execuções de ACP, criações de subagentes, execuções de trabalhos Cron e operações iniciadas pela CLI. As tarefas não substituem sessões, trabalhos Cron nem Heartbeats — elas são o registro de atividades que documenta qual trabalho desacoplado ocorreu, quando ocorreu e se foi bem-sucedido.
Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e conversas interativas normais não criam. Todas as execuções de Cron, criações de ACP, criações de subagentes e comandos de agente da CLI despachados pelo Gateway criam.

​
Resumo

  • As tarefas são registros, não agendadores — Cron e Heartbeat decidem quando o trabalho é executado; as tarefas acompanham o que aconteceu.
  • ACP, subagentes, todos os trabalhos Cron e operações da CLI criam tarefas. Turnos de Heartbeat não criam.
  • Cada tarefa passa por queued → running → terminal (succeeded, failed, timed_out, cancelled ou lost).
  • As tarefas de Cron permanecem ativas enquanto o runtime do Cron ainda controla o trabalho; se o estado do runtime em memória tiver desaparecido, a manutenção de tarefas verificará primeiro o histórico durável de execuções do Cron antes de marcar uma tarefa como perdida.
  • A conclusão é orientada por envio: o trabalho desacoplado pode notificar diretamente ou despertar a sessão/Heartbeat do solicitante quando terminar, portanto loops de consulta de status geralmente são uma abordagem inadequada.
  • Execuções isoladas de Cron e conclusões de subagentes tentam, na medida do possível, limpar as abas/processos do navegador rastreados para suas sessões filhas antes da contabilização final da limpeza.
  • A entrega de Cron isolado suprime respostas intermediárias obsoletas do agente pai enquanto o trabalho dos subagentes descendentes ainda está sendo concluído e dá preferência à saída final dos descendentes quando ela chega antes da entrega.
  • As notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo Heartbeat.
  • openclaw tasks list mostra todas as tarefas; openclaw tasks audit apresenta problemas.
  • Os registros terminais são mantidos por 7 dias (registros lost por 24 horas) e depois removidos automaticamente.

​
Início rápido

​
O que cria uma tarefa

As tarefas de Cron (na sessão principal e isoladas) usam a política de notificação silent — elas criam registros para acompanhamento, mas não geram notificações de tarefa próprias; o Cron controla seu caminho de entrega.As execuções de image_generate, music_generate e video_generate vinculadas à sessão também usam a política de notificação silent. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um despertar interno, para que o agente possa escrever a mensagem de acompanhamento e anexar por conta própria a mídia concluída. O agente solicitante segue seu contrato normal de resposta visível: resposta final automática quando configurada ou message(action="send") mais NO_REPLY quando a sessão exige respostas por meio da ferramenta de mensagens. Se a sessão solicitante não estiver mais ativa ou seu despertar ativo falhar, e o agente de conclusão não incluir parte ou toda a mídia gerada, o OpenClaw enviará, de forma idempotente, uma entrega alternativa direta contendo apenas a mídia ausente para o destino original do canal.
Enquanto uma tarefa de geração de mídia vinculada à sessão ainda estiver ativa, image_generate, music_generate e video_generate protegem contra novas tentativas acidentais: repetir a chamada para o mesmo prompt/solicitação retorna o status da tarefa ativa correspondente em vez de iniciar uma duplicata, enquanto um prompt diferente pode iniciar sua própria tarefa. Use action: "status" quando quiser uma consulta explícita de progresso/status pelo agente.
  • Turnos de Heartbeat — na sessão principal; consulte Heartbeat
  • Turnos normais de conversa interativa
  • Respostas diretas a /command

​
Ciclo de vida da tarefa

As transições ocorrem automaticamente — os eventos do ciclo de vida da execução do agente (início, término e erro) atualizam o status da tarefa; você não precisa gerenciá-lo manualmente. A conclusão da execução do agente é autoritativa para os registros de tarefas ativas. Uma execução desacoplada bem-sucedida é finalizada como succeeded, erros comuns de execução são finalizados como failed, tempos limite são finalizados como timed_out e resultados de cancelamento/aborto são finalizados como cancelled. Depois que uma tarefa se torna terminal, sinais posteriores do ciclo de vida não rebaixam seu estado — uma tarefa cancelada pelo operador ou que já esteja como failed/timed_out/lost permanece assim mesmo que um sinal de sucesso chegue posteriormente. lost considera o runtime:
  • Tarefas de ACP: somente um turno de ACP ativo no processo do Gateway comprova que a execução está ativa; apenas os metadados persistidos da sessão não comprovam isso. A auditoria offline da CLI permanece conservadora e nunca recupera tarefas de ACP.
  • Tarefas de subagentes: a sessão filha subjacente desapareceu do armazenamento do agente de destino (ou contém uma marca de recuperação após reinicialização).
  • Tarefas de Cron: o runtime do Cron deixou de rastrear o trabalho como ativo e o histórico durável de execuções do Cron não mostra um resultado terminal para essa execução. A auditoria offline da CLI não considera autoritativo seu próprio estado vazio do runtime do Cron no processo.
  • Tarefas da CLI: tarefas com um ID de execução/ID de origem usam o contexto ativo da execução, portanto registros remanescentes de sessões filhas ou sessões de conversa não as mantêm ativas depois que a execução controlada pelo Gateway desaparece. Tarefas legadas da CLI sem identidade de execução ainda recorrem à sessão filha. As execuções de openclaw agent vinculadas ao Gateway também são finalizadas com base no resultado da execução, portanto execuções concluídas não permanecem ativas até que o processo de limpeza as marque como lost.

​
Entrega e notificações

Quando uma tarefa atinge um estado terminal, o OpenClaw envia uma notificação. Há dois caminhos de entrega: Entrega direta — se a tarefa tiver um destino de canal (o requesterOrigin), a mensagem de conclusão irá diretamente para esse canal (Discord, Slack, Telegram etc.). As conclusões de tarefas de grupo e canal são encaminhadas pela sessão solicitante para que o agente pai possa escrever a resposta visível. Para conclusões de subagentes, o OpenClaw também preserva o encaminhamento vinculado de thread/tópico quando disponível e pode preencher um to/uma conta ausente usando a rota armazenada da sessão solicitante (lastChannel/lastTo/lastAccountId) antes de desistir da entrega direta. Entrega enfileirada na sessão — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização será enfileirada como um evento do sistema na sessão do solicitante e aparecerá no próximo Heartbeat.
Conclusões de tarefas enfileiradas na sessão acionam imediatamente um despertar de Heartbeat, portanto você vê o resultado rapidamente — não é necessário esperar pelo próximo ciclo agendado do Heartbeat.
Isso significa que o fluxo de trabalho habitual é baseado em envio: inicie o trabalho desacoplado uma vez e deixe o runtime despertar ou notificar você após a conclusão. Consulte o estado da tarefa somente quando precisar depurar, intervir ou realizar uma auditoria explícita.

​
Políticas de notificação

Controle quanto você recebe de informação sobre cada tarefa: Altere a política enquanto uma tarefa estiver em execução:

​
Referência da CLI

Colunas da saída: Tarefa, Tipo, Status, Entrega, Execução, Sessão filha, Resumo. openclaw tasks sem argumentos se comporta como openclaw tasks list.
O token de consulta aceita um ID de tarefa, ID de execução ou chave de sessão. Mostra o registro completo, incluindo tempos, estado da entrega, erro e resumo terminal.
Para tarefas de ACP e subagentes, isso encerra a sessão filha; cancelamentos de ACP e Cron são encaminhados pelo Gateway em execução (tasks.cancel). Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há um identificador separado do runtime filho). O status muda para cancelled e uma notificação de entrega é enviada quando aplicável.
Apresenta problemas operacionais de tarefas e TaskFlows em um único relatório. As constatações também aparecem em openclaw status quando problemas são detectados.Constatações de tarefas:Constatações do TaskFlow:
Use este comando para visualizar ou aplicar a reconciliação, a marcação de limpeza e a remoção de tarefas, do estado do TaskFlow e de linhas obsoletas do registro de sessões de execuções do Cron.A reconciliação considera o runtime:
  • Tarefas ACP exigem um turno ativo no processo do Gateway; tarefas de subagentes verificam sua sessão filha subjacente.
  • Tarefas de subagentes cuja sessão filha tenha uma lápide de recuperação após reinicialização são marcadas como perdidas, em vez de serem tratadas como sessões subjacentes recuperáveis.
  • Tarefas do Cron verificam se o runtime do Cron ainda é proprietário do trabalho e, em seguida, recuperam o status terminal dos logs persistidos de execução do Cron ou do estado do trabalho antes de recorrer a lost. Somente o processo do Gateway é a fonte autoritativa para o conjunto de trabalhos ativos do Cron mantido em memória; a auditoria da CLI em modo offline usa o histórico persistente, mas não marca uma tarefa do Cron como perdida apenas porque esse conjunto local está vazio.
  • Tarefas da CLI com identidade de execução verificam o contexto ativo proprietário da execução, não apenas linhas de sessões filhas ou de sessões de chat.
A limpeza após a conclusão também considera o runtime:
  • Na conclusão de um subagente, o sistema tenta fechar, sem garantia, as abas e os processos de navegador monitorados para a sessão filha antes de prosseguir com a limpeza do anúncio.
  • Na conclusão isolada do Cron, o sistema tenta fechar, sem garantia, as abas e os processos de navegador monitorados para a sessão do Cron antes de encerrar completamente a execução.
  • A entrega isolada do Cron aguarda o acompanhamento de subagentes descendentes quando necessário e suprime textos obsoletos de confirmação do processo pai, em vez de anunciá-los.
  • A entrega da conclusão do subagente usa somente o texto visível mais recente do assistente na sessão filha. A saída de ferramenta ou toolResult não é promovida a texto de resultado da sessão filha. Execuções terminais com falha anunciam o status da falha sem reproduzir o texto de resposta capturado.
  • Falhas de limpeza não ocultam o resultado real da tarefa.
Ao aplicar a manutenção, o OpenClaw também remove linhas obsoletas cron:<jobId>:run:<runId> do registro de sessões com mais de 7 dias, preservando as linhas de trabalhos do Cron atualmente em execução e mantendo intactas as linhas de sessões que não pertencem ao Cron.
O token de consulta do fluxo aceita um ID de fluxo ou uma chave de proprietário. Use estes comandos quando o Fluxo de tarefas orquestrador for o elemento relevante, em vez de um registro individual de tarefa em segundo plano.

​
Quadro de tarefas do chat (/tasks)

Use /tasks em qualquer sessão de chat para ver as tarefas em segundo plano vinculadas a essa sessão. O quadro mostra até cinco tarefas ativas e concluídas recentemente, com runtime, status, duração e detalhes do progresso ou do erro. Quando a sessão atual não tem tarefas vinculadas visíveis, /tasks recorre às contagens de tarefas locais do agente, para que você ainda tenha uma visão geral sem expor detalhes de outras sessões. Para consultar o registro operacional completo, use a CLI: openclaw tasks list.

​
Interface de controle

A Interface de controle da Web tem uma página Tarefas na barra lateral, com tarefas em segundo plano ativas e recentes em tempo real. Use-a para inspecionar o progresso, abrir sessões vinculadas, atualizar o registro ou cancelar tarefas na fila e em execução. Os painéis de chat também têm uma barra recolhível de Tarefas em segundo plano, limitada ao agente do painel: tarefas e subagentes em execução com um controle de interrupção, uma seção de itens concluídos e links para visualizar a transcrição na sessão filha de cada tarefa. Abra-a pelo botão de atividade no cabeçalho do painel (ou pelo botão flutuante de atividade no chat de painel único).

​
Integração de status (pressão das tarefas)

openclaw status inclui uma linha resumida de tarefas:
O resumo contabiliza o trabalho ativo (queued + running), as falhas (failed + timed_out + lost), as constatações da auditoria e o total de registros monitorados; a carga JSON também detalha as contagens por runtime (acp, subagent, cron, cli). Tanto /status quanto a ferramenta session_status usam um instantâneo de tarefas que considera a limpeza: tarefas ativas têm preferência, linhas expiradas ficam ocultas e tarefas terminais aparecem apenas durante uma breve janela recente (5 minutos), com destaque para falhas quando não há trabalho ativo restante. Isso mantém o cartão de status concentrado no que importa agora.

​
Armazenamento e manutenção

​
Onde as tarefas ficam armazenadas

Os registros de tarefas e o estado de entrega persistem no banco de dados de estado SQLite compartilhado do OpenClaw:
Defina OPENCLAW_STATE_DIR para mover toda a raiz de estado (por padrão, ~/.openclaw) para outro local; o caminho do banco de dados compartilhado será movido junto. O registro é carregado na memória no primeiro uso e persiste cada gravação no SQLite, portanto os registros sobrevivem às reinicializações do Gateway. O crescimento do WAL permanece limitado pelo limiar padrão de autocheckpoint do SQLite e por checkpoints PASSIVE periódicos; checkpoints durante o desligamento e a manutenção explícita usam TRUNCATE, para que encerramentos normais recuperem o espaço do WAL sem fazer o processo de limpeza em segundo plano aguardar leitores ativos. Armazenamentos auxiliares legados de instalações mais antigas (tasks/runs.sqlite, flows/registry.sqlite) são importados para o banco de dados compartilhado por openclaw doctor.

​
Manutenção automática

Um processo de limpeza é executado a cada 60 segundos (a primeira execução ocorre cerca de 5 segundos após o início do Gateway) e realiza quatro ações:
1

Reconciliation

Verifica se tarefas ativas ainda têm suporte autoritativo do runtime. Tarefas ACP exigem um turno ativo no processo, tarefas de subagentes usam o estado da sessão filha, tarefas do Cron usam a propriedade do trabalho ativo junto com o histórico persistente de execução e tarefas da CLI com identidade de execução usam o contexto proprietário da execução. Se o estado subjacente desaparecer por mais de 5 minutos (30 minutos para tarefas nativas de subagentes sem filhos), a tarefa será marcada como lost.
2

ACP session repair

Fecha sessões ACP terminais ou órfãs, de execução única e pertencentes ao processo pai, e fecha sessões ACP persistentes obsoletas, terminais ou órfãs, somente quando não houver mais nenhum vínculo de conversa ativo.
3

Cleanup stamping

Define um carimbo de data/hora cleanupAfter nas tarefas terminais (horário terminal + janela de retenção). Durante a retenção, tarefas perdidas ainda aparecem como avisos na auditoria; após a expiração de cleanupAfter ou quando os metadados de limpeza estão ausentes, elas se tornam erros.
4

Pruning

Exclui registros que ultrapassaram sua data cleanupAfter.
Retenção: os registros de tarefas terminais são mantidos por 7 dias (registros lost por 24 horas) e depois removidos automaticamente. Nenhuma configuração é necessária.

​
Como as tarefas se relacionam com outros sistemas

O Fluxo de tarefas é a camada de orquestração de fluxos acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de seu ciclo de vida usando modos de sincronização gerenciados ou espelhados. Use openclaw tasks para inspecionar registros individuais de tarefas e openclaw tasks flow para inspecionar o fluxo orquestrador.
As definições de trabalhos do Cron, o estado de execução do runtime e o histórico de execuções ficam no banco de dados de estado SQLite compartilhado do OpenClaw. Toda execução do Cron cria um registro de tarefa — tanto na sessão principal quanto de forma isolada — com a política de notificação silent, para que as execuções do Cron sejam monitoradas sem gerar suas próprias notificações de tarefa.Consulte Trabalhos do Cron.
Execuções de Heartbeat são turnos da sessão principal — elas não criam registros de tarefas. Quando uma tarefa é concluída, ela pode acionar o despertar de um Heartbeat para que você veja o resultado rapidamente.Consulte Heartbeat.
Uma tarefa pode fazer referência a uma childSessionKey (onde o trabalho é executado) e a uma requesterSessionKey (quem o iniciou). Seu agentId identifica o agente que executa o trabalho, enquanto os campos de solicitante e proprietário preservam o contexto de inicialização e controle. Sessões são o contexto da conversa; tarefas são o monitoramento de atividades sobre esse contexto.
O runId de uma tarefa é vinculado à execução do agente que realiza o trabalho. Eventos do ciclo de vida do agente (início, término e erro) atualizam automaticamente o status da tarefa — não é necessário gerenciar o ciclo de vida manualmente.

​
Relacionados