From 4bd2a11eb8b86e7fd55070819d8dfda1f8a2f767 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 01:46:17 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/automation/cron-jobs.md | 221 +++---- docs/uk/automation/index.md | 108 ++-- docs/uk/concepts/session.md | 127 ++-- docs/uk/gateway/config-agents.md | 526 ++++++++-------- docs/uk/gateway/configuration-reference.md | 559 +++++++++--------- docs/uk/gateway/heartbeat.md | 353 +++++------ docs/uk/gateway/opentelemetry.md | 216 +++---- docs/uk/plugins/hooks.md | 200 ++++--- docs/uk/plugins/sdk-provider-plugins.md | 308 +++++----- docs/uk/providers/fal.md | 73 ++- .../session-management-compaction.md | 261 ++++---- docs/uk/tools/video-generation.md | 349 +++++------ 12 files changed, 1674 insertions(+), 1627 deletions(-) diff --git a/docs/uk/automation/cron-jobs.md b/docs/uk/automation/cron-jobs.md index d13dcb823..2105938aa 100644 --- a/docs/uk/automation/cron-jobs.md +++ b/docs/uk/automation/cron-jobs.md @@ -6,15 +6,15 @@ read_when: summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway title: Заплановані завдання x-i18n: - generated_at: "2026-04-26T01:24:15Z" + generated_at: "2026-04-26T01:42:38Z" model: gpt-5.4 provider: openai - source_hash: 339bb43e7fa34d4307221b4587402d31ebad7642dee36e32f5a91ca44fa06775 + source_hash: f44178e5925292d5216a12874f659a98deda3f02856f2de5f69a56a806a5184e source_path: automation/cron-jobs.md workflow: 15 --- -Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у канал чату або до кінцевої точки Webhook. +Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може доставляти результат назад у чат-канал або до endpoint Webhook. ## Швидкий старт @@ -36,41 +36,37 @@ openclaw cron show openclaw cron runs --id ``` -## Як працює Cron +## Як працює cron - Cron працює **всередині процесу Gateway** (а не всередині моделі). - Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів. -- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення Cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте до gitignore. -- Після цього поділу старіші версії OpenClaw можуть читати `jobs.json`, але можуть сприймати завдання як нові, оскільки поля стану виконання тепер містяться в `jobs-state.json`. -- Усі виконання Cron створюють записи [фонових завдань](/uk/automation/tasks). -- Одноразові завдання (`--at`) типово автоматично видаляються після успішного виконання. -- Ізольовані запуски Cron після завершення намагаються закрити відстежувані вкладки браузера/процеси для своєї сесії `cron:`, щоб від’єднана автоматизація браузера не залишала після себе осиротілі процеси. -- Ізольовані запуски Cron також захищають від застарілих відповідей-підтверджень. Якщо - перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything -together` та подібні підказки), і жоден дочірній запуск субагента більше не - відповідає за фінальну відповідь, OpenClaw ще раз надсилає запит для отримання - фактичного результату перед доставкою. +- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте до gitignore. +- Після розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть сприймати завдання як нові, оскільки поля стану виконання тепер містяться в `jobs-state.json`. +- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks). +- Одноразові завдання (`--at`) після успішного виконання типово автоматично видаляються. +- Ізольовані запуски cron після завершення виконання в режимі best-effort закривають відстежувані вкладки браузера/процеси для своєї сесії `cron:`, щоб відокремлена автоматизація браузера не залишала після себе процеси-сироти. +- Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw повторно надсилає запит один раз, щоб отримати фактичний результат перед доставкою. -Узгодження завдань для Cron належить до виконуваного середовища: активне завдання Cron залишається активним, поки середовище виконання Cron усе ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. -Щойно середовище виконання перестає володіти цим завданням і спливає 5-хвилинне вікно відстрочки, обслуговування може позначити завдання як `lost`. +Узгодження завдань для cron контролюється середовищем виконання: активне завдання cron залишається живим, доки середовище виконання cron все ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. +Щойно середовище виконання перестає контролювати завдання і спливає 5-хвилинне вікно очікування, обслуговування може позначити завдання як `lost`. ## Типи розкладу -| Тип | Прапорець CLI | Опис | -| ------- | ------------- | ------------------------------------------------------- | -| `at` | `--at` | Одноразова часова позначка (ISO 8601 або відносна, наприклад `20m`) | -| `every` | `--every` | Фіксований інтервал | -| `cron` | `--cron` | Cron-вираз із 5 або 6 полів із необов’язковим `--tz` | +| Вид | Прапорець CLI | Опис | +| ------- | ------------- | ------------------------------------------------------------- | +| `at` | `--at` | Одноразова мітка часу (ISO 8601 або відносна, наприклад `20m`) | +| `every` | `--every` | Фіксований інтервал | +| `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). Коли і поля дня місяця, і дня тижня не є wildcard, croner виконує збіг, якщо **збігається будь-яке** з цих полів, а не обидва. Це стандартна поведінка Vixie cron. ``` # Intended: "9 AM on the 15th, only if it's a Monday" @@ -78,89 +74,68 @@ Cron-вирази розбираються за допомогою [croner](http 0 9 15 * 1 ``` -Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. Тут OpenClaw використовує стандартну OR-поведінку Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` від Croner (`0 9 15 * +1`) або плануйте за одним полем, а друге перевіряйте в prompt чи команді вашого завдання. +Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. Тут OpenClaw використовує стандартну поведінку OR із Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` у Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в запиті чи команді вашого завдання. ## Стилі виконання -| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | -| --------------- | -------------------- | ------------------------- | ------------------------------ | -| Основна сесія | `main` | Наступного циклу Heartbeat | Нагадувань, системних подій | -| Ізольований | `isolated` | Виділеної `cron:` | Звітів, фонових завдань | -| Поточна сесія | `current` | Прив’язується під час створення | Повторюваної роботи з урахуванням контексту | -| Користувацька сесія | `session:custom-id` | Постійної іменованої сесії | Робочих процесів, що спираються на історію | +| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | +| --------------- | -------------------- | ------------------------ | -------------------------------- | +| Основна сесія | `main` | Наступного циклу Heartbeat | Нагадувань, системних подій | +| Ізольований | `isolated` | Виділеної `cron:` | Звітів, фонових завдань | +| Поточна сесія | `current` | Прив’язується під час створення | Періодичної роботи з урахуванням контексту | +| Власна сесія | `session:custom-id` | Постійній іменованій сесії | Робочих процесів, що спираються на історію | -Завдання **основної сесії** ставлять системну подію в чергу та за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). **Ізольовані** завдання виконують окремий цикл агента зі свіжою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу будувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. +Завдання **основної сесії** ставлять системну подію в чергу й за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують актуальність щоденного/idle-скидання для цільової сесії. **Ізольовані** завдання виконують окремий цикл агента з новою сесією. **Власні сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу реалізовувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. -Для ізольованих завдань «свіжа сесія» означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення model/auth, але не успадковує фоновий контекст розмови зі старого рядка Cron: маршрутизацію каналу/групи, політику надсилання або черги, elevated-права, джерело чи прив’язку середовища виконання ACP. Використовуйте `current` або `session:`, якщо повторюване завдання має навмисно розвиватися в тому самому контексті розмови. +Для ізольованих завдань “нова сесія” означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення моделі/автентифікації, але не успадковує фоновий контекст розмови зі старого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищені привілеї, origin або прив’язку середовища виконання ACP. Використовуйте `current` або `session:`, коли періодичне завдання має свідомо будуватися на тому самому контексті розмови. -Для ізольованих завдань завершення виконання тепер також включає найкращу спробу очищення браузера для цієї сесії Cron. Помилки очищення ігноруються, щоб фактичний результат Cron усе одно мав пріоритет. +Для ізольованих завдань завершення середовища виконання тепер також включає best-effort очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, тому фактичний результат cron усе одно має пріоритет. -Ізольовані запуски Cron також звільняють усі вбудовані екземпляри середовища виконання MCP, створені для завдання, через спільний шлях очищення середовища виконання. Це відповідає тому, як завершуються клієнти MCP для основної та користувацьких сесій, тож ізольовані завдання Cron не залишають процесів-нащадків stdio чи довготривалих MCP-з’єднань між запусками. +Ізольовані запуски cron також вивільняють усі вбудовані екземпляри середовища виконання MCP, створені для завдання, через спільний шлях очищення середовища виконання. Це відповідає тому, як завершується робота клієнтів MCP для основної та власної сесій, тож ізольовані cron-завдання не призводять до витоків дочірніх stdio-процесів або довготривалих MCP-з’єднань між запусками. -Коли ізольовані запуски Cron оркеструють субагентів, доставка також надає перевагу фінальному -результату дочірнього нащадка над застарілим проміжним текстом батьківського агента. Якщо нащадки все ще -виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його. +Коли ізольовані запуски cron оркеструють субагентів, доставка також надає перевагу фінальному виходу дочірнього елемента, а не застарілому проміжному тексту батьківського. Якщо дочірні елементи все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його. -Для цілей announce у Discord, які підтримують лише текст, OpenClaw надсилає -канонічний фінальний текст асистента один раз замість повторного відтворення і потокового/проміжного текстового payload, і -фінальної відповіді. Медіа та структуровані payload для Discord і далі доставляються окремими payload, щоб вкладення та компоненти не були втрачені. +Для цілей оголошення в Discord лише з текстом OpenClaw надсилає один раз канонічний фінальний текст асистента, а не відтворює і потокові/проміжні текстові payload, і фінальну відповідь. Медіа та структуровані payload для Discord, як і раніше, доставляються окремо, щоб не втрачалися вкладення та компоненти. ### Параметри payload для ізольованих завдань -- `--message`: текст prompt (обов’язковий для isolated) +- `--message`: текст запиту (обов’язково для isolated) - `--model` / `--thinking`: перевизначення моделі та рівня thinking -- `--light-context`: пропустити ін’єкцію файлів початкового завантаження робочого простору -- `--tools exec,read`: обмежити, які інструменти може використовувати завдання +- `--light-context`: пропустити ін’єкцію bootstrap-файлів робочого простору +- `--tools exec,read`: обмежити інструменти, які може використовувати завдання -`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель -не дозволена, Cron записує попередження в журнал і повертається до вибору моделі -агента/типової моделі для цього завдання. Налаштовані ланцюжки fallback і далі застосовуються, але звичайне -перевизначення моделі без явного списку fallback для конкретного завдання більше не додає -основну модель агента як приховану додаткову ціль повторної спроби. +`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/типової моделі для завдання. Налаштовані ланцюжки fallback, як і раніше, застосовуються, але просте перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. Пріоритет вибору моделі для ізольованих завдань: -1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) +1. Перевизначення моделі з Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) 2. `model` у payload конкретного завдання -3. Збережене перевизначення моделі сесії Cron, вибране користувачем +3. Збережене перевизначення моделі cron-сесії, вибране користувачем 4. Вибір моделі агента/типової моделі -Швидкий режим також дотримується підсумкового активного вибору. Якщо вибрана конфігурація моделі -має `params.fastMode`, ізольований Cron використовує це типово. Збережене перевизначення -сесії `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках. +Режим fast також дотримується вибраної активної конфігурації. Якщо вибрана конфігурація моделі має `params.fastMode`, ізольований cron типово використовує її. Збережене в сесії перевизначення `fastMode` усе одно має пріоритет над конфігурацією в обидва боки. -Якщо ізольований запуск натрапляє на живу передачу керування зі зміною моделі, Cron повторює спробу з -перемкненими provider/model і зберігає цей активний вибір для поточного запуску -перед повторною спробою. Коли перемикання також містить новий профіль auth, Cron зберігає -це перевизначення профілю auth для поточного запуску. Кількість повторів обмежена: після -початкової спроби та ще 2 повторів через перемикання Cron перериває виконання замість безкінечного циклу. +Якщо ізольований запуск натрапляє на live-передачу керування зі зміною моделі, cron виконує повторну спробу з перемкненим provider/model і зберігає цей активний вибір для поточного запуску перед повторною спробою. Якщо перемикання також містить новий профіль автентифікації, cron теж зберігає це перевизначення профілю автентифікації для поточного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб після перемикання cron перериває роботу замість нескінченного циклу. ## Доставка та вивід -| Режим | Що відбувається | -| --------- | ----------------------------------------------------------------- | +| Режим | Що відбувається | +| --------- | ------------------------------------------------------------------- | | `announce` | Резервно доставляє фінальний текст до цілі, якщо агент його не надіслав | -| `webhook` | Надсилає POST із payload завершеної події на URL | -| `none` | Без резервної доставки з боку виконавця | +| `webhook` | Надсилає POST payload завершеної події на URL | +| `none` | Немає резервної доставки з боку виконавця | -Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний room ID або форму `room:!room:server` із Matrix. +Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму в Telegram використовуйте `-1001234567890:topic:123`. Для цілей у Slack/Discord/Mattermost слід використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний room ID або форму `room:!room:server` із Matrix. -Для ізольованих завдань доставка до чату є спільною. Якщо маршрут чату доступний, -агент може використовувати інструмент `message`, навіть якщо для завдання задано `--no-deliver`. Якщо -агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервний -announce. В іншому разі `announce`, `webhook` і `none` керують лише тим, що -виконавець робить із фінальною відповіддю після циклу агента. +Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли для завдання задано `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` лише визначають, що виконавець робить із фінальною відповіддю після циклу агента. -Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає -збережену активну ціль доставки для маршруту резервного announce. Внутрішні -ключі сесії можуть бути в нижньому регістрі; цілі доставки provider не відновлюються -з цих ключів, коли доступний поточний контекст чату. +Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену активну ціль доставки для маршруту резервного оголошення. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставки провайдера не відтворюються з цих ключів, коли доступний контекст поточного чату. -Сповіщення про збої використовують окремий маршрут призначення: +Сповіщення про помилки використовують окремий маршрут призначення: -- `cron.failureDestination` задає глобальне типове призначення для сповіщень про збої. -- `job.delivery.failureDestination` перевизначає це для окремого завдання. -- Якщо не задано жодного з них і завдання вже доставляє результат через `announce`, сповіщення про збої тепер резервно використовують цю основну ціль announce. +- `cron.failureDestination` задає глобальне типове значення для сповіщень про помилки. +- `job.delivery.failureDestination` перевизначає його для окремого завдання. +- Якщо не задано жодного з них, а завдання вже доставляє через `announce`, сповіщення про помилки тепер резервно надсилаються на ту саму основну ціль announce. - `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`. ## Приклади CLI @@ -190,7 +165,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -Ізольоване завдання з перевизначенням model і thinking: +Ізольоване завдання з перевизначенням моделі та thinking: ```bash openclaw cron add \ @@ -206,7 +181,7 @@ openclaw cron add \ ## Webhook-и -Gateway може відкривати кінцеві точки HTTP Webhook для зовнішніх тригерів. Увімкніть у конфігурації: +Gateway може надавати HTTP endpoint-и Webhook для зовнішніх тригерів. Увімкніть у конфігурації: ```json5 { @@ -229,7 +204,7 @@ Gateway може відкривати кінцеві точки HTTP Webhook д ### POST /hooks/wake -Поставити системну подію в чергу для основної сесії: +Ставить системну подію в чергу для основної сесії: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -243,7 +218,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ ### POST /hooks/agent -Запустити ізольований цикл агента: +Запускає ізольований цикл агента: ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -254,25 +229,25 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ Поля: `message` (обов’язково), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`. -### Зіставлені hook-и (POST /hooks/\) +### Зіставлені hooks (POST /hooks/\) -Користувацькі імена hook-ів зіставляються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільний payload на дії `wake` або `agent` за допомогою шаблонів або перетворень у коді. +Власні назви hook визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload на дії `wake` або `agent` за допомогою шаблонів або перетворень кодом. ### Безпека -- Тримайте кінцеві точки hook за loopback, tailnet або довіреним reverse proxy. -- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway. +- Тримайте endpoint-и hook за loopback, tailnet або довіреним reverse proxy. +- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації Gateway. - Тримайте `hooks.path` на окремому підшляху; `/` відхиляється. -- Задайте `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. -- Тримайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. -- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесії. -- Payload hook за замовчуванням обгортаються межами безпеки. +- Встановіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. +- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. +- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також встановіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесії. +- Payload hook типово обгортаються межами безпеки. ## Інтеграція Gmail PubSub Підключіть тригери вхідної пошти Gmail до OpenClaw через Google PubSub. -**Передумови**: CLI `gcloud`, `gog` (gogcli), увімкнені hook OpenClaw, Tailscale для публічної кінцевої точки HTTPS. +**Передумови**: CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint. ### Налаштування через майстер (рекомендовано) @@ -280,11 +255,11 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Це записує конфігурацію `hooks.gmail`, вмикає пресет Gmail і використовує Tailscale Funnel для push-кінцевої точки. +Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push endpoint. ### Автозапуск 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`. ### Ручне одноразове налаштування @@ -359,13 +334,9 @@ openclaw cron edit --clear-agent Примітка щодо перевизначення моделі: - `openclaw cron add|edit --model ...` змінює вибрану модель завдання. -- Якщо модель дозволена, саме цей provider/model передається в ізольований запуск - агента. -- Якщо вона не дозволена, cron виводить попередження й повертається до вибору - моделі агента/типової моделі для завдання. -- Налаштовані ланцюжки fallback і далі застосовуються, але звичайне перевизначення `--model` - без явного списку fallback для конкретного завдання більше не переходить до - основної моделі агента як до тихої додаткової цілі повторної спроби. +- Якщо модель дозволена, саме ця пара provider/model передається ізольованому запуску агента. +- Якщо вона не дозволена, cron виводить попередження і повертається до вибору моделі агента/типової моделі для завдання. +- Налаштовані ланцюжки fallback, як і раніше, застосовуються, але просте перевизначення `--model` без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби. ## Конфігурація @@ -387,19 +358,17 @@ openclaw cron edit --clear-agent } ``` -Побічний файл стану виконання виводиться з `cron.store`: сховище `.json`, наприклад -`~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а до шляху сховища -без суфікса `.json` додається `-state.json`. +Похідний sidecar стану виконання визначається з `cron.store`: сховище `.json`, наприклад `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а шлях сховища без суфікса `.json` додає `-state.json`. -Вимкнення Cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. +Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. -**Повтор одноразового завдання**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикаються негайно. +**Повтор одноразового завдання**: тимчасові помилки (ліміт запитів, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки негайно вимикають завдання. -**Повтор періодичного завдання**: експоненційний 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` автоматично очищають файли журналу запусків. -## Усунення неполадок +## Усунення несправностей ### Послідовність команд @@ -419,32 +388,32 @@ openclaw doctor - Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`. - Підтвердьте, що Gateway працює безперервно. - Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста. -- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due`, і час завдання ще не настав. +- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due`, але час виконання завдання ще не настав. ### Cron спрацював, але доставки немає -- Режим доставки `none` означає, що резервне надсилання з боку виконавця не очікується. Агент - усе ще може надсилати напряму за допомогою інструмента `message`, коли маршрут чату доступний. +- Режим доставки `none` означає, що резервного надсилання з боку виконавця не очікується. Агент усе ще може надсилати повідомлення безпосередньо через інструмент `message`, якщо маршрут чату доступний. - Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено. -- Для Matrix скопійовані або застарілі завдання з room ID у `delivery.to`, приведеними до нижнього регістру, - можуть завершуватися невдачею, оскільки room ID Matrix чутливі до регістру. Відредагуйте завдання на точне - значення `!room:server` або `room:!room:server` із Matrix. -- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставка була заблокована через облікові дані. -- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), - OpenClaw пригнічує пряме вихідне надсилання, а також резервний - шлях зведення в черзі, тому назад у чат нічого не публікується. -- Якщо агент має сам написати користувачеві, перевірте, що завдання має придатний - маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль). +- Для Matrix скопійовані або застарілі завдання з room ID у `delivery.to`, приведеними до нижнього регістру, можуть завершуватися помилкою, оскільки room ID у Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` із Matrix. +- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку заблоковано через облікові дані. +- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне надсилання, а також резервний шлях зведення в черзі, тому назад у чат нічого не публікується. +- Якщо агент має сам надіслати повідомлення користувачеві, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явно заданий канал/ціль). -### Поширені нюанси часових поясів +### Здається, що cron або heartbeat заважають rollover у стилі `/new` -- Cron без `--tz` використовує часовий пояс хоста gateway. +- Актуальність щоденного та idle-скидання не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). +- Пробудження cron, запуски heartbeat, сповіщення exec і службові дії gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не продовжують `sessionStartedAt` або `lastInteractionAt`. +- Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії transcript JSONL, якщо файл ще доступний. Для застарілих idle-рядків без `lastInteractionAt` як базову точку idle використовується цей відновлений час початку. + +### Особливості часових поясів + +- Cron без `--tz` використовує часовий пояс хоста Gateway. - Розклади `at` без часового поясу трактуються як UTC. -- `activeHours` у Heartbeat використовує налаштоване визначення часового поясу. +- `activeHours` Heartbeat використовує налаштоване визначення часового поясу. ## Пов’язане -- [Automation & Tasks](/uk/automation) — усі механізми автоматизації з першого погляду -- [Background Tasks](/uk/automation/tasks) — журнал завдань для виконань Cron +- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації в одному огляді +- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron - [Heartbeat](/uk/gateway/heartbeat) — періодичні цикли основної сесії -- [Timezone](/uk/concepts/timezone) — конфігурація часового поясу +- [Часовий пояс](/uk/concepts/timezone) — налаштування часового поясу diff --git a/docs/uk/automation/index.md b/docs/uk/automation/index.md index 69ffd3c8d..922e26ac5 100644 --- a/docs/uk/automation/index.md +++ b/docs/uk/automation/index.md @@ -1,22 +1,22 @@ --- read_when: - - Вибір способу автоматизації роботи з OpenClaw - - Вибір між Heartbeat, Cron, hooks і постійними розпорядженнями + - Вирішення того, як автоматизувати роботу з OpenClaw + - Вибір між Heartbeat, Cron, хуками та постійними дорученнями - Пошук правильної точки входу для автоматизації -summary: 'Огляд механізмів автоматизації: завдання, cron, hooks, постійні розпорядження та TaskFlow' +summary: 'Огляд механізмів автоматизації: завдання, Cron, хуки, постійні доручення та TaskFlow' title: Автоматизація та завдання x-i18n: - generated_at: "2026-04-24T17:33:03Z" + generated_at: "2026-04-26T01:42:38Z" model: gpt-5.4 provider: openai - source_hash: 54524eb5d1fcb2b2e3e51117339be1949d980afaef1f6ae71fcfd764049f3f47 + source_hash: 6d2a2d3ef58830133e07b34f33c611664fc1032247e9dd81005adf7fc0c43cdb source_path: automation/index.md workflow: 15 --- -OpenClaw виконує роботу у фоновому режимі через завдання, заплановані задачі, hooks і постійні інструкції. Ця сторінка допоможе вам вибрати правильний механізм і зрозуміти, як вони поєднуються між собою. +OpenClaw виконує роботу у фоновому режимі через завдання, заплановані завдання, хуки та постійні інструкції. Ця сторінка допоможе вам вибрати правильний механізм і зрозуміти, як вони поєднуються. -## Короткий посібник з вибору +## Короткий посібник із вибору ```mermaid flowchart TD @@ -26,100 +26,100 @@ flowchart TD START --> Q4{Реагувати на події життєвого циклу?} START --> Q5{Надати агенту постійні інструкції?} - Q1 -->|Так| Q1a{Точний час чи гнучко?} - Q1a -->|Точно| CRON["Заплановані завдання (Cron)"] - Q1a -->|Гнучко| HEARTBEAT[Heartbeat] + Q1 -->|Так| Q1a{Точний час чи гнучкий?} + Q1a -->|Точний| CRON["Заплановані завдання (Cron)"] + Q1a -->|Гнучкий| HEARTBEAT[Heartbeat] Q2 -->|Так| TASKS[Фонові завдання] Q3 -->|Так| FLOW[TaskFlow] - Q4 -->|Так| HOOKS[Hooks] - Q5 -->|Так| SO[Постійні розпорядження] + Q4 -->|Так| HOOKS[Хуки] + Q5 -->|Так| SO[Постійні доручення] ``` | Випадок використання | Рекомендовано | Чому | -| --------------------------------------- | ---------------------- | ----------------------------------------------- | -| Надіслати щоденний звіт рівно о 9:00 | Заплановані завдання (Cron) | Точний час, ізольоване виконання | -| Нагадати мені через 20 хвилин | Заплановані завдання (Cron) | Одноразовий запуск із точним часом (`--at`) | -| Запускати щотижневий глибокий аналіз | Заплановані завдання (Cron) | Окреме завдання, можна використовувати іншу модель | -| Перевіряти вхідні кожні 30 хв | Heartbeat | Об’єднує з іншими перевірками, враховує контекст | -| Стежити за календарем щодо майбутніх подій | Heartbeat | Природний варіант для періодичного моніторингу | -| Перевірити статус субагента або запуску ACP | Фонові завдання | Журнал завдань відстежує всю відокремлену роботу | -| Перевірити, що запускалося і коли | Фонові завдання | `openclaw tasks list` і `openclaw tasks audit` | -| Багатокрокове дослідження, а потім підсумок | TaskFlow | Надійна оркестрація з відстеженням ревізій | -| Запустити скрипт під час скидання сесії | Hooks | Керується подіями, спрацьовує на подіях життєвого циклу | -| Виконувати код під час кожного виклику інструмента | Plugin hooks | Внутрішньопроцесні hooks можуть перехоплювати виклики інструментів | -| Завжди перевіряти відповідність перед відповіддю | Постійні розпорядження | Автоматично додаються до кожної сесії | +| --------------------------------------- | ---------------------- | ------------------------------------------------ | +| Надсилати щоденний звіт рівно о 9:00 | Заплановані завдання (Cron) | Точний час, ізольоване виконання | +| Нагадай мені через 20 хвилин | Заплановані завдання (Cron) | Одноразове виконання з точним часом (`--at`) | +| Запускати щотижневий глибокий аналіз | Заплановані завдання (Cron) | Окреме завдання, може використовувати іншу модель | +| Перевіряти вхідні кожні 30 хв | Heartbeat | Об’єднується з іншими перевірками, враховує контекст | +| Відстежувати календар для майбутніх подій | Heartbeat | Природний варіант для періодичної обізнаності | +| Перевірити стан субагента або запуску ACP | Фонові завдання | Журнал завдань відстежує всю відокремлену роботу | +| Переглянути, що виконувалося і коли | Фонові завдання | `openclaw tasks list` і `openclaw tasks audit` | +| Багатокрокове дослідження, а потім підсумок | TaskFlow | Стійка оркестрація з відстеженням ревізій | +| Запустити скрипт під час скидання сесії | Хуки | Керується подіями, спрацьовує на подіях життєвого циклу | +| Виконувати код під час кожного виклику інструмента | Plugin hooks | Внутрішньопроцесні хуки можуть перехоплювати виклики інструментів | +| Завжди перевіряти відповідність перед відповіддю | Постійні доручення | Автоматично додаються до кожної сесії | ### Заплановані завдання (Cron) vs Heartbeat -| Вимір | Заплановані завдання (Cron) | Heartbeat | -| -------------- | ---------------------------------- | ------------------------------------ | -| Час | Точний (cron-вирази, одноразовий запуск) | Приблизний (типово кожні 30 хв) | -| Контекст сесії | Новий (ізольований) або спільний | Повний контекст основної сесії | -| Записи завдань | Створюються завжди | Ніколи не створюються | -| Доставка | Канал, Webhook або без виводу | Вбудовано в основну сесію | -| Найкраще для | Звітів, нагадувань, фонових задач | Перевірки вхідних, календаря, сповіщень | +| Вимір | Заплановані завдання (Cron) | Heartbeat | +| --------------- | ----------------------------------- | ------------------------------------- | +| Час | Точний (cron-вирази, одноразово) | Приблизний (типово кожні 30 хвилин) | +| Контекст сесії | Нова (ізольована) або спільна | Повний контекст основної сесії | +| Записи завдань | Завжди створюються | Ніколи не створюються | +| Доставка | Канал, Webhook або без виводу | Вбудовано в основну сесію | +| Найкраще для | Звітів, нагадувань, фонових завдань | Перевірки вхідних, календаря, сповіщень | -Використовуйте Заплановані завдання (Cron), коли потрібен точний час або ізольоване виконання. Використовуйте Heartbeat, коли роботі корисний повний контекст сесії, а приблизного часу достатньо. +Використовуйте заплановані завдання (Cron), коли вам потрібен точний час або ізольоване виконання. Використовуйте Heartbeat, коли робота виграє від повного контексту сесії, а приблизний час є прийнятним. ## Основні поняття ### Заплановані завдання (cron) -Cron — це вбудований планувальник Gateway для точного часу. Він зберігає задачі, пробуджує агента у потрібний момент і може доставляти результат до каналу чату або endpoint Webhook. Підтримує одноразові нагадування, повторювані вирази та вхідні тригери Webhook. +Cron — це вбудований планувальник Gateway для точного часу. Він зберігає завдання, пробуджує агента в потрібний момент і може доставляти результат у канал чату або на endpoint Webhook. Підтримує одноразові нагадування, повторювані вирази та вхідні тригери Webhook. Див. [Заплановані завдання](/uk/automation/cron-jobs). ### Завдання -Журнал фонових завдань відстежує всю відокремлену роботу: запуски ACP, запуск субагентів, ізольовані cron-виконання та операції CLI. Завдання — це записи, а не планувальники. Використовуйте `openclaw tasks list` і `openclaw tasks audit` для їх перегляду. +Журнал фонових завдань відстежує всю відокремлену роботу: запуски ACP, породження субагентів, ізольовані виконання cron і CLI-операції. Завдання — це записи, а не планувальники. Використовуйте `openclaw tasks list` і `openclaw tasks audit` для їх перевірки. Див. [Фонові завдання](/uk/automation/tasks). ### TaskFlow -TaskFlow — це підкладка оркестрації потоків над фоновими завданнями. Вона керує надійними багатокроковими потоками з керованими та дзеркальними режимами синхронізації, відстеженням ревізій і `openclaw tasks flow list|show|cancel` для перегляду. +TaskFlow — це підсистема оркестрації потоків над фоновими завданнями. Вона керує стійкими багатокроковими потоками з керованими та дзеркальними режимами синхронізації, відстеженням ревізій і `openclaw tasks flow list|show|cancel` для перевірки. Див. [TaskFlow](/uk/automation/taskflow). -### Постійні розпорядження +### Постійні доручення -Постійні розпорядження надають агенту постійні повноваження для виконання визначених програм. Вони зберігаються у файлах робочого простору (зазвичай `AGENTS.md`) і додаються до кожної сесії. Поєднуйте з cron для контролю, прив’язаного до часу. +Постійні доручення надають агенту постійні повноваження для визначених програм. Вони зберігаються у файлах робочого простору (зазвичай `AGENTS.md`) і додаються до кожної сесії. Поєднуйте з cron для правил, що залежать від часу. -Див. [Постійні розпорядження](/uk/automation/standing-orders). +Див. [Постійні доручення](/uk/automation/standing-orders). -### Hooks +### Хуки -Внутрішні hooks — це керовані подіями скрипти, які спрацьовують на подіях життєвого циклу агента -(`/new`, `/reset`, `/stop`), Compaction сесії, запуску gateway та потоці -повідомлень. Вони автоматично виявляються з каталогів і можуть керуватися -через `openclaw hooks`. Для внутрішньопроцесного перехоплення викликів інструментів використовуйте +Внутрішні хуки — це скрипти, керовані подіями, які спрацьовують на подіях життєвого циклу агента +(`/new`, `/reset`, `/stop`), Compaction сесії, запуску gateway та потоку +повідомлень. Вони автоматично виявляються з каталогів і ними можна керувати +за допомогою `openclaw hooks`. Для внутрішньопроцесного перехоплення викликів інструментів використовуйте [Plugin hooks](/uk/plugins/hooks). -Див. [Hooks](/uk/automation/hooks). +Див. [Хуки](/uk/automation/hooks). ### Heartbeat -Heartbeat — це періодичний хід основної сесії (типово кожні 30 хвилин). Він об’єднує кілька перевірок (вхідні, календар, сповіщення) в одному ході агента з повним контекстом сесії. Ходи Heartbeat не створюють записів завдань. Використовуйте `HEARTBEAT.md` для невеликого списку перевірок або блок `tasks:`, якщо ви хочете перевірки лише в належний час у межах самого heartbeat. Порожні файли heartbeat пропускаються як `empty-heartbeat-file`; режим завдань лише в належний час пропускається як `no-tasks-due`. +Heartbeat — це періодичний хід основної сесії (типово кожні 30 хвилин). Він об’єднує кілька перевірок (вхідні, календар, сповіщення) в один хід агента з повним контекстом сесії. Ходи Heartbeat не створюють записи завдань і не подовжують свіжість щоденного/неактивного скидання сесії. Використовуйте `HEARTBEAT.md` для короткого контрольного списку або блок `tasks:`, якщо вам потрібні лише ті періодичні перевірки, строк яких настав, усередині самого heartbeat. Порожні файли heartbeat пропускаються як `empty-heartbeat-file`; режим завдань лише за строком пропускається як `no-tasks-due`. Див. [Heartbeat](/uk/gateway/heartbeat). ## Як вони працюють разом - **Cron** обробляє точні розклади (щоденні звіти, щотижневі огляди) та одноразові нагадування. Усі виконання cron створюють записи завдань. -- **Heartbeat** обробляє рутинний моніторинг (вхідні, календар, сповіщення) в одному об’єднаному ході кожні 30 хвилин. -- **Hooks** реагують на конкретні події (скидання сесії, Compaction, потік повідомлень) за допомогою користувацьких скриптів. Plugin hooks охоплюють виклики інструментів. -- **Постійні розпорядження** надають агенту постійний контекст і межі повноважень. +- **Heartbeat** обробляє рутинний моніторинг (вхідні, календар, сповіщення) одним об’єднаним ходом кожні 30 хвилин. +- **Хуки** реагують на конкретні події (скидання сесій, Compaction, потік повідомлень) за допомогою власних скриптів. Plugin hooks охоплюють виклики інструментів. +- **Постійні доручення** надають агенту постійний контекст і межі повноважень. - **TaskFlow** координує багатокрокові потоки поверх окремих завдань. -- **Завдання** автоматично відстежують усю відокремлену роботу, щоб ви могли її переглядати й аудіювати. +- **Завдання** автоматично відстежують усю відокремлену роботу, щоб ви могли її перевіряти й аудіювати. -## Пов’язане +## Пов’язані матеріали - [Заплановані завдання](/uk/automation/cron-jobs) — точне планування та одноразові нагадування - [Фонові завдання](/uk/automation/tasks) — журнал завдань для всієї відокремленої роботи -- [TaskFlow](/uk/automation/taskflow) — надійна оркестрація багатокрокових потоків -- [Hooks](/uk/automation/hooks) — скрипти життєвого циклу, керовані подіями -- [Plugin hooks](/uk/plugins/hooks) — внутрішньопроцесні hooks для інструментів, промптів, повідомлень і життєвого циклу -- [Постійні розпорядження](/uk/automation/standing-orders) — постійні інструкції агента +- [TaskFlow](/uk/automation/taskflow) — стійка оркестрація багатокрокових потоків +- [Хуки](/uk/automation/hooks) — скрипти життєвого циклу, керовані подіями +- [Plugin hooks](/uk/plugins/hooks) — внутрішньопроцесні хуки для інструментів, промптів, повідомлень і життєвого циклу +- [Постійні доручення](/uk/automation/standing-orders) — постійні інструкції агента - [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії - [Configuration Reference](/uk/gateway/configuration-reference) — усі ключі конфігурації diff --git a/docs/uk/concepts/session.md b/docs/uk/concepts/session.md index f68a2e8d6..b878744e2 100644 --- a/docs/uk/concepts/session.md +++ b/docs/uk/concepts/session.md @@ -1,39 +1,41 @@ --- read_when: - - Ви хочете зрозуміти маршрутизацію та ізоляцію сесій - - Ви хочете налаштувати область дії DM для конфігурацій із кількома користувачами -summary: Як OpenClaw керує сесіями розмови -title: Керування сесіями + - Ви хочете зрозуміти маршрутизацію та ізоляцію сеансів + - Ви хочете налаштувати область DM для багатокористувацьких конфігурацій + - Ви налагоджуєте щоденні скидання сеансів або скидання сеансів під час простою +summary: Як OpenClaw керує сеансами розмови +title: Керування сеансами x-i18n: - generated_at: "2026-04-23T22:59:17Z" + generated_at: "2026-04-26T01:42:37Z" model: gpt-5.4 provider: openai - source_hash: cafff1fd480bdd306f87c818e7cb66bda8440d643fbe9ce5e14b773630b35d37 + source_hash: 9ed910c990de38d6bcab4ac0bd47e4ed61a637cc6af5236c6fafc732aacb92ff source_path: concepts/session.md workflow: 15 --- -OpenClaw організовує розмови в **сесії**. Кожне повідомлення маршрутизується до -сесії залежно від того, звідки воно надійшло -- DM, групові чати, завдання Cron тощо. +OpenClaw організовує розмови в **сеанси**. Кожне повідомлення маршрутизується до +сеансу залежно від того, звідки воно надійшло — DM, групові чати, завдання cron тощо. ## Як маршрутизуються повідомлення -| Джерело | Поведінка | -| --------------- | ----------------------------- | -| Прямі повідомлення | Спільна сесія за замовчуванням | -| Групові чати | Ізольовано для кожної групи | +| Джерело | Поведінка | +| --------------- | ---------------------------- | +| Прямі повідомлення | Спільний сеанс за замовчуванням | +| Групові чати | Ізольовано для кожної групи | | Кімнати/канали | Ізольовано для кожної кімнати | -| Завдання Cron | Нова сесія для кожного запуску | -| Webhook | Ізольовано для кожного hook | +| Завдання Cron | Новий сеанс для кожного запуску | +| Webhook | Ізольовано для кожного hook | ## Ізоляція DM -За замовчуванням усі DM використовують одну спільну сесію для безперервності. Це добре підходить -для конфігурацій з одним користувачем. +За замовчуванням усі DM використовують один спільний сеанс для безперервності. Це підходить для +однокористувацьких конфігурацій. -Якщо кілька людей можуть надсилати повідомлення вашому агенту, увімкніть ізоляцію DM. Без неї всі -користувачі спільно використовують той самий контекст розмови -- приватні повідомлення Alice будуть видимі Bob. +Якщо вашому агенту можуть писати кілька людей, увімкніть ізоляцію DM. Без неї всі +користувачі використовують той самий контекст розмови — приватні повідомлення Alice будуть +видимі Bob. **Виправлення:** @@ -41,53 +43,70 @@ OpenClaw організовує розмови в **сесії**. Кожне п ```json5 { session: { - dmScope: "per-channel-peer", // ізолювати за каналом + відправником + dmScope: "per-channel-peer", // isolate by channel + sender }, } ``` Інші варіанти: -- `main` (типово) -- усі DM використовують одну спільну сесію. -- `per-peer` -- ізоляція за відправником (між каналами). -- `per-channel-peer` -- ізоляція за каналом + відправником (рекомендовано). -- `per-account-channel-peer` -- ізоляція за обліковим записом + каналом + відправником. +- `main` (за замовчуванням) — усі DM використовують один спільний сеанс. +- `per-peer` — ізоляція за відправником (у різних каналах). +- `per-channel-peer` — ізоляція за каналом + відправником (рекомендовано). +- `per-account-channel-peer` — ізоляція за обліковим записом + каналом + відправником. Якщо та сама людина зв’язується з вами з кількох каналів, використовуйте -`session.identityLinks`, щоб пов’язати її ідентичності й дати їм спільну сесію. +`session.identityLinks`, щоб пов’язати її ідентичності й дати їй один спільний сеанс. Перевірте свою конфігурацію за допомогою `openclaw security audit`. -## Життєвий цикл сесії +## Життєвий цикл сеансу -Сесії повторно використовуються, доки не завершиться строк їхньої дії: +Сеанси використовуються повторно, доки не завершиться їхній строк дії: -- **Щоденне скидання** (типово) -- нова сесія о 4:00 ранку за місцевим часом на хості - Gateway. -- **Скидання за неактивністю** (необов’язково) -- нова сесія після певного періоду бездіяльності. Установіть - `session.reset.idleMinutes`. -- **Ручне скидання** -- введіть `/new` або `/reset` у чаті. `/new ` також +- **Щоденне скидання** (за замовчуванням) — новий сеанс о 4:00 ранку за місцевим часом на хості + Gateway. Щоденна актуальність визначається моментом запуску поточного `sessionId`, а не + пізнішими записами метаданих. +- **Скидання після простою** (необов’язково) — новий сеанс після періоду неактивності. Установіть + `session.reset.idleMinutes`. Актуальність простою визначається за останньою реальною + взаємодією користувача/каналу, тому системні події heartbeat, cron і exec не + підтримують сеанс активним. +- **Ручне скидання** — введіть `/new` або `/reset` у чаті. `/new ` також перемикає модель. -Коли налаштовані і щоденне скидання, і скидання за неактивністю, спрацьовує те, що настає раніше. +Якщо налаштовано і щоденне скидання, і скидання після простою, спрацьовує те, у якого +строк дії закінчиться раніше. Переходи heartbeat, cron, exec та інших системних подій можуть записувати метадані сеансу, +але ці записи не подовжують актуальність щоденного скидання чи скидання після простою. -Сесії з активною CLI-сесією, якою володіє provider, не розриваються неявним -щоденним скиданням за замовчуванням. Використовуйте `/reset` або явно налаштуйте `session.reset`, якщо такі -сесії мають завершуватися за таймером. +Сеанси з активним CLI-сеансом, яким керує провайдер, не перериваються неявним +щоденним скиданням за замовчуванням. Використовуйте `/reset` або явно налаштуйте `session.reset`, коли такі +сеанси мають завершуватися за таймером. ## Де зберігається стан -Увесь стан сесії належить **gateway**. Клієнти UI запитують у gateway дані -сесії. +Увесь стан сеансу належить **Gateway**. Клієнти UI звертаються до gateway по +дані сеансу. - **Сховище:** `~/.openclaw/agents//sessions/sessions.json` - **Стенограми:** `~/.openclaw/agents//sessions/.jsonl` -## Обслуговування сесій +`sessions.json` зберігає окремі часові мітки життєвого циклу: -OpenClaw автоматично обмежує обсяг сховища сесій із часом. За замовчуванням він працює +- `sessionStartedAt`: коли почався поточний `sessionId`; це використовується для щоденного скидання. +- `lastInteractionAt`: остання взаємодія користувача/каналу, яка подовжує строк життя до скидання після простою. +- `updatedAt`: остання зміна рядка сховища; корисно для списків і очищення, але + не є авторитетним джерелом для актуальності щоденного скидання/скидання після простою. + +Старіші рядки без `sessionStartedAt` визначаються з заголовка сеансу в JSONL-стенограмі, +якщо він доступний. Якщо в старішому рядку також немає `lastInteractionAt`, +актуальність простою повертається до часу початку цього сеансу, а не до пізніших службових +записів. + +## Обслуговування сеансів + +OpenClaw автоматично обмежує обсяг сховища сеансів з часом. За замовчуванням він працює в режимі `warn` (повідомляє, що було б очищено). Установіть `session.maintenance.mode` у `"enforce"` для автоматичного очищення: @@ -105,26 +124,26 @@ OpenClaw автоматично обмежує обсяг сховища сес Попередній перегляд: `openclaw sessions cleanup --dry-run`. -## Перегляд сесій +## Перегляд сеансів -- `openclaw status` -- шлях до сховища сесій і нещодавня активність. -- `openclaw sessions --json` -- усі сесії (фільтруйте через `--active `). -- `/status` у чаті -- використання контексту, модель і перемикачі. -- `/context list` -- що входить до system prompt. +- `openclaw status` — шлях до сховища сеансів і нещодавня активність. +- `openclaw sessions --json` — усі сеанси (фільтруйте за допомогою `--active `). +- `/status` у чаті — використання контексту, модель і перемикачі. +- `/context list` — що входить до системного prompt. ## Додаткове читання -- [Session Pruning](/uk/concepts/session-pruning) -- обрізання результатів інструментів -- [Compaction](/uk/concepts/compaction) -- підсумовування довгих розмов -- [Session Tools](/uk/concepts/session-tool) -- інструменти агента для міжсесійної роботи -- [Поглиблений огляд керування сесіями](/uk/reference/session-management-compaction) -- +- [Обрізання сеансів](/uk/concepts/session-pruning) — обрізання результатів інструментів +- [Compaction](/uk/concepts/compaction) — підсумовування довгих розмов +- [Інструменти сеансу](/uk/concepts/session-tool) — інструменти агента для роботи між сеансами +- [Поглиблений огляд керування сеансами](/uk/reference/session-management-compaction) -- схема сховища, стенограми, політика надсилання, метадані походження та розширена конфігурація -- [Multi-Agent](/uk/concepts/multi-agent) — маршрутизація та ізоляція сесій між агентами -- [Фонові завдання](/uk/automation/tasks) — як відокремлена робота створює записи завдань із посиланнями на сесії -- [Маршрутизація каналів](/uk/channels/channel-routing) — як вхідні повідомлення маршрутизуються до сесій +- [Багатоагентність](/uk/concepts/multi-agent) — маршрутизація та ізоляція сеансів між агентами +- [Фонові завдання](/uk/automation/tasks) — як відокремлена робота створює записи завдань із посиланнями на сеанси +- [Маршрутизація каналів](/uk/channels/channel-routing) — як вхідні повідомлення маршрутизуються до сеансів -## Пов’язано +## Пов’язане -- [Session pruning](/uk/concepts/session-pruning) -- [Session tools](/uk/concepts/session-tool) +- [Обрізання сеансів](/uk/concepts/session-pruning) +- [Інструменти сеансу](/uk/concepts/session-tool) - [Черга команд](/uk/concepts/queue) diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index ff9094e06..cea3229fd 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,28 +1,28 @@ --- read_when: - - Налаштування типових параметрів агента (моделі, мислення, робочий простір, Heartbeat, медіа, Skills) + - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування сесії, доставки повідомлень і поведінки режиму talk + - Налаштування поведінки сесії, доставки повідомлень і режиму talk summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-25T20:13:31Z" + generated_at: "2026-04-26T01:42:40Z" model: gpt-5.4 provider: openai - source_hash: 0f072438d8445e494b296d2d48f31841292f55758270c2f8095df5c89a6ba013 + source_hash: 2c2027d1abd522c88ad91b2f9596a1aa27da3af8d87fddf42919119c75490060 source_path: gateway/config-agents.md workflow: 15 --- Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`, -`messages.*` і `talk.*`. Для каналів, інструментів, runtime Gateway та інших -ключів верхнього рівня див. [Довідник конфігурації](/uk/gateway/configuration-reference). +`messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших +ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). ## Типові параметри агента ### `agents.defaults.workspace` -За замовчуванням: `~/.openclaw/workspace`. +Типове значення: `~/.openclaw/workspace`. ```json5 { @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись вгору від робочого простору. +Необов’язковий корінь репозиторію, що відображається в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, рухаючись угору від робочого простору. ```json5 { @@ -58,11 +58,11 @@ x-i18n: } ``` -- Не вказуйте `agents.defaults.skills`, щоб Skills за замовчуванням були без обмежень. +- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. - Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. -- Встановіть `agents.list[].skills: []`, щоб не було Skills. -- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; - він не об’єднується з типовими значеннями. +- Укажіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. +- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він + не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` @@ -76,10 +76,10 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору вбудовуються в системний prompt. За замовчуванням: `"always"`. +Керує тим, коли bootstrap-файли робочого простору додаються до системного запиту. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap-контексту робочого простору, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. -- `"never"`: вимикає вбудовування bootstrap-файлів робочого простору та context-файлів на кожному ході. Використовуйте це лише для агентів, які повністю керують власним життєвим циклом prompt (власні context-рушії, нативні runtime, що самі будують свій контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають вбудовування. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне додавання bootstrap-контексту робочого простору, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"never"`: вимикає додавання bootstrap-файлів робочого простору та контекстних файлів на кожному ході. Використовуйте це лише для агентів, які повністю керують життєвим циклом свого запиту (власні рушії контексту, нативні середовища виконання, що самі формують контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають додавання контексту. ```json5 { @@ -89,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл робочого простору до обрізання. За замовчуванням: `12000`. +Максимальна кількість символів для кожного bootstrap-файлу робочого простору перед обрізанням. Типове значення: `12000`. ```json5 { @@ -99,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів робочого простору. За замовчуванням: `60000`. +Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. ```json5 { @@ -109,12 +109,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. -За замовчуванням: `"once"`. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. +Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний prompt. -- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). -- `"always"`: вбудовувати попередження під час кожного запуску, якщо є обрізання. +- `"off"`: ніколи не додає текст попередження до системного запиту. +- `"once"`: додає попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: додає попередження під час кожного запуску, якщо є обрізання. ```json5 { @@ -122,24 +122,24 @@ x-i18n: } ``` -### Карта володіння бюджетом контексту +### Карта власності бюджетів контексту -OpenClaw має кілька великих бюджетів prompt/контексту, і вони -навмисно розділені між підсистемами, а не проходять через один загальний +OpenClaw має кілька великих бюджетів запиту/контексту, і вони +навмисно розділені за підсистемами, а не проходять через один загальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне вбудовування bootstrap робочого простору. + звичайне додавання bootstrap-контексту робочого простору. - `agents.defaults.startupContext.*`: - одноразова стартова прелюдія для `/new` і `/reset`, включно з нещодавніми - щоденними файлами `memory/*.md`. + одноразова стартова преамбула для `/new` і `/reset`, включно з нещодавніми + файлами `memory/*.md`. - `skills.limits.*`: - компактний список Skills, вбудований у системний prompt. + компактний список Skills, що додається до системного запиту. - `agents.defaults.contextLimits.*`: - обмежені runtime-уривки та вбудовані блоки, якими володіє runtime. + обмежені уривки середовища виконання та додані блоки, що належать середовищу виконання. - `memory.qmd.limits.*`: - розміри фрагментів індексованого пошуку в пам’яті та їх вбудовування. + розмір фрагментів і додавання під час пошуку в індексованій пам’яті. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -149,7 +149,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `agents.defaults.startupContext` -Керує стартовою прелюдією першого ходу, яка вбудовується під час простих запусків `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, яка додається під час звичайних запусків `/new` і `/reset`. ```json5 { @@ -170,7 +170,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `agents.defaults.contextLimits` -Спільні типові значення для обмежених поверхонь runtime-контексту. +Спільні типові значення для обмежених поверхонь контексту середовища виконання. ```json5 { @@ -187,18 +187,18 @@ OpenClaw має кілька великих бюджетів prompt/контек } ``` -- `memoryGetMaxChars`: типове обмеження уривка `memory_get` до додавання - метаданих обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines` +- `memoryGetMaxChars`: типове обмеження уривка `memory_get` перед додаванням + метаданих обрізання та сповіщення про продовження. +- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` не вказано. -- `toolResultMaxChars`: обмеження для результатів інструментів у live-режимі, яке використовується для збережених результатів і +- `toolResultMaxChars`: поточне обмеження результату інструмента, що використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: обмеження уривка AGENTS.md, що використовується під час вбудовування +- `postCompactionMaxChars`: обмеження уривка `AGENTS.md`, що використовується під час додавання оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Поля, які не вказано, успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -225,7 +225,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, який вбудовується в системний prompt. Це +Глобальне обмеження для компактного списку Skills, що додається до системного запиту. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -240,7 +240,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету prompt Skills. +Перевизначення для окремого агента для бюджету запиту Skills. ```json5 { @@ -259,8 +259,8 @@ OpenClaw має кілька великих бюджетів prompt/контек ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. -За замовчуванням: `1200`. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. +Типове значення: `1200`. Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload запиту для сценаріїв із великою кількістю скриншотів. Вищі значення зберігають більше візуальних деталей. @@ -273,7 +273,7 @@ OpenClaw має кілька великих бюджетів prompt/контек ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -283,7 +283,7 @@ OpenClaw має кілька великих бюджетів prompt/контек ### `agents.defaults.timeFormat` -Формат часу в системному prompt. За замовчуванням: `auto` (налаштування ОС). +Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -323,7 +323,7 @@ OpenClaw має кілька великих бюджетів prompt/контек }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "pi", // pi | auto | id зареєстрованого harness, наприклад codex + runtime: "pi", // pi | auto | зареєстрований ідентифікатор harness, наприклад codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -342,52 +342,52 @@ OpenClaw має кілька великих бюджетів prompt/контек - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список моделей для аварійного перемикання. + - Форма об’єкта задає основну модель і впорядкований список резервних моделей. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. + - Використовується шляхом інструмента `image` як конфігурація його vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal, `openai/gpt-image-2` для OpenAI Images або `openai/gpt-image-1.5` для виводу OpenAI PNG/WebP із прозорим фоном. - - Якщо ви напряму вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` для `fal/*`). - - Якщо значення не задано, `image_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструментів/Plugin, що генерує зображення. + - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal, `openai/gpt-image-2` для OpenAI Images або `openai/gpt-image-1.5` для прозорого PNG/WebP-виводу OpenAI. + - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` для `fal/*`). + - Якщо параметр не вказано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.6`. - - Якщо значення не задано, `music_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики у порядку provider-id. - - Якщо ви напряму вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо параметр не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API key. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо значення не задано, `video_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео у порядку provider-id. - - Якщо ви напряму вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо параметр не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API key. - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо значення не задано, інструмент PDF використовує як резерв `imageModel`, а потім визначену модель сесії/типову модель. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, які враховуються режимом резервного витягування в інструменті `pdf`. -- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. За замовчуванням: `"off"`. -- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. За замовчуванням: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви не вкажете провайдера, OpenClaw спочатку спробує псевдонім, потім — унікальний збіг серед налаштованих провайдерів для цього точного id моделі, і лише після цього повернеться до налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переключиться на першу налаштовану пару провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. + - Використовується інструментом `pdf` для маршрутизації моделей. + - Якщо параметр не вказано, інструмент PDF використовує резервний перехід до `imageModel`, а потім до визначеної моделі сесії/типової моделі. +- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, якщо `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного вилучення в інструменті `pdf`. +- `verboseDefault`: типовий рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. +- `elevatedDefault`: типовий рівень розширеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API key або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спочатку пробує alias, потім — унікальний збіг серед налаштованих провайдерів для точного ідентифікатора моделі, і лише після цього використовує типового налаштованого провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель, замість того щоб показувати застаріле типове значення видаленого провайдера. - `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). - - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи зі списку дозволених значень, якщо ви не передасте `--replace`. - - Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають інші вже налаштовані провайдери. - - Для прямих моделей OpenAI Responses server-side Compaction вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити вбудовування `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [server-side compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відхиляє заміни, які видалили б наявні записи зі списку дозволених значень, якщо не передано `--replace`. + - Потоки налаштування/онбордингу для провайдера об’єднують вибрані моделі провайдера в цю мапу й зберігають інші вже налаштовані провайдери. + - Для прямих моделей OpenAI Responses compaction на стороні сервера вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Compaction на стороні сервера OpenAI](/uk/providers/openai#server-side-compaction-responses-api). - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. [Кешування prompt](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений JSON passthrough, який об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, перемагає extra body; маршрути completions, які не є нативними, після цього все одно видаляють специфічний для OpenAI `store`. -- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Якщо runtime не вказано, за замовчуванням використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness Plugin перехоплювати підтримувані моделі, або id зареєстрованого harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. Явні runtime Plugin, такі як `codex`, за замовчуванням аварійно завершуються без резервного переходу, якщо ви не встановите `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime-провайдерів. Див. [runtime агентів](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди add/remove для резервних значень), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки резервних значень. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів у межах сесій (кожна сесія все одно серіалізується). За замовчуванням: 4. +- Порядок пріоритету об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). +- `params.extra_body`/`params.extraBody`: розширений pass-through JSON, який об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, перемагає додаткове тіло; маршрути completions, які не є нативними, після цього все одно видаляють специфічний для OpenAI параметр `store`. +- `embeddedHarness`: типова політика низькорівневого середовища виконання для вбудованого агента. Якщо `runtime` не вказано, типово використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, `runtime: "auto"`, щоб зареєстровані harness-и Plugin могли перехоплювати підтримувані моделі, або зареєстрований ідентифікатор harness, як-от `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Явні середовища виконання Plugin, як-от `codex`, типово працюють у режимі fail closed, якщо в цій самій області перевизначення не встановлено `fallback: "pi"`. Зберігайте посилання на моделі в канонічній формі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime провайдера. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. +- Засоби запису конфігурації, що змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та за можливості зберігають наявні списки резервних моделей. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно виконується послідовно). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань слід залишити типовий runtime OpenClaw Pi. +У більшості розгортань слід залишати типове середовище виконання OpenClaw Pi. Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований harness сервера застосунку Codex. Для розуміння моделі див. -[runtime агентів](/uk/concepts/agent-runtimes). +[Середовища виконання агента](/uk/concepts/agent-runtimes). ```json5 { @@ -403,16 +403,16 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Вбудований Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущений fallback за замовчуванням дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден harness Plugin не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущений fallback за замовчуванням дорівнює `"none"`, щоб відсутній harness спричинив помилку, а не тихо використовував PI. Перевизначення runtime не успадковують fallback із ширшої області; встановлюйте `fallback: "pi"` поруч з явним runtime, коли вам навмисно потрібна така сумісність резервного переходу. Помилки вибраного harness Plugin завжди показуються безпосередньо. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає fallback для цього процесу. -- Для розгортань лише з Codex встановіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно встановити `embeddedHarness.fallback: "none"` для читабельності; це типове значення для явних runtime Plugin. -- Вибір harness фіксується для кожного id сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, а не на наявний transcript. Застарілі сесії з історією transcript, але без зафіксованого вибору, вважаються прив’язаними до PI. `/status` показує фактичний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. -- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування провайдера/моделі. +- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness Plugin. Вбудований Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущене значення `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й надалі використовувати PI, якщо жоден harness Plugin не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущене значення `fallback` типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість тихого переходу на PI. Перевизначення runtime не успадковують `fallback` із ширшої області; установіть `fallback: "pi"` поруч із явним runtime, якщо вам свідомо потрібен цей сумісний резервний перехід. Помилки вибраного harness Plugin завжди відображаються безпосередньо. +- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу. +- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для зрозумілості також можна явно встановити `embeddedHarness.fallback: "none"`; це типове значення для явних runtime Plugin. +- Вибір harness закріплюється за ідентифікатором сесії після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без зафіксованого pin, вважаються закріпленими за PI. `/status` повідомляє ефективний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS, як і раніше, використовують свої налаштування провайдера/моделі. -**Вбудовані скорочення-псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Псевдонім | Модель | +| Alias | Модель | | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -423,15 +423,15 @@ harness сервера застосунку Codex. Для розуміння м | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. +Налаштовані вами alias завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. -Для моделей Z.AI за замовчуванням вмикається `tool_stream` для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути його. -Для моделей Anthropic Claude 4.6 за замовчуванням використовується thinking `adaptive`, коли явний рівень thinking не задано. +Для моделей Z.AI GLM-4.x режим thinking автоматично вмикається, якщо ви не встановили `--thinking off` або самостійно не визначили `agents.defaults.models["zai/"].params.thinking`. +Для моделей Z.AI типово вмикається `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо явний рівень thinking не встановлено. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних текстових запусків (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові бекенди CLI для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. ```json5 { @@ -449,7 +449,7 @@ harness сервера застосунку Codex. Для розуміння м sessionArg: "--session", sessionMode: "existing", systemPromptArg: "--system", - // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець файла prompt. + // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець для файла запиту. systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -460,13 +460,13 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли задано `sessionArg`. -- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Бекенди CLI орієнтовані насамперед на текст; інструменти завжди вимкнені. +- Сесії підтримуються, якщо задано `sessionArg`. +- Передавання зображень підтримується, якщо `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -480,7 +480,7 @@ harness сервера застосунку Codex. Для розуміння м ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладки prompt, які застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний поведінковий контракт для всіх провайдерів; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -496,8 +496,8 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. -- `"off"` вимикає лише дружній шар; позначений поведінковий контракт GPT-5 залишається ввімкненим. +- `"friendly"` (типове значення) і `"on"` вмикають дружній шар стилю взаємодії. +- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. - Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -512,12 +512,12 @@ harness сервера застосунку Codex. Для розуміння м every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типове значення: true; false не включає секцію Heartbeat до системного prompt - lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md з bootstrap-файлів робочого простору - isolatedSession: false, // типове значення: false; true запускає кожен Heartbeat у новій сесії (без історії розмови) + includeSystemPromptSection: true, // типове значення: true; false не додає розділ Heartbeat до системного запиту + lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору + isolatedSession: false, // типове значення: false; true запускає кожен heartbeat у новій сесії (без історії розмови) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (типове значення) | block + directPolicy: "allow", // allow (типово) | block target: "none", // типове значення: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, @@ -529,15 +529,15 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли значення false, секція Heartbeat не включається до системного prompt, а `HEARTBEAT.md` не вбудовується в bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли значення true, попередження про помилки інструментів під час запусків Heartbeat не показуються. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його переривання. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/DM. `allow` (типове значення) дозволяє доставку до прямої цілі. `block` блокує доставку до прямої цілі та видає `reason=dm-blocked`. -- `lightContext`: коли значення true, запуски Heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `isolatedSession`: коли значення true, кожен Heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на кожен Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **Heartbeat запускається лише для цих агентів**. -- Heartbeat виконує повноцінні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо `false`, не додає розділ Heartbeat до системного запиту й пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо `true`, приховує payload-и попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після чого його буде перервано. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика доставки напряму/в DM. `allow` (типове значення) дозволяє доставку напряму до цілі. `block` блокує доставку напряму до цілі та видає `reason=dm-blocked`. +- `lightContext`: якщо `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: якщо `true`, кожен запуск Heartbeat відбувається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі ~100K до ~2–5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **лише ці агенти** запускають Heartbeat. +- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -554,9 +554,9 @@ harness сервера застосунку Codex. Для розуміння м identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для Compaction - notifyUser: true, // надсилати короткі сповіщення користувачу, коли Compaction починається й завершується (типове значення: false) + notifyUser: true, // надсилати короткі сповіщення користувачу, коли Compaction починається і завершується (типове значення: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -569,21 +569,21 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- `mode`: `default` або `safeguard` (підсумовування шматками для довгої історії). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки виконується повернення до вбудованого механізму. Встановлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки використовується вбудований механізм. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). - `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найсвіжішого хвоста transcript дослівно. Ручний `/compact` враховує це, коли значення явно задано; інакше ручний Compaction є жорсткою контрольною точкою. -- `identifierPolicy`: `strict` (типове значення), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів на початку підсумовування Compaction. -- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`. -- `qualityGuard`: перевірки з повторними спробами для некоректного виводу підсумків safeguard. У режимі safeguard ввімкнено за замовчуванням; встановіть `enabled: false`, щоб пропустити перевірку. -- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які повторно вбудовуються після Compaction. Типове значення: `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторне вбудовування. Якщо значення не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction повинні виконуватися на іншій; якщо значення не задано, Compaction використовує основну модель сесії. -- `notifyUser`: коли `true`, надсилає короткі сповіщення користувачу, коли Compaction починається і коли він завершується (наприклад, "Compacting context..." і "Compaction complete"). За замовчуванням вимкнено, щоб Compaction залишався безшумним. -- `memoryFlush`: тихий агентний хід перед автоматичним Compaction для збереження довготривалої пам’яті. Пропускається, коли робочий простір доступний лише для читання. +- `keepRecentTokens`: бюджет точки відсікання Pi для дослівного збереження найсвіжішого хвоста транскрипту. Ручна команда `/compact` враховує це, коли параметр явно встановлено; інакше ручна Compaction є жорсткою контрольною точкою. +- `identifierPolicy`: `strict` (типове значення), `off` або `custom`. `strict` додає вбудовані рекомендації щодо збереження непрозорих ідентифікаторів перед підсумовуванням Compaction. +- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `qualityGuard`: перевірки з повторною спробою для malformed output у підсумках safeguard. У режимі safeguard ввімкнено типово; установіть `enabled: false`, щоб пропустити аудит. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з `AGENTS.md`, які слід повторно додати після Compaction. Типово: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне додавання. Якщо параметр не задано або явно встановлено цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишитися на одній моделі, а підсумки Compaction — виконуватися на іншій; якщо параметр не задано, Compaction використовує основну модель сесії. +- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишалася безшумною. +- `memoryFlush`: тихий агентний хід перед автоматичною Compaction для збереження довготривалих записів у пам’яті. Пропускається, якщо робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Очищає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -607,25 +607,25 @@ harness сервера застосунку Codex. Для розуміння м -- `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися повторно (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. +- `mode: "cache-ttl"` вмикає проходи очищення. +- `ttl` керує тим, як часто очищення може запускатися знову (після останнього торкання кешу). +- Очищення спочатку м’яко обрізає завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента на заповнювач. +**Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: - Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення обчислюються за кількістю символів (приблизно), а не за точною кількістю токенів. -- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, очищення пропускається. -Докладніше про поведінку див. [Обрізання сесії](/uk/concepts/session-pruning). +Докладніше про поведінку див. [Очищення сесії](/uk/concepts/session-pruning). -### Блокове потокове передавання +### Потокове передавання блоками ```json5 { @@ -641,13 +641,13 @@ harness сервера застосунку Codex. Для розуміння м } ``` -- Для каналів, відмінних від Telegram, потрібно явно задати `*.blockStreaming: true`, щоб увімкнути відповіді блоками. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. -- `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, потрібне явне `*.blockStreaming: true`, щоб увімкнути відповіді блоками. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. +- `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку й розбиття на блоки див. [Потокове передавання](/uk/concepts/streaming). +Докладніше про поведінку й розбиття на блоки див. [Streaming](/uk/concepts/streaming). -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -661,15 +661,15 @@ harness сервера застосунку Codex. Для розуміння м ``` - Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для окремої сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Індикатори набору](/uk/concepts/typing-indicators). +Докладніше див. [Індикатори набору тексту](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язкове sandbox-ізолювання для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язковий sandbox для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -715,7 +715,7 @@ harness сервера застосунку Codex. Для розуміння м identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Також підтримуються SecretRefs / вбудований вміст: + // Також підтримуються SecretRefs / inline contents: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -764,51 +764,51 @@ harness сервера застосунку Codex. Для розуміння м } ``` - + **Бекенд:** -- `docker`: локальний runtime Docker (типове значення) -- `ssh`: універсальний віддалений runtime на основі SSH -- `openshell`: runtime OpenShell +- `docker`: локальне середовище виконання Docker (типово) +- `ssh`: загальне віддалене середовище виконання на основі SSH +- `openshell`: середовище виконання OpenShell Коли вибрано `backend: "openshell"`, специфічні для runtime налаштування переносяться до `plugins.entries.openshell.config`. -**Конфігурація SSH-бекенда:** +**Конфігурація бекенда SSH:** -- `target`: ціль SSH у формі `user@host[:port]` +- `target`: ціль SSH у форматі `user@host[:port]` - `command`: команда клієнта SSH (типове значення: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, який використовується для робочих просторів у межах області дії -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує в тимчасові файли під час виконання +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах кожної області +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Пріоритет автентифікації SSH:** +**Порядок пріоритету автентифікації SSH:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox +- Значення `*Data`, що базуються на SecretRef, визначаються з активного snapshot середовища виконання секретів до запуску сесії sandbox -**Поведінка SSH-бекенда:** +**Поведінка бекенда SSH:** - один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім зберігає віддалений робочий простір SSH як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH +- потім зберігає віддалений SSH-робочий простір як канонічний +- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично - не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox у межах області дії під `~/.openclaw/sandboxes` +- `none`: робочий простір sandbox для кожної області в `~/.openclaw/sandboxes` - `ro`: робочий простір sandbox у `/workspace`, робочий простір агента монтується лише для читання в `/agent` - `rw`: робочий простір агента монтується для читання й запису в `/workspace` -**Область дії:** +**Область:** -- `session`: контейнер і робочий простір на кожну сесію -- `agent`: один контейнер і робочий простір на агента (типове значення) +- `session`: окремий контейнер + робочий простір для кожної сесії +- `agent`: один контейнер + робочий простір для кожного агента (типово) - `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -840,29 +840,29 @@ harness сервера застосунку Codex. Для розуміння м **Режим OpenShell:** - `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, а потім зберігає віддалений робочий простір як канонічний +- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, після чого віддалений робочий простір залишається канонічним -У режимі `remote` зміни на хості, зроблені локально поза OpenClaw, не синхронізуються автоматично до sandbox після етапу ініціалізації. -Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією керує Plugin. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потрібні вихід у мережу, доступний для запису корінь і користувач root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, доступного для запису кореня та користувача root. -**Для контейнерів за замовчуванням використовується `network: "none"`** — установіть `"bridge"` (або власну мережу bridge), якщо агенту потрібен вихід назовні. -`"host"` заблоковано. `"container:"` за замовчуванням також заблоковано, якщо ви явно не встановите +**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або користувацьку bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). -**Вхідні вкладення** розміщуються в `media/inbound/*` у активному робочому просторі. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні та для окремого агента `binds` об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача через noVNC за замовчуванням використовує автентифікацію VNC, а OpenClaw видає URL із короткочасним токеном (замість того, щоб показувати пароль у спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). -- `allowHostControl: false` (типове значення) блокує націлювання сесій sandbox на браузер хоста. -- `network` за замовчуванням дорівнює `openclaw-sandbox-browser` (виділена мережа bridge). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. -- `cdpSourceRange` за потреби обмежує вхідний доступ CDP на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в браузерний контейнер sandbox. Якщо задано (включно з `[]`), це замінює `docker.binds` для браузерного контейнера. -- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів із контейнерами: +- `allowHostControl: false` (типове значення) блокує націлювання із sandbox-сесій на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність через bridge. +- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо параметр задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для хостів із контейнерами: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -881,25 +881,25 @@ harness сервера застосунку Codex. Для розуміння м - `--metrics-recording-only` - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - увімкнені за замовчуванням і можуть бути вимкнені через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо вони - потрібні вашому робочому процесу. + типово ввімкнені, і їх можна вимкнути за допомогою + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + від них залежить. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - а також `--no-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; щоб змінити стандартні параметри контейнера, використовуйте власний - образ браузера з власним entrypoint. + - Типові параметри є базою образу контейнера; використовуйте власний образ браузера з власною + точкою входу, щоб змінити типові параметри контейнера. -Ізоляція браузера та `sandbox.docker.binds` підтримуються лише в Docker. +Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. -Збирання образів: +Збірка образів: ```bash -scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-setup.sh # головний образ sandbox scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` @@ -918,9 +918,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } thinkingDefault: "high", // перевизначення рівня thinking для окремого агента reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента - fastModeDefault: false, // перевизначення fast mode для окремого агента + fastModeDefault: false, // перевизначення швидкого режиму для окремого агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає відповідні defaults.models params за ключем + params: { cacheRetention: "none" }, // перевизначає ключі у відповідних defaults.models params skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", @@ -952,27 +952,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `id`: стабільний id агента (обов’язково). -- `default`: якщо задано для кількох агентів, перемагає перший (записується попередження). Якщо не задано ні для кого, типовим є перший запис у списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва значення (`[]` вимикає глобальні резервні значення). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні значення, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, якщо ті задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення є допустимими; для Google Gemini значення `adaptive` зберігає динамічне thinking, яким керує провайдер (`thinkingLevel` не задається для Gemini 3/3.1, `thinkingBudget: -1` для Gemini 2.5). -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, а інші агенти залишити з типовим резервним PI в режимі `auto`. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент за замовчуванням має використовувати сесії harness ACP. +- `id`: стабільний ідентифікатор агента (обов’язково). +- `default`: якщо задано для кількох агентів, використовується перший (записується попередження). Якщо не задано для жодного, типовим є перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва значення (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе ще успадковують типові резервні моделі, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли його встановлено; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення є допустимими; для Google Gemini значення `adaptive` залишає динамічний thinking під керуванням провайдера (`thinkingLevel` не задається в Gemini 3/3.1, `thinkingBudget: -1` у Gemini 2.5). +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти збережуть типовий резервний перехід до PI в режимі `auto`. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. - `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типове значення: лише той самий агент). -- Захист успадкування sandbox: якщо сесія ініціатора виконується в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: коли значення true, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типове значення: false). +- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сесія запитувача виконується в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація між кількома агентами -Запускайте кілька ізольованих агентів в одному Gateway. Див. [Мультиагентність](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів в одному Gateway. Див. [Кілька агентів](/uk/concepts/multi-agent). ```json5 { @@ -989,16 +989,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля збігу прив’язки +### Поля збігу binding -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, за замовчуванням використовується route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо `type` відсутній, типово використовується route), `acp` для постійних binding розмов ACP. - `match.channel` (обов’язково) - `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; для конкретних каналів) +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок збігів:** +**Детермінований порядок збігу:** 1. `match.peer` 2. `match.guildId` @@ -1007,11 +1007,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б 5. `match.accountId: "*"` (на рівні всього каналу) 6. Типовий агент -У межах кожного рівня перемагає перший відповідний запис `bindings`. +У межах кожного рівня перемагає перший відповідний запис у `bindings`. -Для записів `type: "acp"` OpenClaw визначає збіг за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів прив’язок route, наведений вище. +Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding. -### Профілі доступу для окремих агентів +### Профілі доступу для окремого агента @@ -1060,7 +1060,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1106,7 +1106,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Докладніше про пріоритети див. [Sandbox і інструменти для мультиагентності](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. [Sandbox і інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools). --- @@ -1132,7 +1132,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропускати відгалуження від батьківського потоку, якщо кількість токенів перевищує це значення (0 вимикає) + parentForkMaxTokens: 100000, // пропускати відгалуження від батьківського треду вище цього ліміту токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1144,8 +1144,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, threadBindings: { enabled: true, - idleHours: 24, // типове значення авто-втрати фокусу після неактивності в годинах (`0` вимикає) - maxAgeHours: 0, // типове значення жорсткого максимального віку в годинах (`0` вимикає) + idleHours: 24, // типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає) + maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) }, mainKey: "main", // застаріле поле (runtime завжди використовує "main") agentToAgent: { maxPingPongTurns: 5 }, @@ -1157,37 +1157,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групових чатів. - `per-sender` (типове значення): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст є бажаним). + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM спільно використовують головну сесію. - - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних вхідних скриньок). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: мапа канонічних id до peer із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Коли налаштовано обидва варіанти, спрацьовує той, який настає раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення відгалуженої сесії потоку (типове значення `100000`). - - Якщо значення `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії transcript батьківської сесії. + - `main`: усі DM спільно використовують основну сесію. + - `per-peer`: ізоляція за ідентифікатором відправника між каналами. + - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для скриньок із багатьма користувачами). + - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). +- **`identityLinks`**: мапа канонічних id до peer-ідентифікаторів із префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає те, що спливає раніше. Актуальність щоденного скидання використовує `sessionStartedAt` у рядку сесії; актуальність скидання через неактивність використовує `lastInteractionAt`. Фонові/системні записи, такі як Heartbeat, пробудження Cron, сповіщення exec і службові записи Gateway, можуть оновлювати `updatedAt`, але вони не підтримують актуальність щоденних/неактивних сесій. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як alias для `direct`. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення відгалуженої сесії треду (типове значення `100000`). + - Якщо значення `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію треду замість успадкування історії транскрипту батьківської сесії. - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. - **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді у відповідь між агентами під час обмінів агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сесій + керування зберіганням. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. +- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: очищення сховища сесій + контроль утримання. - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг віку для застарілих записів (типове значення `30d`). + - `pruneAfter`: віковий поріг для застарілих записів (типове значення `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типове значення `500`). - - `rotateBytes`: ротація `sessions.json`, коли його розмір перевищує це значення (типове значення `10mb`). - - `resetArchiveRetention`: строк зберігання архівів transcript `*.reset.`. За замовчуванням дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` лише записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення бюджету. За замовчуванням дорівнює `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. + - `rotateBytes`: ротує `sessions.json`, коли файл перевищує цей розмір (типове значення `10mb`). + - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` він записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово — `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове значення авто-втрати фокусу після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типове значення жорсткого максимального віку в годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1225,36 +1225,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Префікс відповіді -Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення значення (перемагає найспецифічніше): обліковий запис → канал → глобальне. `""` вимикає значення і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ------------------------ | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — це alias для `{thinkingLevel}`. -### Реакція-підтвердження +### Реакція підтвердження -- За замовчуванням використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. +- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. - Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. -- Область дії: `group-mentions` (типове значення), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram. - У Slack і Discord незадане значення залишає реакції статусу ввімкненими, коли активні реакції-підтвердження. - У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу. +- Область: `group-mentions` (типове значення), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: прибирає підтвердження після відповіді в Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає статусні реакції життєвого циклу в Slack, Discord і Telegram. + У Slack і Discord, якщо значення не задано, статусні реакції залишаються ввімкненими, коли активні реакції підтвердження. + У Telegram, щоб увімкнути статусні реакції життєвого циклу, явно встановіть `true`. ### Inbound debounce -Групує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. +Групує швидкі текстові повідомлення від одного й того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди оминають debounce. ### TTS (синтез мовлення) @@ -1304,13 +1304,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує типовим режимом авто-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для авто-підсумку. -- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням дорівнює `false` (лише за явної згоди). -- API-ключі використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- Вбудовані мовні провайдери належать Plugin. Якщо задано `plugins.allow`, додайте кожен Plugin провайдера TTS, який ви хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як псевдонім для `microsoft`. -- `providers.openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `providers.openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw розглядає його як OpenAI-сумісний сервер TTS і послаблює перевірку моделі/голосу. +- `auto` керує типовим автоматичним режимом TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (увімкнення за бажанням). +- API key резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані мовні провайдери належать Plugin. Якщо задано `plugins.allow`, додайте кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як alias для `microsoft`. +- `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `providers.openai.baseUrl` вказує на не-OpenAI endpoint, OpenClaw розглядає його як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. --- @@ -1345,21 +1345,21 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) існують лише для сумісності й автоматично мігруються до `talk.providers.`. -- Для voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `talk.provider` має відповідати ключу в `talk.providers`, якщо налаштовано кілька провайдерів Talk. +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності й автоматично мігруються до `talk.providers.`. +- Для Voice ID використовуються резервні значення з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. - `providers.*.apiKey` приймає рядки відкритим текстом або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. - `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. -- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовує локальний помічник MLX для macOS. Якщо значення не задано, macOS використовує `mlx-community/Soprano-80M-bf16`. -- Відтворення MLX на macOS виконується через вбудований помічник `openclaw-mlx-tts`, якщо він є, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. -- `speechLocale` задає id локалі BCP 47, який використовується розпізнаванням мовлення Talk в iOS/macOS. Залиште незаданим, щоб використовувати типове значення пристрою. -- `silenceTimeoutMs` визначає, як довго режим Talk чекає після тиші користувача перед надсиланням transcript. Якщо значення не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовує локальний помічник macOS MLX. Якщо параметр не вказано, у macOS використовується `mlx-community/Soprano-80M-bf16`. +- Відтворення MLX у macOS виконується через вбудований помічник `openclaw-mlx-tts`, якщо він наявний, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. +- `speechLocale` задає ідентифікатор локалі BCP 47, який використовується для розпізнавання мовлення Talk в iOS/macOS. Якщо не вказано, використовується типова локаль пристрою. +- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після тиші користувача, перш ніж надіслати транскрипт. Якщо параметр не вказано, зберігається типове вікно паузи платформи (`700 ms` на macOS і Android, `900 ms` на iOS). --- ## Пов’язане -- [Довідник конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації -- [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування +- [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації +- [Конфігурація](/uk/gateway/configuration) — типові завдання та швидке налаштування - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 9f89af230..3c9a7b8ed 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -2,34 +2,34 @@ read_when: - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник із конфігурації +summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-26T00:29:06Z" + generated_at: "2026-04-26T01:42:39Z" model: gpt-5.4 provider: openai - source_hash: 68f5c85de3277249c2e748cccad21354b687320e47a308a22633090633353363 + source_hash: 6197fab3f114cf237de46ea7c06c355be179e7b78ae39920b45bb094a04127b9 source_path: gateway/configuration-reference.md workflow: 15 --- -Основний довідник із конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). +Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний, глибший довідник. Каталоги команд, що належать каналам і Plugin, а також поглиблені параметри пам’яті/QMD винесені на окремі сторінки, а не зібрані тут. +Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і Plugin, а також детальні параметри пам’яті/QMD винесені на окремі сторінки, а не описуються тут. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із злитими метаданими bundled/Plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізованого перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації на відповідність поточній поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із вбудованими метаданими bundled/plugin/channel, об’єднаними за наявності +- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового стану документації конфігурації щодо поточної поверхні схеми Окремі поглиблені довідники: - [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` - [Slash commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки відповідних channel/Plugin для поверхонь команд, специфічних для каналу +- сторінки каналу/Plugin-власника для специфічних для каналу поверхонь команд -Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- @@ -38,30 +38,29 @@ x-i18n: Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див. [Configuration — channels](/uk/gateway/config-channels) для `channels.*`, зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших -bundled каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками). +вбудованих каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками). -## Значення агента за замовчуванням, мультиагентність, сесії та повідомлення +## Типові значення агента, multi-agent, сесії та повідомлення Перенесено на окрему сторінку — див. [Configuration — agents](/uk/gateway/config-agents) для: - `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox) -- `multiAgent.*` (маршрутизація та прив’язки мультиагентності) -- `session.*` (життєвий цикл сесії, compaction, pruning) +- `multiAgent.*` (маршрутизація та прив’язки multi-agent) +- `session.*` (життєвий цикл сесії, Compaction, обрізання) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - `talk.speechLocale`: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) -## Інструменти та користувацькі провайдери +## Інструменти та власні провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів на базі провайдерів, а також налаштування користувацьких -провайдерів / base-URL перенесені на окрему сторінку — див. +Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних провайдерів / base-URL перенесені на окрему сторінку — див. [Configuration — tools and custom providers](/uk/gateway/config-tools). ## MCP -Визначення MCP-серверів, якими керує OpenClaw, розміщуються в `mcp.servers` і +Визначення MCP-серверів, керованих OpenClaw, знаходяться в `mcp.servers` і використовуються вбудованим Pi та іншими адаптерами середовища виконання. Команди `openclaw mcp list`, `show`, `set` і `unset` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -88,17 +87,17 @@ bundled каналів (автентифікація, контроль дост } ``` -- `mcp.servers`: іменовані визначення stdio- або віддалених MCP-серверів для середовищ виконання, що +- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які надають налаштовані MCP-інструменти. -- `mcp.sessionIdleTtlMs`: idle TTL для bundled MCP-середовищ виконання з областю дії сесії. - Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є - резервним механізмом для довготривалих сесій і майбутніх викликів. -- Зміни в `mcp.*` застосовуються гарячим способом через вивільнення кешованих MCP-середовищ виконання сесії. - Наступне виявлення/використання інструменту відтворює їх із нової конфігурації, тому видалені - записи `mcp.servers` прибираються негайно, а не чекають idle TTL. +- `mcp.sessionIdleTtlMs`: idle TTL для MCP-середовищ виконання в межах сесії. + Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є резервним механізмом для + довготривалих сесій і майбутніх викликів. +- Зміни в `mcp.*` застосовуються гаряче через вивільнення кешованих MCP-середовищ виконання сесії. + Наступне виявлення/використання інструменту створює їх заново з нової конфігурації, тому видалені + записи `mcp.servers` прибираються негайно, а не очікують завершення idle TTL. Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і -[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки під час виконання. +[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) для поведінки середовища виконання. ## Skills @@ -125,14 +124,14 @@ bundled каналів (автентифікація, контроль дост } ``` -- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (керовані/робочі Skills не зачіпаються). -- `load.extraDirs`: додаткові спільні кореневі каталоги Skills (найнижчий пріоритет). +- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/робочі skills не зачіпаються). +- `load.extraDirs`: додаткові спільні кореневі каталоги skills (найнижчий пріоритет). - `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли `brew` доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: уподобання щодо Node-інсталятора для специфікацій `metadata.openclaw.install` +- `install.nodeManager`: пріоритет менеджера Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає Skill, навіть якщо його bundled/встановлено. -- `entries..apiKey`: зручне поле для Skills, які оголошують основну env-змінну (простий текстовий рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він bundled/installed. +- `entries..apiKey`: зручне поле для skills, які оголошують основну змінну середовища (звичайний рядок або об’єкт SecretRef). --- @@ -160,38 +159,38 @@ bundled каналів (автентифікація, контроль дост } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення підтримує нативні OpenClaw Plugins, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного компонування без маніфесту. -- **Зміни конфігурації потребують перезапуску Gateway.** -- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugins). `deny` має пріоритет. +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. +- Виявлення підтримує нативні OpenClaw Plugins, а також сумісні пакети Codex і Claude, включно з пакетами Claude без manifest із типовою структурою каталогів. +- **Зміни конфігурації потребують перезапуску gateway.** +- `allow`: необов’язковий список дозволу (завантажуються лише перелічені Plugins). `deny` має пріоритет. - `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: мапа env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами. -- `plugins.entries..hooks.allowConversationAccess`: якщо `true`, довірені не-bundled Plugins можуть читати необроблений вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явним чином довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагента. Використовуйте `"*"` лише тоді, коли справді хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується нативною схемою Plugin OpenClaw, якщо вона доступна). -- Налаштування облікових записів/середовища виконання channel Plugin розміщуються в `channels.` і мають описуватися метаданими `channelConfigs` маніфесту відповідного Plugin, а не центральним реєстром параметрів OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує як запасний варіант `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. - - `baseUrl`: базова URL-адреса API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). +- `plugins.entries..env`: карта змінних середовища в межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих пакетами. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небудовані Plugins можуть читати необроблений вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових підзапусків subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного OpenClaw Plugin, якщо вона доступна). +- Налаштування облікового запису/середовища виконання для канальних Plugins знаходяться в `channels.` і мають бути описані метаданими `channelConfigs` у manifest Plugin-власника, а не центральним реєстром параметрів OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. + - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`, якщо не задано. + - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту скрапінгу в секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдер X Search. + - `timeoutSeconds`: тайм-аут запиту зчитування в секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web search). + - `enabled`: увімкнути провайдера X Search. - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - `enabled`: головний перемикач dreaming (типово `false`). - `frequency`: Cron-розклад для кожного повного циклу dreaming (типово `"0 3 * * *"`). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): +- Повна конфігурація пам’яті наведена в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Plugins пакетів Claude також можуть додавати вбудовані типові налаштування Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- Увімкнені Plugins-пакети Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як необроблені патчі конфігурації OpenClaw. - `plugins.slots.memory`: вибрати ідентифікатор активного Plugin пам’яті або `"none"`, щоб вимкнути Plugins пам’яті. - `plugins.slots.contextEngine`: вибрати ідентифікатор активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. @@ -249,28 +248,28 @@ bundled каналів (автентифікація, контроль дост - `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера типово залишається суворо обмеженою. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тож навігація браузера типово залишається суворо обмеженою. - Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі кінцеві точки віддалених CDP-профілів (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. +- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. - `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі підтримують лише під’єднання (start/stop/reset вимкнено). +- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнені). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли ваш провайдер надає пряму URL-адресу DevTools WebSocket. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддаленої та - `attachOnly` доступності CDP, а також до запитів відкриття вкладок. Керовані loopback-профілі - зберігають локальні типові значення CDP. -- Якщо до зовнішньо керованого CDP-сервісу можна дістатися через loopback, установіть для цього - профілю `attachOnly: true`; інакше OpenClaw розглядатиме loopback-порт як - локальний керований профіль браузера і може повідомляти про помилки володіння локальним портом. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть під’єднуватися до - вибраного хоста або через підключений browser node. + Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), + якщо ваш провайдер надає вам прямий URL DevTools WebSocket. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддалених і + `attachOnly` перевірок доступності CDP, а також до запитів на відкриття вкладок. Керовані loopback- + профілі зберігають локальні значення CDP за замовчуванням. +- Якщо керований зовні сервіс CDP доступний через loopback, установіть для цього + профілю `attachOnly: true`; інакше OpenClaw трактуватиме loopback-порт як + локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + вибраному хості або через підключений вузол браузера. - Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання за CSS-селекторами, хуки завантаження - одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без + дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks для завантаження одного файла, + без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. @@ -278,17 +277,16 @@ bundled каналів (автентифікація, контроль дост `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший — у Brave. - Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP - після запуску процесу та `browser.localCdpReadyTimeoutMs` для - готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome - успішно запускається, але перевірки готовності випереджають завершення запуску. Обидва значення мають бути - додатними цілими числами до `120000` ms; некоректні значення конфігурації відхиляються. + після запуску процесу та `browser.localCdpReadyTimeoutMs` для перевірки готовності CDP websocket + після запуску. Збільшуйте їх на повільніших хостах, де Chrome запускається успішно, але перевірки готовності випереджають завершення запуску. Обидва значення мають бути + додатними цілими числами до `120000` мс; некоректні значення конфігурації відхиляються. - Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` і `browser.profiles..executablePath` обидва +- І `browser.executablePath`, і `browser.profiles..executablePath` приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - `userDataDir` для кожного профілю в профілях `existing-session` також розгортає тильду. -- Служба керування: лише loopback (порт похідний від `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, - `--disable-gpu`, налаштування розміру вікна або прапорці налагодження). + `userDataDir` для профілів `existing-session` на рівні профілю також розгортається з тильдою. +- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад + `--disable-gpu`, розмір вікна або прапорці налагодження). --- @@ -306,7 +304,7 @@ bundled каналів (автентифікація, контроль дост } ``` -- `seamColor`: акцентний колір для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо). +- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо). - `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -382,54 +380,54 @@ bundled каналів (автентифікація, контроль дост } ``` - + -- `mode`: `local` (запуск gateway) або `remote` (підключення до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. - **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка для Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За мережевого режиму Docker bridge (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Non-loopback bind вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з перевіркою ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, коли налаштовано обидва значення, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в запитах онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з перевіркою ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **non-loopback** джерело proxy; loopback reverse proxy на тому ж хості не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: якщо `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth заголовками Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей потік без token припускає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та для кожної області auth (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; встановіть `false`, якщо ви свідомо хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих proxy-розгортань). -- Спроби WS auth з browser-origin завжди обмежуються без винятку для loopback (додатковий захист від браузерного brute force на localhost). -- На loopback ці блокування для browser-origin ізолюються за нормалізованим значенням `Origin`, - тож повторні невдачі з одного localhost origin не блокують автоматично - інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли браузерні клієнти очікуються з non-loopback origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback origin за заголовком Host для розгортань, що навмисно покладаються на політику origin заголовка Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення - через змінну середовища процесу, яке дозволяє незашифрований `ws://` до довірених приватних мережевих - IP; типово незашифрований трафік і надалі дозволено лише для loopback. Еквівалента в `openclaw.json` - немає, а конфігурація приватної мережі браузера, така як - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів +- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. Із bridge-мережею Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Для bind не на loopback потрібна auth gateway. На практиці це означає спільний token/password або reverse proxy з підтримкою ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки запуску та встановлення/відновлення сервісу завершуються помилкою, коли налаштовано обидва, а mode не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей варіант навмисно не пропонується в підказках початкового налаштування. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з підтримкою ідентичності та довіряти заголовкам ідентичності з `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує джерело proxy **не на loopback**; reverse proxy loopback на тому самому хості не задовольняють auth trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth через заголовки Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей потік без token передбачає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожного IP клієнта та для кожної області auth (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні невдалі спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві пройшли паралельно як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо навмисно хочете, щоб трафік localhost теж підпадав під обмеження швидкості (для тестових налаштувань або суворих розгортань через proxy). +- Спроби WS auth із джерелом browser завжди обмежуються без звільнення для loopback (додатковий захист від brute force localhost через browser). +- На loopback ці блокування для джерел browser ізолюються за нормалізованим значенням `Origin`, + тому повторні невдачі з одного localhost origin не призводять автоматично + до блокування іншого origin. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти з origin не на loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback origin через заголовок Host для розгортань, що навмисно покладаються на політику origin через заголовок Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення через змінну + середовища процесу на стороні клієнта, яке дозволяє незашифрований `ws://` до довірених IP + приватної мережі; типово незашифрований трафік і далі дозволено лише для loopback. Еквівалента в + `openclaw.json` немає, а конфігурація приватної мережі browser, така як + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнти Gateway WebSocket. -- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса зовнішнього APNs relay, який використовується офіційними/TestFlight збірками iOS після того, як вони публікують реєстрації relay-backed у gateway. Ця URL-адреса має збігатися з URL relay, зібраною в збірці iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типове значення: `10000`. -- Реєстрації relay-backed делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed до gateway. Цей URL має збігатися з URL relay, вбудованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. +- Реєстрації relay-backed делегуються конкретній ідентичності gateway. Пов’язаний застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і передає до gateway право надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback HTTP URL-адрес relay. У production URL-адреси relay мають лишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора здоров’я. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора здоров’я на канал/обліковий запис за ковзну годину. Типове значення: `10`. -- `channels..healthMonitor.enabled`: вимкнення на рівні каналу для перезапусків монітора здоров’я, зберігаючи глобальний монітор увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для multi-account каналів. Якщо встановлено, має пріоритет над перевизначенням на рівні каналу. -- Шляхи викликів локального gateway можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується fail-closed (без маскування через запасний remote fallback). -- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Вказуйте лише proxy, які ви контролюєте. Записи loopback і далі є чинними для конфігурацій proxy/local-detection на тому ж хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: якщо `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типове значення `false` для поведінки fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання пристрою node без запитаних scopes. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення ролі, scope, метаданих чи публічного ключа. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд node після спарювання та обчислення списку дозволених. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний дозвіл для URL relay HTTP на loopback. У production URL relay мають лишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис у ковзній годині. Типово: `10`. +- `channels..healthMonitor.enabled`: відмова на рівні каналу від перезапусків health-monitor зі збереженням глобального монітора увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається розв’язати, розв’язання завершується fail closed (без маскування через fallback до remote). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Перелічуйте лише proxy, які ви контролюєте. Записи loopback усе ще допустимі для налаштувань proxy на тому самому хості/визначення локального джерела (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail closed. +- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого pairing вузла пристрою без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat і не схвалює автоматично підвищення ролі, областей доступу, метаданих або відкритого ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне налаштування allow/deny для оголошених команд вузла після pairing і оцінювання списку дозволу. - `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny). -- `gateway.tools.allow`: прибрати назви інструментів із типового HTTP-списку deny. +- `gateway.tools.allow`: прибрати назви інструментів із типового списку deny HTTP. @@ -437,14 +435,14 @@ bundled каналів (автентифікація, контроль дост - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилений захист URL-входів Responses: +- Посилення безпеки URL-входу Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні списки allowlist вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посиленого захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для контрольованих вами HTTPS origin; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні списки дозволу трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посилення безпеки відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів @@ -478,9 +476,9 @@ openclaw gateway --port 19001 - `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). - `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла TLS-сертифіката. -- `keyPath`: шлях файлової системи до файла приватного TLS-ключа; обмежте права доступу. -- `caPath`: необов’язковий шлях до набору CA для перевірки клієнта або користувацьких ланцюжків довіри. +- `certPath`: шлях файлової системи до файла сертифіката TLS. +- `keyPath`: шлях файлової системи до файла приватного ключа TLS; зберігайте його з обмеженими дозволами. +- `caPath`: необов’язковий шлях до набору CA для перевірки клієнтів або нестандартних ланцюжків довіри. ### `gateway.reload` @@ -497,12 +495,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку пробувати hot reload; за потреби переходити до перезапуску. -- `debounceMs`: вікно debounce у ms перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у ms для очікування завершення операцій у польоті перед примусовим перезапуском. Не вказуйте його або встановіть `0`, щоб чекати необмежено довго й періодично журналювати попередження про ще незавершені операції. + - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску. +- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском. Пропустіть його або встановіть `0`, щоб чекати безстроково й періодично журналювати попередження про те, що ще є незавершені операції. --- @@ -544,42 +542,42 @@ Hook-token у рядку запиту відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання token Gateway відхиляється. +- `hooks.enabled=true` потребує непорожнього `hooks.token`. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонізований `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping такого явного дозволу не потребують. +- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього явного дозволу. **Кінцеві точки:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` з тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). -- `POST /hooks/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` у mapping, зрендерені шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`. + - `sessionKey` із тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). +- `POST /hooks/` → визначається через `hooks.mappings` + - Значення `sessionKey` у mapping, згенеровані через шаблон, вважаються наданими ззовні й також потребують `hooks.allowRequestSessionKey=true`. - + -- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). -- `match.source` зіставляє поле payload для узагальнених шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. -- `transform` може вказувати на модуль JS/TS, що повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` спрямовує до конкретного агента; невідомі ID повертаються до типового. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не вказано = дозволити все, `[]` = заборонити все). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків агента hook без явного `sessionKey`. -- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесій mapping, керованим шаблоном, задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). +- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` відповідає полю payload для узагальнених шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. +- `transform` може вказувати на модуль JS/TS, який повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії mapping, керованим шаблонами, задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. +- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволений, якщо налаштовано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте таку маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонізованого типового значення. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібен `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого значення. ```json5 { @@ -602,7 +600,7 @@ Hook-token у рядку запиту відхиляються. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час старту, якщо його налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути це. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- @@ -619,18 +617,18 @@ Hook-token у рядку запиту відхиляються. } ``` -- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS, редаговані агентом, і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Лише локально: залишайте `gateway.bind: "loopback"` (типово). -- Для non-loopback bind маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після спарювання та підключення node Gateway рекламує URL-адреси можливостей з областю дії node для доступу до canvas/A2UI. -- URL-адреси можливостей прив’язані до активної WS-сесії node та швидко спливають. Запасний варіант на основі IP не використовується. -- Впроваджує клієнт live reload у HTML, що обслуговується. +- Для bind не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки auth; після pairing і підключення вузла Gateway оголошує URL можливостей із областю вузла для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Fallback на основі IP не використовується. +- Впроваджує клієнт live-reload у HTML, що обслуговується. - Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. -- Вимкніть live reload для великих каталогів або при помилках `EMFILE`. +- Вимикайте live reload для великих каталогів або при помилках `EMFILE`. --- @@ -648,11 +646,11 @@ Hook-token у рядку запиту відхиляються. } ``` -- `minimal` (типово): не включає `cliPath` і `sshPort` до TXT-записів. -- `full`: включає `cliPath` і `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включає `cliPath` + `sshPort` до записів TXT. +- `full`: включає `cliPath` + `sshPort`. +- Назва хоста типово `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. -### Глобальна область (DNS-SD) +### Wide-area (DNS-SD) ```json5 { @@ -670,7 +668,7 @@ Hook-token у рядку запиту відхиляються. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні середовища) ```json5 { @@ -687,14 +685,14 @@ Hook-token у рядку запиту відхиляються. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній відповідний ключ. +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу бракує ключа. - Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої оболонки входу. +- Див. [Environment](/uk/help/environment) для повного пріоритету. -### Підстановка env-змінних +### Підстановка змінних середовища -Посилайтеся на env-змінні в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -706,14 +704,14 @@ Hook-token у рядку запиту відхиляються. - Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте як `$${VAR}`, щоб отримати буквальний `${VAR}`. +- Екрануйте як `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є адитивними: прості текстові значення й далі працюють. +Посилання на секрети є адитивними: звичайні текстові значення також і далі працюють. ### `SecretRef` @@ -726,16 +724,16 @@ Hook-token у рядку запиту відхиляються. Валідація: - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `id` для `source: "file"`: абсолютний JSON pointer (наприклад, `"/providers/openai/apiKey"`) -- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинен містити сегменти шляху `.` або `..`, розділені слешами (наприклад, `a/../b` відхиляється) +- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` id: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "exec"` id не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання з `auth-profiles.json` включено до runtime-розв’язання та покриття аудиту. +- Посилання `auth-profiles.json` включено до розв’язання під час виконання та покриття аудиту. ### Конфігурація провайдерів секретів @@ -767,14 +765,14 @@ Hook-token у рядку запиту відхиляються. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). -- Шляхи провайдерів file і exec працюють у режимі fail closed, якщо перевірка ACL Windows недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує протокольні payload через stdin/stdout. -- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою розв’язаного цільового шляху. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху. -- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). +- Шляхи провайдерів file і exec завершуються fail closed, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою шляху розв’язаного цільового файла. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху розв’язаної цілі. +- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. - Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на увімкнених поверхнях призводять до помилки запуску/reload, а неактивні поверхні пропускаються з діагностикою. +- Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -798,11 +796,11 @@ Hook-token у рядку запиту відхиляються. - Профілі для кожного агента зберігаються в `/auth-profiles.json`. - `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. -- Статичні runtime-облікові дані надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищуються при виявленні. -- Імпорт застарілого OAuth виконується з `~/.openclaw/credentials/oauth.json`. +- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth із підтримкою SecretRef. +- Статичні облікові дані під час виконання надходять зі знімків, розв’язаних у пам’яті; застарілі статичні записи `auth.json` очищуються при виявленні. +- Застарілі імпорти OAuth беруться з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Runtime-поведінка секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -824,25 +822,23 @@ Hook-token у рядку запиту відхиляються. } ``` -- `billingBackoffHours`: базовий інтервал backoff у годинах, коли профіль завершується помилкою через справжні - помилки billing/недостатнього кредиту (типово: `5`). Явний текст про billing - і далі може потрапляти сюди навіть для відповідей `401`/`403`, але - зіставлювачі тексту, специфічні для провайдера, залишаються в межах - провайдера, якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або - ліміт витрат organization/workspace натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для billing на рівні провайдера. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff billing (типово: `24`). -- `authPermanentBackoffMinutes`: базовий інтервал backoff у хвилинах для високовпевнених помилок `auth_permanent` (типово: `10`). +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає невдачі через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг + усе ще може потрапити сюди навіть для відповідей `401`/`403`, але провайдер-специфічні + засоби зіставлення тексту залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter + `Key limit exceeded`). Повторювані HTTP `402` повідомлення про вікно використання або + ліміт витрат організації/робочого простору натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу на рівні провайдера. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). - `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок перевантаження перед переходом до запасної моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, такі як `ModelNotReadyException`. +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли провайдер зайнятий. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок rate-limit перед переходом до запасної моделі (типово: `1`). Цей bucket rate-limit включає текстові форми на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). До цього кошика rate-limit входить текст у формах провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- -## Логування +## Журналювання ```json5 { @@ -859,8 +855,8 @@ Hook-token у рядку запиту відхиляються. - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` з `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `consoleLevel` підвищується до `debug` із `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -876,6 +872,9 @@ Hook-token у рядку запиту відхиляються. otel: { enabled: false, endpoint: "https://otel-collector.example.com:4318", + tracesEndpoint: "https://traces.example.com/v1/traces", + metricsEndpoint: "https://metrics.example.com/v1/metrics", + logsEndpoint: "https://logs.example.com/v1/logs", protocol: "http/protobuf", // http/protobuf | grpc headers: { "x-tenant-id": "my-org" }, serviceName: "openclaw-gateway", @@ -906,19 +905,21 @@ Hook-token у рядку запиту відхиляються. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід у журнали (підтримує шаблони з wildcard, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в ms для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. у [OpenTelemetry export](/uk/gateway/opentelemetry). -- `otel.endpoint`: URL collector для експорту OTel. +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналів (підтримує шаблони з підстановками, як-от `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виводу попереджень про завислі сесії, поки сесія залишається в стані обробки. +- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель конфіденційності див. у [OpenTelemetry export](/uk/gateway/opentelemetry). +- `otel.endpoint`: URL колектора для експорту OTel. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP-адреси для окремих сигналів. Якщо задано, вони перевизначають `otel.endpoint` лише для відповідного сигналу. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. +- `otel.serviceName`: назва сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. -- `otel.sampleRate`: частота вибірки trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в ms. -- `otel.captureContent`: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім системного; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово spans зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. -- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, де вже зареєстровано глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/завершення SDK, що належать Plugin, зберігаючи активними діагностичні слухачі. +- `otel.sampleRate`: частота семплювання trace `0`–`1`. +- `otel.flushIntervalMs`: інтервал періодичного скидання telemetry у мс. +- `otel.captureContent`: явний дозвіл на захоплення необробленого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім system; форма об’єкта дає змогу явно вмикати `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово span зберігають застарілий атрибут `gen_ai.system` для сумісності; metrics GenAI використовують обмежені семантичні атрибути. +- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, але зберігає активними слухачі діагностики. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища адрес для окремих сигналів, які використовуються, коли відповідний ключ конфігурації не задано. - `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). - `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу трасування кешу (усі типово: `true`). @@ -944,11 +945,11 @@ Hook-token у рядку запиту відхиляються. ``` - `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти наявність оновлень npm під час запуску gateway (типово: `true`). +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). - `auto.enabled`: увімкнути фонове автооновлення для встановлень пакета (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням у stable-каналі (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання в stable-каналі в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням на каналі stable (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання для каналу stable в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки каналу beta, у годинах (типово: `1`; максимум: `24`). --- @@ -982,22 +983,22 @@ Hook-token у рядку запиту відхиляються. ``` - `enabled`: глобальний feature gate для ACP (типово: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP). -- `dispatch.enabled`: незалежний gate для dispatch ходу сесії ACP (типово: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося. -- `backend`: ідентифікатор типового runtime-backend ACP (має збігатися із зареєстрованим runtime Plugin ACP). - Якщо встановлено `plugins.allow`, включіть ідентифікатор backend Plugin (наприклад `acpx`), інакше bundled Plugin за замовчуванням не завантажиться. -- `defaultAgent`: запасний ідентифікатор цільового агента ACP, коли spawn не задає явну ціль. -- `allowedAgents`: список дозволених ідентифікаторів агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. +- `dispatch.enabled`: незалежний gate для dispatch ходу сесії ACP (типово: `true`). Установіть `false`, щоб зберегти команди ACP доступними, але заблокувати виконання. +- `backend`: типовий ідентифікатор backend середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP). + Якщо задано `plugins.allow`, включіть ідентифікатор Plugin backend (наприклад `acpx`), інакше bundled Plugin за замовчуванням не завантажиться. +- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawn не задають явну ціль. +- `allowedAgents`: список дозволених ідентифікаторів агентів для сесій середовища виконання ACP; порожнє значення означає відсутність додаткового обмеження. - `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: вікно idle flush у ms для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторні рядки статусу/інструмента для кожного ходу (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потоково інкрементально; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: розділювач перед видимим текстом після прихованих подій інструмента (типово: `"paragraph"`). +- `stream.coalesceIdleMs`: вікно idle-flush у мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. +- `stream.repeatSuppression`: пригнічувати повторювані рядки status/tool у межах одного ходу (типово: `true`). +- `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій tool (типово: `"paragraph"`). - `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктуються за один хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис імен тегів у булеві перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для workers сесій ACP до можливого очищення. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час початкового налаштування runtime-середовища ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків status/update ACP. +- `stream.tagVisibility`: запис назв тегів до булевих перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для worker сесій ACP до можливого очищення. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища виконання ACP. --- @@ -1013,17 +1014,17 @@ Hook-token у рядку запиту відхиляються. } ``` -- `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (типово): ротація кумедних/сезонних слоганів. - - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем підзаголовка banner: + - `"random"` (типово): ротаційні кумедні/сезонні підзаголовки. + - `"default"`: фіксований нейтральний підзаголовок (`Усі ваші чати, один OpenClaw.`). + - `"off"`: без тексту підзаголовка (назва/версія banner усе ще показуються). +- Щоб приховати весь banner (а не лише підзаголовки), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записуються потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, які записуються керованими потоками налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -1045,9 +1046,9 @@ Hook-token у рядку запиту відхиляються. --- -## Bridge (застарілий, видалено) +## Bridge (застарілий, вилучений) -Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -1087,11 +1088,11 @@ Hook-token у рядку запиту відхиляються. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівних видалених транскриптів Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір одного файла журналу запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: кількість найновіших рядків, що зберігаються при запуску очищення журналу запуску. Типове значення: `2000`. -- `webhookToken`: bearer token, що використовується для доставки POST до Cron Webhook (`delivery.mode = "webhook"`); якщо не вказано, заголовок auth не надсилається. -- `webhook`: застаріла URL-адреса запасного Webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів Cron. Типово: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байт. +- `runLog.keepLines`: найновіші рядки, що зберігаються при спрацюванні очищення журналу запуску. Типово: `2000`. +- `webhookToken`: bearer token, що використовується для доставки POST Webhook Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. +- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, у яких усе ще є `notify: true`. ### `cron.retry` @@ -1108,10 +1109,10 @@ Hook-token у рядку запиту відхиляються. ``` - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у ms для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. +- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань Cron. Для повторюваних завдань використовується окрема обробка збоїв. +Застосовується лише до одноразових завдань Cron. Періодичні завдання використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -1133,7 +1134,7 @@ Hook-token у рядку запиту відхиляються. - `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). - `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook. -- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщень. +- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -1151,43 +1152,43 @@ Hook-token у рядку запиту відхиляються. ``` - Типове місце призначення для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли достатньо даних цілі. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL-адреса Webhook. Обов’язково для режиму webhook. +- `to`: явна ціль announce або URL Webhook. Обов’язкове для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. -- Якщо не задано ні глобальне, ні окреме місце призначення для збоїв, завдання, які вже доставляють через `announce`, при збої повертаються до цієї основної цілі announce. +- `delivery.failureDestination` для конкретного завдання перевизначає це глобальне значення за замовчуванням. +- Коли не задано ні глобальне, ні індивідуальне місце призначення збою, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [background tasks](/uk/automation/tasks). --- -## Змінні шаблону моделі медіа +## Змінні шаблону медіамоделі -Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Текст без згадок у групі | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | Ідентифікатор повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (зображення/аудіо/документ/…) | -| `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний media prompt для записів CLI | -| `{{MaxChars}}` | Розв’язаний максимум символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}` | Тема групи (за можливості) | -| `{{GroupMembers}}` | Попередній перегляд учасників групи (за можливості) | -| `{{SenderName}}` | Відображуване ім’я відправника (за можливості) | -| `{{SenderE164}}` | Номер телефону відправника (за можливості) | +| Змінна | Опис | +| ------------------ | --------------------------------------------------- | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Текст без згадок у групі | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | Ідентифікатор повідомлення каналу | +| `{{SessionId}}` | UUID поточної сесії | +| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Транскрипт аудіо | +| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI | +| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}` | Назва групи (best effort) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- @@ -1210,12 +1211,12 @@ Hook-token у рядку запиту відхиляються. **Поведінка злиття:** - Один файл: замінює об’єкт, що його містить. -- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні). +- Масив файлів: глибоко зливається в порядку (пізніші перевизначають попередні). - Сусідні ключі: зливаються після include (перевизначають включені значення). - Вкладені include: до 10 рівнів глибини. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно лишаються в межах цього обмеження. -- Записи, які виконує OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений include з одного файла, записуються назад у цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів, які виконує OpenClaw; такі записи завершуються fail closed замість сплощення конфігурації. +- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все ще залишаються в межах цієї границі. +- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` недоторканим. +- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів, керованих OpenClaw; такі записи завершуються fail closed замість сплощення конфігурації. - Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних include. --- diff --git a/docs/uk/gateway/heartbeat.md b/docs/uk/gateway/heartbeat.md index ee380870f..60225bfd5 100644 --- a/docs/uk/gateway/heartbeat.md +++ b/docs/uk/gateway/heartbeat.md @@ -1,37 +1,37 @@ --- read_when: - - Налаштування частоти або повідомлень Heartbeat + - Налаштування частоти Heartbeat або повідомлень - Вибір між Heartbeat і Cron для запланованих завдань summary: Повідомлення опитування Heartbeat і правила сповіщень title: Heartbeat x-i18n: - generated_at: "2026-04-25T05:55:51Z" + generated_at: "2026-04-26T01:42:38Z" model: gpt-5.4 provider: openai - source_hash: 17353a03bbae7ad564548e767099f8596764e2cf9bc3d457ec9fc3482ba7d71c + source_hash: 440afefdbefba8317eeb7f3a1ecb6dddb2d88600e78b46a31f2f432bfa5eeb33 source_path: gateway/heartbeat.md workflow: 15 --- -> **Heartbeat чи Cron?** Див. [Automation & Tasks](/uk/automation), щоб зрозуміти, коли слід використовувати кожен із них. +> **Heartbeat чи Cron?** Дивіться [Автоматизація й завдання](/uk/automation), щоб зрозуміти, коли використовувати кожен із них. -Heartbeat запускає **періодичні цикли агента** в main session, щоб модель могла -повідомляти про все, що потребує уваги, не засипаючи вас повідомленнями. +Heartbeat запускає **періодичні ходи агента** в основній сесії, щоб модель могла +виявляти все, що потребує уваги, не засипаючи вас повідомленнями. -Heartbeat — це запланований цикл main-session — він **не** створює записів [фонових завдань](/uk/automation/tasks). -Записи завдань призначені для відокремленої роботи (запуски ACP, субагенти, ізольовані завдання cron). +Heartbeat — це запланований хід основної сесії — він **не** створює записи [фонових завдань](/uk/automation/tasks). +Записи завдань призначені для відокремленої роботи (запуски ACP, субагенти, ізольовані завдання Cron). -Усунення несправностей: [Scheduled Tasks](/uk/automation/cron-jobs#troubleshooting) +Усунення проблем: [Заплановані завдання](/uk/automation/cron-jobs#troubleshooting) ## Швидкий старт (для початківців) -1. Залиште heartbeat увімкненим (типове значення — `30m`, або `1h` для автентифікації Anthropic OAuth/token, включно з повторним використанням Claude CLI) або задайте власну частоту. -2. Створіть невеликий контрольний список `HEARTBEAT.md` або блок `tasks:` у робочому просторі агента (необов’язково, але рекомендовано). -3. Визначте, куди мають надходити повідомлення heartbeat (`target: "none"` — типове значення; установіть `target: "last"`, щоб маршрутизувати до останнього контакту). -4. Необов’язково: увімкніть доставку reasoning heartbeat для прозорості. -5. Необов’язково: використовуйте полегшений bootstrap-контекст, якщо запускам heartbeat потрібен лише `HEARTBEAT.md`. -6. Необов’язково: увімкніть ізольовані сесії, щоб не надсилати повну історію розмови під час кожного heartbeat. -7. Необов’язково: обмежте heartbeat активними годинами (за місцевим часом). +1. Залиште Heartbeat увімкненим (типово `30m`, або `1h` для Anthropic OAuth/автентифікації токеном, зокрема повторного використання Claude CLI) або встановіть власний інтервал. +2. Створіть невеликий контрольний список у `HEARTBEAT.md` або блок `tasks:` у робочому просторі агента (необов’язково, але рекомендовано). +3. Вирішіть, куди мають надходити повідомлення Heartbeat (`target: "none"` — типове значення; установіть `target: "last"`, щоб спрямовувати їх до останнього контакту). +4. Необов’язково: увімкніть доставку міркувань Heartbeat для прозорості. +5. Необов’язково: використовуйте полегшений початковий контекст, якщо запускам Heartbeat потрібен лише `HEARTBEAT.md`. +6. Необов’язково: увімкніть ізольовані сесії, щоб не надсилати повну історію розмови під час кожного Heartbeat. +7. Необов’язково: обмежте Heartbeat активними годинами (за місцевим часом). Приклад конфігурації: @@ -42,9 +42,9 @@ Heartbeat — це запланований цикл main-session — він ** heartbeat: { every: "30m", target: "last", // явна доставка до останнього контакту (типово "none") - directPolicy: "allow", // типово: allow для прямих/DM цілей; установіть "block", щоб придушити - lightContext: true, // необов’язково: ін’єктувати з bootstrap-файлів лише HEARTBEAT.md - isolatedSession: true, // необов’язково: нова сесія для кожного запуску (без історії розмови) + directPolicy: "allow", // типово: дозволяти прямі/DM-цілі; установіть "block", щоб придушити + lightContext: true, // необов’язково: інжектувати тільки HEARTBEAT.md із bootstrap-файлів + isolatedSession: true, // необов’язково: нова сесія для кожного запуску (без історії розмов) // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // необов’язково: також надсилати окреме повідомлення `Reasoning:` }, @@ -55,45 +55,45 @@ Heartbeat — це запланований цикл main-session — він ** ## Типові значення -- Інтервал: `30m` (або `1h`, коли виявленим режимом автентифікації є Anthropic OAuth/token, включно з повторним використанням Claude CLI). Установіть `agents.defaults.heartbeat.every` або для конкретного агента `agents.list[].heartbeat.every`; використайте `0m`, щоб вимкнути. -- Тіло prompt (налаштовується через `agents.defaults.heartbeat.prompt`): +- Інтервал: `30m` (або `1h`, коли виявленим режимом автентифікації є Anthropic OAuth/токен, зокрема повторне використання Claude CLI). Установіть `agents.defaults.heartbeat.every` або для окремого агента `agents.list[].heartbeat.every`; використовуйте `0m`, щоб вимкнути. +- Тіло запиту (можна налаштувати через `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- Prompt heartbeat надсилається **дослівно** як повідомлення користувача. System - prompt містить розділ “Heartbeat” лише тоді, коли heartbeat увімкнено для - типового агента, а запуск внутрішньо позначено відповідним прапорцем. -- Коли heartbeat вимкнено через `0m`, звичайні запуски також не включають `HEARTBEAT.md` - до bootstrap-контексту, щоб модель не бачила інструкцій, призначених лише для heartbeat. +- Запит Heartbeat надсилається **дослівно** як повідомлення користувача. Системний + запит містить розділ “Heartbeat” лише тоді, коли Heartbeat увімкнено для + типового агента, а запуск позначено внутрішньо. +- Коли Heartbeat вимкнено через `0m`, звичайні запуски також не включають `HEARTBEAT.md` + до bootstrap-контексту, тож модель не бачить інструкції лише для Heartbeat. - Активні години (`heartbeat.activeHours`) перевіряються в налаштованому часовому поясі. - Поза вікном heartbeat пропускаються до наступного тіку всередині вікна. + Поза цим вікном Heartbeat пропускається до наступного тіку всередині вікна. -## Для чого потрібен prompt heartbeat +## Для чого потрібен запит Heartbeat -Типовий prompt навмисно зроблено широким: +Типовий запит навмисно зроблено широким: - **Фонові завдання**: “Consider outstanding tasks” спонукає агента переглядати - незавершені справи (вхідні, календар, нагадування, роботу в черзі) і повідомляти про все термінове. -- **Перевірка з людиною**: “Checkup sometimes on your human during day time” спонукає до - випадкового ненав’язливого повідомлення на кшталт “чи щось тобі потрібно?”, але уникає нічного спаму + подальші дії (вхідні, календар, нагадування, роботу в черзі) і виявляти все термінове. +- **Перевірка стану людини**: “Checkup sometimes on your human during day time” спонукає + до періодичного легкого повідомлення на кшталт “чи щось тобі потрібно?”, але уникає нічного спаму завдяки використанню вашого налаштованого локального часового поясу (див. [/concepts/timezone](/uk/concepts/timezone)). -Heartbeat може реагувати на завершені [фонові завдання](/uk/automation/tasks), але сам запуск heartbeat не створює запису завдання. +Heartbeat може реагувати на завершені [фонові завдання](/uk/automation/tasks), але сам запуск Heartbeat не створює запис завдання. -Якщо ви хочете, щоб heartbeat робив щось дуже конкретне (наприклад, “перевіряти статистику Gmail PubSub” -або “перевіряти стан gateway”), задайте `agents.defaults.heartbeat.prompt` (або -`agents.list[].heartbeat.prompt`) як власне тіло, яке надсилається дослівно. +Якщо ви хочете, щоб Heartbeat робив щось дуже конкретне (наприклад, “перевірити статистику Gmail PubSub” +або “перевірити справність Gateway”), задайте `agents.defaults.heartbeat.prompt` (або +`agents.list[].heartbeat.prompt`) із власним текстом (надсилається дослівно). ## Контракт відповіді -- Якщо нічого не потребує уваги, дайте відповідь **`HEARTBEAT_OK`**. -- Під час запусків heartbeat OpenClaw трактує `HEARTBEAT_OK` як підтвердження, якщо воно з’являється +- Якщо ніщо не потребує уваги, дайте відповідь **`HEARTBEAT_OK`**. +- Під час запусків Heartbeat OpenClaw трактує `HEARTBEAT_OK` як підтвердження, якщо він з’являється **на початку або в кінці** відповіді. Токен видаляється, а відповідь - відкидається, якщо решта вмісту має **≤ `ackMaxChars`** (типово: 300). -- Якщо `HEARTBEAT_OK` з’являється **посередині** відповіді, воно не має - спеціального значення. + відкидається, якщо залишковий вміст має **≤ `ackMaxChars`** (типово: 300). +- Якщо `HEARTBEAT_OK` з’являється **посередині** відповіді, він не обробляється + особливим чином. - Для сповіщень **не** включайте `HEARTBEAT_OK`; повертайте лише текст сповіщення. -Поза heartbeat сторонній `HEARTBEAT_OK` на початку/в кінці повідомлення видаляється -і логуються; повідомлення, яке складається лише з `HEARTBEAT_OK`, відкидається. +Поза Heartbeat випадковий `HEARTBEAT_OK` на початку/в кінці повідомлення видаляється +й логуються; повідомлення, яке складається лише з `HEARTBEAT_OK`, відкидається. ## Конфігурація @@ -104,12 +104,12 @@ Heartbeat може реагувати на завершені [фонові за heartbeat: { every: "30m", // типово: 30m (0m вимикає) model: "anthropic/claude-opus-4-6", - includeReasoning: false, // типово: false (доставляти окреме повідомлення Reasoning:, коли доступне) - lightContext: false, // типово: false; true залишає з bootstrap-файлів робочого простору лише HEARTBEAT.md - isolatedSession: false, // типово: false; true запускає кожен heartbeat у новій сесії (без історії розмови) - target: "last", // типово: none | варіанти: last | none | (core або plugin, наприклад "bluebubbles") - to: "+15551234567", // необов’язкове перевизначення для конкретного каналу - accountId: "ops-bot", // необов’язковий id каналу для multi-account + includeReasoning: false, // типово: false (доставляти окреме повідомлення Reasoning: коли доступно) + lightContext: false, // типово: false; true залишає тільки HEARTBEAT.md з bootstrap-файлів робочого простору + isolatedSession: false, // типово: false; true запускає кожен Heartbeat у новій сесії (без історії розмов) + target: "last", // типово: none | варіанти: last | none | (core або Plugin, наприклад "bluebubbles") + to: "+15551234567", // необов’язкове перевизначення для каналу + accountId: "ops-bot", // необов’язковий id каналу з кількома обліковими записами prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", ackMaxChars: 300, // макс. кількість символів, дозволена після HEARTBEAT_OK }, @@ -120,19 +120,19 @@ Heartbeat може реагувати на завершені [фонові за ### Область дії та пріоритет -- `agents.defaults.heartbeat` задає глобальну поведінку heartbeat. -- `agents.list[].heartbeat` об’єднується поверх; якщо будь-який агент має блок `heartbeat`, **heartbeat запускаються лише для цих агентів**. +- `agents.defaults.heartbeat` задає глобальну поведінку Heartbeat. +- `agents.list[].heartbeat` об’єднується поверх нього; якщо будь-який агент має блок `heartbeat`, Heartbeat запускається **лише для цих агентів**. - `channels.defaults.heartbeat` задає типові параметри видимості для всіх каналів. -- `channels..heartbeat` перевизначає типові параметри каналів. -- `channels..accounts..heartbeat` (канали multi-account) перевизначає налаштування для конкретного каналу. +- `channels..heartbeat` перевизначає типові параметри каналу. +- `channels..accounts..heartbeat` (канали з кількома обліковими записами) перевизначає налаштування для окремого каналу. -### Heartbeat для конкретного агента +### Heartbeat для окремих агентів -Якщо будь-який запис `agents.list[]` містить блок `heartbeat`, **heartbeat запускаються лише для цих агентів**. -Блок для конкретного агента об’єднується поверх `agents.defaults.heartbeat` -(тобто можна один раз задати спільні типові значення й перевизначати їх для окремих агентів). +Якщо будь-який запис `agents.list[]` містить блок `heartbeat`, Heartbeat +запускається **лише для цих агентів**. Блок для окремого агента об’єднується поверх `agents.defaults.heartbeat` +(тож можна один раз задати спільні типові параметри й перевизначати їх для конкретних агентів). -Приклад: два агенти, heartbeat запускається лише для другого. +Приклад: два агенти, Heartbeat запускається лише для другого агента. ```json5 { @@ -162,7 +162,7 @@ Heartbeat може реагувати на завершені [фонові за ### Приклад активних годин -Обмежте heartbeat робочими годинами в конкретному часовому поясі: +Обмежте Heartbeat робочими годинами в певному часовому поясі: ```json5 { @@ -182,21 +182,21 @@ Heartbeat може реагувати на завершені [фонові за } ``` -Поза цим вікном (до 9:00 або після 22:00 за східним часом) heartbeat пропускаються. Наступний запланований тік усередині вікна виконається нормально. +Поза цим вікном (до 9 ранку або після 10 вечора за східним часом) Heartbeat пропускається. Наступний запланований тік у межах вікна відпрацює звичайно. ### Налаштування 24/7 -Якщо ви хочете, щоб heartbeat запускався весь день, використовуйте один із цих варіантів: +Якщо ви хочете, щоб Heartbeat запускався весь день, використовуйте один із таких шаблонів: -- Узагалі не вказуйте `activeHours` (без обмеження часовим вікном; це типова поведінка). -- Установіть повноденне вікно: `activeHours: { start: "00:00", end: "24:00" }`. +- Взагалі не задавайте `activeHours` (без обмеження часовим вікном; це типова поведінка). +- Задайте вікно на весь день: `activeHours: { start: "00:00", end: "24:00" }`. -Не встановлюйте однакові значення `start` і `end` (наприклад, з `08:00` до `08:00`). -Це обробляється як вікно нульової ширини, тому heartbeat завжди пропускається. +Не задавайте однакові значення для `start` і `end` (наприклад, `08:00` до `08:00`). +Це вважається вікном нульової ширини, тому Heartbeat завжди пропускатиметься. -### Приклад multi account +### Приклад із кількома обліковими записами -Використовуйте `accountId`, щоб націлити heartbeat на конкретний обліковий запис у каналах multi-account, як-от Telegram: +Використовуйте `accountId`, щоб націлити конкретний обліковий запис у каналах із кількома обліковими записами, таких як Telegram: ```json5 { @@ -207,7 +207,7 @@ Heartbeat може реагувати на завершені [фонові за heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // необов’язково: маршрут до конкретної теми/потоку + to: "12345678:topic:42", // необов’язково: спрямувати в конкретну тему/гілку accountId: "ops-bot", }, }, @@ -225,62 +225,63 @@ Heartbeat може реагувати на завершені [фонові за ### Примітки щодо полів -- `every`: інтервал heartbeat (рядок тривалості; типова одиниця = хвилини). -- `model`: необов’язкове перевизначення model для запусків heartbeat (`provider/model`). -- `includeReasoning`: коли увімкнено, також доставляє окреме повідомлення `Reasoning:`, коли воно доступне (такий самий формат, як `/reasoning on`). -- `lightContext`: якщо `true`, запуски heartbeat використовують полегшений bootstrap-контекст і з bootstrap-файлів робочого простору залишають лише `HEARTBEAT.md`. -- `isolatedSession`: якщо `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Використовує той самий шаблон ізоляції, що й cron `sessionTarget: "isolated"`. Значно зменшує витрати токенів на кожен heartbeat. Поєднуйте з `lightContext: true` для максимальної економії. Маршрутизація доставки при цьому все одно використовує контекст main session. -- `session`: необов’язковий ключ сесії для запусків heartbeat. - - `main` (типово): main session агента. - - Явний ключ сесії (скопіюйте з `openclaw sessions --json` або з [CLI sessions](/uk/cli/sessions)). - - Формати ключів сесії: див. [Sessions](/uk/concepts/session) і [Groups](/uk/channels/groups). +- `every`: інтервал Heartbeat (рядок тривалості; типова одиниця = хвилини). +- `model`: необов’язкове перевизначення моделі для запусків Heartbeat (`provider/model`). +- `includeReasoning`: якщо ввімкнено, також доставляє окреме повідомлення `Reasoning:`, коли воно доступне (такий самий формат, як у `/reasoning on`). +- `lightContext`: коли true, запуски Heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: коли true, кожен Heartbeat запускається в новій сесії без попередньої історії розмов. Використовує той самий шаблон ізоляції, що й Cron `sessionTarget: "isolated"`. Суттєво зменшує витрати токенів на кожен Heartbeat. Поєднуйте з `lightContext: true` для максимальної економії. Маршрутизація доставки все одно використовує контекст основної сесії. +- `session`: необов’язковий ключ сесії для запусків Heartbeat. + - `main` (типово): основна сесія агента. + - Явний ключ сесії (скопіюйте з `openclaw sessions --json` або [CLI sessions](/uk/cli/sessions)). + - Формати ключів сесій: див. [Сесії](/uk/concepts/session) і [Групи](/uk/channels/groups). - `target`: - - `last`: доставити до останнього використаного зовнішнього каналу. + - `last`: доставляти в останній використаний зовнішній канал. - явний канал: будь-який налаштований канал або id Plugin, наприклад `discord`, `matrix`, `telegram` або `whatsapp`. - - `none` (типово): запускати heartbeat, але **не доставляти** назовні. -- `directPolicy`: керує поведінкою доставки в direct/DM: - - `allow` (типово): дозволити доставку heartbeat у direct/DM. - - `block`: придушити доставку в direct/DM (`reason=dm-blocked`). -- `to`: необов’язкове перевизначення одержувача (id, специфічний для каналу, наприклад E.164 для WhatsApp або id чату Telegram). Для тем/потоків Telegram використовуйте `:topic:`. -- `accountId`: необов’язковий id облікового запису для каналів multi-account. Коли `target: "last"`, id облікового запису застосовується до визначеного останнього каналу, якщо він підтримує облікові записи; інакше ігнорується. Якщо id облікового запису не відповідає налаштованому обліковому запису для визначеного каналу, доставка пропускається. -- `prompt`: перевизначає типове тіло prompt (не об’єднується). -- `ackMaxChars`: максимальна кількість символів, дозволена після `HEARTBEAT_OK` до доставки. -- `suppressToolErrorWarnings`: якщо `true`, придушує payload-и попереджень про помилки tools під час запусків heartbeat. -- `activeHours`: обмежує запуски heartbeat часовим вікном. Об’єкт із `start` (HH:MM, включно; використовуйте `00:00` для початку дня), `end` (HH:MM, виключно; `24:00` дозволено для кінця дня) та необов’язковим `timezone`. - - Пропущено або `"user"`: використовує ваш `agents.defaults.userTimezone`, якщо задано, інакше повертається до часового поясу системи хоста. + - `none` (типово): запускати Heartbeat, але **не доставляти** назовні. +- `directPolicy`: керує поведінкою доставки напряму/в DM: + - `allow` (типово): дозволяти пряму/DM-доставку Heartbeat. + - `block`: придушувати пряму/DM-доставку (`reason=dm-blocked`). +- `to`: необов’язкове перевизначення отримувача (специфічний для каналу id, наприклад E.164 для WhatsApp або id чату Telegram). Для тем/гілок Telegram використовуйте `:topic:`. +- `accountId`: необов’язковий id облікового запису для каналів із кількома обліковими записами. Коли `target: "last"`, id облікового запису застосовується до визначеного останнього каналу, якщо він підтримує облікові записи; інакше ігнорується. Якщо id облікового запису не відповідає налаштованому обліковому запису для визначеного каналу, доставку буде пропущено. +- `prompt`: перевизначає типове тіло запиту (не об’єднується). +- `ackMaxChars`: максимальна кількість символів, дозволена після `HEARTBEAT_OK` перед доставкою. +- `suppressToolErrorWarnings`: коли true, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat. +- `activeHours`: обмежує запуски Heartbeat часовим вікном. Об’єкт із `start` (HH:MM, включно; використовуйте `00:00` для початку дня), `end` (HH:MM, не включно; `24:00` дозволено для кінця дня) та необов’язковим `timezone`. + - Якщо не задано або `"user"`: використовує ваш `agents.defaults.userTimezone`, якщо задано, інакше переходить до часового поясу системи хоста. - `"local"`: завжди використовує часовий пояс системи хоста. - - Будь-який ідентифікатор IANA (наприклад, `America/New_York`): використовується напряму; якщо він некоректний, використовується поведінка `"user"`, описана вище. - - `start` і `end` не мають бути рівними для активного вікна; рівні значення обробляються як нульова ширина (завжди поза вікном). - - Поза активним вікном heartbeat пропускаються до наступного тіку всередині вікна. + - Будь-який ідентифікатор IANA (наприклад, `America/New_York`): використовується напряму; якщо він недійсний, виконується перехід до поведінки `"user"`, описаної вище. + - `start` і `end` не повинні бути однаковими для активного вікна; однакові значення вважаються нульовою шириною (завжди поза вікном). + - Поза активним вікном Heartbeat пропускається до наступного тіку всередині вікна. ## Поведінка доставки -- Heartbeat за замовчуванням запускаються в main session агента (`agent::`), - або в `global`, коли `session.scope = "global"`. Установіть `session`, щоб перевизначити це на +- Heartbeat запускається в основній сесії агента за замовчуванням (`agent::`), + або в `global`, коли `session.scope = "global"`. Установіть `session`, щоб перевизначити на конкретну сесію каналу (Discord/WhatsApp тощо). - `session` впливає лише на контекст запуску; доставкою керують `target` і `to`. -- Щоб доставляти в конкретний канал/конкретному одержувачу, установіть `target` + `to`. Якщо +- Щоб доставляти в конкретний канал/конкретному отримувачу, установіть `target` + `to`. Якщо `target: "last"`, доставка використовує останній зовнішній канал для цієї сесії. -- Доставка heartbeat за замовчуванням дозволяє direct/DM-цілі. Установіть `directPolicy: "block"`, щоб придушити надсилання на direct-цілі, водночас залишивши сам цикл heartbeat. -- Якщо основна черга зайнята, heartbeat пропускається і повторюється пізніше. -- Якщо `target` не дає жодного зовнішнього призначення, запуск усе одно відбувається, але +- Доставки Heartbeat за замовчуванням дозволяють прямі/DM-цілі. Установіть `directPolicy: "block"`, щоб придушити надсилання на прямі цілі, але при цьому все одно виконати хід Heartbeat. +- Якщо основна черга зайнята, Heartbeat пропускається й повторюється пізніше. +- Якщо `target` не вдається зіставити з жодним зовнішнім призначенням, запуск усе одно відбувається, але вихідне повідомлення не надсилається. -- Якщо `showOk`, `showAlerts` і `useIndicator` усі вимкнені, запуск одразу пропускається з `reason=alerts-disabled`. -- Якщо вимкнено лише доставку сповіщень, OpenClaw усе одно може виконати heartbeat, оновити часові мітки завдань, термін виконання яких настав, відновити часову мітку бездіяльності сесії та придушити зовнішній payload сповіщення. -- Якщо визначена heartbeat-ціль підтримує typing, OpenClaw показує typing, доки - виконується heartbeat. Для цього використовується та сама ціль, до якої heartbeat - надсилав би вивід чату, і це вимикається через `typingMode: "never"`. -- Відповіді лише для heartbeat **не** підтримують активність сесії; останній `updatedAt` - відновлюється, тому завершення за неактивністю працює звичайним чином. -- Історія Control UI і WebChat приховує prompt-и heartbeat та підтвердження, - що містять лише OK. Базовий transcript сесії все одно може містити ці - цикли для аудиту/повторного відтворення. -- Відокремлені [фонові завдання](/uk/automation/tasks) можуть ставити системну подію в чергу й пробуджувати heartbeat, коли main session має швидко щось помітити. Таке пробудження не робить запуск heartbeat фоновим завданням. +- Якщо `showOk`, `showAlerts` і `useIndicator` усі вимкнені, запуск пропускається одразу з `reason=alerts-disabled`. +- Якщо вимкнено лише доставку сповіщень, OpenClaw усе одно може виконати Heartbeat, оновити часові мітки завдань до виконання, відновити часову мітку бездіяльності сесії та придушити зовнішній payload сповіщення. +- Якщо визначена ціль Heartbeat підтримує індикатор набору тексту, OpenClaw показує його, поки + триває запуск Heartbeat. Для цього використовується та сама ціль, куди Heartbeat + надсилав би вихід чату, і це вимикається параметром `typingMode: "never"`. +- Відповіді лише для Heartbeat **не** підтримують сесію активною. Метадані Heartbeat + можуть оновлювати рядок сесії, але завершення за бездіяльністю використовує `lastInteractionAt` з + останнього реального повідомлення користувача/каналу, а добове завершення використовує `sessionStartedAt`. +- Історія в Control UI і WebChat приховує запити Heartbeat і підтвердження лише з OK. + Базовий транскрипт сесії все одно може містити ці + ходи для аудиту/відтворення. +- Відокремлені [фонові завдання](/uk/automation/tasks) можуть ставити системну подію в чергу й будити Heartbeat, коли основна сесія має швидко щось помітити. Таке пробудження не робить запуск Heartbeat фоновим завданням. ## Керування видимістю -За замовчуванням підтвердження `HEARTBEAT_OK` придушуються, тоді як вміст -сповіщень доставляється. Ви можете налаштувати це для окремого каналу або облікового запису: +За замовчуванням підтвердження `HEARTBEAT_OK` придушуються, а вміст сповіщень +доставляється. Ви можете налаштувати це для кожного каналу або облікового запису: ```yaml channels: @@ -288,10 +289,10 @@ channels: heartbeat: showOk: false # Приховувати HEARTBEAT_OK (типово) showAlerts: true # Показувати повідомлення сповіщень (типово) - useIndicator: true # Генерувати події-індикатори (типово) + useIndicator: true # Надсилати події індикатора (типово) telegram: heartbeat: - showOk: true # Показувати OK-підтвердження в Telegram + showOk: true # Показувати підтвердження OK у Telegram whatsapp: accounts: work: @@ -299,17 +300,17 @@ channels: showAlerts: false # Придушити доставку сповіщень для цього облікового запису ``` -Пріоритет: для облікового запису → для каналу → типові значення каналу → вбудовані типові значення. +Пріоритет: для облікового запису → для каналу → типові для каналів → вбудовані типові значення. ### Що робить кожен прапорець -- `showOk`: надсилає підтвердження `HEARTBEAT_OK`, коли модель повертає відповідь, що містить лише OK. -- `showAlerts`: надсилає вміст сповіщення, коли модель повертає відповідь, що не є OK. -- `useIndicator`: генерує події-індикатори для UI-поверхонь статусу. +- `showOk`: надсилає підтвердження `HEARTBEAT_OK`, коли модель повертає відповідь лише з OK. +- `showAlerts`: надсилає вміст сповіщення, коли модель повертає відповідь не-OK. +- `useIndicator`: надсилає події індикатора для поверхонь стану UI. -Якщо **всі три** значення дорівнюють false, OpenClaw повністю пропускає запуск heartbeat (без виклику моделі). +Якщо **усі три** мають значення false, OpenClaw повністю пропускає запуск Heartbeat (без виклику моделі). -### Приклади для окремого каналу та окремого облікового запису +### Приклади для каналу й облікового запису ```yaml channels: @@ -330,46 +331,47 @@ channels: showOk: true ``` -### Поширені шаблони +### Типові шаблони -| Мета | Конфігурація | -| ---------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Типова поведінка (тихі OK, сповіщення увімкнено) | _(конфігурація не потрібна)_ | -| Повністю тихо (без повідомлень, без індикатора) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | -| Лише індикатор (без повідомлень) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| OK лише в одному каналі | `channels.telegram.heartbeat: { showOk: true }` | +| Мета | Конфігурація | +| --- | --- | +| Типова поведінка (тихі OK, сповіщення увімкнені) | _(конфігурація не потрібна)_ | +| Повністю тихо (без повідомлень, без індикатора) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| Лише індикатор (без повідомлень) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | +| OK лише в одному каналі | `channels.telegram.heartbeat: { showOk: true }` | ## HEARTBEAT.md (необов’язково) -Якщо у workspace існує файл `HEARTBEAT.md`, типовий prompt вказує -агенту прочитати його. Сприймайте його як свій “контрольний список heartbeat”: невеликий, стабільний і +Якщо у робочому просторі є файл `HEARTBEAT.md`, типовий запит каже +агенту прочитати його. Думайте про нього як про ваш “контрольний список heartbeat”: невеликий, стабільний і безпечний для включення кожні 30 хвилин. -Під час звичайних запусків `HEARTBEAT.md` ін’єктується лише тоді, коли -heartbeat-guidance увімкнено для типового агента. Вимкнення частоти heartbeat через `0m` або -встановлення `includeSystemPromptSection: false` прибирає його зі звичайного bootstrap-контексту. +Під час звичайних запусків `HEARTBEAT.md` інжектується лише тоді, коли вказівки Heartbeat +увімкнені для типового агента. Вимкнення інтервалу Heartbeat через `0m` або +встановлення `includeSystemPromptSection: false` прибирає його зі звичайного bootstrap- +контексту. -Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки -на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API-виклики. -Таке пропускання позначається як `reason=empty-heartbeat-file`. -Якщо файл відсутній, heartbeat усе одно виконується, а модель сама вирішує, що робити. +Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки й markdown- +заголовки на кшталт `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб зекономити виклики API. +Такий пропуск фіксується як `reason=empty-heartbeat-file`. +Якщо файлу немає, Heartbeat усе одно запускається, а модель вирішує, що робити. -Тримайте його невеликим (короткий контрольний список або нагадування), щоб уникнути роздування prompt. +Тримайте його невеликим (короткий контрольний список або нагадування), щоб уникнути роздування запиту. Приклад `HEARTBEAT.md`: ```md -# Heartbeat checklist +# Контрольний список Heartbeat -- Quick scan: anything urgent in inboxes? -- If it’s daytime, do a lightweight check-in if nothing else is pending. -- If a task is blocked, write down _what is missing_ and ask Peter next time. +- Швидкий перегляд: чи є щось термінове у вхідних? +- Якщо зараз денний час, зроби легкий check-in, якщо більше нічого не очікує. +- Якщо завдання заблоковане, запиши _чого саме бракує_ і запитай Peter наступного разу. ``` ### Блоки `tasks:` `HEARTBEAT.md` також підтримує невеликий структурований блок `tasks:` для перевірок -на основі інтервалів усередині самого heartbeat. +за інтервалами всередині самого Heartbeat. Приклад: @@ -378,76 +380,77 @@ tasks: - name: inbox-triage interval: 30m - prompt: "Check for urgent unread emails and flag anything time sensitive." + prompt: "Перевір термінові непрочитані листи й познач усе, що чутливе до часу." - name: calendar-scan interval: 2h - prompt: "Check for upcoming meetings that need prep or follow-up." + prompt: "Перевір майбутні зустрічі, які потребують підготовки або подальших дій." -# Additional instructions +# Додаткові інструкції -- Keep alerts short. -- If nothing needs attention after all due tasks, reply HEARTBEAT_OK. +- Роби сповіщення короткими. +- Якщо після всіх завдань до виконання ніщо не потребує уваги, відповідай HEARTBEAT_OK. ``` Поведінка: -- OpenClaw парсить блок `tasks:` і перевіряє кожне завдання відносно його власного `interval`. -- До prompt heartbeat для цього тіку включаються лише **завдання, термін яких настав**. -- Якщо жодне завдання не має насталого терміну, heartbeat повністю пропускається (`reason=no-tasks-due`), щоб уникнути марного виклику моделі. -- Вміст `HEARTBEAT.md`, що не належить до завдань, зберігається й додається як додатковий контекст після списку завдань, термін яких настав. -- Часові мітки останнього запуску завдань зберігаються в стані сесії (`heartbeatTaskState`), тому інтервали переживають звичайні перезапуски. -- Часові мітки завдань зсуваються вперед лише після того, як запуск heartbeat проходить свій звичайний шлях відповіді. Пропущені запуски `empty-heartbeat-file` / `no-tasks-due` не позначають завдання як завершені. +- OpenClaw аналізує блок `tasks:` і перевіряє кожне завдання щодо його власного `interval`. +- До запиту Heartbeat для цього тіку включаються лише **завдання до виконання**. +- Якщо жодне завдання не належить до виконання, Heartbeat повністю пропускається (`reason=no-tasks-due`), щоб уникнути марного виклику моделі. +- Вміст у `HEARTBEAT.md`, який не є завданнями, зберігається та додається як додатковий контекст після списку завдань до виконання. +- Часові мітки останнього запуску завдань зберігаються в стані сесії (`heartbeatTaskState`), тож інтервали переживають звичайні перезапуски. +- Часові мітки завдань оновлюються лише після того, як запуск Heartbeat проходить свій звичайний шлях відповіді до кінця. Пропущені запуски `empty-heartbeat-file` / `no-tasks-due` не позначають завдання як завершені. -Режим завдань корисний, якщо ви хочете, щоб один heartbeat-файл містив кілька періодичних перевірок без оплати всіх із них на кожному тіці. +Режим завдань корисний, якщо ви хочете, щоб один файл Heartbeat містив кілька періодичних перевірок без оплати за всі з них на кожному тіку. ### Чи може агент оновлювати HEARTBEAT.md? Так — якщо ви його про це попросите. -`HEARTBEAT.md` — це просто звичайний файл у workspace агента, тож ви можете сказати +`HEARTBEAT.md` — це просто звичайний файл у робочому просторі агента, тож ви можете сказати агенту (у звичайному чаті) щось на кшталт: -- “Update `HEARTBEAT.md` to add a daily calendar check.” -- “Rewrite `HEARTBEAT.md` so it’s shorter and focused on inbox follow-ups.” +- “Онови `HEARTBEAT.md`, щоб додати щоденну перевірку календаря.” +- “Перепиши `HEARTBEAT.md`, щоб він був коротшим і зосередженим на подальших діях щодо вхідних.” Якщо ви хочете, щоб це відбувалося проактивно, можна також додати явний рядок у -свій prompt heartbeat, наприклад: “If the checklist becomes stale, update HEARTBEAT.md +запит Heartbeat, наприклад: “If the checklist becomes stale, update HEARTBEAT.md with a better one.” -Примітка щодо безпеки: не додавайте секрети (API-ключі, телефонні номери, приватні токени) до -`HEARTBEAT.md` — він стає частиною контексту prompt. +Примітка щодо безпеки: не розміщуйте секрети (API-ключі, номери телефонів, приватні токени) у +`HEARTBEAT.md` — він стає частиною контексту запиту. ## Ручне пробудження (на вимогу) -Ви можете поставити системну подію в чергу й негайно запустити heartbeat за допомогою: +Ви можете поставити системну подію в чергу й негайно запустити Heartbeat за допомогою: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -Якщо в кількох агентів налаштовано `heartbeat`, ручне пробудження негайно запустить heartbeat кожного з них. +Якщо в кількох агентів налаштовано `heartbeat`, ручне пробудження негайно запускає Heartbeat кожного з цих +агентів. Використовуйте `--mode next-heartbeat`, щоб дочекатися наступного запланованого тіку. -## Доставка reasoning (необов’язково) +## Доставка міркувань (необов’язково) -За замовчуванням heartbeat доставляють лише фінальний payload “answer”. +За замовчуванням Heartbeat доставляє лише фінальний payload “відповіді”. Якщо ви хочете прозорості, увімкніть: - `agents.defaults.heartbeat.includeReasoning: true` -Коли це ввімкнено, heartbeat також доставлятимуть окреме повідомлення з префіксом -`Reasoning:` (такий самий формат, як `/reasoning on`). Це може бути корисно, коли агент -керує кількома сесіями/codex-ами і ви хочете бачити, чому він вирішив написати -вам, — але це також може розкрити більше внутрішніх деталей, ніж вам потрібно. У групових чатах краще тримати це -вимкненим. +Коли це ввімкнено, Heartbeat також доставлятиме окреме повідомлення з префіксом +`Reasoning:` (такий самий формат, як у `/reasoning on`). Це може бути корисно, коли агент +керує кількома сесіями/codex-ами й ви хочете бачити, чому він вирішив +написати вам — але це також може розкрити більше внутрішніх деталей, ніж вам потрібно. Краще залишати це +вимкненим у групових чатах. -## Урахування вартості +## Усвідомлення вартості -Heartbeat запускають повноцінні цикли агента. Коротші інтервали спалюють більше токенів. Щоб зменшити витрати: +Heartbeat запускає повноцінні ходи агента. Коротші інтервали витрачають більше токенів. Щоб зменшити вартість: -- Використовуйте `isolatedSession: true`, щоб не надсилати повну історію розмови (~100K токенів зменшується приблизно до ~2-5K за запуск). +- Використовуйте `isolatedSession: true`, щоб не надсилати повну історію розмов (~100K токенів зменшується до ~2-5K на запуск). - Використовуйте `lightContext: true`, щоб обмежити bootstrap-файли лише `HEARTBEAT.md`. - Установіть дешевшу `model` (наприклад, `ollama/llama3.2:1b`). - Тримайте `HEARTBEAT.md` невеликим. @@ -455,7 +458,7 @@ Heartbeat запускають повноцінні цикли агента. К ## Пов’язане -- [Automation & Tasks](/uk/automation) — усі механізми автоматизації з одного погляду -- [Background Tasks](/uk/automation/tasks) — як відстежується відокремлена робота -- [Timezone](/uk/concepts/timezone) — як часовий пояс впливає на планування heartbeat -- [Troubleshooting](/uk/automation/cron-jobs#troubleshooting) — налагодження проблем автоматизації +- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації з одного погляду +- [Фонові завдання](/uk/automation/tasks) — як відстежується відокремлена робота +- [Часовий пояс](/uk/concepts/timezone) — як часовий пояс впливає на планування Heartbeat +- [Усунення проблем](/uk/automation/cron-jobs#troubleshooting) — налагодження проблем автоматизації diff --git a/docs/uk/gateway/opentelemetry.md b/docs/uk/gateway/opentelemetry.md index 73c769172..51dcb4e50 100644 --- a/docs/uk/gateway/opentelemetry.md +++ b/docs/uk/gateway/opentelemetry.md @@ -1,35 +1,35 @@ --- read_when: - - Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сеансів до збирача OpenTelemetry - - Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo або іншого бекенда OTLP + - Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry + - Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда - Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення -summary: Експортуйте діагностику OpenClaw до будь-якого збирача OpenTelemetry через plugin diagnostics-otel (OTLP/HTTP) +summary: Експортуйте діагностику OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP) title: Експорт OpenTelemetry x-i18n: - generated_at: "2026-04-25T23:50:24Z" + generated_at: "2026-04-26T01:42:41Z" model: gpt-5.4 provider: openai - source_hash: d478625ec525e76993d0a587b3aa8bc1c98a4d66d1ae8990316be241d3dc96a4 + source_hash: d670d7188d9c075b97743eae82e0aa999ac458a51c978a755e847e0b1648fa44 source_path: gateway/opentelemetry.md workflow: 15 --- -OpenClaw експортує діагностику через вбудований plugin `diagnostics-otel` -за допомогою **OTLP/HTTP (protobuf)**. Будь-який збирач або бекенд, що приймає OTLP/HTTP, -працює без змін у коді. Про локальні файлові журнали та те, як їх читати, див. -у [Журналюванні](/uk/logging). +OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel`, +використовуючи **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, +працює без змін у коді. Для локальних файлових журналів і способів їх читання див. +[Журналювання](/uk/logging). ## Як це працює разом - **Події діагностики** — це структуровані внутрішньопроцесні записи, які створюються - Gateway і вбудованими plugin для запусків моделей, потоку повідомлень, сеансів, черг + Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг та exec. -- **plugin `diagnostics-otel`** підписується на ці події та експортує їх як +- **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як OpenTelemetry **метрики**, **трасування** і **журнали** через OTLP/HTTP. -- Експортери підключаються лише тоді, коли увімкнено і поверхню діагностики, і plugin, - тому внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими. +- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і сам plugin, + тому внутрішньопроцесні накладні витрати за замовчуванням залишаються майже нульовими. -## Швидкий початок +## Швидкий старт ```json5 { @@ -56,7 +56,7 @@ OpenClaw експортує діагностику через вбудовани } ``` -Ви також можете увімкнути plugin з CLI: +Ви також можете ввімкнути plugin з CLI: ```bash openclaw plugins enable diagnostics-otel @@ -68,16 +68,16 @@ openclaw plugins enable diagnostics-otel ## Експортовані сигнали -| Сигнал | Що до нього входить | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черги, стану сеансу, exec і тиску на пам’ять. | -| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки Webhook/повідомлень, збирання контексту та циклів інструментів. | -| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли увімкнено `diagnostics.otel.logs`. | +| Сигнал | Що до нього входить | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черг, стану сесій, exec і тиску на пам’ять. | +| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | +| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | -Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три параметри за замовчуванням -увімкнені, коли `diagnostics.otel.enabled` має значення true. +Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три за замовчуванням увімкнені, +коли `diagnostics.otel.enabled` має значення true. -## Довідник з конфігурації +## Довідник конфігурації ```json5 { @@ -86,14 +86,17 @@ openclaw plugins enable diagnostics-otel otel: { enabled: true, endpoint: "http://otel-collector:4318", - protocol: "http/protobuf", // grpc ігнорується + tracesEndpoint: "http://otel-collector:4318/v1/traces", + metricsEndpoint: "http://otel-collector:4318/v1/metrics", + logsEndpoint: "http://otel-collector:4318/v1/logs", + protocol: "http/protobuf", // grpc is ignored serviceName: "openclaw-gateway", headers: { "x-collector-token": "..." }, traces: true, metrics: true, logs: true, - sampleRate: 0.2, // семплер кореневого спану, 0.0..1.0 - flushIntervalMs: 60000, // інтервал експорту метрик (мінімум 1000 мс) + sampleRate: 0.2, // root-span sampler, 0.0..1.0 + flushIntervalMs: 60000, // metric export interval (min 1000ms) captureContent: { enabled: false, inputMessages: false, @@ -109,101 +112,102 @@ openclaw plugins enable diagnostics-otel ### Змінні середовища -| Variable | Призначення | -| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. | -| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає дротовий протокол (сьогодні враховується лише `http/protobuf`). | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Установіть значення `gen_ai_latest_experimental`, щоб надсилати найновіший експериментальний атрибут GenAI для спанів (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | -| `OPENCLAW_OTEL_PRELOADED` | Установіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | +| Variable | Призначення | +| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для окремих сигналів, які використовуються, коли відповідний ключ конфігурації `diagnostics.otel.*Endpoint` не задано. Конфігурація для конкретного сигналу має пріоритет над змінною середовища для конкретного сигналу, яка має пріоритет над спільною кінцевою точкою. | +| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Встановіть значення `gen_ai_latest_experimental`, щоб надсилати останній експериментальний атрибут GenAI span (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені, низькокардинальні семантичні атрибути незалежно від цього. | +| `OPENCLAW_OTEL_PRELOADED` | Встановіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | ## Конфіденційність і захоплення вмісту -Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Спани містять обмежені -ідентифікатори (канал, провайдер, модель, категорія помилки, ідентифікатори запитів лише у вигляді хешів) -і ніколи не включають текст підказки, текст відповіді, входи інструментів, виходи інструментів або ключі сеансу. +Необроблений вміст моделей/інструментів **не** експортується за замовчуванням. Спани містять обмежені +ідентифікатори (channel, provider, model, категорія помилки, лише хешовані request id) +і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані інструментів або +ключі сесій. -Установлюйте `diagnostics.otel.captureContent.*` у значення `true` лише тоді, коли ваш збирач і -політика зберігання схвалені для тексту підказок, відповідей, інструментів або системних підказок. -Кожен вкладений ключ підключається незалежно: +Встановлюйте `diagnostics.otel.captureContent.*` у `true` лише тоді, коли ваш колектор і +політика зберігання схвалені для тексту промптів, відповідей, інструментів або system prompt. +Кожен підключ окремо вмикається за принципом opt-in: -- `inputMessages` — вміст користувацької підказки. -- `outputMessages` — вміст відповіді моделі. +- `inputMessages` — вміст запитів користувача. +- `outputMessages` — вміст відповідей моделі. - `toolInputs` — корисні навантаження аргументів інструментів. - `toolOutputs` — корисні навантаження результатів інструментів. -- `systemPrompt` — зібрана системна/розробницька підказка. +- `systemPrompt` — зібраний system/developer prompt. -Коли увімкнено будь-який вкладений ключ, спани моделей та інструментів отримують обмежені, відредаговані +Коли ввімкнено будь-який підключ, спани моделей та інструментів отримують обмежені, редаговані атрибути `openclaw.content.*` лише для цього класу. ## Семплювання та скидання -- **Трасування:** `diagnostics.otel.sampleRate` (лише для кореневого спану, `0.0` відкидає все, +- **Трасування:** `diagnostics.otel.sampleRate` (лише для root span, `0.0` відкидає все, `1.0` зберігає все). - **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). -- **Журнали:** журнали OTLP враховують `logging.level` (рівень файлового журналу). До - журналів OTLP **не** застосовується редагування для консолі. Інсталяціям із великим - обсягом даних варто віддавати перевагу семплюванню/фільтруванню на рівні OTLP-збирача, - а не локальному семплюванню. +- **Журнали:** OTLP-журнали враховують `logging.level` (рівень файлового журналу). Редагування + консолі **не** застосовується до OTLP-журналів. Для інсталяцій із великим обсягом + краще використовувати семплювання/фільтрацію на колекторі OTLP, а не локальне семплювання. ## Експортовані метрики -### Використання моделей +### Використання моделі -- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `gen_ai.client.token.usage` (гістограма, метрика семантичних угод GenAI, атрибути: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) -- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних угод GenAI, атрибути: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`) +- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.cost.usd` (лічильник, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.run.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.context.tokens` (гістограма, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `gen_ai.client.token.usage` (гістограма, метрика GenAI semantic conventions, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) +- `gen_ai.client.operation.duration` (гістограма, секунди, метрика GenAI semantic conventions, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язково `error.type`) ### Потік повідомлень -- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`, `openclaw.source`) -- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.delivery.started` (лічильник, атрибути: `openclaw.channel`, `openclaw.delivery.kind`) -- `openclaw.message.delivery.duration_ms` (гістограма, атрибути: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`) +- `openclaw.webhook.received` (лічильник, attrs: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.webhook.error` (лічильник, attrs: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.webhook.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.message.queued` (лічильник, attrs: `openclaw.channel`, `openclaw.source`) +- `openclaw.message.processed` (лічильник, attrs: `openclaw.channel`, `openclaw.outcome`) +- `openclaw.message.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.outcome`) +- `openclaw.message.delivery.started` (лічильник, attrs: `openclaw.channel`, `openclaw.delivery.kind`) +- `openclaw.message.delivery.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`) -### Черги та сеанси +### Черги та сесії -- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або `openclaw.channel=heartbeat`) -- `openclaw.queue.wait_ms` (гістограма, атрибути: `openclaw.lane`) -- `openclaw.session.state` (лічильник, атрибути: `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (лічильник, атрибути: `openclaw.state`) -- `openclaw.session.stuck_age_ms` (гістограма, атрибути: `openclaw.state`) -- `openclaw.run.attempt` (лічильник, атрибути: `openclaw.attempt`) +- `openclaw.queue.lane.enqueue` (лічильник, attrs: `openclaw.lane`) +- `openclaw.queue.lane.dequeue` (лічильник, attrs: `openclaw.lane`) +- `openclaw.queue.depth` (гістограма, attrs: `openclaw.lane` або `openclaw.channel=heartbeat`) +- `openclaw.queue.wait_ms` (гістограма, attrs: `openclaw.lane`) +- `openclaw.session.state` (лічильник, attrs: `openclaw.state`, `openclaw.reason`) +- `openclaw.session.stuck` (лічильник, attrs: `openclaw.state`) +- `openclaw.session.stuck_age_ms` (гістограма, attrs: `openclaw.state`) +- `openclaw.run.attempt` (лічильник, attrs: `openclaw.attempt`) ### Exec -- `openclaw.exec.duration_ms` (гістограма, атрибути: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) +- `openclaw.exec.duration_ms` (гістограма, attrs: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) ### Внутрішні метрики діагностики (пам’ять і цикл інструментів) -- `openclaw.memory.heap_used_bytes` (гістограма, атрибути: `openclaw.memory.kind`) +- `openclaw.memory.heap_used_bytes` (гістограма, attrs: `openclaw.memory.kind`) - `openclaw.memory.rss_bytes` (гістограма) -- `openclaw.memory.pressure` (лічильник, атрибути: `openclaw.memory.level`) -- `openclaw.tool.loop.iterations` (лічильник, атрибути: `openclaw.toolName`, `openclaw.outcome`) -- `openclaw.tool.loop.duration_ms` (гістограма, атрибути: `openclaw.toolName`, `openclaw.outcome`) +- `openclaw.memory.pressure` (лічильник, attrs: `openclaw.memory.level`) +- `openclaw.tool.loop.iterations` (лічильник, attrs: `openclaw.toolName`, `openclaw.outcome`) +- `openclaw.tool.loop.duration_ms` (гістограма, attrs: `openclaw.toolName`, `openclaw.outcome`) ## Експортовані спани - `openclaw.model.usage` - `openclaw.channel`, `openclaw.provider`, `openclaw.model` - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) - - `gen_ai.system` за замовчуванням, або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI + - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші GenAI semantic conventions - `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*` - `openclaw.run` - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory` - `openclaw.model.call` - - `gen_ai.system` за замовчуванням, або `gen_ai.provider.name`, якщо ввімкнено найновіші семантичні угоди GenAI + - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші GenAI semantic conventions - `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` - - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для ідентифікатора запиту до зовнішнього провайдера; сирі ідентифікатори не експортуються) + - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA від upstream request id провайдера; сирі id не експортуються) - `openclaw.tool.execution` - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` - `openclaw.exec` @@ -219,27 +223,27 @@ openclaw plugins enable diagnostics-otel - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту підказки, історії, відповіді або ключа сеансу) + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту prompt, history, response або ключів сесії) - `openclaw.tool.loop` - - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента) + - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, params або виводу інструмента) - `openclaw.memory.pressure` - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` Коли захоплення вмісту явно ввімкнено, спани моделей та інструментів також можуть -містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних -класів вмісту, які ви ввімкнули. +містити обмежені, редаговані атрибути `openclaw.content.*` для конкретних +класів вмісту, які ви явно ввімкнули. ## Каталог подій діагностики -Події нижче є основою для метрик і спанів вище. Plugin також можуть підписуватися -на них напряму без експорту через OTLP. +Події нижче лежать в основі метрик і спанів, наведених вище. Plugins також можуть +підписуватися на них напряму без експорту OTLP. -**Використання моделей** +**Використання моделі** -- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал, - ідентифікатори сеансів. `usage` — це облік провайдера/ходу для вартості й телеметрії; - `context.used` — це знімок поточного prompt/контексту, і він може бути меншим за - `usage.total` провайдера, коли задіяно кешований вхід або виклики циклу інструментів. +- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/channel, + id сесій. `usage` — це облік провайдера/ходу для вартості та телеметрії; + `context.used` — це поточний знімок prompt/context і він може бути меншим за + `usage.total` провайдера, коли залучено кешований ввід або виклики циклу інструментів. **Потік повідомлень** @@ -247,23 +251,23 @@ openclaw plugins enable diagnostics-otel - `message.queued` / `message.processed` - `message.delivery.started` / `message.delivery.completed` / `message.delivery.error` -**Черга та сеанс** +**Черга та сесія** - `queue.lane.enqueue` / `queue.lane.dequeue` - `session.state` / `session.stuck` - `run.attempt` -- `diagnostic.heartbeat` (агреговані лічильники: Webhook/черга/сеанс) +- `diagnostic.heartbeat` (агреговані лічильники: webhook/черга/сесія) **Exec** -- `exec.process.completed` — фінальний результат, тривалість, ціль, режим, код +- `exec.process.completed` — підсумковий результат, тривалість, ціль, режим, код виходу та тип збою. Текст команди й робочі каталоги не включаються. ## Без експортера -Ви можете залишити події діагностики доступними для plugin або користувацьких приймачів без -запуску `diagnostics-otel`: +Ви можете зберегти події діагностики доступними для plugins або користувацьких приймачів +без запуску `diagnostics-otel`: ```json5 { @@ -272,7 +276,7 @@ openclaw plugins enable diagnostics-otel ``` Для цільового виводу налагодження без підвищення `logging.level` використовуйте -прапори діагностики. Прапори нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або +прапорці діагностики. Прапорці нечутливі до регістру та підтримують wildcard-и (наприклад, `telegram.*` або `*`): ```json5 @@ -281,15 +285,15 @@ openclaw plugins enable diagnostics-otel } ``` -Або як одноразове перевизначення через змінну середовища: +Або як одноразове перевизначення через env: ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -Вивід прапорів записується до стандартного файлу журналу (`logging.file`) і все ще -редагується через `logging.redactSensitive`. Повний посібник: -[Прапори діагностики](/uk/diagnostics/flags). +Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і все ще +редагується `logging.redactSensitive`. Повний посібник: +[Прапорці діагностики](/uk/diagnostics/flags). ## Вимкнення @@ -302,10 +306,10 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway Ви також можете не додавати `diagnostics-otel` до `plugins.allow` або виконати `openclaw plugins disable diagnostics-otel`. -## Пов’язане +## Пов’язані матеріали -- [Журналювання](/uk/logging) — файлові журнали, консольний вивід, tailing у CLI та вкладка Logs у Control UI -- [Внутрішня структура журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі -- [Прапори діагностики](/uk/diagnostics/flags) — прапори цільового журналювання налагодження +- [Журналювання](/uk/logging) — файлові журнали, консольний вивід, tailing через CLI та вкладка Logs у Control UI +- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналювання налагодження - [Експорт діагностики](/uk/gateway/diagnostics) — інструмент пакета підтримки для операторів (окремо від експорту OTEL) -- [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник з полів `diagnostics.*` +- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` diff --git a/docs/uk/plugins/hooks.md b/docs/uk/plugins/hooks.md index 942f986bb..bc78d240a 100644 --- a/docs/uk/plugins/hooks.md +++ b/docs/uk/plugins/hooks.md @@ -1,30 +1,30 @@ --- read_when: - Ви створюєте plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу - - Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із plugin + - Вам потрібно заблокувати, переписати або вимагати схвалення для викликів інструментів із plugin - Ви обираєте між внутрішніми хуками та хуками plugin summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сесії та Gateway' title: Хуки Plugin x-i18n: - generated_at: "2026-04-26T00:29:05Z" + generated_at: "2026-04-26T01:42:41Z" model: gpt-5.4 provider: openai - source_hash: c9f1d08cb60b438b5478dc813600cc7c2b7a4169b0785812a04e395e1c893b02 + source_hash: 62d8c21db885abcb70c7aa940e3ce937df09d077587b153015c4c6c5169f4f1d source_path: plugins/hooks.md workflow: 15 --- -Хуки Plugin — це внутрішньопроцесні точки розширення для plugin OpenClaw. Використовуйте їх, -коли plugin потрібно перевіряти або змінювати запуски агентів, виклики інструментів, потік повідомлень, +Хуки Plugin — це точки розширення в процесі виконання для plugin OpenClaw. Використовуйте їх, +коли plugin має перевіряти або змінювати запуски агентів, виклики інструментів, потік повідомлень, життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway. -Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли вам потрібен невеликий -оператором встановлюваний скрипт `HOOK.md` для подій команд і Gateway, таких як +Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), якщо вам потрібен невеликий +встановлюваний оператором скрипт `HOOK.md` для подій команд і Gateway, таких як `/new`, `/reset`, `/stop`, `agent:bootstrap` або `gateway:startup`. ## Швидкий старт -Зареєструйте типізовані хуки plugin за допомогою `api.on(...)` у точці входу вашого plugin: +Зареєструйте типізовані хуки plugin за допомогою `api.on(...)` з точки входу вашого plugin: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -62,54 +62,54 @@ export default definePluginEntry({ ## Каталог хуків Хуки згруповано за поверхнею, яку вони розширюють. Назви, виділені **жирним**, приймають -результат рішення (блокування, скасування, перевизначення або вимога схвалення); усі інші -призначені лише для спостереження. +результат рішення (блокування, скасування, перевизначення або вимога схвалення); усі інші — +лише для спостереження. **Хід агента** -- `before_model_resolve` — перевизначає провайдера або модель перед завантаженням повідомлень сесії -- `before_prompt_build` — додає динамічний контекст або текст системного промпту перед викликом моделі -- `before_agent_start` — комбінована фаза лише для сумісності; натомість використовуйте два хуки вище -- **`before_agent_reply`** — коротко замикає хід моделі синтетичною відповіддю або тишею -- **`before_agent_finalize`** — перевіряє природну фінальну відповідь і запитує ще один прохід моделі -- `agent_end` — спостерігає фінальні повідомлення, стан успіху та тривалість запуску +- `before_model_resolve` — перевизначити провайдера або модель до завантаження повідомлень сесії +- `before_prompt_build` — додати динамічний контекст або текст системного prompt перед викликом моделі +- `before_agent_start` — об’єднана фаза лише для сумісності; натомість віддавайте перевагу двом хукам вище +- **`before_agent_reply`** — коротко замкнути хід моделі синтетичною відповіддю або тишею +- **`before_agent_finalize`** — перевірити природну фінальну відповідь і запросити ще один прохід моделі +- `agent_end` — спостерігати фінальні повідомлення, стан успіху та тривалість запуску **Спостереження за розмовою** -- `model_call_started` / `model_call_ended` — спостерігають очищені метадані виклику провайдера/моделі, час, результат і обмежені хеші request-id без вмісту промпту чи відповіді -- `llm_input` — спостерігає вхід провайдера (системний промпт, промпт, історію) -- `llm_output` — спостерігає вихід провайдера +- `model_call_started` / `model_call_ended` — спостерігати очищені метадані виклику провайдера/моделі, час виконання, результат і обмежені хеші request-id без вмісту prompt або відповіді +- `llm_input` — спостерігати вхідні дані провайдера (системний prompt, prompt, історію) +- `llm_output` — спостерігати вихідні дані провайдера **Інструменти** -- **`before_tool_call`** — переписує параметри інструмента, блокує виконання або вимагає схвалення -- `after_tool_call` — спостерігає результати інструмента, помилки й тривалість -- **`tool_result_persist`** — переписує повідомлення асистента, створене з результату інструмента -- **`before_message_write`** — перевіряє або блокує запис повідомлення в процесі (рідко) +- **`before_tool_call`** — переписати параметри інструмента, заблокувати виконання або вимагати схвалення +- `after_tool_call` — спостерігати результати інструмента, помилки та тривалість +- **`tool_result_persist`** — переписати повідомлення асистента, створене з результату інструмента +- **`before_message_write`** — перевірити або заблокувати запис повідомлення, що виконується (рідкісний випадок) -**Повідомлення і доставка** +**Повідомлення та доставка** -- **`inbound_claim`** — захоплює вхідне повідомлення перед маршрутизацією агента (синтетичні відповіді) -- `message_received` — спостерігає вхідний вміст, відправника, тред і метадані -- **`message_sending`** — переписує вихідний вміст або скасовує доставку -- `message_sent` — спостерігає успіх або помилку вихідної доставки -- **`before_dispatch`** — перевіряє або переписує вихідну диспетчеризацію перед передаванням у канал -- **`reply_dispatch`** — бере участь у фінальному конвеєрі диспетчеризації відповіді +- **`inbound_claim`** — перехопити вхідне повідомлення до маршрутизації агента (синтетичні відповіді) +- `message_received` — спостерігати вхідний вміст, відправника, потік і метадані +- **`message_sending`** — переписати вихідний вміст або скасувати доставку +- `message_sent` — спостерігати успішну або неуспішну вихідну доставку +- **`before_dispatch`** — перевірити або переписати вихідний dispatch до передачі каналу +- **`reply_dispatch`** — брати участь у фінальному конвеєрі dispatch відповіді **Сесії та Compaction** -- `session_start` / `session_end` — відстежують межі життєвого циклу сесії -- `before_compaction` / `after_compaction` — спостерігають або анотують цикли Compaction -- `before_reset` — спостерігає події скидання сесії (`/reset`, програмні скидання) +- `session_start` / `session_end` — відстежувати межі життєвого циклу сесії +- `before_compaction` / `after_compaction` — спостерігати або анотувати цикли Compaction +- `before_reset` — спостерігати події скидання сесії (`/reset`, програмні скидання) **Субагенти** -- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координують маршрутизацію субагентів і доставку після завершення +- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію субагентів і доставку завершення **Життєвий цикл** -- `gateway_start` / `gateway_stop` — запускають або зупиняють сервіси plugin разом із Gateway -- **`before_install`** — перевіряє сканування встановлення skill або plugin і за потреби блокує +- `gateway_start` / `gateway_stop` — запускати або зупиняти сервіси, якими володіє plugin, разом із Gateway +- **`before_install`** — перевіряти сканування встановлення skill або plugin і за потреби блокувати ## Політика викликів інструментів @@ -119,8 +119,8 @@ export default definePluginEntry({ - `event.params` - необов’язковий `event.runId` - необов’язковий `event.toolCallId` -- поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, і - діагностичний `ctx.trace` +- поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, + `ctx.runId`, `ctx.jobId` (встановлюється для запусків, керованих cron), і діагностичний `ctx.trace` Він може повертати: @@ -146,62 +146,65 @@ type BeforeToolCallResult = { Правила: - `block: true` є термінальним і пропускає обробники з нижчим пріоритетом. -- `block: false` вважається відсутністю рішення. +- `block: false` розглядається як відсутність рішення. - `params` переписує параметри інструмента для виконання. - `requireApproval` призупиняє запуск агента і запитує користувача через схвалення plugin. - Команда `/approve` може схвалювати як exec-, так і plugin-схвалення. -- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук + Команда `/approve` може схвалювати як exec, так і схвалення plugin. +- `block: true` з нижчим пріоритетом усе ще може заблокувати виклик після того, як хук з вищим пріоритетом запросив схвалення. - `onResolution` отримує остаточне рішення щодо схвалення — `allow-once`, `allow-always`, `deny`, `timeout` або `cancelled`. -### Збереження результатів інструмента +### Збереження результатів інструментів -Результати інструмента можуть містити структуровані `details` для UI-відображення, діагностики, -маршрутизації медіа або метаданих plugin. Розглядайте `details` як метадані часу виконання, -а не як вміст промпту: +Результати інструментів можуть містити структуровані `details` для відображення в UI, діагностики, +маршрутизації медіа або метаданих, якими володіє plugin. Сприймайте `details` як метадані часу виконання, +а не як вміст prompt: -- OpenClaw видаляє `toolResult.details` перед повторним відтворенням для провайдера і входом Compaction, - щоб метадані не ставали контекстом моделі. -- Збережені записи сесії містять лише обмежені `details`. Завеликі details +- OpenClaw видаляє `toolResult.details` перед повторним відтворенням провайдеру та введенням для Compaction, + тому метадані не стають контекстом моделі. +- Записи збережених сесій містять лише обмежені `details`. Надмірно великі details замінюються компактним підсумком і `persistedDetailsTruncated: true`. -- `tool_result_persist` і `before_message_write` виконуються перед фінальним - обмеженням збереження. Хуки все одно мають тримати повернуті `details` невеликими й уникати - розміщення тексту, важливого для промпту, лише в `details`; помітний для моделі вивід інструмента - слід розміщувати в `content`. +- `tool_result_persist` і `before_message_write` виконуються до фінального + обмеження збереження. Хуки все одно мають зберігати повернені `details` малими й уникати + розміщення тексту, важливого для prompt, лише в `details`; вивід інструмента, видимий моделі, + слід поміщати в `content`. -## Хуки промпту і моделі +## Хуки prompt і моделі Для нових plugin використовуйте хуки, специфічні для фази: -- `before_model_resolve`: отримує лише поточний промпт і метадані вкладень. - Повертає `providerOverride` або `modelOverride`. -- `before_prompt_build`: отримує поточний промпт і повідомлення сесії. - Повертає `prependContext`, `systemPrompt`, `prependSystemContext` або +- `before_model_resolve`: отримує лише поточний prompt і метадані вкладень. + Поверніть `providerOverride` або `modelOverride`. +- `before_prompt_build`: отримує поточний prompt і повідомлення сесії. + Поверніть `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext`. -`before_agent_start` залишається для сумісності. Натомість використовуйте явні хуки вище, -щоб ваш plugin не залежав від застарілої комбінованої фази. +`before_agent_start` залишається для сумісності. Віддавайте перевагу явним хукам вище, +щоб ваш plugin не залежав від застарілої об’єднаної фази. `before_agent_start` і `agent_end` містять `event.runId`, коли OpenClaw може -визначити активний запуск. Це саме значення також доступне в `ctx.runId`. +ідентифікувати активний запуск. Те саме значення також доступне в `ctx.runId`. +Запуски, керовані Cron, також надають `ctx.jobId` (ідентифікатор вихідного cron-завдання), щоб +хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретного запланованого +завдання. Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів провайдера, -яка не повинна отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів -або request ID провайдера. Ці хуки містять стабільні метадані, такі як +яка не повинна отримувати сирі prompt, історію, відповіді, заголовки, тіла запитів або +request ID провайдера. Ці хуки включають стабільні метадані, такі як `runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, фінальні -`durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може вивести +`durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може обчислити обмежений хеш request-id провайдера. `before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не виконується, коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб -попросити harness зробити ще один прохід моделі перед фіналізацією, `{ action: -"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат, щоб продовжити. -Нативні хуки Codex `Stop` передаються в цей хук як рішення OpenClaw +попросити harness виконати ще один прохід моделі перед фіналізацією, `{ action: +"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат, +щоб продовжити. Нативні хуки Codex `Stop` ретранслюються в цей хук як рішення OpenClaw `before_agent_finalize`. -Невбудовані plugin, яким потрібні `llm_input`, `llm_output`, +Небандловані plugin, яким потрібні `llm_input`, `llm_output`, `before_agent_finalize` або `agent_end`, мають встановити: ```json @@ -218,81 +221,82 @@ type BeforeToolCallResult = { } ``` -Хуки, що змінюють промпт, можна вимкнути для окремого plugin за допомогою +Хуки, що змінюють prompt, можна вимкнути для окремого plugin через `plugins.entries..hooks.allowPromptInjection=false`. ## Хуки повідомлень Використовуйте хуки повідомлень для маршрутизації на рівні каналу та політики доставки: -- `message_received`: спостерігає вхідний вміст, відправника, `threadId`, `messageId`, +- `message_received`: спостерігати вхідний вміст, відправника, `threadId`, `messageId`, `senderId`, необов’язкову кореляцію запуску/сесії та метадані. -- `message_sending`: переписує `content` або повертає `{ cancel: true }`. -- `message_sent`: спостерігає фінальний успіх або помилку. +- `message_sending`: переписати `content` або повернути `{ cancel: true }`. +- `message_sent`: спостерігати фінальний успіх або помилку. -Для відповідей TTS лише з аудіо `content` може містити прихований озвучений транскрипт, -навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього -`content` оновлює лише транскрипт, видимий для хуків; він не відображається як -підпис медіа. +Для TTS-відповідей лише з аудіо `content` може містити приховану вимовлену транскрипцію +навіть тоді, коли payload каналу не має видимого тексту/підпису. Переписування цього +`content` оновлює лише видиму для хука транскрипцію; вона не відображається як +підпис до медіа. Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні: `ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`, -`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Надавайте перевагу +`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Віддавайте перевагу цим полям першого класу, перш ніж читати застарілі метадані. -Надавайте перевагу типізованим полям `threadId` і `replyToId`, а не використанню +Віддавайте перевагу типізованим полям `threadId` і `replyToId` перед використанням метаданих, специфічних для каналу. -Правила рішень: +Правила прийняття рішень: - `message_sending` з `cancel: true` є термінальним. -- `message_sending` з `cancel: false` вважається відсутністю рішення. -- Переписаний `content` передається далі в хуки з нижчим пріоритетом, якщо пізніший хук +- `message_sending` з `cancel: false` розглядається як відсутність рішення. +- Переписаний `content` передається далі хукам із нижчим пріоритетом, якщо пізніший хук не скасує доставку. ## Хуки встановлення -`before_install` виконується після вбудованого сканування встановлень skill і plugin. +`before_install` виконується після вбудованого сканування встановлення skill і plugin. Поверніть додаткові висновки або `{ block: true, blockReason }`, щоб зупинити встановлення. -`block: true` є термінальним. `block: false` вважається відсутністю рішення. +`block: true` є термінальним. `block: false` розглядається як відсутність рішення. ## Життєвий цикл Gateway Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. Контекст надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для -перевірки та оновлення Cron. Використовуйте `gateway_stop` для очищення довготривалих -ресурсів. +перевірки та оновлення cron. Використовуйте `gateway_stop`, щоб очищати довготривалі +ресурси. -Не покладайтеся на внутрішній хук `gateway:startup` для сервісів часу виконання, що належать plugin. +Не покладайтеся на внутрішній хук `gateway:startup` для сервісів часу виконання, +якими володіє plugin. -## Майбутні вилучення застарілого +## Майбутні вилучення -Кілька поверхонь, суміжних із хуками, є застарілими, але все ще підтримуються. Мігруйте -до наступного мажорного релізу: +Кілька поверхонь, суміжних із хуками, є застарілими, але все ще підтримуються. Перейдіть +на новий підхід до наступного великого релізу: -- **Прості текстові конверти каналів** в обробниках `inbound_claim` і `message_received`. +- **Конверти каналів у відкритому тексті** в обробниках `inbound_claim` і `message_received`. Читайте `BodyForAgent` і структуровані блоки контексту користувача замість розбору плоского тексту конверта. Див. - [Прості текстові конверти каналів → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). -- **`before_agent_start`** залишається для сумісності. Нові plugin мають використовувати - `before_model_resolve` і `before_prompt_build` замість комбінованої + [Plaintext channel envelopes → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). +- **`before_agent_start`** залишається для сумісності. Новим plugin слід використовувати + `before_model_resolve` і `before_prompt_build` замість об’єднаної фази. -- **`onResolution` у `before_tool_call`** тепер використовує типізоване - об’єднання `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / +- **`onResolution` у `before_tool_call`** тепер використовує типізоване об’єднання + `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) замість довільного `string`. Повний список — реєстрація можливостей пам’яті, профіль thinking провайдера, -зовнішні провайдери auth, типи виявлення провайдерів, аксесори TaskFlow середовища виконання +зовнішні провайдери автентифікації, типи виявлення провайдерів, аксесори середовища виконання завдань і перейменування `command-auth` → `command-status` — див. у -[Міграція Plugin SDK → Активні застарілості](/uk/plugins/sdk-migration#active-deprecations). +[Міграція Plugin SDK → Активні застарівання](/uk/plugins/sdk-migration#active-deprecations). ## Пов’язане -- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарілості та графік вилучення +- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та графік вилучення - [Створення plugin](/uk/plugins/building-plugins) - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Точки входу Plugin](/uk/plugins/sdk-entrypoints) - [Внутрішні хуки](/uk/automation/hooks) -- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals) +- [Внутрішня архітектура plugin](/uk/plugins/architecture-internals) diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index 812137983..27e78dede 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -1,33 +1,35 @@ --- read_when: - - Ви створюєте новий плагін провайдера моделей + - Ви створюєте новий Plugin провайдера моделі - Ви хочете додати до OpenClaw OpenAI-сумісний проксі або власну LLM - - Вам потрібно зрозуміти автентифікацію провайдерів, каталоги та runtime-хуки + - Вам потрібно зрозуміти автентифікацію провайдера, каталоги та runtime hooks sidebarTitle: Provider plugins -summary: Покроковий посібник зі створення плагіна провайдера моделей для OpenClaw -title: Створення плагінів провайдерів +summary: Покроковий посібник зі створення Plugin провайдера моделі для OpenClaw +title: Створення Plugin провайдерів x-i18n: - generated_at: "2026-04-25T18:14:12Z" + generated_at: "2026-04-26T01:43:02Z" model: gpt-5.4 provider: openai - source_hash: c31f73619aa8fecf1b409bbd079683fae9ba996dd6ce22bd894b47cc76d5e856 + source_hash: 987ff69584a3e076189770c253ce48191103b5224e12216fd3d2fc03608ca240 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -Цей посібник проводить вас через створення плагіна провайдера, який додає до OpenClaw провайдера моделей (LLM). Наприкінці у вас буде провайдер із каталогом моделей, автентифікацією через API-ключ і динамічним визначенням моделей. +Цей посібник покроково пояснює, як створити Plugin провайдера, який додає провайдера моделі +(LLM) до OpenClaw. Наприкінці у вас буде провайдер із каталогом моделей, +автентифікацією за API-ключем і динамічним визначенням моделі. - Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Початок роботи](/uk/plugins/building-plugins) про базову структуру пакета - та налаштування маніфесту. + Якщо ви раніше не створювали жодного Plugin для OpenClaw, спочатку прочитайте + [Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою + структурою пакета та налаштуванням маніфесту. - Плагіни провайдерів додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель + Plugin провайдерів додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель має працювати через нативний демон агента, який керує потоками, Compaction або подіями інструментів, поєднайте провайдера з [agent harness](/uk/plugins/sdk-agent-harness), - замість того щоб виносити деталі протоколу демона в core. + а не вбудовуйте деталі протоколу демона в core. ## Покроковий розбір @@ -92,12 +94,12 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти - облікові дані без завантаження runtime вашого плагіна. Додавайте `providerAuthAliases`, + облікові дані без завантаження runtime вашого Plugin. Додавайте `providerAuthAliases`, коли варіант провайдера має повторно використовувати автентифікацію іншого id провайдера. `modelSupport` - необов’язковий і дає OpenClaw змогу автоматично завантажувати ваш плагін провайдера зі скорочених - id моделей, таких як `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте + є необов’язковим і дозволяє OpenClaw автоматично завантажувати ваш Plugin провайдера зі скорочених + id моделей, як-от `acme-large`, ще до появи runtime hooks. Якщо ви публікуєте провайдера в ClawHub, поля `openclaw.compat` і `openclaw.build` - обов’язкові в `package.json`. + є обов’язковими в `package.json`. @@ -177,8 +179,8 @@ x-i18n: `openclaw onboard --acme-ai-api-key ` і вибрати `acme-ai/acme-large` як свою модель. - Якщо апстрим-провайдер використовує інші керувальні токени, ніж OpenClaw, додайте - невелике двонапрямлене текстове перетворення замість заміни шляху потоку: + Якщо провайдер вище за потоком використовує інші керівні токени, ніж OpenClaw, додайте + невелике двоспрямоване текстове перетворення замість заміни шляху потоку: ```typescript api.registerTextTransforms({ @@ -195,13 +197,13 @@ x-i18n: }); ``` - `input` переписує фінальний системний промпт і вміст текстових повідомлень перед + `input` переписує фінальний системний prompt і текстовий вміст повідомлень перед передаванням. `output` переписує текстові дельти асистента і фінальний текст до того, як - OpenClaw розбере власні керувальні маркери або виконає доставлення в канал. + OpenClaw розбере власні керівні маркери або доставку через канал. - Для вбудованих провайдерів, які реєструють лише одного текстового провайдера з автентифікацією - через API-ключ і одним runtime на основі каталогу, віддавайте перевагу вужчому - хелперу `defineSingleProviderPluginEntry(...)`: + Для вбудованих провайдерів, які реєструють лише один текстовий провайдер з + автентифікацією за API-ключем плюс один runtime з підтримкою каталогу, віддавайте перевагу + вужчому допоміжному методу `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -241,33 +243,33 @@ x-i18n: }); ``` - `buildProvider` — це шлях живого каталогу, який використовується, коли OpenClaw може визначити реальну + `buildProvider` — це шлях живого каталогу, який використовується, коли OpenClaw може визначити справжню автентифікацію провайдера. Він може виконувати специфічне для провайдера виявлення. Використовуйте - `buildStaticProvider` лише для офлайн-рядків, які безпечно показувати до налаштування автентифікації; - він не повинен вимагати облікових даних або виконувати мережеві запити. - У поточному відображенні OpenClaw `models list --all` статичні каталоги - виконуються лише для вбудованих плагінів провайдерів із порожньою конфігурацією, порожнім env і без + `buildStaticProvider` лише для офлайнових рядків, які безпечно показувати до налаштування + автентифікації; він не повинен вимагати облікових даних або виконувати мережеві запити. + Відображення `models list --all` в OpenClaw зараз виконує статичні каталоги + лише для вбудованих Plugin провайдерів, з порожньою конфігурацією, порожнім env і без шляхів агента/робочого простору. - Якщо ваш потік автентифікації також має виправляти `models.providers.*`, псевдоніми та - модель агента за замовчуванням під час онбордингу, використовуйте preset-хелпери з - `openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери: + Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, псевдоніми та + модель агента за замовчуванням під час онбордингу, використовуйте готові допоміжні методи з + `openclaw/plugin-sdk/provider-onboard`. Найвужчі допоміжні методи: `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Коли нативний endpoint провайдера підтримує потокові блоки використання на - звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з + Коли нативна кінцева точка провайдера підтримує потокові блоки використання в + звичайному транспорті `openai-completions`, віддавайте перевагу спільним допоміжним методам каталогу з `openclaw/plugin-sdk/provider-catalog-shared`, а не жорсткому кодуванню перевірок id провайдера. `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей endpoint, тому - нативні endpoint-и у стилі Moonshot/DashScope також підключаються, навіть якщо плагін використовує + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з карти можливостей кінцевої точки, + тому нативні кінцеві точки у стилі Moonshot/DashScope також залишаються включеними, навіть коли Plugin використовує власний id провайдера. - - Якщо ваш провайдер приймає довільні id моделей (наприклад, проксі або маршрутизатор), + + Якщо ваш провайдер приймає довільні id моделей, (як-от проксі або маршрутизатор), додайте `resolveDynamicModel`: ```typescript @@ -294,12 +296,12 @@ x-i18n: - - Більшості провайдерів потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки - поступово, відповідно до потреб вашого провайдера. + + Більшості провайдерів достатньо `catalog` + `resolveDynamicModel`. Додавайте hooks + поступово, залежно від потреб вашого провайдера. - Спільні хелпери-конструктори тепер охоплюють найпоширеніші - сімейства replay/tool-compat, тому плагінам зазвичай не потрібно вручну підключати кожен хук окремо: + Спільні допоміжні конструктори тепер охоплюють найпоширеніші сімейства replay/tool-compat, + тому Plugin зазвичай не потрібно вручну підключати кожен hook окремо: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -319,43 +321,43 @@ x-i18n: }); ``` - Доступні сьогодні сімейства replay: + Доступні сімейства replay на сьогодні: - | Family | Що воно підключає | Вбудовані приклади | + | Сімейство | Що воно підключає | Вбудовані приклади | | --- | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту | `moonshot`, `ollama`, `xai`, `zai` | - | `anthropic-by-model` | Claude-орієнтована політика replay, що вибирається за `modelId`, тож транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель справді є id Claude | `amazon-bedrock`, `anthropic-vertex` | - | `google-gemini` | Нативна політика replay Gemini плюс очищення bootstrap replay і режим tagged reasoning-output | `google`, `google-gemini-cli` | - | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini чи переписування bootstrap | `openrouter`, `kilocode`, `opencode`, `opencode-go` | - | `hybrid-anthropic-openai` | Гібридна політика для провайдерів, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | `minimax` | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з санітизацією id викликів інструментів, виправленнями порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту | `moonshot`, `ollama`, `xai`, `zai` | + | `anthropic-by-model` | Політика replay з урахуванням Claude, вибрана за `modelId`, щоб транспорти повідомлень Anthropic отримували очищення thinking-block, специфічне для Claude, лише коли визначена модель справді має id Claude | `amazon-bedrock`, `anthropic-vertex` | + | `google-gemini` | Нативна політика replay Gemini плюс санітизація bootstrap replay і режим виводу reasoning з тегами | `google`, `google-gemini-cli` | + | `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini або переписування bootstrap | `openrouter`, `kilocode`, `opencode`, `opencode-go` | + | `hybrid-anthropic-openai` | Гібридна політика для провайдерів, які поєднують поверхні моделей Anthropiс-message і OpenAI-compatible в одному Plugin; необов’язкове відкидання thinking-block лише для Claude лишається обмеженим стороною Anthropic | `minimax` | - Доступні сьогодні сімейства потоків: + Доступні сімейства потоків на сьогодні: - | Family | Що воно підключає | Вбудовані приклади | + | Сімейство | Що воно підключає | Вбудовані приклади | | --- | --- | --- | - | `google-thinking` | Нормалізація thinking payload Gemini на спільному шляху потоку | `google`, `google-gemini-cli` | - | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху проксі-потоку, де `kilo/auto` і непідтримувані id reasoning проксі пропускають ін’єктований thinking | `kilocode` | - | `moonshot-thinking` | Відображення binary native-thinking payload Moonshot з конфігурації + рівня `/think` | `moonshot` | + | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху потоку | `google`, `google-gemini-cli` | + | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху проксі-потоку, де `kilo/auto` і непідтримувані id reasoning проксі пропускають ін’єкований thinking | `kilocode` | + | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot з конфігурації + рівня `/think` | `moonshot` | | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху потоку | `minimax`, `minimax-portal` | - | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки attribution, `/fast`/`serviceTier`, текстова verbosity, нативний вебпошук Codex, формування payload для reasoning-compat і керування контекстом Responses | `openai`, `openai-codex` | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів проксі, з централізованою обробкою пропусків unsupported-model/`auto` | `openrouter` | - | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для провайдерів на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнено явно | `zai` | + | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, детальність тексту, нативний вебпошук Codex, формування payload для сумісності reasoning і керування контекстом Responses | `openai`, `openai-codex` | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів проксі, де пропуски для непідтримуваних моделей/`auto` обробляються централізовано | `openrouter` | + | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для провайдерів на кшталт Z.AI, яким потрібен потоковий режим інструментів, якщо його явно не вимкнено | `zai` | - - Кожен конструктор сімейства складається з публічних низькорівневих хелперів, експортованих із того самого пакета, до яких можна звертатися, коли провайдеру потрібно вийти за межі типового шаблону: + + Кожен конструктор сімейства складається з нижчорівневих публічних допоміжних методів, експортованих із того самого пакета, до яких можна звернутися, коли провайдеру потрібно відійти від типового шаблону: - - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` і сирі конструктори replay (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Також експортує хелпери replay для Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) і хелпери endpoint/model (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`). - - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, а також спільні обгортки OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), OpenAI-compatible-обгортка DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`) і спільні обгортки проксі/провайдера (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`). - - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, базові хелпери схем Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) і хелпери compat для xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Вбудований плагін xAI використовує `normalizeResolvedModel` + `contributeResolvedModelCompat` разом із ними, щоб правила xAI залишалися у власності провайдера. + - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` і сирі конструктори replay (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Також експортує допоміжні методи replay Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) і допоміжні методи для endpoint/моделей (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`). + - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, а також спільні обгортки OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), OpenAI-сумісна обгортка DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`) і спільні обгортки проксі/провайдера (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`). + - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, базові допоміжні методи схем Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) і допоміжні методи сумісності xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Вбудований Plugin xAI використовує `normalizeResolvedModel` + `contributeResolvedModelCompat` разом із ними, щоб правила xAI залишалися у власності провайдера. - Деякі хелпери потоку навмисно залишаються локальними для провайдера. `@openclaw/anthropic-provider` зберігає `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі конструктори обгорток Anthropic у власному публічному seam `api.ts` / `contract-api.ts`, оскільки вони кодують обробку бета-версій Claude OAuth і gating `context1m`. Аналогічно плагін xAI зберігає нативне формування xAI Responses у власному `wrapStreamFn` (псевдоніми `/fast`, `tool_stream` за замовчуванням, очищення unsupported strict-tool, видалення reasoning-payload, специфічного для xAI). + Деякі допоміжні методи потоків навмисно залишаються локальними для провайдера. `@openclaw/anthropic-provider` тримає `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі конструктори обгорток Anthropic у власному публічному seam `api.ts` / `contract-api.ts`, оскільки вони кодують обробку Claude OAuth beta і gating `context1m`. Plugin xAI так само зберігає формування нативних xAI Responses у власному `wrapStreamFn` (`/fast` aliases, `tool_stream` за замовчуванням, очищення непідтримуваних strict-tool, видалення payload reasoning, специфічного для xAI). - Такий самий шаблон package-root також лежить в основі `@openclaw/openai-provider` (конструктори провайдера, хелпери моделі за замовчуванням, конструктори realtime-провайдера) і `@openclaw/openrouter-provider` (конструктор провайдера плюс хелпери онбордингу/конфігурації). + Той самий шаблон на рівні кореня пакета також лежить в основі `@openclaw/openai-provider` (конструктори провайдера, допоміжні методи моделі за замовчуванням, конструктори realtime-провайдера) і `@openclaw/openrouter-provider` (конструктор провайдера плюс допоміжні методи онбордингу/конфігурації). - - Для провайдерів, яким потрібен обмін токенами перед кожним викликом інференсу: + + Для провайдерів, яким потрібен обмін токенів перед кожним викликом інференсу: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -368,8 +370,8 @@ x-i18n: }, ``` - - Для провайдерів, яким потрібні користувацькі заголовки запиту або модифікації тіла: + + Для провайдерів, яким потрібні власні заголовки запиту або модифікації тіла: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -386,9 +388,9 @@ x-i18n: }, ``` - + Для провайдерів, яким потрібні нативні заголовки запиту/сеансу або метадані в - узагальнених HTTP- чи WebSocket-транспортах: + загальних HTTP- або WebSocket-транспортах: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -408,7 +410,7 @@ x-i18n: }), ``` - + Для провайдерів, які надають дані про використання/білінг: ```typescript @@ -423,76 +425,76 @@ x-i18n: - - OpenClaw викликає хуки в такому порядку. Більшість провайдерів використовують лише 2–3: + + OpenClaw викликає hooks у такому порядку. Більшість провайдерів використовують лише 2–3: | # | Hook | Коли використовувати | | --- | --- | --- | - | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням | - | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | - | 3 | `normalizeModelId` | Очищення застарілих/preview-псевдонімів `model-id` перед пошуком | - | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | + | 1 | `catalog` | Каталог моделей або базові значення `baseUrl` | + | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, якими керує провайдер, під час матеріалізації конфігурації | + | 3 | `normalizeModelId` | Очищення legacy/preview aliases id моделі перед пошуком | + | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Переписування native streaming-usage compat для конфігурованих провайдерів | - | 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить провайдеру | - | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локального/self-hosted або конфігураційного сценарію | - | 9 | `shouldDeferSyntheticProfileAuth` | Опускати синтетичні заповнювачі stored-profile нижче за env/config auth | - | 10 | `resolveDynamicModel` | Приймати довільні id апстрим-моделей | + | 6 | `applyNativeStreamingUsageCompat` | Переписування сумісності native streaming-usage для конфігураційних провайдерів | + | 7 | `resolveConfigApiKey` | Визначення автентифікації маркера env, яким керує провайдер | + | 8 | `resolveSyntheticAuth` | Синтетична автентифікація local/self-hosted або з конфігурації | + | 9 | `shouldDeferSyntheticProfileAuth` | Опускання синтетичних placeholder збереженого профілю нижче за автентифікацію env/config | + | 10 | `resolveDynamicModel` | Прийом довільних id моделей вищого рівня | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | - | 13 | `contributeResolvedModelCompat` | Прапорці compat для моделей вендора за іншим сумісним транспортом | - | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | - | 15 | `normalizeToolSchemas` | Очищення схем інструментів, що належать провайдеру, перед реєстрацією | - | 16 | `inspectToolSchemas` | Діагностика схем інструментів, що належать провайдеру | + | 13 | `contributeResolvedModelCompat` | Прапорці сумісності для моделей вендора за іншим сумісним транспортом | + | 14 | `capabilities` | Legacy статичний набір можливостей; лише для сумісності | + | 15 | `normalizeToolSchemas` | Очищення схем інструментів, яким керує провайдер, перед реєстрацією | + | 16 | `inspectToolSchemas` | Діагностика схем інструментів, якою керує провайдер | | 17 | `resolveReasoningOutputMode` | Контракт tagged vs native reasoning-output | | 18 | `prepareExtraParams` | Параметри запиту за замовчуванням | - | 19 | `createStreamFn` | Повністю користувацький транспорт StreamFn | - | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному шляху потоку | + | 19 | `createStreamFn` | Повністю власний транспорт StreamFn | + | 20 | `wrapStreamFn` | Обгортки власних заголовків/тіла на звичайному шляху потоку | | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn | - | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / cool-down | - | 23 | `formatApiKey` | Користувацька форма runtime-токена | - | 24 | `refreshOAuth` | Користувацьке оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Підказка для виправлення автентифікації | - | 26 | `matchesContextOverflowError` | Виявлення переповнення, що належить провайдеру | - | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить провайдеру | - | 28 | `isCacheTtlEligible` | Гейтинг TTL кешу промптів | - | 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію | - | 30 | `suppressBuiltInModel` | Приховати застарілі апстрим-рядки | + | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сеансу WS / cool-down | + | 23 | `formatApiKey` | Власна форма runtime-токена | + | 24 | `refreshOAuth` | Власне оновлення OAuth | + | 25 | `buildAuthDoctorHint` | Підказка з відновлення автентифікації | + | 26 | `matchesContextOverflowError` | Визначення переповнення, яким керує провайдер | + | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, якою керує провайдер | + | 28 | `isCacheTtlEligible` | Gating TTL кешу prompt | + | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію | + | 30 | `suppressBuiltInModel` | Приховування застарілих рядків вищого рівня | | 31 | `augmentModelCatalog` | Синтетичні рядки для forward-compat | | 32 | `resolveThinkingProfile` | Набір опцій `/think`, специфічний для моделі | - | 33 | `isBinaryThinking` | Сумісність binary thinking on/off | + | 33 | `isBinaryThinking` | Сумісність двійкового вмикання/вимикання thinking | | 34 | `supportsXHighThinking` | Сумісність підтримки reasoning `xhigh` | | 35 | `resolveDefaultThinkingLevel` | Сумісність політики `/think` за замовчуванням | | 36 | `isModernModelRef` | Відповідність live/smoke моделей | - | 37 | `prepareRuntimeAuth` | Обмін токенами перед інференсом | - | 38 | `resolveUsageAuth` | Користувацький розбір облікових даних usage | - | 39 | `fetchUsageSnapshot` | Користувацький endpoint usage | - | 40 | `createEmbeddingProvider` | Адаптер embedding, що належить провайдеру, для пам’яті/пошуку | - | 41 | `buildReplayPolicy` | Користувацька політика replay/Compaction транскрипту | - | 42 | `sanitizeReplayHistory` | Специфічні для провайдера переписування replay після загального очищення | - | 43 | `validateReplayTurns` | Сувора валідація replay-turn перед вбудованим runner | + | 37 | `prepareRuntimeAuth` | Обмін токенів перед інференсом | + | 38 | `resolveUsageAuth` | Власний розбір облікових даних використання | + | 39 | `fetchUsageSnapshot` | Власна кінцева точка використання | + | 40 | `createEmbeddingProvider` | Адаптер embeddings, яким керує провайдер, для пам’яті/пошуку | + | 41 | `buildReplayPolicy` | Власна політика replay/Compaction стенограми | + | 42 | `sanitizeReplayHistory` | Переписування replay, специфічне для провайдера, після загального очищення | + | 43 | `validateReplayTurns` | Сувора валідація turn replay перед вбудованим runner | | 44 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) | Примітки щодо runtime fallback: - - `normalizeConfig` спочатку перевіряє відповідний провайдер, а потім інші плагіни провайдерів, що підтримують хуки, доки один із них справді не змінить конфігурацію. Якщо жоден хук провайдера не перепише підтримуваний запис конфігурації сімейства Google, усе одно буде застосовано вбудований нормалізатор конфігурації Google. - - `resolveConfigApiKey` використовує хук провайдера, якщо він доступний. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, хоча сама runtime-автентифікація Bedrock, як і раніше, використовує стандартний ланцюжок AWS SDK. - - `resolveSystemPromptContribution` дає змогу провайдеру ін’єктувати cache-aware настанови системного промпту для сімейства моделей. Віддавайте йому перевагу над `before_prompt_build`, коли поведінка належить одному провайдеру/сімейству моделей і має зберігати стабільний/динамічний поділ кешу. + - `normalizeConfig` спочатку перевіряє відповідний провайдер, а потім інші Plugin провайдерів із підтримкою hooks, доки один із них справді не змінить конфігурацію. Якщо жоден hook провайдера не перепише підтримуваний запис конфігурації сімейства Google, усе одно застосовується вбудований нормалізатор конфігурації Google. + - `resolveConfigApiKey` використовує hook провайдера, якщо він доступний. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, хоча сама runtime-автентифікація Bedrock і далі використовує стандартний ланцюжок AWS SDK. + - `resolveSystemPromptContribution` дозволяє провайдеру впроваджувати системні вказівки prompt з урахуванням кешу для сімейства моделей. Віддавайте йому перевагу над `before_prompt_build`, коли поведінка належить одному провайдеру/сімейству моделей і має зберігати стабільний/динамічний поділ кешу. - Детальні описи та приклади з реального світу дивіться в [Внутрішня архітектура: runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). + Детальні описи та реальні приклади дивіться в [Внутрішні механізми: runtime hooks провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). - Плагін провайдера може реєструвати мовлення, транскрипцію в realtime, realtime-голос, - розуміння медіа, генерацію зображень, генерацію відео, веботримання, - і вебпошук поряд із текстовим інференсом. OpenClaw класифікує це як - плагін **hybrid-capability** — рекомендований шаблон для корпоративних плагінів - (один плагін на вендора). Див. - [Внутрішня архітектура: володіння можливостями](/uk/plugins/architecture#capability-ownership-model). + Plugin провайдера може реєструвати синтез мовлення, транскрибування в realtime, + голос у realtime, розуміння медіа, генерацію зображень, генерацію відео, web fetch + і вебпошук разом із текстовим інференсом. OpenClaw класифікує це як + Plugin **hybrid-capability** — рекомендований шаблон для корпоративних Plugin + (один Plugin на вендора). Див. + [Внутрішні механізми: володіння можливостями](/uk/plugins/architecture#capability-ownership-model). - Реєструйте кожну можливість у `register(api)` поруч із наявним + Реєструйте кожну можливість усередині `register(api)` поряд із вашим наявним викликом `api.registerProvider(...)`. Вибирайте лише ті вкладки, які вам потрібні: @@ -532,14 +534,14 @@ x-i18n: ``` Використовуйте `assertOkOrThrowProviderError(...)` для HTTP-збоїв провайдера, щоб - плагіни спільно використовували обмежене читання тіла помилки, розбір JSON-помилок і + Plugin спільно використовували обмежене читання тіла помилки, розбір помилок JSON і суфікси request-id. - + Віддавайте перевагу `createRealtimeTranscriptionWebSocketSession(...)` — спільний - хелпер обробляє захоплення проксі, backoff повторного підключення, flush під час закриття, готові - handshake, постановку аудіо в чергу та діагностику подій закриття. Ваш плагін - лише відображає події апстриму. + допоміжний метод обробляє перехоплення проксі, backoff при повторному з’єднанні, flush під час закриття, готові handshake, + чергування аудіо та діагностику подій закриття. Ваш Plugin + лише відображає події вищого рівня. ```typescript api.registerRealtimeTranscriptionProvider({ @@ -577,13 +579,13 @@ x-i18n: }); ``` - Провайдери пакетного STT, які надсилають multipart-аудіо через POST, повинні використовувати + Для пакетних провайдерів STT, які надсилають multipart-аудіо через POST, слід використовувати `buildAudioTranscriptionFormData(...)` з - `openclaw/plugin-sdk/provider-http`. Хелпер нормалізує - імена файлів завантаження, зокрема AAC-завантаження, яким потрібне ім’я файлу у стилі M4A для - сумісних API транскрипції. + `openclaw/plugin-sdk/provider-http`. Цей допоміжний метод нормалізує імена + файлів для завантаження, зокрема завантаження AAC, яким потрібне ім’я файлу у стилі M4A для + сумісних API транскрибування. - + ```typescript api.registerRealtimeVoiceProvider({ id: "acme-ai", @@ -612,11 +614,11 @@ x-i18n: ``` - Можливості відео використовують форму, що **враховує режим**: `generate`, - `imageToVideo` і `videoToVideo`. Плоских агрегованих полів на кшталт - `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` недостатньо, - щоб коректно оголосити підтримку режиму трансформації або чисто вимкнені режими. - Генерація музики наслідує той самий шаблон із явними блоками `generate` / + Можливості відео використовують форму з урахуванням **режимів**: `generate`, + `imageToVideo` і `videoToVideo`. Плоских агрегованих полів, таких як + `maxInputImages` / `maxInputVideos` / `maxDurationSeconds`, недостатньо, + щоб коректно оголошувати підтримку режимів перетворення або вимкнені режими. + Генерація музики дотримується того самого шаблону з явними блоками `generate` / `edit`. ```typescript @@ -631,19 +633,25 @@ x-i18n: label: "Acme Video", capabilities: { generate: { maxVideos: 1, maxDurationSeconds: 10, supportsResolution: true }, - imageToVideo: { enabled: true, maxVideos: 1, maxInputImages: 1, maxDurationSeconds: 5 }, + imageToVideo: { + enabled: true, + maxVideos: 1, + maxInputImages: 1, + maxInputImagesByModel: { "acme/reference-to-video": 9 }, + maxDurationSeconds: 5, + }, videoToVideo: { enabled: false }, }, generateVideo: async (req) => ({ videos: [] }), }); ``` - + ```typescript api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "Отримуйте сторінки через backend рендерингу Acme.", + hint: "Fetch pages through Acme's rendering backend.", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -654,7 +662,7 @@ x-i18n: acme.apiKey = value; }, createTool: () => ({ - description: "Отримати сторінку через Acme Fetch.", + description: "Fetch a page through Acme Fetch.", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -707,14 +715,14 @@ x-i18n: ## Публікація в ClawHub -Плагіни провайдерів публікуються так само, як і будь-які інші зовнішні плагіни коду: +Plugin провайдерів публікуються так само, як і будь-який інший зовнішній кодовий Plugin: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів повинні використовувати +Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети Plugin мають використовувати `clawhub package publish`. ## Структура файлів @@ -722,34 +730,34 @@ clawhub package publish your-org/your-plugin ``` /acme-ai/ ├── package.json # метадані openclaw.providers -├── openclaw.plugin.json # Маніфест із метаданими автентифікації провайдера +├── openclaw.plugin.json # маніфест із метаданими автентифікації провайдера ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Тести - └── usage.ts # Endpoint usage (необов’язково) + ├── provider.test.ts # тести + └── usage.ts # endpoint використання (необов’язково) ``` ## Довідка щодо порядку каталогу -`catalog.order` керує тим, коли ваш каталог зливається відносно вбудованих +`catalog.order` визначає, коли ваш каталог об’єднується відносно вбудованих провайдерів: -| Order | Коли | Випадок використання | +| Порядок | Коли | Випадок використання | | --------- | ------------- | ---------------------------------------------- | -| `simple` | Перший прохід | Прості провайдери з API-ключем | -| `profile` | Після simple | Провайдери, що залежать від профілів автентифікації | +| `simple` | Перший прохід | Звичайні провайдери з API-ключем | +| `profile` | Після simple | Провайдери, обмежені профілями автентифікації | | `paired` | Після profile | Синтез кількох пов’язаних записів | | `late` | Останній прохід | Перевизначення наявних провайдерів (перемагає при колізії) | ## Наступні кроки -- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал -- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, пошук, subagent) -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath -- [Внутрішня архітектура плагінів](/uk/plugins/architecture-internals#provider-runtime-hooks) — деталі хуків і вбудовані приклади +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш Plugin також надає канал +- [SDK Runtime](/uk/plugins/sdk-runtime) — допоміжні методи `api.runtime` (TTS, пошук, subagent) +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з імпорту підшляхів +- [Внутрішні механізми Plugin](/uk/plugins/architecture-internals#provider-runtime-hooks) — подробиці про hooks і вбудовані приклади ## Пов’язане - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення плагінів](/uk/plugins/building-plugins) -- [Створення плагінів каналів](/uk/plugins/sdk-channel-plugins) +- [Створення Plugin](/uk/plugins/building-plugins) +- [Створення Plugin каналів](/uk/plugins/sdk-channel-plugins) diff --git a/docs/uk/providers/fal.md b/docs/uk/providers/fal.md index ec557fc5d..51d7e83dd 100644 --- a/docs/uk/providers/fal.md +++ b/docs/uk/providers/fal.md @@ -1,31 +1,31 @@ --- read_when: - Ви хочете використовувати генерацію зображень fal в OpenClaw - - Вам потрібен потік автентифікації `FAL_KEY` - - Вам потрібні типові налаштування fal для `image_generate` або `video_generate` + - Вам потрібен потік автентифікації FAL_KEY + - Вам потрібні типові значення fal для `image_generate` або `video_generate` summary: Налаштування генерації зображень і відео fal в OpenClaw title: Fal x-i18n: - generated_at: "2026-04-25T19:29:26Z" + generated_at: "2026-04-26T01:43:11Z" model: gpt-5.4 provider: openai - source_hash: 26f28ff7c99dbe386fd2a42f8f85ae8bc34a1510decd302462ab9c8a4a8428ba + source_hash: e6789f0fa1140cf76f0206c7384a79ee8b96de4af9e1dfedc00e5a3382f742bb source_path: providers/fal.md workflow: 15 --- -OpenClaw постачається з вбудованим провайдером `fal` для хостингової генерації зображень і відео. +OpenClaw постачається з вбудованим провайдером `fal` для хостованої генерації зображень і відео. | Властивість | Значення | | ----------- | ------------------------------------------------------------ | | Провайдер | `fal` | -| Автентифікація | `FAL_KEY` (канонічний; `FAL_API_KEY` також працює як запасний варіант) | +| Автентифікація | `FAL_KEY` (канонічний; `FAL_API_KEY` також працює як резервний варіант) | | API | кінцеві точки моделей fal | ## Початок роботи - + ```bash openclaw onboard --auth-choice fal-api-key ``` @@ -47,24 +47,25 @@ OpenClaw постачається з вбудованим провайдером ## Генерація зображень -Вбудований провайдер генерації зображень `fal` за замовчуванням використовує +Вбудований провайдер генерації зображень `fal` типово використовує `fal/fal-ai/flux/dev`. -| Можливість | Значення | -| ------------- | -------------------------- | -| Макс. зображень | 4 на запит | +| Можливість | Значення | +| --------------- | -------------------------- | +| Максимум зображень | 4 на запит | | Режим редагування | Увімкнено, 1 еталонне зображення | -| Перевизначення розміру | Підтримуються | -| Співвідношення сторін | Підтримується | -| Роздільна здатність | Підтримується | -| Формат виводу | `png` або `jpeg` | +| Перевизначення розміру | Підтримується | +| Співвідношення сторін | Підтримується | +| Роздільна здатність | Підтримується | +| Формат виводу | `png` або `jpeg` | Кінцева точка редагування зображень fal **не** підтримує перевизначення `aspectRatio`. -Використовуйте `outputFormat: "png"`, коли вам потрібен вихід у форматі PNG. fal не оголошує в OpenClaw явний елемент керування прозорим фоном, тому `background: -"transparent"` позначається як проігнороване перевизначення для моделей fal. +Використовуйте `outputFormat: "png"`, якщо вам потрібен вивід у форматі PNG. fal не оголошує +явний параметр керування прозорим фоном в OpenClaw, тому `background: +"transparent"` для моделей fal позначається як проігнороване перевизначення. Щоб використовувати fal як типовий провайдер зображень: @@ -82,12 +83,12 @@ OpenClaw постачається з вбудованим провайдером ## Генерація відео -Вбудований провайдер генерації відео `fal` за замовчуванням використовує +Вбудований провайдер генерації відео `fal` типово використовує `fal/fal-ai/minimax/video-01-live`. -| Можливість | Значення | -| ---------- | ----------------------------------------------------------- | -| Режими | Текст у відео, одне еталонне зображення | +| Можливість | Значення | +| ---------- | ------------------------------------------------------------------- | +| Режими | Текст у відео, еталон за одним зображенням, Seedance reference-to-video | | Виконання | Потік submit/status/result на основі черги для довготривалих завдань | @@ -100,8 +101,10 @@ OpenClaw постачається з вбудованим провайдером - `fal/bytedance/seedance-2.0/fast/text-to-video` - `fal/bytedance/seedance-2.0/fast/image-to-video` + - `fal/bytedance/seedance-2.0/fast/reference-to-video` - `fal/bytedance/seedance-2.0/text-to-video` - `fal/bytedance/seedance-2.0/image-to-video` + - `fal/bytedance/seedance-2.0/reference-to-video` @@ -119,6 +122,25 @@ OpenClaw постачається з вбудованим провайдером ``` + + ```json5 + { + agents: { + defaults: { + videoGenerationModel: { + primary: "fal/bytedance/seedance-2.0/fast/reference-to-video", + }, + }, + }, + } + ``` + + Reference-to-video приймає до 9 зображень, 3 відео та 3 аудіоеталонів + через спільні параметри `images`, `videos` і `audioRefs` інструмента `video_generate`, + із максимумом 12 еталонних файлів загалом. + + + ```json5 { @@ -135,10 +157,11 @@ OpenClaw постачається з вбудованим провайдером -Використовуйте `openclaw models list --provider fal`, щоб переглянути повний список доступних моделей fal, включно з нещодавно доданими записами. +Використовуйте `openclaw models list --provider fal`, щоб побачити повний список доступних моделей fal, +зокрема всі нещодавно додані записи. -## Пов’язане +## Пов’язані матеріали @@ -147,7 +170,7 @@ OpenClaw постачається з вбудованим провайдером Спільні параметри інструмента відео і вибір провайдера. - - Типові значення агента, включно з вибором моделей зображень і відео. + + Типові значення агента, зокрема вибір моделей зображень і відео. diff --git a/docs/uk/reference/session-management-compaction.md b/docs/uk/reference/session-management-compaction.md index 9b00edd66..3a3617056 100644 --- a/docs/uk/reference/session-management-compaction.md +++ b/docs/uk/reference/session-management-compaction.md @@ -1,15 +1,15 @@ --- read_when: - - Вам потрібно налагодити id сесій, JSONL транскриптів або поля `sessions.json` - - Ви змінюєте поведінку auto-Compaction або додаєте «перед-Compaction» housekeeping + - Вам потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json + - Ви змінюєте поведінку авто-Compaction або додаєте підготовче очищення перед Compaction - Ви хочете реалізувати скидання пам’яті або тихі системні ходи -summary: 'Поглиблений розбір: сховище сесій + транскрипти, життєвий цикл і внутрішні механізми (авто)Compaction' -title: Поглиблений розбір керування сесіями +summary: 'Поглиблений огляд: сховище сесій і транскрипти, життєвий цикл та внутрішні механізми (авто)Compaction' +title: Поглиблений огляд керування сесіями x-i18n: - generated_at: "2026-04-25T05:58:51Z" + generated_at: "2026-04-26T01:43:32Z" model: gpt-5.4 provider: openai - source_hash: f15b8cf4b1deb947b292c6931257218d7147c11c963e7bf2689b6d1f77ea8159 + source_hash: 5593cb9a2da91892c96f4162c57cf71177e7301d30c6e9d0e1f1a3fe13448735 source_path: reference/session-management-compaction.md workflow: 15 --- @@ -21,48 +21,48 @@ x-i18n: - **Збереження транскриптів** (`*.jsonl`) та їхню структуру - **Гігієна транскриптів** (виправлення, специфічні для провайдера, перед запусками) - **Обмеження контексту** (вікно контексту проти відстежуваних токенів) -- **Compaction** (ручний + auto-Compaction) і де під’єднувати роботу перед Compaction -- **Тихий housekeeping** (наприклад, записи пам’яті, які не повинні створювати видимий для користувача вивід) +- **Compaction** (ручний + авто-Compaction) і де підключати підготовчу роботу перед Compaction +- **Тихе службове обслуговування** (наприклад, записи в пам’ять, які не повинні створювати видимий для користувача вивід) Якщо спочатку вам потрібен огляд вищого рівня, почніть із: - [Керування сесіями](/uk/concepts/session) - [Compaction](/uk/concepts/compaction) -- [Огляд memory](/uk/concepts/memory) -- [Пошук у memory](/uk/concepts/memory-search) -- [Обрізання сесій](/uk/concepts/session-pruning) +- [Огляд пам’яті](/uk/concepts/memory) +- [Пошук у пам’яті](/uk/concepts/memory-search) +- [Очищення сесій](/uk/concepts/session-pruning) - [Гігієна транскриптів](/uk/reference/transcript-hygiene) --- ## Джерело істини: Gateway -OpenClaw побудований навколо єдиного **процесу Gateway**, який володіє станом сесій. +OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій. - UI (застосунок macOS, веб-інтерфейс Control UI, TUI) мають запитувати Gateway щодо списків сесій і кількості токенів. -- У віддаленому режимі файли сесій знаходяться на віддаленому host; «перевірка локальних файлів на Mac» не відображатиме того, що використовує Gateway. +- У віддаленому режимі файли сесій розташовані на віддаленому хості; «перевірка локальних файлів на вашому Mac» не відображатиме те, що використовує Gateway. --- -## Два шари збереження +## Два рівні збереження -OpenClaw зберігає сесії у двох шарах: +OpenClaw зберігає сесії на двох рівнях: 1. **Сховище сесій (`sessions.json`)** - - Map ключ/значення: `sessionKey -> SessionEntry` - - Невелике, змінне, безпечне для редагування (або видалення записів) - - Відстежує метадані сесії (поточний id сесії, останню активність, перемикачі, лічильники токенів тощо) + - Мапа ключ/значення: `sessionKey -> SessionEntry` + - Невелике, змінюване, безпечне для редагування (або видалення записів) + - Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо) 2. **Транскрипт (`.jsonl`)** - - Append-only транскрипт із деревоподібною структурою (записи мають `id` + `parentId`) - - Зберігає фактичну розмову + виклики tools + підсумки Compaction + - Транскрипт лише з додаванням із деревоподібною структурою (записи мають `id` + `parentId`) + - Зберігає фактичну розмову + виклики інструментів + підсумки Compaction - Використовується для відновлення контексту моделі для майбутніх ходів --- ## Розташування на диску -Для кожного агента, на host Gateway: +Для кожного агента на хості Gateway: - Сховище: `~/.openclaw/agents//sessions/sessions.json` - Транскрипти: `~/.openclaw/agents//sessions/.jsonl` @@ -72,25 +72,25 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`. --- -## Обслуговування сховища і контроль диска +## Обслуговування сховища та контроль диска -Збереження сесій має автоматичні механізми обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів: +Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів: - `mode`: `warn` (типово) або `enforce` -- `pruneAfter`: поріг віку застарілих записів (типово `30d`) +- `pruneAfter`: поріг давності застарілих записів (типово `30d`) - `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`) -- `rotateBytes`: ротація `sessions.json`, якщо він перевищує розмір (типово `10mb`) +- `rotateBytes`: ротація `sessions.json`, коли файл завеликий (типово `10mb`) - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення) -- `maxDiskBytes`: необов’язковий бюджет каталогу сесій на диску +- `maxDiskBytes`: необов’язковий бюджет для каталогу сесій - `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`) -Порядок застосування для очищення за бюджетом диска (`mode: "enforce"`): +Порядок примусового очищення за бюджетом диска (`mode: "enforce"`): -1. Спочатку видаляються найстаріші архівовані або осиротілі артефакти транскриптів. -2. Якщо це не допомагає досягти цілі, видаляються найстаріші записи сесій і їхні файли транскриптів. -3. Процес триває, доки використання не стане меншим або рівним `highWaterBytes`. +1. Спочатку видалити найстаріші архівовані або осиротілі артефакти транскриптів. +2. Якщо ціль усе ще не досягнута, витіснити найстаріші записи сесій і їхні файли транскриптів. +3. Продовжувати, доки використання не стане меншим або рівним `highWaterBytes`. -У режимі `mode: "warn"` OpenClaw повідомляє про потенційні видалення, але не змінює сховище/файли. +У `mode: "warn"` OpenClaw повідомляє про потенційні витіснення, але не змінює сховище/файли. Запуск обслуговування на вимогу: @@ -103,18 +103,18 @@ openclaw sessions cleanup --enforce ## Cron-сесії та журнали запусків -Ізольовані запуски Cron також створюють записи сесій/транскрипти, і для них є окремі параметри зберігання: +Ізольовані запуски Cron також створюють записи сесій/транскрипти, і для них є окремі механізми зберігання: -- `cron.sessionRetention` (типово `24h`) обрізає старі сесії ізольованих запусків Cron зі сховища сесій (`false` вимикає це). -- `cron.runLog.maxBytes` + `cron.runLog.keepLines` обрізають файли `~/.openclaw/cron/runs/.jsonl` (типові значення: `2_000_000` байтів і `2000` рядків). +- `cron.sessionRetention` (типово `24h`) очищає старі сесії ізольованих запусків Cron зі сховища сесій (`false` вимикає це). +- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищають файли `~/.openclaw/cron/runs/.jsonl` (типові значення: `2_000_000` байтів і `2000` рядків). Коли Cron примусово створює нову ізольовану сесію запуску, він очищає попередній -запис сесії `cron:` перед записом нового рядка. Він переносить безпечні -параметри, як-от налаштування thinking/fast/verbose, мітки та явні -перевизначення model/auth, вибрані користувачем. Він відкидає фоновий контекст розмови, -такий як маршрутизація channel/group, політика надсилання чи черги, підвищення привілеїв, origin і -прив’язка runtime ACP, щоб новий ізольований запуск не міг успадкувати застарілі повноваження -доставки або runtime від старішого запуску. +запис сесії `cron:` перед записом нового рядка. Він зберігає безпечні +налаштування, такі як параметри thinking/fast/verbose, мітки та явні +перевизначення моделі/автентифікації, вибрані користувачем. Він відкидає фоновий контекст розмови, +такий як маршрутизація каналу/групи, політика надсилання чи черги, підвищення прав, походження та прив’язка середовища виконання ACP, +щоб новий ізольований запуск не міг успадкувати застарілу доставку або +повноваження середовища виконання від старішого запуску. --- @@ -130,22 +130,23 @@ openclaw sessions cleanup --enforce - Cron: `cron:` - Webhook: `hook:` (якщо не перевизначено) -Канонічні правила задокументовано на [/concepts/session](/uk/concepts/session). +Канонічні правила задокументовано в [/concepts/session](/uk/concepts/session). --- -## Id сесій (`sessionId`) +## Ідентифікатори сесій (`sessionId`) Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, який продовжує розмову). Практичні правила: - **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`. -- **Щоденне скидання** (типово о 4:00 ранку за локальним часом на host Gateway) створює новий `sessionId` на наступному повідомленні після межі скидання. -- **Сплив неактивності** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна неактивності. Коли налаштовано і щоденне скидання, і неактивність, спрацьовує те, що спливає першим. -- **Захист від форку батьківського потоку** (`session.parentForkMaxTokens`, типово `100000`) пропускає форк батьківського транскрипту, коли батьківська сесія вже надто велика; новий потік починається з нуля. Установіть `0`, щоб вимкнути. +- **Щоденне скидання** (типово о 4:00 ранку за місцевим часом на хості gateway) створює новий `sessionId` на наступному повідомленні після межі скидання. +- **Закінчення строку бездіяльності** (`session.reset.idleMinutes` або застаріле `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна бездіяльності. Якщо налаштовано і щоденне, і за бездіяльністю, спрацьовує те, що настає раніше. +- **Системні події** (Heartbeat, пробудження Cron, сповіщення exec, службове обслуговування gateway) можуть змінювати рядок сесії, але не подовжують актуальність щоденного/бездіяльного скидання. +- **Захист від розгалуження батьківського потоку** (`session.parentForkMaxTokens`, типово `100000`) пропускає розгалуження батьківського транскрипту, якщо батьківська сесія вже завелика; новий потік починається з нуля. Встановіть `0`, щоб вимкнути. -Деталь реалізації: рішення приймається в `initSessionState()` у `src/auto-reply/reply/session.ts`. +Деталь реалізації: рішення ухвалюється в `initSessionState()` у `src/auto-reply/reply/session.ts`. --- @@ -155,29 +156,36 @@ openclaw sessions cleanup --enforce Ключові поля (не вичерпно): -- `sessionId`: поточний id транскрипту (ім’я файла визначається з нього, якщо не задано `sessionFile`) -- `updatedAt`: мітка часу останньої активності -- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту -- `chatType`: `direct | group | room` (допомагає UI і політиці надсилання) -- `provider`, `subject`, `room`, `space`, `displayName`: метадані для міток груп/каналів +- `sessionId`: поточний ідентифікатор транскрипту (ім’я файла виводиться з нього, якщо не задано `sessionFile`) +- `sessionStartedAt`: часовий штамп початку для поточного `sessionId`; саме його використовує + актуальність щоденного скидання. Для застарілих рядків він може виводитися із заголовка сесії JSONL. +- `lastInteractionAt`: часовий штамп останньої реальної взаємодії користувача/каналу; актуальність + скидання за бездіяльністю використовує саме його, тому Heartbeat, Cron та exec-події не підтримують сесію + активною. Для застарілих рядків без цього поля використовується відновлений час початку сесії + для актуальності бездіяльності. +- `updatedAt`: часовий штамп останньої зміни рядка сховища; використовується для списків, очищення та + службового обліку. Це не авторитетне поле для актуальності щоденного/бездіяльного скидання. +- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту +- `chatType`: `direct | group | room` (допомагає UI та політиці надсилання) +- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів - Перемикачі: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - `sendPolicy` (перевизначення для конкретної сесії) - Вибір моделі: - `providerOverride`, `modelOverride`, `authProfileOverride` -- Лічильники токенів (best-effort / залежать від провайдера): +- Лічильники токенів (найкраще зусилля / залежать від провайдера): - `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens` -- `compactionCount`: як часто auto-Compaction завершувався для цього ключа сесії -- `memoryFlushAt`: мітка часу останнього скидання пам’яті перед Compaction -- `memoryFlushCompactionCount`: кількість Compaction, коли виконувався останній flush +- `compactionCount`: скільки разів авто-Compaction завершувався для цього ключа сесії +- `memoryFlushAt`: часовий штамп останнього скидання пам’яті перед Compaction +- `memoryFlushCompactionCount`: лічильник Compaction на момент останнього скидання -Сховище безпечне для редагування, але Gateway — авторитетне джерело: він може переписувати або повторно гідратувати записи під час роботи сесій. +Сховище безпечне для редагування, але Gateway є джерелом істини: він може переписувати або повторно гідратувати записи під час виконання сесій. --- ## Структура транскрипту (`*.jsonl`) -Транскриптами керує `@mariozechner/pi-coding-agent` через `SessionManager`. +Транскриптами керує `SessionManager` із `@mariozechner/pi-coding-agent`. Файл має формат JSONL: @@ -186,11 +194,11 @@ openclaw sessions cleanup --enforce Помітні типи записів: -- `message`: повідомлення user/assistant/toolResult -- `custom_message`: повідомлення, вставлені розширенням, які _входять_ до контексту моделі (можуть бути приховані від UI) -- `custom`: стан розширення, який _не входить_ до контексту моделі -- `compaction`: збережений підсумок Compaction з `firstKeptEntryId` і `tokensBefore` -- `branch_summary`: збережений підсумок під час навігації по гілці дерева +- `message`: повідомлення користувача/асистента/toolResult +- `custom_message`: повідомлення, ін’єктовані розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від UI) +- `custom`: стан розширення, який _не потрапляє_ в контекст моделі +- `compaction`: збережений підсумок Compaction із `firstKeptEntryId` і `tokensBefore` +- `branch_summary`: збережений підсумок під час навігації гілкою дерева OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису. @@ -198,15 +206,15 @@ OpenClaw навмисно **не** «виправляє» транскрипти ## Вікна контексту проти відстежуваних токенів -Мають значення дві різні концепції: +Мають значення два різні поняття: 1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі) -2. **Лічильники в сховищі сесій**: ковзна статистика, записана в `sessions.json` (використовується для /status і dashboards) +2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і панелей моніторингу) -Якщо ви налаштовуєте обмеження: +Якщо ви налаштовуєте ліміти: - Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію). -- `contextTokens` у сховищі — це оцінка/значення для звітування під час runtime; не сприймайте його як сувору гарантію. +- `contextTokens` у сховищі — це оцінка/звітне значення під час виконання; не вважайте його суворою гарантією. Докладніше див. у [/token-use](/uk/reference/token-use). @@ -214,39 +222,38 @@ OpenClaw навмисно **не** «виправляє» транскрипти ## Compaction: що це таке -Compaction підсумовує старішу розмову в збережений запис `compaction` у транскрипті й залишає недоторканими останні повідомлення. +Compaction узагальнює старішу розмову в збереженому записі `compaction` у транскрипті та зберігає нещодавні повідомлення без змін. Після Compaction майбутні ходи бачать: - Підсумок Compaction - Повідомлення після `firstKeptEntryId` -Compaction є **постійним** (на відміну від обрізання сесії). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). +Compaction є **постійним** (на відміну від очищення сесії). Див. [/concepts/session-pruning](/uk/concepts/session-pruning). -## Межі блоків Compaction і парування tools +## Межі фрагментів Compaction і парування інструментів -Коли OpenClaw розбиває довгий транскрипт на блоки для Compaction, він зберігає -виклики tools від assistant разом із відповідними записами `toolResult`. +Коли OpenClaw ділить довгий транскрипт на фрагменти Compaction, він зберігає +виклики інструментів асистента в парі з відповідними записами `toolResult`. -- Якщо розділення за часткою токенів припадає між викликом tool і його результатом, OpenClaw - зміщує межу до повідомлення assistant з викликом tool, а не розділяє - пару. -- Якщо кінцевий блок `toolResult` інакше перевищив би цільовий розмір блоку, - OpenClaw зберігає цей незавершений блок tool і залишає непідсумований хвіст - недоторканим. -- Перервані/помилкові блоки викликів tools не утримують очікуване розділення відкритим. +- Якщо поділ за часткою токенів припадає між викликом інструмента та його результатом, OpenClaw + зміщує межу до повідомлення асистента з викликом інструмента замість розділення + пари. +- Якщо кінцевий блок результатів інструментів інакше виштовхнув би фрагмент за цільовий розмір, + OpenClaw зберігає цей очікуваний блок інструментів і лишає неузагальнений хвіст без змін. +- Перервані/помилкові блоки викликів інструментів не утримують очікуване розділення відкритим. --- -## Коли відбувається auto-Compaction (runtime Pi) +## Коли відбувається авто-Compaction (середовище Pi) -У вбудованому агенті Pi auto-Compaction спрацьовує у двох випадках: +У вбудованому агенті Pi авто-Compaction спрацьовує у двох випадках: 1. **Відновлення після переповнення**: модель повертає помилку переповнення контексту (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` та подібні варіанти помилок від провайдерів) → compact → повторна спроба. +exceeded` та подібні варіанти від провайдерів) → виконати Compaction → повторити спробу. 2. **Порогове обслуговування**: після успішного ходу, коли: `contextTokens > contextWindow - reserveTokens` @@ -254,15 +261,15 @@ exceeded` та подібні варіанти помилок від прова Де: - `contextWindow` — це вікно контексту моделі -- `reserveTokens` — запас місця для prompt + наступного виводу моделі +- `reserveTokens` — запас, зарезервований для prompt і наступного виводу моделі -Це семантика runtime Pi (OpenClaw споживає події, але Pi вирішує, коли виконувати Compaction). +Це семантика середовища Pi (OpenClaw споживає ці події, але Pi вирішує, коли виконувати Compaction). --- ## Налаштування Compaction (`reserveTokens`, `keepRecentTokens`) -Налаштування Compaction у Pi знаходяться в налаштуваннях Pi: +Налаштування Compaction у Pi містяться в налаштуваннях Pi: ```json5 { @@ -274,18 +281,18 @@ exceeded` та подібні варіанти помилок від прова } ``` -OpenClaw також забезпечує мінімальний поріг безпеки для вбудованих запусків: +OpenClaw також застосовує мінімальний поріг безпеки для вбудованих запусків: -- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw збільшує це значення. +- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує це значення. - Типовий поріг — `20000` токенів. -- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути поріг. -- Якщо значення вже вище, OpenClaw його не змінює. +- Встановіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути поріг. +- Якщо значення вже вище, OpenClaw залишає його без змін. - Ручний `/compact` враховує явний `agents.defaults.compaction.keepRecentTokens` - і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету keep - ручний Compaction залишається жорсткою контрольною точкою, а відновлений контекст починається + і зберігає точку відсікання недавнього хвоста Pi. Без явного бюджету збереження + ручний Compaction лишається жорсткою контрольною точкою, а відновлений контекст починається з нового підсумку. -Чому: потрібно залишити достатньо запасу для багатокрокового «housekeeping» (наприклад, записів у memory), перш ніж Compaction стане неминучим. +Чому: потрібно залишити достатній запас для багатокрокового «службового обслуговування» (наприклад, записів у пам’ять), перш ніж Compaction стане неминучим. Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts` (викликається з `src/agents/pi-embedded-runner.ts`). @@ -294,17 +301,17 @@ OpenClaw також забезпечує мінімальний поріг бе ## Підключувані провайдери Compaction -Плагіни можуть реєструвати провайдера Compaction через `registerCompactionProvider()` у API plugin. Коли `agents.defaults.compaction.provider` встановлено на id зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. +Plugin можуть реєструвати провайдера Compaction через `registerCompactionProvider()` в API plugin. Коли `agents.defaults.compaction.provider` встановлено на ідентифікатор зареєстрованого провайдера, розширення safeguard делегує підсумовування цьому провайдеру замість вбудованого конвеєра `summarizeInStages`. -- `provider`: id зареєстрованого plugin-провайдера Compaction. Залиште незаданим для типового LLM-підсумовування. +- `provider`: ідентифікатор зареєстрованого plugin-провайдера Compaction. Залиште не встановленим для типового підсумовування LLM. - Встановлення `provider` примусово задає `mode: "safeguard"`. - Провайдери отримують ті самі інструкції Compaction і політику збереження ідентифікаторів, що й вбудований шлях. -- Safeguard, як і раніше, зберігає контекст суфікса нещодавніх ходів і розділених ходів після виводу провайдера. -- Вбудоване safeguard-підсумовування повторно дистилює попередні підсумки разом із новими повідомленнями, - а не зберігає повний попередній підсумок дослівно. -- Режим safeguard типово вмикає аудити якості підсумків; установіть - `qualityGuard.enabled: false`, щоб пропустити поведінку повторної спроби при некоректному виводі. -- Якщо провайдер завершується помилкою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого LLM-підсумовування. +- Safeguard і далі зберігає контекст суфікса недавніх ходів і розділених ходів після виводу провайдера. +- Вбудоване підсумовування safeguard повторно дистилює попередні підсумки разом із новими повідомленнями, + а не зберігає весь попередній підсумок дослівно. +- Режим safeguard типово вмикає перевірки якості підсумку; встановіть + `qualityGuard.enabled: false`, щоб пропустити повторні спроби при некоректному виводі. +- Якщо провайдер завершується з помилкою або повертає порожній результат, OpenClaw автоматично повертається до вбудованого підсумовування LLM. - Сигнали abort/timeout перевикидаються (не поглинаються), щоб поважати скасування з боку викликача. Джерело: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. @@ -315,44 +322,44 @@ OpenClaw також забезпечує мінімальний поріг бе Ви можете спостерігати Compaction і стан сесії через: -- `/status` (у будь-якій чат-сесії) +- `/status` (у будь-якій сесії чату) - `openclaw status` (CLI) - `openclaw sessions` / `sessions --json` -- Режим verbose: `🧹 Auto-compaction complete` + кількість Compaction +- Докладний режим: `🧹 Auto-compaction complete` + кількість Compaction --- -## Тихий housekeeping (`NO_REPLY`) +## Тихе службове обслуговування (`NO_REPLY`) OpenClaw підтримує «тихі» ходи для фонових завдань, де користувач не повинен бачити проміжний вивід. Угода: -- Assistant починає свій вивід із точного тихого токена `NO_REPLY` / +- Асистент починає свій вивід із точного тихого токена `NO_REPLY` / `no_reply`, щоб позначити «не доставляти відповідь користувачу». - OpenClaw прибирає/пригнічує це на рівні доставки. -- Пригнічення точного тихого токена не залежить від регістру, тож `NO_REPLY` і - `no_reply` обидва спрацьовують, коли весь payload — це лише тихий токен. -- Це лише для справді фонових ходів без доставки; це не скорочення для - звичайних дієвих запитів користувача. +- Пригнічення точного тихого токена є нечутливим до регістру, тож `NO_REPLY` і + `no_reply` обидва зараховуються, коли весь payload — це лише тихий токен. +- Це лише для справжніх фонових ходів/ходів без доставки; це не скорочення для + звичайних запитів користувача, які потребують дії. -Починаючи з `2026.1.10`, OpenClaw також пригнічує **чернетковий/індикатор набору streaming**, коли -частковий блок починається з `NO_REPLY`, щоб тихі операції не розкривали частковий +Починаючи з `2026.1.10`, OpenClaw також пригнічує **потокову передачу чернеток/індикатора набору**, коли +частковий фрагмент починається з `NO_REPLY`, щоб тихі операції не розкривали частковий вивід посеред ходу. --- -## «Скидання пам’яті» перед Compaction (реалізовано) +## Перед-Compaction «скидання пам’яті» (реалізовано) -Мета: перед тим як відбудеться auto-Compaction, виконати тихий агентний хід, який записує сталий -стан на диск (наприклад, `memory/YYYY-MM-DD.md` у workspace агента), щоб Compaction не міг +Мета: до того, як станеться авто-Compaction, виконати тихий агентний хід, який записує довготривалий +стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб Compaction не міг стерти критичний контекст. -OpenClaw використовує підхід **скидання до порогу**: +OpenClaw використовує підхід **скидання до досягнення порога**: 1. Відстежувати використання контексту сесії. -2. Коли воно перетинає «м’який поріг» (нижче за поріг Compaction у Pi), виконати тиху - директиву «запиши пам’ять зараз» для агента. +2. Коли воно перетинає «м’який поріг» (нижче порога Compaction у Pi), виконати тиху + директиву «записати пам’ять зараз» для агента. 3. Використовувати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач нічого не бачив. @@ -361,7 +368,7 @@ OpenClaw використовує підхід **скидання до поро - `enabled` (типово: `true`) - `softThresholdTokens` (типово: `4000`) - `prompt` (повідомлення користувача для ходу скидання) -- `systemPrompt` (додатковий системний prompt, доданий для ходу скидання) +- `systemPrompt` (додатковий системний prompt, що додається для ходу скидання) Примітки: @@ -369,26 +376,26 @@ OpenClaw використовує підхід **скидання до поро доставки. - Скидання виконується один раз за цикл Compaction (відстежується в `sessions.json`). - Скидання виконується лише для вбудованих сесій Pi (бекенди CLI його пропускають). -- Скидання пропускається, коли workspace сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). -- Див. [Memory](/uk/concepts/memory) щодо структури файлів workspace і шаблонів запису. +- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`). +- Див. [Пам’ять](/uk/concepts/memory), щоб дізнатися про структуру файлів робочого простору та шаблони запису. -Pi також надає hook `session_before_compact` в API розширення, але логіка flush у OpenClaw -сьогодні живе на боці Gateway. +Pi також надає хук `session_before_compact` в API розширень, але логіка +скидання OpenClaw сьогодні живе на боці Gateway. --- -## Контрольний список усунення несправностей +## Контрольний список усунення проблем - Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`. -- Невідповідність між сховищем і транскриптом? Підтвердьте host Gateway і шлях до сховища з `openclaw status`. -- Спам Compaction? Перевірте: +- Невідповідність між сховищем і транскриптом? Підтвердьте хост Gateway і шлях до сховища з `openclaw status`. +- Забагато Compaction? Перевірте: - вікно контексту моделі (занадто мале) - - налаштування Compaction (`reserveTokens`, завелике для вікна моделі, може спричиняти ранніший Compaction) - - роздуття `toolResult`: увімкніть/налаштуйте обрізання сесій -- Витік тихих ходів? Підтвердьте, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку з виправленням пригнічення streaming. + - налаштування Compaction (`reserveTokens`, занадто велике для вікна моделі, може спричинити раніший Compaction) + - роздування результатів інструментів: увімкніть/налаштуйте очищення сесії +- Тихі ходи просочуються? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що у вас збірка, яка містить виправлення пригнічення потокової передачі. ## Пов’язане - [Керування сесіями](/uk/concepts/session) -- [Обрізання сесій](/uk/concepts/session-pruning) +- [Очищення сесій](/uk/concepts/session-pruning) - [Рушій контексту](/uk/concepts/context-engine) diff --git a/docs/uk/tools/video-generation.md b/docs/uk/tools/video-generation.md index 2973eeeb3..e28554386 100644 --- a/docs/uk/tools/video-generation.md +++ b/docs/uk/tools/video-generation.md @@ -1,42 +1,43 @@ --- read_when: - - Створення відео через агента - - Налаштування провайдерів і моделей для генерації відео + - Генерація відео через агента + - Налаштування провайдерів і моделей генерації відео - Розуміння параметрів інструмента `video_generate` -summary: Створюйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів +summary: Генеруйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів title: Генерація відео x-i18n: - generated_at: "2026-04-25T20:33:41Z" + generated_at: "2026-04-26T01:43:33Z" model: gpt-5.4 provider: openai - source_hash: 83349231726cd65299733af1605e0d20ea69a50b35021a784943e5c597bf4eeb + source_hash: b981ca669e92a80fcfb8ff826e0b72edbe673610128afc1d401fa79f95e47c02 source_path: tools/video-generation.md workflow: 15 --- -Агенти OpenClaw можуть створювати відео з текстових запитів, референсних зображень або наявних відео. Підтримується чотирнадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами функцій. Агент автоматично вибирає відповідного провайдера на основі вашої конфігурації та доступних API-ключів. +Агенти OpenClaw можуть генерувати відео з текстових запитів, еталонних зображень або наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає правильного провайдера на основі вашої конфігурації та доступних API-ключів. -Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви його не бачите серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`. +Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, установіть API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`. OpenClaw розглядає генерацію відео як три режими виконання: -- `generate` для запитів text-to-video без референсних медіа -- `imageToVideo`, коли запит містить одне або кілька референсних зображень -- `videoToVideo`, коли запит містить одне або кілька референсних відео +- `generate` для запитів текст-у-відео без еталонних медіа +- `imageToVideo`, коли запит містить одне або кілька еталонних зображень +- `videoToVideo`, коли запит містить одне або кілька еталонних відео -Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний режим перед надсиланням і повідомляє підтримувані режими в `action=list`. +Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний +режим перед надсиланням і повідомляє про підтримувані режими в `action=list`. ## Швидкий старт -1. Задайте API-ключ для будь-якого підтримуваного провайдера: +1. Установіть API-ключ для будь-якого підтримуваного провайдера: ```bash export GEMINI_API_KEY="your-key" ``` -2. За потреби зафіксуйте модель за замовчуванням: +2. За бажанням зафіксуйте типову модель: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" @@ -44,38 +45,39 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. Попросіть агента: -> Згенеруй 5-секундне кінематографічне відео, де дружній лобстер катається на серфі на заході сонця. +> Створи 5-секундне кінематографічне відео з доброзичливим лобстером, який серфить на заході сонця. -Агент автоматично викликає `video_generate`. Дозволяти інструмент через allowlist не потрібно. +Агент автоматично викликає `video_generate`. Дозвільний список інструментів не потрібен. ## Що відбувається, коли ви генеруєте відео Генерація відео є асинхронною. Коли агент викликає `video_generate` у сесії: -1. OpenClaw надсилає запит провайдеру й одразу повертає ID задачі. +1. OpenClaw надсилає запит провайдеру й одразу повертає ID завдання. 2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). 3. Коли відео готове, OpenClaw пробуджує ту саму сесію внутрішньою подією завершення. 4. Агент публікує готове відео назад в оригінальну розмову. -Поки завдання виконується, повторні виклики `video_generate` у тій самій сесії повертають поточний статус задачі замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевірити прогрес через CLI. +Поки завдання виконується, дубльовані виклики `video_generate` у тій самій сесії повертають поточний стан завдання замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевірити поступ із CLI. -Поза запусками агента, що базуються на сесії (наприклад, під час прямих викликів інструмента), інструмент переходить до вбудованої генерації та повертає шлях до фінального медіафайлу в межах того самого ходу. +Поза межами запусків агента, прив’язаних до сесії (наприклад, прямих викликів інструмента), інструмент повертається до вбудованої генерації та повертає фінальний шлях до медіафайлу в тому самому ході. -Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіа, коли провайдер повертає байти. Типове обмеження збереження для згенерованого відео відповідає ліміту відеомедіа, а `agents.defaults.mediaMaxMb` збільшує його для більших рендерів. -Коли провайдер також повертає URL розміщеного результату, OpenClaw може передати цей URL -замість того, щоб завершити задачу з помилкою, якщо локальне збереження відхиляє -завеликий файл. +Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіа, коли +провайдер повертає байти. Типове обмеження на збереження згенерованого відео відповідає +ліміту відеомедіа, а `agents.defaults.mediaMaxMb` підвищує його для більших рендерів. +Коли провайдер також повертає хостований URL результату, OpenClaw може доставити цей URL +замість помилки завдання, якщо локальне збереження відхиляє завеликий файл. -### Життєвий цикл задачі +### Життєвий цикл завдання Кожен запит `video_generate` проходить через чотири стани: -1. **queued** -- задачу створено, очікується, поки провайдер її прийме. +1. **queued** -- завдання створено, очікує, поки провайдер його прийме. 2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). -3. **succeeded** -- відео готове; агент пробуджується та публікує його в розмову. -4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. +3. **succeeded** -- відео готове; агент пробуджується й публікує його в розмову. +4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з подробицями помилки. -Перевірка статусу через CLI: +Перевірка стану з CLI: ```bash openclaw tasks list @@ -83,152 +85,154 @@ openclaw tasks show openclaw tasks cancel ``` -Запобігання дублюванню: якщо для поточної сесії задача відеогенерації вже має стан `queued` або `running`, `video_generate` повертає статус наявної задачі замість запуску нової. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. +Запобігання дублюванню: якщо для поточної сесії завдання відео вже перебуває у стані `queued` або `running`, `video_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. ## Підтримувані провайдери -| Провайдер | Модель за замовчуванням | Текст | Референс зображення | Референс відео | API-ключ | -| -------------------- | ------------------------------- | ----- | --------------------------------------------------- | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | -| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший і останній кадр) | Ні | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший і останній кадр через роль) | Ні | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 референсних зображень | До 3 відео | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення | Ні | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | Так | 1 зображення | 1 відео | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` або MiniMax OAuth | -| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Так | 1 зображення першого кадру або до 7 `reference_image`s | 1 відео | `XAI_API_KEY` | +| Провайдер | Типова модель | Текст | Еталонне зображення | Еталонне відео | API-ключ | +| -------------------- | ------------------------------ | ----- | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- | +| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший і останній кадр) | Ні | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший і останній кадр через role) | Ні | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення; до 9 із Seedance reference-to-video | До 3 відео із Seedance reference-to-video | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Так | 1 зображення | 1 відео | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` або MiniMax OAuth | +| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Так | 1 зображення першого кадру або до 7 `reference_image` | 1 відео | `XAI_API_KEY` | -Деякі провайдери приймають додаткові або альтернативні env vars для API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related). +Деякі провайдери приймають додаткові або альтернативні змінні середовища API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related). -Запустіть `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та режими виконання. +Виконайте `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та +режими виконання. -### Оголошена матриця можливостей +### Матриця оголошених можливостей Це явний контракт режимів, який використовується `video_generate`, контрактними тестами та спільним live sweep. -| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live lanes зараз | -| --------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | -| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` | -| ComfyUI | Так | Так | Ні | Не входить до спільного sweep; покриття, специфічне для workflow, знаходиться в тестах Comfy | -| fal | Так | Так | Ні | `generate`, `imageToVideo` | -| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний sweep Gemini/Veo на основі буфера не приймає такий ввід | -| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` | +| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live lanes наразі | +| --------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | +| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` | +| ComfyUI | Так | Так | Ні | Не у спільному sweep; покриття, специфічне для workflow, розміщено в тестах Comfy | +| fal | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` лише при використанні Seedance reference-to-video | +| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний sweep Gemini/Veo на основі буфера не приймає це введення | +| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` | | OpenAI | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки цей шлях org/input зараз потребує доступу до inpaint/remix на боці провайдера | -| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | -| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибраною моделлю є `runway/gen4_aleph` | -| Together | Так | Так | Ні | `generate`, `imageToVideo` | -| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення | -| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру зараз потрібен віддалений URL MP4 | +| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | +| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` виконується лише коли вибрана модель — `runway/gen4_aleph` | +| Together | Так | Так | Ні | `generate`, `imageToVideo` | +| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення | +| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цей провайдер наразі потребує віддалений URL MP4 | ## Параметри інструмента ### Обов’язкові -| Параметр | Тип | Опис | -| -------- | ------ | --------------------------------------------------------------------------------- | -| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) | +| Параметр | Тип | Опис | +| -------- | ------ | -------------------------------------------------------------------------- | +| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) | -### Входи контенту +### Вхідні дані вмісту -| Параметр | Тип | Опис | -| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `image` | string | Одне референсне зображення (шлях або URL) | -| `images` | string[] | Кілька референсних зображень (до 9) | -| `imageRoles`| string[] | Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` | -| `video` | string | Одне референсне відео (шлях або URL) | -| `videos` | string[] | Кілька референсних відео (до 4) | -| `videoRoles`| string[] | Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку відео. Канонічне значення: `reference_video` | -| `audioRef` | string | Одне референсне аудіо (шлях або URL). Використовується, наприклад, для фонової музики або референсу голосу, коли провайдер підтримує аудіовходи | -| `audioRefs` | string[] | Кілька референсних аудіо (до 3) | -| `audioRoles`| string[] | Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку аудіо. Канонічне значення: `reference_audio` | +| Параметр | Тип | Опис | +| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `image` | string | Одне еталонне зображення (шлях або URL) | +| `images` | string[] | Кілька еталонних зображень (до 9) | +| `imageRoles` | string[] | Необов’язкові підказки ролей для кожної позиції паралельно до об’єднаного списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` | +| `video` | string | Одне еталонне відео (шлях або URL) | +| `videos` | string[] | Кілька еталонних відео (до 4) | +| `videoRoles` | string[] | Необов’язкові підказки ролей для кожної позиції паралельно до об’єднаного списку відео. Канонічне значення: `reference_video` | +| `audioRef` | string | Одне еталонне аудіо (шлях або URL). Використовується, наприклад, для фонового музичного супроводу або еталона голосу, коли провайдер підтримує аудіовходи | +| `audioRefs` | string[] | Кілька еталонних аудіо (до 3) | +| `audioRoles` | string[] | Необов’язкові підказки ролей для кожної позиції паралельно до об’єднаного списку аудіо. Канонічне значення: `reference_audio` | -Підказки ролей передаються провайдеру без змін. Канонічні значення походять -із union `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові -рядки ролей. Масиви `*Roles` не повинні містити більше елементів, ніж -відповідний список референсів; помилки на один елемент більше або менше -завершуються з чітким повідомленням про помилку. Використовуйте порожній рядок, щоб залишити позицію незаданою. Для xAI задайте для кожної ролі зображення -`reference_image`, щоб використовувати його режим генерації `reference_images`; не вказуйте роль -або використовуйте `first_frame` для image-to-video з одним зображенням. +Підказки ролей передаються провайдеру без змін. Канонічні значення беруться з +об’єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові +рядки ролей. Масиви `*Roles` не повинні містити більше записів, ніж +відповідний список еталонів; помилки на один елемент дають зрозуміле повідомлення. +Використовуйте порожній рядок, щоб залишити позицію незаповненою. Для xAI встановіть +для кожної ролі зображення значення `reference_image`, щоб використовувати режим генерації +`reference_images`; не вказуйте роль або використовуйте `first_frame` для +режиму image-to-video з одним зображенням. ### Керування стилем -| Параметр | Тип | Опис | -| ---------------- | ------- | ------------------------------------------------------------------------------------- | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` | -| `resolution` | string | `480P`, `720P`, `768P` або `1080P` | -| `durationSeconds`| number | Цільова тривалість у секундах (округлюється до найближчого значення, яке підтримує провайдер) | -| `size` | string | Підказка розміру, якщо провайдер це підтримує | -| `audio` | boolean | Увімкнути згенероване аудіо у вихідному результаті, якщо підтримується. Відрізняється від `audioRef*` (входи) | -| `watermark` | boolean | Увімкнути або вимкнути водяні знаки провайдера, якщо підтримується | +| Параметр | Тип | Опис | +| ----------------- | ------- | -------------------------------------------------------------------------------------- | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` | +| `resolution` | string | `480P`, `720P`, `768P` або `1080P` | +| `durationSeconds` | number | Цільова тривалість у секундах (округлюється до найближчого підтримуваного провайдером значення) | +| `size` | string | Підказка розміру, якщо провайдер це підтримує | +| `audio` | boolean | Увімкнути згенероване аудіо у виході, якщо підтримується. Відрізняється від `audioRef*` (входи) | +| `watermark` | boolean | Перемикання водяного знака провайдера, якщо підтримується | -`adaptive` — це спеціальне значення, специфічне для провайдера: воно передається без змін +`adaptive` — це специфічний для провайдера службовий маркер: він передається без змін провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад, BytePlus Seedance використовує його для автоматичного визначення співвідношення сторін за -розмірами вхідного зображення). Провайдери, які не оголошують цю можливість, показують значення через +розмірами вхідного зображення). Провайдери, які цього не оголошують, показують це значення через `details.ignoredOverrides` у результаті інструмента, щоб відкидання було видимим. -### Додатково +### Розширені -| Параметр | Тип | Опис | -| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `action` | string | `"generate"` (за замовчуванням), `"status"` або `"list"` | -| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) | -| `filename` | string | Підказка для імені вихідного файлу | -| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах | -| `providerOptions` | object | Параметри, специфічні для провайдера, як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі та типи значень; невідомі ключі або невідповідності призводять до пропуску кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри без змін. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер | +| Параметр | Тип | Опис | +| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `action` | string | `"generate"` (типово), `"status"` або `"list"` | +| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) | +| `filename` | string | Підказка для назви вихідного файла | +| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах | +| `providerOptions` | object | Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі й типи; невідомі ключі або невідповідності змушують пропустити кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри без змін. Виконайте `video_generate action=list`, щоб побачити, що приймає кожен провайдер | -Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого значення, яке підтримує провайдер, а також переназначає перекладені підказки геометрії, наприклад size-to-aspect-ratio, коли fallback-провайдер має іншу поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, занадто велика кількість референсних входів) призводять до помилки ще до надсилання. +Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого підтримуваного провайдером значення, а також переназначає трансльовані геометричні підказки, наприклад size-to-aspect-ratio, коли fallback-провайдер має іншу поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто багато еталонних входів) призводять до помилки ще до надсилання. -Результати інструмента повідомляють застосовані налаштування. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернуті значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. +Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернуті значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. -Референсні входи також вибирають режим виконання: +Еталонні входи також визначають режим виконання: -- Немає референсних медіа: `generate` -- Будь-який референс зображення: `imageToVideo` -- Будь-який референс відео: `videoToVideo` -- Референсні аудіовходи не змінюють визначений режим; вони застосовуються поверх режиму, який вибирають референси зображення/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios` +- Без еталонних медіа: `generate` +- Будь-який еталон зображення: `imageToVideo` +- Будь-який еталон відео: `videoToVideo` +- Входи еталонного аудіо не змінюють визначений режим; вони застосовуються поверх режиму, який визначають еталони зображень/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios` -Змішані референси зображень і відео не є стабільною спільною поверхнею можливостей. -Краще використовувати один тип референсу на запит. +Змішані еталони зображень і відео не є стабільною спільною поверхнею можливостей. +Надавайте перевагу одному типу еталона на запит. #### Fallback і типізовані параметри -Деякі перевірки можливостей застосовуються на рівні fallback, а не на межі -інструмента, щоб запит, який перевищує обмеження основного провайдера, -усе ще міг виконатися на fallback, що має потрібні можливості: +Деякі перевірки можливостей застосовуються на рівні fallback, а не на +межі інструмента, щоб запит, який перевищує обмеження основного провайдера, +усе ще міг виконатися на fallback, що це підтримує: - Якщо активний кандидат не оголошує `maxInputAudios` (або оголошує його як - `0`), він пропускається, коли запит містить аудіореференси, і + `0`), він пропускається, коли запит містить аудіоеталони, і пробується наступний кандидат. -- Якщо `maxDurationSeconds` активного кандидата менший за запитаний - `durationSeconds`, а кандидат не оголошує список +- Якщо `maxDurationSeconds` активного кандидата нижчий за запитане + `durationSeconds` і кандидат не оголошує список `supportedDurationSeconds`, він пропускається. - Якщо запит містить `providerOptions`, а активний кандидат явно оголошує типізовану схему `providerOptions`, кандидат - пропускається, коли передані ключі відсутні в схемі або типи значень + пропускається, якщо надані ключі відсутні в схемі або типи значень не збігаються. Провайдери, які ще не оголосили схему, отримують - параметри без змін (зворотно сумісна наскрізна передача). Провайдер може - явно відмовитися від усіх параметрів провайдера, оголосивши порожню схему - (`capabilities.providerOptions: {}`), що призводить до такого самого пропуску, як і - невідповідність типів. + параметри без змін (зворотно сумісна пряма передача). Провайдер може + явно відмовитися від усіх provider options, оголосивши порожню схему + (`capabilities.providerOptions: {}`), що спричиняє такий самий пропуск, як і + невідповідність типу. -Перша причина пропуску в запиті записується на рівні `warn`, щоб оператори бачили, -коли їхній основний провайдер було пропущено; наступні пропуски записуються на -рівні `debug`, щоб довгі ланцюжки fallback не засмічували логи. Якщо кожен кандидат пропущено, -агрегована помилка містить причину пропуску для кожного. +Перша причина пропуску в запиті журналюється на рівні `warn`, щоб оператори бачили, +коли їхній основний провайдер було пропущено; наступні пропуски журналюються на +`debug`, щоб довгі ланцюжки fallback не засмічували журнал. Якщо пропущено кожного кандидата, +сукупна помилка містить причину пропуску для кожного з них. ## Дії -- **generate** (за замовчуванням) -- створити відео з указаного запиту та необов’язкових референсних входів. -- **status** -- перевірити стан поточної задачі генерації відео для поточної сесії без запуску нової генерації. +- **generate** (типово) -- створити відео за заданим запитом і необов’язковими еталонними входами. +- **status** -- перевірити стан активного відеозавдання для поточної сесії без запуску нової генерації. - **list** -- показати доступних провайдерів, моделі та їхні можливості. ## Вибір моделі @@ -238,13 +242,12 @@ Seedance використовує його для автоматичного в 1. **Параметр інструмента `model`** -- якщо агент указує його у виклику. 2. **`videoGenerationModel.primary`** -- із конфігурації. 3. **`videoGenerationModel.fallbacks`** -- пробуються по черзі. -4. **Автовизначення** -- використовує провайдерів із дійсною автентифікацією, починаючи з поточного провайдера за замовчуванням, а потім решту провайдерів в алфавітному порядку. +4. **Автовизначення** -- використовує провайдерів, які мають дійсну автентифікацію, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку. -Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі кандидати завершуються помилкою, помилка містить подробиці кожної спроби. +Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо помиляються всі кандидати, помилка містить подробиці кожної спроби. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, -щоб для генерації відео використовувалися лише явно вказані записи -`model`, `primary` і `fallbacks`. +щоб генерація відео використовувала лише явно задані записи `model`, `primary` і `fallbacks`. ```json5 { @@ -263,52 +266,52 @@ Seedance використовує його для автоматичного в - Використовує асинхронний endpoint DashScope / Model Studio. Референсні зображення та відео мають бути віддаленими URL `http(s)`. + Використовує асинхронну кінцеву точку DashScope / Model Studio. Еталонні зображення та відео мають бути віддаленими URL `http(s)`. - ID провайдера: `byteplus`. + Ідентифікатор провайдера: `byteplus`. - Моделі: `seedance-1-0-pro-250528` (за замовчуванням), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. + Моделі: `seedance-1-0-pro-250528` (типова), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. - Моделі T2V (`*-t2v-*`) не приймають зображення на вхід; моделі I2V і загальні моделі `*-pro-*` підтримують одне референсне зображення (перший кадр). Передайте зображення позиційно або задайте `role: "first_frame"`. ID моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. + Моделі T2V (`*-t2v-*`) не приймають входи зображень; моделі I2V і загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший кадр). Передайте зображення позиційно або встановіть `role: "first_frame"`. Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean — примусово встановлює 480p), `camera_fixed` (boolean). - Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID провайдера: `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. + Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера: `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. - Використовує уніфікований API `content[]`. Підтримує не більше 2 вхідних зображень (`first_frame` + `last_frame`). Усі входи мають бути віддаленими URL `https://`. Задайте `role: "first_frame"` / `"last_frame"` для кожного зображення або передайте зображення позиційно. + Використовує уніфікований API `content[]`. Підтримує щонайбільше 2 вхідні зображення (`first_frame` + `last_frame`). Усі входи мають бути віддаленими URL `https://`. Установіть `role: "first_frame"` / `"last_frame"` для кожного зображення або передайте зображення позиційно. - `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` зіставляється з `generate_audio`. `providerOptions.seed` (number) передається далі. + `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) передається далі. - Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID провайдера: `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. + Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера: `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. - Використовує уніфікований API `content[]`. Підтримує до 9 референсних зображень, 3 референсних відео та 3 референсних аудіо. Усі входи мають бути віддаленими URL `https://`. Задайте `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. + Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень, 3 еталонних відео та 3 еталонних аудіо. Усі входи мають бути віддаленими URL `https://`. Установіть `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. - `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` зіставляється з `generate_audio`. `providerOptions.seed` (number) передається далі. + `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) передається далі. - Виконання в локальному середовищі або хмарі під керуванням workflow. Підтримує text-to-video та image-to-video через налаштований граф. + Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф. - Використовує flow на основі черги для довготривалих завдань. Лише один референс зображення. + Використовує потік на основі черги для довготривалих завдань. Більшість моделей відео fal приймають одне еталонне зображення. Моделі Seedance 2.0 reference-to-video приймають до 9 зображень, 3 відео та 3 аудіоеталонів, максимум 12 еталонних файлів загалом. - Підтримує один референс зображення або одне референсне відео. + Підтримує одне еталонне зображення або одне еталонне відео. - Лише один референс зображення. + Лише одне еталонне зображення. @@ -316,31 +319,31 @@ Seedance використовує його для автоматичного в - Той самий бекенд DashScope, що й у Alibaba. Референсні входи мають бути віддаленими URL `http(s)`; локальні файли одразу відхиляються. + Той самий бекенд DashScope, що й у Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли одразу відхиляються. - Підтримує локальні файли через data URI. Для video-to-video потрібен `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`. + Підтримує локальні файли через URI даних. Для video-to-video потрібен `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`. - Лише один референс зображення. + Лише одне еталонне зображення. - Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути перенаправлень, які відкидають автентифікацію. `veo3` постачається лише як text-to-video; `kling` потребує віддаленого URL зображення. + Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути редиректів, які скидають автентифікацію. `veo3` вбудовано лише для text-to-video; `kling` потребує віддалений URL зображення. - Підтримує text-to-video, image-to-video з одним зображенням першого кадру, до 7 входів `reference_image` через xAI `reference_images`, а також потоки віддаленого редагування/розширення відео. + Підтримує text-to-video, image-to-video з одним зображенням першого кадру, до 7 входів `reference_image` через xAI `reference_images` і віддалені потоки редагування/розширення відео. -## Режими можливостей провайдера +## Режими можливостей провайдерів -Спільний контракт генерації відео тепер дозволяє провайдерам оголошувати -можливості, специфічні для режимів, а не лише плоскі агреговані обмеження. Нові реалізації провайдерів -мають надавати перевагу явним блокам режимів: +Спільний контракт генерації відео тепер дає змогу провайдерам оголошувати +можливості для конкретних режимів, а не лише плоскі сукупні обмеження. Нові +реалізації провайдерів мають надавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -353,6 +356,7 @@ capabilities: { enabled: true, maxVideos: 1, maxInputImages: 1, + maxInputImagesByModel: { "provider/reference-to-video": 9 }, maxDurationSeconds: 5, }, videoToVideo: { @@ -364,14 +368,19 @@ capabilities: { } ``` -Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, -недостатньо, щоб оголосити підтримку режимів перетворення. Провайдери мають явно оголошувати +Плоских сукупних полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо, +щоб оголосити підтримку режимів перетворення. Провайдери мають явно оголошувати `generate`, `imageToVideo` і `videoToVideo`, щоб live-тести, -контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти підтримку режимів. +контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти +підтримку режимів. + +Коли одна модель провайдера має ширшу підтримку еталонних входів, ніж решта, +використовуйте `maxInputImagesByModel`, `maxInputVideosByModel` або +`maxInputAudiosByModel` замість підвищення загального ліміту для всього режиму. ## Live-тести -Opt-in live-покриття для спільних вбудованих провайдерів: +Покриття зі згодою для спільних вбудованих провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -383,16 +392,16 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv pnpm test:live:media video ``` -Цей live-файл завантажує відсутні env vars провайдерів із `~/.profile`, за -замовчуванням надає перевагу live/env API-ключам над збереженими профілями автентифікації та запускає -безпечний для релізу smoke-тест за замовчуванням: +Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово +надає перевагу live/env API-ключам над збереженими профілями автентифікації та запускає +безпечний для релізу smoke-тест: -- `generate` для кожного не-FAL провайдера у sweep +- `generate` для кожного провайдера у sweep, крім FAL - односекундний запит про лобстера - ліміт операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` - (`180000` за замовчуванням) + (`180000` типово) -FAL вмикається через opt-in, оскільки затримка черги на боці провайдера може суттєво збільшити час релізу: +FAL підключається за згодою, оскільки затримка черги на боці провайдера може домінувати над часом релізу: ```bash pnpm test:live:media video --video-providers fal @@ -403,15 +412,15 @@ pnpm test:live:media video --video-providers fal - `imageToVideo`, коли `capabilities.imageToVideo.enabled` - `videoToVideo`, коли `capabilities.videoToVideo.enabled` і провайдер/модель - приймає локальний відеовхід на основі буфера у спільному sweep + приймає локальне відеовведення на основі буфера у спільному sweep -Сьогодні спільна live lane `videoToVideo` охоплює: +Наразі спільний live lane `videoToVideo` охоплює: -- `runway` лише тоді, коли вибрано `runway/gen4_aleph` +- `runway`, лише якщо ви виберете `runway/gen4_aleph` ## Конфігурація -Задайте модель генерації відео за замовчуванням у вашій конфігурації OpenClaw: +Установіть типову модель генерації відео у своїй конфігурації OpenClaw: ```json5 { @@ -432,10 +441,10 @@ pnpm test:live:media video --video-providers fal openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v" ``` -## Пов’язане +## Пов’язані матеріали - [Огляд інструментів](/uk/tools) -- [Фонові задачі](/uk/automation/tasks) -- відстеження задач для асинхронної генерації відео +- [Фонові завдання](/uk/automation/tasks) -- відстеження завдань для асинхронної генерації відео - [Alibaba Model Studio](/uk/providers/alibaba) - [BytePlus](/uk/concepts/model-providers#byteplus-international) - [ComfyUI](/uk/providers/comfy) @@ -448,5 +457,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 - [Together AI](/uk/providers/together) - [Vydra](/uk/providers/vydra) - [xAI](/uk/providers/xai) -- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) +- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) - [Моделі](/uk/concepts/models)