Heartbeat

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

Heartbeat to zaplanowana tura w głównej sesji — nie tworzy rekordów zadań w tle. Rekordy zadań są przeznaczone do 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 `Thinking` message too      },    },  },}

Wartości domyślne

• 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; 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.
• Limit czasu: tury Heartbeat bez ustawionej wartości używają agents.defaults.timeoutSeconds, jeśli jest ustawione. W przeciwnym razie używają częstotliwości Heartbeat ograniczonej do 600 sekund. Ustaw agents.defaults.heartbeat.timeoutSeconds albo agents.list[].heartbeat.timeoutSeconds dla dłuższej pracy Heartbeat.
• Prompt Heartbeat jest wysyłany dosłownie jako wiadomość użytkownika. Prompt systemowy zawiera sekcję „Heartbeat” tylko wtedy, gdy Heartbeat jest włączony dla domyślnego agenta, a uruchomienie jest oznaczane wewnętrznie.
• Gdy Heartbeat jest wyłączony przez 0m, zwykłe uruchomienia pomijają także HEARTBEAT.md w kontekście startowym, aby model nie widział instrukcji przeznaczonych tylko dla Heartbeat.
• Aktywne godziny (heartbeat.activeHours) są sprawdzane w skonfigurowanej strefie czasowej. Poza oknem Heartbeat jest pomijany do następnego tyknięcia wewnątrz okna.
• Heartbeat automatycznie odkłada działanie, gdy praca cron jest aktywna albo w kolejce. Ustaw heartbeat.skipWhenBusy: true, aby dodatkowo odkładać agenta przy jego własnych torach podagentów powiązanych kluczem sesji albo zagnieżdżonych 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: „Rozważ zaległe zadania” zachęca agenta do przejrzenia dalszych działań (skrzynka odbiorcza, kalendarz, przypomnienia, praca w kolejce) i wskazania wszystkiego, co pilne.
• Kontakt z człowiekiem: „Sprawdzaj czasem swojego człowieka w ciągu dnia” zachęca do okazjonalnej, lekkiej wiadomości „czy czegoś potrzebujesz?”, ale unika nocnego spamu dzięki użyciu 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 stan 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 z obsługą narzędzi mogą zamiast tego wywołać heartbeat_respond z notify: false dla braku widocznej aktualizacji albo notify: true oraz notificationText dla alertu. Gdy jest obecna, odpowiedź strukturalna narzędzia ma pierwszeństwo przed tekstową ścieżką awaryjną.
• Podczas uruchomień Heartbeat OpenClaw traktuje HEARTBEAT_OK jako potwierdzenie, gdy pojawia się na początku albo 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 traktowany specjalnie.
• W przypadku alertów nie dołączaj HEARTBEAT_OK; zwróć wyłącznie tekst alertu.

Poza Heartbeat przypadkowe HEARTBEAT_OK na początku/końcu wiadomości jest usuwane i logowane; wiadomość zawierająca tylko 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 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      },    },  },}

Zakres i pierwszeństwo

• agents.defaults.heartbeat ustawia globalne zachowanie Heartbeat.
• agents.list[].heartbeat jest scalane na wierzchu; jeśli którykolwiek agent ma blok heartbeat, tylko ci agenci uruchamiają Heartbeat.
• channels.defaults.heartbeat ustawia domyślną widoczność dla wszystkich kanałów.
• channels.<channel>.heartbeat zastępuje wartości domyślne kanału.
• channels.<channel>.accounts.<id>.heartbeat (kanały z wieloma kontami) zastępuje ustawienia dla kanału.

Heartbeat dla poszczególnych agentów

Jeśli jakikolwiek wpis agents.list[] zawiera blok heartbeat, tylko ci agenci uruchamiają Heartbeat. Blok dla agenta jest scalany na wierzchu agents.defaults.heartbeat (dzięki czemu możesz raz ustawić wspólne wartości domyślne i nadpisywać je per agent).

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

{  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 aktywnych godzin

Ogranicz Heartbeat 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 albo po 22:00 czasu wschodniego) Heartbeat jest pomijany. Następne zaplanowane tyknięcie wewnątrz okna uruchomi się normalnie.

Konfiguracja 24/7

Jeśli chcesz, aby Heartbeat działał przez 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 z wieloma kontami, 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

Kontrole widoczności

Domyślnie potwierdzenia HEARTBEAT_OK są wyciszane, a treść alertu 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

Pierwszeństwo: ustawienia konta → ustawienia kanału → domyślne ustawienia kanałów → wbudowane ustawienia 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 pomija całe uruchomienie Heartbeat (bez wywołania modelu).

Przykłady dla kanału i dla konta

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 obszarze roboczym istnieje plik HEARTBEAT.md, domyślny prompt mówi agentowi, aby go przeczytał. Traktuj go jak swoją „listę kontrolną Heartbeat”: małą, stabilną i bezpieczną do uwzględniania co 30 minut.

Podczas normalnych uruchomień HEARTBEAT.md jest wstrzykiwany tylko wtedy, gdy wskazówki Heartbeat są włączone dla domyślnego agenta. Wyłączenie częstotliwości Heartbeat za pomocą 0m lub ustawienie includeSystemPromptSection: false pomija go w normalnym kontekście bootstrap.

W natywnym harness Codex treść HEARTBEAT.md nie jest wstrzykiwana do tury. Jeśli plik istnieje i zawiera treść inną niż białe znaki, instrukcje trybu współpracy Heartbeat wskazują Codexowi plik i każą go przeczytać przed kontynuacją.

Jeśli HEARTBEAT.md istnieje, ale jest faktycznie pusty (tylko puste wiersze, komentarze Markdown/HTML, nagłówki Markdown takie jak # Heading, znaczniki bloków kodu lub puste szkielety listy kontrolnej), OpenClaw pomija uruchomienie Heartbeat, aby oszczędzać wywołania API. To pominięcie jest raportowane jako reason=empty-heartbeat-file. Jeśli pliku brakuje, Heartbeat nadal działa, a model decyduje, co zrobić.

Utrzymuj go bardzo małym (krótka lista kontrolna lub przypomnienia), aby uniknąć rozrostu 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 także mały strukturalny blok tasks: do 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 obszarze roboczym agenta, więc możesz powiedzieć agentowi (w normalnym czacie) coś takiego:

• „Zaktualizuj HEARTBEAT.md, aby dodać codzienną kontrolę kalendarza.”
• „Przepisz HEARTBEAT.md, żeby był krótszy i skupiony na działaniach następczych w skrzynce odbiorczej.”

Jeśli chcesz, aby działo się to proaktywnie, możesz też dodać wyraźną linię w swoim prompcie Heartbeat, na przykład: „Jeśli lista kontrolna się zestarzeje, zaktualizuj HEARTBEAT.md lepszą wersją.”

Ręczne wybudzenie (na żądanie)

Możesz dodać zdarzenie systemowe do kolejki i wywołać 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 natychmiast uruchamia Heartbeat każdego z tych agentów.

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

Dostarczanie rozumowania (opcjonalne)

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

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

• agents.defaults.heartbeat.includeReasoning: true

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

Świadomość kosztów

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

• Użyj isolatedSession: true, aby uniknąć wysyłania pełnej historii rozmowy (~100 tys. tokenów do ~2-5 tys. na uruchomienie).
• Użyj lightContext: true, aby ograniczyć pliki bootstrap 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 zostawił 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 runtime sesji z powrotem do skonfigurowanego modelu głównego. Komunikat resetu OpenClaw wskazuje to, gdy ostatni model runtime pasuje do skonfigurowanego heartbeat.model.

Obecne Heartbeaty zachowują istniejący model runtime współdzielonej sesji po zakończeniu uruchomienia. Nadal możesz użyć isolatedSession: true, aby uruchamiać Heartbeaty 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 praca odłączona
• Strefa czasowa — jak strefa czasowa wpływa na harmonogram Heartbeat
• Rozwiązywanie problemów — debugowanie problemów z automatyzacją