Heartbeat

Heartbeat führt periodische Agent-Durchläufe in der Hauptsitzung aus, damit das Modell alles anzeigen kann, was Aufmerksamkeit benötigt, ohne Sie mit Nachrichten zu überfluten.

Heartbeat ist ein geplanter Durchlauf in der Hauptsitzung — es erstellt keine Hintergrundaufgaben-Einträge. Aufgabeneinträge sind für losgelöste Arbeit gedacht (ACP-Durchläufe, Subagents, 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 subagent or nested lanes are busy
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

# Standardwerte

• Intervall: 30m (oder 1h, wenn Anthropic OAuth-/Token-Authentifizierung als Authentifizierungsmodus erkannt wird, einschließlich Claude CLI-Wiederverwendung). Setzen Sie agents.defaults.heartbeat.every oder pro Agent agents.list[].heartbeat.every; verwenden Sie 0m, um es zu deaktivieren.
• Prompt-Inhalt (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 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 Durchlauf wird intern markiert.
• Wenn Heartbeats mit 0m deaktiviert sind, lassen normale Durchläufe HEARTBEAT.md auch aus dem Bootstrap-Kontext weg, damit das Modell keine reinen Heartbeat-Anweisungen sieht.
• Aktive Zeiten (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, solange Cron-Arbeit aktiv ist oder in der Warteschlange steht. Setzen Sie heartbeat.skipWhenBusy: true, um auch bei zusätzlichen ausgelasteten Lanes zurückzustellen (Subagent- oder verschachtelte Befehlsarbeit); dies ist nützlich für lokales Ollama und andere eingeschränkte Hosts mit einer einzelnen Laufzeit.

# Wofür der Heartbeat-Prompt gedacht ist

Der Standard-Prompt ist absichtlich breit gefasst:

• Hintergrundaufgaben: „Ausstehende Aufgaben berücksichtigen“ stößt den Agent an, Follow-ups zu prüfen (Posteingang, Kalender, Erinnerungen, in Warteschlange stehende Arbeit) und alles Dringende anzuzeigen.
• Nachfrage beim Menschen: „Tagsüber gelegentlich bei Ihrem Menschen nachfragen“ stößt eine gelegentliche, leichtgewichtige Nachricht wie „Brauchen Sie etwas?“ an, vermeidet aber nächtliche Nachrichten durch die Verwendung Ihrer konfigurierten lokalen Zeitzone (siehe Zeitzone).

Heartbeat kann auf abgeschlossene Hintergrundaufgaben reagieren, aber ein Heartbeat-Durchlauf 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 eigenen Inhalt (wortgetreu gesendet).

# Antwortvertrag

• Wenn nichts Aufmerksamkeit benötigt, antworten Sie mit HEARTBEAT_OK.
• Tool-fähige Heartbeat-Durchläufe können stattdessen heartbeat_respond mit notify: false für keine sichtbare Aktualisierung oder notify: true plus notificationText für eine Warnung aufrufen. Wenn vorhanden, hat die strukturierte Tool-Antwort Vorrang vor dem Text-Fallback.
• 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 wird verworfen, wenn der verbleibende Inhalt ≤ ackMaxChars ist (Standard: 300).
• Wenn HEARTBEAT_OK in der Mitte einer Antwort erscheint, wird es nicht besonders behandelt.
• Fügen Sie bei Warnungen kein HEARTBEAT_OK ein; geben Sie nur den Warnungstext 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 Reasoning: 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 subagent/nested lanes
        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        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über zusammengeführt; wenn ein Agent einen heartbeat-Block hat, führen nur diese Agents Heartbeats aus.
• channels.defaults.heartbeat legt Sichtbarkeitsstandards für alle Kanäle fest.
• channels.<channel>.heartbeat überschreibt Kanalstandards.
• channels.<channel>.accounts.<id>.heartbeat (Kanäle mit mehreren Konten) überschreibt Einstellungen pro Kanal.

# Heartbeats pro Agent

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

Beispiel: zwei Agents, 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 Zeiten

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 wird normal ausgeführt.

# 24/7-Einrichtung

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

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

# Beispiel mit mehreren Konten

Verwenden Sie accountId, um ein bestimmtes Konto in Kanälen mit mehreren Konten 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

everystring

Heartbeat-Intervall (Dauerzeichenfolge; Standardeinheit = Minuten).

modelstring

Optionale Modellüberschreibung für Heartbeat-Durchläufe (provider/model).

includeReasoningboolean

Wenn aktiviert, wird auch die separate Reasoning:-Nachricht zugestellt, sofern verfügbar (dieselbe Form wie /reasoning on).

lightContextboolean

Wenn true, verwenden Heartbeat-Durchläufe leichtgewichtigen Bootstrap-Kontext und behalten nur HEARTBEAT.md aus den Workspace-Bootstrap-Dateien bei.

isolatedSessionboolean

Wenn true, läuft jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf. Verwendet dasselbe Isolationsmuster wie Cron sessionTarget: "isolated". Reduziert die Token-Kosten pro Heartbeat erheblich. Kombinieren Sie dies mit lightContext: true für maximale Einsparungen. Das Zustellungsrouting verwendet weiterhin den Kontext der Hauptsitzung.

skipWhenBusyboolean

Wenn true, werden Heartbeat-Durchläufe bei zusätzlichen ausgelasteten Lanes zurückgestellt: Subagent- oder verschachtelte Befehlsarbeit. Cron-Lanes stellen Heartbeats immer zurück, auch ohne dieses Flag, sodass Hosts mit lokalen Modellen nicht gleichzeitig Cron- und Heartbeat-Prompts ausführen.

sessionstring

Optionaler Sitzungsschlüssel für Heartbeat-Durchläufe.

• main (Standard): Hauptsitzung des Agent.
• Expliziter Sitzungsschlüssel (kopieren Sie ihn aus openclaw sessions --json oder der Sitzungs-CLI).
• Sitzungsschlüsselformate: siehe Sitzungen und Gruppen.

targetstring

• last: an den zuletzt verwendeten externen Kanal zustellen.
• expliziter Kanal: beliebiger konfigurierter Kanal oder Plugin-ID, zum Beispiel discord, matrix, telegram oder whatsapp.
• none (Standard): Heartbeat ausführen, aber nicht extern zustellen.

directPolicy"allow" | "block"

Steuert das Verhalten bei direkter/DM-Zustellung. allow: direkte/DM-Heartbeat-Zustellung erlauben. block: direkte/DM-Zustellung unterdrücken (reason=dm-blocked).

tostring

Optionale Empfängerüberschreibung (kanalspezifische ID, z. B. E.164 für WhatsApp oder eine Telegram-Chat-ID). Verwenden Sie für Telegram-Themen/Threads <chatId>:topic:<messageThreadId>.

accountIdstring

Optionale Konto-ID für Kanäle mit mehreren Konten. Bei target: "last" gilt die Konto-ID für den aufgelösten letzten Kanal, wenn dieser Konten unterstützt; andernfalls wird sie ignoriert. Wenn die Konto-ID keinem konfigurierten Konto für den aufgelösten Kanal entspricht, wird die Zustellung übersprungen.

promptstring

Überschreibt den Standard-Prompt-Inhalt (wird nicht zusammengeführt).

ackMaxCharsnumber

Maximal zulässige Zeichenanzahl nach HEARTBEAT_OK vor der Zustellung.

suppressToolErrorWarningsboolean

Wenn true, werden Warnungs-Payloads für Tool-Fehler während Heartbeat-Ausführungen unterdrückt.

activeHoursobject

Beschränkt Heartbeat-Ausführungen auf ein Zeitfenster. Objekt mit start (HH:MM, inklusive; verwenden Sie 00:00 für Tagesbeginn), end (HH:MM exklusiv; 24:00 ist für Tagesende zulässig) und optional timezone.

• Ausgelassen oder "user": verwendet Ihr agents.defaults.userTimezone, falls gesetzt, andernfalls wird auf die Zeitzone des Hostsystems zurückgegriffen.
• "local": verwendet immer die Zeitzone des Hostsystems.
• Beliebige IANA-Kennung (z. B. America/New_York): wird direkt verwendet; falls ungültig, wird auf das oben beschriebene "user"-Verhalten zurückgegriffen.
• start und end dürfen für ein aktives Zeitfenster nicht gleich sein; gleiche Werte werden als Breite null behandelt (immer außerhalb des Fensters).
• Außerhalb des aktiven Zeitfensters werden Heartbeats bis zum nächsten Tick innerhalb des Fensters übersprungen.

# Zustellungsverhalten

# Sichtbarkeitssteuerung

Standardmäßig werden HEARTBEAT_OK-Bestätigungen unterdrückt, während Alert-Inhalte 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 → Kanalstandardwerte → integrierte Standardwerte.

# 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: gibt Indicator-Ereignisse für UI-Statusflächen aus.

Wenn alle drei false sind, ü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 # all Slack accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suppress alerts for the ops account only
  telegram:
    heartbeat:
      showOk: true

# Häufige Muster

Ziel	Konfiguration
Standardverhalten (stille OKs, Alerts an)	(keine Konfiguration erforderlich)
Vollständig 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 Kanal	channels.telegram.heartbeat: { showOk: true }

# HEARTBEAT.md (optional)

Wenn im Workspace eine Datei HEARTBEAT.md vorhanden ist, weist der Standard-Prompt den Agent an, sie zu lesen. Betrachten Sie sie als Ihre „Heartbeat-Checkliste“: klein, stabil und sicher genug, um alle 30 Minuten einbezogen zu werden.

Bei normalen Ausführungen wird HEARTBEAT.md nur injiziert, wenn Heartbeat-Anleitung für den Standard-Agent aktiviert ist. Das Deaktivieren der Heartbeat-Kadenz mit 0m oder das Setzen von includeSystemPromptSection: false lässt sie aus dem normalen Bootstrap-Kontext weg.

Wenn HEARTBEAT.md vorhanden, aber praktisch leer ist (nur Leerzeilen und Markdown-Überschriften wie # Heading), überspringt OpenClaw die Heartbeat-Ausführung, um API-Aufrufe zu sparen. Dieses Überspringen wird als reason=empty-heartbeat-file gemeldet. Wenn die Datei fehlt, wird der Heartbeat trotzdem ausgeführt 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 eine einzelne Heartbeat-Datei mehrere regelmäßige Prüfungen enthalten soll, 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 Agent-Workspace, daher können Sie dem Agent (in einem normalen Chat) etwa Folgendes sagen:

• „Aktualisiere HEARTBEAT.md, um eine tägliche Kalenderprüfung hinzuzufügen.“
• „Schreibe HEARTBEAT.md kürzer um und konzentriere sie auf Inbox-Follow-ups.“

Wenn Sie möchten, dass dies proaktiv geschieht, können Sie außerdem eine explizite Zeile in Ihren Heartbeat-Prompt aufnehmen, etwa: „Wenn die Checkliste veraltet ist, aktualisiere HEARTBEAT.md mit einer besseren.“

# Manuelles Wecken (bei Bedarf)

Sie können ein Systemereignis 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 Wecken jeden dieser Agent-Heartbeats sofort aus.

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

# Reasoning-Zustellung (optional)

Standardmäßig stellen Heartbeats nur den finalen „answer“-Payload zu.

Wenn Sie Transparenz wünschen, aktivieren Sie:

• agents.defaults.heartbeat.includeReasoning: true

Wenn aktiviert, stellen Heartbeats außerdem eine separate Nachricht mit dem Präfix Reasoning: zu (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 sollte dies vorzugsweise deaktiviert bleiben.

# Kostenbewusstsein

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

• Verwenden Sie isolatedSession: true, um zu vermeiden, dass der vollständige Gesprächsverlauf gesendet wird (~100K Tokens herunter auf ~2-5K pro Ausführung).
• 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 Zustandsaktualisierungen 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 32k-Fenster, und der nächste Turn der Hauptsitzung einen Kontextüberlauf meldet, setzen Sie das Laufzeitmodell der Sitzung wieder auf das konfigurierte primäre Modell zurück. Die Reset-Nachricht von OpenClaw weist darauf hin, wenn das letzte Laufzeitmodell mit dem konfigurierten heartbeat.model übereinstimmt.

Aktuelle Heartbeats behalten nach Abschluss der Ausführung das bestehende Laufzeitmodell der gemeinsamen Sitzung bei. 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.

# Verwandte Themen

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