Задания Cron (планировщик Gateway)

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

Cron — это встроенный планировщик Gateway. Он сохраняет задания, пробуждает агента в нужное время и может опционально доставлять вывод обратно в чат.

Если вам нужно "запускать это каждое утро" или "напомнить агенту через 20 минут", cron — это механизм для этого.

Кратко

  • Cron работает внутри Gateway (не внутри модели).
  • Задания сохраняются в ~/.openclaw/cron/, поэтому перезапуски не теряют расписания.
  • Два стиля выполнения:
    • Основная сессия: поставить в очередь системное событие, затем выполнить при следующем сердцебиении.
    • Изолированная: запустить отдельный ход агента в cron:<jobId>, опционально доставить вывод.
  • Пробуждения являются приоритетными: задание может запросить "пробудить сейчас" против "следующее сердцебиение".

Обзор для начинающих

Думайте о задании cron как о: когда запускать + что делать.

  1. Выберите расписание

    • Одноразовое напоминание → schedule.kind = "at" (CLI: --at)
    • Повторяющееся задание → schedule.kind = "every" или schedule.kind = "cron"
    • Если ваш временной штамп ISO не указывает часовой пояс, он рассматривается как UTC.

  2. Выберите, где оно выполняется

    • sessionTarget: "main" → запустить во время следующего сердцебиения с основным контекстом.
    • sessionTarget: "isolated" → запустить отдельный ход агента в cron:<jobId>.

  3. Выберите полезную нагрузку

    • Основная сессия → payload.kind = "systemEvent"
    • Изолированная сессия → payload.kind = "agentTurn"

Опционально: deleteAfterRun: true удаляет успешные одноразовые задания из хранилища.

Концепции

Задания

Задание cron — это сохраненная запись с:

  • расписанием (когда оно должно выполняться),
  • полезной нагрузкой (что оно должно делать),
  • опциональной доставкой (куда должен быть отправлен вывод).
  • опциональной привязкой к агенту (agentId): выполнить задание под конкретным агентом; если отсутствует или неизвестно, gateway возвращается к агенту по умолчанию.

Задания идентифицируются стабильным jobId (используется CLI/API Gateway). В вызовах инструментов агента jobId является каноническим; устаревший id принимается для совместимости. Задания могут опционально автоматически удаляться после успешного одноразового выполнения через deleteAfterRun: true.

Расписания

Cron поддерживает три типа расписаний:

  • at: одноразовый временной штамп (мс с эпохи). Gateway принимает ISO 8601 и приводит к UTC.
  • every: фиксированный интервал (мс).
  • cron: 5-полевое выражение cron с опциональным часовым поясом IANA.

Выражения cron используют croner. Если часовой пояс не указан, используется локальный часовой пояс хоста Gateway.

Выполнение в основной и изолированной сессиях

Задания основной сессии (системные события)

Задания основной сессии ставят в очередь системное событие и опционально пробуждают исполнитель сердцебиения. Они должны использовать payload.kind = "systemEvent".

  • wakeMode: "next-heartbeat" (по умолчанию): событие ждет следующего запланированного сердцебиения.
  • wakeMode: "now": событие запускает немедленное выполнение сердцебиения.

Это лучший вариант, когда вы хотите обычный промпт сердцебиения + контекст основной сессии. См. Heartbeat.

Изолированные задания (выделенные cron-сессии)

Изолированные задания выполняют отдельный ход агента в сессии cron:<jobId>.

Ключевое поведение:

  • Промпт с префиксом [cron:<jobId> <имя задания>] для отслеживаемости.
  • Каждый запуск начинает новый session id (без переноса предыдущей беседы).
  • Сводка публикуется в основной сессии (префикс Cron, настраивается).
  • wakeMode: "now" запускает немедленное сердцебиение после публикации сводки.
  • Если payload.deliver: true, вывод доставляется в канал; иначе остается внутренним.

Используйте изолированные задания для шумных, частых или "фоновых задач", которые не должны спамить вашу основную историю чата.

Формы полезной нагрузки (что выполняется)

Поддерживаются два типа полезной нагрузки:

  • systemEvent: только для основной сессии, маршрутизируется через промпт сердцебиения.
  • agentTurn: только для изолированной сессии, выполняет отдельный ход агента.

Общие поля agentTurn:

  • message: обязательный текстовый промпт.
  • model / thinking: опциональные переопределения (см. ниже).
  • timeoutSeconds: опциональное переопределение таймаута.
  • deliver: true для отправки вывода в целевой канал.
  • channel: last или конкретный канал.
  • to: специфичная для канала цель (телефон/чат/id канала).
  • bestEffortDeliver: избегать сбоя задания, если доставка не удалась.

Параметры изоляции (только для session=isolated):

  • postToMainPrefix (CLI: --post-prefix): префикс для системного события в основной сессии.
  • postToMainMode: summary (по умолчанию) или full.
  • postToMainMaxChars: максимум символов когда postToMainMode=full (по умолчанию 8000).

Переопределения модели и мышления

Изолированные задания (agentTurn) могут переопределять модель и уровень мышления:

  • model: Строка провайдер/модель (например, anthropic/claude-sonnet-4-20250514) или алиас (например, opus)
  • thinking: Уровень мышления (off, minimal, low, medium, high, xhigh; только модели GPT-5.2 + Codex)

Примечание: Вы можете установить model и для заданий основной сессии, но это изменяет общую модель основной сессии. Мы рекомендуем переопределения модели только для изолированных заданий, чтобы избежать неожиданных смен контекста.

Приоритет разрешения:

  1. Переопределение полезной нагрузки задания (наивысший)
  2. Значения по умолчанию для конкретного хука (например, hooks.gmail.model)
  3. Конфигурация агента по умолчанию

Доставка (канал + цель)

Изолированные задания могут доставлять вывод в канал. Полезная нагрузка задания может указывать:

  • channel: whatsapp / telegram / discord / slack / mattermost (плагин) / signal / imessage / last
  • to: специфичная для канала целевая получатель

Если channel или to пропущены, cron может вернуться к "последнему маршруту" основной сессии (последнее место, где агент ответил).

Примечания по доставке:

  • Если установлен to, cron автоматически доставляет финальный вывод агента, даже если deliver не указан.
  • Используйте deliver: true, когда хотите доставку по последнему маршруту без явного to.
  • Используйте deliver: false, чтобы сохранить вывод внутренним, даже если присутствует to.

Напоминания о формате цели:

  • Цели Slack/Discord/Mattermost (плагин) должны использовать явные префиксы (например, channel:<id>, user:<id>), чтобы избежать неоднозначности.
  • Темы Telegram должны использовать форму :topic: (см. ниже).

Цели доставки Telegram (темы / форумные потоки)

Telegram поддерживает темы форума через message_thread_id. Для доставки cron вы можете закодировать тему/поток в поле to:

  • -1001234567890 (только id чата)
  • -1001234567890:topic:123 (предпочтительно: явный маркер темы)
  • -1001234567890:123 (краткая форма: числовой суффикс)

Префиксные цели типа telegram:... / telegram:group:... также принимаются:

  • telegram:group:-1001234567890:topic:123

Хранилище и история

  • Хранилище заданий: ~/.openclaw/cron/jobs.json (JSON, управляемый Gateway).
  • История выполнений: ~/.openclaw/cron/runs/<jobId>.jsonl (JSONL, автоматическая очистка).
  • Переопределить путь хранилища: cron.store в конфигурации.

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

{
  cron: {
    enabled: true, // по умолчанию true
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1 // по умолчанию 1
  }
}

Полностью отключить cron:

  • cron.enabled: false (конфигурация)
  • OPENCLAW_SKIP_CRON=1 (переменная окружения)

Быстрый старт CLI

Одноразовое напоминание (UTC ISO, автоудаление после успеха):

openclaw cron add \
  --name "Send reminder" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "Reminder: submit expense report." \
  --wake now \
  --delete-after-run

Одноразовое напоминание (основная сессия, пробудить немедленно):

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

Повторяющееся изолированное задание (доставить в WhatsApp):

openclaw cron add \
  --name "Morning status" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

Повторяющееся изолированное задание (доставить в тему Telegram):

openclaw cron add \
  --name "Nightly summary (topic)" \
  --cron "0 22 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize today; send to the nightly topic." \
  --deliver \
  --channel telegram \
  --to "-1001234567890:topic:123"

Изолированное задание с переопределением модели и мышления:

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

Выбор агента (настройки с несколькими агентами):
```bash
# Привязать задание к агенту "ops" (вернуться к умолчанию, если этот агент отсутствует)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops

# Переключить или очистить агента для существующего задания
openclaw cron edit <jobId> --agent ops
openclaw cron edit <jobId> --clear-agent


Ручной запуск (отладка):
```bash
openclaw cron run <jobId> --force

Редактировать существующее задание (изменить поля):

openclaw cron edit <jobId> \
  --message "Updated prompt" \
  --model "opus" \
  --thinking low

История выполнений:

openclaw cron runs --id <jobId> --limit 50

Немедленное системное событие без создания задания:

openclaw system event --mode now --text "Next heartbeat: check battery."

Поверхность Gateway API

  • cron.list, cron.status, cron.add, cron.update, cron.remove
  • cron.run (принудительно или по расписанию), cron.runs Для немедленных системных событий без задания используйте openclaw system event.

Устранение неполадок

"Ничего не запускается"

  • Проверьте, что cron включен: cron.enabled и OPENCLAW_SKIP_CRON.
  • Проверьте, что Gateway работает непрерывно (cron выполняется внутри процесса Gateway).
  • Для расписаний cron: подтвердите часовой пояс (--tz) против часового пояса хоста.

Telegram доставляет не туда

  • Для тем форума используйте -100…:topic:<id>, чтобы это было явно и однозначно.
  • Если вы видите префиксы telegram:... в логах или сохраненных целях "последнего маршрута", это нормально; доставка cron принимает их и все равно корректно парсит ID тем.
← Назад к документации