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

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

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

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

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

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

## Як працює cron

- Cron працює **всередині** процесу Gateway (не всередині моделі).
- Завдання зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів.
- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks).
- Одноразові завдання (`--at`) після успішного виконання автоматично видаляються за замовчуванням.
- Ізольовані запуски cron у режимі best-effort закривають відстежувані вкладки браузера/процеси для своєї сесії `cron:<jobId>`, коли виконання завершується, щоб відокремлена автоматизація браузера не залишала після себе осиротілі процеси.
- Ізольовані запуски 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`      | Cron-вираз із 5 або 6 полів з необов’язковим `--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`) зберігають контекст між запусками, що дає змогу будувати робочі процеси на кшталт щоденних стендапів на основі попередніх підсумків.

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

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

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

- `--message`: текст prompt (обов’язковий для isolated)
- `--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` усе одно має вищий пріоритет над конфігурацією в будь-який бік.

Якщо ізольований запуск натрапляє на live-передавання керування під час перемикання моделі, cron виконує повторну спробу з перемкненим provider/model і зберігає цей live-вибір перед повторною спробою. Якщо перемикання також містить новий 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, виконавець відповідає за фінальний шлях доставки. Агент отримує prompt повернути підсумок простим текстом, і цей підсумок потім надсилається через `announce`, `webhook` або зберігається внутрішньо для `none`. `--no-deliver` не повертає доставку під контроль агента; він залишає запуск внутрішнім.

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

Сповіщення про помилки використовують окремий шлях призначення:

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

## Вебхуки

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

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

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

### Mapped hooks (POST /hooks/\<name\>)

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

### Безпека

- Тримайте кінцеві точки 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), увімкнені hook в OpenClaw, Tailscale для публічної HTTPS-кінцевої точки.

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

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

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

### Автозапуск 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

# 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 ...` змінює вибрану модель завдання.
- Якщо модель дозволена, саме цей точний provider/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 },
  },
}
```

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

**Повтор одноразового завдання**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки негайно вимикаються.

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

**Обслуговування**: `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` означає, що зовнішнє повідомлення не очікується.
- Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено.
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку заблоковано обліковими даними.
- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також пригнічує резервний шлях із постановкою підсумку в чергу, тому назад у чат нічого не публікується.
- Для ізольованих завдань, якими керує cron, не очікуйте, що агент використовуватиме message tool як резервний варіант. Виконавець керує фінальною доставкою; `--no-deliver` натомість залишає її внутрішньою.

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

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

## Пов’язане

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