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 (або 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-ходи без заданого значення використовують agents.defaults.timeoutSeconds, якщо його встановлено. Інакше вони використовують інтервал heartbeat з обмеженням до 600 секунд. Задайте agents.defaults.heartbeat.timeoutSeconds або agents.list[].heartbeat.timeoutSeconds для окремого агента, якщо потрібна довша робота heartbeat.
• Запит heartbeat надсилається дослівно як повідомлення користувача. Системний запит містить розділ "Heartbeat" лише коли heartbeats увімкнені для типового агента, а запуск позначається внутрішньо.
• Коли heartbeats вимкнено через 0m, звичайні запуски також не включають HEARTBEAT.md у контекст початкового завантаження, щоб модель не бачила інструкції лише для heartbeat.
• Активні години (heartbeat.activeHours) перевіряються в налаштованому часовому поясі. Поза вікном heartbeats пропускаються до наступного такту всередині вікна.
• Heartbeats автоматично відкладаються, доки cron-робота активна або перебуває в черзі. Установіть heartbeat.skipWhenBusy: true, щоб також відкладати агента на його власних прив’язаних до ключа сеансу субагентських або вкладених командних смугах; суміжні агенти більше не призупиняються лише тому, що інший агент має субагентську роботу в процесі.

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

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

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

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

Якщо ви хочете, щоб heartbeat виконував щось дуже конкретне (наприклад, "check Gmail PubSub stats" або "verify gateway health"), задайте 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; повертайте лише текст сповіщення.

Поза heartbeats випадковий 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.",        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

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

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

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

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

Приклад: два агенти, heartbeats запускає лише другий агент.

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

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

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

{  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 за східним часом) heartbeats пропускаються. Наступний запланований такт усередині вікна виконається звичайно.

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

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

• Повністю опустіть 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 # 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

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

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

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

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

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

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

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

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

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

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

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

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

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

Приклад HEARTBEAT.md:

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

Блоки tasks:

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

Приклад:

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

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

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

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

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

• "Update HEARTBEAT.md to add a daily calendar check."
• "Rewrite HEARTBEAT.md so it's shorter and focused on inbox follow-ups."

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

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

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

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

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

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

Доставка reasoning (необов’язково)

За замовчуванням Heartbeat доставляє лише фінальний payload «answer».

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

• agents.defaults.heartbeat.includeReasoning: true

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

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

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

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

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

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

Поточні Heartbeat зберігають наявну runtime-модель спільного сеансу після завершення запуску. Ви все ще можете використовувати isolatedSession: true, щоб запускати Heartbeat у свіжому сеансі, поєднати це з lightContext: true для найменшого запиту або вибрати модель Heartbeat із достатньо великим контекстним вікном для спільного сеансу.

Пов’язане

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