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

# Кроны

## Cron Jobs в OpenClaw

Это механизм **планирования задач** (scheduler), встроенный в Gateway OpenClaw. По сути, это аналог классического Unix cron, но адаптированный для оркестрации AI-агентов. Разберём по порядку.

### Суть концепции

Cron — это встроенный планировщик Gateway, который персистентно хранит задачи (jobs), будит агента в нужный момент и опционально доставляет результат обратно в чат. Типичные сценарии: «запусти это каждое утро» или «дёрни агента через 20 минут».

Ключевой момент: cron работает внутри Gateway, а не внутри модели. Это значит, что планировщик — это инфраструктурный компонент, а не часть inference-пайплайна LLM.

### Три типа расписаний (Schedules)

Поддерживаются три вида расписаний: `at` — одноразовый запуск по ISO 8601 timestamp, `every` — фиксированный интервал в миллисекундах, и `cron` — классическое 5-полевое (или 6-полевое с секундами) cron-выражение с опциональной IANA timezone.

Для парсинга cron-выражений используется библиотека `croner`. Если таймзона не указана, берётся локальная зона хоста Gateway.

### Два режима исполнения

Это, пожалуй, самая важная архитектурная деталь:

**Main session** — задача ставит системное событие в очередь и опционально будит heartbeat runner. Обязательно использует `payload.kind = "systemEvent"`. Подходит, когда нужен полный контекст основной сессии агента.

**Isolated session** — запускает выделенный agent turn в сессии `cron:<jobId>`. Каждый запуск создаёт свежий session id без переноса предыдущего контекста разговора. Это критично для ML-пайплайнов — изолированные задачи не загрязняют основной контекст агента и идеальны для «фоновых» операций вроде периодического сбора метрик или саммаризации.

### Доставка результатов (Delivery)

Три режима доставки для isolated jobs:

* **announce** — результат отправляется в целевой канал (Slack, Telegram, WhatsApp, Discord и т.д.) и краткое резюме постится в основную сессию.
* **webhook** — HTTP POST с payload на указанный URL. Удобно для интеграции с внешними системами мониторинга или MLOps-пайплайнами.
* **none** — только внутреннее исполнение, без доставки.

Если `delivery` не указан для isolated jobs, OpenClaw по умолчанию использует `announce`.

### Model и Thinking overrides

Особенно полезная для ML-инженера фича: isolated jobs могут переопределять модель и уровень thinking. Поле `model` принимает строку провайдер/модель (например, `anthropic/claude-sonnet-4-20250514`) или алиас (например, `opus`), а `thinking` — уровень от `off` до `xhigh`.

Это позволяет, например, запускать еженедельный глубокий анализ на более мощной модели с высоким thinking, а рутинные проверки — на лёгкой модели без thinking, оптимизируя расходы на inference.

### Retry policy

Ошибки классифицируются на transient (rate limit 429, сетевые ошибки, 5xx) и permanent (невалидный API key, ошибки конфигурации).

Для one-shot задач: transient ошибки ретраятся до 3 раз с экспоненциальным backoff (30s → 1m → 5m), permanent — сразу отключают задачу. Для recurring задач применяется backoff до 60 минут, но задача остаётся enabled и backoff сбрасывается после успешного запуска.

### Персистентность

Задачи хранятся на хосте Gateway в `~/.openclaw/cron/jobs.json`. Gateway загружает файл в память и записывает обратно при изменениях. История запусков ведётся в JSONL-файлах с автоматическим pruning по размеру и количеству строк.

### Практический пример

Допустим, нужно каждое утро в 7:00 по LA получать саммари обновлений в Slack:

```text theme={null}
openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"
```

Или еженедельный глубокий анализ на мощной модели:

```text theme={null}
openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce
```

По сути, cron в OpenClaw — это полноценный job scheduler с retry-логикой, персистентностью и гибкой маршрутизацией результатов, заточенный под оркестрацию LLM-агентов.

## HEARTBEAT в OpenClaw

Это механизм **периодического пробуждения агента** в рамках основной (main) сессии. По сути, heartbeat — это таймер, который с заданным интервалом (по умолчанию 30 минут) триггерит агента, чтобы тот выполнил набор проверок и решил, нужно ли что-то сообщить пользователю.

### Как это работает

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

Ключевой артефакт — файл `HEARTBEAT.md`, в котором описывается чеклист того, что агент должен проверить при каждом «пробуждении». Например:

```text theme={null}
# 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 и обрабатывает все пункты за один turn.

### Главное отличие от Cron

Cron и Heartbeat решают разные задачи:

**Heartbeat** — это «периодическая осведомлённость» (periodic awareness). Вместо того чтобы создавать 5 отдельных cron-задач для проверки почты, календаря, погоды, уведомлений и статуса проекта, один heartbeat батчит всё это в один agent turn. Агент при этом работает в контексте основной сессии — он помнит, о чём вы разговаривали, и может приоритизировать на основе этого.

**Cron** — это точное планирование. Используй cron, когда нужен точный тайминг («отправь в 9:00 каждый понедельник»), изоляция сессии, другая модель/thinking level, или one-shot напоминания.

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

1. **Батчинг** — одна инференс-вызов вместо N отдельных задач, что существенно снижает расход токенов и API-вызовов.
2. **Context-awareness** — агент знает, над чем вы работали, и может приоритизировать соответственно.
3. **Smart suppression** — если ничего не требует внимания, агент отвечает `HEARTBEAT_OK` и сообщение пользователю не доставляется. Это критически важно, чтобы не засорять канал коммуникации шумом.
4. **Conversational continuity** — heartbeat-запуски разделяют одну и ту же сессию, поэтому агент помнит недавние разговоры и может естественно продолжать follow-up.

### Конфигурация

```text theme={null}
{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "activeHours": { "start": "08:00", "end": "22:00" }
      }
    }
  }
}
```

Параметр `activeHours` позволяет ограничить heartbeat рабочими часами — агент не будет будить тебя ночью.

### Heartbeat vs Cron: когда что выбирать

Простое правило: если задача требует точного времени — cron. Если задачу можно батчить с другими периодическими проверками — heartbeat. Если нужна изоляция от main session — cron (isolated).

На практике оптимальный сетап — **комбинация обоих**: heartbeat для рутинного мониторинга (почта, календарь, нотификации) в одном батче каждые 30 минут, а cron — для задач с жёстким расписанием (ежедневные отчёты, weekly review) и one-shot напоминаний.

### Cost profile

Heartbeat стоит один agent turn каждые N минут, и стоимость масштабируется с размером `HEARTBEAT.md`. Cron в main session просто добавляет event к следующему heartbeat (без отдельного turn). Cron в isolated session — полный отдельный agent turn на каждый запуск, но можно использовать более дешёвую модель.

Поэтому рекомендация — держать `HEARTBEAT.md` компактным и агрегировать однотипные проверки в heartbeat, а не плодить отдельные cron jobs.