Heartbeat

Heartbeat führt regelmäßige Agent-Turns in der Hauptsitzung aus, damit das Modell alles melden kann, was Aufmerksamkeit erfordert, ohne Sie mit Nachrichten zu überfluten.

Heartbeat ist ein geplanter Turn in der Hauptsitzung — er erstellt keine Hintergrundaufgaben-Einträge. Aufgabeneinträge sind für entkoppelte Arbeit gedacht (ACP-Läufe, Subagenten, isolierte Cron-Jobs).

Fehlerbehebung: Geplante Aufgaben

Schnellstart (Einsteiger)

Beispielkonfiguration:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files        isolatedSession: true, // optional: fresh session each run (no conversation history)        skipWhenBusy: true, // optional: also defer when this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Thinking` message too      },    },  },}

Standardwerte

• Intervall: 30m (oder 1h, wenn Anthropic OAuth-/Token-Authentifizierung als Authentifizierungsmodus erkannt wird, einschließlich Wiederverwendung der Claude CLI). Setzen Sie agents.defaults.heartbeat.every oder pro Agent agents.list[].heartbeat.every; verwenden Sie 0m, um es 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.
• Timeout: Nicht gesetzte Heartbeat-Turns verwenden agents.defaults.timeoutSeconds, wenn gesetzt. Andernfalls verwenden sie den Heartbeat-Takt, begrenzt auf 600 Sekunden. Setzen Sie agents.defaults.heartbeat.timeoutSeconds oder pro Agent agents.list[].heartbeat.timeoutSeconds für längere Heartbeat-Arbeit.
• Der Heartbeat-Prompt wird wortgetreu als Benutzernachricht gesendet. Der System-Prompt enthält nur dann einen Abschnitt „Heartbeat“, wenn Heartbeats für den Standard-Agent aktiviert sind, und der Lauf wird intern markiert.
• Wenn Heartbeats mit 0m deaktiviert sind, lassen normale Läufe auch HEARTBEAT.md aus dem Bootstrap-Kontext weg, damit das Modell keine Heartbeat-spezifischen 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.
• Heartbeats werden automatisch zurückgestellt, während Cron-Arbeit aktiv ist oder in der Warteschlange steht. Setzen Sie heartbeat.skipWhenBusy: true, um einen Agent auch bei seinen eigenen sitzungsschlüsselgebundenen Subagenten- oder verschachtelten Befehls-Lanes zurückzustellen; gleichgeordnete Agenten pausieren nicht mehr nur deshalb, weil ein anderer Agent Subagenten-Arbeit ausführt.

Wofür der Heartbeat-Prompt gedacht ist

Der Standard-Prompt ist absichtlich breit gefasst:

• Hintergrundaufgaben: „Ausstehende Aufgaben berücksichtigen“ regt den Agent an, Follow-ups zu prüfen (Posteingang, Kalender, Erinnerungen, wartende Arbeit) und alles Dringende zu melden.
• Menschlicher Check-in: „Tagsüber gelegentlich bei Ihrem Menschen nachfragen“ regt gelegentlich eine leichtgewichtige Nachricht wie „Brauchen Sie etwas?“ an, vermeidet aber nächtliche Störungen, indem Ihre konfigurierte lokale Zeitzone verwendet wird (siehe Zeitzone).

Heartbeat kann auf abgeschlossene Hintergrundaufgaben reagieren, aber ein Heartbeat-Lauf selbst erstellt keinen Aufgabeneintrag.

Wenn ein Heartbeat etwas sehr Spezifisches tun soll (z. B. „Gmail-PubSub-Statistiken prüfen“ oder „Gateway-Zustand verifizieren“), setzen Sie agents.defaults.heartbeat.prompt (oder agents.list[].heartbeat.prompt) auf einen benutzerdefinierten Text (wird wortgetreu gesendet).

Antwortvertrag

• Wenn nichts Aufmerksamkeit erfordert, antworten Sie mit HEARTBEAT_OK.
• Tool-fähige Heartbeat-Läufe können stattdessen heartbeat_respond mit notify: false für kein sichtbares Update aufrufen, oder notify: true plus notificationText für eine Warnung. Wenn vorhanden, hat die strukturierte Tool-Antwort Vorrang vor dem Text-Fallback.
• Während Heartbeat-Lä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 in der Mitte einer Antwort erscheint, wird es nicht besonders behandelt.
• Bei Warnungen nicht HEARTBEAT_OK einschließen; geben Sie nur den Warntext zurück.

Außerhalb von Heartbeats wird ein versehentliches HEARTBEAT_OK am Anfang/Ende einer Nachricht entfernt und protokolliert; eine Nachricht, die nur HEARTBEAT_OK enthält, wird verworfen.

Konfiguration

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Thinking message when available)        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        to: "+15551234567", // optional channel-specific override        accountId: "ops-bot", // optional multi-account channel id        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 chars allowed after HEARTBEAT_OK      },    },  },}

Geltungsbereich und Vorrang

• agents.defaults.heartbeat legt das globale Heartbeat-Verhalten fest.
• agents.list[].heartbeat wird darübergelegt; wenn ein Agent einen heartbeat-Block hat, führen nur diese Agenten Heartbeats aus.
• channels.defaults.heartbeat legt Sichtbarkeitsstandards für alle Kanäle fest.
• channels.<channel>.heartbeat überschreibt Kanalstandardwerte.
• channels.<channel>.accounts.<id>.heartbeat (Multi-Account-Kanäle) überschreibt Einstellungen pro Kanal.

Heartbeats pro Agent

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

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

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          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.",        },      },    ],  },}

Beispiel für aktive Stunden

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

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz        },      },    },  },}

Außerhalb dieses Fensters (vor 9 Uhr oder nach 22 Uhr Eastern Time) werden Heartbeats übersprungen. Der nächste geplante Tick innerhalb des Fensters läuft normal.

24/7-Einrichtung

Wenn Heartbeats den ganzen Tag laufen sollen, verwenden Sie eines dieser Muster:

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

Multi-Account-Beispiel

Verwenden Sie accountId, um ein bestimmtes Konto auf Multi-Account-Kanälen wie Telegram anzusteuern:

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: route to a specific topic/thread          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 # Hide HEARTBEAT_OK (default)      showAlerts: true # Show alert messages (default)      useIndicator: true # Emit indicator events (default)  telegram:    heartbeat:      showOk: true # Show OK acknowledgments on Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Suppress alert delivery for this account

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

Was jedes Flag bewirkt

• showOk: sendet eine HEARTBEAT_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-Statusflächen aus.

Wenn alle drei falsch sind, überspringt OpenClaw den Heartbeat-Lauf vollständig (kein Modellaufruf).

Beispiele pro Kanal und pro Konto

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # all Slack accounts    accounts:      ops:        heartbeat:          showAlerts: false # suppress alerts for the ops account only  telegram:    heartbeat:      showOk: true

Häufige Muster

HEARTBEAT.md (optional)

Wenn im Workspace 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 Läufen wird HEARTBEAT.md nur eingefügt, wenn Heartbeat-Anleitung für den Standardagenten aktiviert ist. Das Deaktivieren der Heartbeat-Kadenz mit 0m oder das Setzen von includeSystemPromptSection: false lässt sie aus dem normalen Bootstrap-Kontext weg.

Im nativen Codex-Harness wird der Inhalt von HEARTBEAT.md nicht in den Durchlauf eingefügt. Wenn die Datei vorhanden ist und Inhalt enthält, der nicht nur aus Leerraum besteht, verweisen die Heartbeat-Anweisungen für den Kollaborationsmodus Codex auf die Datei und weisen ihn an, sie vor dem Fortfahren zu lesen.

Wenn HEARTBEAT.md vorhanden, aber praktisch leer ist (nur Leerzeilen, Markdown-/HTML-Kommentare, Markdown-Überschriften wie # Heading, Fence-Markierungen oder leere Checklisten-Stubs), ü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 sehr klein (kurze Checkliste oder Erinnerungen), um Prompt-Aufblähung zu vermeiden.

Beispiel für 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.

tasks:-Blöcke

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

Beispiel:

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

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

Kann der Agent HEARTBEAT.md aktualisieren?

Ja — wenn Sie ihn darum bitten.

HEARTBEAT.md ist nur eine normale Datei im Agenten-Workspace, daher können Sie dem Agenten (in einem normalen Chat) zum Beispiel sagen:

• „Aktualisieren Sie HEARTBEAT.md, um eine tägliche Kalenderprüfung hinzuzufügen.“
• „Schreiben Sie HEARTBEAT.md neu, damit sie kürzer ist und sich auf Inbox-Follow-ups konzentriert.“

Wenn dies proaktiv geschehen soll, können Sie auch eine explizite Zeile in Ihren Heartbeat-Prompt aufnehmen, etwa: „Wenn die Checkliste veraltet ist, aktualisieren Sie HEARTBEAT.md mit einer besseren.“

Manuelles Wecken (bei Bedarf)

Sie können ein Systemereignis einreihen und mit folgendem Befehl einen sofortigen Heartbeat auslösen:

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

Wenn für mehrere Agenten heartbeat konfiguriert ist, führt ein manuelles Wecken jeden dieser Agenten-Heartbeats sofort aus.

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

Reasoning-Zustellung (optional)

Standardmäßig liefern Heartbeats nur den finalen „Antwort“-Payload.

Wenn Sie Transparenz wünschen, aktivieren Sie:

• agents.defaults.heartbeat.includeReasoning: true

Wenn aktiviert, liefern Heartbeats außerdem eine separate Nachricht mit dem Präfix Thinking (gleiche Form wie /reasoning on). Das kann nützlich sein, wenn der Agent mehrere Sitzungen/Codexes verwaltet und Sie sehen möchten, warum er entschieden hat, Sie anzupingen — es kann aber auch mehr interne Details preisgeben, als Sie möchten. In Gruppenchats sollten Sie es bevorzugt deaktiviert lassen.

Kostenbewusstsein

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

• Verwenden Sie isolatedSession: true, um zu vermeiden, die vollständige Konversationshistorie zu senden (~100K Tokens herunter auf ~2-5K pro Lauf).
• Verwenden Sie lightContext: true, um Bootstrap-Dateien auf nur HEARTBEAT.md zu beschränken.
• Setzen Sie ein günstigeres model (z. B. ollama/llama3.2:1b).
• Halten Sie HEARTBEAT.md klein.
• Verwenden Sie target: "none", wenn Sie nur interne Statusaktualisierungen möchten.

Kontextüberlauf nach Heartbeat

Wenn ein Heartbeat zuvor eine bestehende Sitzung auf einem kleineren lokalen Modell hinterlassen hat, zum Beispiel einem Ollama-Modell mit einem 32k-Fenster, und der nächste Hauptsitzungsdurchlauf einen Kontextüberlauf meldet, setzen Sie das Sitzungs-Laufzeitmodell wieder auf das konfigurierte primäre Modell zurück. Die Zurücksetzungsnachricht von OpenClaw weist darauf hin, wenn das letzte Laufzeitmodell mit dem konfigurierten heartbeat.model übereinstimmt.

Aktuelle Heartbeats bewahren das bestehende Laufzeitmodell der gemeinsamen Sitzung, nachdem der Lauf abgeschlossen ist. Sie können weiterhin isolatedSession: true verwenden, um Heartbeats in einer frischen Sitzung auszuführen, dies mit lightContext: true für den kleinsten Prompt kombinieren oder ein Heartbeat-Modell mit einem Kontextfenster wählen, das groß genug für die gemeinsame Sitzung ist.

Verwandt

• Automatisierung — alle Automatisierungsmechanismen auf einen Blick
• Hintergrundaufgaben — wie losgelöste Arbeit nachverfolgt wird
• Zeitzone — wie die Zeitzone die Heartbeat-Planung beeinflusst
• Fehlerbehebung — Automatisierungsprobleme debuggen