Heartbeat (Gateway)

Heartbeat чи Cron? Див. Автоматизація й завдання, щоб зрозуміти, коли використовувати кожен із них.

Heartbeat запускає періодичні ходи агента в основній сесії, щоб модель могла повідомляти про все, що потребує уваги, не засипаючи вас повідомленнями. Heartbeat — це запланований хід основної сесії — він не створює записи фонових завдань. Записи завдань призначені для відокремленої роботи (запуски ACP, субагенти, ізольовані cron-завдання). Усунення несправностей: Заплановані завдання

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

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

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // явна доставка до останнього контакту (типове значення — "none")
        directPolicy: "allow", // типово: дозволяти прямі/DM-одержувачі; установіть "block", щоб приглушити
        lightContext: true, // необов’язково: інжектувати лише HEARTBEAT.md із файлів початкового контексту
        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 до початкового контексту, тому модель не бачить інструкції, призначені лише для heartbeat.
Активні години (heartbeat.activeHours) перевіряються в налаштованому часовому поясі. Поза цим вікном heartbeat пропускаються до наступного тіку всередині вікна.

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

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

Фонові завдання: фраза “Consider outstanding tasks” спонукає агента переглядати подальші дії (вхідні, календар, нагадування, роботу в черзі) і повідомляти про все термінове.
Перевірка стану людини: фраза “Checkup sometimes on your human during day time” спонукає до періодичного легкого повідомлення на кшталт “чи щось вам потрібно?”, але допомагає уникати нічного спаму завдяки використанню вашого налаштованого місцевого часового поясу (див. /concepts/timezone).

Heartbeat може реагувати на завершені фонові завдання, але сам запуск 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, відкидається.

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

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

{
  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 робочими годинами в певному часовому поясі:

{
  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:

{
  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: коли ввімкнено, heartbeat-запуски використовують полегшений початковий контекст і зберігають лише HEARTBEAT.md із файлів початкового контексту робочого простору.
isolatedSession: коли ввімкнено, кожен heartbeat запускається в новій сесії без попередньої історії розмов. Використовує той самий шаблон ізоляції, що й cron sessionTarget: "isolated". Значно зменшує витрати токенів на кожен heartbeat. Поєднуйте з lightContext: true для максимальної економії. Маршрутизація доставки все одно використовує контекст основної сесії.
session: необов’язковий ключ сесії для heartbeat-запусків.
- main (типово): основна сесія агента.
- Явний ключ сесії (скопіюйте з openclaw sessions --json або CLI сесій).
- Формати ключів сесії: див. Сесії і Групи.
target:
- last: доставити до останнього використаного зовнішнього каналу.
- явний канал: будь-який налаштований канал або id plugin, наприклад discord, matrix, telegram або whatsapp.
- none (типово): запускати heartbeat, але не доставляти назовні.
directPolicy: керує поведінкою доставки в direct/DM:
- allow (типово): дозволяти доставку heartbeat у direct/DM.
- block: приглушити доставку в direct/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: якщо ввімкнено, приглушує корисні навантаження попереджень про помилки інструментів під час 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 за замовчуванням дозволяє цілі direct/DM. Установіть directPolicy: "block", щоб приглушити надсилання на direct-цілі, але при цьому все одно виконувати хід heartbeat.
Якщо основна черга зайнята, heartbeat пропускається і повторюється пізніше.
Якщо target не вдається зіставити з жодним зовнішнім призначенням, запуск усе одно відбувається, але вихідне повідомлення не надсилається.
Якщо showOk, showAlerts і useIndicator усі вимкнені, запуск одразу пропускається з reason=alerts-disabled.
Якщо вимкнено лише доставку сповіщень, OpenClaw усе одно може виконати heartbeat, оновити часові позначки завдань, відновити часову позначку неактивності сесії та приглушити зовнішнє корисне навантаження сповіщення.
Відповіді лише для heartbeat не підтримують сесію активною; останній updatedAt відновлюється, тож завершення через неактивність працює як зазвичай.
Відокремлені фонові завдання можуть поставити в чергу системну подію й пробудити heartbeat, коли основна сесія має швидко помітити щось важливе. Таке пробудження не перетворює запуск heartbeat на фонове завдання.

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

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

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 (без виклику моделі).

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

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

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

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

Блоки `tasks:`

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

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, наприклад: “Якщо контрольний список застаріє, онови HEARTBEAT.md на кращий.” Примітка щодо безпеки: не вносіть секрети (API-ключі, телефонні номери, приватні токени) до HEARTBEAT.md — він стає частиною контексту запиту.

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

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

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, щоб обмежити файли початкового контексту лише HEARTBEAT.md.
Установіть дешевшу model (наприклад, ollama/llama3.2:1b).
Тримайте HEARTBEAT.md невеликим.
Використовуйте target: "none", якщо вам потрібні лише внутрішні оновлення стану.

Пов’язане

Автоматизація й завдання — огляд усіх механізмів автоматизації
Фонові завдання — як відстежується відокремлена робота
Часовий пояс — як часовий пояс впливає на планування heartbeat
Усунення несправностей — налагодження проблем автоматизації

Gateway

Remote access

Security

Nodes and media

Web interfaces

Heartbeat

Heartbeat (Gateway)

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

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

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

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

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

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

Heartbeat для окремих агентів

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

Конфігурація 24/7

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

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

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

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

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

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

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

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

Блоки `tasks:`

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

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

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

Обізнаність про вартість

Пов’язане

Gateway

Remote access

Security

Nodes and media

Web interfaces

​Heartbeat (Gateway)

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

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

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

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

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

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

​Heartbeat для окремих агентів

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

​Конфігурація 24/7

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

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

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

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

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

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

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

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

​Блоки tasks:

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

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

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

​Обізнаність про вартість

​Пов’язане

Heartbeat (Gateway)

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

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

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

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

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

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

Heartbeat для окремих агентів

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

Конфігурація 24/7

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

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

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

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

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

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

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

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

Блоки `tasks:`

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

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

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

Обізнаність про вартість

Пов’язане