Heartbeat

Heartbeat führt in der Hauptsitzung regelmäßige Agent-Durchläufe aus, damit das Modell auf alles aufmerksam machen kann, was beachtet werden muss, ohne Sie mit Nachrichten zu überhäufen.

Heartbeat ist ein geplanter Durchlauf der Hauptsitzung – dabei werden keine Datensätze für Hintergrundaufgaben erstellt. Aufgabendatensätze sind für entkoppelte Arbeiten vorgesehen (ACP-Ausführungen, Subagenten, isolierte cron-Aufträge).

Intern wird der Heartbeat-Takt vom cron-Scheduler verwaltet: Das Gateway verwaltet für jeden Agenten mit aktiviertem Heartbeat einen systemeigenen cron-Auftrag (in openclaw cron list --all als Heartbeat (agent-id) sichtbar). Die Heartbeat-Konfiguration bleibt die Eingabe für den gewünschten Zustand, während der persistierte Überwachungszeitplan den tatsächlichen Takt und die anschließende Abkühlphase des Runners bestimmt. Das Gateway übernimmt Konfigurationsänderungen beim Start und beim erneuten Laden der Konfiguration; openclaw doctor --fix kann fehlende oder veraltete Überwachungszeilen vor dem nächsten Gateway-Start anlegen. Bearbeiten Sie agents.*.heartbeat, nicht den cron-Auftrag.

Geplante Heartbeats erfordern cron. Wenn cron.enabled den Wert false oder OPENCLAW_SKIP_CRON=1 hat, protokolliert das Gateway beim Start eine Warnung und führt keine geplanten Heartbeats aus; manuelle und ereignisgesteuerte Heartbeat-Aktivierungen bleiben verfügbar. Es gibt keinen separaten Heartbeat-Ersatz-Timer.

Fehlerbehebung: Geplante Aufgaben

Schnellstart (Einsteiger)

Beispielkonfiguration:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explizite Zustellung an den letzten Kontakt (Standard ist "none")        directPolicy: "allow", // Standard: direkte/DM-Ziele zulassen; auf "block" setzen, um sie zu unterdrücken        lightContext: true, // optional: Workspace-Bootstrap-Dateien für Heartbeat-Ausführungen überspringen        isolatedSession: true, // optional: neue Sitzung bei jeder Ausführung (kein Gesprächsverlauf)        // activeHours: { start: "08:00", end: "24:00" },      },    },  },}

Standardwerte

• Intervall: 30m. Durch Anwenden der Anthropic-Provider-Standardwerte wird dies auf 1h erhöht, wenn der ermittelte Authentifizierungsmodus OAuth/Token ist (einschließlich der Wiederverwendung der Claude CLI), jedoch nur, solange heartbeat.every nicht festgelegt ist. Legen Sie agents.defaults.heartbeat.every oder agentenspezifisch agents.entries.*.heartbeat.every fest; verwenden Sie zum Deaktivieren 0m.
• Prompt-Inhalt (über agents.defaults.heartbeat.prompt konfigurierbar): Follow the heartbeat monitor scratch context when provided. Recurring tasks are cron jobs; create or change their schedules with cron tools or the openclaw cron CLI, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• Zeitüberschreitung: Heartbeat-Durchläufe ohne festgelegten Wert verwenden agents.defaults.timeoutSeconds, sofern dieser Wert gesetzt ist. Andernfalls verwenden sie den Heartbeat-Takt, begrenzt auf 600 Sekunden. Legen Sie für längere Heartbeat-Arbeiten agents.defaults.heartbeat.timeoutSeconds oder agentenspezifisch agents.entries.*.heartbeat.timeoutSeconds fest.
• Der Heartbeat-Prompt wird unverändert als Benutzernachricht gesendet. Der System-Prompt enthält einen Abschnitt „Heartbeats“, wenn Heartbeats für den Standardagenten aktiviert sind, und die Ausführung wird intern entsprechend gekennzeichnet.
• Wenn Heartbeats mit 0m deaktiviert werden, bleibt der cron-Überwachungsauftrag bestehen, wird jedoch deaktiviert. Seine Notizen bleiben erhalten, bis Sie den Takt wieder aktivieren.
• Wenn cron selbst deaktiviert ist, werden geplante Heartbeats nicht ausgeführt, auch wenn der Heartbeat-Takt weiterhin aktiviert ist.
• Aktive Zeiten (heartbeat.activeHours) werden in der konfigurierten Zeitzone geprüft. Außerhalb des Zeitfensters werden Heartbeats bis zum nächsten Takt innerhalb des Fensters übersprungen.
• Heartbeats werden automatisch zurückgestellt, solange cron-Arbeiten aktiv sind oder sich in der Warteschlange befinden oder solange die sitzungsschlüsselgebundenen Subagenten- oder verschachtelten Befehls-Lanes dieses Agenten ausgelastet sind. Gleichgeordnete Agenten pausieren einander nicht.

Zweck des Heartbeat-Prompts

Der Standard-Prompt ist bewusst allgemein gehalten:

• Hintergrundaufgaben: „Ausstehende Aufgaben berücksichtigen“ fordert den Agenten auf, Folgemaßnahmen zu prüfen (Posteingang, Kalender, Erinnerungen, Arbeiten in der Warteschlange) und auf dringende Punkte hinzuweisen.
• Nachfrage beim Menschen: „Gelegentlich tagsüber nach dem Menschen sehen“ regt zu einer gelegentlichen kurzen Nachricht wie „Benötigen Sie etwas?“ an, vermeidet jedoch durch Verwendung Ihrer konfigurierten lokalen Zeitzone nächtliche Nachrichtenfluten (siehe Zeitzone).

Heartbeat kann auf abgeschlossene Hintergrundaufgaben reagieren, aber eine Heartbeat-Ausführung selbst erstellt keinen Aufgabendatensatz.

Wenn ein Heartbeat etwas ganz Bestimmtes tun soll (z. B. „Gmail-PubSub-Statistiken prüfen“ oder „Gateway-Zustand überprüfen“), legen Sie agents.defaults.heartbeat.prompt (oder agents.entries.*.heartbeat.prompt) auf einen benutzerdefinierten Inhalt fest (wird unverändert gesendet).

Antwortvertrag

• Wenn nichts beachtet werden muss, antworten Sie mit HEARTBEAT_OK.
• Heartbeat-Ausführungen können stattdessen heartbeat_respond mit notify: false aufrufen, wenn keine sichtbare Aktualisierung erfolgen soll, oder notify: true zusammen mit notificationText für eine Warnung. Falls vorhanden, hat die strukturierte Tool-Antwort Vorrang vor dem textbasierten Rückfall.
• Ein aussagekräftiges heartbeat_respond-Ergebnis mit notify: false bleibt unsichtbar, wird jedoch als begrenzter interner Kontext für den nächsten Benutzerdurchlauf in dieser Sitzung gespeichert. no_change-Bestätigungen und sichtbare Benachrichtigungen werden nicht auf diese Weise gespeichert.
• Während Heartbeat-Ausführungen behandelt OpenClaw HEARTBEAT_OK als Bestätigung, wenn es am Anfang oder Ende der Antwort erscheint. Das Token wird entfernt und die Antwort verworfen, wenn der verbleibende Inhalt höchstens 300 Zeichen umfasst.
• Wenn HEARTBEAT_OK in der Mitte einer Antwort erscheint, wird es nicht besonders behandelt.
• Fügen Sie bei Warnungen HEARTBEAT_OK nicht ein; geben Sie ausschließlich den Warntext zurück.

Außerhalb von Heartbeats wird ein unbeabsichtigtes HEARTBEAT_OK am Anfang oder Ende einer Nachricht entfernt und protokolliert; eine Nachricht, die nur aus HEARTBEAT_OK besteht, wird verworfen.

Konfiguration

{  agents: {    defaults: {      heartbeat: {        every: "30m", // Standard: 30m (0m deaktiviert)        model: "anthropic/claude-opus-4-6",        lightContext: false, // Standard: false; true überspringt Workspace-Bootstrap-Dateien für Heartbeat-Ausführungen        isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer neuen Sitzung aus (kein Gesprächsverlauf)        target: "last", // Standard: none | Optionen: last | none | <channel id> (Kern oder Plugin, z. B. "imessage")        to: "+15551234567", // optionale kanalspezifische Überschreibung        accountId: "ops-bot", // optionale Kanal-ID bei mehreren Konten        prompt: "Befolgen Sie den Kontext der Heartbeat-Überwachungsnotizen, sofern er bereitgestellt wird. Wiederkehrende Aufgaben sind cron-Aufträge; erstellen oder ändern Sie deren Zeitpläne mit cron-Tools oder der openclaw cron CLI, nicht mit Heartbeat-Notizen. Leiten Sie keine alten Aufgaben aus früheren Chats ab und wiederholen Sie diese nicht. Wenn nichts beachtet werden muss, antworten Sie mit HEARTBEAT_OK.",      },    },  },}

Geltungsbereich und Rangfolge

• agents.defaults.heartbeat legt das globale Heartbeat-Verhalten fest.
• agents.entries.*.heartbeat wird darübergelegt; wenn ein Agent einen heartbeat-Block besitzt, führen nur diese Agenten Heartbeats aus.
• channels.defaults.heartbeatVisibility legt die Sichtbarkeitsstandards für alle Kanäle fest.
• channels.<channel>.heartbeatVisibility überschreibt die Kanalstandards.
• channels.<channel>.accounts.<id>.heartbeatVisibility (Kanäle mit mehreren Konten) überschreibt die kanalspezifischen Einstellungen.

Agentenspezifische Heartbeats

Wenn ein agents.entries.*-Eintrag einen heartbeat-Block enthält, führen nur diese Agenten Heartbeats aus. Der agentenspezifische Block wird über agents.defaults.heartbeat gelegt (Sie können daher gemeinsame Standardwerte einmalig festlegen und sie für einzelne Agenten überschreiben).

Beispiel: zwei Agenten, wobei nur der zweite Agent Heartbeats ausführt.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explizite Zustellung an den letzten Kontakt (Standard ist "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "Befolgen Sie den Kontext der Heartbeat-Überwachungsnotizen, sofern er bereitgestellt wird. Wiederkehrende Aufgaben sind cron-Aufträge; erstellen oder ändern Sie deren Zeitpläne mit cron-Tools oder der openclaw cron CLI, nicht mit Heartbeat-Notizen. Leiten Sie keine alten Aufgaben aus früheren Chats ab und wiederholen Sie diese nicht. Wenn nichts beachtet werden muss, antworten Sie mit HEARTBEAT_OK.",        },      },    ],  },}

Beispiel für aktive Zeiten

Beschränken Sie Heartbeats auf Geschäftszeiten in einer bestimmten Zeitzone:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explizite Zustellung an den letzten Kontakt (Standard ist "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; verwendet userTimezone, falls festgelegt, andernfalls die Zeitzone des Hosts        },      },    },  },}

Außerhalb dieses Zeitfensters (vor 9 Uhr oder nach 22 Uhr Eastern Time) werden Heartbeats übersprungen. Der nächste geplante Takt innerhalb des Fensters wird normal ausgeführt.

Einrichtung von 24/7

Wenn Heartbeats ganztägig ausgeführt werden sollen, verwenden Sie eines dieser Muster:

• Lassen Sie activeHours vollständig weg (keine Zeitfensterbeschränkung; dies ist das Standardverhalten).
• Legen Sie ein ganztägiges Zeitfenster fest: activeHours: { start: "00:00", end: "24:00" }.

Beispiel mit mehreren Konten

Verwenden Sie accountId, um auf Kanälen mit mehreren Konten wie Telegram ein bestimmtes Konto auszuwählen:

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: an ein bestimmtes Thema/einen bestimmten Thread weiterleiten          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

Feldhinweise

Zustellungsverhalten

Sichtbarkeitssteuerung

Standardmäßig werden HEARTBEAT_OK-Bestätigungen unterdrückt, während Alarminhalte zugestellt werden. Sie können dies pro Kanal oder pro Konto anpassen:

channels:  defaults:    heartbeat:      showOk: false # HEARTBEAT_OK ausblenden (Standard)      showAlerts: true # Alarmmeldungen anzeigen (Standard)      useIndicator: true # Indikatorereignisse ausgeben (Standard)  telegram:    heartbeat:      showOk: true # OK-Bestätigungen auf Telegram anzeigen  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Alarmzustellung für dieses Konto unterdrücken

Priorität: pro Konto → pro Kanal → Kanalstandards → integrierte Standards.

Funktion der einzelnen Flags

• showOk: sendet eine HEARTBEAT_OK-Bestätigung, wenn das Modell eine reine OK-Antwort zurückgibt.
• showAlerts: sendet den Alarminhalt, wenn das Modell eine andere als eine OK-Antwort zurückgibt.
• useIndicator: gibt Indikatorereignisse für UI-Statusoberflächen aus.

Wenn alle drei auf false gesetzt sind, überspringt OpenClaw den Heartbeat-Durchlauf vollständig (kein Modellaufruf).

Beispiele für Einstellungen pro Kanal und pro Konto

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # alle Slack-Konten    accounts:      ops:        heartbeat:          showAlerts: false # Alarme nur für das ops-Konto unterdrücken  telegram:    heartbeat:      showOk: true

Häufige Muster

Monitor-Notizen (optional)

Jeder Cron-Job des Heartbeat-Monitors besitzt ein privates Notizdokument, das in der gemeinsamen Zustandsdatenbank gespeichert ist. Betrachten Sie es als Ihre „Heartbeat-Checkliste“: klein, stabil und sicher alle 30 Minuten zu berücksichtigen. Wenn Notizen vorhanden sind, wird ihr Inhalt an den Heartbeat-Prompt angehängt.

Verwalten Sie sie mit der Cron-CLI (die Job-ID stammt aus openclaw cron list --all):

openclaw cron scratch <jobId>                 # aktuelle Notizen ausgebenopenclaw cron scratch <jobId> --set "..."     # durch den exakten Text ersetzenopenclaw cron scratch <jobId> --file notes.md # durch den Inhalt einer Datei ersetzen (- für stdin)openclaw cron scratch <jobId> --unset         # entfernen

Schreibvorgänge sind durch Compare-and-Swap geschützt: Übergeben Sie --expected-revision <n>, damit der Vorgang fehlschlägt, statt eine gleichzeitige Bearbeitung zu überschreiben. Die Notizen sind auf 256 KiB begrenzt und erscheinen niemals in der Ausgabe von cron list/cron runs.

Der Agent kann auch seine eigenen Notizen aktualisieren: Während eines Heartbeat-Durchlaufs akzeptiert heartbeat_respond eine optionale Zeichenfolge scratch, die die Notizen des Monitors für zukünftige Heartbeats vollständig ersetzt.

Wenn Notizen vorhanden, aber praktisch leer sind (nur Leerzeilen, Markdown-/HTML-Kommentare, Markdown-Überschriften wie # Heading, Fence-Markierungen oder leere Checklisten-Platzhalter), überspringt OpenClaw den Heartbeat-Durchlauf, um API-Aufrufe zu sparen. Dieses Überspringen wird als reason=empty-heartbeat-file gemeldet. Sind keine Notizen vorhanden, wird der Heartbeat dennoch ausgeführt und das Modell entscheidet, was zu tun ist.

Halten Sie sie knapp (kurze Checkliste oder Erinnerungen), um ein unnötiges Anwachsen des Prompts zu vermeiden.

Beispielnotizen:

# Heartbeat-Checkliste - Kurz prüfen: Gibt es etwas Dringendes in den Posteingängen?- Wenn es Tag ist und sonst nichts ansteht, kurz und unaufwendig nachfragen.- Wenn eine Aufgabe blockiert ist, notieren, _was fehlt_, und Peter beim nächsten Mal fragen.

Wiederkehrende Prüfungen mit Cron planen

Heartbeat-Notizen sind Prompt-Kontext und kein Zeitplaner. Erstellen Sie jede wiederkehrende Prüfung als Cron-Job, damit sie über ein eigenes Intervall, einen eigenen Aktivierungsstatus und einen eigenen Ausführungsverlauf verfügt. Cron-Jobs können weiterhin auf die Hauptsitzung abzielen, wenn für die Prüfung der normale Gesprächskontext verwendet werden soll.

Ältere Notizen können einen strukturierten tasks:-Block enthalten. Führen Sie nach dem Upgrade einmal openclaw doctor --fix aus: Doctor wandelt jeden gültigen Eintrag in einen unabhängig geplanten Cron-Job um, behält sein Intervall und den vorherigen Zeitpunkt der letzten Ausführung bei und entfernt den eingestellten Block, während der umgebende Notiztext erhalten bleibt. Heartbeat-Durchläufe zur Laufzeit interpretieren tasks:-Text nicht als Zeitpläne.

Von Doctor erstellte Heartbeat-Aufgabenjobs behalten die aktiven Heartbeat-Zeiten sowie die Schutzmechanismen für Abkühlzeit, Überlastung und Auslastung bei. Gleichzeitig fällige Jobs können zu einem einzigen Heartbeat-Durchlauf zusammengefasst werden. Ein Vorkommen außerhalb der aktiven Zeiten wird übersprungen und beim nächsten Cron-Vorkommen erneut versucht.

Kann der Agent seine Notizen aktualisieren?

Ja. Während eines Heartbeat-Durchlaufs kann der Agent einen scratch-Wert an heartbeat_respond übergeben, um den Monitor-Text für zukünftige Heartbeats vollständig zu ersetzen. Sie können ihn auch in einem normalen Chat auffordern, openclaw cron scratch <jobId> --set ... auszuführen, oder die Notizen selbst mit demselben Befehl bearbeiten. Verwalten Sie wiederkehrende Zeitpläne mit Cron, statt Zeitplanersyntax in die Notizen zu schreiben.

Manuelle Aktivierung (bei Bedarf)

Verwenden Sie openclaw system event, um ein Systemereignis in die Warteschlange zu stellen und optional sofort einen Heartbeat auszulösen:

openclaw system event --text "Auf dringende Nachfassaktionen prüfen" --mode now

Wenn kein --session-key angegeben ist und für mehrere Agenten heartbeat konfiguriert ist, führt --mode now die Heartbeats all dieser Agenten sofort aus.

Zugehörige Heartbeat-Steuerelemente in derselben CLI-Gruppe:

openclaw system heartbeat last     # letztes Heartbeat-Ereignis anzeigenopenclaw system heartbeat enable   # Heartbeats aktivierenopenclaw system heartbeat disable  # Heartbeats deaktivieren

Kostenbewusstsein

Heartbeats führen vollständige Agentendurchläufe aus. Kürzere Intervalle verbrauchen mehr Token. So lassen sich die Kosten reduzieren:

• Verwenden Sie isolatedSession: true, damit nicht der vollständige Konversationsverlauf gesendet wird (~100K Token werden auf ~2-5K pro Ausführung reduziert).
• Verwenden Sie lightContext: true, um Workspace-Bootstrap-Dateien bei Heartbeat-Ausführungen zu überspringen.
• Legen Sie ein kostengünstigeres model fest (z. B. ollama/llama3.2:1b).
• Halten Sie den temporären Monitorbereich klein.
• Verwenden Sie target: "none", wenn Sie nur interne Statusaktualisierungen wünschen.

Kontextüberlauf nach einem Heartbeat

Heartbeats behalten nach Abschluss der Ausführung das vorhandene Laufzeitmodell der gemeinsam genutzten Sitzung bei. Daher kann ein Heartbeat, der eine Sitzung auf ein kleineres lokales Modell umgestellt hat (beispielsweise ein Ollama-Modell mit einem 32k-Kontextfenster), dieses Modell für den nächsten Durchlauf der Hauptsitzung aktiv lassen. Wenn dieser nächste Durchlauf dann einen Kontextüberlauf meldet und das zuletzt verwendete Laufzeitmodell der Sitzung mit dem konfigurierten heartbeat.model übereinstimmt, nennt die Wiederherstellungsmeldung von OpenClaw die Übernahme des Heartbeat-Modells als wahrscheinliche Ursache und schlägt eine Korrektur vor.

So vermeiden Sie dies: Verwenden Sie isolatedSession: true, um Heartbeats in einer neuen Sitzung auszuführen (optional in Kombination mit lightContext: true für den kleinstmöglichen Prompt), oder wählen Sie ein Heartbeat-Modell mit einem Kontextfenster, das groß genug für die gemeinsam genutzte Sitzung ist.

Verwandte Themen

• Automatisierung – alle Automatisierungsmechanismen auf einen Blick
• Hintergrundaufgaben – wie abgekoppelte Arbeiten nachverfolgt werden
• Zeitzone – wie sich die Zeitzone auf die Heartbeat-Planung auswirkt
• Fehlerbehebung – Fehler bei der Automatisierung diagnostizieren