Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

¿Buscas programación? Consulta Automatización para elegir el mecanismo adecuado. Esta página es el registro de actividad del trabajo en segundo plano, no el programador.
Las tareas en segundo plano registran el trabajo que se ejecuta fuera de tu sesión principal de conversación: ejecuciones de ACP, creaciones de subagentes, ejecuciones aisladas de trabajos cron y operaciones iniciadas desde la CLI. Las tareas no sustituyen a las sesiones, los trabajos cron ni los heartbeats: son el registro de actividad que documenta qué trabajo desacoplado ocurrió, cuándo y si tuvo éxito.
No toda ejecución de agente crea una tarea. Los turnos de heartbeat y el chat interactivo normal no lo hacen. Todas las ejecuciones cron, creaciones de ACP, creaciones de subagentes y comandos de agente de la CLI sí lo hacen.

​
TL;DR

  • 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 aún posee el trabajo; si el estado del runtime en memoria ya no existe, el mantenimiento de tareas primero revisa el historial duradero de ejecuciones cron antes de marcar una tarea como perdida.
  • La finalización se impulsa por notificaciones push: el trabajo desacoplado puede notificar directamente o despertar la sesión/heartbeat solicitante cuando termina, por lo que los bucles de sondeo de estado suelen tener una forma inadecuada.
  • Las ejecuciones cron aisladas y las finalizaciones de subagentes intentan, en la medida de lo posible, limpiar pestañas/procesos de navegador registrados 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 aún se está drenando, 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 expone 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

​
Qué crea una tarea

OrigenTipo de runtimeCuándo se crea un registro de tareaPolítica de notificación predeterminada
Ejecuciones en segundo plano de ACPacpAl crear una sesión hija de ACPdone_only
Orquestación de subagentessubagentAl crear un subagente mediante sessions_spawndone_only
Trabajos Cron (todos los tipos)cronCada ejecución cron (sesión principal y aislada)silent
Operaciones de la CLIcliComandos openclaw agent que se ejecutan a través del Gatewaysilent
Trabajos multimedia del agentecliEjecuciones music_generate/video_generate respaldadas por sesiónsilent
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 usan silent de forma predeterminada, pero son más visibles porque se ejecutan en su propia sesión.Las ejecuciones music_generate y video_generate respaldadas por sesión también usan la política de notificación silent. Aun así crean registros de tarea, pero la finalización se devuelve a la sesión original del agente como un despertar interno para que el agente pueda escribir el mensaje de seguimiento y adjuntar el contenido multimedia terminado por sí mismo. Las finalizaciones en grupos/canales 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 con la herramienta de mensajes en una ruta solo de herramientas, OpenClaw envía la alternativa de finalización directamente al canal original en lugar de dejar el contenido multimedia privado.
Mientras una tarea video_generate respaldada por sesión siga activa, la herramienta también actúa como protección: 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.
  • Turnos de Heartbeat: sesión principal; consulta Heartbeat
  • Turnos normales de chat interactivo
  • Respuestas directas de /command

​
Ciclo de vida de la tarea

EstadoQué significa
queuedCreada, en espera de que el agente se inicie
runningEl turno del agente se está ejecutando activamente
succeededCompletada correctamente
failedCompletada con un error
timed_outSuperó el tiempo de espera configurado
cancelledDetenida por el operador mediante openclaw tasks cancel
lostEl runtime perdió el estado de respaldo autoritativo tras un período de gracia de 5 minutos
Las transiciones ocurren automáticamente: cuando termina la ejecución de agente asociada, el estado de la tarea se actualiza para coincidir. La finalización de la ejecución de agente es autoritativa para los registros de tareas activas. Una ejecución desacoplada exitosa finaliza como succeeded, los errores ordinarios de ejecución finalizan como failed y los resultados de tiempo de espera o interrupció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 tiene en cuenta el runtime:
  • Tareas ACP: desaparecieron los metadatos de respaldo de la sesión hija de ACP.
  • 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 registra el trabajo como activo y el historial duradero 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 de cron en proceso como autoridad.
  • Tareas de la CLI: las tareas con un id de ejecución/id de origen usan el contexto de ejecución en vivo, por lo que las filas persistentes de sesión hija o sesión de chat no las mantienen activas después de que desaparece la ejecución propiedad del Gateway. Las tareas heredadas de la CLI sin identidad de ejecución aún recurren a la sesión hija. Las ejecuciones openclaw agent respaldadas por Gateway también finalizan a partir de su resultado de ejecución, por lo que las ejecuciones completadas no permanecen activas hasta que el proceso de barrido 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.). En cambio, las finalizaciones de tareas de grupo y canal se enrutan a través de la sesión solicitante para que el agente padre pueda escribir la respuesta visible. Para las finalizaciones de subagentes, OpenClaw también preserva el enrutamiento vinculado de hilo/tema cuando está disponible y puede rellenar un to / cuenta faltante desde la ruta almacenada de la sesión solicitante (lastChannel / lastTo / lastAccountId) antes de desistir de 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 heartbeat.
La finalización de una tarea activa un despertar inmediato de heartbeat para que veas el resultado rápidamente; no tienes que esperar al siguiente tick de heartbeat programado.
Esto significa que el flujo de trabajo habitual se basa en push: 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 se te informa sobre cada tarea:
PolíticaQué se entrega
done_only (predeterminado)Solo estado terminal (succeeded, failed, etc.): este es el valor predeterminado
state_changesCada transición de estado y actualización de progreso
silentNada en absoluto
Cambia la política mientras una tarea está en ejecución: 
openclaw tasks notify <lookup> state_changes

​
Referencia de la CLI

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.
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.
openclaw tasks cancel <lookup>
Para tareas ACP y de subagente, esto termina la sesión hija. Para tareas registradas por la CLI, la cancelación se registra en el registro de tareas (no hay un identificador de runtime hijo separado). El estado cambia a cancelled y se envía una notificación de entrega cuando corresponde.
openclaw tasks notify <lookup> <done_only|state_changes|silent>

openclaw tasks audit [--json]
Expone problemas operativos. Los hallazgos también aparecen en openclaw status cuando se detectan problemas.
HallazgoGravedadActivador
stale_queuedwarnEn cola durante más de 10 minutos
stale_runningerrorEn ejecución durante más de 30 minutos
lostwarn/errorLa propiedad de la tarea respaldada por el runtime desapareció; las tareas perdidas retenidas advierten hasta cleanupAfter, luego se convierten en errores
delivery_failedwarnLa entrega falló y la política de notificación no es silent
missing_cleanupwarnTarea terminal sin marca de tiempo de limpieza
inconsistent_timestampswarnInfracción de la línea de tiempo (por ejemplo, terminó antes de empezar)
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
Usa esto para previsualizar o aplicar la reconciliación, el marcado de limpieza y la depuración de tareas, el estado de Task Flow y las filas obsoletas del registro de sesiones de ejecuciones cron.La reconciliación tiene en cuenta el runtime:
  • Las tareas ACP/subagent comprueban su sesión secundaria subyacente.
  • Las tareas de subagent cuya sesión secundaria tiene una lápida de recuperación tras reinicio se marcan como perdidas en lugar de tratarse como sesiones subyacentes recuperables.
  • Las tareas Cron comprueban si el runtime cron todavía posee el trabajo y luego recuperan el estado terminal de los registros persistidos de ejecuciones cron/estado del trabajo antes de recurrir a lost. Solo el proceso Gateway es autoritativo para el conjunto en memoria de trabajos cron activos; la auditoría offline de CLI usa historial duradero, pero no marca una tarea cron como perdida solo porque ese Set local esté vacío.
  • Las tareas CLI con identidad de ejecución comprueban el contexto de ejecución en vivo propietario, no solo las filas de sesión secundaria o sesión de chat.
La limpieza de finalización también tiene en cuenta el runtime:
  • La finalización de subagent cierra por mejor esfuerzo las pestañas/procesos de navegador rastreados de la sesión secundaria antes de que continúe la limpieza del anuncio.
  • La finalización de cron aislado cierra por mejor esfuerzo las pestañas/procesos de navegador rastreados de la sesión cron antes de que la ejecución se desmonte por completo.
  • La entrega de cron aislado espera el seguimiento de subagent 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 subagent 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 solo con timeout de llamadas de herramienta pueden contraerse en un resumen breve 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.
Al aplicar mantenimiento, OpenClaw también elimina las filas obsoletas del registro de sesiones cron:<jobId>:run:<uuid> con más de 7 días, conservando las filas de trabajos cron actualmente en ejecución y dejando intactas las filas de sesiones que no son cron.
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
Usa estos comandos cuando lo que te importa es el Task Flow orquestador, 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 las tareas activas y completadas recientemente con runtime, estado, tiempos y detalles 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 obteniendo 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
El resumen informa:
  • 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 que tiene en cuenta 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 mismo.

​
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 ofrecer durabilidad entre reinicios. El Gateway mantiene acotado el registro de escritura adelantada de SQLite usando el umbral predeterminado de autocheckpoint de SQLite, además de checkpoints TRUNCATE periódicos y durante el apagado.

​
Mantenimiento automático

Un barrendero se ejecuta cada 60 segundos y gestiona cuatro cosas:
1

Reconciliación

Comprueba si las tareas activas todavía tienen respaldo autoritativo del runtime. Las tareas ACP/subagent usan el estado de sesión secundaria, las tareas cron usan la propiedad de trabajos activos y las tareas CLI con identidad de ejecución usan el contexto de ejecución propietario. Si ese estado subyacente desaparece durante más de 5 minutos, la tarea se marca como lost.
2

Reparación de sesiones ACP

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.
3

Marcado de limpieza

Establece una marca de tiempo cleanupAfter en tareas terminales (endedAt + 7 días). Durante la retención, las tareas perdidas siguen apareciendo en la auditoría como advertencias; después de que caduque cleanupAfter o cuando falten metadatos de limpieza, son errores.
4

Depuración

Elimina registros posteriores a su fecha cleanupAfter.
Retención: los registros de tareas terminales se conservan durante 7 días y luego se depuran automáticamente. No se requiere configuración.

​
Cómo se relacionan las tareas con otros sistemas

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 ciclo de vida usando modos de sincronización gestionados o reflejados. Usa openclaw tasks para inspeccionar registros individuales de tareas y openclaw tasks flow para inspeccionar el flujo orquestador.Consulta Task Flow para obtener más detalles.
Una definición de trabajo 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 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, por lo que se rastrean sin generar notificaciones.Consulta Trabajos Cron.
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.
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 encima de eso.
El runId de una tarea enlaza con la ejecución del agente que realiza el trabajo. Los eventos de 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