Heartbeat

Heartbeat uruchamia okresowe tury agenta w sesji głównej, aby model mógł sygnalizować wszystko, co wymaga uwagi, bez zasypywania Cię wiadomościami.

Heartbeat to zaplanowana tura w sesji głównej — nie tworzy rekordów zadań w tle. Rekordy zadań są przeznaczone dla pracy odłączonej (uruchomienia ACP, podagenci, izolowane zadania cron).

Rozwiązywanie problemów: Zaplanowane zadania

Szybki start (początkujący)

Przykładowa konfiguracja:

{  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 `Reasoning:` message too      },    },  },}

Domyślne ustawienia

• Interwał: 30m (albo 1h, gdy wykrytym trybem uwierzytelniania jest Anthropic OAuth/token, w tym ponowne użycie Claude CLI). Ustaw agents.defaults.heartbeat.every albo agents.list[].heartbeat.every dla agenta; użyj 0m, aby wyłączyć.
• Treść promptu (konfigurowalna przez 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.
• Prompt heartbeat jest wysyłany dosłownie jako wiadomość użytkownika. Prompt systemowy zawiera sekcję „Heartbeat” tylko wtedy, gdy heartbeaty są włączone dla domyślnego agenta, a uruchomienie jest oznaczone wewnętrznie.
• Gdy heartbeaty są wyłączone przez 0m, zwykłe uruchomienia pomijają także HEARTBEAT.md w kontekście startowym, aby model nie widział instrukcji przeznaczonych tylko dla heartbeat.
• Godziny aktywności (heartbeat.activeHours) są sprawdzane w skonfigurowanej strefie czasowej. Poza oknem heartbeaty są pomijane do następnego taktu wewnątrz okna.
• Heartbeaty automatycznie odraczają się, gdy praca cron jest aktywna lub w kolejce. Ustaw heartbeat.skipWhenBusy: true, aby również odraczać agenta przy jego własnym podagencie z kluczem sesji lub zagnieżdżonych ścieżkach poleceń; agenci równorzędni nie są już wstrzymywani tylko dlatego, że inny agent ma trwającą pracę podagenta.

Do czego służy prompt heartbeat

Domyślny prompt jest celowo szeroki:

• Zadania w tle: „Consider outstanding tasks” zachęca agenta do przejrzenia dalszych działań (skrzynka odbiorcza, kalendarz, przypomnienia, praca w kolejce) i zasygnalizowania wszystkiego, co pilne.
• Kontakt z człowiekiem: „Checkup sometimes on your human during day time” zachęca do okazjonalnej, lekkiej wiadomości „czy czegoś potrzebujesz?”, ale unika nocnego spamu, używając skonfigurowanej lokalnej strefy czasowej (zobacz Strefa czasowa).

Heartbeat może reagować na ukończone zadania w tle, ale samo uruchomienie heartbeat nie tworzy rekordu zadania.

Jeśli chcesz, aby heartbeat robił coś bardzo konkretnego (np. „sprawdź statystyki Gmail PubSub” albo „zweryfikuj kondycję Gateway”), ustaw agents.defaults.heartbeat.prompt (albo agents.list[].heartbeat.prompt) na niestandardową treść (wysyłaną dosłownie).

Kontrakt odpowiedzi

• Jeśli nic nie wymaga uwagi, odpowiedz HEARTBEAT_OK.
• Uruchomienia heartbeat obsługujące narzędzia mogą zamiast tego wywołać heartbeat_respond z notify: false dla braku widocznej aktualizacji albo notify: true plus notificationText dla alertu. Jeśli występuje, strukturalna odpowiedź narzędzia ma pierwszeństwo przed tekstowym wariantem awaryjnym.
• Podczas uruchomień heartbeat OpenClaw traktuje HEARTBEAT_OK jako potwierdzenie, gdy pojawia się na początku lub końcu odpowiedzi. Token jest usuwany, a odpowiedź odrzucana, jeśli pozostała treść ma ≤ ackMaxChars (domyślnie: 300).
• Jeśli HEARTBEAT_OK pojawia się w środku odpowiedzi, nie jest traktowane specjalnie.
• W przypadku alertów nie dołączaj HEARTBEAT_OK; zwróć tylko tekst alertu.

Poza heartbeatami zbłąkane HEARTBEAT_OK na początku/końcu wiadomości jest usuwane i logowane; wiadomość składająca się tylko z HEARTBEAT_OK jest odrzucana.

Konfiguracja

{  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 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      },    },  },}

Zakres i pierwszeństwo

• agents.defaults.heartbeat ustawia globalne zachowanie heartbeat.
• agents.list[].heartbeat scala się na wierzchu; jeśli dowolny agent ma blok heartbeat, heartbeaty uruchamiają tylko ci agenci.
• channels.defaults.heartbeat ustawia domyślną widoczność dla wszystkich kanałów.
• channels.<channel>.heartbeat zastępuje domyślne ustawienia kanałów.
• channels.<channel>.accounts.<id>.heartbeat (kanały wielokontowe) zastępuje ustawienia dla kanału.

Heartbeaty dla agenta

Jeśli dowolny wpis agents.list[] zawiera blok heartbeat, heartbeaty uruchamiają tylko ci agenci. Blok dla agenta scala się na wierzchu agents.defaults.heartbeat (dzięki czemu możesz raz ustawić wspólne ustawienia domyślne i nadpisywać je dla poszczególnych agentów).

Przykład: dwóch agentów, tylko drugi agent uruchamia heartbeaty.

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

Przykład godzin aktywności

Ogranicz heartbeaty do godzin pracy w konkretnej strefie czasowej:

{  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        },      },    },  },}

Poza tym oknem (przed 9:00 lub po 22:00 czasu wschodniego) heartbeaty są pomijane. Następny zaplanowany takt wewnątrz okna uruchomi się normalnie.

Konfiguracja 24/7

Jeśli chcesz, aby heartbeaty działały cały dzień, użyj jednego z tych wzorców:

• Całkowicie pomiń activeHours (brak ograniczenia oknem czasowym; to zachowanie domyślne).
• Ustaw okno całodniowe: activeHours: { start: "00:00", end: "24:00" }.

Przykład wielu kont

Użyj accountId, aby wskazać konkretne konto w kanałach wielokontowych, takich jak Telegram:

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

Uwagi o polach

Zachowanie dostarczania

Kontrolki widoczności

Domyślnie potwierdzenia HEARTBEAT_OK są pomijane, a treść alertów jest dostarczana. Możesz dostosować to dla kanału lub konta:

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

Priorytet: na konto → na kanał → domyślne ustawienia kanału → wbudowane wartości domyślne.

Co robi każda flaga

• showOk: wysyła potwierdzenie HEARTBEAT_OK, gdy model zwraca odpowiedź zawierającą tylko OK.
• showAlerts: wysyła treść alertu, gdy model zwraca odpowiedź inną niż OK.
• useIndicator: emituje zdarzenia wskaźnika dla powierzchni statusu UI.

Jeśli wszystkie trzy mają wartość false, OpenClaw całkowicie pomija uruchomienie Heartbeat (bez wywołania modelu).

Przykłady na kanał i na 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

Typowe wzorce

HEARTBEAT.md (opcjonalne)

Jeśli w przestrzeni roboczej istnieje plik HEARTBEAT.md, domyślny prompt każe agentowi go przeczytać. Traktuj go jak swoją „listę kontrolną Heartbeat”: małą, stabilną i bezpieczną do dołączania co 30 minut.

Przy normalnych uruchomieniach HEARTBEAT.md jest wstrzykiwany tylko wtedy, gdy wskazówki Heartbeat są włączone dla domyślnego agenta. Wyłączenie rytmu Heartbeat za pomocą 0m albo ustawienie includeSystemPromptSection: false pomija go w normalnym kontekście startowym.

Jeśli HEARTBEAT.md istnieje, ale jest faktycznie pusty (tylko puste wiersze i nagłówki Markdown, takie jak # Heading), OpenClaw pomija uruchomienie Heartbeat, aby oszczędzić wywołania API. To pominięcie jest raportowane jako reason=empty-heartbeat-file. Jeśli pliku brakuje, Heartbeat nadal się uruchamia, a model decyduje, co zrobić.

Utrzymuj go bardzo małym (krótka lista kontrolna lub przypomnienia), aby uniknąć rozdęcia promptu.

Przykład 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.

Bloki tasks:

HEARTBEAT.md obsługuje też mały ustrukturyzowany blok tasks: dla kontroli opartych na interwałach wewnątrz samego Heartbeat.

Przykład:

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.

Tryb zadań jest przydatny, gdy chcesz, aby jeden plik Heartbeat zawierał kilka okresowych kontroli bez płacenia za wszystkie przy każdym takcie.

Czy agent może aktualizować HEARTBEAT.md?

Tak — jeśli go o to poprosisz.

HEARTBEAT.md to zwykły plik w przestrzeni roboczej agenta, więc możesz powiedzieć agentowi (w normalnym czacie) na przykład:

• „Zaktualizuj HEARTBEAT.md, aby dodać codzienną kontrolę kalendarza.”
• „Przepisz HEARTBEAT.md, żeby był krótszy i skupiał się na follow-upach w skrzynce odbiorczej.”

Jeśli chcesz, aby działo się to proaktywnie, możesz też dołączyć w prompcie Heartbeat jawny wiersz, taki jak: „Jeśli lista kontrolna się zdezaktualizuje, zaktualizuj HEARTBEAT.md lepszą wersją.”

Ręczne wybudzenie (na żądanie)

Możesz dodać zdarzenie systemowe do kolejki i wyzwolić natychmiastowy Heartbeat za pomocą:

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

Jeśli wielu agentów ma skonfigurowany heartbeat, ręczne wybudzenie uruchamia natychmiast każdy z tych Heartbeat agentów.

Użyj --mode next-heartbeat, aby poczekać na następny zaplanowany takt.

Dostarczanie rozumowania (opcjonalne)

Domyślnie Heartbeat dostarczają tylko końcowy ładunek „odpowiedzi”.

Jeśli chcesz przejrzystości, włącz:

• agents.defaults.heartbeat.includeReasoning: true

Po włączeniu Heartbeat będą także dostarczać osobną wiadomość z prefiksem Reasoning: (ten sam kształt co /reasoning on). Może to być przydatne, gdy agent zarządza wieloma sesjami/kodexami i chcesz zobaczyć, dlaczego zdecydował się do Ciebie odezwać — ale może też ujawnić więcej wewnętrznych szczegółów, niż chcesz. W czatach grupowych lepiej pozostawić to wyłączone.

Świadomość kosztów

Heartbeat uruchamiają pełne tury agenta. Krótsze interwały zużywają więcej tokenów. Aby zmniejszyć koszt:

• Użyj isolatedSession: true, aby uniknąć wysyłania pełnej historii rozmowy (~100K tokenów do ~2-5K na uruchomienie).
• Użyj lightContext: true, aby ograniczyć pliki startowe tylko do HEARTBEAT.md.
• Ustaw tańszy model (np. ollama/llama3.2:1b).
• Utrzymuj HEARTBEAT.md mały.
• Użyj target: "none", jeśli chcesz tylko aktualizacji stanu wewnętrznego.

Przepełnienie kontekstu po Heartbeat

Jeśli Heartbeat wcześniej pozostawił istniejącą sesję na mniejszym modelu lokalnym, na przykład modelu Ollama z oknem 32k, a następna tura głównej sesji zgłasza przepełnienie kontekstu, zresetuj model wykonawczy sesji z powrotem do skonfigurowanego modelu głównego. Komunikat resetu OpenClaw wskazuje to, gdy ostatni model wykonawczy pasuje do skonfigurowanego heartbeat.model.

Obecne Heartbeat zachowują istniejący model wykonawczy współdzielonej sesji po zakończeniu uruchomienia. Nadal możesz użyć isolatedSession: true, aby uruchamiać Heartbeat w świeżej sesji, połączyć to z lightContext: true dla najmniejszego promptu albo wybrać model Heartbeat z oknem kontekstu wystarczająco dużym dla współdzielonej sesji.

Powiązane

• Automatyzacja — wszystkie mechanizmy automatyzacji w skrócie
• Zadania w tle — jak śledzona jest odłączona praca
• Strefa czasowa — jak strefa czasowa wpływa na planowanie Heartbeat
• Rozwiązywanie problemów — debugowanie problemów z automatyzacją