English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Automation and tasks

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 aislados y operaciones iniciadas por la CLI.

Las tareas no reemplazan las sesiones, los trabajos Cron ni los Heartbeat: son el registro de actividad que documenta qué trabajo desacoplado ocurrió, cuándo y si se completó correctamente.

Resumen rápido

  • Las tareas son registros, no programadores: 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 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 runtime de Cron todavía sea propietario del trabajo; si el estado del runtime en memoria desaparece, el mantenimiento de tareas primero comprueba el historial durable de ejecuciones Cron antes de marcar una tarea como perdida.
  • La finalización se basa en envío: el trabajo desacoplado puede notificar directamente o despertar la sesión solicitante o el Heartbeat cuando termina, por lo que los bucles de sondeo de estado normalmente tienen la forma incorrecta.
  • Las ejecuciones Cron aisladas y las finalizaciones de subagentes intentan limpiar, con el mejor esfuerzo, las pestañas/procesos de navegador rastreados para su sesión hija antes de la contabilidad final de limpieza.
  • La entrega Cron aislada suprime respuestas intermedias obsoletas del padre mientras el trabajo de subagentes descendientes sigue drenándose, y prefiere la salida final del descendiente cuando llega antes de la entrega.
  • Las notificaciones de finalización se entregan directamente a un canal o se encolan para el siguiente Heartbeat.
  • openclaw tasks list muestra todas las tareas; openclaw tasks audit expone problemas.
  • Los registros terminales se conservan durante 7 días y luego se eliminan automáticamente.

Inicio rápido

Listar y filtrar

# List all tasks (newest first)
openclaw tasks list

# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running

Inspeccionar

# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>

Cancelar y notificar

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

# Change notification policy for a task
openclaw tasks notify <lookup> state_changes

Auditoría y mantenimiento

# Run a health audit
openclaw tasks audit

# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply

Flujo de tareas

# Inspect TaskFlow state
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>

Qué crea una tarea

Origen Tipo de runtime Cuándo se crea un registro de tarea Política de notificación predeterminada
Ejecuciones en segundo plano de ACP acp Al crear una sesión ACP hija done_only
Orquestación de subagentes subagent Al crear un subagente mediante sessions_spawn done_only
Trabajos Cron (todos los tipos) cron Cada ejecución Cron (de sesión principal y aislada) silent
Operaciones de la CLI cli Comandos openclaw agent que se ejecutan a través del Gateway silent
Trabajos multimedia del agente cli Ejecuciones con respaldo de sesión de music_generate/video_generate silent
Valores predeterminados de notificación para Cron y multimedia

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

Las ejecuciones con respaldo de sesión de music_generate y video_generate también usan la política de notificación silent. Siguen creando registros de tareas, pero la finalización se devuelve a la sesión de agente original como una activación interna para que el agente pueda escribir el mensaje de seguimiento y adjuntar por sí mismo el contenido multimedia terminado. Las finalizaciones de grupo/canal siguen la política normal de respuesta visible, por lo que el agente usa la herramienta de mensajes cuando la entrega de origen lo requiere. Si el agente de finalización no produce evidencia de entrega mediante la herramienta de mensajes en una ruta solo de herramientas, OpenClaw envía la reserva de finalización directamente al canal original en lugar de dejar el contenido multimedia privado.

Límite de seguridad para video_generate concurrente

Mientras una tarea video_generate con respaldo de sesión siga activa, la herramienta también actúa como límite de seguridad: las llamadas repetidas a video_generate en esa misma sesión devuelven el estado de la tarea activa en lugar de iniciar una segunda generación concurrente. Usa action: "status" cuando quieras una consulta 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 de /command

Ciclo de vida de una 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 Qué significa
queued Creada, esperando a que el agente empiece
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 runtime perdió el estado de respaldo autoritativo después de un periodo de gracia de 5 minutos

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

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

lost es consciente del runtime:

  • Tareas ACP: desaparecieron los metadatos de la sesión ACP hija de respaldo.
  • Tareas de subagente: la sesión hija de respaldo desapareció del almacén del agente de destino.
  • Tareas Cron: el runtime de Cron ya no rastrea el trabajo como activo y el historial durable de ejecuciones Cron no muestra un resultado terminal para esa ejecución. La auditoría de la CLI sin conexión no trata su propio estado vacío del runtime Cron en proceso como autoridad.
  • Tareas de la CLI: las tareas de sesión hija aislada usan la sesión hija; las tareas de la CLI con respaldo de chat usan en cambio el contexto de ejecución activo, por lo que las filas persistentes de sesión de canal/grupo/directa no las mantienen activas. Las ejecuciones openclaw agent con respaldo del Gateway también finalizan desde su resultado de ejecución, por lo que las ejecuciones completadas no permanecen activas hasta que el barrendero las marca como lost.

Entrega y notificaciones

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

Entrega directa: si la tarea tiene un destino de canal (el requesterOrigin), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Para las finalizaciones de subagentes, OpenClaw también conserva el enrutamiento de hilo/tema vinculado cuando está disponible y puede completar un to / cuenta faltante desde la ruta almacenada de la sesión solicitante (lastChannel / lastTo / lastAccountId) antes de renunciar a la entrega directa.

Entrega encolada en sesión: si la entrega directa falla o no hay ningún origen definido, la actualización se encola como evento de sistema en la sesión del solicitante y aparece en el siguiente Heartbeat.

Esto significa que el flujo de trabajo habitual se basa en envío: inicia el trabajo desacoplado una vez y luego deja que el runtime te despierte o notifique al finalizar. Sondea el estado de la tarea solo cuando necesites depuración, intervención o una auditoría explícita.

Políticas de notificación

Controla cuánto recibes sobre cada tarea:

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

Cambia la política mientras una tarea está en ejecución:

openclaw tasks notify <lookup> state_changes

Referencia de la CLI

tasks list 
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]

Columnas de salida: ID de tarea, tipo, estado, entrega, ID de ejecución, sesión hija, resumen.

tasks show 
openclaw tasks show <lookup>

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

tasks cancel 
openclaw tasks cancel <lookup>

Para tareas ACP y de subagente, esto elimina la sesión hija. Para tareas rastreadas por la CLI, la cancelación se registra en el registro de tareas (no hay un identificador de runtime hijo separado). El estado pasa a cancelled y se envía una notificación de entrega cuando corresponde.

tasks notify 
openclaw tasks notify <lookup> <done_only|state_changes|silent>
tasks audit 
openclaw tasks audit [--json]

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

Hallazgo Gravedad 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 warn/error La propiedad de la tarea respaldada por el runtime desapareció; las tareas perdidas retenidas advierten hasta cleanupAfter y luego se convierten en errores
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 Infracción de la línea de tiempo (por ejemplo, terminó antes de empezar)
tasks maintenance 
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]

Usa esto para previsualizar o aplicar la conciliación, el marcado de limpieza y la depuración para las tareas y el estado de Task Flow.

La conciliación tiene en cuenta el runtime:

  • Las tareas de ACP/subagente comprueban su sesión secundaria de respaldo.
  • Las tareas de subagente cuya sesión secundaria tiene una lápida de recuperación tras reinicio se marcan como perdidas en lugar de tratarse como sesiones de respaldo recuperables.
  • Las tareas Cron comprueban si el runtime de cron aún posee el trabajo, luego recuperan el estado terminal a partir de los registros persistidos de ejecuciones de cron/estado del trabajo antes de recurrir a lost. Solo el proceso Gateway es autoritativo para el conjunto de trabajos activos de cron en memoria; la auditoría de CLI sin conexión usa historial duradero, pero no marca una tarea Cron como perdida únicamente porque ese Set local esté vacío.
  • Las tareas de CLI respaldadas por chat comprueban el contexto de ejecución en vivo propietario, no solo la fila de sesión de chat.

La limpieza de finalización también tiene en cuenta el runtime:

  • La finalización de subagente cierra, con el mejor esfuerzo, las pestañas/procesos de navegador rastreados para la sesión secundaria antes de que continúe la limpieza de anuncio.
  • La finalización de Cron aislado cierra, con el mejor esfuerzo, las pestañas/procesos de navegador rastreados para la sesión de cron antes de que la ejecución se desmonte por completo.
  • La entrega de Cron aislado espera el seguimiento de subagentes descendientes cuando es necesario y suprime el texto obsoleto de acuse de recibo del padre en lugar de anunciarlo.
  • La entrega de finalización de subagente prefiere el texto visible más reciente del asistente; si está vacío, recurre al texto saneado más reciente de herramienta/toolResult, y las ejecuciones de llamadas a herramientas que solo agotan el tiempo de espera pueden reducirse a un breve resumen de progreso parcial. Las ejecuciones terminales fallidas anuncian el estado de fallo sin reproducir el texto de respuesta capturado.
  • Los fallos 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>

Usa estos comandos cuando el Task Flow orquestador es lo que te importa, en lugar de un registro individual de tarea en segundo plano.

Tablero de tareas de 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 tareas activas y completadas recientemente con runtime, estado, tiempos y progreso o detalles de error.

Cuando la sesión actual no tiene tareas vinculadas visibles, /tasks recurre a conteos de tareas locales del agente para que sigas obteniendo una vista general sin filtrar detalles de otras sesiones.

Para el registro operativo completo, 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

El resumen informa:

  • active - conteo de queued + running
  • failures - conteo 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 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 centrada en lo que importa ahora.

Almacenamiento y mantenimiento

Dónde viven las tareas

Los registros de tareas persisten en SQLite en:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

El registro se carga en memoria al iniciar el gateway y sincroniza las escrituras con SQLite para garantizar durabilidad entre reinicios. El Gateway mantiene acotado el registro de escritura anticipada de SQLite usando el umbral predeterminado de autocheckpoint de SQLite, además de puntos de control TRUNCATE periódicos y al apagar.

Mantenimiento automático

Un barrido se ejecuta cada 60 segundos y gestiona cuatro cosas:

  • Reconciliation

    Comprueba si las tareas activas todavía tienen respaldo autoritativo de runtime. Las tareas de ACP/subagente usan el estado de sesión secundaria, las tareas Cron usan la propiedad de trabajos activos y las tareas de CLI respaldadas por 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.

  • ACP session repair

    Cierra sesiones ACP one-shot terminales o huérfanas propiedad del padre, y cierra sesiones ACP persistentes terminales obsoletas o huérfanas solo cuando no queda ningún enlace de conversación activo.

  • Cleanup stamping

    Establece una marca de tiempo cleanupAfter en 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 vence cleanupAfter o cuando faltan metadatos de limpieza, son errores.

  • Pruning

    Elimina registros posteriores a su fecha cleanupAfter.

    • Cómo se relacionan las tareas con otros sistemas

    Tasks and Task Flow

    Task Flow es la capa de orquestación de flujos por encima de las tareas en segundo plano. Un solo flujo puede coordinar varias tareas durante su vida útil usando modos de sincronización gestionados o reflejados. Usa openclaw tasks para inspeccionar registros de tareas individuales y openclaw tasks flow para inspeccionar el flujo orquestador.

    Consulta Task Flow para más detalles.

    Tasks and cron

    Una definición de trabajo de cron vive en ~/.openclaw/cron/jobs.json; el estado de ejecución del runtime vive junto a ella en ~/.openclaw/cron/jobs-state.json. Cada ejecución de cron crea un registro de tarea, tanto de sesión principal como aislada. Las tareas Cron de sesión principal usan de forma predeterminada la política de notificación silent, de modo que se rastrean sin generar notificaciones.

    Consulta Trabajos Cron.

    Tasks and heartbeat

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

    Consulta Heartbeat.

    Tasks and sessions

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

    Tasks and agent runs

    El runId de una tarea enlaza con la ejecución del agente que hace el trabajo. Los eventos del ciclo de vida del agente (inicio, fin, error) actualizan automáticamente el estado de la tarea; no necesitas gestionar el ciclo de vida manualmente.

    Relacionado