Tarefas em segundo plano

Tarefas em segundo plano rastreiam trabalho que roda 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 livro-razão de atividades que registra qual trabalho destacado aconteceu, quando e se foi bem-sucedido.

# TL;DR

• Tarefas são registros, não agendadores - Cron e Heartbeat decidem quando o trabalho roda, 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 do Cron ainda possui o trabalho; se o estado de 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 consulta de status geralmente têm o formato errado.
• Execuções Cron isoladas e conclusões de subagentes fazem limpeza de melhor esforço das abas/processos de navegador rastreados para sua sessão filha antes da escrituração final de limpeza.
• A entrega Cron isolada suprime respostas intermediárias obsoletas do pai enquanto trabalho de subagente descendente ainda está drenando, e prefere a saída final 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 podados 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

# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>

# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>

# Change notification policy for a task
openclaw tasks notify <lookup> state_changes

# Run a health audit
openclaw tasks audit

# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply

# Inspect TaskFlow state
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>

# O que cria uma tarefa

# Ciclo de vida da tarefa

stateDiagram-v2
    [*] --> queued
    queued --> running : agent starts
    running --> succeeded : completes ok
    running --> failed : error
    running --> timed_out : timeout exceeded
    running --> cancelled : operator cancels
    queued --> lost : session gone > 5 min
    running --> lost : session gone > 5 min

As transições acontecem automaticamente - quando a execução do agente associada termina, o status da tarefa é atualizado para corresponder.

A conclusão da execução do agente é autoritativa para registros de tarefa ativos. Uma execução destacada bem-sucedida finaliza como succeeded, erros comuns de execução finalizam como failed, e resultados de timeout ou aborto finalizam como timed_out. Se um operador já cancelou a tarefa, ou se 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 é consciente do runtime:

• Tarefas ACP: os 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 do 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. 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 ativo, então linhas persistentes de sessão filha ou sessão de chat não as mantêm vivas depois que a execução pertencente ao Gateway desaparece. Tarefas CLI legadas sem identidade de execução ainda recorrem à 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 ficam 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 destino de canal (o requesterOrigin), a mensagem de conclusão vai direto para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagente, 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.

Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho destacado uma vez e deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa apenas quando precisar de depuração, intervenção ou uma auditoria explícita.

# Políticas de notificação

Controle quanto você ouve sobre cada tarefa:

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]

openclaw tasks show <lookup>

openclaw tasks cancel <lookup>

openclaw tasks notify <lookup> <done_only|state_changes|silent>

openclaw tasks audit [--json]

openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]

openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>

# 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 detalhes de progresso ou 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 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 em uma olhada:

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 priorizadas, linhas concluídas obsoletas são ocultadas, e falhas recentes só aparecem quando nenhum trabalho ativo resta. Isso mantém o cartão de status focado no que importa agora.

# Armazenamento e manutenção

# Onde as tarefas ficam

Registros de tarefa persistem no SQLite em:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

O registro é carregado em memória no início do gateway e sincroniza gravações com o 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 TRUNCATE periódicos e no encerramento.

# Manutenção automática

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

# Como as tarefas se relacionam com outros sistemas

# Relacionado

• Automação e Tarefas - todos os mecanismos de automação em uma olhada
• CLI: Tarefas - referência de comandos da CLI
• Heartbeat - turnos periódicos de sessão principal
• Tarefas Agendadas - agendamento de trabalho em segundo plano
• Task Flow - orquestração de fluxos acima das tarefas