Заплановані завдання (Cron)

Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у канал чату або на endpoint вебхука.

Швидкий старт

# Додати одноразове нагадування
openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

# Перевірити свої завдання
openclaw cron list

# Переглянути історію запусків
openclaw cron runs --id <job-id>

Як працює cron

Cron працює всередині процесу Gateway (не всередині моделі).
Завдання зберігаються в ~/.openclaw/cron/jobs.json, тому перезапуски не призводять до втрати розкладів.
Усі виконання cron створюють записи фонових завдань.
Одноразові завдання (--at) за замовчуванням автоматично видаляються після успішного виконання.
Ізольовані запуски cron у межах best-effort закривають відстежувані вкладки/процеси браузера для своєї сесії cron:<jobId> після завершення запуску, щоб відокремлена автоматизація браузера не залишала осиротілі процеси.
Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення стану (on it, pulling everything together та подібні підказки), і жоден дочірній запуск subagent більше не відповідає за фінальну відповідь, OpenClaw повторно надсилає запит один раз для отримання фактичного результату перед доставкою.

Узгодження завдань для cron належить до runtime: активне завдання cron залишається активним, доки runtime cron усе ще відстежує це завдання як запущене, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і спливає 5-хвилинне вікно пільги, обслуговування може позначити завдання як lost.

Типи розкладу

Тип	Прапорець CLI	Опис
`at`	`--at`	Одноразова мітка часу (ISO 8601 або відносна, наприклад `20m`)
`every`	`--every`	Фіксований інтервал
`cron`	`--cron`	Cron-вираз із 5 або 6 полів із необов’язковим `--tz`

Мітки часу без часової зони трактуються як UTC. Додайте --tz America/New_York для планування за локальним часом. Повторювані вирази на початок години автоматично зсуваються до 5 хвилин, щоб зменшити пікове навантаження. Використовуйте --exact, щоб примусово ввімкнути точний час, або --stagger 30s для явного вікна.

Стилі виконання

Стиль	Значення `--session`	Запускається в	Найкраще підходить для
Основна сесія	`main`	Наступний цикл heartbeat	Нагадувань, системних подій
Ізольований	`isolated`	Виділена `cron:<jobId>`	Звітів, фонових завдань
Поточна сесія	`current`	Прив’язується під час створення	Повторюваної роботи з урахуванням контексту
Користувацька сесія	`session:custom-id`	Постійна іменована сесія	Процесів, що спираються на історію

Завдання основної сесії ставлять у чергу системну подію й за потреби пробуджують heartbeat (--wake now або --wake next-heartbeat). Ізольовані завдання запускають окремий цикл агента з новою сесією. Користувацькі сесії (session:xxx) зберігають контекст між запусками, що дає змогу будувати процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. Для ізольованих завдань teardown runtime тепер також включає best-effort очищення браузера для цієї сесії cron. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет. Коли ізольовані запуски cron оркеструють subagent, доставка також надає перевагу фінальному результату дочірнього процесу над застарілим проміжним текстом батьківського. Якщо дочірні процеси все ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського процесу замість того, щоб оголошувати його.

Параметри payload для ізольованих завдань

--message: текст запиту (обов’язковий для isolated)
--model / --thinking: перевизначення моделі та рівня thinking
--light-context: пропустити ін’єкцію файлів bootstrap робочого простору
--tools exec,read: обмежити, які інструменти може використовувати завдання

--model використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і повертається до вибору моделі агента/типової моделі для цього завдання. Налаштовані ланцюжки fallback усе ще застосовуються, але просте перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль для повторної спроби. Пріоритет вибору моделі для ізольованих завдань такий:

Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене)
model у payload конкретного завдання
Збережене перевизначення моделі сесії cron
Вибір моделі агента/типової моделі

Швидкий режим також наслідує вибраний поточний варіант. Якщо в конфігурації вибраної моделі є params.fastMode, ізольований cron використовує його за замовчуванням. Збережене перевизначення сесії fastMode усе одно має пріоритет над конфігурацією в обох напрямках. Якщо ізольований запуск потрапляє на передачу керування під час живого перемикання моделі, cron повторює спробу з перемкнутим provider/model і зберігає цей поточний вибір перед повторною спробою. Коли перемикання також несе новий профіль auth, cron зберігає і це перевизначення профілю auth. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб перемикання cron перериває виконання замість нескінченного циклу.

Доставка та вивід

Режим	Що відбувається
`announce`	Доставити підсумок у цільовий канал (типово для isolated)
`webhook`	Надіслати payload події завершення через POST на URL
`none`	Лише внутрішньо, без доставки

Використовуйте --announce --channel telegram --to "-1001234567890" для доставки в канал. Для тем форуму Telegram використовуйте -1001234567890:topic:123. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (channel:<id>, user:<id>). Для ізольованих завдань, якими володіє cron, runner керує фінальним шляхом доставки. Агент отримує запит повернути текстовий підсумок, а потім цей підсумок надсилається через announce, webhook або зберігається внутрішньо для none. --no-deliver не повертає доставку агенту; воно залишає запуск внутрішнім. Якщо оригінальне завдання явно вказує написати якомусь зовнішньому отримувачу, агент має зазначити виводом, кому/куди має бути надіслано це повідомлення, замість спроби відправити його безпосередньо. Сповіщення про збої йдуть окремим маршрутом призначення:

cron.failureDestination задає глобальне типове призначення для сповіщень про збої.
job.delivery.failureDestination перевизначає його для конкретного завдання.
Якщо не задано жодного з них, а завдання вже доставляє через announce, сповіщення про збої тепер за замовчуванням повертаються до цієї основної цілі announce.
delivery.failureDestination підтримується лише для завдань sessionTarget="isolated", якщо основний режим доставки не є webhook.

Приклади CLI

Одноразове нагадування (основна сесія):

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

Повторюване ізольоване завдання з доставкою:

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"

Ізольоване завдання з перевизначенням моделі та thinking:

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 \
  --announce

Вебхуки

Gateway може відкривати endpoint-и HTTP вебхуків для зовнішніх тригерів. Увімкніть у конфігурації:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Автентифікація

Кожен запит має містити токен hook через заголовок:

Authorization: Bearer <token> (рекомендовано)
x-openclaw-token: <token>

Токени в query string відхиляються.

POST /hooks/wake

Поставити системну подію в чергу для основної сесії:

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

text (обов’язково): опис події
mode (необов’язково): now (типово) або next-heartbeat

POST /hooks/agent

Запустити ізольований цикл агента:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'

Поля: message (обов’язково), name, agentId, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.

Зіставлені hook-и (POST /hooks/<name>)

Користувацькі назви hook-ів визначаються через hooks.mappings у конфігурації. Зіставлення можуть перетворювати довільний payload на дії wake або agent за допомогою шаблонів чи трансформацій коду.

Безпека

Тримайте endpoint-и hook-ів за loopback, tailnet або довіреним reverse proxy.
Використовуйте окремий токен hook; не використовуйте повторно токени auth gateway.
Тримайте hooks.path на окремому підшляху; / відхиляється.
Установіть hooks.allowedAgentIds, щоб обмежити явну маршрутизацію agentId.
Залишайте hooks.allowRequestSessionKey=false, якщо вам не потрібні сесії, що обираються викликачем.
Якщо ви вмикаєте hooks.allowRequestSessionKey, також задайте hooks.allowedSessionKeyPrefixes, щоб обмежити допустимі форми ключів сесії.
Payload-и hook-ів за замовчуванням обгортаються межами безпеки.

Інтеграція Gmail PubSub

Підключіть тригери вхідної Gmail до OpenClaw через Google PubSub. Передумови: gcloud CLI, gog (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint.

Налаштування через майстер (рекомендовано)

openclaw webhooks gmail setup --account openclaw@gmail.com

Це записує конфігурацію hooks.gmail, вмикає пресет Gmail і використовує Tailscale Funnel для push endpoint.

Автозапуск Gateway

Коли hooks.enabled=true і задано hooks.gmail.account, Gateway під час запуску стартує gog gmail watch serve і автоматично поновлює watch. Установіть OPENCLAW_SKIP_GMAIL_WATCHER=1, щоб відмовитися від цього.

Ручне одноразове налаштування

Виберіть проєкт GCP, який володіє OAuth client, що використовується gog:

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

Створіть topic і надайте Gmail доступ для push:

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

Запустіть watch:

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

Перевизначення моделі Gmail

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

Керування завданнями

# Перелічити всі завдання
openclaw cron list

# Редагувати завдання
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Примусово запустити завдання зараз
openclaw cron run <jobId>

# Запустити лише якщо настав час
openclaw cron run <jobId> --due

# Переглянути історію запусків
openclaw cron runs --id <jobId> --limit 50

# Видалити завдання
openclaw cron remove <jobId>

# Вибір агента (конфігурації з кількома агентами)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

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

openclaw cron add|edit --model ... змінює вибрану модель завдання.
Якщо модель дозволена, саме цей provider/model потрапляє до ізольованого запуску агента.
Якщо ні, cron попереджає та повертається до вибору моделі агента/типової моделі завдання.
Налаштовані ланцюжки fallback усе ще застосовуються, але просте перевизначення --model без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби.

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

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

Вимкнення cron: cron.enabled: false або OPENCLAW_SKIP_CRON=1. Повторна спроба для одноразових завдань: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційною затримкою. Постійні помилки негайно вимикаються. Повторна спроба для повторюваних завдань: експоненційна затримка (від 30 с до 60 хв) між спробами. Затримка скидається після наступного успішного запуску. Обслуговування: cron.sessionRetention (типово 24h) видаляє записи сесій ізольованих запусків. cron.runLog.maxBytes / cron.runLog.keepLines автоматично очищають файли журналу запусків.

Усунення несправностей

Послідовність команд

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

Cron не спрацьовує

Перевірте cron.enabled і змінну середовища OPENCLAW_SKIP_CRON.
Підтвердьте, що Gateway працює безперервно.
Для розкладів cron перевірте часовий пояс (--tz) у порівнянні з часовим поясом хоста.
reason: not-due у виводі запуску означає, що ручний запуск було перевірено через openclaw cron run <jobId> --due, але час виконання завдання ще не настав.

Cron спрацював, але доставки немає

Режим доставки none означає, що зовнішнє повідомлення не очікується.
Відсутня/некоректна ціль доставки (channel/to) означає, що вихідне надсилання було пропущено.
Помилки auth каналу (unauthorized, Forbidden) означають, що доставку заблоковано обліковими даними.
Якщо ізольований запуск повертає лише тихий токен (NO_REPLY / no_reply), OpenClaw пригнічує пряме вихідне надсилання, а також запасний шлях доставки підсумку через чергу, тому назад у чат нічого не публікується.
Для ізольованих завдань, якими володіє cron, не очікуйте, що агент використовуватиме інструмент message як запасний варіант. Runner керує фінальною доставкою; --no-deliver залишає її внутрішньою, а не дозволяє пряме надсилання.

Особливості часових поясів

Cron без --tz використовує часовий пояс хоста gateway.
Розклади at без часового поясу трактуються як UTC.
activeHours для heartbeat використовує налаштоване визначення часового поясу.

Пов’язане

Автоматизація та завдання — огляд усіх механізмів автоматизації
Фонові завдання — журнал завдань для виконань cron
Heartbeat — періодичні цикли основної сесії
Часовий пояс — налаштування часового поясу

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Заплановані завдання

Заплановані завдання (Cron)

Швидкий старт

Як працює cron

Типи розкладу

Стилі виконання

Параметри payload для ізольованих завдань

Доставка та вивід

Приклади CLI

Вебхуки

Автентифікація

POST /hooks/wake

POST /hooks/agent

Зіставлені hook-и (POST /hooks/<name>)

Безпека

Інтеграція Gmail PubSub

Налаштування через майстер (рекомендовано)

Автозапуск Gateway

Ручне одноразове налаштування

Перевизначення моделі Gmail

Керування завданнями

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

Усунення несправностей

Послідовність команд

Cron не спрацьовує

Cron спрацював, але доставки немає

Особливості часових поясів

Пов’язане

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Заплановані завдання (Cron)

​Швидкий старт

​Як працює cron

​Типи розкладу

​Стилі виконання

​Параметри payload для ізольованих завдань

​Доставка та вивід

​Приклади CLI

​Вебхуки

​Автентифікація

​POST /hooks/wake

​POST /hooks/agent

​Зіставлені hook-и (POST /hooks/<name>)

​Безпека

​Інтеграція Gmail PubSub

​Налаштування через майстер (рекомендовано)

​Автозапуск Gateway

​Ручне одноразове налаштування

​Перевизначення моделі Gmail

​Керування завданнями

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

​Усунення несправностей

​Послідовність команд

​Cron не спрацьовує

​Cron спрацював, але доставки немає

​Особливості часових поясів

​Пов’язане

Заплановані завдання (Cron)

Швидкий старт

Як працює cron

Типи розкладу

Стилі виконання

Параметри payload для ізольованих завдань

Доставка та вивід

Приклади CLI

Вебхуки

Автентифікація

POST /hooks/wake

POST /hooks/agent

Зіставлені hook-и (POST /hooks/<name>)

Безпека

Інтеграція Gmail PubSub

Налаштування через майстер (рекомендовано)

Автозапуск Gateway

Ручне одноразове налаштування

Перевизначення моделі Gmail

Керування завданнями

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

Усунення несправностей

Послідовність команд

Cron не спрацьовує

Cron спрацював, але доставки немає

Особливості часових поясів

Пов’язане