Heartbeat

Heartbeat uruchamia okresowe tury agenta w sesji głównej, dzięki czemu model może zgłaszać wszystko, co wymaga uwagi, bez zasypywania Cię wiadomościami.

Heartbeat jest zaplanowaną turą sesji głównej — nie tworzy rekordów zadań w tle. Rekordy zadań służą do pracy odłączonej (uruchomienia ACP, podagenci, izolowane zadania Cron).

Rozwiązywanie problemów: Zaplanowane zadania

Szybki start (dla początkujących)

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. Zastosowanie wartości domyślnych dostawcy Anthropic zwiększa go do 1h, gdy rozpoznanym trybem uwierzytelniania jest OAuth/token (w tym ponowne użycie Claude CLI), ale tylko wtedy, gdy heartbeat.every nie jest ustawione. Ustaw agents.defaults.heartbeat.every lub agents.list[].heartbeat.every dla poszczególnych agentów; użyj 0m, aby wyłączyć.
• Treść monitu (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 ją skonfigurowano. W przeciwnym razie używają interwału Heartbeat ograniczonego do 600 sekund. Ustaw agents.defaults.heartbeat.timeoutSeconds lub agents.list[].heartbeat.timeoutSeconds dla poszczególnych agentów, aby umożliwić dłuższą pracę Heartbeat.
• Monit Heartbeat jest wysyłany dosłownie jako wiadomość użytkownika. Monit systemowy zawiera sekcję „Heartbeat” tylko wtedy, gdy Heartbeat jest włączony dla domyślnego agenta (a includeSystemPromptSection nie ma wartości false), a uruchomienie jest oznaczane wewnętrznie.
• Gdy Heartbeat jest wyłączony przez 0m, zwykłe uruchomienia również pomijają HEARTBEAT.md w kontekście inicjalizacyjnym, aby model nie widział instrukcji przeznaczonych wyłącznie dla Heartbeat.
• Godziny aktywności (heartbeat.activeHours) są sprawdzane w skonfigurowanej strefie czasowej. Poza tym przedziałem Heartbeat jest pomijany aż do następnego wywołania mieszczącego się w przedziale.
• Heartbeat jest automatycznie odraczany, gdy praca Cron jest aktywna lub oczekuje w kolejce. Ustaw heartbeat.skipWhenBusy: true, aby odraczać także agenta, gdy jego własny podagent powiązany z kluczem sesji lub zagnieżdżone ścieżki poleceń są zajęte; agenci równorzędni nie są już wstrzymywani tylko dlatego, że inny agent wykonuje pracę podagenta.

Do czego służy monit Heartbeat

Domyślny monit jest celowo ogólny:

• Zadania w tle: „Uwzględnij zaległe zadania” zachęca agenta do przeglądania dalszych działań (skrzynki odbiorczej, kalendarza, przypomnień, pracy w kolejce) i zgłaszania pilnych spraw.
• Kontakt z człowiekiem: „Od czasu do czasu w ciągu dnia zapytaj swojego człowieka, jak się ma” zachęca do sporadycznej, krótkiej wiadomości „czy czegoś potrzebujesz?”, ale zapobiega wysyłaniu wiadomości w nocy 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 wykonywał bardzo konkretne działanie (np. „sprawdź statystyki Gmail PubSub” lub „zweryfikuj stan Gateway”), ustaw niestandardową treść w agents.defaults.heartbeat.prompt (lub agents.list[].heartbeat.prompt), która zostanie wysłana dosłownie.

Kontrakt odpowiedzi

• Jeśli nic nie wymaga uwagi, odpowiedz HEARTBEAT_OK.
• Uruchomienia Heartbeat mogą zamiast tego wywołać heartbeat_respond z notify: false, aby nie wyświetlać aktualizacji, lub z notify: true i notificationText, aby wysłać alert. Jeśli występuje ustrukturyzowana odpowiedź narzędzia, ma ona pierwszeństwo przed tekstowym rozwiązaniem zastępczym.
• Podczas uruchomień Heartbeat OpenClaw traktuje HEARTBEAT_OK jako potwierdzenie, gdy występuje ono na początku lub końcu odpowiedzi. Token zostaje usunięty, a odpowiedź odrzucona, jeśli pozostała treść ma ≤ ackMaxChars znaków (domyślnie: 300).
• Jeśli HEARTBEAT_OK występuje w środku odpowiedzi, nie jest traktowane w szczególny sposób.
• W przypadku alertów nie dołączaj HEARTBEAT_OK; zwróć wyłącznie tekst alertu.

Poza uruchomieniami Heartbeat przypadkowe HEARTBEAT_OK na początku lub końcu wiadomości jest usuwane i rejestrowane; wiadomość zawierająca wyłącznie 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.",        includeSystemPromptSection: true, // default: true; false omits the ## Heartbeats system prompt section for the default agent        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

Zakres i pierwszeństwo

• agents.defaults.heartbeat określa globalne działanie Heartbeat.
• agents.list[].heartbeat jest nakładane na te ustawienia; jeśli dowolny agent ma blok heartbeat, Heartbeat uruchamiają tylko ci agenci.
• channels.defaults.heartbeat określa domyślne ustawienia widoczności dla wszystkich kanałów.
• channels.<channel>.heartbeat zastępuje wartości domyślne kanałów.
• channels.<channel>.accounts.<id>.heartbeat (kanały obsługujące wiele kont) zastępuje ustawienia poszczególnych kanałów.

Heartbeat dla poszczególnych agentów

Jeśli dowolny wpis agents.list[] zawiera blok heartbeat, Heartbeat uruchamiają tylko ci agenci. Blok poszczególnego agenta jest nakładany na agents.defaults.heartbeat (możesz więc raz ustawić wspólne wartości domyślne, a następnie zastępować je dla poszczególnych agentów).

Przykład: dwóch agentów, ale tylko drugi 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 godzin aktywności

Ogranicz Heartbeat do godzin pracy w określonej 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 przedziałem (przed 9:00 lub po 22:00 czasu wschodniego) Heartbeat jest pomijany. Następne zaplanowane wywołanie mieszczące się w przedziale zostanie uruchomione normalnie.

Konfiguracja całodobowa

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

• Całkowicie pomiń activeHours (brak ograniczenia do przedziału czasowego; jest to zachowanie domyślne).
• Ustaw przedział całodniowy: activeHours: { start: "00:00", end: "24:00" }.

Przykład wielu kont

Użyj accountId, aby wskazać konkretne konto w kanałach obsługujących wiele kont, 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 dotyczące pól

Zachowanie dostarczania

Kontrola widoczności

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

channels:  defaults:    heartbeat:      showOk: false # Ukryj HEARTBEAT_OK (domyślnie)      showAlerts: true # Pokazuj komunikaty alertów (domyślnie)      useIndicator: true # Emituj zdarzenia wskaźnika (domyślnie)  telegram:    heartbeat:      showOk: true # Pokazuj potwierdzenia OK w Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Pomiń dostarczanie alertów dla tego konta

Kolejność pierwszeństwa: dla konta → dla kanału → domyślne ustawienia kanałów → ustawienia wbudowane.

Działanie poszczególnych flag

• showOk: wysyła potwierdzenie HEARTBEAT_OK, gdy model zwróci odpowiedź zawierającą wyłącznie OK.
• showAlerts: wysyła treść alertu, gdy model zwróci odpowiedź inną niż OK.
• useIndicator: emituje zdarzenia wskaźnika dla powierzchni interfejsu prezentujących stan.

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

Przykłady ustawień dla kanału i konta

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # wszystkie konta Slack    accounts:      ops:        heartbeat:          showAlerts: false # pomijaj alerty tylko dla konta ops  telegram:    heartbeat:      showOk: true

Typowe wzorce

HEARTBEAT.md (opcjonalnie)

Jeśli w przestrzeni roboczej istnieje plik HEARTBEAT.md, domyślny prompt nakazuje agentowi go odczytać. Traktuj go jako „listę kontrolną Heartbeat”: krótką, stabilną i bezpieczną do sprawdzania co 30 minut.

Podczas zwykłych uruchomień plik 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 powoduje pominięcie go w zwykłym kontekście inicjalizacji.

W natywnym środowisku Codex zawartość HEARTBEAT.md nie jest wstrzykiwana do tury tak jak inne pliki inicjalizacyjne. Jeśli plik istnieje i zawiera znaki inne niż białe, notatka trybu współpracy Heartbeat wskazuje Codex ten plik i nakazuje odczytać go przed kontynuowaniem.

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

Plik powinien być bardzo krótki (krótka lista kontrolna lub przypomnienia), aby uniknąć nadmiernego rozrostu promptu.

Przykładowy plik HEARTBEAT.md:

# Lista kontrolna Heartbeat - Szybki przegląd: czy w skrzynkach odbiorczych jest coś pilnego?- Jeśli jest dzień i nic innego nie oczekuje, wykonaj krótką kontrolę.- Jeśli zadanie jest zablokowane, zapisz _czego brakuje_ i następnym razem zapytaj Petera.

Bloki tasks:

Plik HEARTBEAT.md obsługuje również mały, ustrukturyzowany blok tasks: przeznaczony do kontroli wykonywanych okresowo w ramach samego Heartbeat.

Przykład:

tasks: - name: inbox-triage  interval: 30m  prompt: "Sprawdź pilne nieprzeczytane wiadomości e-mail i oznacz wszystko, co wymaga szybkiej reakcji."- name: calendar-scan  interval: 2h  prompt: "Sprawdź nadchodzące spotkania wymagające przygotowania lub dalszych działań." # Dodatkowe instrukcje - Alerty powinny być krótkie.- Jeśli po wykonaniu wszystkich wymaganych zadań nic nie wymaga uwagi, odpowiedz HEARTBEAT_OK.

Tryb zadań jest przydatny, gdy jeden plik Heartbeat ma zawierać kilka okresowych kontroli, bez ponoszenia kosztu wszystkich z nich przy każdym takcie.

Czy agent może aktualizować HEARTBEAT.md?

Tak — jeśli go o to poprosisz.

HEARTBEAT.md jest zwykłym plikiem w przestrzeni roboczej agenta, dlatego możesz powiedzieć agentowi (na zwykłym czacie) na przykład:

• „Zaktualizuj HEARTBEAT.md, dodając codzienną kontrolę kalendarza”.
• „Przepisz HEARTBEAT.md, aby był krótszy i skupiał się na dalszych działaniach dotyczących skrzynki odbiorczej”.

Jeśli chcesz, aby działo się to proaktywnie, możesz również umieścić w prompcie Heartbeat wyraźną instrukcję, na przykład: „Jeśli lista kontrolna stanie się nieaktualna, zaktualizuj HEARTBEAT.md, zastępując ją lepszą”.

Ręczne wybudzenie (na żądanie)

Użyj openclaw system event, aby dodać zdarzenie systemowe do kolejki i opcjonalnie natychmiast uruchomić Heartbeat:

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

Jeśli nie podano --session-key, a wiele agentów ma skonfigurowany heartbeat, opcja --mode now natychmiast uruchamia Heartbeat każdego z tych agentów.

Powiązane elementy sterujące Heartbeat w tej samej grupie CLI:

openclaw system heartbeat last     # pokaż ostatnie zdarzenie Heartbeatopenclaw system heartbeat enable   # włącz Heartbeatopenclaw system heartbeat disable  # wyłącz Heartbeat

Dostarczanie toku rozumowania (opcjonalnie)

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

Jeśli chcesz zapewnić przejrzystość, włącz:

• agents.defaults.heartbeat.includeReasoning: true

Po włączeniu Heartbeat dostarcza również osobną wiadomość poprzedzoną prefiksem Thinking (w takim samym formacie jak /reasoning on). Może to być przydatne, gdy agent zarządza wieloma sesjami/instancjami Codex i chcesz wiedzieć, dlaczego zdecydował się wysłać Ci powiadomienie — może jednak ujawnić więcej wewnętrznych szczegółów, niż chcesz. W czatach grupowych najlepiej pozostawić tę opcję wyłączoną.

Świadomość kosztów

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

• Użyj isolatedSession: true, aby uniknąć wysyłania pełnej historii konwersacji (zmniejszając liczbę tokenów z ok. 100 tys. do ok. 2–5 tys. na uruchomienie).
• Użyj lightContext: true, aby ograniczyć pliki inicjalizacyjne wyłącznie do HEARTBEAT.md.
• Ustaw tańszy model (np. ollama/llama3.2:1b).
• Zachowaj niewielki rozmiar pliku HEARTBEAT.md.
• Użyj target: "none", jeśli potrzebujesz tylko wewnętrznych aktualizacji stanu.

Przepełnienie kontekstu po Heartbeat

Po zakończeniu uruchomienia Heartbeat zachowuje istniejący model wykonawczy współdzielonej sesji, dlatego Heartbeat, który przełączył sesję na mniejszy model lokalny (na przykład model Ollama z oknem 32 tys. tokenów), może pozostawić ten model aktywny podczas następnej tury głównej sesji. Jeśli ta następna tura zgłosi przepełnienie kontekstu, a ostatni model wykonawczy sesji jest zgodny ze skonfigurowanym heartbeat.model, komunikat odzyskiwania OpenClaw wskazuje przeniesienie modelu Heartbeat jako prawdopodobną przyczynę i sugeruje rozwiązanie.

Aby temu zapobiec: użyj isolatedSession: true, aby uruchamiać Heartbeat w nowej sesji (opcjonalnie w połączeniu z lightContext: true, aby uzyskać najmniejszy możliwy prompt), albo wybierz model Heartbeat z oknem kontekstu wystarczająco dużym dla współdzielonej sesji.

Powiązane

• Automatyzacja — przegląd wszystkich mechanizmów automatyzacji
• Zadania w tle — sposób śledzenia odłączonych zadań
• Strefa czasowa — wpływ strefy czasowej na harmonogram Heartbeat
• Rozwiązywanie problemów — diagnozowanie problemów z automatyzacją