Hintergrundaufgaben

Hintergrundaufgaben erfassen Arbeit, die außerhalb Ihrer Haupt-Konversationssitzung ausgeführt wird: ACP-Ausführungen, das Starten von Subagenten, Cron-Job-Ausführungen und über die CLI gestartete Vorgänge.

Aufgaben ersetzen weder Sitzungen noch Cron-Jobs oder Heartbeats – sie sind das Aktivitätsprotokoll, das aufzeichnet, welche entkoppelte Arbeit wann ausgeführt wurde und ob sie erfolgreich war.

Kurzfassung

• Aufgaben sind Datensätze, keine Scheduler – Cron und Heartbeat bestimmen, wann Arbeit ausgeführt wird; Aufgaben erfassen, was geschehen ist.
• ACP, Subagenten, alle Cron-Jobs und CLI-Vorgänge erstellen Aufgaben. Heartbeat-Durchläufe tun dies nicht.
• Jede Aufgabe durchläuft queued → running → terminal (erfolgreich, fehlgeschlagen, Zeitüberschreitung, abgebrochen oder verloren).
• Cron-Aufgaben bleiben aktiv, solange die Cron-Laufzeit noch für den Job zuständig ist. Wenn der Laufzeitstatus im Arbeitsspeicher nicht mehr vorhanden ist, prüft die Aufgabenwartung zunächst den dauerhaften Cron-Ausführungsverlauf, bevor sie eine Aufgabe als verloren markiert.
• Abschlüsse werden per Push gemeldet: Entkoppelte Arbeit kann nach Abschluss direkt benachrichtigen oder die anfordernde Sitzung beziehungsweise den Heartbeat aktivieren. Schleifen zur Statusabfrage sind daher normalerweise der falsche Ansatz.
• Isolierte Cron-Ausführungen und abgeschlossene Subagenten versuchen vor der abschließenden Bereinigung der Verwaltungsdaten, nach bestem Bemühen die verfolgten Browser-Tabs und Prozesse ihrer untergeordneten Sitzung zu bereinigen.
• Bei isolierter Cron-Zustellung werden veraltete vorläufige Antworten der übergeordneten Sitzung unterdrückt, solange nachgelagerte Subagent-Arbeit noch ausläuft. Trifft die endgültige Ausgabe eines Nachfolgers vor der Zustellung ein, wird diese bevorzugt.
• Abschlussbenachrichtigungen werden direkt an einen Kanal zugestellt oder für den nächsten Heartbeat in die Warteschlange gestellt.
• openclaw tasks list zeigt alle Aufgaben an; openclaw tasks audit hebt Probleme hervor.
• Abgeschlossene Datensätze werden 7 Tage lang aufbewahrt (lost-Datensätze 24 Stunden) und anschließend automatisch bereinigt.

Schnellstart

# Alle Aufgaben auflisten (neueste zuerst)openclaw tasks list # Nach Laufzeit oder Status filternopenclaw tasks list --runtime acpopenclaw tasks list --status running

# Details zu einer bestimmten Aufgabe anzeigen (nach Aufgaben-ID, Ausführungs-ID oder Sitzungsschlüssel)openclaw tasks show <lookup>

# Eine laufende Aufgabe abbrechen (beendet die untergeordnete Sitzung)openclaw tasks cancel <lookup> # Benachrichtigungsrichtlinie für eine Aufgabe ändernopenclaw tasks notify <lookup> state_changes

# Zustandsprüfung ausführenopenclaw tasks audit # Wartung in der Vorschau anzeigen oder anwendenopenclaw tasks maintenanceopenclaw tasks maintenance --apply

# TaskFlow-Status prüfenopenclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

Was eine Aufgabe erstellt

Aufgabenlebenszyklus

stateDiagram-v2
    [*] --> queued
    queued --> running : Agent startet
    running --> succeeded : erfolgreich abgeschlossen
    running --> failed : Fehler
    running --> timed_out : Zeitlimit überschritten
    queued --> cancelled : Bediener bricht ab
    running --> cancelled : Bediener bricht ab
    queued --> lost : zugrunde liegender Status seit > 5 Min. nicht vorhanden
    running --> lost : zugrunde liegender Status seit > 5 Min. nicht vorhanden

Übergänge erfolgen automatisch – Lebenszyklusereignisse der Agentenausführung (Start, Ende, Fehler) aktualisieren den Aufgabenstatus; Sie verwalten ihn nicht manuell.

Der Abschluss einer Agentenausführung ist für aktive Aufgabendatensätze maßgeblich. Eine erfolgreiche entkoppelte Ausführung wird als succeeded abgeschlossen, gewöhnliche Ausführungsfehler als failed, Zeitüberschreitungen als timed_out und Abbruchergebnisse als cancelled. Sobald eine Aufgabe einen Endstatus erreicht hat, wird sie durch spätere Lebenszyklussignale nicht herabgestuft – eine vom Bediener abgebrochene oder bereits als failed/timed_out/lost markierte Aufgabe behält diesen Status, selbst wenn danach ein Erfolgssignal eintrifft.

lost berücksichtigt die Laufzeit:

• ACP-Aufgaben: Nur ein aktiver prozessinterner ACP-Durchlauf im Gateway belegt, dass die Ausführung noch aktiv ist; dauerhaft gespeicherte Sitzungsmetadaten allein reichen nicht aus. Die Offline-CLI-Prüfung bleibt konservativ und reklamiert ACP-Aufgaben niemals zurück.
• Subagent-Aufgaben: Die zugrunde liegende untergeordnete Sitzung ist aus dem Speicher des Zielagenten verschwunden oder enthält eine Tombstone-Markierung für die Wiederherstellung nach einem Neustart.
• Cron-Aufgaben: Die Cron-Laufzeit verfolgt den Job nicht mehr als aktiv, und der dauerhafte Cron-Ausführungsverlauf enthält kein Endergebnis für diese Ausführung. Die Offline-CLI-Prüfung betrachtet ihren eigenen leeren prozessinternen Cron-Laufzeitstatus nicht als maßgeblich.
• CLI-Aufgaben: Aufgaben mit Ausführungs-ID/Quell-ID verwenden den aktiven Ausführungskontext. Daher halten verbleibende Datensätze untergeordneter Sitzungen oder Chatsitzungen sie nicht aktiv, nachdem die vom Gateway verwaltete Ausführung verschwunden ist. Ältere CLI-Aufgaben ohne Ausführungsidentität greifen weiterhin auf die untergeordnete Sitzung zurück. Gateway-gestützte openclaw agent-Ausführungen werden ebenfalls anhand ihres Ausführungsergebnisses abgeschlossen, sodass abgeschlossene Ausführungen nicht aktiv bleiben, bis der Bereinigungsprozess sie als lost markiert.

Zustellung und Benachrichtigungen

Wenn eine Aufgabe einen Endstatus erreicht, benachrichtigt OpenClaw Sie. Dafür gibt es zwei Zustellungswege:

Direkte Zustellung – Wenn die Aufgabe ein Kanalziel (requesterOrigin) hat, wird die Abschlussnachricht direkt an diesen Kanal gesendet (Discord, Slack, Telegram usw.). Abschlüsse von Gruppen- und Kanalaufgaben werden stattdessen über die anfordernde Sitzung geleitet, damit der übergeordnete Agent die sichtbare Antwort verfassen kann. Bei Abschlüssen von Subagenten bewahrt OpenClaw außerdem gebundene Thread-/Themen-Routen, sofern verfügbar, und kann fehlende to-/Kontoinformationen aus der gespeicherten Route der anfordernden Sitzung (lastChannel / lastTo / lastAccountId) ergänzen, bevor die direkte Zustellung aufgegeben wird.

Zustellung über die Sitzungswarteschlange – Wenn die direkte Zustellung fehlschlägt oder kein Ursprung festgelegt ist, wird die Aktualisierung als Systemereignis in die Warteschlange der anfordernden Sitzung gestellt und beim nächsten Heartbeat angezeigt.

Der übliche Arbeitsablauf ist daher Push-basiert: Starten Sie entkoppelte Arbeit einmal und lassen Sie sich anschließend von der Laufzeit bei Abschluss aktivieren oder benachrichtigen. Fragen Sie den Aufgabenstatus nur ab, wenn Sie Fehler untersuchen, eingreifen oder eine ausdrückliche Prüfung durchführen müssen.

Benachrichtigungsrichtlinien

Steuern Sie, wie viele Meldungen Sie zu jeder Aufgabe erhalten:

Ändern Sie die Richtlinie, während eine Aufgabe ausgeführt wird:

openclaw tasks notify <lookup> state_changes

CLI-Referenz

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>

Chat-Aufgabenübersicht (/tasks)

Verwenden Sie /tasks in einer beliebigen Chatsitzung, um die mit dieser Sitzung verknüpften Hintergrundaufgaben anzuzeigen. Die Übersicht zeigt bis zu fünf aktive und kürzlich abgeschlossene Aufgaben mit Laufzeit, Status, Zeitangaben sowie Fortschritts- oder Fehlerdetails.

Wenn die aktuelle Sitzung keine sichtbaren verknüpften Aufgaben enthält, greift /tasks auf agentenlokale Aufgabenzahlen zurück, damit Sie weiterhin einen Überblick erhalten, ohne Details anderer Sitzungen offenzulegen.

Verwenden Sie für das vollständige Betriebsprotokoll die CLI: openclaw tasks list.

Control UI

Die Web-Control-UI enthält in der Seitenleiste eine Seite Aufgaben mit aktiven und kürzlich abgeschlossenen Hintergrundaufgaben in Echtzeit. Verwenden Sie sie, um den Fortschritt zu prüfen, verknüpfte Sitzungen zu öffnen, das Protokoll zu aktualisieren oder Aufgaben in der Warteschlange und laufende Aufgaben abzubrechen.

Chat-Bereiche verfügen außerdem über eine einklappbare Leiste Hintergrundaufgaben, deren Umfang auf den Agenten des Bereichs beschränkt ist: laufende Aufgaben und Subagents mit einer Stoppsteuerung, ein Abschnitt für abgeschlossene Aufgaben sowie Links zum Anzeigen des Transkripts der jeweiligen untergeordneten Sitzung. Öffnen Sie sie über den Aktivitätsschalter in der Kopfzeile des Bereichs (oder über die schwebende Aktivitätsschaltfläche im Einzelbereichs-Chat).

Wählen Sie eine Aufgabe in der Leiste aus, um ihre begrenzte Eingabeaufforderung und die neueste Ausgabe oder Fehlerzusammenfassung zu prüfen. Laufende Arbeiten bleiben von abgeschlossenen Arbeiten getrennt, und abgeschlossene Zeilen zeigen, ob die Aufgabe erfolgreich abgeschlossen wurde oder fehlgeschlagen ist. Öffnen Sie unter iOS Chat actions → Background Tasks; öffnen Sie unter Android das Überlaufmenü des Chats und wählen Sie Background tasks. Beide mobilen Ansichten verwenden dieselbe Gruppierung in Running und Finished und öffnen bei der Auswahl die Aufgabendetails.

Statusintegration (Aufgabenauslastung)

openclaw status enthält eine Aufgabenzeile für den schnellen Überblick:

Aufgaben    2 aktiv · 1 in Warteschlange · 1 in Ausführung · 1 Problem · Prüfung sauber · 6 verfolgt

Die Zusammenfassung zählt aktive Arbeit (queued + running), Fehlschläge (failed + timed_out + lost), Prüfungsbefunde und die Gesamtzahl der verfolgten Datensätze; die JSON-Nutzlast schlüsselt die Zahlen außerdem nach Laufzeit auf (acp, subagent, cron, cli).

Sowohl /status als auch das Tool session_status verwenden eine bereinigungsbewusste Aufgabenmomentaufnahme: Aktive Aufgaben werden bevorzugt, abgelaufene Zeilen ausgeblendet und beendete Aufgaben nur für ein kurzes aktuelles Zeitfenster (5 Minuten) angezeigt, wobei Fehlschläge hervorgehoben werden, wenn keine aktive Arbeit mehr vorhanden ist. Dadurch konzentriert sich die Statuskarte auf das, was gerade wichtig ist.

Speicherung und Wartung

Speicherort der Aufgaben

Aufgabendatensätze und Zustellungszustand bleiben in der gemeinsam genutzten OpenClaw-SQLite-Zustandsdatenbank erhalten:

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

Legen Sie OPENCLAW_STATE_DIR fest, um das gesamte Zustandsstammverzeichnis (Standard: ~/.openclaw) an einen anderen Ort zu verschieben; der Pfad der gemeinsamen Datenbank wird ebenfalls verschoben.

Die Registrierung wird bei der ersten Verwendung in den Arbeitsspeicher geladen und jede Änderung wird zurück in SQLite geschrieben, sodass Datensätze Gateway-Neustarts überstehen. Das WAL-Wachstum bleibt durch den standardmäßigen Autocheckpoint-Schwellenwert von SQLite sowie regelmäßige PASSIVE-Checkpoints begrenzt; Checkpoints beim Herunterfahren und bei expliziter Wartung verwenden TRUNCATE, damit bei normalen Schließvorgängen WAL-Speicher freigegeben wird, ohne dass die Hintergrundbereinigung auf aktive Leser warten muss.

Veraltete Sidecar-Speicher aus älteren Installationen (tasks/runs.sqlite, flows/registry.sqlite) werden durch openclaw doctor in die gemeinsame Datenbank importiert.

Automatische Wartung

Eine Bereinigung wird alle 60 Sekunden ausgeführt (der erste Durchlauf etwa 5 Sekunden nach dem Start des Gateway) und erledigt vier Aufgaben:

Beziehung von Aufgaben zu anderen Systemen

Verwandte Themen

• Automatisierung – alle Automatisierungsmechanismen auf einen Blick
• CLI: Aufgaben – Referenz der CLI-Befehle
• Heartbeat – regelmäßige Durchläufe der Hauptsitzung
• Geplante Aufgaben – Planung von Hintergrundarbeiten
• TaskFlow – Ablauf-Orchestrierung über Aufgaben hinweg