Heartbeat (Gateway)

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

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

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

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

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // 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) проверяются в настроенном часовом поясе. Вне окна heartbeat пропускаются до следующего тика внутри окна.

Для чего нужен запрос heartbeat

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

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

Если вы хотите, чтобы 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-5",
        includeReasoning: false, // по умолчанию: false (доставлять отдельное сообщение Reasoning: когда доступно)
        target: "last",         // last | none | <id канала> (core или plugin, например, "bluebubbles")
        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.",
        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"
      }
    },
    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."
        }
      }
    ]
  }
}

Примечания к полям

  • every: интервал heartbeat (строка длительности; единица по умолчанию = минуты).
  • model: необязательное переопределение модели для запусков heartbeat (provider/model).
  • includeReasoning: когда включено, также доставляет отдельное сообщение Reasoning:, когда доступно (та же форма, что и /reasoning on).
  • session: необязательный ключ сессии для запусков heartbeat.
    • main (по умолчанию): основная сессия агента.
    • Явный ключ сессии (скопируйте из openclaw sessions --json или sessions CLI).
    • Форматы ключа сессии: см. Sessions и Groups.
  • target:
    • last (по умолчанию): доставлять на последний использованный внешний канал.
    • явный канал: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
    • none: запустить heartbeat, но не доставлять внешне.
  • to: необязательное переопределение получателя (id, специфичный для канала, например, E.164 для WhatsApp или id чата Telegram).
  • prompt: переопределяет тело запроса по умолчанию (не объединяется).
  • ackMaxChars: макс. символов разрешено после HEARTBEAT_OK перед доставкой.

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

  • Heartbeat по умолчанию запускаются в основной сессии агента (agent:<id>:<mainKey>), или global, когда session.scope = "global". Установите session для переопределения на конкретную сессию канала (Discord/WhatsApp/и т.д.).
  • session влияет только на контекст запуска; доставка контролируется target и to.
  • Для доставки на конкретный канал/получателя установите target + to. При target: "last" доставка использует последний внешний канал для этой сессии.
  • Если основная очередь занята, 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 (нет вызова модели).

Примеры на уровне канала vs на уровне учетной записи

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

- Быстрое сканирование: что-нибудь срочное во входящих?
- Если сейчас дневное время, сделайте легкую проверку, если ничего другого не ожидается.
- Если задача заблокирована, запишите *что отсутствует* и спросите Peter в следующий раз.

Может ли агент обновлять 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). Это может быть полезно, когда агент управляет несколькими сессиями/кодексами, и вы хотите видеть, почему он решил пинговать вас — но это также может раскрыть больше внутренних деталей, чем вы хотите. Предпочитайте отключать это в групповых чатах.

Осознание затрат

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

← Назад к документации