Heartbeat (Gateway)

Heartbeat vs. Cron? Siehe Cron vs. Heartbeat für Hinweise, wann Sie was nutzen.

Heartbeat führt periodische Agenten-Durchläufe in der Hauptsitzung aus, damit das Modell alles, was Aufmerksamkeit braucht, anzeigen kann, ohne Sie zuzuspamen.

Schnellstart (Anfänger)

Heartbeats aktiviert lassen (Standard 30m oder 1h bei Anthropic-OAuth/Setup-Token) oder eigene Taktung setzen.
Eine kleine HEARTBEAT.md-Checkliste im Agenten-Workspace anlegen (optional, aber empfohlen).
Festlegen, wohin Heartbeat-Nachrichten gehen (target: "last" ist Standard).
Optional: Heartbeat-Reasoning-Auslieferung für Transparenz aktivieren.
Optional: Heartbeats auf aktive Stunden (lokale Zeit) beschränken.

Beispiel-Konfiguration:


{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: separate „Reasoning:“-Nachricht mitsenden
      }
    }
  }
}

Standardwerte

Intervall: 30m (oder 1h, wenn Anthropic-OAuth/Setup-Token als Auth-Modus erkannt wird). agents.defaults.heartbeat.every oder pro Agent agents.list[].heartbeat.every setzen; 0m deaktiviert.
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 wörtlich als Nutzer-Nachricht gesendet. Der System-Prompt enthält einen „Heartbeat“-Abschnitt und der Lauf wird intern markiert.
Aktive Stunden (heartbeat.activeHours) werden in der konfigurierten Zeitzone geprüft. Außerhalb des Fensters werden Heartbeats übersprungen bis zum nächsten Tick innerhalb des Fensters.

Wofür der Heartbeat-Prompt da ist

Der Standard-Prompt ist bewusst breit:

Hintergrundaufgaben: „Consider outstanding tasks“ animiert den Agenten, Follow-ups (Posteingang, Kalender, Erinnerungen, Warteschlangen-Arbeit) zu prüfen und Dringendes anzuzeigen.
Human-Check-in: „Checkup sometimes on your human during day time“ animiert zu gelegentlichen leichten „Brauchst du was?“-Nachrichten, vermeidet aber nächtlichen Spam durch Ihre konfigurierte lokale Zeitzone (siehe Zeitzone).

Für sehr spezifische Heartbeat-Aufgaben (z. B. „Gmail-PubSub-Statistik prüfen“ oder „Gateway-Health prüfen“) agents.defaults.heartbeat.prompt (oder agents.list[].heartbeat.prompt) auf einen eigenen Text setzen (wörtlich gesendet).

Antwort-Vertrag

Wenn nichts Aufmerksamkeit braucht, mit HEARTBEAT_OK antworten.
Während Heartbeat-Läufen behandelt OpenClaw HEARTBEAT_OK als Bestätigung, wenn es am Anfang oder Ende der Antwort steht. Der Token wird entfernt und die Antwort verworfen, wenn der verbleibende Inhalt ≤ ackMaxChars (Standard: 300) ist.
Steht HEARTBEAT_OK in der Mitte einer Antwort, wird es nicht speziell behandelt.
Bei Alerts kein HEARTBEAT_OK mitsenden; nur den Alert-Text zurückgeben.

Außerhalb von Heartbeats wird verirrtes HEARTBEAT_OK am Anfang/Ende einer Nachricht entfernt und geloggt; eine Nachricht, die nur HEARTBEAT_OK ist, wird verworfen.

Konfiguration


{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",           // Standard: 30m (0m deaktiviert)
        model: "anthropic/claude-opus-4-5",
        includeReasoning: false, // Standard: false (separate Reasoning:-Nachricht bei Verfügbarkeit)
        target: "last",         // last | none | <channel id> (Kern oder Plugin, z. B. "bluebubbles")
        to: "+15551234567",     // optionaler kanalspezifischer Override
        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.",
        ackMaxChars: 300        // max. Zeichen nach HEARTBEAT_OK
      }
    }
  }
}

Geltungsbereich und Vorrang

agents.defaults.heartbeat setzt das globale Heartbeat-Verhalten.
agents.list[].heartbeat wird darauf zusammengeführt; hat ein Agent einen heartbeat-Block, laufen nur diese Agenten Heartbeats.
channels.defaults.heartbeat setzt Sichtbarkeits-Standards für alle Kanäle.
channels.<channel>.heartbeat überschreibt Kanal-Standards.
channels.<channel>.accounts.<id>.heartbeat (Multi-Account-Kanäle) überschreibt pro-Kanal-Einstellungen.

Pro-Agent-Heartbeats

Enthält ein agents.list[]-Eintrag einen heartbeat-Block, laufen nur diese Agenten Heartbeats. Der Pro-Agent-Block wird mit agents.defaults.heartbeat zusammengeführt (gemeinsame Defaults einmal setzen, pro Agent überschreiben). Beispiel: zwei Agenten, nur der zweite läuft Heartbeats.


{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last"
      }
    },
    list: [\
      { id: "main", default: true },\
      {\
        id: "ops",\
        heartbeat: {\
          every: "1h",\
          target: "whatsapp",\
          to: "+15551234567",\
          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."\
        }\
      }\
    ]
  }
}

Feldnotizen

every: Heartbeat-Intervall (Dauer-String; Standardeinheit = Minuten).
model: optionaler Modell-Override für Heartbeat-Läufe (provider/model).
includeReasoning: wenn aktiviert, wird bei Verfügbarkeit auch die separate Reasoning:-Nachricht ausgeliefert (gleiche Form wie /reasoning on).
session: optionaler Sitzungsschlüssel für Heartbeat-Läufe.
- main (Standard): Agent-Hauptsitzung.
- Expliziter Sitzungsschlüssel (aus openclaw sessions --json oder Sessions-CLI kopieren).
- Sitzungsschlüssel-Formate: siehe Sitzungen und Gruppen.
target:
- last (Standard): an den zuletzt genutzten externen Kanal liefern.
- expliziter Kanal: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
- none: Heartbeat ausführen, aber nicht extern ausliefern.
to: optionaler Empfänger-Override (kanalspezifische ID, z. B. E.164 für WhatsApp oder Telegram-Chat-ID).
prompt: überschreibt den Standard-Prompt-Text (nicht zusammengeführt).
ackMaxChars: max. Zeichen nach HEARTBEAT_OK vor Auslieferung.

Auslieferungsverhalten

Heartbeats laufen standardmäßig in der Hauptsitzung des Agenten (agent:<id>:<mainKey>), oder global bei session.scope = "global". session setzen, um auf eine bestimmte Kanal-Sitzung (Discord/WhatsApp usw.) zu überschreiben.
session betrifft nur den Lauf-Kontext; Auslieferung steuern target und to.
Für Auslieferung an einen bestimmten Kanal/Empfänger target + to setzen. Bei target: "last" nutzt die Auslieferung den letzten externen Kanal für diese Sitzung.
Ist die Haupt-Warteschlange belegt, wird der Heartbeat übersprungen und später erneut versucht.
Löst target auf kein externes Ziel auf, findet der Lauf trotzdem statt, es wird aber keine ausgehende Nachricht gesendet.
Nur-Heartbeat-Antworten halten die Sitzung nicht am Leben; das letzte updatedAt wird wiederhergestellt, damit Idle-Expiry normal funktioniert.

Sichtbarkeits-Steuerung

Standardmäßig werden HEARTBEAT_OK-Bestätigungen unterdrückt, während Alert-Inhalt ausgeliefert wird. Pro Kanal oder pro Account anpassbar:


channels:
  defaults:
    heartbeat:
      showOk: false      # HEARTBEAT_OK ausblenden (Standard)
      showAlerts: true   # Alert-Nachrichten anzeigen (Standard)
      useIndicator: true # Indikator-Ereignisse senden (Standard)
  telegram:
    heartbeat:
      showOk: true       # OK-Bestätigungen auf Telegram anzeigen
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Alerts nur für diesen Account unterdrücken

Vorrang: pro-Account → pro-Kanal → Kanal-Standards → eingebaute Standards.

Was die Flags bewirken

showOk: sendet eine HEARTBEAT_OK-Bestätigung, wenn das Modell eine reine OK-Antwort liefert.
showAlerts: sendet den Alert-Inhalt, wenn das Modell eine Nicht-OK-Antwort liefert.
useIndicator: sendet Indikator-Ereignisse für UI-Status-Oberflächen.

Sind alle drei false, überspringt OpenClaw den Heartbeat-Lauf komplett (kein Modell-Aufruf).

Pro-Kanal vs. Pro-Account-Beispiele


channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # alle Slack-Accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # Alerts nur für den ops-Account unterdrücken
  telegram:
    heartbeat:
      showOk: true

Typische Muster

Ziel	Konfiguration
Standard (stille OKs, Alerts 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)

Existiert eine HEARTBEAT.md im Workspace, weist der Standard-Prompt den Agenten an, sie zu lesen. Sie dient als „Heartbeat-Checkliste“: klein, stabil und unkritisch alle 30 Minuten. Ist HEARTBEAT.md vorhanden aber effektiv leer (nur Leerzeilen und Markdown-Überschriften wie # Heading), überspringt OpenClaw den Heartbeat-Lauf, um API-Aufrufe zu sparen. Fehlt die Datei, läuft der Heartbeat trotzdem und das Modell entscheidet. Kurz halten (Checkliste oder Erinnerungen), um den Prompt nicht aufzublähen. Beispiel HEARTBEAT.md:


# Heartbeat-Checkliste

- Kurz prüfen: etwas Dringendes in den Posteingängen?
- Wenn Tag, leichter Check-in, wenn nichts anderes ansteht.
- Bei blockierter Aufgabe festhalten, *was fehlt*, und nächstes Mal Peter fragen.

Kann der Agent HEARTBEAT.md aktualisieren?

Ja — wenn Sie es anweisen. HEARTBEAT.md ist eine normale Datei im Agenten-Workspace; Sie können dem Agenten (im normalen Chat) z. B. sagen:

„Aktualisiere HEARTBEAT.md um eine tägliche Kalenderprüfung.“
„Schreibe HEARTBEAT.md kürzer und fokussiert auf Posteingang-Follow-ups.“

Für proaktive Updates können Sie im Heartbeat-Prompt eine explizite Zeile ergänzen wie: „If the checklist becomes stale, update HEARTBEAT.md with a better one.“ Sicherheitshinweis: Keine Geheimnisse (API-Keys, Telefonnummern, private Tokens) in HEARTBEAT.md — sie werden Teil des Prompt-Kontexts.

Manueller Wake (on-demand)

Sie können ein System-Event in die Warteschlange legen und sofort einen Heartbeat auslösen:


openclaw system event --text "Check for urgent follow-ups" --mode now

Haben mehrere Agenten heartbeat konfiguriert, führt ein manueller Wake bei jedem dieser Agenten sofort einen Heartbeat aus. --mode next-heartbeat wartet auf den nächsten geplanten Tick.

Reasoning-Auslieferung (optional)

Standardmäßig liefern Heartbeats nur die finale „Antwort“-Payload. Für mehr Transparenz aktivieren:

agents.defaults.heartbeat.includeReasoning: true

Wenn aktiviert, liefern Heartbeats zusätzlich eine separate Nachricht mit Präfix Reasoning: (gleiche Form wie /reasoning on). Nützlich, wenn der Agent mehrere Sitzungen/Codexe verwaltet und Sie sehen wollen, warum er Sie anpingt—kann aber mehr interne Details preisgeben als gewünscht. In Gruppenchats besser aus lassen.

Kostenbewusstsein

Heartbeats sind volle Agenten-Durchläufe. Kürzere Intervalle verbrauchen mehr Tokens. HEARTBEAT.md klein halten und ein günstigeres model oder target: "none" erwägen, wenn Sie nur interne State-Updates wollen.