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

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

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

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 listopenclaw cron get <job-id>openclaw cron show <job-id>

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, але можуть сприймати завдання як нові, оскільки поля runtime тепер зберігаються в jobs-state.json.
• Коли jobs.json редагують під час роботи Gateway або коли його зупинено, OpenClaw порівнює змінені поля розкладу з метаданими pending runtime slot і очищає застарілі значення nextRunAtMs. Перезаписи, що змінюють лише форматування або порядок ключів, зберігають pending slot.
• Усі виконання cron створюють записи фонового завдання.
• Під час запуску Gateway прострочені ізольовані завдання agent-turn переплановуються за межі вікна підключення каналу, а не відтворюються негайно, тому запуск Discord/Telegram і налаштування native-command залишаються чутливими після перезапусків.
• Одноразові завдання (--at) типово автоматично видаляються після успішного виконання.
• Ізольовані запуски cron за принципом best-effort закривають відстежувані вкладки/процеси браузера для своєї сесії cron:<jobId> після завершення запуску, щоб від’єднана автоматизація браузера не залишала осиротілі процеси.
• Ізольовані запуски cron, які отримують вузький дозвіл cron self-cleanup grant, усе ще можуть читати статус планувальника, self-filtered список свого поточного завдання та історію запусків цього завдання, щоб перевірки статусу/Heartbeat могли переглядати власний розклад без ширшого доступу до мутацій cron.
• Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення статусу (on it, pulling everything together і подібні підказки), і жоден дочірній subagent run більше не відповідає за фінальну відповідь, OpenClaw один раз повторно запитує фактичний результат перед доставкою.
• Ізольовані запуски cron надають перевагу структурованим метаданим execution-denial із вбудованого запуску, а потім повертаються до відомих маркерів фінального підсумку/виводу, як-от SYSTEM_RUN_DENIED і INVALID_REQUEST, тому заблокована команда не звітується як успішний запуск.
• Ізольовані запуски cron також розглядають помилки агента на рівні запуску як помилки завдання, навіть коли payload відповіді не створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій замість того, щоб позначати завдання як успішне.
• Коли ізольоване завдання agent-turn досягає timeoutSeconds, cron перериває базовий запуск агента й надає йому коротке вікно очищення. Якщо запуск не завершує draining, очищення під керуванням Gateway примусово очищає право власності цієї сесії на запуск перед тим, як cron запише тайм-аут, щоб робота чату в черзі не залишилася за застарілою processing session.
• Якщо ізольований agent-turn зависає до старту runner або до першого виклику моделі, cron записує фазово-специфічний тайм-аут, як-от setup timed out before runner start або stalled before first model call (last phase: context-engine). Ці watchdogs покривають вбудованих провайдерів і CLI-backed провайдерів до фактичного запуску їхнього зовнішнього CLI-процесу та обмежуються незалежно від довгих значень timeoutSeconds, щоб збої cold-start/auth/context проявлялися швидко, а не чекали повного бюджету завдання.

Типи розкладів

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

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

Day-of-month і day-of-week використовують логіку OR

Cron-вирази розбираються за допомогою croner. Коли поля day-of-month і day-of-week обидва не є 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. Щоб вимагати обидві умови, використовуйте модифікатор day-of-week + у Croner (0 9 15 * +1) або плануйте за одним полем і перевіряйте інше в prompt чи команді вашого завдання.

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

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

--model використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення /model у chat-session: налаштовані fallback chains усе ще застосовуються, коли основна модель завдання дає збій. Якщо запитана модель не дозволена або не може бути resolved, cron завершує запуск з явною validation error замість мовчазного fallback до agent/default model selection завдання.

Cron-завдання також можуть містити fallbacks на рівні payload. Коли цей список присутній, він замінює налаштований fallback chain для завдання. Використовуйте fallbacks: [] у job payload/API, коли потрібен строгий запуск cron, який пробує лише вибрану модель. Якщо завдання має --model, але не має ні payload fallbacks, ні configured fallbacks, OpenClaw передає явне порожнє fallback override, щоб agent primary не додавався як прихована додаткова retry target.

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

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

Fast mode також відповідає resolved live selection. Якщо конфіг вибраної моделі має params.fastMode, isolated cron типово використовує його. Збережене перевизначення сесії fastMode усе ще має пріоритет над config в обох напрямках.

Якщо ізольований запуск потрапляє на live model-switch handoff, cron повторює спробу з перемкненим provider/model і зберігає цей live selection для активного запуску перед retry. Коли перемикання також містить новий auth profile, cron також зберігає це auth profile override для активного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 switch retries cron перериває виконання замість нескінченного циклу.

Перш ніж ізольований запуск Cron увійде до runner агента, OpenClaw перевіряє доступні локальні кінцеві точки провайдера для налаштованих провайдерів api: "ollama" і api: "openai-completions", у яких baseUrl є loopback, приватною мережею або .local. Якщо ця кінцева точка недоступна, запуск записується як skipped із чіткою помилкою провайдера/моделі замість початку виклику моделі. Результат кінцевої точки кешується на 5 хвилин, тому багато запланованих завдань, що використовують той самий недоступний локальний сервер Ollama, vLLM, SGLang або LM Studio, спільно використовують одну невелику перевірку замість створення шквалу запитів. Пропущені запуски provider-preflight не збільшують backoff помилок виконання; увімкніть failureAlert.includeSkipped, якщо потрібні повторні сповіщення про пропуск.

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

Використовуйте --announce --channel telegram --to "-1001234567890" для доставки в канал. Для тем форуму Telegram використовуйте -1001234567890:topic:123; прямі RPC/config виклики також можуть передавати delivery.threadId як рядок або число. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (channel:<id>, user:<id>). ID кімнат Matrix чутливі до регістру; використовуйте точний ID кімнати або форму room:!room:server з Matrix.

Коли доставка announce використовує channel: "last" або пропускає channel, ціль із префіксом провайдера, наприклад telegram:123, може вибрати канал до того, як Cron повернеться до історії сесії або одного налаштованого каналу. Лише префікси, оголошені завантаженим Plugin, є селекторами провайдера. Якщо delivery.channel задано явно, префікс цілі має називати того самого провайдера; наприклад, channel: "whatsapp" із to: "telegram:123" відхиляється замість того, щоб дозволити WhatsApp інтерпретувати Telegram ID як номер телефону. Префікси типу цілі та сервісу, як-от channel:<id>, user:<id>, imessage:<handle> і sms:<number>, залишаються синтаксисом цілей, яким володіє канал, а не селекторами провайдера.

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

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

Неявна доставка announce використовує налаштовані allowlists каналів для валідації та перемаршрутизації застарілих цілей. Схвалення зі сховища пар DM не є одержувачами резервної автоматизації; задайте delivery.to або налаштуйте запис allowFrom каналу, коли заплановане завдання має проактивно надсилати в DM.

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

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

Приклади 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"

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 Webhook кінцеві точки для зовнішніх тригерів. Увімкніть у config:

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

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

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

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

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

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

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

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

Під’єднайте тригери вхідної пошти Gmail до OpenClaw через Google PubSub.

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

openclaw webhooks gmail setup --account [email protected]

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

Автозапуск Gateway

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

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

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

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:[email protected] \  --role=roles/pubsub.publisher

gog gmail watch start \  --account [email protected] \  --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",    },  },}

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

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent opsopenclaw cron edit <jobId> --clear-agent

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

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

maxConcurrentRuns обмежує як заплановану диспетчеризацію Cron, так і виконання ізольованих ходів агента. Ізольовані агентські ходи Cron внутрішньо використовують виділену lane виконання черги cron-nested, тому збільшення цього значення дає незалежним LLM-запускам Cron просуватися паралельно, а не лише запускати їхні зовнішні wrappers Cron. Спільна lane nested, що не належить Cron, цим налаштуванням не розширюється.

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

Якщо ви редагуєте jobs.json вручну, не додавайте jobs-state.json до source control. OpenClaw використовує цей sidecar для pending slots, active markers, метаданих останнього запуску та ідентичності розкладу, яка повідомляє scheduler, коли зовнішньо відредагованому завданню потрібен свіжий nextRunAtMs.

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

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

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

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

Пов’язане

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