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, 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 # 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: создает события индикатора для поверхностей статуса 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 включено для агента по умолчанию. Отключение частоты 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, чтобы дождаться следующего запланированного тика.

Доставка рассуждений (необязательно)

По умолчанию Heartbeat доставляет только итоговый payload «ответа».

Если нужна прозрачность, включите:

• 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
• Устранение неполадок — отладка проблем автоматизации