Tareas en segundo plano

Las tareas en segundo plano rastrean el trabajo que se ejecuta fuera de tu sesión principal de conversación: ejecuciones de ACP, creación de subagentes, ejecuciones aisladas de trabajos Cron y operaciones iniciadas por la CLI.

Las tareas no reemplazan sesiones, trabajos Cron ni Heartbeats: son el registro de actividad que registra qué trabajo desvinculado ocurrió, cuándo y si se completó correctamente.

Resumen

• Las tareas son registros, no programadores: Cron y Heartbeat deciden cuándo se ejecuta el trabajo; las tareas rastrean qué ocurrió.
• ACP, los subagentes, todos los trabajos Cron y las operaciones de la CLI crean tareas. Los turnos de Heartbeat no.
• Cada tarea avanza por queued → running → terminal (succeeded, failed, timed_out, cancelled o lost).
• Las tareas Cron permanecen activas mientras el runtime de Cron aún posee el trabajo; si el estado del runtime en memoria desaparece, el mantenimiento de tareas primero revisa el historial durable de ejecuciones Cron antes de marcar una tarea como perdida.
• La finalización está impulsada por push: el trabajo desvinculado puede notificar directamente o despertar la sesión solicitante/Heartbeat cuando termina, por lo que los bucles de sondeo de estado suelen tener la forma equivocada.
• Las ejecuciones Cron aisladas y las finalizaciones de subagentes intentan limpiar, con el mejor esfuerzo, las pestañas/procesos del navegador rastreados para su sesión hija antes de la contabilidad final de limpieza.
• La entrega Cron aislada suprime respuestas principales intermedias obsoletas mientras el trabajo de subagentes descendientes aún se está drenando, y prefiere la salida final del descendiente cuando llega antes de la entrega.
• Las notificaciones de finalización se entregan directamente a un canal o se ponen en cola para el siguiente Heartbeat.
• openclaw tasks list muestra todas las tareas; openclaw tasks audit muestra problemas.
• Los registros terminales se conservan durante 7 días y luego se depuran automáticamente.

Inicio rápido

# List all tasks (newest first)openclaw tasks list # Filter by runtime or statusopenclaw tasks list --runtime acpopenclaw 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 taskopenclaw tasks notify <lookup> state_changes

# Run a health auditopenclaw tasks audit # Preview or apply maintenanceopenclaw tasks maintenanceopenclaw tasks maintenance --apply

# Inspect TaskFlow stateopenclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

Qué crea una tarea

Ciclo de vida de las tareas

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

Las transiciones ocurren automáticamente: cuando termina la ejecución del agente asociado, el estado de la tarea se actualiza para coincidir.

La finalización de la ejecución del agente es autoritativa para los registros de tareas activos. Una ejecución desvinculada correcta finaliza como succeeded, los errores ordinarios de ejecución finalizan como failed, y los resultados de tiempo de espera o aborto finalizan como timed_out. Si un operador ya canceló la tarea, o el runtime ya registró un estado terminal más fuerte como failed, timed_out o lost, una señal de éxito posterior no rebaja ese estado terminal.

lost tiene en cuenta el runtime:

• Tareas ACP: desaparecieron los metadatos de la sesión hija de ACP de respaldo.
• Tareas de subagente: la sesión hija de respaldo desapareció del almacén del agente de destino.
• Tareas Cron: el runtime de Cron ya no rastrea el trabajo como activo y el historial durable de ejecuciones Cron no muestra un resultado terminal para esa ejecución. La auditoría sin conexión de la CLI no trata su propio estado vacío del runtime Cron en proceso como autoridad.
• Tareas de la CLI: las tareas con un id de ejecución/id de origen usan el contexto de ejecución en vivo, por lo que las filas persistentes de sesión hija o sesión de chat no las mantienen activas después de que desaparece la ejecución propiedad del Gateway. Las tareas de la CLI heredadas sin identidad de ejecución aún recurren a la sesión hija. Las ejecuciones openclaw agent respaldadas por Gateway también finalizan desde su resultado de ejecución, por lo que las ejecuciones completadas no permanecen activas hasta que el barrendero las marca como lost.

Entrega y notificaciones

Cuando una tarea alcanza un estado terminal, OpenClaw te notifica. Hay dos rutas de entrega:

Entrega directa: si la tarea tiene un destino de canal (el requesterOrigin), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Las finalizaciones de tareas de grupos y canales se enrutan en cambio a través de la sesión solicitante para que el agente principal pueda escribir la respuesta visible. Para finalizaciones de subagentes, OpenClaw también conserva el enrutamiento vinculado de hilo/tema cuando está disponible y puede completar un to / cuenta faltante desde la ruta almacenada de la sesión solicitante (lastChannel / lastTo / lastAccountId) antes de rendirse con la entrega directa.

Entrega en cola de sesión: si la entrega directa falla o no hay origen definido, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente Heartbeat.

Eso significa que el flujo de trabajo habitual está basado en push: inicia el trabajo desvinculado una vez y luego deja que el runtime te despierte o notifique al finalizar. Sondea el estado de la tarea solo cuando necesites depuración, intervención o una auditoría explícita.

Políticas de notificación

Controla cuánto recibes sobre cada tarea:

Cambia la política mientras una tarea se está ejecutando:

openclaw tasks notify <lookup> state_changes

Referencia de la 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>

Tablero de tareas de chat (/tasks)

Usa /tasks en cualquier sesión de chat para ver las tareas en segundo plano vinculadas a esa sesión. El tablero muestra tareas activas y completadas recientemente con runtime, estado, tiempos y progreso o detalles de error.

Cuando la sesión actual no tiene tareas vinculadas visibles, /tasks recurre a recuentos de tareas locales del agente para que sigas teniendo una vista general sin filtrar detalles de otras sesiones.

Para el libro mayor completo del operador, usa la CLI: openclaw tasks list.

Integración de estado (presión de tareas)

openclaw status incluye un resumen rápido de tareas:

Tasks: 3 queued · 2 running · 1 issues

El resumen informa:

• active - recuento de queued + running
• failures - recuento de failed + timed_out + lost
• byRuntime - desglose por acp, subagent, cron, cli

Tanto /status como la herramienta session_status usan una instantánea de tareas consciente de la limpieza: se prefieren las tareas activas, se ocultan las filas completadas obsoletas y los fallos recientes solo aparecen cuando no queda trabajo activo. Esto mantiene la tarjeta de estado centrada en lo que importa ahora mismo.

Almacenamiento y mantenimiento

Dónde viven las tareas

Los registros de tareas persisten en SQLite en:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

El registro se carga en memoria al iniciar el gateway y sincroniza las escrituras con SQLite para mantener durabilidad entre reinicios. El Gateway mantiene acotado el registro de escritura anticipada de SQLite usando el umbral predeterminado de autocheckpoint de SQLite más checkpoints periódicos PASSIVE. El apagado y los checkpoints explícitos de mantenimiento siguen usando TRUNCATE para que los cierres normales puedan recuperar espacio de WAL sin hacer que el barrido en segundo plano espere a lectores activos.

Mantenimiento automático

Un barrido se ejecuta cada 60 segundos y gestiona cuatro cosas:

Cómo se relacionan las tareas con otros sistemas

Relacionado

• Automatización - todos los mecanismos de automatización de un vistazo
• CLI: tareas - referencia de comandos de la CLI
• Heartbeat - turnos periódicos de sesión principal
• Tareas programadas - programación de trabajo en segundo plano
• Flujo de tareas - orquestación de flujos por encima de tareas