Tâches en arrière-plan

Les tâches en arrière-plan suivent les travaux exécutés en dehors de votre session de conversation principale : exécutions ACP, lancements de sous-agents, exécutions de tâches Cron et opérations lancées depuis la CLI.

Les tâches ne remplacent ni les sessions, ni les tâches Cron, ni les Heartbeats : elles constituent le registre d’activité qui consigne les travaux détachés effectués, leur date et leur réussite éventuelle.

En bref

• Les tâches sont des enregistrements, pas des planificateurs : Cron et Heartbeat déterminent quand les travaux s’exécutent, tandis que les tâches suivent ce qui s’est passé.
• ACP, les sous-agents, toutes les tâches Cron et les opérations de la CLI créent des tâches. Les tours de Heartbeat n’en créent pas.
• Chaque tâche passe par les états queued → running → terminal (succeeded, failed, timed_out, cancelled ou lost).
• Les tâches Cron restent actives tant que le moteur d’exécution Cron possède encore la tâche ; si l’état d’exécution en mémoire a disparu, la maintenance des tâches vérifie d’abord l’historique persistant des exécutions Cron avant de marquer une tâche comme perdue.
• La fin d’une tâche est signalée par envoi automatique : les travaux détachés peuvent envoyer directement une notification ou réveiller la session ou le Heartbeat du demandeur à leur achèvement. Les boucles d’interrogation de l’état sont donc généralement inadaptées.
• Lors du nettoyage final, les exécutions Cron isolées et les sous-agents terminés tentent, dans la mesure du possible, de fermer les onglets et processus de navigateur suivis pour leur session enfant.
• La distribution des exécutions Cron isolées masque les réponses intermédiaires obsolètes du parent tant que les travaux des sous-agents descendants ne sont pas tous terminés, et privilégie la sortie finale d’un descendant lorsqu’elle arrive avant la distribution.
• Les notifications de fin sont envoyées directement à un canal ou placées en attente jusqu’au prochain Heartbeat.
• openclaw tasks list affiche toutes les tâches ; openclaw tasks audit signale les problèmes.
• Les enregistrements terminaux sont conservés pendant 7 jours, contre 24 heures pour les enregistrements lost, puis automatiquement supprimés.

Démarrage rapide

# 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>

Éléments qui créent une tâche

Cycle de vie d’une tâche

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

Les transitions se produisent automatiquement : les événements du cycle de vie de l’exécution de l’agent — démarrage, fin et erreur — mettent à jour l’état de la tâche. Vous ne le gérez pas manuellement.

La fin de l’exécution de l’agent fait autorité pour les enregistrements de tâche actifs. Une exécution détachée réussie se termine à l’état succeeded, une erreur d’exécution ordinaire à l’état failed, un dépassement de délai à l’état timed_out et une annulation ou interruption à l’état cancelled. Lorsqu’une tâche a atteint un état terminal, les signaux ultérieurs du cycle de vie ne peuvent pas dégrader son état : une tâche annulée par un opérateur ou déjà à l’état failed, timed_out ou lost conserve cet état, même si un signal de réussite arrive ensuite.

L’état lost dépend du moteur d’exécution :

• Tâches ACP : seul un tour ACP actif dans le processus du Gateway prouve que l’exécution est encore en cours ; les métadonnées de session persistantes ne suffisent pas. L’audit hors ligne de la CLI reste prudent et ne récupère jamais les tâches ACP.
• Tâches de sous-agent : la session enfant sous-jacente a disparu du stockage de l’agent cible, ou contient une pierre tombale de récupération après redémarrage.
• Tâches Cron : le moteur d’exécution Cron ne suit plus la tâche comme étant active et l’historique persistant des exécutions Cron ne contient aucun résultat terminal pour cette exécution. L’audit hors ligne de la CLI ne considère pas son propre état vide du moteur Cron en mémoire comme faisant autorité.
• Tâches de la CLI : les tâches dotées d’un identifiant d’exécution ou d’un identifiant source utilisent le contexte d’exécution actif. Ainsi, les lignes persistantes d’une session enfant ou de conversation ne les maintiennent pas actives après la disparition de l’exécution gérée par le Gateway. Les anciennes tâches de la CLI dépourvues d’identité d’exécution continuent de se rabattre sur la session enfant. Les exécutions openclaw agent prises en charge par le Gateway sont également finalisées à partir du résultat de leur exécution ; les exécutions terminées ne restent donc pas actives jusqu’à ce que le processus de nettoyage les marque comme lost.

Distribution et notifications

Lorsqu’une tâche atteint un état terminal, OpenClaw vous en informe. Deux chemins de distribution sont possibles :

Distribution directe : si la tâche possède une cible de canal, définie par requesterOrigin, le message d’achèvement est directement envoyé à ce canal, par exemple Discord, Slack ou Telegram. Les achèvements de tâches de groupe et de canal sont plutôt acheminés par la session du demandeur, afin que l’agent parent puisse rédiger la réponse visible. Pour les achèvements de sous-agents, OpenClaw conserve également, lorsqu’il est disponible, le routage lié au fil de discussion ou au sujet. Il peut aussi compléter un champ to ou un compte manquant à partir du routage enregistré dans la session du demandeur (lastChannel / lastTo / lastAccountId) avant de renoncer à la distribution directe.

Distribution mise en file d’attente dans la session : si la distribution directe échoue ou si aucune origine n’est définie, la mise à jour est placée en file d’attente sous forme d’événement système dans la session du demandeur et apparaît au prochain Heartbeat.

Le flux de travail habituel repose donc sur l’envoi automatique : lancez une seule fois le travail détaché, puis laissez le moteur d’exécution vous réveiller ou vous avertir à son achèvement. N’interrogez l’état des tâches que pour le débogage, une intervention ou un audit explicite.

Politiques de notification

Contrôlez la quantité d’informations reçues pour chaque tâche :

Modifiez la politique pendant l’exécution d’une tâche :

openclaw tasks notify <lookup> state_changes

Référence 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>

Tableau des tâches de discussion (/tasks)

Utilisez /tasks dans n’importe quelle session de discussion pour afficher les tâches en arrière-plan liées à cette session. Le tableau affiche jusqu’à cinq tâches actives ou récemment terminées, avec leur environnement d’exécution, leur état, leurs données temporelles ainsi que les détails de progression ou d’erreur.

Lorsque la session actuelle ne comporte aucune tâche liée visible, /tasks utilise à la place les nombres de tâches locales de l’agent afin de fournir tout de même une vue d’ensemble sans divulguer les détails d’autres sessions.

Pour consulter le registre complet destiné aux opérateurs, utilisez la CLI : openclaw tasks list.

Interface de contrôle

L’interface de contrôle web comporte une page Tâches dans la barre latérale, avec les tâches en arrière-plan actives et récentes mises à jour en direct. Utilisez-la pour examiner la progression, ouvrir les sessions liées, actualiser le registre ou annuler les tâches en file d’attente et en cours d’exécution.

Les volets de discussion comportent également un panneau réductible Tâches en arrière-plan, limité à l’agent du volet : tâches et sous-agents en cours avec une commande d’arrêt, une section des éléments terminés et des liens Afficher la transcription vers la session enfant de chaque tâche. Ouvrez-le depuis le bouton d’activité dans l’en-tête du volet, ou depuis le bouton d’activité flottant dans une discussion à volet unique.

Intégration à l’état (charge des tâches)

openclaw status comprend une ligne offrant un aperçu des tâches :

Tasks    2 active · 1 queued · 1 running · 1 issue · audit clean · 6 tracked

Le récapitulatif compte les travaux actifs (queued + running), les échecs (failed + timed_out + lost), les constats d’audit et le nombre total d’enregistrements suivis ; la charge utile JSON ventile également les nombres par environnement d’exécution (acp, subagent, cron, cli).

/status et l’outil session_status utilisent tous deux un instantané des tâches tenant compte du nettoyage : les tâches actives sont privilégiées, les lignes expirées sont masquées et les tâches terminales n’apparaissent que pendant une courte période récente de 5 minutes, avec une priorité accordée aux échecs lorsqu’il ne reste aucun travail actif. Ainsi, la fiche d’état reste centrée sur ce qui importe actuellement.

Stockage et maintenance

Emplacement des tâches

Les enregistrements des tâches et l’état de remise persistent dans la base de données d’état SQLite partagée d’OpenClaw :

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

Définissez OPENCLAW_STATE_DIR pour déplacer l’ensemble de la racine d’état, située par défaut dans ~/.openclaw, vers un autre emplacement ; le chemin de la base de données partagée est déplacé avec elle.

Le registre est chargé en mémoire à la première utilisation et chaque écriture est persistée dans SQLite, ce qui permet aux enregistrements de survivre aux redémarrages du Gateway. La croissance du journal WAL reste limitée grâce au seuil de point de contrôle automatique par défaut de SQLite et à des points de contrôle PASSIVE périodiques ; les points de contrôle effectués à l’arrêt et lors d’une maintenance explicite utilisent TRUNCATE, afin que les fermetures normales récupèrent l’espace WAL sans obliger le processus de nettoyage en arrière-plan à attendre les lecteurs actifs.

Les anciens magasins annexes provenant d’installations antérieures (tasks/runs.sqlite, flows/registry.sqlite) sont importés dans la base de données partagée par openclaw doctor.

Maintenance automatique

Un processus de nettoyage s’exécute toutes les 60 secondes — le premier passage a lieu environ 5 secondes après le démarrage du Gateway — et gère quatre opérations :

Relations entre les tâches et les autres systèmes

Voir aussi

• Automatisation - tous les mécanismes d’automatisation en un coup d’œil
• CLI : tâches - référence des commandes de la CLI
• Heartbeat - tours périodiques de la session principale
• Tâches planifiées - planification du travail en arrière-plan
• Flux de tâches - orchestration des flux au-dessus des tâches