---
read_when:
    - Планування фонових завдань або пробуджень
    - Підключення зовнішніх тригерів (Webhook-и, Gmail) до OpenClaw
    - Вибір між Heartbeat і Cron для запланованих завдань
summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway
title: Заплановані завдання
x-i18n:
    generated_at: "2026-04-23T22:57:21Z"
    model: gpt-5.4
    provider: openai
    source_hash: a165c7d2c51ebd5625656690458a96b04b498de29ecadcefc65864cbc2c1b84b
    source_path: automation/cron-jobs.md
    workflow: 15
---

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

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

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

```bash
# Add a one-shot reminder
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

# Check your jobs
openclaw cron list
openclaw cron show <job-id>

# See run history
openclaw cron runs --id <job-id>
```

## Як працює cron

- Cron працює **всередині процесу Gateway** (не всередині моделі).
- Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів.
- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте в gitignore.
- Після цього розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть сприймати завдання як нові, оскільки поля стану виконання тепер містяться в `jobs-state.json`.
- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks).
- Одноразові завдання (`--at`) після успішного виконання типово автоматично видаляються.
- Ізольовані запуски cron після завершення виконують очищення відстежуваних вкладок/процесів браузера для своєї сесії `cron:<jobId>` у режимі best-effort, щоб від’єднана автоматизація браузера не залишала сирітські процеси.
- Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо
  перший результат — це лише проміжне оновлення стану (`on it`, `pulling everything
together` та подібні підказки), і жоден дочірній запуск субагента більше не
  відповідає за фінальну відповідь, OpenClaw один раз повторно формує запит, щоб отримати фактичний
  результат перед доставкою.

<a id="maintenance"></a>

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

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

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

Позначки часу без часової зони трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним часом.

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

### День місяця і день тижня використовують логіку OR

Cron-вирази розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard-значеннями, croner виконує збіг, якщо **будь-яке** з полів збігається, а не обидва. Це стандартна поведінка Vixie cron.

```
# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1
```

Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує стандартну OR-поведінку Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` у Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання.

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

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

Завдання **основної сесії** ставлять у чергу системну подію й за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). **Ізольовані** завдання запускають окремий цикл агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу будувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки.

Для ізольованих завдань завершення виконання тепер включає очищення браузера для цієї cron-сесії в режимі best-effort. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет.

Ізольовані запуски cron також звільняють усі вбудовані екземпляри середовища виконання MCP, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як клієнти MCP в основній і користувацьких сесіях завершуються, тож ізольовані завдання cron не спричиняють витоків дочірніх stdio-процесів або довготривалих MCP-з’єднань між запусками.

Коли ізольовані запуски cron оркеструють субагентів, доставка також надає
перевагу фінальному результату нащадка замість застарілого проміжного тексту батьківського запуску. Якщо нащадки все ще
виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість його оголошення.

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

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

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

Пріоритет вибору моделі для ізольованих завдань такий:

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

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

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

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

| Режим      | Що відбувається                                                    |
| ---------- | ------------------------------------------------------------------ |
| `announce` | Резервно доставляє фінальний текст у ціль, якщо агент не надіслав його сам |
| `webhook`  | Надсилає payload події завершення POST-запитом на URL              |
| `none`     | Немає резервної доставки з боку runner                             |

Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:<id>`, `user:<id>`).

Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний,
агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо
агент надсилає повідомлення в налаштовану/поточну ціль, OpenClaw пропускає резервне
оголошення. В іншому разі `announce`, `webhook` і `none` лише керують тим, що
runner робить із фінальною відповіддю після завершення циклу агента.

Сповіщення про збої проходять окремим маршрутом доставки:

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

## Приклади CLI

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

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

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

```bash
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:

```bash
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
```

## Webhook-и

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

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

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

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

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

Токени в рядку запиту відхиляються.

### POST /hooks/wake

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

```bash
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

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

```bash
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"}'
```

Поля: `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; не використовуйте повторно токени автентифікації gateway.
- Тримайте `hooks.path` на окремому підшляху; `/` відхиляється.
- Налаштуйте `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`.
- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, які обирає викликач.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також налаштуйте `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесій.
- Payload-и hook-ів типово обгортаються межами безпеки.

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

Підключіть тригери вхідних листів Gmail до OpenClaw через Google PubSub.

**Передумови**: CLI `gcloud`, `gog` (gogcli), увімкнені OpenClaw hooks, Tailscale для публічного HTTPS-endpoint-а.

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

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

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

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

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

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

1. Виберіть проєкт GCP, якому належить OAuth-клієнт, що використовується `gog`:

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

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

```bash
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
```

3. Запустіть watch:

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

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

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

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

```bash
# List all jobs
openclaw cron list

# Show one job, including resolved delivery route
openclaw cron show <jobId>

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
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 ...` змінює вибрану модель завдання.
- Якщо модель дозволена, саме цей провайдер/модель використовується в ізольованому
  запуску агента.
- Якщо вона не дозволена, cron видає попередження та повертається до вибору
  моделі агента/типової моделі для цього завдання.
- Налаштовані ланцюжки fallback усе ще застосовуються, але звичайне перевизначення `--model`
  без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента
  як до тихої додаткової цілі для повторної спроби.

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

```json5
{
  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 },
  },
}
```

Допоміжний файл стану runtime визначається на основі `cron.store`: сховище `.json`, таке як
`~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а до шляху сховища
без суфікса `.json` додається `-state.json`.

Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`.

**Повтор одноразового завдання**: тимчасові помилки (rate limit, overload, network, server error) повторюються до 3 разів з експоненційною затримкою. Постійні помилки одразу вимикають завдання.

**Повтор періодичного завдання**: експоненційна затримка (від 30 с до 60 хв) між повторними спробами. Після наступного успішного запуску затримка скидається.

**Обслуговування**: `cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналу запусків.

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

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

```bash
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` означає, що резервне надсилання з боку runner не очікується. Агент
  усе ще може надсилати повідомлення напряму через інструмент `message`, якщо маршрут чату доступний.
- Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено.
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку було заблоковано через облікові дані.
- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`),
  OpenClaw пригнічує пряме вихідне надсилання, а також резервний шлях
  queued summary, тому назад у чат нічого не публікується.
- Якщо агент має сам надіслати повідомлення користувачеві, перевірте, що завдання має придатний
  маршрут (`channel: "last"` з попереднім чатом або явно заданий канал/ціль).

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

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

## Пов’язане

- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації з першого погляду
- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron
- [Heartbeat](/uk/gateway/heartbeat) — періодичні цикли основної сесії
- [Часовий пояс](/uk/concepts/timezone) — конфігурація часового поясу
