diff --git a/docs/uk/automation/cron-jobs.md b/docs/uk/automation/cron-jobs.md index e1f9a13f9..cb3175b92 100644 --- a/docs/uk/automation/cron-jobs.md +++ b/docs/uk/automation/cron-jobs.md @@ -7,15 +7,15 @@ sidebarTitle: Scheduled tasks summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway title: Заплановані завдання x-i18n: - generated_at: "2026-04-27T06:22:17Z" + generated_at: "2026-04-27T06:34:27Z" model: gpt-5.4 provider: openai - source_hash: 81a20982283388b36047bcfffe20af8edf0a9a1eab0ae5f9fee91919e36d0860 + source_hash: c7df825e11a574929f221214611ae041db94aec5b8ddd2101ac88a22427af3b1 source_path: automation/cron-jobs.md workflow: 15 --- -Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента у потрібний час і може повертати результат назад у чат-канал або на кінцеву точку Webhook. +Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента у потрібний час і може повертати результат назад у чат-канал або до кінцевої точки Webhook. ## Швидкий старт @@ -46,38 +46,38 @@ Cron — це вбудований планувальник Gateway. Він зб ## Як працює 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 запускається **всередині процесу 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 після завершення виконують best-effort закриття відстежуваних вкладок/процесів браузера для своєї сесії `cron:`, щоб відокремлена автоматизація браузера не залишала після себе осиротілі процеси. -- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск subagent більше не відповідає за фінальну відповідь, OpenClaw повторно надсилає запит один раз, щоб отримати фактичний результат перед доставленням. -- Ізольовані запуски cron надають перевагу структурованим метаданим про відмову у виконанні з вбудованого запуску, а потім переходять до відомих фінальних маркерів підсумку/виводу, таких як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не позначалася як успішний запуск. -- Ізольовані запуски cron також вважають помилки агента на рівні запуску помилками завдання, навіть якщо жоден payload відповіді не створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збої замість того, щоб позначати завдання як успішне. +- Одноразові завдання (`--at`) типово автоматично видаляються після успішного виконання. +- Ізольовані запуски cron у межах best-effort закривають відстежувані вкладки браузера/процеси для своєї сесії `cron:` після завершення запуску, щоб відокремлена автоматизація браузера не залишала після себе осиротілі процеси. +- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск subagent більше не відповідає за фінальну відповідь, OpenClaw повторно формує запит один раз, щоб отримати фактичний результат перед доставленням. +- Ізольовані запуски cron надають перевагу структурованим метаданим відмови виконання з вбудованого запуску, а потім повертаються до відомих маркерів фінального підсумку/виводу, таких як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не була позначена як успішний запуск. +- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть якщо жодного payload відповіді не було створено, тож збої моделі/провайдера збільшують лічильники помилок і спричиняють сповіщення про збої, а не очищають завдання як успішне. -Узгодження завдань для cron насамперед належить runtime, а вже потім спирається на стійку історію: активне cron-завдання залишається активним, доки runtime cron усе ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і минає 5-хвилинне пільгове вікно, перевірки обслуговування звіряють збережені журнали запусків і стан завдань для відповідного запуску `cron::`. Якщо ця стійка історія містить фінальний результат, реєстр завдань фіналізується на його основі; інакше обслуговування, яке належить Gateway, може позначити завдання як `lost`. Офлайновий аудит CLI може відновитися зі стійкої історії, але він не розглядає власний порожній набір активних завдань у процесі як доказ того, що Gateway-керований запуск cron зник. +Узгодження завдань для cron спочатку належить runtime, а вже потім спирається на довговічну історію: активне завдання cron лишається активним, поки runtime cron усе ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і спливає 5-хвилинне вікно очікування, перевірки обслуговування звіряють збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця довговічна історія показує термінальний результат, реєстр завдань завершується на її основі; інакше обслуговування, яким володіє Gateway, може позначити завдання як `lost`. Автономний аудит CLI може відновитися з довговічної історії, але не розглядає власний порожній внутрішньопроцесний набір активних завдань як доказ того, що запуск cron, яким володіє Gateway, зник. ## Типи розкладу -| Вид | Прапорець CLI | Опис | -| ------- | ------------- | ---------------------------------------------------------- | -| `at` | `--at` | Одноразова часова мітка (ISO 8601 або відносно, наприклад `20m`) | -| `every` | `--every` | Фіксований інтервал | -| `cron` | `--cron` | 5-польовий або 6-польовий cron-вираз з необов’язковим `--tz` | +| Kind | CLI flag | Description | +| ------- | --------- | ------------------------------------------------------- | +| `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 -Cron-вирази розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, 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" @@ -85,34 +85,34 @@ 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`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання. ## Стилі виконання -| Стиль | Значення `--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`). Ці системні події не подовжують свіжість щоденного/неактивного скидання для цільової сесії. **Ізольовані** завдання запускають окремий хід агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу будувати процеси на кшталт щоденних стендапів на основі попередніх підсумків. - - Для ізольованих завдань «свіжа сесія» означає новий ідентифікатор transcript/session для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явні обрані користувачем перевизначення model/auth, але не успадковує фоновий контекст розмови зі старішого рядка cron: маршрутизацію channel/group, політику send або queue, elevation, origin чи runtime-прив’язку ACP. Використовуйте `current` або `session:`, коли періодичне завдання має свідомо продовжувати роботу в тому самому контексті розмови. + + Для ізольованих завдань "нова сесія" означає новий ідентифікатор transcript/session для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення model/auth, але не успадковує фоновий контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищення привілеїв, походження або прив’язку runtime ACP. Використовуйте `current` або `session:`, коли періодичне завдання має свідомо продовжувати той самий контекст розмови. - Для ізольованих завдань завершення runtime тепер включає best-effort очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет. + Для ізольованих завдань завершення runtime тепер включає best-effort очищення браузера для цієї сесії cron. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет. - Ізольовані запуски cron також вивільняють будь-які вбудовані екземпляри runtime MCP, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як завершуються клієнти MCP для основної сесії та власної сесії, тож ізольовані cron-завдання не призводять до витоку дочірніх stdio-процесів або довгоживучих MCP-з’єднань між запусками. + Ізольовані запуски cron також звільняють будь-які вбудовані екземпляри runtime MCP, створені для завдання через спільний шлях очищення runtime. Це відповідає тому, як клієнти MCP основної та користувацької сесій завершуються, тож ізольовані завдання cron не спричиняють витоків дочірніх stdio-процесів або довгоживучих MCP-з’єднань між запусками. - Коли ізольовані запуски cron оркеструють subagent, доставлення також надає перевагу фінальному виводу дочірнього запуску перед застарілим проміжним текстом батьківського. Якщо дочірні запуски все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його. + Коли ізольовані запуски cron оркеструють subagent, доставлення також надає перевагу фінальному виводу нащадка замість застарілого проміжного тексту батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його. - Для цілей оголошення в Discord лише з текстом OpenClaw надсилає канонічний фінальний текст асистента один раз замість повторного відтворення і streamed/intermediate text payloads, і фінальної відповіді. Медіа та структуровані payloads Discord, як і раніше, доставляються окремо, щоб не втрачалися вкладення й компоненти. + Для цілей оголошення Discord лише з текстом OpenClaw надсилає канонічний фінальний текст помічника один раз, замість повторного відтворення і потокових/проміжних текстових payload, і фінальної відповіді. Медіа та структуровані payload Discord, як і раніше, доставляються окремими payload, щоб не втрачалися вкладення й компоненти. @@ -135,39 +135,40 @@ Cron-вирази розбираються за допомогою [croner](http Обмежити, які інструменти може використовувати завдання, наприклад `--tools exec,read`. -`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/моделі за замовчуванням для завдання. Налаштовані ланцюжки fallback, як і раніше, застосовуються, але звичайне перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. +`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/типової моделі для завдання. Налаштовані ланцюжки fallback, як і раніше, застосовуються, але звичайне перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. Пріоритет вибору моделі для ізольованих завдань такий: 1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) -2. `model` у payload для конкретного завдання -3. Збережене перевизначення моделі cron-сесії, вибране користувачем -4. Вибір моделі агента/за замовчуванням +2. `model` у payload конкретного завдання +3. Збережене перевизначення моделі сесії cron, вибране користувачем +4. Вибір моделі агента/типової моделі -Режим fast теж дотримується остаточно вибраного live-вибору. Якщо вибрана конфігурація моделі має `params.fastMode`, ізольований cron використовує його за замовчуванням. Збережене в сесії перевизначення `fastMode`, як і раніше, має пріоритет над конфігурацією в обох напрямах. +Швидкий режим також наслідує розв’язаний активний вибір. Якщо вибрана конфігурація моделі має `params.fastMode`, ізольований cron типово використовує його. Збережене в сесії перевизначення `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках. -Якщо ізольований запуск натрапляє на live-передавання керування зі зміною моделі, cron повторює спробу з перемкненим провайдером/моделлю та зберігає цей live-вибір для активного запуску перед повторною спробою. Якщо перемикання також містить новий auth profile, cron теж зберігає це перевизначення auth profile для активного запуску. Кількість повторних спроб обмежена: після початкової спроби плюс 2 повторні спроби після перемикання cron припиняє виконання замість нескінченного циклу. +Якщо ізольований запуск натрапляє на живий handoff перемикання моделі, cron виконує повторну спробу з переключеним провайдером/моделлю та зберігає цей активний вибір для поточного запуску перед повторною спробою. Коли перемикання також містить новий профіль auth, cron теж зберігає це перевизначення профілю auth для поточного запуску. Кількість повторних спроб обмежена: після початкової спроби плюс 2 повторні спроби через перемикання cron перериває роботу замість безкінечного циклу. ## Доставлення та вивід -| Режим | Що відбувається | -| ---------- | ---------------------------------------------------------------- | +| Режим | Що відбувається | +| ---------- | ------------------------------------------------------------------- | | `announce` | Резервно доставляє фінальний текст до цілі, якщо агент його не надіслав | -| `webhook` | Надсилає payload події завершення через POST на URL | -| `none` | Немає резервного доставлення з боку виконавця | +| `webhook` | Надсилає POST payload завершеної події на URL | +| `none` | Без резервного доставлення з боку runner | -Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставлення в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ідентифікатор кімнати або форму `room:!room:server` із Matrix. +Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставлення в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ID кімнати або форму `room:!room:server` із Matrix. -Для ізольованих завдань доставлення в чат є спільним. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. В іншому разі `announce`, `webhook` і `none` керують лише тим, що виконавець робить із фінальною відповіддю після циклу агента. +Для ізольованих завдань доставлення в чат є спільним. Якщо доступний маршрут чату, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. В іншому разі `announce`, `webhook` і `none` керують лише тим, що runner робить із фінальною відповіддю після ходу агента. -Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену live-ціль доставлення для маршруту резервного оголошення. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставлення провайдера не відновлюються з цих ключів, коли доступний контекст поточного чату. +Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену активну ціль доставлення для резервного маршруту оголошення. Внутрішні ключі сесії можуть бути у нижньому регістрі; цілі доставлення провайдера не відновлюються з цих ключів, коли доступний поточний контекст чату. -Сповіщення про помилки використовують окремий шлях призначення: +Сповіщення про збої використовують окремий маршрут призначення: -- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про помилки. -- `job.delivery.failureDestination` перевизначає його для конкретного завдання. -- Якщо жодне з них не задано, а завдання вже доставляє через `announce`, сповіщення про помилки тепер резервно надсилаються до цієї основної цілі announce. +- `cron.failureDestination` задає глобальне типове призначення для сповіщень про збої. +- `job.delivery.failureDestination` перевизначає це для конкретного завдання. +- Якщо жодне з них не задано і завдання вже доставляє через `announce`, сповіщення про збої тепер резервно надсилаються на цю основну ціль `announce`. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний режим доставлення не є `webhook`. +- `failureAlert.includeSkipped: true` дає змогу завданню або глобальній політиці сповіщень cron повторно повідомляти про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тож вони не впливають на backoff помилок виконання. ## Приклади CLI @@ -212,7 +213,7 @@ Cron-вирази розбираються за допомогою [croner](http ## Webhook-и -Gateway може надавати HTTP-кінцеві точки Webhook для зовнішніх тригерів. Увімкніть це в конфігурації: +Gateway може відкривати HTTP-кінцеві точки Webhook для зовнішніх тригерів. Увімкніть у конфігурації: ```json5 { @@ -231,7 +232,7 @@ Gateway може надавати HTTP-кінцеві точки Webhook для - `Authorization: Bearer ` (рекомендовано) - `x-openclaw-token: ` -Токени в query string відхиляються. +Токени в рядку запиту відхиляються. @@ -253,7 +254,7 @@ Gateway може надавати HTTP-кінцеві точки Webhook для - Запустити ізольований цикл агента: + Запустити ізольований хід агента: ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -266,7 +267,7 @@ Gateway може надавати HTTP-кінцеві точки Webhook для - Власні імена hook визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload на дії `wake` або `agent` за допомогою шаблонів або трансформацій коду. + Користувацькі імена hook розв’язуються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload на дії `wake` або `agent` за допомогою шаблонів або кодових перетворень. @@ -275,10 +276,10 @@ Gateway може надавати HTTP-кінцеві точки Webhook для - Використовуйте окремий токен 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 @@ -295,17 +296,17 @@ Gateway може надавати HTTP-кінцеві точки Webhook для openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push-кінцевої точки. +Це записує конфігурацію `hooks.gmail`, вмикає пресет Gmail і використовує Tailscale Funnel для push-кінцевої точки. ### Автозапуск Gateway -Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час завантаження запускає `gog gmail watch serve` і автоматично поновлює watch. Щоб відмовитися, установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`. +Коли `hooks.enabled=true` і встановлено `hooks.gmail.account`, Gateway під час завантаження запускає `gog gmail watch serve` і автоматично поновлює watch. Щоб відмовитися, встановіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`. ### Ручне одноразове налаштування - Виберіть проєкт GCP, якому належить OAuth-клієнт, що використовується `gog`: + Виберіть проєкт GCP, якому належить OAuth client, що використовується `gog`: ```bash gcloud auth login @@ -314,7 +315,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com ``` - + ```bash gcloud pubsub topics create gog-gmail-watch gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ @@ -348,28 +349,28 @@ openclaw webhooks gmail setup --account openclaw@gmail.com ## Керування завданнями ```bash -# Перелічити всі завдання +# List all jobs openclaw cron list -# Показати одне завдання, включно з визначеним маршрутом доставлення +# Show one job, including resolved delivery route openclaw cron show -# Відредагувати завдання +# Edit a job openclaw cron edit --message "Updated prompt" --model "opus" -# Примусово запустити завдання зараз +# Force run a job now openclaw cron run -# Запустити лише якщо настав час +# Run only if due openclaw cron run --due -# Переглянути історію запусків +# View run history openclaw cron runs --id --limit 50 -# Видалити завдання +# Delete a job openclaw cron remove -# Вибір агента (конфігурації з кількома агентами) +# Agent selection (multi-agent setups) openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` @@ -378,9 +379,9 @@ openclaw cron edit --clear-agent Примітка щодо перевизначення моделі: - `openclaw cron add|edit --model ...` змінює вибрану модель завдання. -- Якщо модель дозволена, саме ця комбінація провайдера/моделі потрапляє до ізольованого запуску агента. -- Якщо вона не дозволена, cron видає попередження і повертається до вибору моделі агента/моделі за замовчуванням для завдання. -- Налаштовані ланцюжки fallback, як і раніше, застосовуються, але звичайне перевизначення `--model` без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби. +- Якщо модель дозволена, саме ця пара провайдер/модель передається до ізольованого запуску агента. +- Якщо вона не дозволена, cron видає попередження і повертається до вибору моделі агента/типової моделі для завдання. +- Налаштовані ланцюжки fallback, як і раніше, застосовуються, але звичайне перевизначення `--model` без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до мовчазної додаткової цілі повторної спроби. ## Конфігурація @@ -403,23 +404,23 @@ openclaw cron edit --clear-agent } ``` -Стан sidecar runtime виводиться з `cron.store`: сховище `.json`, як-от `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а до шляху сховища без суфікса `.json` додається `-state.json`. +Sidecar стану runtime виводиться з `cron.store`: сховище `.json`, таке як `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, тоді як до шляху сховища без суфікса `.json` додається `-state.json`. -Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. +Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. - **Повторна спроба для одноразових завдань**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційною затримкою. Постійні помилки відразу вимикаються. + **Повторна спроба для одноразового завдання**: тимчасові помилки (ліміт швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки одразу вимикають завдання. - **Повторна спроба для періодичних завдань**: експоненційна затримка (від 30 с до 60 хв) між повторними спробами. Після наступного успішного запуску затримка скидається. + **Повторна спроба для періодичного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторами. Backoff скидається після наступного успішного запуску. - `cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналів запусків. + `cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналу запусків. -## Усунення проблем +## Усунення несправностей ### Послідовність команд @@ -437,33 +438,33 @@ openclaw doctor - Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`. - - Переконайтеся, що Gateway працює безперервно. - - Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста. - - `reason: not-due` у виводі запуску означає, що ручний запуск перевірявся командою `openclaw cron run --due`, і для завдання ще не настав час. + - Підтвердьте, що Gateway працює безперервно. + - Для розкладів `cron` перевірте часовий пояс (`--tz`) відносно часового поясу хоста. + - `reason: not-due` у виводі запуску означає, що ручний запуск перевірявся через `openclaw cron run --due` і час виконання завдання ще не настав. - - - Режим доставлення `none` означає, що резервне надсилання з боку виконавця не очікується. Агент усе ще може надіслати повідомлення безпосередньо через інструмент `message`, коли маршрут чату доступний. + + - Режим доставлення `none` означає, що резервне надсилання з боку runner не очікується. Агент усе ще може напряму надсилати через інструмент `message`, коли доступний маршрут чату. - Відсутня/некоректна ціль доставлення (`channel`/`to`) означає, що вихідне надсилання було пропущено. - - Для Matrix скопійовані або застарілі завдання з `delivery.to` room ID у нижньому регістрі можуть не працювати, оскільки room ID у Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` з Matrix. + - Для Matrix скопійовані або застарілі завдання з `delivery.to` room ID у нижньому регістрі можуть не працювати, оскільки room ID Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` з Matrix. - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставлення було заблоковано обліковими даними. - - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне доставлення, а також резервний шлях підсумку через чергу, тож назад у чат нічого не публікується. - - Якщо агент має сам надіслати повідомлення користувачеві, перевірте, що завдання має придатний маршрут (`channel: "last"` з попереднім чатом або явний канал/ціль). + - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне доставлення, а також резервний шлях підсумку в черзі, тому назад у чат нічого не публікується. + - Якщо агент має сам написати користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль). - - - Свіжість щоденного та неактивного скидання не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). - - Пробудження cron, запуски heartbeat, сповіщення exec і службові дії gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`. - - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії в transcript JSONL, якщо файл усе ще доступний. Застарілі рядки неактивності без `lastInteractionAt` використовують цей відновлений час початку як базову точку неактивності. + + - Свіжість щоденного скидання та скидання через неактивність не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). + - Пробудження cron, запуски heartbeat, сповіщення exec і службові операції gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але не подовжують `sessionStartedAt` або `lastInteractionAt`. + - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії transcript JSONL, якщо файл усе ще доступний. Застарілі рядки неактивності без `lastInteractionAt` використовують цей відновлений час початку як базову точку неактивності. - Cron без `--tz` використовує часовий пояс хоста gateway. - Розклади `at` без часового поясу трактуються як UTC. - - `activeHours` у Heartbeat використовує налаштоване визначення часового поясу. + - `activeHours` Heartbeat використовує налаштоване визначення часового поясу. ## Пов’язане -- [Автоматизація й завдання](/uk/automation) — огляд усіх механізмів автоматизації +- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації з одного погляду - [Фонові завдання](/uk/automation/tasks) — реєстр завдань для виконань cron - [Heartbeat](/uk/gateway/heartbeat) — періодичні цикли основної сесії -- [Часовий пояс](/uk/concepts/timezone) — налаштування часового поясу +- [Часовий пояс](/uk/concepts/timezone) — конфігурація часового поясу diff --git a/docs/uk/cli/cron.md b/docs/uk/cli/cron.md index 81ce13027..dedb33ee1 100644 --- a/docs/uk/cli/cron.md +++ b/docs/uk/cli/cron.md @@ -1,14 +1,14 @@ --- read_when: - - Вам потрібні заплановані завдання і пробудження + - Вам потрібні заплановані завдання та пробудження - Ви налагоджуєте виконання Cron і журнали -summary: Довідка CLI для `openclaw cron` (планування і запуск фонових завдань) +summary: Довідка CLI для `openclaw cron` (планування та запуск фонових завдань) title: Cron x-i18n: - generated_at: "2026-04-27T06:23:55Z" + generated_at: "2026-04-27T06:34:28Z" model: gpt-5.4 provider: openai - source_hash: 498759e5682d63a2f3f96fd4dcdc7402f1398a6b1a835e6a3b624e526fec5ce3 + source_hash: 2997467e11d787009920d5036a2590780839b219d8be6804a9ee61fd9b11a585 source_path: cli/cron.md workflow: 15 --- @@ -18,45 +18,45 @@ x-i18n: Керуйте завданнями Cron для планувальника Gateway. -Запустіть `openclaw cron --help`, щоб побачити повну поверхню команд. Див. [Завдання Cron](/uk/automation/cron-jobs) для концептуального посібника. +Запустіть `openclaw cron --help`, щоб переглянути повну поверхню команд. Див. [завдання Cron](/uk/automation/cron-jobs) для концептуального посібника. -## Сеанси +## Сесії `--session` приймає `main`, `isolated`, `current` або `session:`. - - - `main` прив’язується до основного сеансу агента. - - `isolated` створює нову стенограму та ідентифікатор сеансу для кожного запуску. - - `current` прив’язується до активного сеансу на момент створення. - - `session:` фіксує прив’язку до явного постійного ключа сеансу. + + - `main` прив’язується до основної сесії агента. + - `isolated` створює новий transcript та ідентифікатор сесії для кожного запуску. + - `current` прив’язується до активної сесії на момент створення. + - `session:` фіксує явний ключ постійної сесії. - - Ізольовані запуски скидають фоновий контекст розмови. Маршрутизація каналу й групи, політика надсилання/черги, підвищення привілеїв, джерело й прив’язка середовища виконання ACP скидаються для нового запуску. Безпечні налаштування та явно вибрані користувачем перевизначення моделі чи автентифікації можуть зберігатися між запусками. + + Isolated-запуски скидають фоновий контекст розмови. Маршрутизація каналу й групи, політика надсилання/черги, підвищення привілеїв, origin і прив’язка середовища виконання ACP скидаються для нового запуску. Безпечні параметри та явні перевизначення моделі або автентифікації, вибрані користувачем, можуть зберігатися між запусками. ## Доставка -`openclaw cron list` і `openclaw cron show ` показують попередній перегляд визначеного маршруту доставки. Для `channel: "last"` у попередньому перегляді видно, чи маршрут визначено з основного або поточного сеансу, чи він завершиться безпечною відмовою. +`openclaw cron list` і `openclaw cron show ` показують попередній перегляд визначеного маршруту доставки. Для `channel: "last"` попередній перегляд показує, чи маршрут визначився з основної або поточної сесії, чи буде безпечно відхилений. -Ізольовані завдання `cron add` типово використовують доставку `--announce`. Використовуйте `--no-deliver`, щоб залишити вивід внутрішнім. `--deliver` залишається застарілим псевдонімом для `--announce`. +Isolated-завдання `cron add` за замовчуванням використовують доставку `--announce`. Використовуйте `--no-deliver`, щоб залишити вивід внутрішнім. `--deliver` залишається застарілим синонімом для `--announce`. -### Володіння доставкою +### Відповідальність за доставку -Для ізольованої доставки чату Cron відповідальність поділяється між агентом і виконавцем: +Доставка повідомлень у чат для isolated Cron спільно розподіляється між агентом і виконавцем: -- Агент може надсилати напряму через інструмент `message`, якщо маршрут чату доступний. -- Резервна доставка `announce` надсилає лише фінальну відповідь, якщо агент не надіслав її напряму до визначеної цілі. -- `webhook` надсилає завершене навантаження на URL. +- Агент може надсилати напряму за допомогою інструмента `message`, коли маршрут чату доступний. +- `announce` резервно доставляє лише фінальну відповідь, якщо агент не надіслав її напряму до визначеної цілі. +- `webhook` надсилає завершений payload на URL. - `none` вимикає резервну доставку виконавцем. -`--announce` — це резервна доставка фінальної відповіді виконавцем. `--no-deliver` вимикає цей резервний механізм, але не прибирає в агента інструмент `message`, якщо маршрут чату доступний. +`--announce` — це резервна доставка фінальної відповіді виконавцем. `--no-deliver` вимикає цю резервну доставку, але не прибирає інструмент `message` агента, коли маршрут чату доступний. -Нагадування, створені з активного чату, зберігають активну ціль доставки чату для резервної доставки announce. Внутрішні ключі сеансу можуть бути в нижньому регістрі; не використовуйте їх як джерело істини для чутливих до регістру ідентифікаторів провайдерів, таких як ідентифікатори кімнат Matrix. +Нагадування, створені з активного чату, зберігають ціль доставки активного чату для резервної доставки announce. Внутрішні ключі сесій можуть бути в нижньому регістрі; не використовуйте їх як джерело істини для чутливих до регістру ідентифікаторів провайдерів, таких як ідентифікатори кімнат Matrix. ### Доставка збоїв @@ -67,33 +67,33 @@ x-i18n: 3. Основна ціль announce завдання (коли явну ціль для збоїв не задано). -Завдання основного сеансу можуть використовувати `delivery.failureDestination`, лише коли основний режим доставки — `webhook`. Ізольовані завдання приймають його в усіх режимах. +Завдання основної сесії можуть використовувати `delivery.failureDestination`, лише коли основний режим доставки — `webhook`. Isolated-завдання приймають його в усіх режимах. -Примітка: ізольовані запуски Cron розглядають збої агента на рівні запуску як помилки завдання, навіть коли -навантаження відповіді не створюється, тому збої моделі/провайдера все одно збільшують лічильники помилок -і запускають сповіщення про збій. +Примітка: isolated Cron-запуски трактують збої агента на рівні запуску як помилки завдання, навіть коли payload відповіді не створено, тому збої моделі/провайдера все одно збільшують лічильники помилок і запускають сповіщення про збій. ## Планування ### Одноразові завдання -`--at ` планує одноразовий запуск. Дата й час без зсуву трактуються як UTC, якщо ви також не передасте `--tz `, яке інтерпретує локальний час у вказаному часовому поясі. +`--at ` планує одноразовий запуск. Дати й час без зміщення трактуються як UTC, якщо ви також не передасте `--tz `, який інтерпретує локальний час у вказаному часовому поясі. -Одноразові завдання типово видаляються після успішного виконання. Використовуйте `--keep-after-run`, щоб зберегти їх. +Одноразові завдання після успішного виконання за замовчуванням видаляються. Використовуйте `--keep-after-run`, щоб зберегти їх. ### Повторювані завдання -Повторювані завдання використовують експоненційне збільшення затримки повтору після послідовних помилок: 30с, 1хв, 5хв, 15хв, 60хв. Після наступного успішного запуску розклад повертається до звичайного режиму. +Після послідовних помилок повторювані завдання використовують експоненційне резервне повторення: 30 с, 1 хв, 5 хв, 15 хв, 60 хв. Після наступного успішного запуску розклад повертається до норми. + +Пропущені запуски відстежуються окремо від помилок виконання. Вони не впливають на резервне повторення, але `openclaw cron edit --failure-alert-include-skipped` може додати до сповіщень про збої повторювані сповіщення про пропущені запуски. ### Ручні запуски `openclaw cron run` повертається, щойно ручний запуск поставлено в чергу. Успішні відповіді містять `{ ok: true, enqueued: true, runId }`. Використовуйте `openclaw cron runs --id `, щоб відстежити підсумковий результат. -`openclaw cron run ` типово примусово запускає завдання. Використовуйте `--due`, щоб зберегти попередню поведінку «запускати лише коли настав час». +`openclaw cron run ` за замовчуванням примусово запускає завдання. Використовуйте `--due`, щоб зберегти стару поведінку «запускати лише якщо настав час». ## Моделі @@ -101,82 +101,82 @@ x-i18n: `cron add|edit --model ` вибирає дозволену модель для завдання. -Якщо модель не дозволена, Cron попереджає й повертається до вибору моделі агента або типової моделі для завдання. Налаштовані ланцюжки резервного переходу все ще застосовуються, але звичайне перевизначення моделі без явного списку резервних варіантів для завдання більше не додає основну модель агента як приховану додаткову ціль повтору. +Якщо модель не дозволена, Cron показує попередження і повертається до вибору моделі агента або моделі за замовчуванням для завдання. Налаштовані ланцюжки резервного переходу й надалі застосовуються, але звичайне перевизначення моделі без явного списку резервних варіантів для завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. -### Пріоритет моделі для ізольованого Cron +### Пріоритет моделей isolated Cron -Ізольований Cron визначає активну модель у такому порядку: +Isolated Cron визначає активну модель у такому порядку: 1. Перевизначення Gmail-hook. -2. `--model` для конкретного завдання. -3. Збережене перевизначення моделі сеансу Cron (коли користувач її вибрав). -4. Вибір моделі агента або типової моделі. +2. `--model` для завдання. +3. Збережене перевизначення моделі cron-session (коли користувач його вибрав). +4. Вибір моделі агента або моделі за замовчуванням. ### Швидкий режим -Швидкий режим ізольованого Cron слідує за визначеним вибором активної моделі. Конфігурація моделі `params.fastMode` застосовується типово, але збережене в сеансі перевизначення `fastMode` усе ще має пріоритет над конфігурацією. +Швидкий режим isolated Cron дотримується визначеного вибору активної моделі. Конфігурація моделі `params.fastMode` застосовується за замовчуванням, але збережене перевизначення `fastMode` сесії все одно має вищий пріоритет за конфігурацію. -### Повторні спроби під час перемикання live-моделі +### Повторні спроби при перемиканні активної моделі -Якщо ізольований запуск викидає `LiveSessionModelSwitchError`, Cron зберігає перевизначений провайдер і модель (а також перевизначення профілю автентифікації, якщо воно є) для активного запуску перед повторною спробою. Зовнішній цикл повторів обмежений двома повторними спробами перемикання після початкової спроби, а потім переривається замість нескінченного циклу. +Якщо isolated-запуск викидає `LiveSessionModelSwitchError`, Cron перед повторною спробою зберігає перемкнений провайдер і модель (а також перевизначення профілю автентифікації після перемикання, якщо воно є) для активного запуску. Зовнішній цикл повторних спроб обмежено двома повторними спробами перемикання після початкової спроби, після чого він переривається замість нескінченного циклу. ## Вивід запуску та відмови -### Приглушення застарілих підтверджень +### Придушення застарілих підтверджень -Ізольовані ходи Cron приглушують застарілі відповіді, що містять лише підтвердження. Якщо перший результат — лише проміжне оновлення стану і жоден субагент-нащадок не відповідає за фінальну відповідь, Cron один раз повторно формує запит для отримання реального результату перед доставкою. +У turns isolated Cron придушуються відповіді, що містять лише застаріле підтвердження. Якщо перший результат — це лише проміжне оновлення стану і жоден дочірній запуск підлеглого агента не відповідає за остаточну відповідь, Cron один раз повторно формує запит для отримання реального результату перед доставкою. -### Приглушення тихого токена +### Придушення тихого токена -Якщо ізольований запуск Cron повертає лише тихий токен (`NO_REPLY` або `no_reply`), Cron приглушує як пряме вихідне доставлення, так і резервний шлях зведення через чергу, тому назад у чат нічого не надсилається. +Якщо isolated Cron-запуск повертає лише тихий токен (`NO_REPLY` або `no_reply`), Cron придушує як пряме вихідне доставлення, так і резервний шлях зведення в черзі, тому назад у чат нічого не публікується. ### Структуровані відмови -Ізольовані запуски Cron надають перевагу структурованим метаданим відмови виконання із вбудованого запуску, а потім переходять до відомих маркерів відмови у фінальному виводі, таких як `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` і фрази відмови прив’язки погодження. +Isolated Cron-запуски надають перевагу структурованим метаданим відмови виконання із вбудованого запуску, а потім повертаються до відомих маркерів відмови у фінальному виводі, таких як `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` і фрази відмови, пов’язані з прив’язкою схвалення. -`cron list` і історія запусків показують причину відмови замість повідомлення про заблоковану команду як `ok`. +`cron list` та історія запусків показують причину відмови замість того, щоб позначати заблоковану команду як `ok`. ## Зберігання -Зберігання й видалення контролюються в конфігурації: +Зберігання та очищення налаштовуються в конфігурації: -- `cron.sessionRetention` (типово `24h`) видаляє завершені сеанси ізольованих запусків. +- `cron.sessionRetention` (типово `24h`) очищає завершені сесії isolated-запусків. - `cron.runLog.maxBytes` і `cron.runLog.keepLines` очищають `~/.openclaw/cron/runs/.jsonl`. -## Міграція старих завдань +## Міграція старіших завдань -Якщо у вас є завдання Cron, створені до поточного формату доставки та зберігання, запустіть `openclaw doctor --fix`. Doctor нормалізує застарілі поля Cron (`jobId`, `schedule.cron`, поля доставки верхнього рівня, включно із застарілим `threadId`, псевдоніми доставки `provider` у навантаженні) і мігрує прості резервні завдання webhook з `notify: true` до явної доставки webhook, коли налаштовано `cron.webhook`. +Якщо у вас є завдання Cron, створені до поточного формату доставки та зберігання, запустіть `openclaw doctor --fix`. Doctor нормалізує застарілі поля Cron (`jobId`, `schedule.cron`, поля доставки верхнього рівня, включно із застарілим `threadId`, псевдоніми доставки `provider` у payload) і мігрує прості резервні webhook-завдання `notify: true` до явної доставки webhook, коли налаштовано `cron.webhook`. -## Поширені зміни +## Типові зміни -Оновлення параметрів доставки без зміни повідомлення: +Оновіть параметри доставки без зміни повідомлення: ```bash openclaw cron edit --announce --channel telegram --to "123456789" ``` -Вимкнення доставки для ізольованого завдання: +Вимкніть доставку для isolated-завдання: ```bash openclaw cron edit --no-deliver ``` -Увімкнення полегшеного bootstrap-контексту для ізольованого завдання: +Увімкніть полегшений початковий контекст для isolated-завдання: ```bash openclaw cron edit --light-context ``` -Оголошення в певний канал: +Оголосіть у конкретний канал: ```bash openclaw cron edit --announce --channel slack --to "channel:C1234567890" ``` -Створення ізольованого завдання з полегшеним bootstrap-контекстом: +Створіть isolated-завдання з полегшеним початковим контекстом: ```bash openclaw cron add \ @@ -188,11 +188,11 @@ openclaw cron add \ --no-deliver ``` -`--light-context` застосовується лише до ізольованих завдань ходу агента. Для запусків Cron полегшений режим залишає bootstrap-контекст порожнім замість додавання повного набору bootstrap-контексту робочого простору. +`--light-context` застосовується лише до isolated agent-turn завдань. Для Cron-запусків полегшений режим залишає початковий контекст порожнім замість ін’єкції повного набору початкового контексту робочого простору. -## Поширені команди адміністрування +## Типові команди адміністрування -Ручний запуск і перегляд: +Ручний запуск і перевірка: ```bash openclaw cron list @@ -202,9 +202,9 @@ openclaw cron run --due openclaw cron runs --id --limit 50 ``` -Записи `cron runs` включають діагностику доставки з цільовою cron-адресою, визначеною ціллю, надсиланнями через інструмент повідомлень, використанням резервного механізму та станом доставки. +Записи `cron runs` включають діагностику доставки з передбаченою ціллю Cron, визначеною ціллю, надсиланнями через інструмент повідомлень, використанням резервного шляху та станом доставки. -Перенаправлення агента й сеансу: +Перенаправлення агента та сесії: ```bash openclaw cron edit --agent ops diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 3a4460355..c9578d8b6 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,72 +1,72 @@ --- read_when: - - Вам потрібна точна семантика полів конфігурації або значення за замовчуванням + - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник з конфігурації +summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник із конфігурації x-i18n: - generated_at: "2026-04-26T19:17:02Z" + generated_at: "2026-04-27T06:34:28Z" model: gpt-5.4 provider: openai - source_hash: 2579a59555d480b116955cad0508392240ee6ae4f19cf46b8fc754c0ce48f870 + source_hash: 497bd9147b0c08e04195ab7b697f76bd69513f63f5c5a248a8fead3c9cecd570 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 і дає посилання назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і плагінам, а також глибокі параметри пам’яті/QMD винесені на окремі сторінки, а не наведені тут. -Код як джерело істини: +Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із вбудованими метаданими bundled/plugin/channel, об’єднаними за наявності +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із злитими метаданими bundled/plugin/channel, коли вони доступні - `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації відносно поточної поверхні схеми +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc на відповідність поточній поверхні схеми Шлях пошуку для агента: використовуйте дію інструмента `gateway` `config.schema.lookup` для точної документації та обмежень на рівні полів перед редагуванням. Використовуйте -[Configuration](/uk/gateway/configuration) для рекомендацій, орієнтованих на завдання, а цю сторінку — +[Configuration](/uk/gateway/configuration) для вказівок, орієнтованих на завдання, а цю сторінку — для ширшої карти полів, значень за замовчуванням і посилань на довідники підсистем. -Окремі поглиблені довідники: +Окремі детальні довідники: -- [Довідник з конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Косі команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки власників channel/plugin для поверхонь команд, специфічних для каналів +- [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 каталогу команд +- сторінки каналів/плагінів-власників для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі та коми в кінці). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. --- ## Канали -Ключі конфігурації для кожного каналу перенесені на окрему сторінку — див. +Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. [Configuration — channels](/uk/gateway/config-channels) для `channels.*`, -включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими -bundled каналами (автентифікація, контроль доступу, кілька облікових записів, обмеження згадок). +зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших +bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження згадувань). -## Значення агента за замовчуванням, multi-agent, сесії та повідомлення +## Значення агентів за замовчуванням, multi-agent, сесії та повідомлення Перенесено на окрему сторінку — див. [Configuration — agents](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox) +- `agents.defaults.*` (робочий простір, модель, thinking, Heartbeat, пам’ять, медіа, Skills, sandbox) - `multiAgent.*` (маршрутизація та прив’язки multi-agent) - `session.*` (життєвий цикл сесії, Compaction, очищення) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - `talk.speechLocale`: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS - - `talk.silenceTimeoutMs`: якщо не встановлено, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) -## Інструменти та custom providers +## Інструменти та власні провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів із backing provider, а також налаштування custom -provider / base-URL перенесені на окрему сторінку — див. +Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів, а також налаштування +власних провайдерів / базових 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` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -74,7 +74,7 @@ provider / base-URL перенесені на окрему сторінку — ```json5 { mcp: { - // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction. + // Необов’язково. За замовчуванням: 600000 мс (10 хвилин). Встановіть 0, щоб вимкнути витіснення під час простою. sessionIdleTtlMs: 600000, servers: { docs: { @@ -95,15 +95,15 @@ provider / base-URL перенесені на окрему сторінку — - `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які надають налаштовані MCP-інструменти. -- `mcp.sessionIdleTtlMs`: idle TTL для bundled MCP runtime на рівні сесії. - Одноразові вбудовані запуски запитують очищення після завершення виконання; цей TTL є - запобіжним механізмом для довготривалих сесій і майбутніх викликів. -- Зміни в `mcp.*` застосовуються гаряче через вивільнення кешованих session MCP runtime. - Наступне виявлення/використання інструмента створює їх заново з нової конфігурації, тому видалені - записи `mcp.servers` прибираються негайно, а не очікують завершення idle TTL. +- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP-середовищ виконання з прив’язкою до сесії. + Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є + страховкою для довготривалих сесій і майбутніх викликачів. +- Зміни в `mcp.*` застосовуються на льоту шляхом звільнення кешованих session MCP-середовищ виконання. + Наступне виявлення/використання інструмента відтворює їх із нової конфігурації, тому видалені + записи `mcp.servers` прибираються негайно, а не чекають 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 @@ -120,7 +120,7 @@ provider / base-URL перенесені на окрему сторінку — }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або plaintext рядок env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -130,18 +130,18 @@ provider / base-URL перенесені на окрему сторінку — } ``` -- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace skills не зачіпаються). -- `load.extraDirs`: додаткові спільні кореневі каталоги skills (найнижчий пріоритет). +- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/workspace 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..apiKey`: зручне поле для skills, що оголошують основну змінну середовища (plaintext рядок або об’єкт SecretRef). --- -## Plugins +## Плагіни ```json5 { @@ -166,45 +166,45 @@ provider / base-URL перенесені на окрему сторінку — ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні OpenClaw plugins, а також сумісні bundled 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 hooks і підтримуваних каталогів hook, наданих bundle. -- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені не-bundled 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, якщо вона доступна). -- Налаштування облікових записів/виконання channel plugin розміщуються в `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` або env-змінну `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). +- Виявлення підтримує нативні OpenClaw plugins, а також сумісні бандли Codex і Claude, включно з бандлами Claude стандартного макета без manifest. +- **Зміни конфігурації потребують перезапуску gateway.** +- `allow`: необов’язковий список дозволу (завантажуються лише перелічені plugins). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні плагіна (коли це підтримує плагін). +- `plugins.entries..env`: карта змінних середовища в області плагіна. +- `plugins.entries..hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють промпт, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks плагіна та підтримуваних каталогів hooks, наданих бандлами. +- `plugins.entries..hooks.allowConversationAccess`: якщо `true`, довірені неbundled plugins можуть читати необроблений вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому плагіну запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо ви навмисно хочете дозволити будь-яку модель. +- `plugins.entries..config`: визначений плагіном об’єкт конфігурації (валідується схемою нативного OpenClaw plugin, коли вона доступна). +- Налаштування облікових записів/середовища виконання для channel plugin розміщуються в `channels.` і мають описуватися метаданими `channelConfigs` у manifest плагіна-власника, а не центральним реєстром параметрів OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера веб-отримання Firecrawl. + - `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`: тайм-аут запиту scrape у секундах (за замовчуванням: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (веб-пошук Grok). - `enabled`: увімкнути провайдера X Search. - - `model`: модель Grok, яку слід використовувати для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) для фаз і порогів. - - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: Cron-розклад для кожного повного циклу dreaming (типово `"0 3 * * *"`). + - `model`: модель Grok, яку використовувати для пошуку (наприклад, `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: налаштування Dreaming для пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. + - `enabled`: головний перемикач Dreaming (за замовчуванням `false`). + - `frequency`: Cron-ритм для кожного повного проходу Dreaming (за замовчуванням `"0 3 * * *"`). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Довіднику з конфігурації пам’яті](/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` -- Увімкнені Claude bundled plugins також можуть надавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як необроблені патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного plugin пам’яті або `"none"`, щоб вимкнути plugins пам’яті. -- `plugins.slots.contextEngine`: вибрати id активного plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- Увімкнені plugins-бандли Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати ідентифікатор активного memory plugin або `"none"`, щоб вимкнути plugins пам’яті. +- `plugins.slots.contextEngine`: вибрати ідентифікатор активного плагіна рушія контексту; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший рушій. Див. [Plugins](/uk/tools/plugin). --- -## Browser +## Браузер ```json5 { @@ -213,8 +213,8 @@ provider / base-URL перенесені на окрему сторінку — evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі + // allowPrivateNetwork: true, // застарілий псевдонім // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -251,31 +251,31 @@ provider / base-URL перенесені на окрему сторінку — ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `tabCleanup` очищає відстежувані вкладки основного агента після простою або коли - сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб +- `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли + сесія перевищує свій ліміт. Встановіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не встановлено, тому навігація браузера типово залишається суворо обмеженою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі віддалені кінцеві точки профілю CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тож навігація браузера за замовчуванням залишається суворо обмеженою. +- Встановлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. +- У суворому режимі кінцеві точки віддалених CDP-профілів (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. - `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі підключення (запуск/зупинка/скидання вимкнені). +- Віддалені профілі працюють лише в режимі 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 як + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), + коли ваш провайдер надає вам прямий DevTools WebSocket URL. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддалених і + `attachOnly` перевірок доступності CDP, а також до запитів на відкриття вкладок. Керовані loopback- + профілі зберігають локальні значення CDP за замовчуванням. +- Якщо зовнішньо керований CDP-сервіс доступний через loopback, установіть для цього + профілю `attachOnly: true`; інакше OpenClaw трактуватиме loopback-порт як локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом. - Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на - вибраному хості або через підключений вузол браузера. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний + вибраному хості або через підключений браузерний Node. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на певний профіль браузера на основі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks завантаження - одного файлу, без перевизначення тайм-ауту діалогів, без `wait --load networkidle`, а також без + дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks для завантаження одного файла, + без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. @@ -283,17 +283,17 @@ provider / base-URL перенесені на окрему сторінку — `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший — у Brave. - Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP - після запуску процесу та `browser.localCdpReadyTimeoutMs` для + після старту процесу та `browser.localCdpReadyTimeoutMs` для готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome - запускається успішно, але перевірки готовності змагаються із запуском. Обидва значення мають бути + успішно запускається, але перевірки готовності змагаються зі стартом. Обидва значення мають бути додатними цілими числами до `120000` мс; некоректні значення конфігурації відхиляються. -- Порядок автовиявлення: типовий браузер, якщо на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` і `browser.profiles..executablePath` обидва +- Порядок автовиявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- І `browser.executablePath`, і `browser.profiles..executablePath` приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - `userDataDir` для кожного профілю `existing-session` також розгортається з тильдою. -- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). + `userDataDir` для кожного профілю в профілях `existing-session` також розгортає тильду. +- Служба керування: лише loopback (порт визначається з `gateway.port`, за замовчуванням `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, - `--disable-gpu`, розміри вікна або прапорці налагодження). + `--disable-gpu`, розмір вікна або прапорці налагодження). --- @@ -305,14 +305,14 @@ provider / base-URL перенесені на окрему сторінку — seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji, короткий текст, URL зображення або data URI }, }, } ``` -- `seamColor`: колір акценту для chrome UI нативного застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності для Control UI. Резервно використовується ідентичність активного агента. +- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення ідентичності для Control UI. Як запасний варіант використовується ідентичність активного агента. --- @@ -327,8 +327,8 @@ provider / base-URL перенесені на окрему сторінку — auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // або OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // для mode=trusted-proxy; див. /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -346,9 +346,9 @@ provider / base-URL перенесені на окрему сторінку — basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // небезпечно: дозволяє абсолютні зовнішні URL для вбудовування через http(s) + // allowedOrigins: ["https://control.example.com"], // обов’язково для не-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // небезпечний режим резервного визначення джерела через Host-заголовок // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -359,20 +359,20 @@ provider / base-URL перенесені на окрему сторінку — // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // Необов’язково. За замовчуванням false. allowRealIpFallback: false, nodes: { pairing: { - // Optional. Default unset/disabled. + // Необов’язково. За замовчуванням не задано/вимкнено. autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"], }, allowCommands: ["canvas.navigate"], denyCommands: ["system.run"], }, tools: { - // Additional /tools/invoke HTTP denies + // Додаткові HTTP-заборони для /tools/invoke deny: ["browser"], - // Remove tools from the default HTTP deny list + // Видалити інструменти зі стандартного списку HTTP-заборон allow: ["gateway"], }, push: { @@ -387,69 +387,69 @@ provider / base-URL перенесені на окрему сторінку — } ``` - + -- `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`: `auto`, `loopback` (за замовчуванням), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `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` усередині контейнера. За 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`. Потоки запуску й встановлення/відновлення служби завершуються помилкою, коли налаштовано обидва параметри, а режим не вказано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в запитах онбордингу. +- **Примітка для 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. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках початкового налаштування. - `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; 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. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожного IP клієнта й для кожної області auth (спільний секрет і token пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні некоректні спроби від того самого клієнта можуть активувати лімітер на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли ви навмисно хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих розгортань proxy). -- Спроби auth WS із походження браузера завжди обмежуються без винятку для loopback (додатковий захист від перебору localhost із браузера). -- На loopback такі блокування для походження браузера ізолюються за нормалізованим значенням `Origin`, - тож повторні невдачі з одного походження localhost не блокують автоматично +- `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 (спільний секрет і token пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому паралельні неправильні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` за замовчуванням має значення `true`; установіть `false`, якщо ви навмисно хочете застосовувати rate limit і до localhost-трафіку (для тестових налаштувань або суворих розгортань через proxy). +- Спроби WS auth із браузерного походження завжди обмежуються без винятку для loopback (захист у глибину від brute force через браузер до localhost). +- На loopback ці блокування браузерного походження ізолюються за нормалізованим значенням `Origin`, + тож повторні невдачі з одного localhost-походження не блокують автоматично інше походження. - `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний список дозволених джерел браузера для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з не-loopback джерел. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення джерела за заголовком Host для розгортань, які навмисно покладаються на політику джерела за заголовком Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення через - змінну середовища процесу, яке дозволяє незашифрований `ws://` до довірених IP - приватної мережі; типово незашифрований трафік і далі дозволено лише для loopback. Еквівалента в `openclaw.json` - немає, а конфігурація приватної мережі браузера, така як +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з не-loopback origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через Host-header для розгортань, що навмисно покладаються на політику origin на основі Host-header. +- `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`, не впливає на клієнти Gateway WebSocket. -- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS-URL-адреса зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації ними реєстрацій із relay-підтримкою до gateway. Ця URL-адреса має збігатися з URL relay, скомпільованою в збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. -- Реєстрації з relay-підтримкою делегуються конкретній ідентичності 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. URL-адреси relay у production мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски моніторингу стану. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Це значення має бути більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків моніторингу стану на канал/обліковий запис за ковзну годину. Типово: `10`. -- `channels..healthMonitor.enabled`: вимкнення на рівні каналу для перезапусків моніторингу стану за збереження глобального монітора. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо встановлено, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не встановлено. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується в закритий бік помилкою (без маскування резервним варіантом 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 для автоматичного схвалення першого спарювання пристрою Node без запитаних областей доступу. Якщо не встановлено, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення ролі, області доступу, метаданих чи публічного ключа. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування дозволу/заборони для оголошених команд вузла після спарювання та оцінювання списку дозволених. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). -- `gateway.tools.allow`: видаляє назви інструментів із типового списку заборон. +- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовується офіційними/TestFlight збірками iOS після того, як вони публікують до gateway реєстрації з підтримкою relay. Цей URL має збігатися з URL relay, скомпільованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. За замовчуванням `10000`. +- Реєстрації з підтримкою relay делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає до gateway дозвіл надсилання в межах цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення середовища для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний вихід лише для розробки для URL relay loopback HTTP. URL relay у production мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. За замовчуванням: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис за ковзну годину. За замовчуванням: `10`. +- `channels..healthMonitor.enabled`: вимкнення перезапусків монітора стану для окремого каналу зі збереженням глобального монітора. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і їх не вдається розв’язати, розв’язання завершується закритою відмовою (без маскування через резервний віддалений варіант). +- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки пересланого клієнта. Указуйте лише 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 пристрою Node без запитаних scopes. Якщо не задано, вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, scope, metadata або публічного ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд Node після pairing і перевірки списку дозволу. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює стандартний список заборон). +- `gateway.tools.allow`: вилучити назви інструментів зі стандартного списку HTTP-заборон. -### OpenAI-сумісні кінцеві точки +### Кінцеві точки, сумісні з OpenAI -- Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: за замовчуванням вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. - Посилення захисту URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні списки дозволених трактуються як невстановлені; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посилення захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-джерел, які ви контролюєте; див. [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)) ### Ізоляція кількох екземплярів @@ -481,11 +481,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла сертифіката TLS. -- `keyPath`: шлях файлової системи до файла приватного ключа TLS; обмежуйте доступ правами. -- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або нетипових ланцюжків довіри. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для local/dev використання. +- `certPath`: шлях файлової системи до файла TLS-сертифіката. +- `keyPath`: шлях файлової системи до файла приватного ключа TLS; обмежте доступ правами. +- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або власних ланцюжків довіри. ### `gateway.reload` @@ -502,12 +502,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску. - - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - - `"hot"`: застосовувати зміни в поточному процесі без перезапуску. - - `"hybrid"` (типово): спершу спробувати hot reload; за потреби перейти до перезапуску. + - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway у разі зміни конфігурації. + - `"hot"`: застосовувати зміни в процесі без перезапуску. + - `"hybrid"` (за замовчуванням): спочатку пробувати hot reload; за потреби повертатися до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском. Не вказуйте його або встановіть `0`, щоб чекати необмежено довго й періодично журналювати попередження про те, що очікування ще триває. +- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення операцій у процесі перед примусовим перезапуском. Пропустіть або встановіть `0`, щоб чекати безстроково та журналювати періодичні попередження про ще незавершені операції. --- @@ -545,37 +545,37 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Hook-token у рядку запиту відхиляються. +Токени hooks у query-string відхиляються. Примітки щодо валідації та безпеки: - `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token Gateway відхиляється. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. -- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонний `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping цього дозволу не потребують. +- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо 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`). + - `sessionKey` із тіла запиту приймається лише коли `hooks.allowRequestSessionKey=true` (за замовчуванням: `false`). - `POST /hooks/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються наданими ззовні й також вимагають `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, розглядаються як зовнішньо задані й також вимагають `hooks.allowRequestSessionKey=true`. - + -- `match.path` зіставляється з підшляхом після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). -- `match.source` зіставляється з полем тіла запиту для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають дані з тіла запиту. +- `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`. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та вихід за межі каталогу відхиляються). +- `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 (має бути дозволено, якщо задано каталог моделей). @@ -584,7 +584,7 @@ Hook-token у рядку запиту відхиляються. - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. - Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного типового значення. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного значення за замовчуванням. ```json5 { @@ -607,7 +607,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,20 +619,20 @@ Hook-token у рядку запиту відхиляються. canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // або OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Обслуговує HTML/CSS/JS, які редагує агент, і A2UI через HTTP під портом Gateway: +- Обслуговує HTML/CSS/JS, які агент може редагувати, і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Bind не-loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після спарювання та підключення вузла Gateway рекламує URL-адреси можливостей із областю Node для доступу до canvas/A2UI. -- URL-адреси можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Резервний варіант на основі IP не використовується. -- Вставляє клієнт live reload у обслуговуваний HTML. -- Автоматично створює стартовий `index.html`, якщо каталог порожній. +- Лише локально: зберігайте `gateway.bind: "loopback"` (за замовчуванням). +- Для bind не-loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки auth; після pairing і підключення node Gateway рекламує URL можливостей з областю node для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Впроваджує клієнт live reload у HTML, що обслуговується. +- Автоматично створює початковий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. - Вимкніть live reload для великих каталогів або при помилках `EMFILE`. @@ -653,9 +653,9 @@ Hook-token у рядку запиту відхиляються. } ``` -- `minimal` (типово): не включає `cliPath` + `sshPort` із TXT-записів. +- `minimal` (за замовчуванням): не включає `cliPath` + `sshPort` до TXT-записів. - `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. +- Ім’я хоста за замовчуванням — `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -667,7 +667,7 @@ Hook-token у рядку запиту відхиляються. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. +Записує unicast-зону DNS-SD до `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендується CoreDNS) + Tailscale split DNS. Налаштування: `openclaw dns setup --apply`. @@ -675,7 +675,7 @@ Hook-token у рядку запиту відхиляються. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні середовища) ```json5 { @@ -692,14 +692,14 @@ Hook-token у рядку запиту відхиляються. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли у середовищі процесу бракує цього ключа. -- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої оболонки входу. -- Див. [Environment](/uk/help/environment) для повного пріоритету. +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу бракує ключа. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. +- Повний пріоритет див. у [Environment](/uk/help/environment). -### Підстановка env-змінних +### Підстановка змінних середовища -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -709,7 +709,7 @@ Hook-token у рядку запиту відхиляються. } ``` -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. - Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. @@ -718,7 +718,7 @@ Hook-token у рядку запиту відхиляються. ## Секрети -Посилання на секрети є адитивними: прості текстові значення й надалі працюють. +Посилання на секрети є адитивними: plaintext-значення також продовжують працювати. ### `SecretRef` @@ -732,15 +732,15 @@ 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: "file"`: абсолютний вказівник JSON (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені символом `/` (наприклад, `a/../b` відхиляється) +- `id` для `source: "exec"` не повинні містити сегменти шляху, розділені `/`, у вигляді `.` або `..` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` входять до розв’язання під час виконання та покриття аудиту. +- Посилання в `auth-profiles.json` включено до розв’язання під час виконання та покриття аудиту. ### Конфігурація провайдерів секретів @@ -748,7 +748,7 @@ Hook-token у рядку запиту відхиляються. { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // необов’язковий явний env-провайдер filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -772,14 +772,14 @@ Hook-token у рядку запиту відхиляються. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). -- Шляхи провайдерів file і exec завершуються в закритий бік помилкою, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує корисні навантаження протоколу через stdin/stdout. -- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою шляху до фактично розв’язаного цільового файла. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху розв’язаного цільового файла. -- Дочірнє середовище `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`. -- Посилання на секрети розв’язуються під час активації у знімок у пам’яті, а далі шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). +- Шляхи провайдерів file і exec завершуються закритою відмовою, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які не можна перевірити. +- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout. +- За замовчуванням шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання, водночас перевіряючи шлях розв’язаного цільового об’єкта. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до шляху розв’язаного цільового об’єкта. +- Середовище дочірнього процесу `exec` за замовчуванням мінімальне; явно передавайте потрібні змінні через `passEnv`. +- Посилання на секрети розв’язуються під час активації у snapshot у пам’яті, а шляхи запитів потім читають лише цей snapshot. +- Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -801,13 +801,13 @@ 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`. +- Профілі для кожного агента зберігаються у `/auth-profiles.json`. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. +- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. +- Статичні облікові дані під час виконання надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. +- Застарілі імпорти OAuth — з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime для секретів та інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). +- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -829,20 +829,20 @@ Hook-token у рядку запиту відхиляються. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає помилки через справжні - помилки billing/недостатнього кредиту (типово: `5`). Явний текст billing усе ще - може потрапити сюди навіть для відповідей `401`/`403`, але текстові - зіставлювачі, специфічні для провайдера, залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані `402` usage-window або - повідомлення про ліміт витрат організації/робочого простору натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff billing для кожного провайдера. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff billing (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для помилок `auth_permanent` з високою впевненістю (типово: `10`). -- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли провайдер зайнятий. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок обмеження частоти перед перемиканням на резервну модель (типово: `1`). Цей кошик обмеження частоти включає текстові форми провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні + помилки білінгу/недостатнього кредиту (за замовчуванням: `5`). Явний текст про білінг + усе одно може потрапити сюди навіть для відповідей `401`/`403`, але специфічні для провайдера + зіставлювачі тексту залишаються в межах провайдера, якому вони належать (наприклад для OpenRouter + `Key limit exceeded`). Повторювані помилки використання `402` usage-window або + повідомлення про ліміт витрат організації/робочого простору натомість залишаються в гілці `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`, коли провайдер зайнятий. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок rate limit перед переходом на резервну модель (за замовчуванням: `1`). До цього кошика rate limit входить текст у стилі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -861,11 +861,11 @@ Hook-token у рядку запиту відхиляються. } ``` -- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- Файл журналу за замовчуванням: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. - `consoleLevel` підвищується до `debug` з `--verbose`. -- `maxFileBytes`: максимальний розмір активного файла журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. -- `redactSensitive` / `redactPatterns`: маскування за принципом best-effort для виводу в консоль, файлів журналу, записів журналу OTLP і збереженого тексту транскрипту сесії. +- `maxFileBytes`: максимальний розмір активного файла журналу в байтах перед ротацією (додатне ціле число; за замовчуванням: `104857600` = 100 МБ). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. +- `redactSensitive` / `redactPatterns`: маскування за принципом best-effort для виводу в консолі, файлів журналів, записів журналів OTLP і збереженого тексту транскрипту сесії. --- @@ -913,25 +913,25 @@ Hook-token у рядку запиту відхиляються. } ``` -- `enabled`: головний перемикач для виводу інструментування (типово: `true`). +- `enabled`: головний перемикач для виводу інструментування (за замовчуванням: `true`). - `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує шаблони з підстановками, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель конфіденційності див. у [OpenTelemetry export](/uk/gateway/opentelemetry). +- `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.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.sampleRate`: частота вибірки trace `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `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` для сумісності; метрики 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`: env-змінні кінцевих точок для конкретних сигналів, що використовуються, коли відповідний ключ конфігурації не встановлено. -- `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усі типово: `true`). +- `otel.captureContent`: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. За замовчуванням вимкнено. Булеве значення `true` захоплює вміст не системних повідомлень/інструментів; форма об’єкта дає змогу явно вмикати `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`: перемикач середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить плагіну, зберігаючи активними слухачі діагностики. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища для окремих кінцевих точок сигналів, які використовуються, коли відповідний ключ конфігурації не задано. +- `cacheTrace.enabled`: журналювати snapshot cache trace для вбудованих запусків (за замовчуванням: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (за замовчуванням: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі за замовчуванням: `true`). --- @@ -953,12 +953,12 @@ Hook-token у рядку запиту відхиляються. } ``` -- `channel`: канал випуску для інсталяцій npm/git — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для пакетних інсталяцій (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням на каналі stable (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання каналу stable в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки каналу beta в годинах (типово: `1`; максимум: `24`). +- `channel`: канал релізу для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (за замовчуванням: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних установлень (за замовчуванням: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (за замовчуванням: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (за замовчуванням: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (за замовчуванням: `1`; максимум: `24`). --- @@ -991,23 +991,23 @@ Hook-token у рядку запиту відхиляються. } ``` -- `enabled`: глобальний перемикач можливостей ACP (типово: `true`; установіть `false`, щоб приховати affordances dispatch і spawn ACP). -- `dispatch.enabled`: незалежний перемикач для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб залишити доступними команди ACP, але заблокувати виконання. -- `backend`: ідентифікатор типового backend runtime ACP (має відповідати зареєстрованому Plugin runtime ACP). - Якщо встановлено `plugins.allow`, включіть ідентифікатор plugin backend (наприклад `acpx`), інакше bundled типовий plugin не завантажиться. +- `enabled`: глобальний feature gate для ACP (за замовчуванням: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP). +- `dispatch.enabled`: незалежний gate для dispatch turn сесій ACP (за замовчуванням: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: ідентифікатор стандартного runtime backend ACP (має збігатися із зареєстрованим runtime plugin ACP). + Якщо встановлено `plugins.allow`, включіть ідентифікатор backend plugin (наприклад `acpx`), інакше bundled plugin за замовчуванням не завантажиться. - `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawn не вказує явну ціль. -- `allowedAgents`: список дозволених ідентифікаторів агентів для сесій runtime ACP; порожній означає відсутність додаткових обмежень. +- `allowedAgents`: список дозволених ідентифікаторів агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. - `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: вікно idle-flush у мс для потокового тексту. +- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. - `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки стану/інструментів на кожному ході (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується на хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків стану/оновлення ACP. -- `stream.tagVisibility`: запис назв тегів у перевизначення видимості подій потоків у форматі boolean. -- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до моменту, коли їх можна очищати. -- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час початкового налаштування середовища runtime ACP. +- `stream.repeatSuppression`: придушувати повторювані рядки статусу/інструментів на turn (за замовчуванням: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до terminal event turn. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (за замовчуванням: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується на turn ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. +- `stream.tagVisibility`: запис імен тегів у логічні перевизначення видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для працівників сесій ACP до моменту можливого очищення. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap runtime-середовища ACP. --- @@ -1024,10 +1024,10 @@ Hook-token у рядку запиту відхиляються. ``` - `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (типово): змінні кумедні/сезонні слогани. + - `"random"` (за замовчуванням): змінні кумедні/сезонні слогани. - `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`). - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- Щоб приховати весь банер (а не лише слогани), установіть змінну середовища `OPENCLAW_HIDE_BANNER=1`. --- @@ -1051,13 +1051,13 @@ Hook-token у рядку запиту відхиляються. ## Identity -Див. поля identity у `agents.list` в розділі [Типові значення агента](/uk/gateway/config-agents#agent-defaults). +Див. поля identity у `agents.list` в розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults). --- -## Bridge (застарілий, вилучений) +## Bridge (застаріло, видалено) -Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -1086,22 +1086,22 @@ Hook-token у рядку запиту відхиляються. cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // застарілий резервний варіант для збережених завдань notify:true + webhookToken: "replace-with-dedicated-token", // необов’язковий bearer token для вихідної auth Webhook + sessionRetention: "24h", // рядок тривалості або false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // за замовчуванням 2_000_000 байтів + keepLines: 2000, // за замовчуванням 2000 }, }, } ``` -- `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` @@ -1117,11 +1117,11 @@ Hook-token у рядку запиту відхиляються. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (за замовчуванням: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів. -Застосовується лише до одноразових завдань cron. Для повторюваних завдань використовується окрема обробка помилок. +Застосовується лише до одноразових cron-завдань. Для повторюваних завдань використовується окрема обробка помилок. ### `cron.failureAlert` @@ -1132,6 +1132,7 @@ Hook-token у рядку запиту відхиляються. enabled: false, after: 3, cooldownMs: 3600000, + includeSkipped: false, mode: "announce", accountId: "main", }, @@ -1139,10 +1140,11 @@ Hook-token у рядку запиту відхиляються. } ``` -- `enabled`: увімкнути сповіщення про помилки для завдань cron (типово: `false`). -- `after`: кількість послідовних помилок перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). +- `enabled`: увімкнути сповіщення про збої для cron-завдань (за замовчуванням: `false`). +- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook. +- `includeSkipped`: зараховувати послідовні пропущені запуски до порога сповіщення (за замовчуванням: `false`). Пропущені запуски відстежуються окремо й не впливають на backoff помилок виконання. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook. - `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -1160,51 +1162,51 @@ Hook-token у рядку запиту відхиляються. } ``` -- Типовий пункт призначення для сповіщень про помилки cron у всіх завданнях. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли достатньо даних цілі. +- Стандартне місце призначення для сповіщень про збої cron у всіх завданнях. +- `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 відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). --- -## Змінні шаблону моделі медіа +## Змінні шаблону медіамоделі -Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повний вхідний текст повідомлення | -| `{{RawBody}}` | Сире тіло повідомлення (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Тіло повідомлення без згадок групи | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Текст без згадувань групи | | `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор одержувача | +| `{{To}}` | Ідентифікатор призначення | | `{{MessageSid}}` | Ідентифікатор повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}` | `"true"`, якщо створено нову сесію | +| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіотранскрипт | -| `{{Prompt}}` | Розв’язаний медіа-prompt для записів CLI | -| `{{MaxChars}}` | Розв’язаний максимум символів виводу для записів CLI | +| `{{MediaType}}` | Тип медіа (зображення/аудіо/документ/…) | +| `{{Transcript}}` | Транскрипт аудіо | +| `{{Prompt}}` | Розв’язаний медіапромпт для записів CLI | +| `{{MaxChars}}` | Розв’язана максимальна кількість символів для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | | `{{GroupSubject}}` | Тема групи (best effort) | -| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | +| `{{GroupMembers}}` | Попередній список учасників групи (best effort) | | `{{SenderName}}` | Відображуване ім’я відправника (best effort) | | `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- -## Include конфігурації (`$include`) +## Включення конфігурації (`$include`) -Розділіть конфігурацію на кілька файлів: +Розділяйте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -1219,20 +1221,20 @@ Hook-token у рядку запиту відхиляються. **Поведінка злиття:** -- Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається за порядком (пізніші перевизначають раніші). -- Сусідні ключі: зливаються після include (перевизначають включені значення). -- Вкладені include: до 10 рівнів глибини. -- Шляхи: розв’язуються відносно файла, який включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/форми `../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї межі. -- Записи під керуванням OpenClaw, які змінюють лише один розділ верхнього рівня, підтримуваний include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Include кореня, масиви include та include із сусідніми перевизначеннями є лише для читання для записів під керуванням OpenClaw; такі записи завершуються в закритий бік помилкою замість сплощення конфігурації. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок синтаксичного аналізу та циклічних include. +- Один файл: замінює об’єкт, що його містить. +- Масив файлів: глибоко зливається по порядку (пізніші перевизначають попередні). +- Сусідні ключі: зливаються після включень (перевизначають включені значення). +- Вкладені включення: до 10 рівнів глибини. +- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в межах цієї межі. +- Записи, що належать OpenClaw і змінюють лише один розділ верхнього рівня, підтриманий включенням одного файла, записуються назад у цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі включення, масиви включень і включення з перевизначеннями сусідніх ключів доступні лише для читання для записів, що належать OpenClaw; такі записи завершуються закритою відмовою замість сплощення конфігурації. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок синтаксичного аналізу та циклічних включень. --- -_Пов’язане: [Configuration](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язано: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ ## Пов’язане - [Configuration](/uk/gateway/configuration) -- [Приклади конфігурації](/uk/gateway/configuration-examples) +- [Configuration examples](/uk/gateway/configuration-examples)