Heartbeat (Gateway)
Heartbeat oder Cron? Unter Automatisierung & Aufgaben finden Sie Hinweise dazu, wann was verwendet werden sollte.Heartbeat führt periodische Agent-Turns in der Hauptsitzung aus, damit das Modell alles hervorheben kann, was Aufmerksamkeit braucht, ohne Sie zuzuspammen. Heartbeat ist ein geplanter Turn in der Hauptsitzung — dabei werden keine Einträge für Hintergrundaufgaben erstellt. Aufgabeneinträge sind für entkoppelte Arbeit gedacht (ACP-Läufe, Subagenten, isolierte Cron-Jobs). Fehlerbehebung: Geplante Aufgaben
Schnellstart (Anfänger)
- Lassen Sie Heartbeats aktiviert (Standard ist
30mbzw.1hbei Anthropic-OAuth-/Token-Authentifizierung, einschließlich Claude-CLI-Wiederverwendung) oder legen Sie Ihre eigene Frequenz fest. - Erstellen Sie eine kleine Checkliste in
HEARTBEAT.mdoder einentasks:-Block im Agent-Workspace (optional, aber empfohlen). - Entscheiden Sie, wohin Heartbeat-Nachrichten gesendet werden sollen (
target: "none"ist der Standard; setzen Sietarget: "last", um an den letzten Kontakt zu senden). - Optional: Aktivieren Sie die Zustellung von Heartbeat-Reasoning für mehr Transparenz.
- Optional: Verwenden Sie einen leichtgewichtigen Bootstrap-Kontext, wenn Heartbeat-Läufe nur
HEARTBEAT.mdbenötigen. - Optional: Aktivieren Sie isolierte Sitzungen, um zu vermeiden, bei jedem Heartbeat den vollständigen Gesprächsverlauf zu senden.
- Optional: Beschränken Sie Heartbeats auf aktive Stunden (Ortszeit).
Standardwerte
- Intervall:
30m(oder1h, wenn Anthropic-OAuth-/Token-Authentifizierung der erkannte Auth-Modus ist, einschließlich Claude-CLI-Wiederverwendung). Legen Sieagents.defaults.heartbeat.everyoder pro Agentagents.list[].heartbeat.everyfest; verwenden Sie0m, um zu deaktivieren. - Prompt-Text (konfigurierbar über
agents.defaults.heartbeat.prompt):Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. - Der Heartbeat-Prompt wird unverändert als Benutzernachricht gesendet. Der System- Prompt enthält nur dann einen Abschnitt „Heartbeat“, wenn Heartbeats für den Standard-Agenten aktiviert sind und der Lauf intern entsprechend markiert ist.
- Wenn Heartbeats mit
0mdeaktiviert sind, lassen normale LäufeHEARTBEAT.mdebenfalls aus dem Bootstrap-Kontext weg, damit das Modell keine nur für Heartbeats gedachten Anweisungen sieht. - Aktive Stunden (
heartbeat.activeHours) werden in der konfigurierten Zeitzone geprüft. Außerhalb des Fensters werden Heartbeats bis zum nächsten Tick innerhalb des Fensters übersprungen.
Wofür der Heartbeat-Prompt gedacht ist
Der Standard-Prompt ist absichtlich breit formuliert:- Hintergrundaufgaben: „Consider outstanding tasks“ stößt den Agenten dazu an, offene Nachverfolgungen (Posteingang, Kalender, Erinnerungen, wartende Arbeit) zu prüfen und alles Dringende hervorzuheben.
- Check-in beim Menschen: „Checkup sometimes on your human during day time“ stößt gelegentliche leichtgewichtige Nachrichten wie „Brauchst du etwas?“ an, vermeidet aber nächtlichen Spam durch Verwendung Ihrer konfigurierten lokalen Zeitzone (siehe /concepts/timezone).
agents.defaults.heartbeat.prompt (oder
agents.list[].heartbeat.prompt) auf einen benutzerdefinierten Textkörper (wird unverändert gesendet).
Antwortvertrag
- Wenn nichts Aufmerksamkeit braucht, antworten Sie mit
HEARTBEAT_OK. - Während Heartbeat-Läufen behandelt OpenClaw
HEARTBEAT_OKals Bestätigung, wenn es am Anfang oder Ende der Antwort erscheint. Das Token wird entfernt und die Antwort verworfen, wenn der verbleibende Inhalt ≤ackMaxCharsist (Standard: 300). - Wenn
HEARTBEAT_OKin der Mitte einer Antwort erscheint, wird es nicht besonders behandelt. - Für Warnungen kein
HEARTBEAT_OKeinschließen; geben Sie nur den Warntext zurück.
HEARTBEAT_OK am Anfang/Ende einer Nachricht entfernt
und protokolliert; eine Nachricht, die nur aus HEARTBEAT_OK besteht, wird verworfen.
Konfiguration
Geltungsbereich und Priorität
agents.defaults.heartbeatlegt das globale Heartbeat-Verhalten fest.agents.list[].heartbeatwird darübergelegt; wenn irgendein Agent einenheartbeat-Block hat, führen nur diese Agenten Heartbeats aus.channels.defaults.heartbeatlegt Sichtbarkeitsstandards für alle Kanäle fest.channels.<channel>.heartbeatüberschreibt die Kanalstandards.channels.<channel>.accounts.<id>.heartbeat(Multi-Account-Kanäle) überschreibt pro Kanal die Einstellungen.
Heartbeats pro Agent
Wenn irgendein Eintrag inagents.list[] einen heartbeat-Block enthält, führen nur diese Agenten
Heartbeats aus. Der Block pro Agent wird über agents.defaults.heartbeat
gelegt (so können gemeinsame Standardwerte einmal gesetzt und pro Agent überschrieben werden).
Beispiel: zwei Agenten, nur der zweite Agent führt Heartbeats aus.
Beispiel für aktive Stunden
Beschränken Sie Heartbeats auf Geschäftszeiten in einer bestimmten Zeitzone:24/7-Setup
Wenn Heartbeats den ganzen Tag laufen sollen, verwenden Sie eines dieser Muster:- Lassen Sie
activeHoursganz weg (keine Einschränkung auf ein Zeitfenster; das ist das Standardverhalten). - Setzen Sie ein ganztägiges Fenster:
activeHours: { start: "00:00", end: "24:00" }.
start und end (zum Beispiel 08:00 bis 08:00).
Das wird als Fenster mit Breite null behandelt, daher werden Heartbeats immer übersprungen.
Beispiel für Multi-Account
Verwenden SieaccountId, um bei Multi-Account-Kanälen wie Telegram ein bestimmtes Konto anzusprechen:
Hinweise zu den Feldern
every: Heartbeat-Intervall (Dauerstring; Standard-Einheit = Minuten).model: optionaler Modell-Override für Heartbeat-Läufe (provider/model).includeReasoning: wenn aktiviert, wird auch die separateReasoning:-Nachricht zugestellt, sofern verfügbar.lightContext: wenntrue, verwenden Heartbeat-Läufe einen leichtgewichtigen Bootstrap-Kontext und behalten aus den Workspace-Bootstrap-Dateien nurHEARTBEAT.md.isolatedSession: wenntrue, läuft jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf. Verwendet dasselbe Isolationsmuster wie Cron mitsessionTarget: "isolated". Reduziert die Token-Kosten pro Heartbeat erheblich. Für maximale Einsparungen mitlightContext: truekombinieren. Das Zustellungsrouting nutzt weiterhin den Kontext der Hauptsitzung.session: optionaler Sitzungsschlüssel für Heartbeat-Läufe.main(Standard): Hauptsitzung des Agenten.- expliziter Sitzungsschlüssel (kopieren aus
openclaw sessions --jsonoder der sessions CLI). - Formate von Sitzungsschlüsseln: siehe Sessions und Groups.
target:last: an den zuletzt verwendeten externen Kanal zustellen.- expliziter Kanal: jeder konfigurierte Kanal oder jede Plugin-ID, zum Beispiel
discord,matrix,telegramoderwhatsapp. none(Standard): den Heartbeat ausführen, aber nicht extern zustellen.
directPolicy: steuert das Verhalten für direkte/DM-Zustellung:allow(Standard): direkte/DM-Heartbeat-Zustellung erlauben.block: direkte/DM-Zustellung unterdrücken (reason=dm-blocked).
to: optionaler Empfänger-Override (kanalspezifische ID, z. B. E.164 für WhatsApp oder eine Telegram-Chat-ID). Für Telegram-Topics/-Threads verwenden Sie<chatId>:topic:<messageThreadId>.accountId: optionale Konto-ID für Multi-Account-Kanäle. Beitarget: "last"gilt die Konto-ID für den aufgelösten letzten Kanal, falls dieser Konten unterstützt; andernfalls wird sie ignoriert. Wenn die Konto-ID nicht zu einem konfigurierten Konto für den aufgelösten Kanal passt, wird die Zustellung übersprungen.prompt: überschreibt den Standard-Prompt-Text (wird nicht zusammengeführt).ackMaxChars: maximale Anzahl von Zeichen nachHEARTBEAT_OK, bevor zugestellt wird.suppressToolErrorWarnings: wenntrue, werden Warn-Payloads für Tool-Fehler während Heartbeat-Läufen unterdrückt.activeHours: beschränkt Heartbeat-Läufe auf ein Zeitfenster. Objekt mitstart(HH:MM, inklusive; verwenden Sie00:00für Tagesbeginn),end(HH:MM, exklusiv;24:00ist für Tagesende erlaubt) und optionaltimezone.- Weggelassen oder
"user": verwendet Ihreagents.defaults.userTimezone, falls gesetzt, andernfalls die Zeitzone des Host-Systems. "local": verwendet immer die Zeitzone des Host-Systems.- Beliebiger IANA-Bezeichner (z. B.
America/New_York): wird direkt verwendet; falls ungültig, wird auf das oben beschriebene"user"-Verhalten zurückgegriffen. startundenddürfen für ein aktives Fenster nicht gleich sein; gleiche Werte werden als Fenster mit Breite null behandelt (immer außerhalb des Fensters).- Außerhalb des aktiven Fensters werden Heartbeats bis zum nächsten Tick innerhalb des Fensters übersprungen.
- Weggelassen oder
Zustellungsverhalten
- Heartbeats laufen standardmäßig in der Hauptsitzung des Agenten (
agent:<id>:<mainKey>), oder inglobal, wennsession.scope = "global"ist. Setzen Siesession, um auf eine bestimmte Kanalsitzung (Discord/WhatsApp/etc.) umzuschalten. sessionwirkt sich nur auf den Laufkontext aus; die Zustellung wird durchtargetundtogesteuert.- Um an einen bestimmten Kanal/Empfänger zuzustellen, setzen Sie
target+to. Mittarget: "last"verwendet die Zustellung den zuletzt verwendeten externen Kanal für diese Sitzung. - Heartbeat-Zustellungen erlauben standardmäßig direkte/DM-Ziele. Setzen Sie
directPolicy: "block", um direkte Ziele zu unterdrücken und den Heartbeat-Turn trotzdem auszuführen. - Wenn die Hauptwarteschlange ausgelastet ist, wird der Heartbeat übersprungen und später erneut versucht.
- Wenn
targetzu keinem externen Ziel aufgelöst wird, findet der Lauf trotzdem statt, aber es wird keine ausgehende Nachricht gesendet. - Wenn
showOk,showAlertsunduseIndicatoralle deaktiviert sind, wird der Lauf vorab alsreason=alerts-disabledübersprungen. - Wenn nur die Alarmzustellung deaktiviert ist, kann OpenClaw den Heartbeat trotzdem ausführen, Zeitstempel fälliger Aufgaben aktualisieren, den Leerlauf-Zeitstempel der Sitzung wiederherstellen und die ausgehende Alarm-Payload unterdrücken.
- Reine Heartbeat-Antworten halten die Sitzung nicht aktiv; der letzte
updatedAt- Wert wird wiederhergestellt, sodass das Idle-Ablaufverhalten normal bleibt. - Entkoppelte Hintergrundaufgaben können ein Systemereignis in die Warteschlange stellen und Heartbeat aufwecken, wenn die Hauptsitzung etwas schnell bemerken soll. Dieses Aufwecken macht den Heartbeat-Lauf nicht zu einer Hintergrundaufgabe.
Sichtbarkeitssteuerung
Standardmäßig werdenHEARTBEAT_OK-Bestätigungen unterdrückt, während Alarminhalt
zugestellt wird. Sie können das pro Kanal oder pro Konto anpassen:
Was die einzelnen Flags bewirken
showOk: sendet eineHEARTBEAT_OK-Bestätigung, wenn das Modell eine reine OK-Antwort zurückgibt.showAlerts: sendet den Alarminhalt, wenn das Modell eine Nicht-OK-Antwort zurückgibt.useIndicator: gibt Indikatorereignisse für UI-Statusoberflächen aus.
false sind, überspringt OpenClaw den Heartbeat-Lauf vollständig (kein Modellaufruf).
Beispiele pro Kanal vs. pro Konto
Häufige Muster
| Ziel | Konfiguration |
|---|---|
| Standardverhalten (stille OKs, Alarme an) | (keine Konfiguration nötig) |
| Vollständig still (keine Nachrichten, kein Indikator) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false } |
| Nur Indikator (keine Nachrichten) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true } |
| OKs nur in einem Kanal | channels.telegram.heartbeat: { showOk: true } |
HEARTBEAT.md (optional)
Wenn im Workspace eine DateiHEARTBEAT.md existiert, weist der Standard-Prompt den
Agenten an, sie zu lesen. Betrachten Sie sie als Ihre „Heartbeat-Checkliste“: klein, stabil und
sicher genug, um sie alle 30 Minuten einzubinden.
Bei normalen Läufen wird HEARTBEAT.md nur eingebunden, wenn Heartbeat-Anleitung
für den Standard-Agenten aktiviert ist. Das Deaktivieren der Heartbeat-Frequenz mit 0m oder
das Setzen von includeSystemPromptSection: false entfernt sie aus dem normalen Bootstrap-
Kontext.
Wenn HEARTBEAT.md existiert, aber praktisch leer ist (nur Leerzeilen und Markdown-
Überschriften wie # Heading), überspringt OpenClaw den Heartbeat-Lauf, um API-Aufrufe zu sparen.
Dieses Überspringen wird als reason=empty-heartbeat-file gemeldet.
Wenn die Datei fehlt, läuft der Heartbeat trotzdem, und das Modell entscheidet, was zu tun ist.
Halten Sie sie klein (kurze Checkliste oder Erinnerungen), um Prompt-Bloat zu vermeiden.
Beispiel für HEARTBEAT.md:
tasks:-Blöcke
HEARTBEAT.md unterstützt außerdem einen kleinen strukturierten tasks:-Block für
intervallbasierte Prüfungen innerhalb von Heartbeat selbst.
Beispiel:
- OpenClaw parst den
tasks:-Block und prüft jede Aufgabe anhand ihres eigeneninterval. - Nur fällige Aufgaben werden für diesen Tick in den Heartbeat-Prompt aufgenommen.
- Wenn keine Aufgaben fällig sind, wird der Heartbeat vollständig übersprungen (
reason=no-tasks-due), um einen unnötigen Modellaufruf zu vermeiden. - Nicht aufgabenbezogener Inhalt in
HEARTBEAT.mdbleibt erhalten und wird nach der Liste der fälligen Aufgaben als zusätzlicher Kontext angehängt. - Zeitstempel des letzten Laufs von Aufgaben werden im Sitzungsstatus (
heartbeatTaskState) gespeichert, sodass Intervalle normale Neustarts überstehen. - Aufgabenzeitstempel werden erst aktualisiert, nachdem ein Heartbeat-Lauf seinen normalen Antwortpfad abgeschlossen hat. Übersprungene Läufe mit
empty-heartbeat-file/no-tasks-duemarkieren Aufgaben nicht als abgeschlossen.
Kann der Agent HEARTBEAT.md aktualisieren?
Ja — wenn Sie ihn dazu auffordern.
HEARTBEAT.md ist einfach eine normale Datei im Agent-Workspace, daher können Sie dem
Agenten (in einem normalen Chat) zum Beispiel Folgendes sagen:
- „Aktualisiere
HEARTBEAT.md, um eine tägliche Kalenderprüfung hinzuzufügen.“ - „Schreibe
HEARTBEAT.mdso um, dass sie kürzer ist und sich auf Inbox-Nachverfolgungen konzentriert.“
HEARTBEAT.md — sie wird Teil des Prompt-Kontexts.
Manuelles Aufwecken (on-demand)
Sie können ein Systemereignis in die Warteschlange stellen und einen sofortigen Heartbeat auslösen mit:heartbeat konfiguriert haben, führt ein manuelles Aufwecken Heartbeats für jeden dieser
Agenten sofort aus.
Verwenden Sie --mode next-heartbeat, um bis zum nächsten geplanten Tick zu warten.
Zustellung von Reasoning (optional)
Standardmäßig stellen Heartbeats nur die finale „Antwort“-Payload zu. Wenn Sie Transparenz möchten, aktivieren Sie:agents.defaults.heartbeat.includeReasoning: true
Reasoning: zu (dieselbe Form wie bei /reasoning on). Das kann nützlich sein, wenn der Agent
mehrere Sitzungen/Codexes verwaltet und Sie sehen möchten, warum er sich entschieden hat, Sie anzupingen —
es kann aber auch mehr interne Details preisgeben, als Sie möchten. Lassen Sie es in Gruppenchats
nach Möglichkeit deaktiviert.
Kostenbewusstsein
Heartbeats führen vollständige Agent-Turns aus. Kürzere Intervalle verbrauchen mehr Tokens. So reduzieren Sie die Kosten:- Verwenden Sie
isolatedSession: true, um das Senden des vollständigen Gesprächsverlaufs zu vermeiden (~100K Tokens auf ~2-5K pro Lauf). - Verwenden Sie
lightContext: true, um Bootstrap-Dateien nur aufHEARTBEAT.mdzu beschränken. - Setzen Sie ein günstigeres
model(z. B.ollama/llama3.2:1b). - Halten Sie
HEARTBEAT.mdklein. - Verwenden Sie
target: "none", wenn Sie nur interne Statusaktualisierungen möchten.
Verwandt
- Automatisierung & Aufgaben — alle Automatisierungsmechanismen auf einen Blick
- Hintergrundaufgaben — wie entkoppelte Arbeit nachverfolgt wird
- Zeitzone — wie die Zeitzone die Heartbeat-Planung beeinflusst
- Fehlerbehebung — Debugging von Automatisierungsproblemen