Heartbeat

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

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

Усунення несправностей: Заплановані завдання

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

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

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

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

• Інтервал: 30m. Застосування типових значень провайдера Anthropic збільшує його до 1h, коли визначеним режимом автентифікації є OAuth/токен (зокрема повторне використання Claude CLI), але лише доки не задано heartbeat.every. Установіть 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 не задано окреме значення, використовується agents.defaults.timeoutSeconds, коли його встановлено. Інакше використовується періодичність Heartbeat з обмеженням у 600 секунд. Для тривалішої роботи Heartbeat установіть agents.defaults.heartbeat.timeoutSeconds або agents.list[].heartbeat.timeoutSeconds для окремого агента.
• Запит Heartbeat надсилається дослівно як повідомлення користувача. Системний запит містить розділ «Heartbeats», лише коли Heartbeat увімкнено для типового агента (і includeSystemPromptSection не дорівнює false), а запуск внутрішньо позначається відповідним прапорцем.
• Коли Heartbeat вимкнено за допомогою 0m, звичайні запуски також не включають HEARTBEAT.md до початкового контексту, тому модель не бачить інструкцій, призначених лише для Heartbeat.
• Години активності (heartbeat.activeHours) перевіряються у налаштованому часовому поясі. Поза цим проміжком Heartbeat пропускається до наступного такту в межах проміжку.
• Heartbeat автоматично відкладається, доки робота Cron активна або перебуває в черзі. Установіть heartbeat.skipWhenBusy: true, щоб також відкладати запуск агента, коли зайнятий його власний підагент із ключем сеансу або вкладені канали команд; споріднені агенти більше не призупиняються лише через те, що інший агент виконує роботу підагента.

Для чого призначений запит Heartbeat

Типовий запит навмисно має широке формулювання:

• Фонові завдання: фраза «Розглянь незавершені завдання» спонукає агента перевірити подальші дії (вхідні повідомлення, календар, нагадування, роботу в черзі) і повідомити про все термінове.
• Зв’язок із людиною: фраза «Іноді вдень перевіряй, як справи в твоєї людини» спонукає час від часу надсилати коротке повідомлення на кшталт «Вам щось потрібно?», але запобігає нічному потоку повідомлень завдяки використанню налаштованого місцевого часового поясу (див. Часовий пояс).

Heartbeat може реагувати на завершені фонові завдання, але сам запуск Heartbeat не створює запису завдання.

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

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

• Якщо ніщо не потребує уваги, дайте відповідь HEARTBEAT_OK.
• Натомість запуски Heartbeat можуть викликати heartbeat_respond із notify: false, щоб не показувати оновлення, або з notify: true та notificationText, щоб надіслати сповіщення. Якщо структурована відповідь інструмента наявна, вона має пріоритет над резервною текстовою відповіддю.
• Під час запусків Heartbeat OpenClaw розглядає HEARTBEAT_OK як підтвердження, якщо він розташований на початку або в кінці відповіді. Токен вилучається, а відповідь відкидається, якщо решта вмісту має довжину ≤ ackMaxChars (типове значення: 300).
• Якщо HEARTBEAT_OK розташований усередині відповіді, він не обробляється особливим чином.
• Для сповіщень не додавайте HEARTBEAT_OK; повертайте лише текст сповіщення.

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

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

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

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

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

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

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

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

Поза цим проміжком (до 9:00 або після 22:00 за східним часом) Heartbeat пропускається. Наступний запланований такт у межах проміжку буде виконано у звичайному режимі.

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

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

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

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

Використовуйте accountId, щоб націлитися на певний обліковий запис у каналах із кількома обліковими записами, як-от 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" },      },    },  },}

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

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

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

За замовчуванням підтвердження 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: генерує події індикатора для поверхонь стану інтерфейсу.

Якщо всі три мають значення 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

Поширені схеми

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

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

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

У нативному середовищі Codex вміст HEARTBEAT.md не додається до ходу так само, як інші початкові файли. Якщо файл існує й містить не лише пробільні символи, примітка режиму співпраці Heartbeat спрямовує Codex до цього файлу та наказує прочитати його перед продовженням.

Якщо HEARTBEAT.md існує, але фактично порожній (містить лише порожні рядки, коментарі Markdown/HTML, заголовки 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.

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

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

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

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

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

Якщо ви хочете, щоб це відбувалося проактивно, можна також додати до запиту Heartbeat явний рядок на кшталт: «Якщо контрольний список застаріє, онови HEARTBEAT.md, створивши кращий».

Ручна активація (на вимогу)

Використовуйте openclaw system event, щоб додати системну подію до черги та, за потреби, негайно запустити Heartbeat:

openclaw system event --text "Перевір термінові подальші дії" --mode now

Якщо --session-key не вказано й Heartbeat налаштовано для кількох агентів, --mode now негайно запускає Heartbeat кожного з цих агентів.

Пов’язані засоби керування Heartbeat у тій самій групі CLI:

openclaw system heartbeat last     # показати останню подію Heartbeatopenclaw system heartbeat enable   # увімкнути Heartbeatopenclaw system heartbeat disable  # вимкнути Heartbeat

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

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

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

• agents.defaults.heartbeat.includeReasoning: true

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

Урахування витрат

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

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

Переповнення контексту після Heartbeat

Після завершення запуску Heartbeat зберігає поточну модель виконання спільного сеансу, тому Heartbeat, який перемкнув сеанс на меншу локальну модель (наприклад, модель Ollama з контекстним вікном 32 тис. токенів), може залишити цю модель активною для наступного циклу основного сеансу. Якщо під час цього наступного циклу виникне повідомлення про переповнення контексту, а остання модель виконання сеансу збігається з налаштованою heartbeat.model, повідомлення OpenClaw про відновлення вкаже на перенесення моделі Heartbeat як імовірну причину та запропонує спосіб виправлення.

Щоб уникнути цього, використовуйте isolatedSession: true для запуску Heartbeat у новому сеансі (за потреби разом із lightContext: true для найменшого запиту) або виберіть для Heartbeat модель із контекстним вікном, достатньо великим для спільного сеансу.

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

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