Heartbeat

Heartbeat führt in der Hauptsitzung regelmäßige Agent-Durchläufe aus, damit das Modell auf alles aufmerksam machen kann, was Ihre Beachtung erfordert, 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-Durchläufe, Subagenten, isolierte Cron-Aufträge).

Fehlerbehebung: Geplante Aufgaben

Schnellstart (für Einsteiger)

Beispielkonfiguration:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explizite Zustellung an den letzten Kontakt (Standard ist "none")        directPolicy: "allow", // Standard: Direkt-/DM-Ziele zulassen; zum Unterdrücken "block" festlegen        lightContext: true, // optional: aus Bootstrap-Dateien nur HEARTBEAT.md einfügen        isolatedSession: true, // optional: bei jedem Durchlauf neue Sitzung (kein Gesprächsverlauf)        skipWhenBusy: true, // optional: auch zurückstellen, wenn Subagent- oder verschachtelte Ausführungsspuren dieses Agenten beschäftigt sind        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: zusätzlich separate `Thinking`-Nachricht senden      },    },  },}

Standardwerte

• Intervall: 30m. Beim Anwenden der Standardeinstellungen des Anthropic-Providers wird es 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.list[].heartbeat.every fest; mit 0m deaktivieren Sie Heartbeat.
• Prompt-Inhalt (über agents.defaults.heartbeat.prompt konfigurierbar): Lies HEARTBEAT.md, falls die Datei existiert (Arbeitsbereichskontext). Befolge sie strikt. Leite keine alten Aufgaben aus früheren Chats ab und wiederhole sie nicht. Wenn nichts beachtet werden muss, antworte mit HEARTBEAT_OK.
• Zeitüberschreitung: Heartbeat-Durchläufe ohne festgelegten Wert verwenden agents.defaults.timeoutSeconds, sofern dieser Wert festgelegt ist. Andernfalls verwenden sie das Heartbeat-Intervall, begrenzt auf 600 Sekunden. Legen Sie für längere Heartbeat-Arbeiten agents.defaults.heartbeat.timeoutSeconds oder agentenspezifisch agents.list[].heartbeat.timeoutSeconds fest.
• Der Heartbeat-Prompt wird unverändert als Benutzernachricht gesendet. Der System-Prompt enthält nur dann einen Abschnitt „Heartbeats“, wenn Heartbeats für den Standard-Agenten aktiviert sind (und includeSystemPromptSection nicht false ist); außerdem wird der Durchlauf intern gekennzeichnet.
• Wenn Heartbeats mit 0m deaktiviert sind, lassen normale Durchläufe HEARTBEAT.md ebenfalls aus dem Bootstrap-Kontext aus, damit das Modell keine ausschließlich für Heartbeat bestimmten Anweisungen sieht.
• Aktive Zeiten (heartbeat.activeHours) werden in der konfigurierten Zeitzone geprüft. Außerhalb des Zeitfensters werden Heartbeats bis zum nächsten Ausführungszeitpunkt innerhalb des Fensters übersprungen.
• Heartbeats werden automatisch zurückgestellt, während Cron-Arbeiten aktiv sind oder in der Warteschlange stehen. Legen Sie heartbeat.skipWhenBusy: true fest, um einen Agenten auch dann zurückzustellen, wenn sein eigener sitzungsschlüsselgebundener Subagent oder verschachtelte Befehlsausführungsspuren beschäftigt sind; nebengeordnete Agenten werden nicht mehr angehalten, nur weil ein anderer Agent laufende Subagent-Arbeiten hat.

Zweck des Heartbeat-Prompts

Der Standard-Prompt ist bewusst allgemein gehalten:

• Hintergrundaufgaben: „Ausstehende Aufgaben berücksichtigen“ veranlasst den Agenten, Folgevorgänge (Posteingang, Kalender, Erinnerungen, Arbeiten in der Warteschlange) zu prüfen und auf Dringendes hinzuweisen.
• Nachfrage beim Menschen: „Erkundigen Sie sich tagsüber gelegentlich bei Ihrem Menschen“ regt zu einer gelegentlichen kurzen Nachricht wie „Benötigen Sie etwas?“ an, vermeidet jedoch nächtliche Nachrichten durch Verwendung Ihrer konfigurierten lokalen Zeitzone (siehe Zeitzone).

Heartbeat kann auf abgeschlossene Hintergrundaufgaben reagieren, ein Heartbeat-Durchlauf selbst erstellt jedoch keinen Aufgabendatensatz.

Wenn ein Heartbeat etwas Bestimmtes tun soll (beispielsweise „Gmail-PubSub-Statistiken prüfen“ oder „Zustand des Gateways überprüfen“), legen Sie für agents.defaults.heartbeat.prompt (oder agents.list[].heartbeat.prompt) einen benutzerdefinierten Inhalt fest, der unverändert gesendet wird.

Antwortvertrag

• Wenn nichts beachtet werden muss, antworten Sie mit HEARTBEAT_OK.
• Heartbeat-Durchläufe 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ückfallwert.
• Während Heartbeat-Durchläufen behandelt OpenClaw HEARTBEAT_OK als Bestätigung, wenn es am Anfang oder Ende der Antwort steht. Das Token wird entfernt und die Antwort verworfen, wenn der verbleibende Inhalt ≤ ackMaxChars ist (Standard: 300).
• Wenn HEARTBEAT_OK in der Mitte einer Antwort vorkommt, wird es nicht besonders behandelt.
• Fügen Sie bei Warnungen kein HEARTBEAT_OK ein; geben Sie nur den Warntext zurück.

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

Konfiguration

{  agents: {    defaults: {      heartbeat: {        every: "30m", // Standard: 30m (0m deaktiviert)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // Standard: false (separate Thinking-Nachricht zustellen, wenn verfügbar)        lightContext: false, // Standard: false; bei true wird aus den Bootstrap-Dateien des Arbeitsbereichs nur HEARTBEAT.md beibehalten        isolatedSession: false, // Standard: false; bei true läuft jeder Heartbeat in einer neuen Sitzung (kein Gesprächsverlauf)        skipWhenBusy: false, // Standard: false; bei true wird auch auf Subagent-/verschachtelte Ausführungsspuren dieses Agenten gewartet        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 für mehrere Konten        prompt: "Lies HEARTBEAT.md, falls die Datei existiert (Arbeitsbereichskontext). Befolge sie strikt. Leite keine alten Aufgaben aus früheren Chats ab und wiederhole sie nicht. Wenn nichts beachtet werden muss, antworte mit HEARTBEAT_OK.",        includeSystemPromptSection: true, // Standard: true; false lässt den System-Prompt-Abschnitt ## Heartbeats für den Standard-Agenten aus        ackMaxChars: 300, // maximal zulässige Zeichenanzahl nach HEARTBEAT_OK      },    },  },}

Geltungsbereich und Vorrang

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

Agentenspezifische Heartbeats

Wenn irgendein Eintrag in agents.list[] einen heartbeat-Block enthält, führen nur diese Agenten Heartbeats aus. Der agentenspezifische Block wird über agents.defaults.heartbeat gelegt (Sie können gemeinsame Standardwerte also einmal festlegen und für einzelne Agenten überschreiben).

Beispiel: Zwei Agenten, nur der zweite Agent führt Heartbeats aus.

{  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: "Lies HEARTBEAT.md, falls die Datei existiert (Arbeitsbereichskontext). Befolge sie strikt. Leite keine alten Aufgaben aus früheren Chats ab und wiederhole sie nicht. Wenn nichts beachtet werden muss, antworte 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 Ostküstenzeit) werden Heartbeats übersprungen. Der nächste geplante Ausführungszeitpunkt innerhalb des Fensters wird normal ausgeführt.

Rund-um-die-Uhr-Konfiguration

Wenn Heartbeats den ganzen Tag 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 für mehrere Konten

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

{  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" },      },    },  },}

Hinweise zu den Feldern

Zustellungsverhalten

Sichtbarkeitssteuerung

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

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

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

Funktion der einzelnen Optionen

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

Wenn alle drei den Wert false haben, überspringt OpenClaw die Heartbeat-Ausführung vollständig (kein Modellaufruf).

Beispiele 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 # Warnungen nur für das Betriebskonto unterdrücken  telegram:    heartbeat:      showOk: true

Häufige Muster

HEARTBEAT.md (optional)

Wenn im Arbeitsbereich eine Datei HEARTBEAT.md vorhanden ist, 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 zu berücksichtigen.

Bei normalen Ausführungen wird HEARTBEAT.md nur eingefügt, wenn die Heartbeat-Anleitung für den Standard-Agenten aktiviert ist. Durch Deaktivieren des Heartbeat-Intervalls mit 0m oder Festlegen von includeSystemPromptSection: false wird sie aus dem normalen Bootstrap-Kontext weggelassen.

In der nativen Codex-Laufzeitumgebung wird der Inhalt von HEARTBEAT.md nicht wie andere Bootstrap-Dateien in den Durchlauf eingefügt. Wenn die Datei vorhanden ist und Inhalt enthält, der nicht nur aus Leerraum besteht, verweist ein Hinweis zum Heartbeat-Zusammenarbeitsmodus Codex auf die Datei und weist Codex an, sie vor dem Fortfahren zu lesen.

Wenn HEARTBEAT.md vorhanden, aber praktisch leer ist (nur Leerzeilen, Markdown-/HTML-Kommentare, Markdown-Überschriften wie # Heading, Begrenzungsmarkierungen oder leere Checklisten-Platzhalter), überspringt OpenClaw die Heartbeat-Ausführung, um API-Aufrufe einzusparen. Dieses Überspringen wird als reason=empty-heartbeat-file gemeldet. Wenn die Datei fehlt, wird der Heartbeat dennoch ausgeführt und das Modell entscheidet, was zu tun ist.

Halten Sie sie sehr klein (kurze Checkliste oder Erinnerungen), um ein Aufblähen des Prompts zu vermeiden.

Beispiel für HEARTBEAT.md:

# Heartbeat-Checkliste - Kurzer Überblick: Gibt es etwas Dringendes in den Posteingängen?- Wenn es tagsüber ist und nichts anderes ansteht, eine kurze, unkomplizierte Rückmeldung geben.- Wenn eine Aufgabe blockiert ist, notieren, _was fehlt_, und Peter beim nächsten Mal fragen.

tasks:-Blöcke

HEARTBEAT.md unterstützt außerdem einen kleinen strukturierten tasks:-Block für intervallbasierte Prüfungen innerhalb des Heartbeats selbst.

Beispiel:

tasks: - name: inbox-triage  interval: 30m  prompt: "Nach dringenden ungelesenen E-Mails suchen und alles Zeitkritische kennzeichnen."- name: calendar-scan  interval: 2h  prompt: "Nach bevorstehenden Besprechungen suchen, die Vorbereitung oder Nachbereitung erfordern." # Zusätzliche Anweisungen - Warnungen kurz halten.- Wenn nach allen fälligen Aufgaben nichts beachtet werden muss, mit HEARTBEAT_OK antworten.

Der Aufgabenmodus ist nützlich, wenn Sie mehrere regelmäßige Prüfungen in einer einzigen Heartbeat-Datei verwalten möchten, ohne bei jedem Tick für alle Prüfungen zu bezahlen.

Kann der Agent HEARTBEAT.md aktualisieren?

Ja – wenn Sie ihn darum bitten.

HEARTBEAT.md ist lediglich eine normale Datei im Arbeitsbereich des Agenten. Daher können Sie dem Agenten (in einem normalen Chat) beispielsweise Folgendes mitteilen:

• „Aktualisieren Sie HEARTBEAT.md, um eine tägliche Kalenderprüfung hinzuzufügen.“
• „Überarbeiten Sie HEARTBEAT.md, sodass die Datei kürzer ist und sich auf Nachfassaktionen im Posteingang konzentriert.“

Wenn dies proaktiv geschehen soll, können Sie außerdem eine ausdrückliche Zeile in Ihren Heartbeat-Prompt aufnehmen, beispielsweise: „Wenn die Checkliste veraltet ist, aktualisieren Sie HEARTBEAT.md mit einer besseren Version.“

Manuelles Aufwecken (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 "Check for urgent follow-ups" --mode now

Wenn kein --session-key angegeben ist und für mehrere Agenten heartbeat konfiguriert wurde, 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

Zustellung von Schlussfolgerungen (optional)

Standardmäßig liefern Heartbeats nur die abschließende „Antwort“-Nutzlast.

Wenn Sie Transparenz wünschen, aktivieren Sie:

• agents.defaults.heartbeat.includeReasoning: true

Wenn diese Option aktiviert ist, liefern Heartbeats außerdem eine separate Nachricht mit dem Präfix Thinking (im selben Format wie bei /reasoning on). Dies kann hilfreich sein, wenn der Agent mehrere Sitzungen/Codex-Instanzen verwaltet und Sie nachvollziehen möchten, warum er sich bei Ihnen gemeldet hat. Es kann jedoch auch mehr interne Details preisgeben, als Sie möchten. Lassen Sie diese Option in Gruppenchats vorzugsweise deaktiviert.

Kostenbewusstsein

Heartbeats führen vollständige Agent-Durchläufe aus. Kürzere Intervalle verbrauchen mehr Tokens. So reduzieren Sie die Kosten:

• Verwenden Sie isolatedSession: true, damit nicht der vollständige Gesprächsverlauf gesendet wird (Reduzierung von etwa 100.000 Tokens auf etwa 2.000–5.000 pro Durchlauf).
• Verwenden Sie lightContext: true, um die Bootstrap-Dateien auf HEARTBEAT.md zu beschränken.
• Legen Sie ein günstigeres model fest (z. B. ollama/llama3.2:1b).
• Halten Sie HEARTBEAT.md klein.
• Verwenden Sie target: "none", wenn Sie nur interne Statusaktualisierungen wünschen.

Kontextüberlauf nach einem Heartbeat

Heartbeats behalten nach Abschluss des Durchlaufs das bestehende Laufzeitmodell der gemeinsamen Sitzung bei. Daher kann ein Heartbeat, der eine Sitzung auf ein kleineres lokales Modell umgestellt hat (beispielsweise ein Ollama-Modell mit einem Kontextfenster von 32.000 Tokens), dieses Modell für den nächsten Durchlauf der Hauptsitzung beibehalten. Wenn dieser nächste Durchlauf daraufhin einen Kontextüberlauf meldet und das letzte Laufzeitmodell der Sitzung dem konfigurierten heartbeat.model entspricht, nennt die Wiederherstellungsnachricht von OpenClaw das Übergreifen des Heartbeat-Modells als wahrscheinliche Ursache und schlägt eine Lösung vor.

Um dies zu vermeiden, verwenden Sie isolatedSession: true, damit Heartbeats in einer neuen Sitzung ausgeführt werden (optional zusammen 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 gemeinsame Sitzung ist.

Verwandte Themen

• Automatisierung – alle Automatisierungsmechanismen auf einen Blick
• Hintergrundaufgaben – wie entkoppelte Arbeit nachverfolgt wird
• Zeitzone – wie sich die Zeitzone auf die Heartbeat-Planung auswirkt
• Fehlerbehebung – Fehlerdiagnose bei Automatisierungsproblemen