diff --git a/docs/uk/automation/cron-jobs.md b/docs/uk/automation/cron-jobs.md index 375a3e7a6..ad796d42c 100644 --- a/docs/uk/automation/cron-jobs.md +++ b/docs/uk/automation/cron-jobs.md @@ -1,21 +1,21 @@ --- read_when: - Планування фонових завдань або пробуджень - - Підключення зовнішніх тригерів (вебхуків, Gmail) до OpenClaw + - Підключення зовнішніх тригерів (Webhook, Gmail) до OpenClaw - Вибір між Heartbeat і Cron для запланованих завдань sidebarTitle: Scheduled tasks -summary: Заплановані завдання, Webhook і тригери Gmail PubSub для планувальника Gateway +summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway title: Заплановані завдання x-i18n: - generated_at: "2026-04-29T08:22:12Z" + generated_at: "2026-04-29T15:58:21Z" model: gpt-5.5 provider: openai - source_hash: 0a3df95ee8680e49fa97373f8325eb348a817aad49ceae6c73547ae3fd294cf2 + source_hash: 021e623bdea786178e0948e9905360c897c26d31fdf866e9af8cfc9538968d60 source_path: automation/cron-jobs.md workflow: 16 --- -Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може доставляти результат назад у канал чату або кінцеву точку Webhook. +Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента у потрібний час і може доставляти результат назад у канал чату або кінцеву точку webhook. ## Швидкий старт @@ -47,39 +47,40 @@ Cron — це вбудований планувальник Gateway. Він зб ## Як працює cron - Cron працює **всередині процесу Gateway** (не всередині моделі). -- Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому розклади не втрачаються після перезапусків. +- Визначення завдань зберігаються в `~/.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 порівнює змінені поля розкладу з метаданими очікуваного слота виконання й очищає застарілі значення `nextRunAtMs`. Суто форматувальні переписування або переписування лише з іншим порядком ключів зберігають очікуваний слот. +- Після розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть вважати завдання новими, бо поля runtime тепер містяться в `jobs-state.json`. +- Коли `jobs.json` редагується під час роботи або зупинки Gateway, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного runtime-слота й очищує застарілі значення `nextRunAtMs`. Суто форматування або переписування лише порядку ключів зберігають очікуваний слот. - Усі виконання cron створюють записи [фонового завдання](/uk/automation/tasks). -- Під час запуску Gateway прострочені ізольовані завдання ходу агента переплановуються за межі вікна підключення каналу замість негайного повторного відтворення, тому запуск Discord/Telegram і налаштування нативних команд залишаються чутливими після перезапусків. +- Під час запуску Gateway прострочені ізольовані завдання agent-turn переплановуються за межі вікна підключення каналу, а не відтворюються негайно, тому запуск Discord/Telegram і налаштування нативних команд залишаються чуйними після перезапусків. - Одноразові завдання (`--at`) за замовчуванням автоматично видаляються після успішного виконання. -- Ізольовані запуски cron за можливості закривають відстежувані вкладки браузера/процеси для свого сеансу `cron:` після завершення запуску, щоб від’єднана автоматизація браузера не залишала осиротілі процеси. -- Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення стану (`on it`, `pulling everything together` і подібні підказки), а жоден дочірній субагентський запуск більше не відповідає за фінальну відповідь, OpenClaw один раз повторно запитує фактичний результат перед доставкою. -- Ізольовані запуски cron надають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім повертаються до відомих маркерів фінального підсумку/виводу, як-от `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблоковану команду не було повідомлено як успішний запуск. -- Ізольовані запуски cron також трактують помилки агента на рівні запуску як помилки завдання, навіть коли корисне навантаження відповіді не створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій замість очищення завдання як успішного. +- Ізольовані запуски cron за можливості закривають відстежувані вкладки/процеси браузера для свого сеансу `cron:` після завершення запуску, щоб від'єднана автоматизація браузера не залишала осиротілих процесів. +- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат є лише проміжним оновленням стану (`on it`, `pulling everything together` і подібні підказки), а жоден дочірній запуск субагента вже не відповідає за фінальну відповідь, OpenClaw один раз повторно запитує фактичний результат перед доставкою. +- Ізольовані запуски cron спершу віддають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім переходять до відомих маркерів фінального підсумку/виводу, таких як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не повідомлялася як успішний запуск. +- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть коли payload відповіді не створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій, а не очищують завдання як успішне. +- Коли ізольоване завдання agent-turn досягає `timeoutSeconds`, cron перериває базовий запуск агента й дає йому коротке вікно для очищення. Якщо запуск не завершує спорожнення, очищення, яким володіє Gateway, примусово очищує володіння сеансом цього запуску до того, як cron запише тайм-аут, щоб робота з черги чату не залишалася за застарілим сеансом обробки. -Узгодження завдань для cron спочатку належить середовищу виконання, а вже потім спирається на довготривалу історію: активне завдання cron залишається активним, доки середовище виконання cron все ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірнього сеансу все ще існує. Коли середовище виконання перестає володіти завданням і 5-хвилинне вікно відстрочки спливає, перевірки обслуговування переглядають збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця довготривала історія показує термінальний результат, реєстр завдань фіналізується на її основі; інакше обслуговування, що належить Gateway, може позначити завдання як `lost`. Офлайн-аудит CLI може відновитися з довготривалої історії, але він не трактує власний порожній набір активних завдань у процесі як доказ того, що запуск cron, який належить Gateway, зник. +Узгодження завдань для cron спершу належить runtime, а потім спирається на довготривалу історію: активне завдання cron залишається live, доки runtime cron ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірнього сеансу ще існує. Щойно runtime перестає володіти завданням і 5-хвилинне пільгове вікно спливає, обслуговування перевіряє збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця довготривала історія показує термінальний результат, журнал завдань фіналізується з нього; інакше обслуговування, яким володіє Gateway, може позначити завдання як `lost`. Офлайн-аудит CLI може відновлюватися з довготривалої історії, але він не трактує власний порожній in-process набір активних завдань як доказ того, що запуск cron, яким володіє Gateway, зник. ## Типи розкладів | Тип | Прапорець CLI | Опис | | ------- | ------------- | ------------------------------------------------------- | -| `at` | `--at` | Одноразова часова позначка (ISO 8601 або відносна, як `20m`) | +| `at` | `--at` | Одноразова позначка часу (ISO 8601 або відносна, як-от `20m`) | | `every` | `--every` | Фіксований інтервал | -| `cron` | `--cron` | 5-польовий або 6-польовий вираз cron з необов’язковим `--tz` | +| `cron` | `--cron` | 5-польовий або 6-польовий вираз cron з необов'язковим `--tz` | -Часові позначки без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом. +Позначки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом. -Повторювані вирази на початку години автоматично розносяться в межах до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна. +Повторювані вирази на початку години автоматично розподіляються з розкидом до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна. -### День місяця і день тижня використовують логіку OR +### День місяця й день тижня використовують логіку OR -Вирази Cron аналізуються за допомогою [croner](https://github.com/Hexagon/croner). Коли поля дня місяця і дня тижня обидва не є шаблонами, croner збігається, коли збігається **будь-яке** з полів, а не обидва. Це стандартна поведінка Vixie cron. +Вирази cron розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли поля дня місяця й дня тижня обидва не є шаблонами, croner збігається, коли збігається **будь-яке** з полів, а не обидва. Це стандартна поведінка Vixie cron. ``` # Intended: "9 AM on the 15th, only if it's a Monday" @@ -87,42 +88,42 @@ Cron — це вбудований планувальник Gateway. Він зб 0 9 15 * 1 ``` -Це спрацьовує приблизно 5-6 разів на місяць замість 0-1 разу на місяць. OpenClaw тут використовує стандартну поведінку OR від Croner. Щоб вимагати обидві умови, використовуйте модифікатор дня тижня `+` від Croner (`0 9 15 * +1`) або плануйте за одним полем і перевіряйте інше в підказці чи команді вашого завдання. +Це спрацьовує приблизно 5-6 разів на місяць замість 0-1 разу на місяць. OpenClaw тут використовує стандартну поведінку OR від Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` від Croner (`0 9 15 * +1`) або плануйте за одним полем і перевіряйте інше у prompt чи команді завдання. ## Стилі виконання -| Стиль | Значення `--session` | Виконується в | Найкраще для | -| --------------- | -------------------- | -------------------------- | ------------------------------- | -| Основний сеанс | `main` | Наступний хід Heartbeat | Нагадування, системні події | -| Ізольований | `isolated` | Виділений `cron:` | Звіти, фонові справи | -| Поточний сеанс | `current` | Прив’язується під час створення | Періодична робота з урахуванням контексту | -| Користувацький сеанс | `session:custom-id` | Постійний іменований сеанс | Робочі процеси, що спираються на історію | +| Стиль | Значення `--session` | Виконується в | Найкраще для | +| --------------- | -------------------- | ------------------------- | ------------------------------- | +| Основний сеанс | `main` | Наступний heartbeat turn | Нагадування, системні події | +| Ізольований | `isolated` | Виділений `cron:` | Звіти, фонові службові роботи | +| Поточний сеанс | `current` | Прив'язаний під час створення | Періодична робота з урахуванням контексту | +| Власний сеанс | `session:custom-id` | Постійний іменований сеанс | Робочі процеси, що спираються на історію | - - Завдання **основного сеансу** ставлять у чергу системну подію та необов’язково пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують свіжість щоденного/неактивного скидання для цільового сеансу. **Ізольовані** завдання виконують виділений хід агента зі свіжим сеансом. **Користувацькі сеанси** (`session:xxx`) зберігають контекст між запусками, уможливлюючи робочі процеси на кшталт щоденних стендапів, що спираються на попередні підсумки. + + Завдання **основного сеансу** ставлять системну подію в чергу й за потреби пробуджують heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують свіжість щоденного/idle-скидання для цільового сеансу. **Ізольовані** завдання виконують виділений agent turn зі свіжим сеансом. **Власні сеанси** (`session:xxx`) зберігають контекст між запусками, уможливлюючи робочі процеси на кшталт щоденних стендапів, що спираються на попередні підсумки. - Для ізольованих завдань «свіжий сеанс» означає новий ідентифікатор стенограми/сеансу для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення моделі/автентифікації, але не успадковує навколишній контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання або черги, підвищення прав, походження чи прив’язку середовища виконання ACP. Використовуйте `current` або `session:`, коли періодичне завдання має навмисно спиратися на той самий контекст розмови. + Для ізольованих завдань «свіжий сеанс» означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явні вибрані користувачем перевизначення моделі/автентифікації, але не успадковує навколишній контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання або черги, підвищення, origin чи прив'язку ACP runtime. Використовуйте `current` або `session:`, коли повторюване завдання має навмисно спиратися на той самий контекст розмови. - - Для ізольованих завдань завершення середовища виконання тепер включає best-effort очищення браузера для цього сеансу cron. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет. + + Для ізольованих завдань демонтаж runtime тепер включає best-effort очищення браузера для цього сеансу cron. Помилки очищення ігноруються, щоб фактичний результат cron все одно мав пріоритет. - Ізольовані запуски cron також звільняють усі вбудовані екземпляри середовища виконання MCP, створені для завдання, через спільний шлях очищення середовища виконання. Це відповідає тому, як завершуються MCP-клієнти основного сеансу та користувацького сеансу, тож ізольовані завдання cron не залишають stdio дочірні процеси або довготривалі MCP-з’єднання між запусками. + Ізольовані запуски cron також утилізують будь-які bundled MCP runtime instances, створені для завдання, через спільний шлях runtime-cleanup. Це відповідає тому, як демонтуються MCP-клієнти основного сеансу й власного сеансу, тому ізольовані завдання cron не залишають stdio дочірні процеси або довгоживучі MCP-з'єднання між запусками. - Коли ізольовані запуски cron оркеструють субагентів, доставка також надає перевагу фінальному виводу нащадка над застарілим проміжним текстом батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його. + Коли ізольовані запуски cron оркеструють субагентів, доставка також віддає перевагу фінальному виводу нащадка над застарілим проміжним текстом батьківського запуску. Якщо нащадки ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського запуску замість того, щоб оголошувати його. - Для текстових цілей оголошень Discord OpenClaw надсилає канонічний фінальний текст асистента один раз замість повторного відтворення і потокових/проміжних текстових корисних навантажень, і фінальної відповіді. Медіа та структуровані корисні навантаження Discord усе ще доставляються як окремі корисні навантаження, щоб вкладення й компоненти не було втрачено. + Для текстових цілей оголошення Discord OpenClaw надсилає канонічний фінальний текст асистента один раз замість повторного відтворення і streamed/intermediate текстових payload, і фінальної відповіді. Медіа та структуровані payload Discord все ще доставляються як окремі payload, щоб вкладення й компоненти не губилися. -### Параметри корисного навантаження для ізольованих завдань +### Параметри payload для ізольованих завдань - Текст підказки (обов’язковий для ізольованих). + Текст prompt (обов'язковий для ізольованого). Перевизначення моделі; використовує вибрану дозволену модель для завдання. @@ -131,55 +132,55 @@ Cron — це вбудований планувальник Gateway. Він зб Перевизначення рівня thinking. - Пропустити впровадження файлів початкового налаштування робочої області. + Пропустити ін'єкцію bootstrap-файла робочої області. Обмежити, які інструменти може використовувати завдання, наприклад `--tools exec,read`. -`--model` використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення `/model` у чат-сеансі: налаштовані ланцюжки резервних варіантів усе ще застосовуються, коли основна модель завдання зазнає збою. Якщо запитана модель не дозволена або її неможливо визначити, cron завершує запуск помилкою з явною помилкою валідації замість тихого повернення до вибору моделі агента/стандартної моделі завдання. +`--model` використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення `/model` сеансу чату: налаштовані ланцюжки fallback все ще застосовуються, коли основна модель завдання зазнає збою. Якщо запитана модель не дозволена або не може бути визначена, cron завершує запуск із явною помилкою валідації замість тихого fallback до вибору моделі агента/за замовчуванням для завдання. -Завдання Cron також можуть містити `fallbacks` на рівні корисного навантаження. Якщо вони присутні, цей список замінює налаштований ланцюжок резервних варіантів для завдання. Використовуйте `fallbacks: []` у корисному навантаженні/API завдання, коли потрібен строгий запуск cron, який пробує лише вибрану модель. Якщо завдання має `--model`, але не має ні резервних варіантів у корисному навантаженні, ні налаштованих резервних варіантів, OpenClaw передає явне порожнє перевизначення резервних варіантів, щоб основна модель агента не додавалася як прихована додаткова ціль повторної спроби. +Завдання Cron також можуть містити `fallbacks` на рівні payload. Коли він присутній, цей список замінює налаштований ланцюжок fallback для завдання. Використовуйте `fallbacks: []` у payload/API завдання, коли потрібен строгий запуск cron, який пробує лише вибрану модель. Якщо завдання має `--model`, але не має fallback ні в payload, ні в конфігурації, OpenClaw передає явне порожнє перевизначення fallback, щоб основна модель агента не додавалася як прихована додаткова ціль повторної спроби. Пріоритет вибору моделі для ізольованих завдань: -1. Перевизначення моделі Gmail-хука (коли запуск прийшов із Gmail і це перевизначення дозволене) -2. `model` у корисному навантаженні окремого завдання -3. Збережене користувачем перевизначення моделі сеансу cron -4. Вибір моделі агента/стандартної моделі +1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) +2. `model` у payload конкретного завдання +3. Збережене вибране користувачем перевизначення моделі сеансу cron +4. Вибір моделі агента/за замовчуванням -Швидкий режим також відповідає визначеному живому вибору. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron використовує це за замовчуванням. Збережене перевизначення `fastMode` сеансу все ще має пріоритет над конфігурацією в будь-якому напрямку. +Fast mode також наслідує resolved live selection. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron використовує це за замовчуванням. Збережене перевизначення `fastMode` сеансу все одно має пріоритет над конфігурацією в будь-якому напрямку. -Якщо ізольований запуск натрапляє на живу передачу перемикання моделі, cron повторює спробу з перемкненим провайдером/моделлю та зберігає цей живий вибір для активного запуску перед повторною спробою. Коли перемикання також містить новий профіль автентифікації, cron також зберігає це перевизначення профілю автентифікації для активного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторні спроби перемикання cron переривається замість безкінечного циклу. +Якщо ізольований запуск потрапляє на live model-switch handoff, cron повторює спробу з перемкненим провайдером/моделлю і зберігає цей live selection для активного запуску перед повторною спробою. Коли перемикання також містить новий auth profile, cron також зберігає це перевизначення auth profile для активного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб перемикання cron переривається замість нескінченного циклу. -Перш ніж ізольований запуск cron увійде в runner агента, OpenClaw перевіряє досяжні локальні кінцеві точки провайдерів для налаштованих провайдерів `api: "ollama"` і `api: "openai-completions"`, чий `baseUrl` є local loopback, приватною мережею або `.local`. Якщо ця кінцева точка недоступна, запуск записується як `skipped` із чіткою помилкою провайдера/моделі замість запуску виклику моделі. Результат кінцевої точки кешується на 5 хвилин, тому багато належних до виконання завдань, які використовують той самий недоступний локальний сервер Ollama, vLLM, SGLang або LM Studio, ділять один малий зонд замість створення шквалу запитів. Пропущені запуски передперевірки провайдера не збільшують backoff помилок виконання; увімкніть `failureAlert.includeSkipped`, коли потрібні повторні сповіщення про пропуски. +Перед тим як ізольований запуск cron входить у runner агента, OpenClaw перевіряє доступні локальні кінцеві точки провайдерів для налаштованих провайдерів `api: "ollama"` і `api: "openai-completions"`, чий `baseUrl` є loopback, private-network або `.local`. Якщо ця кінцева точка не працює, запуск записується як `skipped` із чіткою помилкою провайдера/моделі замість початку виклику моделі. Результат кінцевої точки кешується на 5 хвилин, тому багато прострочених завдань, що використовують той самий непрацюючий локальний сервер Ollama, vLLM, SGLang або LM Studio, ділять одну невелику перевірку замість створення шторму запитів. Пропущені provider-preflight запуски не збільшують backoff помилок виконання; увімкніть `failureAlert.includeSkipped`, якщо хочете повторювані сповіщення про пропуск. -## Доставка і вивід +## Доставка й вивід -| Режим | Що відбувається | -| ---------- | ----------------------------------------------------------------- | -| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент не надіслав | -| `webhook` | POST корисне навантаження завершеної події на URL | -| `none` | Немає резервної доставки runner | +| Режим | Що відбувається | +| ---------- | ------------------------------------------------------------------ | +| `announce` | Fallback-доставляє фінальний текст до цілі, якщо агент не надіслав | +| `webhook` | POST payload події завершення на URL | +| `none` | Немає fallback-доставки runner | -Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`; прямі RPC/конфігураційні виклики також можуть передавати `delivery.threadId` як рядок або число. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ідентифікатор кімнати або форму `room:!room:server` з Matrix. +Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`; прямі виклики RPC/config також можуть передавати `delivery.threadId` як рядок або число. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ID кімнати або форму `room:!room:server` з Matrix. -Для ізольованих завдань доставлення в чат є спільним. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` керують лише тим, що runner робить із фінальною відповіддю після ходу агента. +Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` керують лише тим, що runner робить із фінальною відповіддю після ходу агента. -Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає чинну ціль живого доставлення для резервного маршруту оголошення. Внутрішні ключі сеансів можуть бути в нижньому регістрі; цілі доставлення провайдерів не реконструюються з цих ключів, коли доступний поточний контекст чату. +Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену поточну ціль доставки для резервного маршруту оголошення. Внутрішні ключі сесій можуть бути в нижньому регістрі; цілі доставки провайдера не реконструюються з цих ключів, коли доступний поточний контекст чату. -Сповіщення про помилки використовують окремий шлях призначення: +Сповіщення про збої використовують окремий шлях призначення: -- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про помилки. +- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про збої. - `job.delivery.failureDestination` перевизначає його для окремого завдання. -- Якщо не задано жодного з них, а завдання вже доставляється через `announce`, сповіщення про помилки тепер повертаються до цієї основної цілі оголошення. -- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставлення не `webhook`. -- `failureAlert.includeSkipped: true` вмикає для завдання або глобальної політики сповіщень cron повторювані сповіщення про пропущені запуски. Пропущені запуски зберігають окремий лічильник послідовних пропусків, тому вони не впливають на backoff помилок виконання. +- Якщо жодне з них не задано, а завдання вже доставляє через `announce`, сповіщення про збої тепер повертаються до цієї основної цілі оголошення. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`. +- `failureAlert.includeSkipped: true` вмикає для завдання або глобальної політики сповіщень cron повторні сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому вони не впливають на backoff помилок виконання. ## Приклади CLI - + ```bash openclaw cron add \ --name "Calendar check" \ @@ -189,7 +190,7 @@ Cron — це вбудований планувальник Gateway. Він зб --wake now ``` - + ```bash openclaw cron add \ --name "Morning brief" \ @@ -202,7 +203,7 @@ Cron — це вбудований планувальник Gateway. Він зб --to "channel:C1234567890" ``` - + ```bash openclaw cron add \ --name "Deep analysis" \ @@ -217,9 +218,9 @@ Cron — це вбудований планувальник Gateway. Він зб -## Webhook-и +## Webhooks -Gateway може надавати HTTP-ендпоїнти Webhook для зовнішніх тригерів. Увімкніть у конфігурації: +Gateway може відкривати HTTP Webhook-ендпоїнти для зовнішніх тригерів. Увімкніть у config: ```json5 { @@ -242,7 +243,7 @@ Gateway може надавати HTTP-ендпоїнти Webhook для зов - Додати системну подію в чергу для основного сеансу: + Додайте системну подію до черги для основної сесії: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -260,7 +261,7 @@ Gateway може надавати HTTP-ендпоїнти Webhook для зов - Запустити ізольований хід агента: + Запустіть ізольований хід агента: ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -272,48 +273,48 @@ Gateway може надавати HTTP-ендпоїнти Webhook для зов Поля: `message` (обов’язкове), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `fallbacks`, `thinking`, `timeoutSeconds`. - - Користувацькі імена hook розв’язуються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload-и на дії `wake` або `agent` за допомогою шаблонів чи перетворень коду. + + Власні назви hook розв’язуються через `hooks.mappings` у config. Mappings можуть перетворювати довільні payloads на дії `wake` або `agent` за допомогою шаблонів чи перетворень коду. -Тримайте ендпоїнти hook за loopback, tailnet або довіреним reverse proxy. +Тримайте hook-ендпоїнти за local loopback, tailnet або довіреним reverse proxy. -- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway. -- Тримайте `hooks.path` на окремому підшляху; `/` відхиляється. +- Використовуйте виділений токен hook; не перевикористовуйте токени автентифікації Gateway. +- Тримайте `hooks.path` на виділеному підшляху; `/` відхиляється. - Задайте `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. -- Тримайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сеанси, вибрані викликачем. -- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сеансів. -- Payload-и hook типово обгортаються межами безпеки. +- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. +- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесій. +- Payloads hook за замовчуванням обгортаються межами безпеки. ## Інтеграція Gmail PubSub -Під’єднайте тригери вхідної пошти Gmail до OpenClaw через Google PubSub. +Під’єднайте тригери вхідної скриньки Gmail до OpenClaw через Google PubSub. **Передумови:** CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS-ендпоїнта. -### Налаштування через майстер (рекомендовано) +### Налаштування майстром (рекомендовано) ```bash openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push-ендпоїнта. +Це записує 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`, щоб відмовитися. +Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway запускає `gog gmail watch serve` під час завантаження та автоматично поновлює watch. Задайте `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися. ### Ручне одноразове налаштування - - Виберіть проєкт GCP, якому належить OAuth-клієнт, що використовується `gog`: + + Виберіть проєкт GCP, якому належить клієнт OAuth, що використовується `gog`: ```bash gcloud auth login @@ -322,7 +323,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com ``` - + ```bash gcloud pubsub topics create gog-gmail-watch gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ @@ -330,7 +331,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com --role=roles/pubsub.publisher ``` - + ```bash gog gmail watch start \ --account openclaw@gmail.com \ @@ -386,11 +387,11 @@ openclaw cron edit --clear-agent Примітка щодо перевизначення моделі: - `openclaw cron add|edit --model ...` змінює вибрану модель завдання. -- Якщо модель дозволена, цей точний провайдер/модель доходить до ізольованого запуску агента. -- Якщо вона не дозволена або її неможливо розв’язати, cron завершує запуск помилкою з явною помилкою валідації. -- Налаштовані ланцюжки fallback і далі застосовуються, бо cron `--model` є основною моделлю завдання, а не перевизначенням `/model` сеансу. -- Payload `fallbacks` замінює налаштовані fallback-и для цього завдання; `fallbacks: []` вимикає fallback і робить запуск строгим. -- Простий `--model` без явного або налаштованого списку fallback не переходить до основної моделі агента як мовчазної додаткової цілі повторної спроби. +- Якщо модель дозволена, точний provider/model доходить до ізольованого запуску агента. +- Якщо вона не дозволена або не може бути розв’язана, cron завершує запуск з явною помилкою валідації. +- Налаштовані fallback chains усе ще застосовуються, бо cron `--model` є основним значенням завдання, а не перевизначенням сесії `/model`. +- Payload `fallbacks` замінює налаштовані fallbacks для цього завдання; `fallbacks: []` вимикає fallback і робить запуск строгим. +- Звичайний `--model` без явного або налаштованого списку fallback не переходить до основної моделі агента як мовчазна додаткова ціль повторної спроби. @@ -414,29 +415,29 @@ openclaw cron edit --clear-agent } ``` -`maxConcurrentRuns` обмежує як заплановане dispatch cron, так і виконання ізольованих ходів агента. Ізольовані ходи cron-агента внутрішньо використовують виділену смугу виконання черги `cron-nested`, тому збільшення цього значення дає незалежним cron-запускам LLM просуватися паралельно, а не лише запускати їхні зовнішні cron-обгортки. Спільна не-cron смуга `nested` цим налаштуванням не розширюється. +`maxConcurrentRuns` обмежує як диспетчеризацію запланованих cron, так і виконання ізольованого ходу агента. Ізольовані ходи cron-агента внутрішньо використовують виділену смугу виконання черги `cron-nested`, тому збільшення цього значення дає змогу незалежним cron-запускам LLM просуватися паралельно, а не лише запускати їхні зовнішні cron-обгортки. Спільна не-cron смуга `nested` цим налаштуванням не розширюється. -Допоміжний файл стану runtime виводиться з `cron.store`: сховище `.json`, як-от `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, тоді як шлях сховища без суфікса `.json` додає `-state.json`. +Sidecar стану runtime виводиться з `cron.store`: сховище `.json`, як-от `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а шлях сховища без суфікса `.json` додає `-state.json`. -Якщо ви вручну редагуєте `jobs.json`, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей допоміжний файл для pending slots, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка повідомляє scheduler, коли зовнішньо відредагованому завданню потрібен новий `nextRunAtMs`. +Якщо ви вручну редагуєте `jobs.json`, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для pending slots, active markers, метаданих останнього запуску та ідентичності розкладу, яка повідомляє scheduler, коли зовнішньо відредаговане завдання потребує нового `nextRunAtMs`. Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. - - **Повторна спроба one-shot**: тимчасові помилки (ліміт частоти, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикають негайно. + + **Повторна спроба одноразового завдання**: тимчасові помилки (ліміт частоти, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикають негайно. - **Повторна спроба recurring**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску. + **Повторна спроба повторюваного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску. - - `cron.sessionRetention` (типово `24h`) очищає записи ізольованих сеансів запуску. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналів запусків. + + `cron.sessionRetention` (за замовчуванням `24h`) очищує записи ізольованих run-session. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищують файли run-log. ## Усунення несправностей -### Послідовність команд +### Сходи команд ```bash openclaw status @@ -450,39 +451,39 @@ openclaw doctor ``` - + - Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`. - Переконайтеся, що Gateway працює безперервно. - - Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста. - - `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено командою `openclaw cron run --due`, і строк виконання завдання ще не настав. + - Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом host. + - `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due`, і час завдання ще не настав. - - - Режим доставлення `none` означає, що резервне надсилання runner не очікується. Агент усе ще може надсилати напряму за допомогою інструмента `message`, коли доступний маршрут чату. - - Відсутня/недійсна ціль доставлення (`channel`/`to`) означає, що вихідне повідомлення було пропущено. - - Для Matrix скопійовані або legacy завдання з ідентифікаторами кімнат `delivery.to` у нижньому регістрі можуть не спрацювати, бо ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання до точного значення `!room:server` або `room:!room:server` з Matrix. - - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставлення заблоковано обліковими даними. - - Якщо ізольований запуск повертає лише silent token (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне доставлення, а також пригнічує резервний шлях queued summary, тому нічого не надсилається назад у чат. - - Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль). + + - Режим доставки `none` означає, що резервне надсилання runner не очікується. Агент усе ще може надсилати напряму через інструмент `message`, коли доступний маршрут чату. + - Відсутня/недійсна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено. + - Для Matrix скопійовані або legacy завдання з ідентифікаторами кімнат `delivery.to` у нижньому регістрі можуть завершуватися помилкою, бо ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання до точного значення `!room:server` або `room:!room:server` з Matrix. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку заблоковано обліковими даними. + - Якщо ізольований запуск повертає лише мовчазний токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також пригнічує резервний шлях зведення в черзі, тому в чат нічого не публікується. + - Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` з попереднім чатом або явний канал/ціль). - - - Актуальність щоденного та idle reset не базується на `updatedAt`; див. [Керування сеансами](/uk/concepts/session#session-lifecycle). - - Wakeup-и cron, запуски heartbeat, exec-сповіщення та службові записи gateway можуть оновлювати рядок сеансу для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`. - - Для legacy рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сеансу transcript JSONL, коли файл ще доступний. Legacy idle rows без `lastInteractionAt` використовують цей відновлений час початку як свій idle baseline. + + - Свіжість щоденного та неактивного скидання не базується на `updatedAt`; див. [Керування сеансами](/uk/concepts/session#session-lifecycle). + - Пробудження Cron, запуски heartbeat, сповіщення exec і службові оновлення gateway можуть оновлювати рядок сеансу для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`. + - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сеансу transcript JSONL, якщо файл досі доступний. Застарілі неактивні рядки без `lastInteractionAt` використовують цей відновлений час початку як базовий рівень неактивності. - Cron без `--tz` використовує часовий пояс хоста gateway. - Розклади `at` без часового поясу трактуються як UTC. - - Heartbeat `activeHours` використовує налаштоване розв’язання часового поясу. + - Heartbeat `activeHours` використовує налаштоване визначення часового поясу. ## Пов’язане -- [Автоматизація й завдання](/uk/automation) — короткий огляд усіх механізмів автоматизації -- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань Cron +- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації стисло +- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron - [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основного сеансу - [Часовий пояс](/uk/concepts/timezone) — налаштування часового поясу diff --git a/docs/uk/concepts/agent-loop.md b/docs/uk/concepts/agent-loop.md index 127fb8860..97a015b97 100644 --- a/docs/uk/concepts/agent-loop.md +++ b/docs/uk/concepts/agent-loop.md @@ -1,177 +1,178 @@ --- read_when: - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу - - Ви змінюєте постановку сеансів у чергу, запис транскриптів або поведінку блокування запису сеансу + - Ви змінюєте постановку сеансів у чергу, операції запису транскриптів або поведінку блокування запису сеансу summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: - generated_at: "2026-04-28T20:11:20Z" + generated_at: "2026-04-29T15:58:15Z" model: gpt-5.5 provider: openai - source_hash: 3f870abbd9ce724e04b32dfe6296ef0df10ebd5cc6d37492457dc77dfb868b8f + source_hash: 902d543bd71dd517a810d825cbe92e244fe89230f47eeada72477c657a2bec32 source_path: concepts/agent-loop.md workflow: 16 --- -Агентний цикл — це повний “реальний” запуск агента: приймання → збирання контексту → інференс моделі → +Агентний цикл — це повний «реальний» запуск агента: приймання → збирання контексту → інференс моделі → виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення -на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сеансу. +на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сесії. -В OpenClaw цикл — це один серіалізований запуск на сеанс, який генерує події життєвого циклу та потоку, -поки модель міркує, викликає інструменти й потоково видає результат. У цьому документі пояснено, як цей автентичний цикл -з’єднаний наскрізно. +В OpenClaw цикл — це один серіалізований запуск на сесію, який видає події життєвого циклу та потоку, +поки модель думає, викликає інструменти й транслює вивід. У цьому документі пояснено, як цей справжній цикл +зв’язаний наскрізно. ## Точки входу - Gateway RPC: `agent` і `agent.wait`. - CLI: команда `agent`. -## Як це працює (загальний огляд) +## Як це працює (на високому рівні) -1. RPC `agent` перевіряє параметри, визначає сеанс (sessionKey/sessionId), зберігає метадані сеансу, одразу повертає `{ runId, acceptedAt }`. +1. `agent` RPC перевіряє параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії, негайно повертає `{ runId, acceptedAt }`. 2. `agentCommand` запускає агента: - - визначає модель + стандартні значення thinking/verbose/trace + - визначає модель + типові значення thinking/verbose/trace - завантажує знімок Skills - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core) - - генерує **завершення/помилку життєвого циклу**, якщо вбудований цикл не згенерує їх сам + - видає **lifecycle end/error**, якщо вбудований цикл цього не видає 3. `runEmbeddedPiAgent`: - - серіалізує запуски через посеансові + глобальні черги - - визначає модель + профіль автентифікації та створює сеанс pi - - підписується на події pi й потоково передає дельти асистента/інструментів + - серіалізує запуски через черги на рівні сесії та глобальні черги + - визначає модель + профіль автентифікації та будує сесію pi + - підписується на події pi і транслює дельти assistant/tool - застосовує тайм-аут -> перериває запуск у разі перевищення - повертає payload-и + метадані використання -4. `subscribeEmbeddedPiSession` мостить події pi-agent-core до потоку OpenClaw `agent`: +4. `subscribeEmbeddedPiSession` зв’язує події pi-agent-core з потоком OpenClaw `agent`: - події інструментів => `stream: "tool"` - дельти асистента => `stream: "assistant"` - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` використовує `waitForAgentRun`: - - чекає **завершення/помилки життєвого циклу** для `runId` + - чекає на **lifecycle end/error** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Черги + паралельність -- Запуски серіалізуються за ключем сеансу (лінія сеансу) й опціонально через глобальну лінію. -- Це запобігає перегонам інструментів/сеансів і підтримує узгоджену історію сеансу. -- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які передаються до цієї системи ліній. +- Запуски серіалізуються за ключем сесії (сесійна смуга) і, за потреби, через глобальну смугу. +- Це запобігає гонкам інструментів/сесії та підтримує узгоджену історію сесії. +- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему смуг. Див. [Черга команд](/uk/concepts/queue). -- Записи транскрипту також захищені блокуванням запису сеансу на файлі сеансу. Блокування - враховує процеси та базується на файлі, тому воно ловить записувачів, які обходять внутрішньопроцесну чергу або приходять +- Записи транскрипту також захищені сесійним блокуванням запису у файл сесії. Блокування + враховує процеси та базується на файлах, тому воно виявляє записувачів, які обходять внутрішньопроцесну чергу або надходять з іншого процесу. -- Блокування запису сеансу за замовчуванням нерекурсивні. Якщо helper навмисно вкладає отримання +- Сесійні блокування запису за замовчуванням не є реентерабельними. Якщо допоміжний компонент навмисно вкладає отримання того самого блокування, зберігаючи одного логічного записувача, він має явно ввімкнути це через `allowReentrant: true`. -## Підготовка сеансу + робочого простору +## Підготовка сесії + робочої області -- Робочий простір визначається й створюється; sandbox-запуски можуть перенаправлятися до кореня sandbox-робочого простору. -- Skills завантажуються (або повторно використовуються зі знімка) та інжектяться в env і prompt. -- Bootstrap/context-файли визначаються й інжектяться у звіт системного prompt-а. -- Отримується блокування запису сеансу; `SessionManager` відкривається й готується до потокової передачі. Будь-який - подальший шлях переписування транскрипту, Compaction або скорочення має взяти те саме блокування перед відкриттям або +- Робоча область визначається та створюється; запуски в sandbox можуть перенаправлятися до кореня робочої області sandbox. +- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt. +- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt. +- Отримується сесійне блокування запису; `SessionManager` відкривається та готується перед потоковою передачею. Будь-який + подальший шлях перезапису транскрипту, Compaction або обрізання має отримати те саме блокування перед відкриттям або зміною файлу транскрипту. -## Збирання prompt-а + системний prompt +## Збирання prompt + системний prompt -- Системний prompt будується з базового prompt-а OpenClaw, prompt-а Skills, bootstrap-контексту та перевизначень для запуску. -- Застосовуються модельно-специфічні ліміти та резерв токенів для Compaction. -- Див. [Системний prompt](/uk/concepts/system-prompt), щоб зрозуміти, що бачить модель. +- Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для окремого запуску. +- Застосовуються обмеження, специфічні для моделі, і резерв токенів для Compaction. +- Див. [Системний prompt](/uk/concepts/system-prompt), щоб дізнатися, що бачить модель. -## Точки hook-ів (де можна перехоплювати) +## Точки hook (де можна перехопити) -OpenClaw має дві системи hook-ів: +OpenClaw має дві системи hook: -- **Внутрішні hook-и** (hook-и Gateway): подієві скрипти для команд і подій життєвого циклу. -- **Hook-и Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. +- **Внутрішні hooks** (Gateway hooks): скрипти, керовані подіями, для команд і подій життєвого циклу. +- **Plugin hooks**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway. -### Внутрішні hook-и (hook-и Gateway) +### Внутрішні hooks (Gateway hooks) -- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt-а. +- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt. Використовуйте це, щоб додавати/видаляти файли bootstrap-контексту. -- **Hook-и команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію про hook-и). +- **Command hooks**: `/new`, `/reset`, `/stop` та інші події команд (див. документ Hooks). -Див. [Hook-и](/uk/automation/hooks) для налаштування та прикладів. +Див. [Hooks](/uk/automation/hooks) для налаштування та прикладів. -### Hook-и Plugin (життєвий цикл агента + gateway) +### Plugin hooks (життєвий цикл агента + gateway) Вони виконуються всередині циклу агента або конвеєра gateway: -- **`before_model_resolve`**: виконується до сеансу (без `messages`), щоб детерміновано перевизначити provider/model перед визначенням моделі. -- **`before_prompt_build`**: виконується після завантаження сеансу (з `messages`), щоб інжектити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt-а. Використовуйте `prependContext` для динамічного тексту на хід і поля системного контексту для стабільних настанов, які мають бути в просторі системного prompt-а. -- **`before_agent_start`**: застарілий hook сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним hook-ам вище. -- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, дозволяючи Plugin забрати хід і повернути синтетичну відповідь або повністю приглушити хід. +- **`before_model_resolve`**: виконується до сесії (без `messages`), щоб детерміновано перевизначити provider/model перед визначенням моделі. +- **`before_prompt_build`**: виконується після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на окремий хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного prompt. +- **`before_agent_start`**: застарілий hook сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним hooks вище. +- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, даючи Plugin можливість забрати хід і повернути синтетичну відповідь або повністю заглушити хід. - **`agent_end`**: перевіряє фінальний список повідомлень і метадані запуску після завершення. -- **`before_compaction` / `after_compaction`**: спостерігають або анотують цикли Compaction. +- **`before_compaction` / `after_compaction`**: спостерігають за циклами Compaction або анотують їх. - **`before_tool_call` / `after_tool_call`**: перехоплюють параметри/результати інструментів. -- **`before_install`**: перевіряє вбудовані результати сканування та опціонально блокує встановлення skill або Plugin. -- **`tool_result_persist`**: синхронно трансформує результати інструментів перед записом у транскрипт сеансу, який належить OpenClaw. -- **`message_received` / `message_sending` / `message_sent`**: hook-и вхідних + вихідних повідомлень. -- **`session_start` / `session_end`**: межі життєвого циклу сеансу. +- **`before_install`**: перевіряє вбудовані результати сканування та за потреби блокує встановлення skill або Plugin. +- **`tool_result_persist`**: синхронно трансформує результати інструментів перед їх записом у транскрипт сесії, яким володіє OpenClaw. +- **`message_received` / `message_sending` / `message_sent`**: hooks вхідних + вихідних повідомлень. +- **`session_start` / `session_end`**: межі життєвого циклу сесії. - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway. -Правила ухвалення рішень hook-ами для outbound/tool-запобіжників: +Правила рішень hook для вихідних/tool guard: -- `before_tool_call`: `{ block: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` нічого не робить і не знімає попереднє блокування. -- `before_install`: `{ block: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом. -- `before_install`: `{ block: false }` нічого не робить і не знімає попереднє блокування. -- `message_sending`: `{ cancel: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` нічого не робить і не знімає попереднє скасування. +- `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. +- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. -Див. [Hook-и Plugin](/uk/plugins/hooks) для API hook-ів і деталей реєстрації. +Див. [Plugin hooks](/uk/plugins/hooks) для API hook і деталей реєстрації. -Harness-и можуть адаптувати ці hook-и по-різному. Harness app-server Codex зберігає -hook-и Plugin OpenClaw як контракт сумісності для задокументованих дзеркальних -поверхонь, тоді як нативні hook-и Codex залишаються окремим нижчорівневим механізмом Codex. +Harness-и можуть адаптувати ці hooks по-різному. Harness app-server Codex зберігає +OpenClaw plugin hooks як контракт сумісності для документованих дзеркальних +поверхонь, тоді як нативні hooks Codex залишаються окремим низькорівневим механізмом Codex. ## Потокова передача + часткові відповіді -- Дельти асистента потоково надходять із pi-agent-core і генеруються як події `assistant`. -- Блокова потокова передача може генерувати часткові відповіді або на `text_end`, або на `message_end`. -- Потокове міркування може генеруватися як окремий потік або як блокові відповіді. -- Див. [Потокова передача](/uk/concepts/streaming) щодо поведінки chunking і блокових відповідей. +- Дельти асистента транслюються з pi-agent-core і видаються як події `assistant`. +- Потокова передача блоків може видавати часткові відповіді або на `text_end`, або на `message_end`. +- Потокова передача міркувань може видаватися як окремий потік або як блокові відповіді. +- Див. [Потокова передача](/uk/concepts/streaming) для поведінки фрагментації та блокових відповідей. ## Виконання інструментів + інструменти повідомлень -- Події старту/оновлення/завершення інструменту генеруються в потоці `tool`. -- Результати інструментів очищаються за розміром і payload-ами зображень перед логуванням/генеруванням. -- Надсилання інструментів повідомлень відстежуються, щоб пригнічувати дублікати підтверджень асистента. +- Події старту/оновлення/завершення інструментів видаються в потоці `tool`. +- Результати інструментів санітизуються за розміром і image payload-ами перед логуванням/видачею. +- Надсилання інструментами повідомлень відстежуються, щоб пригнічувати дублікати підтверджень від асистента. ## Формування відповіді + пригнічення - Фінальні payload-и збираються з: - - тексту асистента (та опціонального міркування) + - тексту асистента (і необов’язкових міркувань) - inline-підсумків інструментів (коли verbose + дозволено) - - тексту помилки асистента, коли модель помиляється -- Точний мовчазний токен `NO_REPLY` / `no_reply` фільтрується з вихідних + - тексту помилки асистента, коли модель повертає помилку +- Точний silent token `NO_REPLY` / `no_reply` фільтрується з вихідних payload-ів. - Дублікати інструментів повідомлень видаляються з фінального списку payload-ів. -- Якщо не лишається придатних до рендерингу payload-ів і інструмент завершився з помилкою, генерується fallback-відповідь про помилку інструменту +- Якщо не лишається жодного придатного для рендерингу payload-а, а інструмент завершився помилкою, видається резервна відповідь про помилку інструмента (якщо інструмент повідомлень уже не надіслав видиму для користувача відповідь). ## Compaction + повторні спроби -- Автоматичний Compaction генерує події потоку `compaction` і може запускати повторну спробу. +- Auto-compaction видає події потоку `compaction` і може запускати повторну спробу. - Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання виводу. -- Див. [Compaction](/uk/concepts/compaction) щодо конвеєра Compaction. +- Див. [Compaction](/uk/concepts/compaction) для конвеєра Compaction. ## Потоки подій (сьогодні) -- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як fallback через `agentCommand`) +- `lifecycle`: видається `subscribeEmbeddedPiSession` (і як резервний варіант `agentCommand`) - `assistant`: потокові дельти з pi-agent-core -- `tool`: потокові події інструментів із pi-agent-core +- `tool`: потокові події інструментів з pi-agent-core -## Обробка чат-каналу +## Обробка чат-каналів - Дельти асистента буферизуються в чат-повідомлення `delta`. -- Чат `final` генерується на **завершення/помилку життєвого циклу**. +- Чат `final` видається на **lifecycle end/error**. ## Тайм-аути -- Стандартно для `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає. -- Середовище виконання агента: `agents.defaults.timeoutSeconds` за замовчуванням 172800 с (48 годин); застосовується таймером переривання в `runEmbeddedPiAgent`. -- Відновлення завислого сеансу: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` виявляє довгі сеанси `processing`. Активні вбудовані запуски, активні операції відповіді та активні задачі лінії сеансу за замовчуванням залишаються лише попередженнями; якщо діагностика не показує активної роботи для сеансу, watchdog звільняє відповідну лінію сеансу, щоб запланована стартова робота могла завершитися. -- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять chunks відповіді. `models.providers..timeoutSeconds` розширює цей idle watchdog для повільних локальних/self-hosted provider-ів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли налаштовано, з верхньою межею 120 с за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron. -- Тайм-аут HTTP-запиту provider-а: `models.providers..timeoutSeconds` застосовується до HTTP-fetch-ів моделі цього provider-а, включно з connect, headers, body, тайм-аутом запиту SDK, загальною обробкою guarded-fetch abort і idle watchdog потоку моделі. Використовуйте це для повільних локальних/self-hosted provider-ів, як-от Ollama, перед підвищенням тайм-ауту всього середовища виконання агента. +- `agent.wait` за замовчуванням: 30 с (лише очікування). Параметр `timeoutMs` перевизначає. +- Середовище виконання агента: `agents.defaults.timeoutSeconds` за замовчуванням 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. +- Середовище виконання Cron: ізольований agent-turn `timeoutSeconds` належить cron. Планувальник запускає цей таймер, коли починається виконання, перериває базовий запуск у налаштований граничний час, а потім виконує обмежене очищення перед записом тайм-ауту, щоб застаріла дочірня сесія не могла тримати смугу заблокованою. +- Відновлення завислої сесії: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` виявляє довгі сесії `processing`. Активні вбудовані запуски, активні операції відповіді та активні завдання сесійної смуги за замовчуванням залишаються лише попередженнями; якщо діагностика не показує активної роботи для сесії, watchdog звільняє відповідну сесійну смугу, щоб робота запуску в черзі могла виконатися. +- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення idle window не надходять фрагменти відповіді. `models.providers..timeoutSeconds` розширює цей idle watchdog для повільних локальних/самостійно розгорнутих providers; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли це налаштовано, з обмеженням 120 с за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron. +- Тайм-аут HTTP-запиту provider: `models.providers..timeoutSeconds` застосовується до HTTP fetch-ів моделі цього provider, включно з connect, headers, body, тайм-аутом запиту SDK, загальною обробкою guarded-fetch abort і watchdog простою потоку моделі. Використовуйте це для повільних локальних/самостійно розгорнутих providers, таких як Ollama, перш ніж підвищувати тайм-аут усього середовища виконання агента. ## Де все може завершитися раніше @@ -183,7 +184,7 @@ hook-и Plugin OpenClaw як контракт сумісності для зад ## Пов’язане - [Інструменти](/uk/tools) — доступні інструменти агента -- [Hook-и](/uk/automation/hooks) — подієві скрипти, що запускаються подіями життєвого циклу агента -- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови -- [Схвалення Exec](/uk/tools/exec-approvals) — ворота схвалення для shell-команд -- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning +- [Hooks](/uk/automation/hooks) — скрипти, керовані подіями, що запускаються подіями життєвого циклу агента +- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови +- [Exec Approvals](/uk/tools/exec-approvals) — approval gates для shell-команд +- [Thinking](/uk/tools/thinking) — конфігурація рівня thinking/reasoning