​

Heartbeat (Gateway)

Heartbeat vs. Cron? Siehe Cron vs Heartbeat für Hinweise, wann welches Verfahren zu verwenden ist.

​

Schnellstart (Anfänger)

1. Lassen Sie Heartbeats aktiviert (Standard ist 30m oder 1h für Anthropic OAuth/Setup-Token) oder legen Sie Ihre eigene Taktung fest.
2. Erstellen Sie eine kleine HEARTBEAT.md-Checkliste im Agent-Workspace (optional, aber empfohlen).
3. Entscheiden Sie, wohin Heartbeat-Nachrichten gesendet werden sollen (target: "last" ist der Standard).
4. Optional: Aktivieren Sie die Auslieferung der Heartbeat-Begründung für Transparenz.
5. Optional: Beschränken Sie Heartbeats auf aktive Stunden (lokale Zeit).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

Standardwerte

• Intervall: 30m (oder 1h, wenn Anthropic OAuth/Setup-Token als Authentifizierungsmodus erkannt wird). Setzen Sie agents.defaults.heartbeat.every oder pro Agent agents.list[].heartbeat.every; verwenden Sie 0m, um 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.
• Der Heartbeat-Prompt wird wortgetreu als Benutzernachricht gesendet. Der System- Prompt enthält einen Abschnitt „Heartbeat“, und der Lauf wird intern gekennzeichnet.
• 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 erfolgt. Außerhalb des Fensters werden Herzbeats übersprungen bis zum nächsten Häkchen im Fenster.

​

Wofür der Heartbeat-Prompt gedacht ist

• Hintergrundaufgaben: „Consider outstanding tasks“ veranlasst den Agenten, Nachverfolgungen (Posteingang, Kalender, Erinnerungen, Warteschlangenarbeit) zu prüfen und Dringendes hervorzuheben.
• Menschlicher Check-in: „Checkup sometimes on your human during day time“ regt gelegentliche, leichte „Brauchen Sie etwas?“-Nachrichten an, vermeidet aber nächtlichen Spam durch Verwendung Ihrer konfigurierten lokalen Zeitzone (siehe /concepts/timezone).

​

Antwortvertrag

• Wenn nichts Aufmerksamkeit erfordert, antworten Sie mit HEARTBEAT_OK.
• 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 wird verworfen, wenn der verbleibende Inhalt ≤ ackMaxChars ist (Standard: 300).
• Wenn HEARTBEAT_OK in der Mitte einer Antwort erscheint, wird es nicht speziell behandelt.
• Für Alarme nicht HEARTBEAT_OK einfügen; geben Sie nur den Alarmtext zurück.

​

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)
        target: "last", // 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 Priorität

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

​

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

​

Beispiel für aktive Stunden

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

Beispiel für mehrere Konten

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Feldnotizen

• every: Heartbeat-Intervall (Dauerzeichenfolge; Standardeinheit = Minuten).
• model: optionale Modellüberschreibung für Heartbeat-Läufe (provider/model).
• includeReasoning: wenn aktiviert, wird auch die separate Reasoning:-Nachricht ausgeliefert, sofern verfügbar (gleiche Form wie /reasoning on).
• session: optionaler Sitzungs-Schlüssel für Heartbeat-Läufe.
  • main (Standard): Hauptsitzung des Agenten.
  • Expliziter Sitzungs-Schlüssel (kopieren Sie ihn aus openclaw sessions --json oder der sessions CLI).
  • Sitzungs-Schlüsselformate: siehe Sessions und Groups.
• target:
  • last (Standard): Auslieferung an den zuletzt verwendeten externen Kanal.
  • Expliziter Kanal: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: Heartbeat ausführen, aber nicht extern ausliefern.
• to: optionale Empfängerüberschreibung (kanalspezifische ID, z. B. E.164 für WhatsApp oder eine Telegram-Chat-ID).
• accountId: optionale Konto-ID für Mehrkonten-Kanäle. Wenn target: "last", gilt die Konto-ID für den aufgelösten letzten Kanal, sofern dieser Konten unterstützt; andernfalls wird sie ignoriert. Wenn die Konto-ID keinem konfigurierten Konto für den aufgelösten Kanal entspricht, wird die Auslieferung übersprungen.
• prompt: überschreibt den Standard-Prompt-Text (wird nicht zusammengeführt).
• ackMaxChars: maximale Zeichenanzahl, die nach HEARTBEAT_OK vor der Auslieferung erlaubt ist.
• activeHours: beschränkt Heartbeat-Läufe auf ein Zeitfenster. Objekt mit start (HH:MM, inklusiv), end (HH:MM exklusiv; 24:00 für Tagesende zulässig) und optional timezone.
  • Weggelassen oder "user": verwendet Ihre agents.defaults.userTimezone, falls gesetzt, andernfalls die Zeitzone des Host-Systems.
  • "local": verwendet immer die Zeitzone des Host-Systems.
  • Beliebige IANA-Kennung (z. B. America/New_York): wird direkt verwendet; bei Ungültigkeit fällt es auf das oben genannte "user"-Verhalten zurück.
  • Außerhalb des aktiven Fensters werden Heartbeats übersprungen, bis der nächste Tick innerhalb des Fensters erfolgt.

​

Auslieferungsverhalten

• Heartbeats laufen standardmäßig in der Hauptsitzung des Agenten (agent:<id>:<mainKey>) oder global, wenn session.scope = "global". Setzen Sie session, um auf eine bestimmte Kanal-Sitzung (Discord/WhatsApp/etc.)
• session beeinflusst nur den Laufkontext; die Auslieferung wird durch target und to gesteuert.
• Um an einen bestimmten Kanal/Empfänger zu liefern, setzen Sie target + to. Mit target: "last" verwendet die Auslieferung den letzten externen Kanal für diese Sitzung.
• Wenn die Hauptwarteschlange ausgelastet ist, wird der Heartbeat übersprungen und später erneut versucht.
• Wenn target zu keinem externen Ziel aufgelöst wird, findet der Lauf dennoch statt, aber es wird keine ausgehende Nachricht gesendet.
• Nur-Heartbeat-Antworten halten die Sitzung nicht aktiv; der letzte updatedAt wird wiederhergestellt, sodass das Leerlauf-Ablaufen normal erfolgt.

​

Sichtbarkeitssteuerungen

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

​

Was jedes Flag bewirkt

• showOk: sendet eine HEARTBEAT_OK-Bestätigung, wenn das Modell eine reine OK-Antwort zurückgibt.
• showAlerts: sendet den Alarm-Inhalt, wenn das Modell eine Nicht-OK-Antwort zurückgibt.
• useIndicator: erzeugt Indikator-Ereignisse für UI-Statusoberflächen.

​

Beispiele: Pro-Kanal vs. 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)

# 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?

• „Aktualisiere HEARTBEAT.md, um eine tägliche Kalenderprüfung hinzuzufügen.“
• „Schreibe HEARTBEAT.md neu, damit es kürzer ist und sich auf Posteingangs- Nachverfolgungen konzentriert.“

​

Manueller Weckruf (on-demand)

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

​

Auslieferung der Begründung (optional)

• agents.defaults.heartbeat.includeReasoning: true

​

Kostenbewusstsein