Heartbeat (Gateway)

Heartbeat oder Cron? Unter Cron vs. Heartbeat findest du Orientierungshilfe, wann du was verwenden solltest.

Heartbeat fĂŒhrt periodische Agent-Turns in der Hauptsession aus, damit das Modell Dinge ans Licht bringen kann, die Aufmerksamkeit erfordern — ohne dich zuzuspammen.

Fehlerbehebung: /automation/troubleshooting

Schnellstart (Einsteiger)

  1. Lass Heartbeats aktiviert (Standard ist 30m, oder 1h bei Anthropic OAuth/Setup-Token) oder setze deine eigene Frequenz.
  2. Erstelle eine kleine HEARTBEAT.md-Checkliste im Agent-Workspace (optional, aber empfohlen).
  3. Entscheide, wohin Heartbeat-Nachrichten gehen sollen (target: "none" ist der Standard; setze target: "last", um an den letzten Kontakt zu senden).
  4. Optional: Aktiviere die Heartbeat-Reasoning-Zustellung fĂŒr Transparenz.
  5. Optional: Verwende leichtgewichtigen Bootstrap-Kontext, wenn Heartbeat-Runs nur HEARTBEAT.md benötigen.
  6. Optional: BeschrÀnke Heartbeats auf aktive Stunden (lokale Zeit).

Beispielkonfiguration:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explizite Zustellung an letzten Kontakt (Standard ist "none")
        directPolicy: "allow", // Standard: allow fĂŒr Direct/DM-Ziele; "block" zum UnterdrĂŒcken
        lightContext: true, // optional: nur HEARTBEAT.md aus Bootstrap-Dateien injizieren
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: auch separate `Reasoning:`-Nachricht senden
      },
    },
  },
}

Standards

  • 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-Body (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 Benutzernachricht gesendet. Der System-Prompt enthĂ€lt einen “Heartbeat”-Abschnitt und der Run 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 bewusst breit gefasst:

  • Hintergrundaufgaben: “Consider outstanding tasks” fordert den Agenten auf, Follow-ups zu prĂŒfen (Posteingang, Kalender, Erinnerungen, wartende Arbeit) und dringende Dinge hervorzuheben.
  • Menschlicher Check-in: “Checkup sometimes on your human during day time” regt eine gelegentliche leichtgewichtige “Brauchst du etwas?”-Nachricht an, vermeidet aber Nacht-Spam durch Verwendung deiner konfigurierten lokalen Zeitzone (siehe /concepts/timezone).

Wenn du möchtest, dass ein Heartbeat etwas sehr Bestimmtes tut (z. B. “prĂŒfe Gmail-PubSub-Stats” oder “verifiziere Gateway-Gesundheit”), setze agents.defaults.heartbeat.prompt (oder agents.list[].heartbeat.prompt) auf einen benutzerdefinierten Body (wird wörtlich gesendet).

Antwort-Vertrag

  • Wenn nichts Aufmerksamkeit erfordert, antworte mit HEARTBEAT_OK.
  • WĂ€hrend Heartbeat-Runs 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 (Standard: 300) betrĂ€gt.
  • Wenn HEARTBEAT_OK in der Mitte einer Antwort erscheint, wird es nicht besonders behandelt.
  • FĂŒr Alarme kein HEARTBEAT_OK verwenden; gib nur den Alarmtext zurĂŒck.

Außerhalb von Heartbeats wird 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-6",
        includeReasoning: false, // Standard: false (liefert separate Reasoning:-Nachricht wenn verfĂŒgbar)
        lightContext: false, // Standard: false; true behÀlt nur HEARTBEAT.md aus Workspace-Bootstrap-Dateien
        target: "last", // Standard: none | Optionen: last | none | <Kanal-ID> (Core oder Plugin, z.B. "bluebubbles")
        to: "+15551234567", // optionaler kanalspezifischer Override
        accountId: "ops-bot", // optionale Multi-Account-Kanal-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. Zeichen nach HEARTBEAT_OK erlaubt
      },
    },
  },
}

Geltungsbereich und PrioritÀt

  • agents.defaults.heartbeat setzt das globale Heartbeat-Verhalten.
  • agents.list[].heartbeat wird darauf zusammengefĂŒhrt; wenn ein Agent einen heartbeat-Block hat, fĂŒhren nur diese Agenten Heartbeats aus.
  • 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 Kanal-Einstellungen.

Pro-Agent-Heartbeats

Wenn ein agents.list[]-Eintrag einen heartbeat-Block enthĂ€lt, fĂŒhren nur diese Agenten Heartbeats aus. Der Pro-Agent-Block wird auf agents.defaults.heartbeat zusammengefĂŒhrt (du kannst also gemeinsame Standards einmal setzen und pro Agent ĂŒberschreiben).

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explizite Zustellung an letzten Kontakt (Standard ist "none")
      },
    },
    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.",
        },
      },
    ],
  },
}

Beispiel fĂŒr aktive Stunden

Heartbeats auf GeschÀftszeiten in einer bestimmten Zeitzone beschrÀnken:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explizite Zustellung an letzten Kontakt (Standard ist "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; verwendet deine userTimezone wenn gesetzt, sonst Host-TZ
        },
      },
    },
  },
}

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

24/7-Setup

Wenn du Heartbeats rund um die Uhr laufen lassen willst, verwende eines dieser Muster:

  • Lass activeHours komplett weg (keine Zeitfenster-EinschrĂ€nkung; das ist das Standardverhalten).
  • Setze ein Ganztagesfenster: activeHours: { start: "00:00", end: "24:00" }.

Setze nicht dieselbe start- und end-Zeit (z. B. 08:00 bis 08:00). Das wird als Null-Breite-Fenster behandelt, sodass Heartbeats immer ĂŒbersprungen werden.

Multi-Account-Beispiel

Verwende accountId, um ein bestimmtes Konto bei Multi-Account-KanÀlen wie Telegram anzusprechen:

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // optional: an ein bestimmtes Topic/Thread weiterleiten
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

Feld-ErlÀuterungen

  • every: Heartbeat-Intervall (Duration-String; Standardeinheit = Minuten).
  • model: optionaler Modell-Override fĂŒr Heartbeat-Runs (provider/model).
  • includeReasoning: wenn aktiviert, wird auch die separate Reasoning:-Nachricht zugestellt, wenn verfĂŒgbar (gleiches Format wie /reasoning on).
  • lightContext: wenn true, verwenden Heartbeat-Runs leichtgewichtigen Bootstrap-Kontext und behalten nur HEARTBEAT.md aus Workspace-Bootstrap-Dateien.
  • session: optionaler Session-Key fĂŒr Heartbeat-Runs.
    • main (Standard): Agent-Hauptsession.
    • Expliziter Session-Key (kopieren aus openclaw sessions --json oder der Sessions-CLI).
    • Session-Key-Formate: siehe Sessions und Groups.
  • target:
    • last: An den zuletzt genutzten externen Kanal zustellen.
    • Expliziter Kanal: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
    • none (Standard): Heartbeat ausfĂŒhren, aber nicht extern zustellen.
  • directPolicy: Steuert das Direct/DM-Zustellverhalten:
    • allow (Standard): Direct/DM-Heartbeat-Zustellung erlauben.
    • block: Direct/DM-Zustellung unterdrĂŒcken (reason=dm-blocked).
  • to: optionaler EmpfĂ€nger-Override (kanalspezifische ID, z. B. E.164 fĂŒr WhatsApp oder Telegram-Chat-ID). FĂŒr Telegram-Topics/Threads verwende <chatId>:topic:<messageThreadId>.
  • accountId: optionale Account-ID fĂŒr Multi-Account-KanĂ€le. Bei target: "last" gilt die Account-ID fĂŒr den aufgelösten letzten Kanal, wenn dieser Accounts unterstĂŒtzt; andernfalls wird sie ignoriert. Wenn die Account-ID nicht mit einem konfigurierten Account des aufgelösten Kanals ĂŒbereinstimmt, wird die Zustellung ĂŒbersprungen.
  • prompt: ĂŒberschreibt den Standard-Prompt-Body (wird nicht zusammengefĂŒhrt).
  • ackMaxChars: maximale Zeichenzahl nach HEARTBEAT_OK vor der Zustellung.
  • suppressToolErrorWarnings: wenn true, unterdrĂŒckt Tool-Fehler-Warnungs-Payloads wĂ€hrend Heartbeat-Runs.
  • activeHours: beschrĂ€nkt Heartbeat-Runs auf ein Zeitfenster. Objekt mit start (HH:MM, inklusive; verwende 00:00 fĂŒr Tagesanfang), end (HH:MM exklusiv; 24:00 erlaubt fĂŒr Tagesende) und optionalem timezone.
    • Weggelassen oder "user": verwendet deine agents.defaults.userTimezone wenn gesetzt, sonst Fallback auf die Host-System-Zeitzone.
    • "local": verwendet immer die Host-System-Zeitzone.
    • Jeder IANA-Bezeichner (z. B. America/New_York): wird direkt verwendet; bei ungĂŒltigem Wert Fallback auf das "user"-Verhalten oben.
    • start und end dĂŒrfen nicht gleich sein fĂŒr ein aktives Fenster; gleiche Werte werden als Null-Breite behandelt (immer außerhalb des Fensters).
    • Außerhalb des aktiven Fensters werden Heartbeats ĂŒbersprungen, bis der nĂ€chste Tick innerhalb des Fensters liegt.

Zustellverhalten

  • Heartbeats laufen standardmĂ€ĂŸig in der Hauptsession des Agenten (agent:<id>:<mainKey>), oder global wenn session.scope = "global". Setze session um auf eine bestimmte Kanal-Session (Discord/WhatsApp/etc.) zu ĂŒberschreiben.
  • session beeinflusst nur den Run-Kontext; die Zustellung wird durch target und to gesteuert.
  • Um an einen bestimmten Kanal/EmpfĂ€nger zuzustellen, setze target + to. Mit target: "last" wird der zuletzt genutzte externe Kanal fĂŒr diese Session verwendet.
  • Heartbeat-Zustellungen erlauben standardmĂ€ĂŸig Direct/DM-Ziele. Setze directPolicy: "block", um Direct-Target-Sends zu unterdrĂŒcken, wĂ€hrend der Heartbeat-Turn trotzdem lĂ€uft.
  • Wenn die Hauptwarteschlange beschĂ€ftigt ist, wird der Heartbeat ĂŒbersprungen und spĂ€ter erneut versucht.
  • Wenn target kein externes Ziel ergibt, lĂ€uft der Run trotzdem, aber keine ausgehende Nachricht wird gesendet.
  • Reine Heartbeat-Antworten halten die Session nicht am Leben; der letzte updatedAt-Zeitpunkt wird wiederhergestellt, sodass sich Idle-Expiry normal verhĂ€lt.

Sichtbarkeitssteuerung

StandardmĂ€ĂŸig werden HEARTBEAT_OK-BestĂ€tigungen unterdrĂŒckt, wĂ€hrend Alarm-Inhalte zugestellt werden. Du kannst das pro Kanal oder pro Account anpassen:

channels:
  defaults:
    heartbeat:
      showOk: false # HEARTBEAT_OK ausblenden (Standard)
      showAlerts: true # Alarm-Nachrichten anzeigen (Standard)
      useIndicator: true # Indikator-Events senden (Standard)
  telegram:
    heartbeat:
      showOk: true # OK-BestÀtigungen auf Telegram anzeigen
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Alarm-Zustellung fĂŒr dieses Konto unterdrĂŒcken

PrioritĂ€t: pro Account → pro Kanal → Kanal-Standards → eingebaute Standards.

Was jedes Flag tut

  • showOk: Sendet eine HEARTBEAT_OK-BestĂ€tigung, wenn das Modell eine OK-only-Antwort zurĂŒckgibt.
  • showAlerts: Sendet den Alarm-Inhalt, wenn das Modell eine Nicht-OK-Antwort zurĂŒckgibt.
  • useIndicator: Sendet Indikator-Events fĂŒr UI-Status-OberflĂ€chen.

Wenn alle drei false sind, ĂŒberspringt OpenClaw den Heartbeat-Run komplett (kein Modellaufruf).

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 # Alarme nur fĂŒr das ops-Konto unterdrĂŒcken
  telegram:
    heartbeat:
      showOk: true

GĂ€ngige Muster

ZielKonfiguration
Standardverhalten (stille OKs, Alarme an)(keine Konfiguration nötig)
Komplett 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 Kanalchannels.telegram.heartbeat: { showOk: true }

HEARTBEAT.md (optional)

Wenn eine HEARTBEAT.md-Datei im Workspace existiert, weist der Standard-Prompt den Agenten an, sie zu lesen. Betrachte sie als deine “Heartbeat-Checkliste”: klein, stabil und sicher fĂŒr die Verwendung alle 30 Minuten.

Wenn HEARTBEAT.md existiert, aber praktisch leer ist (nur Leerzeilen und Markdown-Überschriften wie # Heading), ĂŒberspringt OpenClaw den Heartbeat-Run, um API-Aufrufe zu sparen. Fehlt die Datei, 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-Checkliste

- Kurzer Scan: Etwas Dringendes in den PosteingÀngen?
- Wenn es Tag ist, mache einen leichten Check-in, falls nichts anderes ansteht.
- Wenn eine Aufgabe blockiert ist, notiere _was fehlt_ und frage Peter beim nÀchsten Mal.

Kann der Agent HEARTBEAT.md aktualisieren?

Ja — wenn du ihn darum bittest.

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

  • “Aktualisiere HEARTBEAT.md mit einem tĂ€glichen Kalender-Check.”
  • “Schreibe HEARTBEAT.md um, sodass sie kĂŒrzer ist und sich auf Posteingangs-Follow-ups konzentriert.”

Wenn du willst, dass das proaktiv passiert, kannst du auch eine explizite Zeile in deinem Heartbeat-Prompt einfĂŒgen wie: “If the checklist becomes stale, update HEARTBEAT.md with a better one.”

Sicherheitshinweis: Schreibe keine Geheimnisse (API-SchlĂŒssel, Telefonnummern, private Token) in HEARTBEAT.md — sie wird Teil des Prompt-Kontexts.

Manueller Wake (bei Bedarf)

Du kannst ein System-Event in die Warteschlange stellen und einen sofortigen Heartbeat auslösen mit:

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

Wenn mehrere Agenten heartbeat konfiguriert haben, fĂŒhrt ein manueller Wake die Heartbeats all dieser Agenten sofort aus.

Verwende --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 du Transparenz willst, 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/Codexe verwaltet und du sehen willst, warum er sich gemeldet hat — aber es kann auch mehr interne Details preisgeben als gewĂŒnscht. In Gruppenchats lieber deaktiviert lassen.

Kostenbewusstsein

Heartbeats fĂŒhren vollstĂ€ndige Agent-Turns aus. KĂŒrzere Intervalle verbrauchen mehr Token. Halte HEARTBEAT.md klein und erwĂ€ge ein gĂŒnstigeres model oder target: "none", wenn du nur interne State-Updates willst.

arrow_back
ZurĂŒck
Health
Weiter
Doctor
arrow_forward