Skip to main content

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

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

{
  "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.