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 utilizan la política de notificación silent de forma predeterminada: crean registros para seguimiento pero no generan notificaciones. Las tareas cron aisladas también utilizan de forma predeterminada silent pero son más visibles porque se ejecutan en su propia sesión.

Las ejecuciones image_generate, music_generate y video_generate con respaldo de sesión también utilizan 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 reactivador interno para que el agente pueda escribir el mensaje de seguimiento y adjuntar el medio finalizado por sí mismo. Los eventos de finalización de medios generados requieren entrega mediante herramienta de mensaje: el agente debe enviar el medio finalizado con la herramienta message y luego responder NO_REPLY. Si el agente de finalización solo escribe una respuesta final privada u omite el archivo adjunto del medio, OpenClaw marca la transferencia de finalización como fallida; no publica automáticamente el medio generado como alternativa.

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 normales de chat interactivo
Respuestas directas /command

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]

Use esto para previsualizar o aplicar conciliación, limpieza de estampado y poda para tareas, el estado de Task Flow y filas obsoletas del registro de sesión de ejecución 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 cron verifican si el tiempo de ejecución cron todavía posee el trabajo, luego recuperan el estado terminal de los registros de ejecución cron/estado del trabajo persistido antes de recurrir a lost. Solo el proceso Gateway es autoritario para el conjunto de trabajos activos cron en memoria; la auditoría de CLI sin conexión utiliza el historial duradero pero no marca una tarea 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 sesión de chat.

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

La finalización del subagente cierra con el mejor esfuerzo las pestañas/procesos del navegador rastreados para la sesión secundaria antes de que continúe la limpieza del anuncio.
La finalización del cron aislado cierra con el mejor esfuerzo las pestañas/procesos del navegador rastreados para la sesión cron antes de que la ejecución se desarme por completo.
La entrega del 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 prefiere el texto visible más reciente del asistente; si está vacío, recurre al texto de herramienta/toolResult más reciente saneado, y las ejecuciones de llamadas a herramienta solo por tiempo de espera pueden colapsarse en un breve resumen de progreso parcial. Las ejecuciones fallidas terminales anuncian el estado de falla sin reproducir el texto de respuesta capturado.
Los fallos de limpieza no enmascaran el resultado real de la tarea.

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

:run:

` de más de 7 días, mientras preserva las filas para los trabajos cron que se están ejecutando actualmente y deja las filas de sesión no cron intactas.

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 es la capa de orquestación de flujo sobre las tareas en segundo plano. Un único flujo puede coordinar múltiples tareas durante su vida útil utilizando modos de sincronización administrados o reflejados. Use openclaw tasks para inspeccionar registros de tareas individuales y openclaw tasks flow para inspeccionar el flujo de orquestación.

Consulte Task Flow para obtener más detalles.

Tareas y cron

Una definición de trabajo cron reside en ~/.openclaw/cron/jobs.json; el estado de ejecución en tiempo de ejecución reside junto a ella en ~/.openclaw/cron/jobs-state.json. Todas las ejecuciones cron crean un registro de tarea, tanto de sesión principal como aisladas. Las tareas cron de sesión principal tienen por defecto la política de notificación silent para que realicen un seguimiento sin generar notificaciones.

Consulte Cron Jobs.

Tareas y heartbeat

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

Consulte Heartbeat.

Tareas y sesiones

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.

Tareas y ejecuciones de agentes

El 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, finalización, error) actualizan automáticamente el estado de la tarea; no necesita gestionar el ciclo de vida manualmente.

Relacionado

Automation - todos los mecanismos de automatización de un vistazo
CLI: Tasks - referencia de comandos de CLI
Heartbeat - turnos periódicos de sesión principal
Tareas programadas - programación de trabajos en segundo plano
Flujo de tareas - orquestación de flujos sobre las tareas