Конфигурация и операции

Heartbeat

Heartbeat или Cron? См. Cron vs Heartbeat для рекомендаций, когда использовать каждый из них.

Heartbeat выполняет периодические циклы агента в основной сессии, чтобы модель могла выявить всё, что требует внимания, не спамя вас. Устранение неполадок: /automation/troubleshooting

Быстрый старт (для начинающих)

  1. Оставьте heartbeats включёнными (по умолчанию 30m, или 1h для Anthropic OAuth/setup-token) или установите свой собственный интервал.
  2. Создайте небольшой чек-лист HEARTBEAT.md в рабочей области агента (необязательно, но рекомендуется).
  3. Решите, куда должны отправляться сообщения heartbeat (по умолчанию target: "none"; установите target: "last" для маршрутизации к последнему контакту).
  4. Необязательно: включите доставку рассуждений heartbeat для прозрачности.
  5. Необязательно: используйте облегчённый контекст начальной загрузки, если для heartbeat нужен только HEARTBEAT.md.
  6. Необязательно: ограничьте heartbeats активными часами (локальное время).

Пример конфигурации:

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

Значения по умолчанию

  • Интервал: 30m (или 1h, когда в качестве режима аутентификации обнаружен Anthropic OAuth/setup-token). Установите 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.activeHours) проверяются в настроенном часовом поясе. Вне окна heartbeats пропускаются до следующего тика внутри окна.

Для чего нужен промпт heartbeat

Промпт по умолчанию намеренно широкий:

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

Если вы хотите, чтобы heartbeat выполнял что-то очень конкретное (например, “проверить статистику Gmail PubSub” или “проверить работоспособность шлюза”), установите agents.defaults.heartbeat.prompt (или agents.list[].heartbeat.prompt) на пользовательское тело (отправляется дословно).

Контракт ответа

  • Если ничего не требует внимания, ответьте HEARTBEAT_OK.
  • Во время запусков heartbeat OpenClaw рассматривает HEARTBEAT_OK как подтверждение, когда оно появляется в начале или конце ответа. Токен удаляется, а ответ отбрасывается, если оставшееся содержимое ≤ ackMaxChars (по умолчанию: 300).
  • Если HEARTBEAT_OK появляется в середине ответа, он не обрабатывается особым образом.
  • Для оповещений не включайте HEARTBEAT_OK; возвращайте только текст оповещения.

Вне heartbeats, случайный 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 из файлов начальной загрузки рабочей области
        target: "last", // по умолчанию: none | варианты: last | none | <channel id> (ядро или плагин, например "bluebubbles")
        to: "+15551234567", // опциональное переопределение для конкретного канала
        accountId: "ops-bot", // опциональный идентификатор канала для нескольких аккаунтов
        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, только эти агенты запускают 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", // явная доставка последнему контакту (по умолчанию "none")
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          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", // явная доставка последнему контакту (по умолчанию "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // опционально; использует ваш userTimezone, если установлен, иначе часовой пояс хоста
        },
      },
    },
  },
}

Вне этого окна (до 9 утра или после 10 вечера по восточному времени) heartbeats пропускаются. Следующий запланированный тик внутри окна выполнится нормально.

Настройка 24/7

Если вы хотите, чтобы heartbeats работали круглосуточно, используйте один из этих шаблонов:

  • Пропустите activeHours полностью (нет ограничений по временному окну; это поведение по умолчанию).
  • Установите окно на весь день: activeHours: { start: "00:00", end: "24:00" }.

Не устанавливайте одинаковое время start и end (например, с 08:00 до 08:00). Это рассматривается как окно нулевой ширины, поэтому heartbeats всегда пропускаются.

Пример с несколькими аккаунтами

Используйте 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: при значении true запуски heartbeat используют облегчённый контекст начальной загрузки и оставляют только HEARTBEAT.md из файлов начальной загрузки рабочей области.
  • session: опциональный ключ сессии для запусков heartbeat.
    • main (по умолчанию): основная сессия агента.
    • Явный ключ сессии (скопируйте из openclaw sessions --json или CLI сессий).
    • Форматы ключей сессии: см. Сессии и Группы.
  • target:
    • last: доставить на последний использованный внешний канал.
    • явный канал: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
    • none (по умолчанию): запустить heartbeat, но не доставлять внешне.
  • directPolicy: управляет поведением доставки в личные сообщения:
    • allow (по умолчанию): разрешить доставку heartbeat в личные сообщения.
    • block: подавить доставку в личные сообщения (reason=dm-blocked).
  • to: опциональное переопределение получателя (идентификатор, специфичный для канала, например E.164 для WhatsApp или идентификатор чата Telegram). Для тем/тредов Telegram используйте <chatId>:topic:<messageThreadId>.
  • accountId: опциональный идентификатор аккаунта для каналов с несколькими аккаунтами. При target: "last" идентификатор аккаунта применяется к разрешённому последнему каналу, если он поддерживает аккаунты; в противном случае игнорируется. Если идентификатор аккаунта не соответствует настроенному аккаунту для разрешённого канала, доставка пропускается.
  • prompt: переопределяет тело промпта по умолчанию (не объединяется).
  • ackMaxChars: максимальное количество символов после HEARTBEAT_OK перед доставкой.
  • suppressToolErrorWarnings: при значении true подавляет предупреждения об ошибках инструментов во время запусков heartbeat.
  • activeHours: ограничивает запуски heartbeat временным окном. Объект с start (ЧЧ:ММ, включительно; используйте 00:00 для начала дня), end (ЧЧ:ММ исключительно; 24:00 разрешено для конца дня) и опциональным timezone.
    • Пропущено или "user": использует ваш agents.defaults.userTimezone, если установлен, иначе возвращается к системному часовому поясу хоста.
    • "local": всегда использует системный часовой пояс хоста.
    • Любой идентификатор IANA (например, America/New_York): используется напрямую; если недействителен, возвращается к поведению "user", указанному выше.
    • start и end не должны быть равны для активного окна; равные значения рассматриваются как окно нулевой ширины (всегда вне окна).
    • Вне активного окна heartbeats пропускаются до следующего тика внутри окна.

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

  • Heartbeats по умолчанию запускаются в основной сессии агента (agent:<id>:<mainKey>) или в global, когда session.scope = "global". Установите session для переопределения на конкретную сессию канала (Discord/WhatsApp/и т.д.).
  • session влияет только на контекст выполнения; доставка контролируется target и to.
  • Для доставки на конкретный канал/получателя установите target + to. При target: "last" доставка использует последний внешний канал для этой сессии.
  • Доставки heartbeat по умолчанию разрешают прямые/личные цели. Установите directPolicy: "block", чтобы подавить отправку на прямые цели, при этом всё равно выполняя цикл heartbeat.
  • Если основная очередь занята, heartbeat пропускается и повторяется позже.
  • Если target разрешается в отсутствие внешнего назначения, запуск всё равно происходит, но исходящее сообщение не отправляется.
  • Ответы только от heartbeat не поддерживают сессию активной; последнее значение updatedAt восстанавливается, чтобы истечение срока простоя работало нормально.

Управление видимостью

По умолчанию подтверждения 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 существует, но фактически пуст (только пустые строки и заголовки markdown, такие как # Heading), OpenClaw пропускает запуск heartbeat для экономии вызовов API. Если файл отсутствует, 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.

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

Ручной запуск (по требованию)

Вы можете поставить в очередь системное событие и запустить немедленный heartbeat с помощью:

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

Если несколько агентов имеют настроенный heartbeat, ручной запуск немедленно выполнит heartbeats каждого из этих агентов. Используйте --mode next-heartbeat, чтобы дождаться следующего запланированного тика.

Доставка рассуждений (опционально)

По умолчанию heartbeats доставляют только финальную полезную нагрузку «ответа». Если вам нужна прозрачность, включите:

  • agents.defaults.heartbeat.includeReasoning: true

При включении heartbeats также будут доставлять отдельное сообщение с префиксом Reasoning: (такой же формат, как /reasoning on). Это может быть полезно, когда агент управляет несколькими сессиями/кодексами, и вы хотите видеть, почему он решил связаться с вами — но это также может раскрыть больше внутренних деталей, чем вы хотите. Предпочтительнее оставлять это выключенным в групповых чатах.

Учёт стоимости

Heartbeats выполняют полные циклы агента. Более короткие интервалы сжигают больше токенов. Держите HEARTBEAT.md небольшим и рассмотрите более дешёвую model или target: "none", если вам нужны только обновления внутреннего состояния.

Проверки работоспособностиДоктор