openclaw cron

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

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

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

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --agent ops

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

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

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

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"]'. Командні завдання захоплюють 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 надсилає готове корисне навантаження методом POST на 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>, що інтерпретує місцевий час у заданому часовому поясі.

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

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

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

Для ізольованих завдань, націлених на налаштованого локального постачальника моделі (базова URL-адреса на local loopback, у приватній мережі або в .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.

Параметр Cron --model визначає основну модель завдання, а не перевизначення /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) як авторитетний сигнал відмови. Вони також враховують обгортки UNAVAILABLE від хоста Node навколо вкладеної структурованої помилки з одним із цих кодів.

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

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

Зберігання

Зберігання та очищення керуються в конфігурації:

• cron.sessionRetention (типове значення 24h; false вимикає цю функцію) очищає сеанси завершених ізольованих запусків.
• cron.runLog.keepLines (типове значення 2000) очищає збережені рядки історії запусків SQLite для кожного завдання. cron.runLog.maxBytes (типове значення 2000000) і надалі підтримується для сумісності зі старішими файловими журналами запусків; очищення SQLite ґрунтується на кількості рядків.

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

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

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

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 * * *" \  "Summarize overnight updates." \  --name "Lightweight morning brief" \  --session isolated \  --light-context \  --no-deliver

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

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

openclaw cron create "*/30 * * * *" \  --name "Position export" \  --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
• Заплановані завдання