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

Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може доставляти результат назад у чат-канал або Webhook 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 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, але можуть трактувати завдання як нові, оскільки поля виконання тепер містяться в jobs-state.json.
• Коли jobs.json редагується під час роботи Gateway або коли його зупинено, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного runtime slot і очищає застарілі значення nextRunAtMs. Перезаписи лише з форматуванням або зміною порядку ключів зберігають очікуваний slot.
• Усі виконання cron створюють записи фонового завдання.
• Під час запуску Gateway прострочені ізольовані завдання agent-turn переплановуються за межі вікна підключення каналу, а не відтворюються негайно, тому запуск Discord/Telegram і налаштування native-command залишаються responsive після перезапусків.
• Одноразові завдання (--at) за замовчуванням автоматично видаляються після успішного виконання.
• Ізольовані запуски cron у режимі best-effort закривають відстежувані вкладки браузера/процеси для їхньої сесії cron:<jobId> після завершення запуску, щоб від’єднана браузерна автоматизація не залишала осиротілі процеси.
• Ізольовані запуски cron, які отримують вузький дозвіл на самоочищення cron, усе ще можуть читати стан планувальника й самофільтрований список свого поточного завдання, тож перевірки status/heartbeat можуть оглядати власний розклад без ширшого доступу до мутацій cron.
• Ізольовані запуски cron також захищаються від застарілих підтверджувальних відповідей. Якщо перший результат — це лише проміжне оновлення стану (on it, pulling everything together і подібні підказки), і жоден descendant subagent run більше не відповідає за фінальну відповідь, OpenClaw один раз повторно запитує фактичний результат перед доставкою.
• Ізольовані запуски cron спершу надають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім повертаються до відомих маркерів фінального summary/output, таких як SYSTEM_RUN_DENIED і INVALID_REQUEST, щоб заблокована команда не повідомлялася як успішний запуск.
• Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання навіть тоді, коли payload відповіді не створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій замість того, щоб позначати завдання як успішне.
• Коли ізольоване завдання agent-turn досягає timeoutSeconds, cron перериває базовий запуск агента й надає йому коротке вікно для очищення. Якщо запуск не завершується, очищення, що належить Gateway, примусово очищає ownership сесії цього запуску перед тим, як cron запише timeout, тому робота чату в черзі не лишається за застарілою processing session.

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

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

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

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

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

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

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

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

Якщо старіші або відредаговані вручну entries jobs.json зберігають payload.model як "default", "null", порожній рядок або JSON null, запустіть openclaw doctor --fix. Doctor видаляє ці invalid persisted override sentinels; runtime не підтримує їх як fallback aliases. Опустіть поле model, щоб використовувати normal agent/default model selection.

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

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

1. Gmail hook model override (коли запуск надійшов із Gmail і цей override дозволений)
2. Per-job payload model
3. User-selected stored cron session model override
4. Agent/default model selection

Fast mode також слідує за resolved live selection. Якщо selected model config має params.fastMode, isolated cron використовує це за замовчуванням. Stored session override fastMode усе ще має пріоритет над config в обох напрямках.

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

Перед тим як isolated cron run увійде в agent runner, OpenClaw перевіряє reachable local provider endpoints для налаштованих провайдерів api: "ollama" і api: "openai-completions", у яких baseUrl є loopback, private-network або .local. Якщо цей endpoint не працює, запуск записується як skipped з чіткою provider/model error замість початку model call. Endpoint result кешується на 5 хвилин, тому багато due jobs, що використовують той самий недоступний локальний сервер Ollama, vLLM, SGLang або LM Studio, ділять одну невелику перевірку замість створення request storm. Skipped provider-preflight runs не збільшують execution-error backoff; увімкніть failureAlert.includeSkipped, якщо хочете повторні skip notifications.

# Доставка й результат

Використовуйте --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.

Коли доставка оголошення використовує 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, webhook і none керують лише тим, що runner робить із фінальною відповіддю після ходу агента.

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

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

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

• cron.failureDestination задає глобальне типове значення для сповіщень про помилки.
• job.delivery.failureDestination перевизначає його для окремого завдання.
• Якщо жодне не задано і завдання вже доставляє через 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 endpoint-и для зовнішніх тригерів. Увімкніть у config:

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

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

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

• 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 [email protected]

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

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

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

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

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

gcloud pubsub topics create gog-gmail-watch
gcloud 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 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

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

{
  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 внутрішньо використовують виділену execution lane черги cron-nested, тому збільшення цього значення дозволяє незалежним cron LLM-запускам просуватися паралельно, а не лише запускати їхні зовнішні cron wrappers. Спільна не-cron lane nested цим параметром не розширюється.

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

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

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

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

# Драбина команд

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
• Heartbeat — періодичні ходи основного сеансу
• Часовий пояс — конфігурація часового поясу