openclaw cron

Керуйте завданнями Cron для планувальника Gateway.

Швидке створення завдань

openclaw cron create — це псевдонім для openclaw cron add. Для нових завдань спочатку вкажіть розклад, а потім запит:

openclaw cron create "0 7 * * *" \  "Підсумуй оновлення за ніч." \  --name "Ранковий огляд" \  --agent ops

Використовуйте --webhook <url>, якщо завдання має надіслати готове корисне навантаження запитом POST, а не доставити його до цільового чату:

openclaw cron create "0 18 * * 1-5" \  "Підсумуй сьогоднішні розгортання у форматі JSON." \  --name "Огляд розгортань" \  --webhook "https://example.invalid/openclaw/cron"

Використовуйте --command для детермінованих завдань у стилі оболонки, які виконуються всередині Cron OpenClaw без запуску ізольованого виконання агента або моделі:

openclaw cron create "*/15 * * * *" \  --name "Перевірка глибини черги" \  --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. Командні завдання перехоплюють stdout/stderr, записують звичайну історію Cron і спрямовують вивід через ті самі режими доставки announce, webhook або none, що й ізольовані завдання. Команда, яка виводить лише NO_REPLY, не надсилається.

Сеанси

--session приймає main, isolated, current або session:<id>.

Доставка

openclaw cron list і openclaw cron show <job-id> показують попередній перегляд визначеного маршруту доставки. Для channel: "last" попередній перегляд показує, чи маршрут визначено з основного або поточного сеансу, чи операція завершиться безпечною відмовою.

Цілі з префіксом постачальника можуть усувати неоднозначність невизначених каналів оголошень. Наприклад, to: "telegram:123" вибирає Telegram, коли delivery.channel не вказано або задано last. Селекторами постачальників є лише префікси, оголошені завантаженим Plugin. Якщо delivery.channel вказано явно, префікс має відповідати цьому каналу; channel: "whatsapp" разом із to: "telegram:123" відхиляється. Службові префікси, як-от imessage: і sms:, залишаються синтаксисом цілі, яким керує канал.

Відповідальність за доставку

Доставка ізольованого чату Cron розподіляється між агентом і засобом виконання:

• Агент може надсилати безпосередньо за допомогою інструмента message, коли доступний маршрут чату.
• Резервний механізм announce доставляє остаточну відповідь лише тоді, коли агент не надіслав її безпосередньо до визначеної цілі.
• webhook надсилає готове корисне навантаження за URL-адресою.
• none вимикає резервну доставку засобом виконання.

Використовуйте cron add|create --webhook <url> або cron edit <job-id> --webhook <url>, щоб налаштувати доставку через Webhook. Не поєднуйте --webhook із прапорцями доставки до чату, як-от --announce, --no-deliver, --channel, --to, --thread-id або --account.

cron edit <job-id> може скасувати окремі поля маршрутизації доставки за допомогою --clear-channel, --clear-to, --clear-thread-id і --clear-account (кожне з них відхиляється в поєднанні з відповідним прапорцем установлення). На відміну від --no-deliver, який лише вимикає резервну доставку засобом виконання, ці параметри видаляють збережене поле, тож завдання знову визначає цю частину маршруту з типових значень.

--announce — це резервна доставка остаточної відповіді засобом виконання. --no-deliver вимикає цей резервний механізм, але не видаляє інструмент message агента, коли доступний маршрут чату.

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

Доставка сповіщень про помилки

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

1. delivery.failureDestination у завданні.
2. Глобальний cron.failureDestination.
3. Основна ціль оголошення завдання (коли жоден із наведених вище варіантів не визначає конкретне місце призначення).

Ізольовані запуски Cron трактують помилки агента на рівні запуску як помилки завдання, навіть коли корисне навантаження відповіді не створено, тому помилки моделі або постачальника все одно збільшують лічильники помилок і активують сповіщення про помилки.

Командні завдання Cron не запускають ізольований хід агента. Нульовий код завершення записує ok; ненульовий код завершення, сигнал, перевищення часу очікування або перевищення часу очікування без виводу записує error і може активувати той самий шлях сповіщення про помилки.

Якщо час очікування ізольованого запуску спливає до першого запиту до моделі, openclaw cron show і openclaw cron runs містять помилку, специфічну для фази, як-от setup timed out before runner start, або повідомлення про зависання з назвою останньої відомої фази запуску (наприклад, context-engine). Для постачальників на базі CLI сторожовий таймер перед запитом до моделі залишається активним, доки не почнеться хід зовнішнього CLI, тому зависання під час пошуку сеансу, виконання перехоплювача, автентифікації, підготовки запиту й налаштування CLI реєструються як помилки Cron перед запитом до моделі.

Планування

Одноразові завдання

--at <datetime> планує одноразовий запуск. Дата й час без зміщення трактуються як UTC, якщо також не передано --tz <iana>, що інтерпретує місцевий час у вказаному часовому поясі.

Повторювані завдання

Повторювані завдання після послідовних помилок використовують експоненційну затримку повторних спроб: 30s, 1m, 5m, 15m, 60m. Розклад повертається до звичайного режиму після наступного успішного запуску.

Пропущені запуски відстежуються окремо від помилок виконання. Вони не впливають на затримку повторних спроб, але openclaw cron edit <job-id> --failure-alert-include-skipped може ввімкнути для сповіщень про помилки повторювані повідомлення про пропущені запуски.

Для ізольованих завдань, націлених на локального налаштованого постачальника моделей (базова URL-адреса в інтерфейсі зворотного зв’язку, приватній мережі або .local), Cron виконує полегшену попередню перевірку постачальника перед запуском ходу агента: постачальники api: "ollama" перевіряються за адресою /api/tags; інші локальні постачальники, сумісні з OpenAI (api: "openai-completions", наприклад vLLM, SGLang, LM Studio), перевіряються за адресою /models. Якщо кінцева точка недоступна, запуск записується як skipped і повторюється за наступним розкладом; результат перевірки доступності кешується окремо для кожної кінцевої точки протягом 5 хвилин, щоб численні завдання, спрямовані до одного локального сервера, не перевантажували його повторними перевірками.

Завдання Cron, стан очікування середовища виконання й історія запусків зберігаються у спільній базі даних стану SQLite. Застарілі файли jobs.json, <name>-state.json і runs/*.jsonl імпортуються один раз і перейменовуються із суфіксом .migrated. Після імпорту редагуйте розклади за допомогою openclaw cron add|edit|remove, а не шляхом редагування файлів JSON.

Ручні запуски

openclaw cron run <job-id> типово запускає примусово й повертає результат одразу після додавання ручного запуску до черги. Успішні відповіді містять { ok: true, enqueued: true, runId }. Використовуйте повернений runId, щоб пізніше переглянути результат:

openclaw cron run <job-id>openclaw cron runs --id <job-id> --run-id <run-id>

Додайте --wait, якщо сценарій має блокуватися, доки саме цей поставлений у чергу запуск не отримає кінцевий стан:

openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s

З --wait CLI усе одно спочатку викликає cron.run, а потім опитує cron.runs щодо поверненого runId. Команда завершується з кодом 0 лише тоді, коли запуск завершується зі станом ok. Вона завершується з ненульовим кодом, коли запуск завершується зі станом error або skipped, коли відповідь Gateway не містить runId або коли спливає --wait-timeout (типово 10m, з опитуванням кожні 2s за замовчуванням). --poll-interval має бути більшим за нуль.

Моделі

cron add|edit --model <ref> вибирає дозволену модель для завдання. cron add|edit --fallbacks <list> задає резервні моделі для окремого завдання, наприклад --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5; передайте --fallbacks "" для суворого запуску без резервних моделей. cron edit <job-id> --clear-fallbacks видаляє перевизначення резервних моделей для окремого завдання. cron edit <job-id> --clear-model видаляє перевизначення моделі для окремого завдання, щоб завдання дотримувалося звичайного пріоритету вибору моделі Cron (збережене перевизначення сеансу Cron, якщо воно є, інакше модель агента або типова модель); цей параметр не можна поєднувати з --model. cron add|edit --thinking <level> задає перевизначення режиму міркування для окремого завдання; cron edit <job-id> --clear-thinking видаляє його, щоб завдання дотримувалося звичайного пріоритету режиму міркування Cron, і цей параметр не можна поєднувати з --thinking.

--model Cron — це основна модель завдання, а не перевизначення /model сеансу чату. Це означає:

• Налаштовані резервні моделі й надалі застосовуються, коли вибрана модель завдання дає збій.
• fallbacks у корисному навантаженні окремого завдання замінює налаштований список резервних моделей, якщо його вказано.
• Порожній список резервних моделей для окремого завдання (--fallbacks "" або fallbacks: [] у корисному навантаженні завдання чи API) робить запуск Cron суворим.
• Якщо завдання має --model, але список резервних моделей не налаштовано, OpenClaw передає явне порожнє перевизначення резервних моделей, щоб основна модель агента не додавалася як прихована ціль повторної спроби.
• Попередні перевірки локального постачальника перебирають налаштовані резервні моделі, перш ніж позначити запуск Cron як skipped.

openclaw doctor повідомляє про завдання, у яких уже встановлено payload.model, зокрема про кількість за просторами імен постачальників і невідповідності agents.defaults.model. Використовуйте цю перевірку, коли поведінка автентифікації, постачальника або виставлення рахунків відрізняється між активним чатом і запланованими завданнями.

Пріоритет моделей ізольованого Cron

Ізольований Cron визначає активну модель у такому порядку:

1. Перевизначення перехоплювача Gmail.
2. --model для окремого завдання.
3. Збережене перевизначення моделі сеансу Cron (якщо користувач вибрав модель).
4. Модель агента або типова модель.

Швидкий режим

Ізольований швидкий режим Cron використовує визначений поточний вибір моделі. Конфігурація моделі params.fastMode застосовується за замовчуванням, але збережене перевизначення сеансу fastMode усе одно має пріоритет над конфігурацією. Коли визначеним режимом є auto, граничний час використовує значення params.fastAutoOnSeconds вибраної моделі, за замовчуванням — 60 секунд.

Повторні спроби після перемикання поточної моделі

Якщо ізольований запуск породжує LiveSessionModelSwitchError, Cron перед повторною спробою зберігає перемкнуті провайдер і модель (а також перевизначення перемкнутого профілю автентифікації, якщо воно наявне) для активного запуску. Зовнішній цикл повторних спроб обмежено двома спробами перемикання після початкової спроби, після чого виконання переривається замість нескінченного циклу.

Результати запуску та відмови

Приглушення застарілих підтверджень

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

Приглушення токена мовчання

Якщо ізольований запуск Cron повертає лише токен мовчання (NO_REPLY або no_reply), Cron приглушує як пряме вихідне доставлення, так і резервний шлях зведення в черзі, тому в чат нічого не надсилається.

Структуровані відмови

Ізольовані запуски Cron використовують структуровані метадані відмови у виконанні з вкладеного запуску (фатальні помилки інструмента виконання з кодом SYSTEM_RUN_DENIED або INVALID_REQUEST) як авторитетний сигнал відмови. Вони також враховують обгортки хоста Node UNAVAILABLE навколо вкладеної структурованої помилки, що містить один із цих кодів.

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

cron list та історія запусків показують причину відмови замість повідомлення про заблоковану команду як ok.

Зберігання

Поведінка зберігання:

• cron.sessionRetention (за замовчуванням 24h, або false для вимкнення) видаляє завершені сеанси ізольованих запусків.
• Історія запусків зберігає найновіші 2000 кінцевих рядків для кожного завдання Cron. Для втрачених рядків зберігається стандартне 24-годинне вікно очищення втрачених завдань.

Міграція старіших завдань

Поширені зміни

Оновіть налаштування доставлення, не змінюючи повідомлення:

openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

Вимкніть доставлення для ізольованого завдання:

openclaw cron edit <job-id> --no-deliver

Увімкніть полегшений початковий контекст для ізольованого завдання:

openclaw cron edit <job-id> --light-context

Надсилайте оголошення до певного каналу:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

Надсилайте оголошення до теми форуму Telegram:

openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

Створіть ізольоване завдання з полегшеним початковим контекстом:

openclaw cron create "0 7 * * *" \  "Підсумуй нічні оновлення." \  --name "Полегшений ранковий огляд" \  --session isolated \  --light-context \  --no-deliver

--light-context застосовується лише до ізольованих завдань кроку агента. Для запусків Cron полегшений режим залишає початковий контекст порожнім замість додавання повного набору початкового контексту робочого простору.

Створіть командне завдання з точними argv, cwd, env, stdin та обмеженнями результату:

openclaw cron create "*/30 * * * *" \  --name "Експорт позиції" \  --command-argv '["node","scripts/export-position.mjs"]' \  --command-cwd "/srv/app" \  --command-env "NODE_ENV=production" \  --command-input '{"mode":"summary"}' \  --timeout-seconds 120 \  --no-output-timeout-seconds 30 \  --output-max-bytes 65536 \  --webhook "https://example.invalid/openclaw/cron"

Поширені команди адміністрування

Ручний запуск і перевірка:

openclaw cron listopenclaw cron list --agent opsopenclaw cron get <job-id>openclaw cron show <job-id>openclaw cron run <job-id>openclaw cron run <job-id> --dueopenclaw cron run <job-id> --wait --wait-timeout 10mopenclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2sopenclaw cron runs --id <job-id> --limit 50openclaw cron runs --id <job-id> --run-id <run-id>

openclaw cron list за замовчуванням показує всі відповідні завдання. Передайте --agent <id>, щоб показати лише завдання, ефективний нормалізований ідентифікатор агента яких збігається; завдання без збереженого ідентифікатора агента вважаються такими, що належать налаштованому агенту за замовчуванням.

openclaw cron get <job-id> безпосередньо повертає збережений JSON завдання. Використовуйте cron show <job-id>, коли потрібне зручне для читання подання з попереднім переглядом маршруту доставлення.

cron list --json та cron show <job-id> --json містять поле верхнього рівня status для кожного завдання, обчислене на основі enabled, state.runningAtMs і state.lastRunStatus. Значення: disabled, running, ok, error, skipped або idle. Стан JSON залишається канонічним і без оформлення, щоб зовнішні інструменти могли читати стан завдання без повторного обчислення; у зрозумілому для людини результаті повторювані стани error можуть доповнюватися кількістю збоїв.

Записи cron runs містять діагностику доставлення із запланованою ціллю Cron, визначеною ціллю, надсиланнями через інструмент повідомлень, використанням резервного варіанта та станом доставлення.

Переналаштування агента та сеансу:

openclaw cron edit <job-id> --agent opsopenclaw cron edit <job-id> --clear-agentopenclaw cron edit <job-id> --session currentopenclaw cron edit <job-id> --session "session:daily-brief"

openclaw cron add попереджає, коли --agent пропущено в завданнях кроку агента, і використовує агента за замовчуванням (main). Передайте --agent <id> під час створення, щоб закріпити конкретного агента.

Коригування доставлення:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"openclaw cron edit <job-id> --webhook "https://example.invalid/openclaw/cron"openclaw cron edit <job-id> --best-effort-deliveropenclaw cron edit <job-id> --no-best-effort-deliveropenclaw cron edit <job-id> --no-deliver

Пов’язані матеріали

• Довідник CLI
• Заплановані завдання