Tareas en segundo plano

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

Las tareas no reemplazan a las sesiones, trabajos cron o heartbeats: son el registro de actividad que registra qué trabajo desacoplado sucedió, cuándo y si tuvo éxito.

Resumen

Las tareas son registros, no programadores: cron y heartbeat deciden cuándo se ejecuta el trabajo, las tareas rastrean qué sucedió.
ACP, subagentes, todos los trabajos de cron y las operaciones de CLI crean tareas. Los turnos de Heartbeat no.
Cada tarea pasa por queued → running → terminal (succeeded, failed, timed_out, cancelled o lost).
Las tareas de cron se mantienen activas mientras el tiempo de ejecución de cron sea propietario del trabajo; si el estado del tiempo de ejecución en memoria desaparece, el mantenimiento de tareas verifica primero el historial duradero de ejecuciones de cron antes de marcar una tarea como perdida.
La finalización se impulsa por eventos (push): el trabajo desvinculado puede notificar directamente o despertar la sesión/latido del solicitante cuando termina, por lo que los bucles de sondeo de estado suelen ser el enfoque incorrecto.
Las ejecuciones cron aisladas y las finalizaciones de subagentes realizan un mejor esfuerzo para limpiar las pestañas/procesos del navegador rastreados para su sesión secundaria antes de la contabilidad final de limpieza.
La entrega de cron aislada suprime las respuestas principales interinas obsoletas mientras el trabajo de subagente descendente aún se está drenando, y prefiere la salida descendente final 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 latido.
openclaw tasks list muestra todas las tareas; openclaw tasks audit resalta los problemas.
Los registros terminales se mantienen durante 7 días y luego se podan automáticamente.

Inicio 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

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

Change notification policy for a task

openclaw tasks notify

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

openclaw tasks flow cancel

Qué crea una tarea

Fuente	Tipo de tiempo de ejecución	Cuándo se crea un registro de tarea	Política de notificación predeterminada
Ejecuciones en segundo plano de ACP	`acp`	Generar una sesión secundaria de ACP	`done_only`
Orquestación de subagentes	`subagent`	Generar un subagente mediante `sessions_spawn`	`done_only`
Trabajos de cron (todos los tipos)	`cron`	Cada ejecución de cron (sesión principal y aislada)	`silent`
Operaciones de CLI	`cli`	Comandos `openclaw agent` que se ejecutan a través de la puerta de enlace	`silent`
Trabajos de medios del agente	`cli`	Ejecuciones `image_generate`/`music_generate`/`video_generate` respaldadas por sesión	`silent`

Valores predeterminados de notificación para cron y medios

Las tareas cron de sesión principal usan la política de notificación silent de manera predeterminada; crean registros para el seguimiento pero no generan notificaciones. Las tareas cron aisladas también usan silent de forma predeterminada, pero son más visibles porque se ejecutan en su propia sesión.

Las ejecuciones image_generate, music_generate y video_generate respaldadas por sesión también usan la política de notificación silent. Aún crean registros de tareas, pero la finalización se devuelve a la sesión del agente original como un despertar interno para que el agente pueda escribir el mensaje de seguimiento y adjuntar el medio terminado él mismo. El agente solicitante sigue su contrato de respuesta visible normal: respuesta final automática cuando está configurado, o message(action="send") más NO_REPLY cuando la sesión requiere respuestas de herramienta de mensajes. Si la sesión solicitante ya no está activa o su despertar activo falla, y el agente de finalización pierde parte o todo el medio generado, OpenClaw envía una reserva directa idempotente con solo el medio que falta al objetivo del canal original.

Concurrent media-generation guardrail

Mientras una tarea de generación de medios respaldada por sesión sigue activa, las herramientas de medios también actúan como guardarrails para reintentos accidentales. Las llamadas repetidas a image_generate para el mismo mensaje devuelven el estado de la tarea activa coincidente, mientras que un mensaje de imagen distinto puede iniciar su propia tarea. Las llamadas a music_generate y video_generate aún devuelven el estado de la tarea activa para esa sesión en lugar de iniciar una segunda generación simultánea. Use action: "status" cuando desee una búsqueda explícita de progreso/estado desde el lado del agente.

Qué no crea tareas

Turnos de Heartbeat - sesión principal; consulta Heartbeat
Turnos de chat interactivo normales
Respuestas /command directas

Ciclo de vida de la tarea

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

Estado	Lo que significa
`queued`	Creada, esperando a que el agente se inicie
`running`	El turno del agente se está ejecutando activamente
`succeeded`	Completada exitosamente
`failed`	Completada con un error
`timed_out`	Excedió el tiempo de espera configurado
`cancelled`	Detenido por el operador mediante `openclaw tasks cancel`
`lost`	El tiempo de ejecución perdió el estado de respaldo autoritativo después de un período de gracia de 5 minutos

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

La finalización de la ejecución del agente es autorizada para los registros de tareas activas. Una ejecución desacoplada exitosa se finaliza como succeeded, los errores de ejecución ordinarios se finalizados como failed, y los resultados de tiempo de espera o cancelación se finalizan como timed_out. Si un operador ya canceló la tarea, o el tiempo de ejecución ya registró un estado terminal más fuerte como failed, timed_out o lost, una señal de éxito posterior no degrada ese estado terminal.

lost tiene conocimiento del tiempo de ejecución:

Tareas de ACP: los metadatos de la sesión secundaria de respaldo de ACP desaparecieron.
Tareas de subagente: la sesión secundaria de respaldo desapareció del almacén del agente de destino.
Tareas de cron: el tiempo de ejecución de cron ya no rastrea el trabajo como activo y duradero el historial de ejecuciones de cron no muestra un resultado terminal para esa ejecución. La auditoría de CLI fuera de línea no trata su propio estado vacío del tiempo de ejecución de cron en proceso como autoridad.
Tareas de CLI: las tareas con un id de ejecución/id de fuente usan el contexto de ejecución en vivo, por lo que las filas persistentes de sub-sesión o de sesión de chat no las mantienen vivas después de que desaparece la ejecución propiedad de la puerta de enlace. Las tareas de CLI heredadas sin identidad de ejecución todavía recurren a la sub-sesión. Las ejecuciones de openclaw agent respaldadas por la puerta de enlace también se finalizan desde su resultado de ejecución, por lo que las ejecuciones completas no permanecen activas hasta que el barredor las marca como lost.

Entrega y notificaciones

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

Entrega directa - si la tarea tiene un objetivo de canal (el requesterOrigin), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Las finalizaciónes de tareas de grupo y canal en su lugar se enrutan a través de la sesión solicitante para que el agente principal pueda escribir la respuesta visible. Para las finalizaciónes de subagente, OpenClaw también preserva el enrutamiento de hilo/tema vinculado cuando está disponible y puede completar una to / cuenta faltante desde la ruta almacenada de la sesión solicitante (lastChannel / lastTo / lastAccountId) antes de renunciar a la entrega directa.

Entrega en cola de sesión - si la entrega directa falla o no se establece ningún origen, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente latido (heartbeat).

Esto significa que el flujo de trabajo habitual se basa en el envío (push): inicie el trabajo desvinculado una vez y luego deje que el tiempo de ejecución lo despierte o le notifique al completarse. Sondee el estado de la tarea solo cuando necesite depuración, intervención o una auditoría explícita.

Políticas de notificación

Controle cuánto recibe sobre cada tarea:

Política	Qué se entrega
`done_only` (predeterminado)	Solo el estado terminal (exitoso, fallido, etc.) - este es el valor predeterminado
`state_changes`	Cada transición de estado y actualización de progreso
`silent`	Nada en absoluto

Cambiar la política mientras se ejecuta una tarea:

openclaw tasks notify <lookup> state_changes

Referencia de la CLI

tasks list

openclaw tasks list [--runtime

] [—status

] [—json] ```

Columnas de salida: ID de tarea, Tipo, Estado, Entrega, ID de ejecución, Sesión secundaria, Resumen.

tasks show

openclaw tasks show

El token de búsqueda acepta un ID de tarea, ID de ejecución o clave de sesión. Muestra el registro completo, incluyendo el tiempo, el estado de entrega, el error y el resumen terminal.

tasks cancel

openclaw tasks cancel

Para las tareas de ACP y subagentes, esto termina la sesión secundaria. Para las tareas rastreadas por CLI, la cancelación se registra en el registro de tareas (no hay un identificador de tiempo de ejecución secundario separado). El estado cambia a `cancelled` y se envía una notificación de entrega cuando corresponde.

tasks notify

openclaw tasks notify

tasks audit

openclaw tasks audit [--json]

Detecta problemas operativos. Los hallazgos también aparecen en openclaw status cuando se detectan problemas.

Hallazgo	Severidad	Activador
`stale_queued`	advertencia	En cola durante más de 10 minutos
`stale_running`	error	En ejecución durante más de 30 minutos
`lost`	advertencia/error	La propiedad de la tarea respaldada por el tiempo de ejecución desapareció; las tareas perdidas retenidas advierten hasta `cleanupAfter`, luego se convierten en errores
`delivery_failed`	advertencia	La entrega falló y la política de notificación no es `silent`
`missing_cleanup`	advertencia	Tarea terminal sin marca de tiempo de limpieza
`inconsistent_timestamps`	advertencia	Violación de la línea de tiempo (por ejemplo, terminó antes de comenzar)

tasks maintenance

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

Úselo para previsualizar o aplicar la conciliación, la limpieza de estampación y la poda para tareas, el estado de Task Flow y las filas obsoletas del registro de sesiones de ejecución de cron.

La conciliación es consciente del tiempo de ejecución:

Las tareas de ACP/subagente verifican su sesión secundaria de respaldo.
Las tareas de subagente cuya sesión secundaria tiene una lápida de reinicio-recuperación se marcan como perdidas en lugar de ser tratadas como sesiones de respaldo recuperables.
Las tareas de cron verifican si el tiempo de ejecución de cron todavía posee el trabajo, luego recuperan el estado terminal de los registros de ejecución de cron persistentes/estado del trabajo antes de recurrir a lost. Solo el proceso Gateway es autoritario para el conjunto de trabajos activos de cron en memoria; la auditoría de CLI fuera de línea utiliza el historial duradero pero no marca una tarea de cron como perdida solo porque ese conjunto local esté vacío.
Las tareas de CLI con identidad de ejecución verifican el contexto de ejecución en vivo propietario, no solo las filas de sesión secundaria o de chat.

La limpieza al finalizar también es consciente del tiempo de ejecución:

La finalización del subagente cierra, con el mejor esfuerzo posible, las pestañas/procesos del navegador rastreados para la sesión secundaria antes de que continúe la limpieza del anuncio.
La finalización de cron aislado cierra, con el mejor esfuerzo posible, las pestañas/procesos del navegador rastreados para la sesión de cron antes de que la ejecución se cierre por completo.
La entrega de cron aislado espera el seguimiento del subagente descendente cuando es necesario y suprime el texto de reconocimiento principal obsoleto en lugar de anunciarlo.
La entrega de finalización del subagente usa solo el último texto de asistente visible del secundario. La salida de herramienta/toolResult no se promueve al texto de resultado secundario. Las ejecuciones fallidas terminales anuncian el estado de falla sin reproducir el texto de respuesta capturado.
Los fallos de limpieza no ocultan el resultado real de la tarea.

Al aplicar el mantenimiento, OpenClaw también elimina filas obsoletas del registro de sesiones de `cron:

:run:

` de más de 7 días, preservando las filas de los trabajos de cron que se están ejecutando actualmente y dejando las filas de sesiones que no son de cron sin tocar.

tasks flow list | show | cancel

openclaw tasks flow list [--status

] [—json] openclaw tasks flow show

[—json] openclaw tasks flow cancel

Utilice estos cuando el flujo de tareas (Task Flow) de orquestación es lo que le importa en lugar de un registro individual de tarea en segundo plano.

Tablero de tareas de chat (`/tasks`)

Use /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 tiempo de ejecución, estado, cronometraje y detalles de progreso o error.

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

Para el registro completo del operador, use la CLI: openclaw tasks list.

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

openclaw status incluye un resumen de tareas de un vistazo:

Tasks: 3 queued · 2 running · 1 issues

El resumen informa:

activo - recuento de queued + running
fallos - recuento de failed + timed_out + lost
porRuntime - desglose por acp, subagent, cron, cli

Tanto /status como la herramienta session_status utilizan 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 enfocada en lo importante ahora mismo.

Almacenamiento y mantenimiento

Dónde residen las tareas

Los registros de tareas persisten en SQLite en:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

El registro se carga en la memoria al iniciar la puerta de enlace y sincroniza las escrituras con SQLite para la durabilidad a través de reinicios. La puerta de enlace mantiene el registro de escritura anticipada (write-ahead log) de SQLite limitado utilizando el umbral de punto de control automático predeterminado de SQLite más puntos de control TRUNCATE periódicos y de apagado.

Mantenimiento automático

Un limpiador se ejecuta cada 60 segundos y maneja cuatro cosas:

Conciliación
Comprueba si las tareas activas todavía tienen soporte de runtime autorizado. Las tareas de ACP/subagente utilizan el estado de sub-sesión, las tareas de cron utilizan la propiedad de trabajo activo y las tareas de CLI con identidad de ejecución utilizan el contexto de ejecución propietario. Si ese estado de soporte ha desaparecido durante más de 5 minutos, la tarea se marca como lost.
Reparación de sesión ACP
Cierra sesiones ACP de un solo uso terminales o huérfanas propiedad del padre, y cierra sesiones ACP persistentes terminales u huérfanas obsoletas solo cuando no queda ningún enlace de conversación activo.
Marcado de limpieza
Establece una marca de tiempo de cleanupAfter en las tareas terminales (endedAt + 7 días). Durante la retención, las tareas perdidas aún aparecen en la auditoría como advertencias; después de que cleanupAfter caduque o cuando falta metadatos de limpieza, son errores.
Poda
Elimina registros pasados su fecha de cleanupAfter.

Cómo se relacionan las tareas con otros sistemas

Tareas y flujo de tareas (Task Flow)

Task Flow es la capa de orquestación de flujo sobre las tareas en segundo plano. Un solo flujo puede coordinar múltiples tareas a lo largo de su vida útil utilizando modos de sincronización administrados o reflejados. Usa openclaw tasks para inspeccionar registros de tareas individuales y openclaw tasks flow para inspeccionar el flujo de orquestación.

Consulta Task Flow para obtener más detalles.

Tasks and cron

Las definiciones de trabajos de cron, el estado de ejecución en tiempo de ejecución y el historial de ejecuciones residen en la base de datos de estado compartido SQLite de OpenClaw. Cada ejecución de cron crea un registro de tarea, tanto de sesión principal como aislada. Las tareas de cron de sesión principal tienen como valor predeterminado la política de notificación silent para que rastreen sin generar notificaciones.

Consulte Cron Jobs.

Tasks and heartbeat

Las ejecuciones de Heartbeat son turnos de sesión principal; no crean registros de tareas. Cuando se completa una tarea, puede activar un despertar de heartbeat para que vea el resultado rápidamente.

Consulte Heartbeat.

Tasks and sessions

Una tarea puede hacer referencia a una childSessionKey (donde se ejecuta el trabajo) y una requesterSessionKey (quién la inició). Las sesiones son el contexto de la conversación; las tareas son el seguimiento de la actividad sobre eso.

Tasks and agent runs

La runId de una tarea se vincula a la ejecución del agente que realiza el trabajo. Los eventos del ciclo de vida del agente (inicio, fin, error) actualizan automáticamente el estado de la tarea; no es necesario administrar el ciclo de vida manualmente.

Relacionado

Automation - todos los mecanismos de automatización en un vistazo
CLI: Tasks - referencia de comandos de la CLI
Heartbeat - turnos periódicos de sesión principal
Scheduled Tasks - programación de trabajos en segundo plano
Task Flow - orquestación de flujo por encima de las tareas