---
read_when:
    - Налаштування частоти Heartbeat або повідомлень
    - Вибір між Heartbeat і Cron для запланованих завдань
summary: Повідомлення опитування Heartbeat та правила сповіщень
title: Heartbeat
x-i18n:
    generated_at: "2026-04-22T05:01:11Z"
    model: gpt-5.4
    provider: openai
    source_hash: 13004e4e20b02b08aaf16f22cdf664d0b59da69446ecb30453db51ffdfd1d267
    source_path: gateway/heartbeat.md
    workflow: 15
---

# Heartbeat (Gateway)

> **Heartbeat чи Cron?** Див. [Автоматизація й завдання](/uk/automation) для рекомендацій, коли використовувати кожен із них.

Heartbeat запускає **періодичні ходи агента** в основній сесії, щоб модель могла
помічати все, що потребує уваги, не засипаючи вас повідомленнями.

Heartbeat — це запланований хід в основній сесії — він **не** створює записи [фонових завдань](/uk/automation/tasks).
Записи завдань призначені для відокремленої роботи (запуски ACP, субагенти, ізольовані завдання Cron).

Усунення несправностей: [Заплановані завдання](/uk/automation/cron-jobs#troubleshooting)

## Швидкий старт (для початківців)

1. Залиште heartbeat увімкненими (типове значення — `30m`, або `1h` для Anthropic OAuth/автентифікації токеном, зокрема повторного використання Claude CLI) або задайте власну частоту.
2. Створіть невеликий контрольний список `HEARTBEAT.md` або блок `tasks:` у робочому просторі агента (необов’язково, але рекомендовано).
3. Визначте, куди мають надходити повідомлення heartbeat (`target: "none"` — типове значення; установіть `target: "last"`, щоб спрямовувати їх до останнього контакту).
4. Необов’язково: увімкніть доставку міркувань heartbeat для прозорості.
5. Необов’язково: використовуйте полегшений початковий контекст, якщо для запусків heartbeat потрібен лише `HEARTBEAT.md`.
6. Необов’язково: увімкніть ізольовані сесії, щоб не надсилати повну історію розмови під час кожного heartbeat.
7. Необов’язково: обмежте heartbeat активними годинами (за місцевим часом).

Приклад конфігурації:

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // явна доставка до останнього контакту (типове значення — "none")
        directPolicy: "allow", // типово: дозволяти прямі/DM-одержувачі; установіть "block", щоб приглушити
        lightContext: true, // необов’язково: інжектувати лише HEARTBEAT.md із bootstrap-файлів
        isolatedSession: true, // необов’язково: нова сесія для кожного запуску (без історії розмов)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // необов’язково: також надсилати окреме повідомлення `Reasoning:`
      },
    },
  },
}
```

## Типові значення

- Інтервал: `30m` (або `1h`, коли виявленим режимом автентифікації є Anthropic OAuth/токен, зокрема повторне використання Claude CLI). Установіть `agents.defaults.heartbeat.every` або `agents.list[].heartbeat.every`; використайте `0m`, щоб вимкнути.
- Текст запиту (можна налаштувати через `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.`
- Запит heartbeat надсилається **дослівно** як повідомлення користувача. Системний
  запит містить розділ “Heartbeat” лише тоді, коли heartbeat увімкнено для
  агента за замовчуванням, а запуск внутрішньо позначено відповідним прапорцем.
- Коли heartbeat вимкнено через `0m`, звичайні запуски також не включають `HEARTBEAT.md`
  до bootstrap-контексту, щоб модель не бачила інструкцій лише для heartbeat.
- Активні години (`heartbeat.activeHours`) перевіряються в налаштованому часовому поясі.
  Поза цим вікном heartbeat пропускаються до наступного такту всередині вікна.

## Для чого потрібен запит heartbeat

Типовий запит навмисно є широким:

- **Фонові завдання**: «Розглядай незавершені завдання» спонукає агента переглядати
  подальші дії (вхідні, календар, нагадування, поставлену в чергу роботу) і виводити все термінове.
- **Перевірка стану людини**: «Іноді перевіряй, як справи у твоєї людини протягом дня» спонукає
  до епізодичних легких повідомлень на кшталт «чи щось тобі потрібно?», але уникає нічного спаму
  завдяки використанню вашого налаштованого місцевого часового поясу (див. [/concepts/timezone](/uk/concepts/timezone)).

Heartbeat може реагувати на завершені [фонові завдання](/uk/automation/tasks), але сам запуск heartbeat не створює запис завдання.

Якщо ви хочете, щоб heartbeat робив щось дуже конкретне (наприклад, «перевір статистику Gmail PubSub»
або «перевір стан Gateway»), установіть `agents.defaults.heartbeat.prompt` (або
`agents.list[].heartbeat.prompt`) на власний текст (він надсилається дослівно).

## Контракт відповіді

- Якщо увага ні до чого не потрібна, відповідайте **`HEARTBEAT_OK`**.
- Під час запусків heartbeat OpenClaw трактує `HEARTBEAT_OK` як підтвердження, якщо він з’являється
  на **початку або в кінці** відповіді. Токен видаляється, а відповідь
  відкидається, якщо залишковий вміст має **≤ `ackMaxChars`** (типово: 300).
- Якщо `HEARTBEAT_OK` з’являється **посередині** відповіді, він не обробляється
  особливим чином.
- Для сповіщень **не** включайте `HEARTBEAT_OK`; повертайте лише текст сповіщення.

Поза heartbeat випадковий `HEARTBEAT_OK` на початку/в кінці повідомлення видаляється
й записується в журнал; повідомлення, яке складається лише з `HEARTBEAT_OK`, відкидається.

## Конфігурація

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // типово: 30m (0m вимикає)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // типово: false (доставляти окреме повідомлення Reasoning:, якщо доступне)
        lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору
        isolatedSession: false, // типово: false; true запускає кожен heartbeat у новій сесії (без історії розмов)
        target: "last", // типово: none | варіанти: last | none | <channel id> (ядро або plugin, наприклад "bluebubbles")
        to: "+15551234567", // необов’язкове перевизначення для конкретного каналу
        accountId: "ops-bot", // необов’язковий 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, // максимальна кількість символів після HEARTBEAT_OK
      },
    },
  },
}
```

### Область дії та пріоритет

- `agents.defaults.heartbeat` задає глобальну поведінку heartbeat.
- `agents.list[].heartbeat` зливається поверх нього; якщо будь-який агент має блок `heartbeat`, heartbeat запускаються **лише для цих агентів**.
- `channels.defaults.heartbeat` задає типові параметри видимості для всіх каналів.
- `channels.<channel>.heartbeat` перевизначає типові параметри каналу.
- `channels.<channel>.accounts.<id>.heartbeat` (канали з кількома обліковими записами) перевизначає налаштування на рівні каналу.

### Heartbeat для окремого агента

Якщо будь-який запис `agents.list[]` містить блок `heartbeat`, heartbeat
запускаються **лише для цих агентів**. Блок для окремого агента зливається поверх `agents.defaults.heartbeat`
(тож ви можете один раз задати спільні типові значення й перевизначати їх для окремих агентів).

Приклад: два агенти, heartbeat запускаються лише для другого агента.

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // явна доставка до останнього контакту (типове значення — "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.",
        },
      },
    ],
  },
}
```

### Приклад активних годин

Обмежте heartbeat робочими годинами в конкретному часовому поясі:

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // явна доставка до останнього контакту (типове значення — "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // необов’язково; використовує ваш userTimezone, якщо задано, інакше часовий пояс хоста
        },
      },
    },
  },
}
```

Поза цим вікном (до 9 ранку або після 10 вечора за східним часом) heartbeat пропускаються. Наступний запланований такт усередині вікна буде виконано як звичайно.

### Налаштування 24/7

Якщо ви хочете, щоб heartbeat працювали весь день, використайте один із цих шаблонів:

- Повністю не вказуйте `activeHours` (без обмеження часовим вікном; це типова поведінка).
- Установіть повноденне вікно: `activeHours: { start: "00:00", end: "24:00" }`.

Не встановлюйте однаковий час для `start` і `end` (наприклад, `08:00` до `08:00`).
Це трактується як вікно нульової ширини, тому heartbeat завжди пропускаються.

### Приклад із кількома обліковими записами

Використовуйте `accountId`, щоб націлитися на конкретний обліковий запис у каналах із кількома обліковими записами, як-от Telegram:

```json5
{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // необов’язково: спрямувати до конкретної теми/гілки
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}
```

### Примітки щодо полів

- `every`: інтервал heartbeat (рядок тривалості; типова одиниця — хвилини).
- `model`: необов’язкове перевизначення моделі для запусків heartbeat (`provider/model`).
- `includeReasoning`: коли ввімкнено, також доставляє окреме повідомлення `Reasoning:`, якщо воно доступне (такий самий формат, як у `/reasoning on`).
- `lightContext`: коли true, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору.
- `isolatedSession`: коли true, кожен heartbeat запускається в новій сесії без попередньої історії розмов. Використовує той самий шаблон ізоляції, що й Cron `sessionTarget: "isolated"`. Значно знижує витрати токенів на кожен heartbeat. Поєднуйте з `lightContext: true` для максимальної економії. Маршрутизація доставки все одно використовує контекст основної сесії.
- `session`: необов’язковий ключ сесії для запусків heartbeat.
  - `main` (типово): основна сесія агента.
  - Явний ключ сесії (скопіюйте з `openclaw sessions --json` або з [CLI sessions](/cli/sessions)).
  - Формати ключів сесій: див. [Сесії](/uk/concepts/session) і [Групи](/uk/channels/groups).
- `target`:
  - `last`: доставити до останнього використаного зовнішнього каналу.
  - явний канал: будь-який налаштований канал або id plugin, наприклад `discord`, `matrix`, `telegram` або `whatsapp`.
  - `none` (типово): запускати heartbeat, але **не доставляти** їх назовні.
- `directPolicy`: керує поведінкою доставки напряму/DM:
  - `allow` (типово): дозволяти пряму/DM-доставку heartbeat.
  - `block`: приглушувати пряму/DM-доставку (`reason=dm-blocked`).
- `to`: необов’язкове перевизначення одержувача (специфічний для каналу id, наприклад E.164 для WhatsApp або id чату Telegram). Для тем/гілок Telegram використовуйте `<chatId>:topic:<messageThreadId>`.
- `accountId`: необов’язковий id облікового запису для каналів із кількома обліковими записами. Коли `target: "last"`, id облікового запису застосовується до визначеного останнього каналу, якщо він підтримує облікові записи; інакше ігнорується. Якщо id облікового запису не відповідає налаштованому обліковому запису для визначеного каналу, доставка пропускається.
- `prompt`: перевизначає типовий текст запиту (без злиття).
- `ackMaxChars`: максимальна кількість символів, дозволена після `HEARTBEAT_OK` перед доставкою.
- `suppressToolErrorWarnings`: коли true, приглушує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat.
- `activeHours`: обмежує запуски heartbeat часовим вікном. Об’єкт із `start` (HH:MM, включно; використовуйте `00:00` для початку дня), `end` (HH:MM, виключно; `24:00` дозволено для кінця дня) та необов’язковим `timezone`.
  - Пропущено або `"user"`: використовує ваш `agents.defaults.userTimezone`, якщо задано, інакше повертається до часового поясу системи хоста.
  - `"local"`: завжди використовує часовий пояс системи хоста.
  - Будь-який ідентифікатор IANA (наприклад, `America/New_York`): використовується напряму; якщо він недійсний, застосовується поведінка `"user"` вище.
  - `start` і `end` не повинні бути однаковими для активного вікна; однакові значення трактуються як нульова ширина (завжди поза вікном).
  - Поза активним вікном heartbeat пропускаються до наступного такту всередині вікна.

## Поведінка доставки

- Heartbeat запускаються в основній сесії агента за замовчуванням (`agent:<id>:<mainKey>`),
  або в `global`, коли `session.scope = "global"`. Установіть `session`, щоб перевизначити це на
  конкретну сесію каналу (Discord/WhatsApp тощо).
- `session` впливає лише на контекст запуску; доставкою керують `target` і `to`.
- Щоб доставляти в конкретний канал/конкретному одержувачу, установіть `target` + `to`. Із
  `target: "last"` доставка використовує останній зовнішній канал для цієї сесії.
- Доставки heartbeat за замовчуванням дозволяють прямі/DM-одержувачі. Установіть `directPolicy: "block"`, щоб приглушити надсилання прямим одержувачам, але все одно виконувати хід heartbeat.
- Якщо основна черга зайнята, heartbeat пропускається і повторюється пізніше.
- Якщо `target` не вдається зіставити з жодним зовнішнім призначенням, запуск усе одно відбувається, але
  вихідне повідомлення не надсилається.
- Якщо `showOk`, `showAlerts` і `useIndicator` усі вимкнені, запуск пропускається одразу з `reason=alerts-disabled`.
- Якщо вимкнено лише доставку сповіщень, OpenClaw усе одно може виконати heartbeat, оновити часові позначки завдань, строк виконання яких настав, відновити часову позначку простою сесії та приглушити зовнішнє корисне навантаження сповіщення.
- Якщо визначена ціль heartbeat підтримує індикатор набору тексту, OpenClaw показує набір тексту, поки
  активний запуск heartbeat. Для цього використовується та сама ціль, до якої heartbeat
  надсилав би вивід чату, і це вимикається через `typingMode: "never"`.
- Відповіді лише для heartbeat **не** підтримують сесію активною; останній `updatedAt`
  відновлюється, тож завершення за простоєм працює як звичайно.
- Відокремлені [фонові завдання](/uk/automation/tasks) можуть поставити в чергу системну подію і розбудити heartbeat, коли основна сесія має швидко щось помітити. Таке пробудження не робить запуск heartbeat фоновим завданням.

## Керування видимістю

За замовчуванням підтвердження `HEARTBEAT_OK` приглушуються, а вміст сповіщень
доставляється. Ви можете налаштувати це для кожного каналу або кожного облікового запису:

```yaml
channels:
  defaults:
    heartbeat:
      showOk: false # Приховати HEARTBEAT_OK (типово)
      showAlerts: true # Показувати повідомлення сповіщень (типово)
      useIndicator: true # Генерувати події індикатора (типово)
  telegram:
    heartbeat:
      showOk: true # Показувати підтвердження OK у Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Приглушити доставку сповіщень для цього облікового запису
```

Пріоритет: для облікового запису → для каналу → типові значення каналу → вбудовані типові значення.

### Що робить кожен прапорець

- `showOk`: надсилає підтвердження `HEARTBEAT_OK`, коли модель повертає відповідь лише з OK.
- `showAlerts`: надсилає вміст сповіщення, коли модель повертає відповідь, відмінну від OK.
- `useIndicator`: генерує події індикатора для поверхонь статусу UI.

Якщо **всі три** мають значення false, OpenClaw повністю пропускає запуск heartbeat (без виклику моделі).

### Приклади для каналу й для облікового запису

```yaml
channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # усі облікові записи Slack
    accounts:
      ops:
        heartbeat:
          showAlerts: false # приглушити сповіщення лише для облікового запису ops
  telegram:
    heartbeat:
      showOk: true
```

### Поширені шаблони

| Мета                                     | Конфігурація                                                                              |
| ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| Типова поведінка (тихі OK, сповіщення ввімкнені) | _(конфігурація не потрібна)_                                                              |
| Повністю тихо (без повідомлень, без індикатора) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
| Лише індикатор (без повідомлень)         | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`  |
| OK лише в одному каналі                  | `channels.telegram.heartbeat: { showOk: true }`                                           |

## HEARTBEAT.md (необов’язково)

Якщо у робочому просторі існує файл `HEARTBEAT.md`, типовий запит наказує
агенту прочитати його. Думайте про нього як про свій «контрольний список heartbeat»: невеликий, стабільний і
безпечний для включення кожні 30 хвилин.

Під час звичайних запусків `HEARTBEAT.md` інжектується лише тоді, коли інструкції heartbeat
увімкнено для агента за замовчуванням. Вимкнення частоти heartbeat через `0m` або
встановлення `includeSystemPromptSection: false` прибирає його зі звичайного bootstrap-
контексту.

Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-
заголовки на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб зекономити виклики API.
Такий пропуск позначається як `reason=empty-heartbeat-file`.
Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити.

Тримайте його невеликим (короткий контрольний список або нагадування), щоб уникнути роздування запиту.

Приклад `HEARTBEAT.md`:

```md
# Контрольний список heartbeat

- Швидкий перегляд: чи є щось термінове у вхідних?
- Якщо зараз день, зроби легку перевірку стану, якщо більше нічого не очікує.
- Якщо завдання заблоковане, запиши _чого бракує_ і запитай Peter наступного разу.
```

### Блоки `tasks:`

`HEARTBEAT.md` також підтримує невеликий структурований блок `tasks:` для перевірок
за інтервалом усередині самого heartbeat.

Приклад:

```md
tasks:

- name: inbox-triage
  interval: 30m
  prompt: "Перевір термінові непрочитані листи й познач усе, що чутливе до часу."
- name: calendar-scan
  interval: 2h
  prompt: "Перевір найближчі зустрічі, які потребують підготовки або подальших дій."

# Додаткові інструкції

- Роби сповіщення короткими.
- Якщо після всіх завдань, строк яких настав, увага ні до чого не потрібна, відповідай HEARTBEAT_OK.
```

Поведінка:

- OpenClaw розбирає блок `tasks:` і перевіряє кожне завдання відносно його власного `interval`.
- До запиту heartbeat для цього такту включаються лише завдання, **строк яких настав**.
- Якщо строк жодного завдання не настав, heartbeat повністю пропускається (`reason=no-tasks-due`), щоб уникнути марного виклику моделі.
- Вміст у `HEARTBEAT.md`, який не є завданнями, зберігається й додається як додатковий контекст після списку завдань, строк яких настав.
- Часові позначки останнього запуску завдань зберігаються в стані сесії (`heartbeatTaskState`), тож інтервали переживають звичайні перезапуски.
- Часові позначки завдань просуваються лише після того, як запуск heartbeat завершує свій звичайний шлях відповіді. Пропущені запуски `empty-heartbeat-file` / `no-tasks-due` не позначають завдання як виконані.

Режим завдань корисний, коли ви хочете, щоб один файл heartbeat містив кілька періодичних перевірок, не оплачуючи всі з них на кожному такті.

### Чи може агент оновлювати HEARTBEAT.md?

Так — якщо ви його про це попросите.

`HEARTBEAT.md` — це просто звичайний файл у робочому просторі агента, тож ви можете сказати
агенту (у звичайному чаті) щось на кшталт:

- “Онови `HEARTBEAT.md`, щоб додати щоденну перевірку календаря.”
- “Перепиши `HEARTBEAT.md`, щоб він був коротшим і зосередженим на подальших діях щодо вхідних.”

Якщо ви хочете, щоб це відбувалося проактивно, ви також можете включити явний рядок у
свій запит heartbeat, наприклад: “If the checklist becomes stale, update HEARTBEAT.md
with a better one.”

Примітка щодо безпеки: не записуйте секрети (ключі API, телефонні номери, приватні токени) у
`HEARTBEAT.md` — він стає частиною контексту запиту.

## Ручне пробудження (на вимогу)

Ви можете поставити в чергу системну подію й негайно запустити heartbeat за допомогою:

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

Якщо `heartbeat` налаштовано для кількох агентів, ручне пробудження негайно запускає heartbeat кожного з цих агентів.

Використовуйте `--mode next-heartbeat`, щоб дочекатися наступного запланованого такту.

## Доставка міркувань (необов’язково)

За замовчуванням heartbeat доставляють лише фінальне корисне навантаження «відповіді».

Якщо вам потрібна прозорість, увімкніть:

- `agents.defaults.heartbeat.includeReasoning: true`

Коли цей параметр увімкнено, heartbeat також доставлятимуть окреме повідомлення з префіксом
`Reasoning:` (у тому самому форматі, що й `/reasoning on`). Це може бути корисно, коли агент
керує кількома сесіями/codex і ви хочете бачити, чому він вирішив
написати вам, — але це також може розкрити більше внутрішніх деталей, ніж вам потрібно. У групових чатах краще залишати це
вимкненим.

## Урахування вартості

Heartbeat запускають повноцінні ходи агента. Коротші інтервали спалюють більше токенів. Щоб зменшити вартість:

- Використовуйте `isolatedSession: true`, щоб не надсилати повну історію розмови (~100K токенів знижується до ~2-5K на запуск).
- Використовуйте `lightContext: true`, щоб обмежити bootstrap-файли лише `HEARTBEAT.md`.
- Установіть дешевшу `model` (наприклад, `ollama/llama3.2:1b`).
- Тримайте `HEARTBEAT.md` невеликим.
- Використовуйте `target: "none"`, якщо вам потрібні лише внутрішні оновлення стану.

## Пов’язані матеріали

- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації з одного погляду
- [Фонові завдання](/uk/automation/tasks) — як відстежується відокремлена робота
- [Часовий пояс](/uk/concepts/timezone) — як часовий пояс впливає на планування heartbeat
- [Усунення несправностей](/uk/automation/cron-jobs#troubleshooting) — налагодження проблем автоматизації
