Tareas en segundo plano

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

Las tareas no sustituyen a las sesiones, los trabajos cron ni los heartbeats: son el registro de actividad que deja constancia de 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 pasa 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 siendo responsable del trabajo; si el estado del entorno de ejecución en memoria desaparece, 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 push: el trabajo desacoplado puede notificar directamente o activar la sesión o el heartbeat del solicitante cuando termina, por lo que los bucles de sondeo de estado suelen ser un enfoque inadecuado.
• Las ejecuciones de cron aisladas y las finalizaciones de subagentes intentan, sin garantía, limpiar las pestañas y los procesos del navegador registrados para su sesión secundaria antes de realizar el registro final de limpieza.
• La entrega de cron aislada suprime las respuestas provisionales obsoletas del agente principal mientras el trabajo de los subagentes descendientes sigue terminando y da preferencia a la salida final de los descendientes 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 presenta 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

# Mostrar todas las tareas (primero las más recientes)openclaw tasks list # Filtrar por entorno de ejecución o estadoopenclaw tasks list --runtime acpopenclaw tasks list --status running

# Mostrar los detalles de una tarea específica (por ID de tarea, ID de ejecución o clave de sesión)openclaw tasks show <lookup>

# Cancelar una tarea en ejecución (termina la sesión secundaria)openclaw tasks cancel <lookup> # Cambiar la política de notificaciones de una tareaopenclaw tasks notify <lookup> state_changes

# Ejecutar una auditoría de estadoopenclaw tasks audit # Previsualizar o aplicar el mantenimientoopenclaw tasks maintenanceopenclaw tasks maintenance --apply

# Inspeccionar el estado de TaskFlowopenclaw 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 : el agente se inicia
    running --> succeeded : se completa correctamente
    running --> failed : error
    running --> timed_out : se supera el tiempo de espera
    queued --> cancelled : el operador cancela
    running --> cancelled : el operador cancela
    queued --> lost : el estado subyacente desaparece durante más de 5 min
    running --> lost : el estado subyacente desaparece durante más de 5 min

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

La finalización de la ejecución del agente es autoritativa para los registros de tareas activas. Una ejecución desacoplada correcta termina como succeeded, los errores normales de ejecución terminan como failed, los tiempos de espera terminan como timed_out y los resultados de cancelación o anulación terminan como cancelled. Una vez que una tarea alcanza un estado terminal, las señales posteriores del ciclo de vida no reducen su estado: una tarea cancelada por el operador o que ya tenga el estado failed/timed_out/lost permanece así aunque después llegue una señal de finalización correcta.

lost tiene en cuenta el entorno de ejecución:

• Tareas de ACP: solo un turno de ACP activo 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 de la CLI sin conexión es conservadora y nunca recupera tareas de ACP.
• Tareas de subagentes: la sesión secundaria subyacente 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 de la CLI sin conexión no considera autoritativo el estado vacío de su propio entorno de ejecución de cron dentro del proceso.
• Tareas de la CLI: las tareas con un ID 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 openclaw agent respaldadas por el Gateway también terminan según el resultado de su ejecución, por lo que las ejecuciones completadas no permanecen activas hasta que el proceso de limpieza las marca como lost.

Entrega y notificaciones

Cuando una tarea alcanza un estado terminal, OpenClaw envía una notificación. Hay dos rutas de entrega:

Entrega directa: si la tarea tiene un canal de destino (el 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 a hilos o temas 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 renunciar a la entrega directa.

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

Esto significa que el flujo de trabajo habitual se basa en notificaciones push: se inicia una vez el trabajo desacoplado y después se deja que el entorno de ejecución active una sesión o envíe una notificación al finalizar. Consulte el estado de las tareas únicamente cuando necesite depurar, intervenir o realizar una auditoría explícita.

Políticas de notificaciones

Controle cuánta información se recibe sobre cada tarea:

Cambie 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)

Utilice /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 los errores.

Cuando la sesión actual no tiene tareas vinculadas visibles, /tasks recurre a los recuentos de tareas locales del agente, por lo que se sigue obteniendo una vista general sin revelar detalles de otras sesiones.

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

Interfaz de control

La interfaz de control web tiene una página Tareas en la barra lateral con las tareas en segundo plano activas y recientes en tiempo real. Se utiliza 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 barra contraíble de Tareas en segundo plano limitada al agente del panel: tareas y subagentes en ejecución con un control para detenerlos, una sección de tareas 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).

Seleccione una tarea en la barra para inspeccionar su instrucción de entrada delimitada y el resumen más reciente de la salida o del error. El trabajo en ejecución permanece separado del finalizado, y las filas finalizadas indican si la tarea se completó o falló. En iOS, abra Acciones del chat → Tareas en segundo plano; en Android, abra el menú adicional del chat y seleccione Tareas en segundo plano. Ambas vistas móviles utilizan la misma agrupación de En ejecución y Finalizadas, y abren los detalles de la tarea al seleccionarla.

Integración del estado (carga de tareas)

openclaw status incluye una línea de tareas que permite consultar el estado de un vistazo:

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

El resumen cuenta 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 da prioridad a las tareas activas, se ocultan las filas caducadas y las tareas terminales solo aparecen durante un breve periodo reciente (5 minutos); cuando no queda trabajo activo, se destacan los fallos. De este modo, la tarjeta de estado se centra en lo importante en ese momento.

Almacenamiento y mantenimiento

Ubicación de las tareas

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

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

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

El registro se carga en memoria la primera vez que se utiliza y cada escritura se vuelve a guardar en SQLite, por lo que los registros sobreviven a los reinicios del Gateway. El crecimiento del WAL se mantiene limitado mediante el umbral de puntos de control automáticos predeterminado de SQLite y los puntos de control periódicos PASSIVE; los puntos de control del apagado y del mantenimiento explícito utilizan TRUNCATE, por lo que los cierres normales recuperan el espacio del WAL sin hacer que el proceso de limpieza en segundo plano espere 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 ocurre unos 5 segundos después de iniciarse el Gateway) y se ocupa de cuatro tareas:

Relación entre las tareas y 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
• TaskFlow - orquestación de flujos por encima de las tareas