Tareas en segundo plano

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

Las tareas no sustituyen a las sesiones, los trabajos cron ni los Heartbeat: son el registro de actividad que documenta qué trabajo desacoplado se realizó, 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 registran 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 entorno de ejecución de cron siga controlando el trabajo; si desaparece el estado del entorno de ejecución en memoria, el mantenimiento de tareas comprueba primero el historial persistente de ejecuciones de cron antes de marcar una tarea como perdida.
• La finalización se basa en notificaciones: el trabajo desacoplado puede notificar directamente o reactivar la sesión o el Heartbeat del solicitante cuando termina, por lo que los bucles de consulta de estado suelen ser un enfoque inadecuado.
• Las ejecuciones aisladas de cron y las finalizaciones de subagentes intentan, en la medida de lo posible, cerrar las pestañas y los procesos del navegador registrados para su sesión secundaria antes de la limpieza administrativa final.
• La entrega de cron aislada omite las respuestas provisionales obsoletas del agente principal mientras aún se completa el trabajo de los subagentes descendientes, y prefiere la salida final de estos si 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 señala los problemas.
• Los registros terminales se conservan durante 7 días (los registros lost, durante 24 horas) y después se eliminan 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 task 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
    queued --> cancelled : operator cancels
    running --> cancelled : operator cancels
    queued --> lost : backing state gone > 5 min
    running --> lost : backing state gone > 5 min

Las transiciones se producen automáticamente: los eventos del ciclo de vida de la ejecución del agente (inicio, fin y error) actualizan el estado de la tarea; no es necesario administrarlo manualmente.

La finalización de la ejecución del agente es la fuente autoritativa para los registros de tareas activas. Una ejecución desacoplada correcta finaliza como succeeded, los errores ordinarios de ejecución finalizan como failed, los tiempos de espera finalizan como timed_out y las cancelaciones o interrupciones finalizan como cancelled. Una vez que una tarea alcanza un estado terminal, las señales posteriores del ciclo de vida no la degradan: una tarea cancelada por un operador o que ya esté en estado failed/timed_out/lost permanece así aunque posteriormente llegue una señal de éxito.

lost depende del entorno de ejecución:

• Tareas de ACP: solo un turno activo de ACP dentro del proceso del Gateway demuestra que la ejecución sigue activa; los metadatos persistentes de la sesión por sí solos no lo demuestran. La auditoría sin conexión de la CLI es conservadora y nunca recupera tareas de ACP.
• Tareas de subagentes: la sesión secundaria de respaldo desapareció del almacén del agente de destino (o contiene una marca de recuperación tras reinicio).
• Tareas cron: el entorno de ejecución de cron ya no registra el trabajo como activo y el historial persistente de ejecuciones de cron no muestra un resultado terminal para esa ejecución. La auditoría sin conexión de la CLI no considera autoritativo su propio estado vacío del entorno de ejecución de cron dentro del proceso.
• Tareas de la CLI: las tareas con un identificador de ejecución o de origen usan el contexto de ejecución activo, por lo que las filas persistentes de sesiones secundarias o de chat no las mantienen activas después de que desaparece la ejecución controlada por el Gateway. Las tareas heredadas de la CLI sin identidad de ejecución siguen recurriendo a la sesión secundaria. Las ejecuciones de openclaw agent respaldadas por el Gateway también finalizan a partir del resultado de su ejecución, por lo que las ejecuciones completadas no permanecen activas hasta que el proceso de mantenimiento las marca como lost.

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 canal de destino (requesterOrigin), el mensaje de finalización se envía directamente a ese canal (Discord, Slack, Telegram, etc.). En cambio, las finalizaciones de tareas de grupos y canales se encaminan mediante la sesión solicitante para que el agente principal pueda escribir la respuesta visible. Para las finalizaciones de subagentes, OpenClaw también conserva el enrutamiento vinculado del hilo o tema cuando está disponible y puede completar un valor to o una cuenta que falten a partir de la ruta almacenada en la sesión solicitante (lastChannel / lastTo / lastAccountId) antes de desistir de la entrega directa.

Entrega en cola de la sesión: si falla la entrega directa o no se ha definido 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 Heartbeat.

Esto significa que el flujo de trabajo habitual se basa en notificaciones: inicia una vez el trabajo desacoplado y deja que el entorno de ejecución te reactive o notifique cuando finalice. Consulta el estado de las tareas solo cuando necesites depurar, intervenir o realizar una auditoría explícita.

Políticas de notificación

Controla cuánta información recibes sobre cada tarea:

Cambia la política mientras se ejecuta una tarea:

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> [--json]

openclaw tasks cancel <lookup>

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

openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--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>

Panel de tareas del chat (/tasks)

Use /tasks en cualquier sesión de chat para ver las tareas en segundo plano vinculadas a esa sesión. El panel muestra hasta cinco tareas activas y completadas recientemente con detalles del entorno de ejecución, el estado, los tiempos y el progreso o error.

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

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

Interfaz web de control

La interfaz web de control tiene una página Tareas en la barra lateral con las tareas en segundo plano activas y recientes en tiempo real. Úsela para inspeccionar el progreso, abrir sesiones vinculadas, actualizar el registro o cancelar tareas en cola y en ejecución.

Los paneles de chat también tienen una sección contraíble de Tareas en segundo plano limitada al agente del panel: muestra las tareas y los subagentes en ejecución con un control para detenerlos, una sección de finalizadas y enlaces para ver la transcripción de la sesión secundaria de cada tarea. Ábrala desde el selector de actividad del encabezado del panel (o desde el botón flotante de actividad en el chat de un solo panel).

Integración del estado (carga de tareas)

openclaw status incluye una línea de tareas resumida:

Tareas    2 activas · 1 en cola · 1 en ejecución · 1 problema · auditoría limpia · 6 rastreadas

El resumen contabiliza el trabajo activo (queued + running), los fallos (failed + timed_out + lost), los hallazgos de auditoría y el total de registros rastreados; la carga JSON también desglosa los recuentos por entorno de ejecución (acp, subagent, cron, cli).

Tanto /status como la herramienta session_status utilizan una instantánea de tareas que tiene en cuenta la limpieza: se priorizan las tareas activas, se ocultan las filas caducadas y las tareas terminales solo aparecen durante un breve período reciente (5 minutos), con énfasis en los fallos cuando no queda trabajo activo. Esto mantiene la tarjeta de estado centrada en lo importante en este momento.

Almacenamiento y mantenimiento

Dónde se guardan las tareas

Los registros de tareas y el estado de entrega persisten en la base de datos SQLite de estado compartida de OpenClaw:

~/.openclaw/state/openclaw.sqlite   (tablas: task_runs, task_delivery_state, flow_runs)

Establezca OPENCLAW_STATE_DIR para mover toda la raíz de estado (de forma predeterminada, ~/.openclaw) a otra ubicación; la ruta de la base de datos compartida se moverá con ella.

El registro se carga en memoria con el primer uso y cada escritura se guarda en SQLite, por lo que los registros sobreviven a los reinicios del Gateway. El crecimiento del WAL se mantiene limitado mediante el umbral predeterminado de puntos de control automáticos de SQLite y puntos de control PASSIVE periódicos; los puntos de control al apagar y durante el mantenimiento explícito usan TRUNCATE, por lo que los cierres normales recuperan el espacio del WAL sin obligar al proceso de limpieza en segundo plano a esperar a los lectores activos.

Los almacenes auxiliares heredados de instalaciones anteriores (tasks/runs.sqlite, flows/registry.sqlite) se importan en la base de datos compartida mediante openclaw doctor.

Mantenimiento automático

Un proceso de limpieza se ejecuta cada 60 segundos (la primera pasada se realiza unos 5 segundos después de iniciar el Gateway) y se encarga de cuatro aspectos:

Relación de las tareas con otros sistemas

Contenido 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 la sesión principal
• Tareas programadas - programación de trabajo en segundo plano
• Flujo de tareas - orquestación de flujos sobre las tareas