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

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

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

openclaw cron create "2026-02-01T16:00:00Z" \  --name "Reminder" \  --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 (а не всередині моделі).
• Визначення завдань, стан виконання та історія запусків зберігаються у спільній SQLite-базі стану OpenClaw, тому перезапуски не призводять до втрати розкладів.
• Під час оновлення виконайте openclaw doctor --fix, щоб імпортувати застарілі файли ~/.openclaw/cron/jobs.json, jobs-state.json і runs/*.jsonl у SQLite та перейменувати їх із суфіксом .migrated. Некоректні рядки завдань пропускаються під час виконання та копіюються в jobs-quarantine.json для подальшого виправлення або перегляду.
• cron.store досі позначає логічний ключ сховища cron і шлях імпорту doctor. Після імпорту редагування цього JSON-файлу більше не змінює активні cron-завдання; натомість використовуйте openclaw cron add|edit|remove або RPC-методи Gateway для cron.
• Усі виконання cron створюють записи фонового завдання.
• Під час запуску Gateway прострочені ізольовані завдання agent-turn переплановуються за межі вікна підключення каналу, а не відтворюються негайно, тож запуск Discord/Telegram і налаштування нативних команд залишаються чуйними після перезапусків.
• Одноразові завдання (--at) за замовчуванням автоматично видаляються після успіху.
• Ізольовані cron-запуски з максимальними зусиллями закривають відстежувані вкладки браузера/процеси для свого сеансу cron:<jobId> після завершення запуску, щоб від'єднана браузерна автоматизація не залишала сирітські процеси.
• Ізольовані cron-запуски, які отримують вузький дозвіл cron на самоочищення, усе ще можуть читати стан планувальника, самовідфільтрований список свого поточного завдання та історію запусків цього завдання, щоб перевірки стану/Heartbeat могли оглядати власний розклад без ширшого доступу до зміни cron.
• Ізольовані cron-запуски також захищаються від застарілих відповідей-підтверджень. Якщо перший результат є лише проміжним оновленням стану (on it, pulling everything together і подібні підказки), а жоден дочірній subagent-запуск більше не відповідає за фінальну відповідь, OpenClaw один раз повторно надсилає запит на фактичний результат перед доставкою.
• Ізольовані cron-запуски використовують структуровані метадані відмови у виконанні з вбудованого запуску, зокрема обгортки node-host UNAVAILABLE, вкладене повідомлення про помилку яких починається з SYSTEM_RUN_DENIED або INVALID_REQUEST, тож заблокована команда не звітується як успішний запуск, а звичайний текст асистента не сприймається як відмова.
• Ізольовані cron-запуски також трактують помилки агента на рівні запуску як помилки завдання, навіть коли payload відповіді не створено, тож помилки моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій замість позначення завдання як успішного.
• Коли ізольоване завдання agent-turn досягає timeoutSeconds, cron перериває базовий запуск агента й надає йому коротке вікно для очищення. Якщо запуск не завершується, очищення під керуванням Gateway примусово очищає власність сеансу цього запуску перед тим, як cron зафіксує тайм-аут, тож поставлена в чергу робота чату не залишається за застарілим обробним сеансом.
• Якщо ізольований agent-turn зависає до старту runner або до першого виклику моделі, cron записує фазоспецифічний тайм-аут, наприклад setup timed out before runner start або stalled before first model call (last phase: context-engine). Ці watchdog-перевірки охоплюють вбудованих провайдерів і провайдерів на базі CLI до фактичного старту їхнього зовнішнього CLI-процесу та обмежуються незалежно від довгих значень timeoutSeconds, щоб збої холодного старту/автентифікації/контексту проявлялися швидко, а не чекали повного бюджету завдання.
• Якщо ви використовуєте системний cron або інший зовнішній планувальник для запуску openclaw agent, обгорніть його ескалацією hard-kill, навіть якщо CLI обробляє SIGTERM/SIGINT. Запуски через Gateway просять Gateway перервати прийняті запуски; локальні та вбудовані fallback-запуски отримують той самий сигнал переривання. Для GNU timeout надавайте перевагу timeout -k 60 600 openclaw agent ... замість простого timeout 600 ...; значення -k є резервним обмежувачем supervisor, якщо процес не може завершитися. Для systemd unit зберігайте ту саму форму, використовуючи сигнал зупинки SIGTERM плюс пільгове вікно, наприклад TimeoutStopSec, перед будь-яким фінальним kill. Якщо повторна спроба повторно використовує --run-id, поки оригінальний запуск Gateway усе ще активний, дублікат звітується як такий, що вже виконується, замість старту другого запуску.

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

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

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

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

Cron-вирази розбираються 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 чи команді вашого завдання.

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

Payload команд

Використовуйте payload команд для детермінованих скриптів, які мають виконуватися всередині планувальника Gateway без старту ізольованого agent turn на базі моделі. Командні завдання виконуються на хості Gateway, захоплюють stdout/stderr, записують запуск в історію cron і повторно використовують ті самі режими доставки announce, webhook і none, що й ізольовані завдання.

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> зберігає argv: ["sh", "-lc", <shell>]. Використовуйте --command-argv '["node","scripts/report.mjs"]', коли потрібно точне виконання argv без розбору shell. Необов'язкові поля --command-env KEY=VALUE, --command-input, --timeout-seconds, --no-output-timeout-seconds і --output-max-bytes керують середовищем процесу, stdin і межами виводу.

Якщо stdout непорожній, цей текст є доставленим результатом. Якщо stdout порожній, а stderr непорожній, доставляється stderr. Якщо присутні обидва потоки, cron доставляє невеликий блок stdout: / stderr:. Нульовий код виходу записує запуск як ok; ненульовий вихід, сигнал, тайм-аут або тайм-аут без виводу записує error і може запускати сповіщення про збій. Команда, яка друкує лише NO_REPLY, використовує звичайне приглушення silent-token у cron і нічого не надсилає назад у чат.

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

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

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

Перевірки preflight для локального провайдера проходять налаштовані fallback перед позначенням запуску cron як skipped; fallbacks: [] зберігає цей preflight-шлях строгим.

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

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

Швидкий режим також дотримується розв’язаного live-вибору. Якщо конфіг вибраної моделі має params.fastMode, isolated cron використовує його за замовчуванням. Збережене перевизначення fastMode у сесії все одно має пріоритет над конфігом в обох напрямках. Auto mode використовує поріг params.fastAutoOnSeconds вибраної моделі, якщо він присутній, інакше за замовчуванням 60 секунд.

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

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

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

Використовуйте --announce --channel telegram --to "-1001234567890" для доставки в канал. Для тем форуму Telegram використовуйте -1001234567890:topic:123; OpenClaw також приймає скорочення -1001234567890:123, яке належить Telegram. Прямі RPC/config-виклики можуть передавати delivery.threadId як рядок або число. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (channel:<id>, user:<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>, залишаються синтаксисом цілі, яким володіє канал, а не селекторами провайдера.

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

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

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

Мова виводу

Cron-завдання не виводять мову відповіді з каналу, локалі або попередніх повідомлень. Додайте правило мови в заплановане повідомлення або шаблон:

openclaw cron edit <jobId> \  --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."

Для файлів шаблонів тримайте інструкцію щодо мови в згенерованому prompt і перевіряйте, що placeholders на кшталт {{language}} заповнені до запуску завдання. Якщо вивід змішує мови, зробіть правило явним, наприклад: "Use Chinese for narrative text and keep technical terms in English."

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

• 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 create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --tz "America/Los_Angeles" \  --session isolated \  --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

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

Webhook

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

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

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

Кожен запит має містити hook-токен через header:

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

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

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 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, щоб відмовитися.

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

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:gmail-api-push@system.gserviceaccount.com \  --role=roles/pubsub.publisher

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 # Отримати одне збережене завдання як JSONopenclaw cron get <jobId> # Показати одне завдання, включно з визначеним маршрутом доставкиopenclaw cron show <jobId> # Редагувати завданняopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Примусово запустити завдання заразopenclaw cron run <jobId> # Примусово запустити завдання зараз і дочекатися його кінцевого стануopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Запустити лише якщо настав часopenclaw cron run <jobId> --due # Переглянути історію запусківopenclaw cron runs --id <jobId> --limit 50 # Переглянути один точний запускopenclaw cron runs --id <jobId> --run-id <runId> # Видалити завданняopenclaw cron remove <jobId> # Вибір агента (налаштування з кількома агентами)openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

openclaw cron run <jobId> повертається після додавання ручного запуску до черги. Використовуйте --wait для shutdown-хуків, скриптів обслуговування або іншої автоматизації, яка має блокуватися, доки запуск у черзі не завершиться. Режим очікування опитує точний повернений runId; він завершується з 0 для статусу ok і з ненульовим кодом для error, skipped або тайм-ауту очікування.

Інструмент агента cron повертає компактні підсумки завдань (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) з cron(action: "list"); використовуйте cron(action: "get", jobId: "...") для одного повного визначення завдання. Прямі викликачі Gateway можуть передати compact: true до cron.list; якщо його опустити, зберігається наявна повна відповідь із попередніми переглядами доставки.

openclaw cron create є псевдонімом для openclaw cron add, а нові завдання можуть використовувати позиційний розклад ("0 9 * * 1", "every 1h", "20m" або ISO timestamp), після якого йде позиційний prompt агента. Використовуйте --webhook <url> у cron add|create або cron edit, щоб POST-ити payload завершеного запуску до HTTP-точки доступу. Доставку Webhook не можна поєднувати з прапорцями доставки в чат, такими як --announce, --channel, --to, --thread-id або --account. У cron edit --clear-channel, --clear-to, --clear-thread-id і --clear-account скасовують ці поля маршрутизації окремо (кожен відхиляється разом із відповідним прапорцем установлення), що відрізняється від --no-deliver, який вимикає fallback-доставку runner.

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

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 8,    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, так і виконання ізольованих ходів агента, і за замовчуванням дорівнює 8. Ізольовані ходи cron-агента внутрішньо використовують виділену чергу виконання cron-nested, тому збільшення цього значення дає незалежним cron LLM-запускам змогу просуватися паралельно, а не лише запускати зовнішні cron-обгортки. Спільна не-cron черга nested цим налаштуванням не розширюється.

cron.store є логічним ключем сховища та шляхом імпорту legacy doctor. Запустіть openclaw doctor --fix, щоб імпортувати наявні JSON-сховища в SQLite і заархівувати їх; майбутні зміни cron мають виконуватися через CLI або Gateway API.

Вимкнути 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 — періодичні ходи основного сеансу
• Timezone — конфігурація timezone