> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron и Heartbeat

# Cron vs Heartbeat: когда использовать каждый вариант

И heartbeats, и задания cron позволяют запускать задачи по расписанию. Это руководство помогает выбрать подходящий механизм для вашего сценария использования.

## Краткое руководство по выбору

| Сценарий использования                               | Рекомендуется           | Почему                                                   |
| ---------------------------------------------------- | ----------------------- | -------------------------------------------------------- |
| Проверять почту каждые 30 мин                        | Heartbeat               | Объединяется с другими проверками, учитывает контекст    |
| Отправлять ежедневный отчёт ровно в 9 утра           | Cron (изолированный)    | Требуется точное время                                   |
| Следить за календарём на предмет предстоящих событий | Heartbeat               | Естественно подходит для периодической осведомлённости   |
| Запускать еженедельный глубокий анализ               | Cron (изолированный)    | Самостоятельная задача, можно использовать другую модель |
| Напомнить мне через 20 минут                         | Cron (основной, `--at`) | Одноразовая задача с точным временем                     |
| Фоновая проверка состояния проекта                   | Heartbeat               | Использует существующий цикл                             |

## Heartbeat: периодическая осведомлённость

Heartbeats выполняются в **основном сеансе** с регулярным интервалом (по умолчанию: 30 мин). Они предназначены для того, чтобы агент проверял состояние дел и выявлял всё важное.

### Когда использовать heartbeat

* **Несколько периодических проверок**: Вместо 5 отдельных заданий cron для проверки почты, календаря, погоды, уведомлений и статуса проекта один heartbeat может объединить всё это.
* **Решения с учётом контекста**: У агента есть полный контекст основного сеанса, поэтому он может разумно решать, что срочно, а что может подождать.
* **Непрерывность диалога**: Запуски heartbeat используют один и тот же сеанс, поэтому агент помнит недавние разговоры и может естественно продолжать взаимодействие.
* **Мониторинг с низкими накладными расходами**: Один heartbeat заменяет множество мелких задач опроса.

### Преимущества heartbeat

* **Объединяет несколько проверок**: За один ход агент может просмотреть почту, календарь и уведомления вместе.
* **Снижает количество API-вызовов**: Один heartbeat дешевле, чем 5 изолированных заданий cron.
* **Учитывает контекст**: Агент знает, над чем вы работали, и расставляет приоритеты соответствующим образом.
* **Умное подавление**: Если ничего не требует внимания, агент отвечает `HEARTBEAT_OK`, и сообщение не доставляется.
* **Естественное время выполнения**: Возможен небольшой дрейф в зависимости от нагрузки очереди, что подходит для большинства задач мониторинга.

### Пример heartbeat: чек-лист HEARTBEAT.md

```md theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in
```

Агент читает это при каждом heartbeat и обрабатывает все пункты за один ход.

### Настройка heartbeat

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // interval
        target: "last", // where to deliver alerts
        activeHours: { start: "08:00", end: "22:00" }, // optional
      },
    },
  },
}
```

Полную конфигурацию см. в разделе [Heartbeat](/gateway/heartbeat).

## Cron: точное планирование

Задания cron выполняются **в строго заданное время** и могут запускаться в изолированных сеансах, не влияя на основной контекст.

### Когда использовать cron

* **Требуется точное время**: «Отправить это в 9:00 утра каждый понедельник» (а не «примерно около 9»).
* **Самостоятельные задачи**: Задачи, которым не нужен контекст диалога.
* **Другая модель/мышление**: Тяжёлый анализ, для которого оправдано использование более мощной модели.
* **Одноразовые напоминания**: «Напомни мне через 20 минут» с `--at`.
* **Шумные/частые задачи**: Задачи, которые захламляли бы историю основного сеанса.
* **Внешние триггеры**: Задачи, которые должны выполняться независимо от того, активен ли агент в остальном.

### Преимущества cron

* **Точное время**: 5-польные cron-выражения с поддержкой часовых поясов.
* **Изоляция сеанса**: Выполняется в `cron:<jobId>` без загрязнения основной истории.
* **Переопределение модели**: Используйте более дешёвую или более мощную модель для каждого задания.
* **Контроль доставки**: Изолированные задания по умолчанию используют `announce` (сводка); при необходимости выберите `none`.
* **Немедленная доставка**: Режим announce публикует результат напрямую, не дожидаясь heartbeat.
* **Контекст агента не требуется**: Выполняется, даже если основной сеанс простаивает или уплотнён.
* **Поддержка одноразовых задач**: `--at` для точных будущих временных меток.

### Пример cron: ежедневный утренний брифинг

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"
```

Это задание запускается ровно в 7:00 по времени Нью-Йорка, использует Opus для качества и напрямую публикует сводку в WhatsApp.

### Пример cron: одноразовое напоминание

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run
```

Полную справку по CLI см. в разделе [Cron jobs](/automation/cron-jobs).

## Блок-схема принятия решения

```
Does the task need to run at an EXACT time?
  YES -> Use cron
  NO  -> Continue...

Does the task need isolation from main session?
  YES -> Use cron (isolated)
  NO  -> Continue...

Can this task be batched with other periodic checks?
  YES -> Use heartbeat (add to HEARTBEAT.md)
  NO  -> Use cron

Is this a one-shot reminder?
  YES -> Use cron with --at
  NO  -> Continue...

Does it need a different model or thinking level?
  YES -> Use cron (isolated) with --model/--thinking
  NO  -> Use heartbeat
```

## Сочетание обоих

Наиболее эффективная настройка использует **оба** механизма:

1. **Heartbeat** обрабатывает рутинный мониторинг (почта, календарь, уведомления) одним пакетным запуском каждые 30 минут.
2. **Cron** обрабатывает точные расписания (ежедневные отчёты, еженедельные обзоры) и одноразовые напоминания.

### Пример: эффективная настройка автоматизации

**HEARTBEAT.md** (проверяется каждые 30 мин):

```md theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Heartbeat checklist

- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours
```

**Задания cron** (точное время):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Daily morning briefing at 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Weekly project review on Mondays at 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# One-shot reminder
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
```

## Lobster: детерминированные рабочие процессы с подтверждениями

Lobster — это среда выполнения рабочих процессов для **многошаговых конвейеров инструментов**, которым требуется детерминированное выполнение и явные подтверждения.
Используйте его, когда задача выходит за рамки одного хода агента и нужен возобновляемый рабочий процесс с контрольными точками для человека.

### Когда подходит Lobster

* **Многошаговая автоматизация**: Нужен фиксированный конвейер вызовов инструментов, а не разовый промпт.
* **Шлюзы подтверждения**: Побочные эффекты должны останавливаться до вашего подтверждения, а затем возобновляться.
* **Возобновляемые запуски**: Продолжение приостановленного рабочего процесса без повторного выполнения ранних шагов.

### Как он сочетается с heartbeat и cron

* **Heartbeat/cron** определяют, *когда* происходит запуск.
* **Lobster** определяет, *какие шаги* выполняются после начала запуска.

Для запланированных рабочих процессов используйте cron или heartbeat, чтобы инициировать ход агента, который вызывает Lobster.
Для ad-hoc рабочих процессов вызывайте Lobster напрямую.

### Операционные примечания (из кода)

* Lobster запускается как **локальный подпроцесс** (CLI `lobster`) в режиме инструмента и возвращает **JSON-конверт**.
* Если инструмент возвращает `needs_approval`, вы возобновляете выполнение с `resumeToken` и флагом `approve`.
* Инструмент является **необязательным плагином**; включайте его аддитивно через `tools.alsoAllow: ["lobster"]` (рекомендуется).
* Если вы передаёте `lobsterPath`, это должен быть **абсолютный путь**.

Полное описание использования и примеры см. в разделе [Lobster](/tools/lobster).

## Основной сеанс vs изолированный сеанс

И heartbeat, и cron могут взаимодействовать с основным сеансом, но по-разному:

|         | Heartbeat                            | Cron (основной)                    | Cron (изолированный)           |
| ------- | ------------------------------------ | ---------------------------------- | ------------------------------ |
| Session | Основной                             | Основной (через системное событие) | `cron:<jobId>`                 |
| History | Общий доступ                         | Общий доступ                       | Новая при каждом запуске       |
| Context | Полный                               | Полный                             | Нет (чистый старт)             |
| Model   | Модель основного сеанса              | Модель основного сеанса            | Можно переопределить           |
| Output  | Доставляется, если не `HEARTBEAT_OK` | Промпт heartbeat + событие         | Объявить сводку (по умолчанию) |

### Когда использовать cron в основном сеансе

Используйте `--session main` с `--system-event`, если вы хотите:

* Чтобы напоминание/событие появилось в контексте основного сеанса
* Чтобы агент обработал его при следующем heartbeat с полным контекстом
* Отсутствие отдельного изолированного запуска

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now
```

### Когда использовать изолированный cron

Используйте `--session isolated`, если вы хотите:

* Чистое состояние без предыдущего контекста
* Другую модель или настройки «мышления»
* Прямую публикацию сводок в канал
* Историю, которая не захламляет основной сеанс

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce
```

## Соображения по стоимости

| Механизм             | Профиль стоимости                                                     |
| -------------------- | --------------------------------------------------------------------- |
| Heartbeat            | Один ход каждые N минут; масштабируется с размером HEARTBEAT.md       |
| Cron (основной)      | Добавляет событие к следующему heartbeat (без изолированного хода)    |
| Cron (изолированный) | Полный ход агента на задание; можно использовать более дешёвую модель |

**Советы**:

* Держите `HEARTBEAT.md` небольшим, чтобы минимизировать накладные расходы на токены.
* Объединяйте похожие проверки в heartbeat вместо нескольких заданий cron.
* Используйте `target: "none"` для heartbeat, если нужна только внутренняя обработка.
* Используйте изолированный cron с более дешёвой моделью для рутинных задач.

## Связанное

* [Heartbeat](/gateway/heartbeat) — полная конфигурация heartbeat
* [Cron jobs](/automation/cron-jobs) — полная справка по CLI и API cron
* [System](/cli/system) — системные события и управление heartbeat