​

Heartbeat (Gateway)

Heartbeat czy Cron? Zobacz Cron vs Heartbeat, aby uzyskać wskazówki, kiedy używać każdego z nich.

​

Szybki start (dla początkujących)

1. Pozostaw heartbeat włączony (domyślnie 30m lub 1h dla Anthropic OAuth/setup-token) albo ustaw własną częstotliwość.
2. Utwórz krótką listę kontrolną HEARTBEAT.md w obszarze roboczym agenta (opcjonalne, ale zalecane).
3. Zdecyduj, gdzie mają trafiać komunikaty heartbeat (target: "last" jest domyślne).
4. Opcjonalnie: włącz dostarczanie rozumowania heartbeat dla przejrzystości.
5. Opcjonalnie: ogranicz heartbeat do aktywnych godzin (czas lokalny).

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

​

Ustawienia domyślne

• Interwał: 30m (lub 1h, gdy wykrytym trybem uwierzytelniania jest Anthropic OAuth/setup-token). Ustaw agents.defaults.heartbeat.every lub per‑agent 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.
• Prompt heartbeat jest wysyłany dosłownie jako wiadomość użytkownika. Prompt systemowy zawiera sekcję „Heartbeat”, a uruchomienie jest oznaczane wewnętrznie.
• Aktywne godziny (heartbeat.activeHours) są sprawdzane w skonfigurowanej strefie czasowej. Poza oknem heartbeat jest pomijany do następnego tyknięcia w obrębie okna.

​

Do czego służy prompt heartbeat

• Zadania w tle: „Consider outstanding tasks” skłania agenta do przeglądu działań następczych (skrzynka odbiorcza, kalendarz, przypomnienia, kolejka pracy) i wyłonienia pilnych spraw.
• Kontakt z człowiekiem: „Checkup sometimes on your human during day time” zachęca do okazjonalnej, lekkiej wiadomości „czy czegoś potrzebujesz?”, jednocześnie unikając nocnego spamu dzięki użyciu skonfigurowanej lokalnej strefy czasowej (zob. /concepts/timezone).

​

Kontrakt odpowiedzi

• Jeśli nic nie wymaga uwagi, odpowiedz HEARTBEAT_OK.
• 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 pojawi się w środku odpowiedzi, nie jest traktowany w szczególny sposób.
• W przypadku alertów nie dołączaj HEARTBEAT_OK; zwróć wyłącznie treść alertu.

​

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

​

Zakres i pierwszeństwo

• agents.defaults.heartbeat ustawia globalne zachowanie heartbeat.
• agents.list[].heartbeat nadpisuje/scala się na wierzchu; jeśli którykolwiek agent ma blok heartbeat, heartbeat uruchamiają tylko te agenty.
• channels.defaults.heartbeat ustawia domyślną widoczność dla wszystkich kanałów.
• channels.<channel>.heartbeat nadpisuje domyślne ustawienia kanałów.
• channels.<channel>.accounts.<id>.heartbeat (kanały wielokontowe) nadpisuje ustawienia per‑kanał.

​

Heartbeat per‑agent

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

​

Przykład aktywnych godzin

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

​

Przykład wielu kont

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

​

Uwagi do pól

• every: interwał heartbeat (łańcuch czasu trwania; domyślna jednostka = minuty).
• model: opcjonalne nadpisanie modelu dla uruchomień heartbeat (provider/model).
• includeReasoning: gdy włączone, dostarcza także osobną wiadomość Reasoning:, gdy jest dostępna (ten sam kształt co /reasoning on).
• session: opcjonalny klucz sesji dla uruchomień heartbeat.
  • main (domyślne): główna sesja agenta.
  • Jawny klucz sesji (skopiuj z openclaw sessions --json lub z sessions CLI).
  • Formaty klucza sesji: zob. Sessions i Groups.
• target:
  • last (domyślne): dostarcz do ostatnio użytego kanału zewnętrznego.
  • jawny kanał: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: uruchom heartbeat, ale nie dostarczaj na zewnątrz.
• to: opcjonalne nadpisanie odbiorcy (identyfikator specyficzny dla kanału, np. E.164 dla WhatsApp lub identyfikator czatu Telegram).
• accountId: opcjonalny identyfikator konta dla kanałów wielokontowych. Gdy target: "last", identyfikator konta dotyczy rozwiązanego ostatniego kanału, jeśli obsługuje konta; w przeciwnym razie jest ignorowany. Jeśli identyfikator konta nie pasuje do skonfigurowanego konta dla rozwiązanego kanału, dostarczenie jest pomijane.
• prompt: nadpisuje domyślną treść promptu (nie jest scalane).
• ackMaxChars: maks. liczba znaków dozwolona po HEARTBEAT_OK przed dostarczeniem.
• activeHours: ogranicza uruchomienia heartbeat do okna czasowego. Obiekt z start (HH:MM, włącznie), end (HH:MM, wyłącznie; dozwolone 24:00 dla końca dnia) oraz opcjonalnie timezone.
  • Pominięte lub "user": używa Twojej agents.defaults.userTimezone, jeśli ustawiona, w przeciwnym razie wraca do strefy czasowej systemu hosta.
  • "local": zawsze używa strefy czasowej systemu hosta.
  • Dowolny identyfikator IANA (np. America/New_York): używany bezpośrednio; jeśli nieprawidłowy, wraca do zachowania "user" powyżej.
  • Poza aktywnym oknem heartbeat jest pomijany do następnego tyknięcia w obrębie okna.

​

Zachowanie dostawy

• Heartbeat domyślnie uruchamia się w głównej sesji agenta (agent:<id>:<mainKey>), lub global, gdy session.scope = "global". Ustaw session, aby nadpisać na konkretną sesję kanału (Discord/WhatsApp/etc.).
• session wpływa tylko na kontekst uruchomienia; dostarczanie kontrolują target i to.
• Aby dostarczyć do konkretnego kanału/odbiorcy, ustaw target + to. Z target: "last" dostarczanie używa ostatniego kanału zewnętrznego dla tej sesji.
• Jeśli główna kolejka jest zajęta, heartbeat jest pomijany i ponawiany później.
• Jeśli target rozwiąże się do braku celu zewnętrznego, uruchomienie nadal następuje, ale nie jest wysyłana żadna wiadomość wychodząca.
• Odpowiedzi wyłącznie heartbeat nie podtrzymują sesji; przywracany jest ostatni updatedAt, więc wygaszanie bezczynności działa normalnie.

​

Kontrole widoczności

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

​

Co robi każda flaga

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

​

Przykłady per‑kanał vs per‑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)

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

​

Czy agent może aktualizować HEARTBEAT.md?

• „Zaktualizuj HEARTBEAT.md, aby dodać codzienne sprawdzenie kalendarza.”
• „Przepisz HEARTBEAT.md, aby był krótszy i skupiony na działaniach następczych ze skrzynki.”

​

Ręczne wybudzenie (na żądanie)

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

​

Dostarczanie rozumowania (opcjonalne)

• agents.defaults.heartbeat.includeReasoning: true

​

Świadomość kosztów