Tareas en segundo plano
¿Buscas programación? Consulta Automatización y tareas para elegir el mecanismo adecuado. Esta página cubre el seguimiento del trabajo en segundo plano, no su programación.
Las tareas en segundo plano hacen seguimiento del trabajo que se ejecuta fuera de tu sesión principal de conversación:
ejecuciones de ACP, generación de subagentes, ejecuciones aisladas de trabajos cron y operaciones iniciadas por la CLI.
Las tareas no reemplazan las sesiones, los trabajos cron ni los heartbeat: son el registro de actividad que anota qué trabajo desacoplado ocurrió, cuándo y si se completó correctamente.
No todas las ejecuciones de agentes crean una tarea. Los turnos de heartbeat y el chat interactivo normal no lo hacen. Todas las ejecuciones cron, las ejecuciones de ACP, las ejecuciones de subagentes y los comandos de agente de la CLI sí lo hacen.
Resumen rápido
- Las tareas son registros, no planificadores: cron y heartbeat deciden cuándo se ejecuta el trabajo; las tareas registran qué ocurrió.
- ACP, subagentes, todos los trabajos 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 cron permanecen activas mientras el entorno de ejecución cron siga siendo propietario del trabajo; las tareas de CLI basadas en chat permanecen activas solo mientras su contexto de ejecución propietario siga activo.
- La finalización se impulsa por envío: el trabajo desacoplado puede notificar directamente o activar la sesión solicitante o el heartbeat cuando termina, por lo que los bucles de sondeo de estado normalmente no son el enfoque correcto.
- Las ejecuciones cron aisladas y las finalizaciones de subagentes limpian, en el mejor esfuerzo, las pestañas o procesos del navegador rastreados para su sesión hija antes de la contabilidad final de limpieza.
- La entrega cron aislada suprime las respuestas provisionales obsoletas del proceso padre mientras el trabajo de subagentes descendientes sigue drenándose, y prefiere la salida final 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 los problemas.- Los registros terminales se conservan durante 7 días y luego se eliminan 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 <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>
Qué crea una tarea
| Origen | Tipo de entorno | Cuándo se crea un registro de tarea | Política de notificación predeterminada |
|---|
| Ejecuciones en segundo plano de ACP | acp | Generación de una sesión hija de ACP | done_only |
| Orquestación de subagentes | subagent | Generación de un subagente mediante sessions_spawn | done_only |
| Trabajos cron (todos los tipos) | cron | Cada ejecución cron (sesión principal y aislada) | silent |
| Operaciones de CLI | cli | Comandos openclaw agent que se ejecutan a través del gateway | silent |
silent de forma predeterminada: crean registros para 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.
Qué no crea tareas:
- Turnos de heartbeat: sesión principal; consulta Heartbeat
- Turnos de chat interactivo normales
- Respuestas directas de
/command
Ciclo de vida de la tarea
| Estado | Qué significa |
|---|
queued | Creada, esperando a que el agente inicie |
running | El turno del agente se está ejecutando activamente |
succeeded | Completada correctamente |
failed | Completada con un error |
timed_out | Superó el tiempo de espera configurado |
cancelled | Detenida por el operador mediante openclaw tasks cancel |
lost | El entorno de ejecución perdió el estado de respaldo autorizado después de un período de gracia de 5 minutos |
lost tiene en cuenta el entorno de ejecución:
- Tareas de ACP: desaparecieron los metadatos de la sesión hija de ACP de respaldo.
- Tareas de subagentes: la sesión hija de respaldo desapareció del almacén del agente de destino.
- Tareas cron: el entorno de ejecución cron ya no rastrea el trabajo como activo.
- Tareas de CLI: las tareas de sesión hija aislada usan la sesión hija; las tareas de CLI basadas en chat usan en su lugar el contexto de ejecución activo, por lo que las filas persistentes de sesión de canal/grupo/directa no las mantienen activas.
Entrega y notificaciones
Cuando una tarea alcanza un estado terminal, OpenClaw te lo notifica. Hay dos rutas de entrega:
Entrega directa: si la tarea tiene un destino de canal (el requesterOrigin), el mensaje de finalización se envía directamente a ese canal (Telegram, Discord, Slack, etc.). Para las finalizaciones de subagentes, OpenClaw también conserva el enrutamiento enlazado de hilo/tema cuando está disponible y puede completar un to o una cuenta faltantes a partir de la ruta almacenada de la sesión solicitante (lastChannel / lastTo / lastAccountId) antes de abandonar la entrega directa.
Entrega en cola de sesión: si la entrega directa falla o no se define un origen, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente heartbeat.
La finalización de una tarea activa un heartbeat inmediato para que veas el resultado rápidamente; no tienes que esperar al siguiente intervalo programado del heartbeat.
Políticas de notificación
Controla cuánto deseas saber sobre cada tarea:
| Política | Qué se entrega |
|---|
done_only (predeterminada) | Solo el estado terminal (succeeded, failed, etc.): esta es la opción predeterminada |
state_changes | Cada transición de estado y actualización de progreso |
silent | Nada en absoluto |
openclaw tasks notify <lookup> state_changes
Referencia de CLI
tasks list
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
tasks show
openclaw tasks show <lookup>
tasks cancel
openclaw tasks cancel <lookup>
cancelled y se envía una notificación de entrega.
tasks notify
openclaw tasks notify <lookup> <done_only|state_changes|silent>
tasks audit
openclaw tasks audit [--json]
openclaw status cuando se detectan problemas.
| Hallazgo | Severidad | Activador |
|---|
stale_queued | warn | En cola durante más de 10 minutos |
stale_running | error | En ejecución durante más de 30 minutos |
lost | error | La propiedad de la tarea respaldada por el entorno desapareció |
delivery_failed | warn | La entrega falló y la política de notificación no es silent |
missing_cleanup | warn | Tarea terminal sin marca de tiempo de limpieza |
inconsistent_timestamps | warn | Violación de la secuencia temporal (por ejemplo, terminó antes de empezar) |
tasks maintenance
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
- Las tareas de ACP/subagentes comprueban su sesión hija de respaldo.
- Las tareas cron comprueban si el entorno de ejecución cron sigue siendo propietario del trabajo.
- Las tareas de CLI basadas en chat comprueban el contexto de ejecución activo propietario, no solo la fila de sesión del chat.
La limpieza de finalización también tiene en cuenta el entorno de ejecución:
- La finalización de subagentes cierra, en el mejor esfuerzo, las pestañas o procesos del navegador rastreados para la sesión hija antes de que continúe la limpieza del anuncio.
- La finalización cron aislada cierra, en el mejor esfuerzo, las pestañas o procesos del navegador rastreados para la sesión cron antes de que la ejecución se desmonte por completo.
- La entrega cron aislada espera el seguimiento de subagentes descendientes cuando es necesario y suprime el texto obsoleto de confirmación del proceso padre en lugar de anunciarlo.
- La entrega de finalización de subagentes prefiere el texto visible más reciente del asistente; si está vacío, recurre al texto saneado más reciente de
tool/toolResult, y las ejecuciones de solo llamadas de herramientas con tiempo de espera agotado pueden contraerse a un breve resumen de progreso parcial.
- Los errores de limpieza no ocultan el resultado real de la tarea.
tasks flow list|show|cancel
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
Tablero de tareas del 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 las tareas activas y completadas recientemente con entorno de ejecución, estado, tiempo y detalle de progreso o 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 visión general sin filtrar detalles de otras sesiones.
Para el registro completo del operador, usa 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
- 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 con reconocimiento de limpieza: se priorizan las tareas activas, se ocultan las filas completadas obsoletas y los errores 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
Mantenimiento automático
Un proceso de barrido se ejecuta cada 60 segundos y se encarga de tres cosas:
- Conciliación: comprueba si las tareas activas todavía tienen respaldo autoritativo del entorno de ejecución. Las tareas de ACP/subagentes usan el estado de la sesión hija, las tareas cron usan la propiedad del trabajo activo y las tareas de CLI basadas en chat usan el contexto de ejecución propietario. Si ese estado de respaldo desaparece durante más de 5 minutos, la tarea se marca como
lost.
- Marcado de limpieza: establece una marca de tiempo
cleanupAfter en las tareas terminales (endedAt + 7 days).
- Depuración: elimina los registros que hayan superado su fecha
cleanupAfter.
Retención: los registros de tareas terminales se conservan durante 7 días y luego se eliminan automáticamente. No se necesita configuración.
Cómo se relacionan las tareas con otros sistemas
Tareas y Task Flow
Task Flow es la capa de orquestación de flujos por encima de las tareas en segundo plano. Un único flujo puede coordinar múltiples tareas a lo largo de su vida útil mediante modos de sincronización gestionados o reflejados. Usa openclaw tasks para inspeccionar registros individuales de tareas y openclaw tasks flow para inspeccionar el flujo de orquestación.
Consulta Task Flow para obtener más detalles.
Tareas y cron
Una definición de trabajo cron vive en ~/.openclaw/cron/jobs.json. Cada ejecución cron crea un registro de tarea, tanto en la sesión principal como en la aislada. Las tareas cron de la sesión principal usan la política de notificación silent de forma predeterminada para hacer seguimiento sin generar notificaciones.
Consulta Trabajos cron.
Tareas y heartbeat
Las ejecuciones de heartbeat son turnos de la sesión principal: no crean registros de tarea. Cuando una tarea se completa, puede activar un heartbeat para que veas el resultado rápidamente.
Consulta Heartbeat.
Tareas y sesiones
Una tarea puede hacer referencia a una childSessionKey (donde se ejecuta el trabajo) y a una requesterSessionKey (quién lo inició). Las sesiones son el contexto de conversación; las tareas son el seguimiento de actividad por encima de ese contexto.
Tareas y ejecuciones de agentes
El runId de una tarea enlaza con 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 necesitas gestionar manualmente el ciclo de vida.
Relacionado
