Pular para o conteúdo principal
Procurando agendamento? Consulte Automação para escolher o mecanismo certo. Esta página é o registro de atividades do trabalho em segundo plano, não o agendador.
Tarefas em segundo plano rastreiam trabalho executado fora da sua sessão de conversa principal: execuções ACP, criações de subagentes, execuções isoladas de trabalhos cron e operações iniciadas pela CLI. Tarefas não substituem sessões, trabalhos cron nem Heartbeats - elas são o registro de atividades que registra qual trabalho destacado aconteceu, quando 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 cron, criações ACP, criações de subagentes e comandos de agente pela CLI criam.

​
Resumo

  • Tarefas são registros, não agendadores - cron e Heartbeat decidem quando o trabalho é executado; tarefas rastreiam 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).
  • Tarefas cron permanecem ativas enquanto o runtime cron ainda possui o trabalho; se o estado do runtime em memória desapareceu, a manutenção de tarefas primeiro verifica o histórico durável de execuções cron antes de marcar uma tarefa como perdida.
  • A conclusão é orientada por push: trabalho destacado pode notificar diretamente ou acordar a sessão/Heartbeat solicitante quando termina, então loops de sondagem de status geralmente têm o formato errado.
  • Execuções cron isoladas e conclusões de subagentes fazem a melhor tentativa de limpar abas/processos de navegador rastreados para sua sessão filha antes da escrituração final de limpeza.
  • A entrega de cron isolado suprime respostas provisórias obsoletas do pai enquanto o trabalho de subagentes descendentes ainda está escoando, e prefere a saída final do descendente quando ela chega antes da entrega.
  • 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 expõe problemas.
  • Registros terminais são mantidos por 7 dias e depois removidos automaticamente.

​
Início rápido

# List all tasks (newest first)
openclaw tasks list

# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running

​
O que cria uma tarefa

OrigemTipo de runtimeQuando um registro de tarefa é criadoPolítica padrão de notificação
Execuções ACP em segundo planoacpCriação de uma sessão ACP filhadone_only
Orquestração de subagentessubagentCriação de um subagente via sessions_spawndone_only
Trabalhos cron (todos os tipos)cronToda execução cron (sessão principal e isolada)silent
Operações da CLIcliComandos openclaw agent executados pelo Gatewaysilent
Trabalhos de mídia do agentecliExecuções image_generate/music_generate/video_generate apoiadas por sessãosilent
Tarefas cron da sessão principal usam a política de notificação silent por padrão - elas criam registros para rastreamento, mas não geram notificações. Tarefas cron isoladas também usam silent por padrão, mas são mais visíveis porque são executadas em sua própria sessão.Execuções image_generate, music_generate e video_generate apoiadas por 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 wake interno para que o agente possa escrever a mensagem de acompanhamento e anexar a mídia finalizada por conta própria. 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 ferramenta de mensagem. Se a sessão solicitante não estiver mais ativa ou seu wake ativo falhar, e o agente de conclusão perder parte ou toda a mídia gerada, o OpenClaw envia um fallback direto idempotente apenas com a mídia ausente para o alvo original do canal.
Enquanto uma tarefa de geração de mídia apoiada por sessão ainda está ativa, as ferramentas de mídia também atuam como proteções contra novas tentativas acidentais. Chamadas repetidas de image_generate para o mesmo prompt retornam o status da tarefa ativa correspondente, enquanto um prompt de imagem distinto pode iniciar sua própria tarefa. Chamadas music_generate e video_generate ainda retornam o status da tarefa ativa dessa sessão em vez de iniciar uma segunda geração concorrente. Use action: "status" quando quiser uma consulta explícita de progresso/status pelo lado do agente.
  • Turnos de Heartbeat - sessão principal; consulte Heartbeat
  • Turnos normais de conversa interativa
  • Respostas diretas a /command

​
Ciclo de vida da tarefa

StatusO que significa
queuedCriada, aguardando o agente iniciar
runningO turno do agente está em execução ativa
succeededConcluída com sucesso
failedConcluída com um erro
timed_outExcedeu o tempo limite configurado
cancelledInterrompida pelo operador via openclaw tasks cancel
lostO runtime perdeu o estado de apoio autoritativo após um período de carência de 5 minutos
Transições acontecem automaticamente - quando a execução de agente associada termina, o status da tarefa é atualizado para corresponder. A conclusão da execução de agente é autoritativa para registros de tarefas ativas. Uma execução destacada bem-sucedida finaliza como succeeded, erros comuns de execução finalizam como failed, e resultados de tempo limite ou aborto finalizam como timed_out. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte, como failed, timed_out ou lost, um sinal posterior de sucesso não rebaixa esse status terminal. lost reconhece o runtime:
  • Tarefas ACP: metadados da sessão ACP filha de apoio desapareceram.
  • Tarefas de subagente: a sessão filha de apoio desapareceu do armazenamento do agente de destino.
  • Tarefas cron: o runtime cron não rastreia mais o trabalho como ativo e o histórico durável de execuções cron não mostra um resultado terminal para essa execução. A auditoria offline pela CLI não trata seu próprio estado vazio de runtime cron em processo como autoridade.
  • Tarefas CLI: tarefas com um id de execução/id de origem usam o contexto de execução ao vivo, então linhas remanescentes de sessão filha ou sessão de chat não as mantêm ativas depois que a execução pertencente ao Gateway desaparece. Tarefas CLI legadas sem identidade de execução ainda recaem para a sessão filha. Execuções openclaw agent apoiadas pelo Gateway também finalizam a partir de seu resultado de execução, então execuções concluídas não permanecem ativas até que o varredor as marque como lost.

​
Entrega e notificações

Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega: Entrega direta - se a tarefa tem um alvo de canal (o requesterOrigin), a mensagem de conclusão vai direto para esse canal (Telegram, Discord, Slack etc.). Conclusões de tarefas em grupos e canais, em vez disso, são roteadas 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 roteamento de thread/tópico vinculado quando disponível e pode preencher um to / conta ausente a partir da 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 é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo Heartbeat.
A conclusão da tarefa aciona um wake imediato de Heartbeat para que você veja o resultado rapidamente - você não precisa esperar pelo próximo tique de Heartbeat agendado.
Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho destacado uma vez e depois deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa por sondagem somente quando precisar depurar, intervir ou executar uma auditoria explícita.

​
Políticas de notificação

Controle o quanto você ouve sobre cada tarefa:
PolíticaO que é entregue
done_only (padrão)Apenas estado terminal (succeeded, failed etc.) - este é o padrão
state_changesToda transição de estado e atualização de progresso
silentNada
Altere a política enquanto uma tarefa está em execução: 
openclaw tasks notify <lookup> state_changes

​
Referência da CLI

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID da execução, Sessão filha, Resumo.
openclaw tasks show <lookup>
O token de consulta aceita um ID de tarefa, ID de execução ou chave de sessão. Mostra o registro completo, incluindo temporização, estado de entrega, erro e resumo terminal.
openclaw tasks cancel <lookup>
Para tarefas ACP e de subagentes, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há um identificador separado de runtime filho). O status transita para cancelled e uma notificação de entrega é enviada quando aplicável.
openclaw tasks notify <lookup> <done_only|state_changes|silent>

openclaw tasks audit [--json]
Expõe problemas operacionais. Achados também aparecem em openclaw status quando problemas são detectados.
AchadoSeveridadeGatilho
stale_queuedwarnEm fila há mais de 10 minutos
stale_runningerrorEm execução há mais de 30 minutos
lostwarn/errorA propriedade da tarefa respaldada pelo runtime desapareceu; tarefas perdidas retidas avisam até cleanupAfter, depois viram erros
delivery_failedwarnA entrega falhou e a política de notificação não é silent
missing_cleanupwarnTarefa terminal sem timestamp de limpeza
inconsistent_timestampswarnViolação de linha do tempo (por exemplo, terminou antes de começar)
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
Use isto para pré-visualizar ou aplicar reconciliação, marcação de limpeza e remoção de tarefas, estado do Task Flow e linhas obsoletas do registro de sessões de execuções de cron.A reconciliação é ciente do runtime:
  • Tarefas ACP/subagente verificam a sessão filha que as respalda.
  • Tarefas de subagente cuja sessão filha tem uma lápide de recuperação de reinicialização são marcadas como perdidas em vez de serem tratadas como sessões de respaldo recuperáveis.
  • Tarefas Cron verificam se o runtime de cron ainda possui o job, depois recuperam o status terminal a partir de logs de execução de cron/estado de job persistidos antes de recorrer a lost. Somente o processo do Gateway é autoritativo para o conjunto em memória de jobs ativos de cron; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa cron como perdida apenas porque esse Set local está vazio.
  • Tarefas CLI com identidade de execução verificam o contexto de execução ao vivo proprietário, não apenas linhas de sessão filha ou sessão de chat.
A limpeza de conclusão também é ciente do runtime:
  • A conclusão de subagente fecha, em melhor esforço, abas/processos de navegador rastreados para a sessão filha antes que a limpeza do anúncio continue.
  • A conclusão de cron isolado fecha, em melhor esforço, abas/processos de navegador rastreados para a sessão de cron antes que a execução seja totalmente encerrada.
  • A entrega de cron isolado aguarda o acompanhamento de subagentes descendentes quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
  • A entrega de conclusão de subagente usa apenas o texto visível mais recente do assistente da criança. Saída de ferramenta/toolResult não é promovida para texto de resultado da criança. Execuções terminais com falha anunciam o status de falha sem reproduzir o texto de resposta capturado.
  • Falhas de limpeza não mascaram o resultado real da tarefa.
Ao aplicar manutenção, o OpenClaw também remove linhas obsoletas do registro de sessões cron:<jobId>:run:<uuid> com mais de 7 dias, preservando linhas de jobs cron atualmente em execução e deixando linhas de sessão que não são cron intocadas.
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
Use isto quando o Task Flow orquestrador for o que importa para você, 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 tarefas em segundo plano vinculadas a essa sessão. O quadro mostra tarefas ativas e concluídas recentemente com runtime, status, tempo e progresso ou detalhes de erro. Quando a sessão atual não tem tarefas vinculadas visíveis, /tasks recorre a contagens de tarefas locais do agente para que você ainda tenha uma visão geral sem vazar detalhes de outras sessões. Para o livro-razão completo do operador, use a CLI: openclaw tasks list.

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

openclaw status inclui um resumo de tarefas de relance: 
Tasks: 3 queued · 2 running · 1 issues
O resumo informa:
  • active - contagem de queued + running
  • failures - contagem de failed + timed_out + lost
  • byRuntime - detalhamento por acp, subagent, cron, cli
Tanto /status quanto a ferramenta session_status usam um snapshot de tarefas ciente de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas são ocultadas, e falhas recentes só aparecem quando não resta nenhum trabalho ativo. Isso mantém o cartão de status focado no que importa agora.

​
Armazenamento e manutenção

​
Onde as tarefas ficam

Registros de tarefas persistem no SQLite em: 
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
O registro é carregado na memória na inicialização do gateway e sincroniza gravações no SQLite para durabilidade entre reinicializações. O Gateway mantém o log write-ahead do SQLite limitado usando o limite padrão de autocheckpoint do SQLite mais checkpoints PASSIVE periódicos. Desligamento e checkpoints explícitos de manutenção ainda usam TRUNCATE para que fechamentos normais possam recuperar espaço de WAL sem fazer o varredor em segundo plano esperar por leitores ativos.

​
Manutenção automática

Um varredor roda a cada 60 segundos e cuida de quatro coisas:
1

Reconciliação

Verifica se tarefas ativas ainda têm respaldo autoritativo do runtime. Tarefas ACP/subagente usam estado de sessão filha, tarefas cron usam propriedade de job ativo, e tarefas CLI com identidade de execução usam o contexto de execução proprietário. Se esse estado de respaldo desaparecer por mais de 5 minutos, a tarefa é marcada como lost.
2

Reparo de sessão ACP

Fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs somente quando não resta nenhum vínculo de conversa ativo.
3

Marcação de limpeza

Define um timestamp cleanupAfter em tarefas terminais (endedAt + 7 dias). Durante a retenção, tarefas perdidas ainda aparecem na auditoria como avisos; depois que cleanupAfter expira ou quando metadados de limpeza estão ausentes, elas são erros.
4

Remoção

Exclui registros após a data cleanupAfter.
Retenção: registros de tarefas terminais são mantidos por 7 dias e então removidos automaticamente. Nenhuma configuração necessária.

​
Como as tarefas se relacionam com outros sistemas

Task Flow é 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.Consulte Task Flow para detalhes.
Definições de jobs Cron, estado de execução em runtime e histórico de execuções ficam no banco de dados SQLite de estado compartilhado do OpenClaw. Toda execução de cron cria um registro de tarefa - tanto de sessão principal quanto isolada. Tarefas cron de sessão principal usam a política de notificação silent por padrão para que sejam rastreadas sem gerar notificações.Consulte Cron Jobs.
Execuções de Heartbeat são turnos de sessão principal - elas não criam registros de tarefas. Quando uma tarefa é concluída, ela pode acionar um despertar de heartbeat para que você veja o resultado prontamente.Consulte Heartbeat.
Uma tarefa pode referenciar um childSessionKey (onde o trabalho roda) e um requesterSessionKey (quem a iniciou). Seu agentId identifica o agente que executa o trabalho, enquanto os campos de solicitante e proprietário preservam o contexto de lançamento e controle. Sessões são contexto de conversa; tarefas são rastreamento de atividade por cima disso.
O runId de uma tarefa se vincula à execução do agente que realiza o trabalho. Eventos de ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa - você não precisa gerenciar o ciclo de vida manualmente.

​
Relacionado