Heartbeat (Gateway)

Heartbeat vs Cron? Schau dir Cron vs Heartbeat an, um zu entscheiden, wann du was verwendest.

Heartbeat führt regelmäßige Agent-Durchläufe in der Haupt-Session aus, damit das Modell wichtige Dinge melden kann, ohne dich mit Nachrichten zu überfluten.

Schnellstart (Einsteiger)

Lass Heartbeats aktiviert (Standard ist 30m, oder 1h bei Anthropic OAuth/Setup-Token) oder leg dein eigenes Intervall fest.
Erstelle eine kleine HEARTBEAT.md-Checkliste im Agent-Workspace (optional, aber empfohlen).
Entscheide, wohin Heartbeat-Nachrichten gehen sollen (target: "last" ist der Standard).
Optional: Aktiviere die Heartbeat-Reasoning-Zustellung für mehr Transparenz.
Optional: Beschränke Heartbeats auf aktive Stunden (Ortszeit).

Beispiel-Konfiguration:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: zusätzlich separate `Reasoning:`-Nachricht senden
      },
    },
  },
}

Standardwerte

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

Wofür der Heartbeat-Prompt gedacht ist

Der Standard-Prompt ist absichtlich breit gefasst:

Hintergrundaufgaben: “Consider outstanding tasks” regt den Agent an, Follow-ups (Posteingang, Kalender, Erinnerungen, anstehende Arbeit) zu prüfen und Dringendes zu melden.
Check-in beim Menschen: “Checkup sometimes on your human during day time” regt gelegentlich eine leichte “Brauchst du was?”-Nachricht an, vermeidet aber nächtlichen Spam durch Nutzung deiner konfigurierten Zeitzone (siehe /concepts/timezone).

Wenn du möchtest, dass ein Heartbeat etwas ganz Bestimmtes tut (z.B. “Gmail PubSub-Stats prüfen” oder “Gateway-Zustand verifizieren”), setze agents.defaults.heartbeat.prompt (oder agents.list[].heartbeat.prompt) auf einen eigenen Text (wird wörtlich gesendet).

Antwort-Konvention

Wenn nichts Aufmerksamkeit erfordert, antworte mit HEARTBEAT_OK.
Während Heartbeat-Durchläufen 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 <= ackMaxChars ist (Standard: 300).
Wenn HEARTBEAT_OK mitten in einer Antwort erscheint, wird es nicht besonders behandelt.
Bei Alerts kein HEARTBEAT_OK einfügen; nur den Alert-Text zurückgeben.

Außerhalb von Heartbeats wird ein versehentliches HEARTBEAT_OK am Anfang/Ende einer Nachricht entfernt und geloggt; eine Nachricht, die nur HEARTBEAT_OK enthält, 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 senden wenn verfügbar)
        target: "last", // last | none | <channel id> (core oder plugin, z.B. "bluebubbles")
        to: "+15551234567", // optionaler channel-spezifischer 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 erlaubt
      },
    },
  },
}

Geltungsbereich und Priorität

agents.defaults.heartbeat legt das globale Heartbeat-Verhalten fest.
agents.list[].heartbeat wird darüber gemergt; wenn ein Agent einen heartbeat-Block hat, führen nur diese Agents Heartbeats aus.
channels.defaults.heartbeat legt Sichtbarkeits-Standards für alle Channels fest.
channels.<channel>.heartbeat überschreibt Channel-Standards.
channels.<channel>.accounts.<id>.heartbeat (Multi-Account-Channels) überschreibt pro-Channel-Einstellungen.

Pro-Agent Heartbeats

Wenn ein agents.list[]-Eintrag einen heartbeat-Block enthält, führen nur diese Agents Heartbeats aus. Der pro-Agent-Block wird über agents.defaults.heartbeat gemergt (so kannst du gemeinsame Standards einmal setzen und pro Agent überschreiben).

Beispiel: zwei Agents, nur der zweite führt Heartbeats aus.

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

Feld-Erklärungen

every: Heartbeat-Intervall (Dauer-String; Standard-Einheit = Minuten).
model: optionaler Model-Override für Heartbeat-Durchläufe (provider/model).
includeReasoning: wenn aktiviert, wird auch die separate Reasoning:-Nachricht gesendet, wenn verfügbar (gleiches Format wie /reasoning on).
session: optionaler Session-Key für Heartbeat-Durchläufe.
- main (Standard): Agent-Haupt-Session.
- Expliziter Session-Key (kopiere von openclaw sessions --json oder der Sessions CLI).
- Session-Key-Formate: siehe Sessions und Groups.
target:
- last (Standard): an den zuletzt verwendeten externen Channel senden.
- expliziter Channel: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
- none: Heartbeat ausführen, aber nicht extern zustellen.
to: optionaler Empfänger-Override (channel-spezifische ID, z.B. E.164 für WhatsApp oder eine Telegram-Chat-ID).
prompt: überschreibt den Standard-Prompt-Text (wird nicht gemergt).
ackMaxChars: max. Zeichen nach HEARTBEAT_OK vor Zustellung erlaubt.

Zustellungsverhalten

Heartbeats laufen standardmäßig in der Haupt-Session des Agents (agent:<id>:<mainKey>), oder global wenn session.scope = "global". Setze session, um auf eine bestimmte Channel-Session (Discord/WhatsApp/etc.) zu wechseln.
session beeinflusst nur den Ausführungskontext; die Zustellung wird durch target und to gesteuert.
Um an einen bestimmten Channel/Empfänger zu senden, setze target + to. Mit target: "last" wird der zuletzt verwendete externe Channel für diese Session genutzt.
Wenn die Haupt-Queue beschäftigt ist, wird der Heartbeat übersprungen und später erneut versucht.
Wenn target zu keinem externen Ziel führt, läuft der Durchlauf trotzdem, aber es wird keine ausgehende Nachricht gesendet.
Reine Heartbeat-Antworten halten die Session nicht am Leben; der letzte updatedAt-Wert wird wiederhergestellt, damit Idle-Expiry normal funktioniert.

Sichtbarkeitssteuerung

Standardmäßig werden HEARTBEAT_OK-Bestätigungen unterdrückt, während Alert-Inhalte zugestellt werden. Du kannst das pro Channel oder pro Account anpassen:

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

Priorität: pro-Account -> pro-Channel -> Channel-Standards -> eingebaute Standards.

Was jedes Flag bewirkt

showOk: sendet eine HEARTBEAT_OK-Bestätigung, wenn das Modell eine reine OK-Antwort zurückgibt.
showAlerts: sendet den Alert-Inhalt, wenn das Modell eine Nicht-OK-Antwort zurückgibt.
useIndicator: emittiert Indicator-Events für UI-Status-Oberflächen.

Wenn alle drei false sind, überspringt OpenClaw den Heartbeat-Durchlauf komplett (kein Model-Aufruf).

Pro-Channel 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

Häufige Muster

Ziel	Konfiguration
Standardverhalten (stille OKs, Alerts an)	(keine Konfiguration nötig)
Komplett still (keine Nachrichten, kein Indicator)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }`
Nur Indicator (keine Nachrichten)	`channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`
OKs nur in einem Channel	`channels.telegram.heartbeat: { showOk: true }`

HEARTBEAT.md (optional)

Wenn eine HEARTBEAT.md-Datei im Workspace existiert, weist der Standard-Prompt den Agent an, sie zu lesen. Betrachte sie als deine “Heartbeat-Checkliste”: klein, stabil und sicher, alle 30 Minuten eingebunden zu werden.

Wenn HEARTBEAT.md existiert, aber praktisch leer ist (nur Leerzeilen und Markdown-Überschriften wie # Heading), überspringt OpenClaw den Heartbeat-Durchlauf, um API-Aufrufe zu sparen. Wenn die Datei fehlt, läuft der Heartbeat trotzdem und das Modell entscheidet, was zu tun ist.

Halte sie klein (kurze Checkliste oder Erinnerungen), um Prompt-Aufblähung zu vermeiden.

Beispiel HEARTBEAT.md:

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it's daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

Kann der Agent HEARTBEAT.md aktualisieren?

Ja — wenn du ihn darum bittest.

HEARTBEAT.md ist einfach eine normale Datei im Agent-Workspace, also kannst du dem Agent (in einem normalen Chat) sowas sagen wie:

“Aktualisiere HEARTBEAT.md, um einen täglichen Kalender-Check hinzuzufügen.”
“Schreib HEARTBEAT.md um, damit sie kürzer ist und sich auf Posteingang-Follow-ups konzentriert.”

Wenn du möchtest, dass das proaktiv passiert, kannst du auch eine explizite Zeile in deinen Heartbeat-Prompt einfügen wie: “If the checklist becomes stale, update HEARTBEAT.md with a better one.”

Sicherheitshinweis: Leg keine Secrets (API-Keys, Telefonnummern, private Tokens) in HEARTBEAT.md — sie wird Teil des Prompt-Kontexts.

Manuelles Aufwecken (on-demand)

Du kannst ein System-Event einreihen und einen sofortigen Heartbeat auslösen mit:

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

Wenn mehrere Agents heartbeat konfiguriert haben, führt ein manuelles Aufwecken jeden dieser Agent-Heartbeats sofort aus.

Verwende --mode next-heartbeat, um auf den nächsten geplanten Tick zu warten.

Reasoning-Zustellung (optional)

Standardmäßig liefern Heartbeats nur die finale “Antwort”-Payload.

Wenn du Transparenz möchtest, aktiviere:

agents.defaults.heartbeat.includeReasoning: true

Wenn aktiviert, liefern Heartbeats auch eine separate Nachricht mit dem Präfix Reasoning: (gleiches Format wie /reasoning on). Das kann nützlich sein, wenn der Agent mehrere Sessions/Codexes verwaltet und du sehen willst, warum er dich angepingt hat — aber es kann auch mehr interne Details preisgeben, als du möchtest. In Gruppenchats lieber deaktiviert lassen.

Kostenbewusstsein

Heartbeats führen vollständige Agent-Durchläufe aus. Kürzere Intervalle verbrauchen mehr Tokens. Halte HEARTBEAT.md klein und erwäge ein günstigeres model oder target: "none", wenn du nur interne Status-Updates willst.