diff --git a/docs/uk/automation/index.md b/docs/uk/automation/index.md index 922e26ac5..ae55ff823 100644 --- a/docs/uk/automation/index.md +++ b/docs/uk/automation/index.md @@ -1,125 +1,125 @@ --- read_when: - - Вирішення того, як автоматизувати роботу з OpenClaw - - Вибір між Heartbeat, Cron, хуками та постійними дорученнями + - Вибір способу автоматизації роботи з OpenClaw + - Вибір між Heartbeat, Cron, хуками та постійними вказівками - Пошук правильної точки входу для автоматизації -summary: 'Огляд механізмів автоматизації: завдання, Cron, хуки, постійні доручення та TaskFlow' +summary: 'Огляд механізмів автоматизації: завдання, Cron, хуки, постійні вказівки та Task Flow' title: Автоматизація та завдання x-i18n: - generated_at: "2026-04-26T01:42:38Z" - model: gpt-5.4 + generated_at: "2026-04-29T09:13:04Z" + model: gpt-5.5 provider: openai - source_hash: 6d2a2d3ef58830133e07b34f33c611664fc1032247e9dd81005adf7fc0c43cdb + source_hash: da79bdd32a231f90850697b94bf061a778e9d0ad81420119ccd3fa0d3bc16fc1 source_path: automation/index.md - workflow: 15 + workflow: 16 --- -OpenClaw виконує роботу у фоновому режимі через завдання, заплановані завдання, хуки та постійні інструкції. Ця сторінка допоможе вам вибрати правильний механізм і зрозуміти, як вони поєднуються. +OpenClaw виконує роботу у фоні через завдання, заплановані роботи, обробники подій і постійні інструкції. Ця сторінка допоможе вибрати правильний механізм і зрозуміти, як вони працюють разом. -## Короткий посібник із вибору +## Короткий посібник для вибору ```mermaid flowchart TD - START([Що вам потрібно?]) --> Q1{Запланувати роботу?} - START --> Q2{Відстежувати відокремлену роботу?} - START --> Q3{Оркеструвати багатокрокові потоки?} - START --> Q4{Реагувати на події життєвого циклу?} - START --> Q5{Надати агенту постійні інструкції?} + START([What do you need?]) --> Q1{Schedule work?} + START --> Q2{Track detached work?} + START --> Q3{Orchestrate multi-step flows?} + START --> Q4{React to lifecycle events?} + START --> Q5{Give the agent persistent instructions?} - Q1 -->|Так| Q1a{Точний час чи гнучкий?} - Q1a -->|Точний| CRON["Заплановані завдання (Cron)"] - Q1a -->|Гнучкий| HEARTBEAT[Heartbeat] + Q1 -->|Yes| Q1a{Exact timing or flexible?} + Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"] + Q1a -->|Flexible| HEARTBEAT[Heartbeat] - Q2 -->|Так| TASKS[Фонові завдання] - Q3 -->|Так| FLOW[TaskFlow] - Q4 -->|Так| HOOKS[Хуки] - Q5 -->|Так| SO[Постійні доручення] + Q2 -->|Yes| TASKS[Background Tasks] + Q3 -->|Yes| FLOW[Task Flow] + Q4 -->|Yes| HOOKS[Hooks] + Q5 -->|Yes| SO[Standing Orders] ``` -| Випадок використання | Рекомендовано | Чому | +| Варіант використання | Рекомендовано | Чому | | --------------------------------------- | ---------------------- | ------------------------------------------------ | -| Надсилати щоденний звіт рівно о 9:00 | Заплановані завдання (Cron) | Точний час, ізольоване виконання | -| Нагадай мені через 20 хвилин | Заплановані завдання (Cron) | Одноразове виконання з точним часом (`--at`) | -| Запускати щотижневий глибокий аналіз | Заплановані завдання (Cron) | Окреме завдання, може використовувати іншу модель | -| Перевіряти вхідні кожні 30 хв | Heartbeat | Об’єднується з іншими перевірками, враховує контекст | -| Відстежувати календар для майбутніх подій | Heartbeat | Природний варіант для періодичної обізнаності | -| Перевірити стан субагента або запуску ACP | Фонові завдання | Журнал завдань відстежує всю відокремлену роботу | -| Переглянути, що виконувалося і коли | Фонові завдання | `openclaw tasks list` і `openclaw tasks audit` | -| Багатокрокове дослідження, а потім підсумок | TaskFlow | Стійка оркестрація з відстеженням ревізій | -| Запустити скрипт під час скидання сесії | Хуки | Керується подіями, спрацьовує на подіях життєвого циклу | -| Виконувати код під час кожного виклику інструмента | Plugin hooks | Внутрішньопроцесні хуки можуть перехоплювати виклики інструментів | -| Завжди перевіряти відповідність перед відповіддю | Постійні доручення | Автоматично додаються до кожної сесії | +| Надіслати щоденний звіт рівно о 9:00 | Заплановані завдання (Cron) | Точний час, ізольоване виконання | +| Нагадати мені через 20 хвилин | Заплановані завдання (Cron) | Одноразове завдання з точним часом (`--at`) | +| Запускати щотижневий глибокий аналіз | Заплановані завдання (Cron) | Самостійне завдання, може використовувати іншу модель | +| Перевіряти вхідні кожні 30 хв | Heartbeat | Об'єднується з іншими перевірками, враховує контекст | +| Моніторити календар на майбутні події | Heartbeat | Природний вибір для періодичної обізнаності | +| Переглянути стан підагенту або запуску ACP | Фонові завдання | Журнал завдань відстежує всю відокремлену роботу | +| Перевірити, що запускалося і коли | Фонові завдання | `openclaw tasks list` і `openclaw tasks audit` | +| Багатоетапне дослідження з подальшим підсумком | Task Flow | Стійка оркестрація з відстеженням ревізій | +| Запустити скрипт під час скидання сесії | Хуки | Керується подіями, спрацьовує на події життєвого циклу | +| Виконувати код під час кожного виклику інструмента | Plugin-хуки | Внутрішньопроцесні хуки можуть перехоплювати виклики інструментів | +| Завжди перевіряти відповідність перед відповіддю | Постійні розпорядження | Автоматично вставляються в кожну сесію | -### Заплановані завдання (Cron) vs Heartbeat +### Заплановані завдання (Cron) і Heartbeat -| Вимір | Заплановані завдання (Cron) | Heartbeat | +| Вимір | Заплановані завдання (Cron) | Heartbeat | | --------------- | ----------------------------------- | ------------------------------------- | -| Час | Точний (cron-вирази, одноразово) | Приблизний (типово кожні 30 хвилин) | -| Контекст сесії | Нова (ізольована) або спільна | Повний контекст основної сесії | -| Записи завдань | Завжди створюються | Ніколи не створюються | -| Доставка | Канал, Webhook або без виводу | Вбудовано в основну сесію | -| Найкраще для | Звітів, нагадувань, фонових завдань | Перевірки вхідних, календаря, сповіщень | +| Час | Точний (cron-вирази, одноразові запуски) | Приблизний (типово кожні 30 хв) | +| Контекст сесії | Новий (ізольований) або спільний | Повний контекст основної сесії | +| Записи завдань | Завжди створюються | Ніколи не створюються | +| Доставка | Канал, webhook або без виводу | Вбудовано в основну сесію | +| Найкраще для | Звітів, нагадувань, фонових робіт | Перевірок вхідних, календаря, сповіщень | -Використовуйте заплановані завдання (Cron), коли вам потрібен точний час або ізольоване виконання. Використовуйте Heartbeat, коли робота виграє від повного контексту сесії, а приблизний час є прийнятним. +Використовуйте Заплановані завдання (Cron), коли потрібен точний час або ізольоване виконання. Використовуйте Heartbeat, коли робота виграє від повного контексту сесії, а приблизний час підходить. ## Основні поняття ### Заплановані завдання (cron) -Cron — це вбудований планувальник Gateway для точного часу. Він зберігає завдання, пробуджує агента в потрібний момент і може доставляти результат у канал чату або на endpoint Webhook. Підтримує одноразові нагадування, повторювані вирази та вхідні тригери Webhook. +Cron — це вбудований планувальник Gateway для точного часу. Він зберігає роботи, пробуджує агента в потрібний момент і може доставляти вивід у чат-канал або webhook-ендпоінт. Підтримує одноразові нагадування, повторювані вирази та вхідні webhook-тригери. Див. [Заплановані завдання](/uk/automation/cron-jobs). ### Завдання -Журнал фонових завдань відстежує всю відокремлену роботу: запуски ACP, породження субагентів, ізольовані виконання cron і CLI-операції. Завдання — це записи, а не планувальники. Використовуйте `openclaw tasks list` і `openclaw tasks audit` для їх перевірки. +Журнал фонових завдань відстежує всю відокремлену роботу: запуски ACP, створення підагентів, ізольовані виконання cron і операції CLI. Завдання — це записи, а не планувальники. Використовуйте `openclaw tasks list` і `openclaw tasks audit`, щоб переглядати їх. Див. [Фонові завдання](/uk/automation/tasks). -### TaskFlow +### Task Flow -TaskFlow — це підсистема оркестрації потоків над фоновими завданнями. Вона керує стійкими багатокроковими потоками з керованими та дзеркальними режимами синхронізації, відстеженням ревізій і `openclaw tasks flow list|show|cancel` для перевірки. +Task Flow — це субстрат оркестрації потоків над фоновими завданнями. Він керує стійкими багатоетапними потоками з керованими та дзеркальними режимами синхронізації, відстеженням ревізій і `openclaw tasks flow list|show|cancel` для перегляду. -Див. [TaskFlow](/uk/automation/taskflow). +Див. [Task Flow](/uk/automation/taskflow). -### Постійні доручення +### Постійні розпорядження -Постійні доручення надають агенту постійні повноваження для визначених програм. Вони зберігаються у файлах робочого простору (зазвичай `AGENTS.md`) і додаються до кожної сесії. Поєднуйте з cron для правил, що залежать від часу. +Постійні розпорядження надають агенту постійні операційні повноваження для визначених програм. Вони зберігаються у файлах робочого простору (зазвичай `AGENTS.md`) і вставляються в кожну сесію. Поєднуйте їх із cron для примусового виконання за часом. -Див. [Постійні доручення](/uk/automation/standing-orders). +Див. [Постійні розпорядження](/uk/automation/standing-orders). ### Хуки -Внутрішні хуки — це скрипти, керовані подіями, які спрацьовують на подіях життєвого циклу агента -(`/new`, `/reset`, `/stop`), Compaction сесії, запуску gateway та потоку -повідомлень. Вони автоматично виявляються з каталогів і ними можна керувати +Внутрішні хуки — це керовані подіями скрипти, які запускаються подіями життєвого циклу агента +(`/new`, `/reset`, `/stop`), Compaction сесії, запуском gateway і потоком +повідомлень. Вони автоматично виявляються з директорій і ними можна керувати за допомогою `openclaw hooks`. Для внутрішньопроцесного перехоплення викликів інструментів використовуйте -[Plugin hooks](/uk/plugins/hooks). +[Plugin-хуки](/uk/plugins/hooks). Див. [Хуки](/uk/automation/hooks). ### Heartbeat -Heartbeat — це періодичний хід основної сесії (типово кожні 30 хвилин). Він об’єднує кілька перевірок (вхідні, календар, сповіщення) в один хід агента з повним контекстом сесії. Ходи Heartbeat не створюють записи завдань і не подовжують свіжість щоденного/неактивного скидання сесії. Використовуйте `HEARTBEAT.md` для короткого контрольного списку або блок `tasks:`, якщо вам потрібні лише ті періодичні перевірки, строк яких настав, усередині самого heartbeat. Порожні файли heartbeat пропускаються як `empty-heartbeat-file`; режим завдань лише за строком пропускається як `no-tasks-due`. +Heartbeat — це періодичний хід основної сесії (типово кожні 30 хвилин). Він об'єднує кілька перевірок (вхідні, календар, сповіщення) в один хід агента з повним контекстом сесії. Ходи Heartbeat не створюють записи завдань і не подовжують свіжість щоденного або неактивного скидання сесії. Використовуйте `HEARTBEAT.md` для невеликого контрольного списку або блок `tasks:`, коли потрібні періодичні перевірки лише за строком виконання всередині самого heartbeat. Порожні файли heartbeat пропускаються як `empty-heartbeat-file`; режим завдань лише за строком виконання пропускається як `no-tasks-due`. Heartbeat відкладаються, поки cron-робота активна або в черзі, а `heartbeat.skipWhenBusy` також може відкладати їх, поки підагент або вкладені лінії зайняті. Див. [Heartbeat](/uk/gateway/heartbeat). ## Як вони працюють разом -- **Cron** обробляє точні розклади (щоденні звіти, щотижневі огляди) та одноразові нагадування. Усі виконання cron створюють записи завдань. -- **Heartbeat** обробляє рутинний моніторинг (вхідні, календар, сповіщення) одним об’єднаним ходом кожні 30 хвилин. -- **Хуки** реагують на конкретні події (скидання сесій, Compaction, потік повідомлень) за допомогою власних скриптів. Plugin hooks охоплюють виклики інструментів. -- **Постійні доручення** надають агенту постійний контекст і межі повноважень. -- **TaskFlow** координує багатокрокові потоки поверх окремих завдань. -- **Завдання** автоматично відстежують усю відокремлену роботу, щоб ви могли її перевіряти й аудіювати. +- **Cron** обробляє точні розклади (щоденні звіти, щотижневі огляди) і одноразові нагадування. Усі виконання cron створюють записи завдань. +- **Heartbeat** обробляє регулярний моніторинг (вхідні, календар, сповіщення) в одному об'єднаному ході кожні 30 хвилин. +- **Хуки** реагують на конкретні події (скидання сесії, Compaction, потік повідомлень) за допомогою користувацьких скриптів. Plugin-хуки охоплюють виклики інструментів. +- **Постійні розпорядження** надають агенту постійний контекст і межі повноважень. +- **Task Flow** координує багатоетапні потоки над окремими завданнями. +- **Завдання** автоматично відстежують всю відокремлену роботу, щоб ви могли її переглядати й аудіювати. -## Пов’язані матеріали +## Пов'язане -- [Заплановані завдання](/uk/automation/cron-jobs) — точне планування та одноразові нагадування +- [Заплановані завдання](/uk/automation/cron-jobs) — точне планування й одноразові нагадування - [Фонові завдання](/uk/automation/tasks) — журнал завдань для всієї відокремленої роботи -- [TaskFlow](/uk/automation/taskflow) — стійка оркестрація багатокрокових потоків -- [Хуки](/uk/automation/hooks) — скрипти життєвого циклу, керовані подіями -- [Plugin hooks](/uk/plugins/hooks) — внутрішньопроцесні хуки для інструментів, промптів, повідомлень і життєвого циклу -- [Постійні доручення](/uk/automation/standing-orders) — постійні інструкції агента +- [Task Flow](/uk/automation/taskflow) — стійка оркестрація багатоетапних потоків +- [Хуки](/uk/automation/hooks) — керовані подіями скрипти життєвого циклу +- [Plugin-хуки](/uk/plugins/hooks) — внутрішньопроцесні хуки інструментів, промптів, повідомлень і життєвого циклу +- [Постійні розпорядження](/uk/automation/standing-orders) — постійні інструкції агента - [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії -- [Configuration Reference](/uk/gateway/configuration-reference) — усі ключі конфігурації +- [Довідник конфігурації](/uk/gateway/configuration-reference) — усі ключі конфігурації diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 666a99535..118904ea8 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,68 +1,182 @@ --- read_when: - - Потрібно з’ясувати, чому завдання CI було або не було запущене - - Ви діагностуєте перевірки GitHub Actions, що завершуються з помилкою -summary: Граф завдань CI, контрольні перевірки за областю та локальні еквіваленти команд -title: Конвеєр CI + - Вам потрібно зрозуміти, чому завдання CI виконалося або не виконалося + - Ви налагоджуєте перевірки GitHub Actions, які не проходять +summary: Граф завдань CI, перевірки за областю дії та локальні еквіваленти команд +title: CI-конвеєр x-i18n: - generated_at: "2026-04-29T08:15:17Z" + generated_at: "2026-04-29T09:13:01Z" model: gpt-5.5 provider: openai - source_hash: fedb986b861ed53f97cb94eecd17b94b1f49008070fb87fb0fad8848ede82fb7 + source_hash: fe934a27ac3ad314869c9a3995fb83d0fa1bda61f6e31508ce518ce601b0e3d2 source_path: ci.md workflow: 16 --- -CI запускається під час кожного push до `main` і кожного pull request. Він використовує розумне обмеження області, щоб пропускати дорогі завдання, коли зміни торкнулися лише непов’язаних ділянок. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області й розгортають повний звичайний граф CI для кандидатів на реліз або широкої перевірки, з Android-ланами, які вмикаються через `include_android` для окремих ручних запусків. Лани попереднього релізу Plugin, призначені лише для релізів, живуть в окремому workflow `Plugin Prerelease` і запускаються лише з `Full Release Validation` або явного ручного dispatch. +CI запускається під час кожного push до `main` і кожного pull request. Він використовує розумне обмеження області, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області та розгортають повний звичайний граф CI для реліз-кандидатів або широкої валідації, причому Android-лінії вмикаються через `include_android` для окремих ручних запусків. Передрелізні лінії Plugin, призначені лише для релізу, розміщені в окремому workflow `Plugin Prerelease` і запускаються лише з `Full Release Validation` або явного ручного dispatch. -Шард `check-dependencies` запускає `pnpm deadcode:dependencies`, production Knip-перевірку лише залежностей, закріплену на останній версії Knip, яку використовує цей скрипт, із вимкненим мінімальним віком релізу pnpm для встановлення `dlx`. Він блокує нові невикористані, незазначені, нерозв’язані, бінарні або каталогові залежності, не вмикаючи повний режим Knip для невикористаних файлів, який залишається ручним аудитом, оскільки OpenClaw навмисно завантажує багато Plugin і runtime-поверхонь через manifests та рядкові specifiers. +Шард `check-dependencies` запускає `pnpm deadcode:dependencies`, production-прохід Knip лише для залежностей, закріплений за найновішою версією Knip, яку використовує цей скрипт, із вимкненим мінімальним віком релізу pnpm для встановлення `dlx`. Він блокує нові невикористані, неоголошені, нерозв’язані, бінарні або каталогові залежності, не вмикаючи повний режим Knip для невикористаних файлів, який залишається ручним аудитом, оскільки OpenClaw навмисно завантажує багато Plugin і runtime-поверхонь через маніфести та рядкові специфікатори. -`Full Release Validation` — це ручний umbrella workflow для "запустити все перед релізом". Він приймає branch, tag або повний commit SHA, dispatch-ить ручний workflow `CI` з цією ціллю, dispatch-ить `Plugin Prerelease` для release-only доказу plugin/package/static/Docker, а також dispatch-ить `OpenClaw Release Checks` для install smoke, package acceptance, Docker release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram ланів. Він також може запускати post-publish workflow `NPM Telegram Beta E2E`, коли надано published package spec. `release_profile=minimum|stable|full` керує шириною live/provider, яку передають у release checks: `minimum` залишає найшвидші OpenAI/core release-critical лани, `stable` додає stable provider/backend набір, а `full` запускає широку advisory provider/media матрицю. Umbrella записує dispatched child run ids, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки child run і додає таблиці найповільніших завдань для кожного child run. Якщо child workflow перезапущено і він став green, перезапустіть лише parent verifier job, щоб оновити umbrella result і timing summary. +`Full Release Validation` — це ручний umbrella workflow для «запустити все +перед релізом». Він приймає гілку, тег або повний SHA коміту, dispatch-ить +ручний workflow `CI` із цією ціллю, dispatch-ить `Plugin Prerelease` для +релізних доказів Plugin/пакетів/статичних артефактів/Docker, а також dispatch-ить +`OpenClaw Release Checks` для install smoke, package acceptance, Docker +release-path наборів, live/E2E, OpenWebUI, паритету QA Lab, Matrix і Telegram +ліній. Він також може запускати post-publish workflow `NPM Telegram Beta E2E`, коли +надано специфікацію опублікованого пакета. `release_profile=minimum|stable|full` керує широтою live/provider, +яку передають у release checks: `minimum` залишає найшвидші OpenAI/core +релізно-критичні лінії, `stable` додає стабільний набір provider/backend, а +`full` запускає широку advisory provider/media матрицю. Umbrella записує +ідентифікатори запущених дочірніх run, а фінальне завдання `Verify full validation` повторно перевіряє +поточні висновки дочірніх run і додає таблиці найповільніших завдань для кожного дочірнього +run. Якщо дочірній workflow перезапущено і він став зеленим, перезапустіть лише батьківське +завдання verifier, щоб оновити результат umbrella і підсумок часу. -Для відновлення `Full Release Validation` і `OpenClaw Release Checks` обидва приймають `rerun_group`. Використовуйте `all` для release candidate, `ci` лише для звичайного full CI child, `release-checks` для кожного release child або вужчу release group: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` в umbrella. Це утримує rerun невдалого release box у межах після сфокусованого виправлення. +Для відновлення `Full Release Validation` і `OpenClaw Release Checks` обидва +приймають `rerun_group`. Використовуйте `all` для реліз-кандидата, `ci` лише для +звичайного повного дочірнього CI, `release-checks` для кожного дочірнього release або вужчу +релізну групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, +`qa-parity`, `qa-live` або `npm-telegram` в umbrella. Це утримує перезапуск невдалої +release box у межах після сфокусованого виправлення. -Release live/E2E child зберігає широке native покриття `pnpm test:live`, але запускає його як named shards (`native-live-src-agents`, `native-live-src-gateway-core`, provider-filtered завдання `native-live-src-gateway-profiles`, `native-live-src-gateway-backends`, `native-live-test`, `native-live-extensions-a-k`, `native-live-extensions-l-n`, `native-live-extensions-openai`, `native-live-extensions-o-z-other`, `native-live-extensions-xai`, split media audio/video shards і provider-filtered music shards) через `scripts/test-live-shard.mjs` замість одного serial job. Це зберігає те саме файлове покриття, водночас полегшуючи rerun і діагностику повільних live provider failures. Агреговані назви shards `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються дійсними для ручних one-shot reruns. +Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але +запускає його як іменовані шарди (`native-live-src-agents`, +`native-live-src-gateway-core`, відфільтровані за provider +завдання `native-live-src-gateway-profiles`, +`native-live-src-gateway-backends`, `native-live-test`, +`native-live-extensions-a-k`, `native-live-extensions-l-n`, +`native-live-extensions-openai`, `native-live-extensions-o-z-other`, +`native-live-extensions-xai`, розділені audio/video шарди media, а також +відфільтровані за provider music шарди) через `scripts/test-live-shard.mjs` замість +одного послідовного завдання. Це зберігає те саме файлове покриття, водночас спрощуючи перезапуск +і діагностику повільних live-збоїв provider. Агреговані назви шардів +`native-live-extensions-o-z`, `native-live-extensions-media` і +`native-live-extensions-media-music` залишаються дійсними для ручних +одноразових перезапусків. -Native live media shards запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, який збирає workflow `Live Media Runner Image`. Цей image попередньо встановлює `ffmpeg` і `ffprobe`; media jobs лише перевіряють binaries перед setup. Тримайте Docker-backed live suites на звичайних Blacksmith runners, бо container jobs є неправильним місцем для запуску nested Docker tests. +Нативні live media шарди запускаються в +`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow +`Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і +`ffprobe`; media-завдання лише перевіряють бінарні файли перед налаштуванням. Тримайте live-набори з підтримкою Docker +на звичайних Blacksmith runners, тому що container jobs не підходять +для запуску вкладених Docker-тестів. -Docker-backed live model/backend shards використовують окремий спільний image `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного commit. Live release workflow збирає й push-ить цей image один раз, після чого Docker live model, gateway, CLI backend, ACP bind і Codex harness shards запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Якщо ці shards незалежно перебудовують повну source Docker target, release run налаштований неправильно і марнуватиме wall clock на дубльовані image builds. +Live model/backend шарди з підтримкою Docker використовують окремий спільний +образ `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного коміту. Live +release workflow один раз збирає та публікує цей образ, після чого Docker live model, +gateway, CLI backend, ACP bind і Codex harness шарди запускаються з +`OPENCLAW_SKIP_DOCKER_BUILD=1`. Якщо ці шарди незалежно перебудовують повну source Docker +ціль, release run налаштовано неправильно, і він марнуватиме час на дубльовані збірки образів. -`OpenClaw Release Checks` використовує trusted workflow ref, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей artifact як у live/E2E release-path Docker workflow, так і в package acceptance shard. Це зберігає однакові package bytes між release boxes і уникає повторного repacking того самого candidate у кількох child jobs. +`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз розв’язати вибране +посилання в tarball `release-package-under-test`, а потім передає цей артефакт +і в live/E2E release-path Docker workflow, і в шард package acceptance. +Це підтримує однаковість байтів пакета між release boxes і уникає +повторного пакування того самого кандидата в кількох дочірніх завданнях. -`Package Acceptance` — це side-run workflow для перевірки package artifact без блокування release workflow. Він розв’язує одного candidate з published npm spec, trusted `package_ref`, зібраного за допомогою вибраного harness `workflow_ref`, HTTPS tarball URL із SHA-256 або tarball artifact з іншого GitHub Actions run, завантажує його як `package-under-test`, а потім повторно використовує Docker release/E2E scheduler із цим tarball замість repacking workflow checkout. Профілі покривають smoke, package, product, full і custom Docker lane selections. Профіль `package` використовує offline Plugin покриття, щоб перевірка published-package не залежала від live доступності ClawHub. Необов’язковий Telegram lane повторно використовує artifact `package-under-test` у workflow `NPM Telegram Beta E2E`, а шлях published npm spec збережено для standalone dispatches. +`Package Acceptance` — це side-run workflow для валідації артефакта пакета +без блокування release workflow. Він розв’язує одного кандидата з +опублікованої npm-специфікації, довіреного `package_ref`, зібраного вибраним +`workflow_ref` harness, HTTPS URL tarball із SHA-256 або tarball-артефакта +з іншого GitHub Actions run, завантажує його як `package-under-test`, а потім повторно використовує +Docker release/E2E scheduler із цим tarball замість повторного пакування +workflow checkout. Профілі охоплюють smoke, package, product, full і custom +вибір Docker-ліній. Профіль `package` використовує офлайн-покриття Plugin, щоб +валідація опублікованого пакета не залежала від доступності live ClawHub. Необов’язкова +Telegram-лінія повторно використовує артефакт +`package-under-test` у workflow `NPM Telegram Beta E2E`, а шлях +опублікованої npm-специфікації зберігається для окремих dispatch. -## Приймання package +## Приймання пакета -Використовуйте `Package Acceptance`, коли питання звучить так: "чи працює цей installable package OpenClaw як продукт?" Це відрізняється від звичайного CI: звичайний CI перевіряє source tree, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі задіюють після встановлення або оновлення. +Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальований пакет OpenClaw +як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє +дерево вихідного коду, тоді як package acceptance перевіряє один tarball через +той самий Docker E2E harness, який користувачі задіюють після встановлення або оновлення. -Workflow має чотири завдання: +Робочий процес має чотири завдання: -1. `resolve_package` checkout-ить `workflow_ref`, розв’язує одного package candidate, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як artifact `package-under-test` і друкує source, workflow ref, package ref, version, SHA-256 та profile у GitHub step summary. -2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Reusable workflow завантажує цей artifact, перевіряє tarball inventory, готує package-digest Docker images за потреби й запускає вибрані Docker lanes проти цього package замість packing workflow checkout. Коли profile вибирає кілька targeted `docker_lanes`, reusable workflow готує package і shared images один раз, а потім розгортає ці lanes як parallel targeted Docker jobs з унікальними artifacts. -3. `package_telegram` необов’язково викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не `none`, і встановлює той самий artifact `package-under-test`, коли Package Acceptance розв’язав його; standalone Telegram dispatch усе ще може встановлювати published npm spec. -4. `summary` провалює workflow, якщо package resolution, Docker acceptance або optional Telegram lane завершилися невдало. +1. `resolve_package` отримує `workflow_ref`, визначає одного кандидата пакета, + записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує + `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як + артефакт `package-under-test` і виводить джерело, workflow ref, package + ref, версію, SHA-256 та профіль у зведенні кроку GitHub. +2. `docker_acceptance` викликає + `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і + `package_artifact_name=package-under-test`. Перевикористовуваний робочий процес завантажує + цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи + package-digest і запускає вибрані Docker-напрями для цього + пакета замість пакування checkout робочого процесу. Коли профіль вибирає + кілька цільових `docker_lanes`, перевикористовуваний робочий процес готує пакет + і спільні образи один раз, а потім розгортає ці напрями як паралельні цільові Docker + завдання з унікальними артефактами. +3. `package_telegram` необов’язково викликає `NPM Telegram Beta E2E`. Він запускається, коли + `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, + коли Приймання пакета визначило один; автономний Telegram dispatch + усе ще може встановити опубліковану npm-специфікацію. +4. `summary` завершує робочий процес помилкою, якщо визначення пакета, Docker-приймання або + необов’язковий Telegram-напрям зазнали невдачі. -Джерела candidates: +Джерела кандидатів: -- `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну OpenClaw release version, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для published beta/stable acceptance. -- `source=ref`: пакує trusted `package_ref` branch, tag або full commit SHA. Resolver fetch-ить OpenClaw branches/tags, перевіряє, що вибраний commit досяжний з repository branch history або release tag, встановлює deps у detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. -- `source=url`: завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим. -- `source=artifact`: завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його варто надати для externally shared artifacts. +- `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну + версію релізу OpenClaw, як-от `openclaw@2026.4.27-beta.2`. Використовуйте це для + приймання опублікованих beta/stable. +- `source=ref`: пакує довірені гілку, тег або повний SHA коміту `package_ref`. + Розв’язувач отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт + досяжний з історії гілки репозиторію або релізного тегу, встановлює залежності у + від’єднаному worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. +- `source=url`: завантажує HTTPS `.tgz`; `package_sha256` обов’язковий. +- `source=artifact`: завантажує один `.tgz` з `artifact_run_id` і + `artifact_name`; `package_sha256` необов’язковий, але його варто надати для + артефактів, якими діляться зовні. -Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це trusted workflow/harness code, який запускає test. `package_ref` — це source commit, який пакується, коли `source=ref`. Це дає змогу поточному test harness перевіряти старіші trusted source commits без запуску старої workflow logic. +Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений +код робочого процесу/оснастки, який запускає тест. `package_ref` — це вихідний коміт, +який пакується, коли `source=ref`. Це дає змогу поточній тестовій оснастці перевіряти +старіші довірені вихідні коміти без запуску старої логіки робочого процесу. -Profiles зіставляються з Docker coverage: +Профілі відповідають Docker-покриттю: - `smoke`: `npm-onboard-channel-agent`, `gateway-network`, `config-reload` -- `package`: `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update` -- `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full`: повні Docker release-path chunks з OpenWebUI -- `custom`: точні `docker_lanes`; обов’язковий, коли `suite_profile=custom` +- `package`: `npm-onboard-channel-agent`, `doctor-switch`, + `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, + `plugin-update` +- `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, + `openai-web-search-minimal`, `openwebui` +- `full`: повні фрагменти Docker release-path з OpenWebUI +- `custom`: точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Release checks викликають Package Acceptance з `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` і `telegram_mode=mock-openai`. Release-path Docker chunks покривають overlapping package/update/plugin lanes, тоді як Package Acceptance зберігає artifact-native bundled-channel compat, offline Plugin і Telegram proof проти того самого resolved package tarball. -Cross-OS release checks усе ще покривають OS-specific onboarding, installer і platform behavior; package/update product validation має починатися з Package Acceptance. Windows packaged і installer fresh lanes також перевіряють, що встановлений package може імпортувати browser-control override із raw absolute Windows path. +Перевірки релізу викликають Приймання пакета з `source=ref`, +`package_ref=`, `workflow_ref=`, +`suite_profile=custom`, +`docker_lanes='bundled-channel-deps-compat plugins-offline'` і +`telegram_mode=mock-openai`. Docker-фрагменти release-path +покривають перетин напрямів package/update/plugin, тоді як Приймання пакета +зберігає artifact-native доказ сумісності bundled-channel, офлайн-Plugin і +Telegram для того самого визначеного tarball пакета. +Перевірки релізу Cross-OS і далі покривають специфічні для ОС onboarding, інсталятор і +поведінку платформи; перевірку продукту package/update слід починати з Приймання +пакета. Напрями Windows packaged та installer fresh також перевіряють, що +встановлений пакет може імпортувати перевизначення browser-control із сирого абсолютного +шляху Windows. -Package Acceptance має обмежені legacy-compatibility windows для вже published packages. Packages до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати compatibility path для відомих private QA entries у `dist/postinstall-inventory.json`, які вказують на tarball-omitted files, `doctor-switch` може пропустити subcase persistence `gateway install --wrapper`, коли package не exposes цей flag, `update-channel-switch` може prune відсутні `pnpm.patchedDependencies` з tarball-derived fake git fixture і може log відсутній persisted `update.channel`, plugin smokes можуть читати legacy install-record locations або приймати відсутню marketplace install-record persistence, а `plugin-update` може дозволяти config metadata migration, водночас усе ще вимагаючи, щоб install record і no-reinstall behavior лишалися unchanged. Published package `2026.4.26` також може warn щодо local build metadata stamp files, які вже були shipped. Пізніші packages мають задовольняти modern contracts; ті самі conditions завершуються failure замість warn або skip. +Приймання пакета має обмежені вікна зворотної сумісності для вже +опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, +можуть використовувати шлях сумісності для відомих приватних QA-записів у +`dist/postinstall-inventory.json`, які вказують на файли, пропущені з tarball; +`doctor-switch` може пропустити підвипадок збереження `gateway install --wrapper`, +коли пакет не надає цей прапор, `update-channel-switch` може вилучити +відсутні `pnpm.patchedDependencies` з фальшивої git-фікстури, похідної від tarball, і +може логувати відсутній збережений `update.channel`, plugin smoke-тести можуть читати +застарілі розташування install-record або приймати відсутність збереження marketplace +install-record, а `plugin-update` може дозволяти міграцію метаданих конфігурації, водночас +і далі вимагаючи, щоб запис встановлення та поведінка без перевстановлення залишалися +незмінними. Опублікований пакет `2026.4.26` також може попереджати про локальні +файли міток метаданих збірки, які вже були доставлені. Пізніші пакети мають +відповідати сучасним контрактам; ті самі умови спричиняють помилку замість попередження +або пропуску. Приклади: @@ -105,27 +219,23 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску приймання пакета починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте дочірній запуск `docker_acceptance` і його Docker-артефакти: -`.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали lane, часові показники фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних Docker lane замість повторного запуску повної валідації релізу. +Під час налагодження невдалого запуску приймання пакета починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали lanes, таймінги фаз і команди повторного запуску. Віддавайте перевагу повторному запуску невдалого профілю пакета або точних Docker lanes замість повторного запуску повної валідації релізу. -QA Lab має окремі CI lane поза основним workflow з розумною областю дії. Workflow `Parity gate` запускається для відповідних змін PR і через ручний запуск; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lane як паралельні job. Live job використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. Перевірки релізу запускають Matrix і Telegram live transport lane з детермінованим mock-провайдером і mock-qualified models (`mock-openai/gpt-5.5` та `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live-моделі та звичайного запуску provider-plugin. Live transport gateway також вимикає пошук у пам’яті, тому що QA parity окремо покриває поведінку пам’яті; підключення провайдера покривається окремими наборами live model, native provider і Docker provider. Matrix використовує `--profile fast` для запланованих і релізних gate, додаючи `--fail-fast` лише тоді, коли checkout-нутий CLI це підтримує. Стандарт CLI і ручне введення workflow залишаються `all`; ручний dispatch `matrix_profile=all` завжди розбиває повне покриття Matrix на job `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також запускає критичні для релізу QA Lab lane перед затвердженням релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane job, а потім завантажує обидва артефакти в невелику report job для фінального порівняння parity. -Не ставте шлях landing PR за `Parity gate`, якщо зміна фактично не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. -Для звичайних виправлень каналів, конфігурації, документації або unit-тестів вважайте це опційним сигналом і дотримуйтеся scoped CI/check evidence. +QA Lab має окремі CI lanes поза основним smart-scoped workflow. Workflow `Parity gate` запускається для відповідних змін у PR і manual dispatch; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 агентні пакети. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. Release checks запускають Matrix і Telegram live transport lanes з deterministic mock provider і mock-qualified models (`mock-openai/gpt-5.5` та `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live model і звичайного запуску плагіна провайдера. Live transport gateway також вимикає пошук у пам’яті, оскільки QA parity покриває поведінку пам’яті окремо; підключення провайдерів покривається окремими наборами live model, native provider і Docker provider. Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли це підтримує поточний checked-out CLI. Значення CLI за замовчуванням і manual workflow input лишаються `all`; manual `matrix_profile=all` dispatch завжди розбиває повне покриття Matrix на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також запускає release-critical QA Lab lanes перед схваленням релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane-завдання, а потім завантажує обидва артефакти в невелике report-завдання для фінального parity-порівняння. Не ставте шлях landing PR за `Parity gate`, якщо зміна насправді не зачіпає QA runtime, parity model-pack або поверхню, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit-тестів розглядайте це як необов’язковий сигнал і спирайтеся на scoped CI/check evidence. -Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів, призначений для очищення дублікатів після land. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що landed PR merged і що кожен дублікат має або спільну referenced issue, або overlapping changed hunks. +Workflow `Duplicate PRs After Merge` — це manual maintainer workflow для очищення дублікатів після landing. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landed PR об’єднано, і що кожен дублікат має або спільну referenced issue, або перетин змінених hunks. -Workflow `CodeQL` навмисно є вузьким першим проходом security scanner, а не повним sweep репозиторію. Щоденні та ручні запуски сканують код Actions workflow плюс найризикованіші JavaScript/TypeScript поверхні auth, secrets, sandbox, cron і gateway за допомогою high-precision security queries. Job channel-runtime-boundary окремо сканує core channel implementation contracts плюс channel plugin runtime, gateway, Plugin SDK, secrets і audit touchpoints у категорії `/codeql-critical-security/channel-runtime-boundary`, щоб signal безпеки каналу міг масштабуватися без розширення базової категорії JS/TS. +Workflow `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним скануванням репозиторію. Щоденні й ручні запуски сканують код Actions workflow плюс найбільш ризиковані JavaScript/TypeScript поверхні auth, secrets, sandbox, cron і gateway за допомогою high-precision security queries. Завдання channel-runtime-boundary окремо сканує контракти реалізації core channel плюс channel plugin runtime, gateway, Plugin SDK, secrets і audit touchpoints у категорії `/codeql-critical-security/channel-runtime-boundary`, щоб security-сигнал каналу міг масштабуватися без розширення базової JS/TS категорії. -Workflow `CodeQL Android Critical Security` — це запланований Android security shard. Він вручну збирає Android app для CodeQL на найменшому label Blacksmith Linux runner, прийнятому workflow sanity, і завантажує результати в категорію `/codeql-critical-security/android`. +Workflow `CodeQL Android Critical Security` — це scheduled Android security shard. Він вручну збирає Android app для CodeQL на найменшій Blacksmith Linux runner label, яку приймає workflow sanity, і завантажує результати в категорію `/codeql-critical-security/android`. -Workflow `CodeQL macOS Critical Security` — це щотижневий/ручний macOS security shard. Він вручну збирає macOS app для CodeQL на Blacksmith macOS, відфільтровує результати збірки залежностей із завантажуваного SARIF і завантажує результати в категорію `/codeql-critical-security/macos`. Тримайте його поза щоденним стандартним workflow, бо macOS build домінує runtime навіть коли чистий. +Workflow `CodeQL macOS Critical Security` — це щотижневий/manual macOS security shard. Він вручну збирає macOS app для CodeQL на Blacksmith macOS, відфільтровує результати dependency build із завантаженого SARIF і завантажує результати в категорію `/codeql-critical-security/macos`. Тримайте його поза щоденним workflow за замовчуванням, бо macOS build домінує в runtime навіть коли він clean. -Workflow `CodeQL Critical Quality` — це відповідний non-security shard. Він запускає лише JavaScript/TypeScript quality queries з error severity і безпековою тематикою вимкненою над вузькими high-value surfaces на меншому Blacksmith Linux runner. Його job core-auth-secrets сканує код auth, secrets, sandbox, cron і gateway security boundary в окремій категорії `/codeql-critical-quality/core-auth-secrets`. Job config-boundary сканує config schema, migration, normalization і IO contracts в окремій категорії `/codeql-critical-quality/config-boundary`. Job gateway-runtime-boundary сканує gateway protocol schemas і server method contracts в окремій категорії `/codeql-critical-quality/gateway-runtime-boundary`. Job channel-runtime-boundary сканує core channel implementation contracts в окремій категорії `/codeql-critical-quality/channel-runtime-boundary`. Job agent-runtime-boundary сканує command execution, model/provider dispatch, auto-reply dispatch and queues, а також ACP control-plane runtime contracts в окремій категорії `/codeql-critical-quality/agent-runtime-boundary`. Job mcp-process-runtime-boundary сканує MCP servers and tool bridges, process supervision helpers і outbound delivery contracts в окремій категорії `/codeql-critical-quality/mcp-process-runtime-boundary`. Job memory-runtime-boundary сканує memory host SDK, memory runtime facades, memory Plugin SDK aliases, memory runtime activation glue і memory doctor commands в окремій категорії `/codeql-critical-quality/memory-runtime-boundary`. Job ui-control-plane сканує Control UI bootstrap, local persistence, gateway control flows і task control-plane runtime contracts в окремій категорії `/codeql-critical-quality/ui-control-plane`. Job web-media-runtime-boundary сканує core web fetch/search, media IO, media understanding, image-generation і media-generation runtime contracts в окремій категорії `/codeql-critical-quality/web-media-runtime-boundary`. Job plugin-boundary сканує loader, registry, public-surface і Plugin SDK entrypoint contracts в окремій категорії `/codeql-critical-quality/plugin-boundary`. Тримайте workflow окремо від security, щоб quality findings можна було планувати, вимірювати, вимикати або розширювати без приховування security signal. -Розширення Swift, Python і bundled-plugin CodeQL слід додавати назад як scoped або sharded follow-up work лише після того, як вузькі профілі матимуть стабільні runtime і signal. +Workflow `CodeQL Critical Quality` — це відповідний non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries на вузьких high-value поверхнях на меншому Blacksmith Linux runner. Його завдання core-auth-secrets сканує auth, secrets, sandbox, cron і gateway security boundary code в окремій категорії `/codeql-critical-quality/core-auth-secrets`. Завдання config-boundary сканує config schema, migration, normalization і IO contracts в окремій категорії `/codeql-critical-quality/config-boundary`. Завдання gateway-runtime-boundary сканує gateway protocol schemas і server method contracts в окремій категорії `/codeql-critical-quality/gateway-runtime-boundary`. Завдання channel-runtime-boundary сканує core channel implementation contracts в окремій категорії `/codeql-critical-quality/channel-runtime-boundary`. Завдання agent-runtime-boundary сканує command execution, model/provider dispatch, auto-reply dispatch і queues, а також ACP control-plane runtime contracts в окремій категорії `/codeql-critical-quality/agent-runtime-boundary`. Завдання mcp-process-runtime-boundary сканує MCP servers і tool bridges, process supervision helpers та outbound delivery contracts в окремій категорії `/codeql-critical-quality/mcp-process-runtime-boundary`. Завдання memory-runtime-boundary сканує memory host SDK, memory runtime facades, memory Plugin SDK aliases, memory runtime activation glue і memory doctor commands в окремій категорії `/codeql-critical-quality/memory-runtime-boundary`. Завдання ui-control-plane сканує Control UI bootstrap, local persistence, gateway control flows і task control-plane runtime contracts в окремій категорії `/codeql-critical-quality/ui-control-plane`. Завдання web-media-runtime-boundary сканує core web fetch/search, media IO, media understanding, image-generation і media-generation runtime contracts в окремій категорії `/codeql-critical-quality/web-media-runtime-boundary`. Завдання plugin-boundary сканує loader, registry, public-surface і Plugin SDK entrypoint contracts в окремій категорії `/codeql-critical-quality/plugin-boundary`. Тримайте workflow окремо від security, щоб quality findings можна було планувати, вимірювати, вимикати або розширювати без затемнення security-сигналу. Розширення CodeQL для Swift, Python і bundled-plugin слід додавати назад як scoped або sharded follow-up work лише після того, як вузькі профілі матимуть стабільні runtime і signal. -Workflow `Docs Agent` — це event-driven Codex maintenance lane для підтримання наявної документації узгодженою з нещодавно landed changes. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запускати його напряму. Workflow-run invocation пропускаються, коли `main` просунувся далі або коли інший non-skipped Docs Agent run було створено за останню годину. Коли він запускається, то переглядає commit range від попереднього non-skipped Docs Agent source SHA до поточного `main`, тому один щогодинний запуск може покрити всі main changes, накопичені з часу останнього docs pass. +Workflow `Docs Agent` — це event-driven Codex maintenance lane для підтримання наявної документації узгодженою з нещодавно landing-змінами. Він не має pure schedule: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запускати його напряму. Workflow-run invocations пропускаються, коли `main` уже зрушив далі або коли інший non-skipped Docs Agent run було створено за останню годину. Коли він запускається, він переглядає діапазон комітів від попереднього non-skipped Docs Agent source SHA до поточного `main`, тож один погодинний запуск може покрити всі зміни main, накопичені з останнього docs pass. -Workflow `Test Performance Agent` — це event-driven Codex maintenance lane для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже виконувався або виконується цього UTC-дня. Manual dispatch обходить цей daily activity gate. Lane збирає full-suite grouped Vitest performance report, дозволяє Codex робити лише невеликі coverage-preserving test performance fixes замість широких refactors, потім повторно запускає full-suite report і відхиляє зміни, які зменшують passing baseline test count. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а after-agent full-suite report має пройти, перш ніж щось буде committed. Коли `main` просувається до того, як bot push lands, lane rebase-ить validated patch, повторно запускає `pnpm check:changed` і повторює push; conflicting stale patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб Codex action міг зберегти ту саму drop-sudo safety posture, що й docs agent. +Workflow `Test Performance Agent` — це event-driven Codex maintenance lane для повільних тестів. Він не має pure schedule: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже запускався або виконується цього UTC дня. Manual dispatch обходить цей daily activity gate. Lane збирає full-suite grouped Vitest performance report, дозволяє Codex вносити лише невеликі coverage-preserving test performance fixes замість широких рефакторингів, потім повторно запускає full-suite report і відхиляє зміни, що зменшують passing baseline test count. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а after-agent full-suite report має пройти перед будь-яким комітом. Коли `main` просувається до того, як bot push landing, lane rebase-ить validated patch, повторно запускає `pnpm check:changed` і повторює push; conflicting stale patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб Codex action міг зберегти ту саму drop-sudo safety posture, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -134,32 +244,32 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Огляд job +## Огляд завдань -| Job | Призначення | Коли запускається | +| Завдання | Призначення | Коли запускається | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Виявляє docs-only changes, changed scopes, changed extensions і будує CI manifest | Завжди для non-draft pushes і PRs | -| `security-scm-fast` | Виявлення private key і workflow audit через `zizmor` | Завжди для non-draft pushes і PRs | -| `security-dependency-audit` | Dependency-free production lockfile audit щодо npm advisories | Завжди для non-draft pushes і PRs | -| `security-fast` | Обов’язковий aggregate для швидких security jobs | Завжди для non-draft pushes і PRs | +| `preflight` | Виявляє docs-only changes, changed scopes, changed extensions і будує CI manifest | Завжди для non-draft pushes і PRs | +| `security-scm-fast` | Виявлення приватних ключів і audit workflow через `zizmor` | Завжди для non-draft pushes і PRs | +| `security-dependency-audit` | Dependency-free production lockfile audit щодо npm advisories | Завжди для non-draft pushes і PRs | +| `security-fast` | Обов’язковий aggregate для fast security jobs | Завжди для non-draft pushes і PRs | | `build-artifacts` | Збирає `dist/`, Control UI, built-artifact checks і reusable downstream artifacts | Node-relevant changes | -| `checks-fast-core` | Швидкі Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Node-relevant changes | +| `checks-fast-core` | Fast Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Node-relevant changes | | `checks-fast-contracts-channels` | Sharded channel contract checks зі стабільним aggregate check result | Node-relevant changes | -| `checks-node-core-test` | Core Node test shards, без channel, bundled, contract і extension lanes | Node-relevant changes | -| `check` | Sharded еквівалент main local gate: prod types, lint, guards, test types і strict smoke | Node-relevant changes | +| `checks-node-core-test` | Core Node test shards, крім channel, bundled, contract і extension lanes | Node-relevant changes | +| `check` | Sharded main local gate equivalent: prod types, lint, guards, test types і strict smoke | Node-relevant changes | | `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Node-relevant changes | | `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Node-relevant changes | | `checks` | Verifier для built-artifact channel tests | Node-relevant changes | -| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Manual CI dispatch для releases | +| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Manual CI dispatch for releases | | `check-docs` | Docs formatting, lint і broken-link checks | Docs changed | | `skills-python` | Ruff + pytest для Python-backed skills | Python-skill-relevant changes | | `checks-windows` | Windows-specific process/path tests плюс shared runtime import specifier regressions | Windows-relevant changes | -| `macos-node` | macOS TypeScript test lane з використанням shared built artifacts | macOS-relevant changes | +| `macos-node` | macOS TypeScript test lane із використанням shared built artifacts | macOS-relevant changes | | `macos-swift` | Swift lint, build і tests для macOS app | macOS-relevant changes | | `android` | Android unit tests для обох flavors плюс одна debug APK build | Android-relevant changes | -| `test-performance-agent` | Щоденна Codex slow-test optimization після trusted activity | Main CI success або manual dispatch | +| `test-performance-agent` | Daily Codex slow-test optimization після trusted activity | Main CI success або manual dispatch | -Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але примусово вмикають кожну лінію поза Android-областю: Linux Node-шарди, шарди bundled-plugin, контракти каналів, сумісність із Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python skills, Windows, macOS і Control UI i18n. Окремі ручні запуски CI виконують лише Android із `include_android=true`; повна парасолька релізу вмикає Android, передаючи `include_android=true`. Статичні перевірки попереднього випуску Plugin, лише релізний шард `agentic-plugins`, повний пакетний прогін extension і Docker-лінії попереднього випуску Plugin вилучено з CI. Набір попереднього випуску Docker виконується лише тоді, коли `Full Release Validation` запускає окремий робочий процес `Plugin Prerelease` з увімкненим шлюзом релізної валідації. Ручні запуски використовують унікальну групу конкурентності, щоб повний набір для кандидата в реліз не було скасовано іншим запуском push або PR на тому самому ref. Необов’язковий ввід `target_ref` дає змогу довіреному викликачеві виконати цей граф для гілки, тегу або повного commit SHA, використовуючи файл робочого процесу з вибраного dispatch ref. +Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але примусово вмикають кожну scoped lane, крім Android: шарди Linux Node, шарди плагінів у комплекті, контракти каналів, сумісність із Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python Skills, Windows, macOS і Control UI i18n. Окремі ручні запуски CI виконують лише Android із `include_android=true`; повна парасолька релізу вмикає Android, передаючи `include_android=true`. Статичні перевірки передрелізу Plugin, релізний шард `agentic-plugins`, повний batch sweep розширень і Docker lanes передрелізу плагінів виключені з CI. Набір передрелізних перевірок Docker запускається лише тоді, коли `Full Release Validation` запускає окремий workflow `Plugin Prerelease` з увімкненим gate перевірки релізу. Ручні запуски використовують унікальну групу concurrency, щоб повний набір release candidate не скасовувався іншим push або запуском PR на тому самому ref. Необов’язковий input `target_ref` дає змогу довіреному виклику запустити цей граф для гілки, тегу або повного SHA коміту, використовуючи файл workflow з вибраного dispatch ref. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -167,60 +277,64 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## Порядок швидкого збою +## Порядок fail-fast -Завдання впорядковано так, щоб дешеві перевірки завершувалися збоєм до запуску дорогих: +Завдання впорядковано так, щоб дешеві перевірки падали до запуску дорогих: -1. `preflight` визначає, які лінії взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються збоєм, не чекаючи на важчі завдання матриці артефактів і платформ. -3. `build-artifacts` перетинається зі швидкими Linux-лініями, щоб нижчі споживачі могли стартувати, щойно спільний build буде готовий. -4. Після цього розгалужуються важчі платформні та runtime-лінії: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи на важчі матричні завдання для артефактів і платформ. +3. `build-artifacts` перекривається зі швидкими Linux lanes, щоб downstream-споживачі могли стартувати щойно спільний build буде готовий. +4. Після цього розгалужуються важчі platform і runtime lanes: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка областей міститься в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Ручний dispatch пропускає визначення changed-scope і змушує preflight manifest діяти так, ніби змінилася кожна scoped area. -Редагування робочого процесу CI валідують граф Node CI плюс linting робочих процесів, але самі по собі не примушують збірки Windows, Android або macOS native; ці платформні лінії залишаються обмеженими змінами платформного вихідного коду. -Редагування лише маршрутизації CI, вибрані дешеві редагування core-test fixtures і вузькі редагування helper/test-routing для контрактів Plugin використовують швидкий Node-only шлях manifest: preflight, security і один task `checks-fast-core`. Цей шлях оминає build artifacts, сумісність із Node 22, контракти каналів, повні core-шарди, bundled-plugin шарди та додаткові guard-матриці, коли змінені файли обмежено поверхнями routing або helper, які швидкий task перевіряє напряму. -Windows Node-перевірки обмежені Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, конфігурацією package manager і поверхнями CI workflow, які виконують цю лінію; непов’язані зміни source, Plugin, install-smoke і test-only залишаються на Linux Node-лініях, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже перевіряють звичайні тестові шарди. -Окремий робочий процес `install-smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають fast path для Docker/package поверхонь, змін bundled plugin package/manifest, а також core plugin/channel/gateway/Plugin SDK поверхонь, які перевіряють Docker smoke jobs. Source-only зміни bundled Plugin, test-only редагування та docs-only редагування не резервують Docker workers. Fast path один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke agents delete shared-workspace, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений Docker-профіль bundled-plugin із 240-секундним aggregate command timeout, причому Docker run кожного сценарію обмежено окремо. Full path зберігає QR package install і installer Docker/update покриття для нічних scheduled runs, ручних dispatches, workflow-call release checks і pull request, які справді торкаються installer/package/Docker поверхонь. Push у `main`, включно з merge commits, не примушують full path; коли changed-scope logic запитала б full coverage на push, workflow зберігає fast Docker smoke і залишає full install smoke для nightly або release validation. Повільний Bun global install image-provider smoke окремо gated через `run_bun_global_install_smoke`; він виконується за нічним schedule і з release checks workflow, а ручні dispatches `install-smoke` можуть увімкнути його, але pull request і push у `main` його не запускають. QR і installer Docker tests зберігають власні install-focused Dockerfiles. Локальний `test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: bare Node/Git runner для installer/update/plugin-dependency ліній і functional image, який встановлює той самий tarball у `/app` для звичайних functionality ліній. Визначення Docker-ліній містяться в `scripts/lib/docker-e2e-scenarios.mjs`, planner logic міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний plan. Scheduler вибирає image для кожної lane за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lanes із `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте default main-pool slot count 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM` і provider-sensitive tail-pool slot count 10 через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження важких lanes за замовчуванням дорівнюють `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб npm install і multi-service lanes не перевантажували Docker, поки легші lanes усе ще заповнюють доступні слоти. Одна lane, важча за effective caps, усе одно може стартувати з порожнього pool, а потім виконується самостійно, доки не звільнить capacity. Старти lanes за замовчуванням рознесено на 2 секунди, щоб уникати локальних Docker daemon create storms; перевизначте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний aggregate попередньо перевіряє Docker, видаляє застарілі OpenClaw E2E containers, виводить active-lane status, зберігає lane timings для longest-first ordering і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для інспекції scheduler. За замовчуванням він припиняє планувати нові pooled lanes після першого збою, а кожна lane має 120-хвилинний fallback timeout, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lanes використовують суворіші per-lane caps. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні scheduler lanes, включно з release-only lanes, як-от `install-e2e`, і split bundled update lanes, як-от `bundled-channel-update-acpx`, пропускаючи cleanup smoke, щоб agents могли відтворити одну failed lane. Багаторазовий live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, яке package, image kind, live image, lane і credential coverage потрібне, після чого `scripts/docker-e2e.mjs` перетворює цей plan на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує package artifact із поточного запуску, або завантажує package artifact із `package_artifact_run_id`; валідує tarball inventory; збирає й пушить package-digest-tagged bare/functional GHCR Docker E2E images через Blacksmith Docker layer cache, коли plan потребує package-installed lanes; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest images замість повторної збірки. Робочий процес `Package Acceptance` є високорівневим package gate: він визначає candidate з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або попереднього workflow artifact, а потім передає цей єдиний artifact `package-under-test` у багаторазовий Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна acceptance logic могла валідувати старіші trusted commits без checkout старого workflow code. Release checks запускають custom Package Acceptance delta для target ref: bundled-channel compat, offline plugin fixtures і Telegram package QA проти resolved tarball. Release-path Docker suite запускає менші chunked jobs із `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний image kind і виконував кілька lanes через той самий weighted scheduler (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`). OpenWebUI включено в `plugins-runtime-services`, коли full release-path coverage запитує його, і він зберігає окремий chunk `openwebui` лише для OpenWebUI-only dispatches. Legacy aggregate chunk names `package-update`, `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` досі працюють для manual reruns, але release workflow використовує split chunks, щоб installer E2E і bundled plugin install/uninstall sweeps не домінували на critical path. Alias lane `install-e2e` залишається aggregate manual rerun alias для обох provider installer lanes. Chunk `bundled-channels` запускає split lanes `bundled-channel-*` і `bundled-channel-update-*`, а не serial all-in-one lane `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` з lane logs, timings, `summary.json`, `failures.json`, phase timings, scheduler plan JSON, slow-lane tables і per-lane rerun commands. Input workflow `docker_lanes` запускає вибрані lanes проти підготовлених images замість chunk jobs, що обмежує debugging failed-lane одним targeted Docker job і готує, завантажує або повторно використовує package artifact для цього run; якщо вибрана lane є live Docker lane, targeted job локально збирає live-test image для цього rerun. Згенеровані per-lane GitHub rerun commands включають `package_artifact_run_id`, `package_artifact_name` і prepared image inputs, коли ці значення існують, щоб failed lane могла повторно використати точні package і images із failed run. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker artifacts із GitHub run і надрукувати combined/per-lane targeted rerun commands; використовуйте `pnpm test:docker:timings ` для slow-lane і phase critical-path summaries. Scheduled live/E2E workflow щодня запускає full release-path Docker suite. Bundled update matrix розділено за update target, щоб повторні npm update і doctor repair passes могли шардитися з іншими bundled checks. +Логіка scope міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. +Ручний dispatch пропускає виявлення changed-scope і змушує manifest preflight діяти так, ніби кожна scoped area змінилася. +Редагування CI workflow перевіряють граф Node CI плюс workflow linting, але самі по собі не примушують запускати нативні builds Windows, Android або macOS; ці platform lanes залишаються scoped до змін у platform source. +Редагування лише маршрутизації CI, вибрані дешеві редагування core-test fixtures, а також вузькі редагування plugin contract helper/test-routing використовують швидкий шлях manifest лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях оминає build artifacts, сумісність із Node 22, контракти каналів, повні core shards, bundled-plugin shards і додаткові guard matrices, коли змінені файли обмежені routing або helper surfaces, які fast task перевіряє напряму. +Windows Node checks обмежені Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і поверхнями CI workflow, які виконують цю lane; непов’язані source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes, щоб вони не резервували 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними test shards. +Окремий workflow `install-smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke coverage на `run_fast_install_smoke` і `run_full_install_smoke`. Pull requests запускають fast path для Docker/package surfaces, змін package/manifest плагінів у комплекті, а також core plugin/channel/gateway/Plugin SDK surfaces, які перевіряють Docker smoke jobs. Source-only changes у плагінах у комплекті, test-only edits і docs-only edits не резервують Docker workers. Fast path один раз збирає image з root Dockerfile, перевіряє CLI, запускає agents delete shared-workspace CLI smoke, запускає container gateway-network e2e, перевіряє bundled extension build arg і запускає обмежений bundled-plugin Docker profile під 240-секундним aggregate command timeout, причому Docker run кожного scenario обмежений окремо. Full path зберігає QR package install і installer Docker/update coverage для нічних scheduled runs, manual dispatches, workflow-call release checks і pull requests, які справді зачіпають installer/package/Docker surfaces. Pushes у `main`, включно з merge commits, не примушують full path; коли логіка changed-scope запитала б full coverage на push, workflow залишає fast Docker smoke, а full install smoke лишає для nightly або release validation. Повільний Bun global install image-provider smoke окремо gated через `run_bun_global_install_smoke`; він запускається за nightly schedule і з workflow release checks, а manual `install-smoke` dispatches можуть opt in до нього, але pull requests і pushes у `main` його не запускають. QR і installer Docker tests зберігають власні install-focused Dockerfiles. Локальний `test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні images `scripts/e2e/Dockerfile`: bare Node/Git runner для installer/update/plugin-dependency lanes і functional image, який встановлює той самий tarball у `/app` для normal functionality lanes. Визначення Docker lanes містяться в `scripts/lib/docker-e2e-scenarios.mjs`, planner logic міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний plan. Scheduler вибирає image для кожної lane через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте default main-pool slot count 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а provider-sensitive tail-pool slot count 10 через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Heavy lane caps за замовчуванням мають значення `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб npm install і multi-service lanes не перевантажували Docker, поки легші lanes усе ще заповнюють доступні slots. Одна lane, важча за effective caps, усе ще може стартувати з порожнього pool, а потім виконується сама, доки не звільнить capacity. Запуски lanes за замовчуванням staggered на 2 секунди, щоб уникнути local Docker daemon create storms; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний aggregate preflights Docker, видаляє застарілі OpenClaw E2E containers, виводить active-lane status, зберігає lane timings для longest-first ordering і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для inspection scheduler. Він за замовчуванням припиняє планувати нові pooled lanes після першої failure, і кожна lane має 120-minute fallback timeout, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lanes використовують жорсткіші per-lane caps. `OPENCLAW_DOCKER_ALL_LANES=` запускає exact scheduler lanes, включно з release-only lanes, як-от `install-e2e`, і split bundled update lanes, як-от `bundled-channel-update-acpx`, водночас пропускаючи cleanup smoke, щоб agents могли відтворити одну failed lane. Reusable live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, яке package, image kind, live image, lane і credential coverage потрібні, а потім `scripts/docker-e2e.mjs` перетворює цей plan на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує package artifact поточного run, або завантажує package artifact із `package_artifact_run_id`; перевіряє tarball inventory; збирає й push-ить package-digest-tagged bare/functional GHCR Docker E2E images через Docker layer cache Blacksmith, коли plan потребує package-installed lanes; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або existing package-digest images замість rebuild. Workflow `Package Acceptance` є high-level package gate: він resolves candidate з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або artifact попереднього workflow, а потім передає цей єдиний artifact `package-under-test` у reusable Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна acceptance logic могла перевіряти старіші trusted commits без checkout старого workflow code. Release checks запускають custom Package Acceptance delta для target ref: bundled-channel compat, offline plugin fixtures і Telegram package QA against resolved tarball. Release-path Docker suite запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk тягнув лише потрібний image kind і виконував кілька lanes через той самий weighted scheduler (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-plugins|plugins-runtime-services|plugins-runtime-install-a|plugins-runtime-install-b|plugins-runtime-install-c|plugins-runtime-install-d|bundled-channels`). OpenWebUI включено до `plugins-runtime-services`, коли full release-path coverage цього вимагає, і він зберігає standalone chunk `openwebui` лише для OpenWebUI-only dispatches. Legacy aggregate chunk names `package-update`, `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` все ще працюють для manual reruns, але release workflow використовує split chunks, щоб installer E2E і bundled plugin install/uninstall sweeps не домінували на critical path. Alias lane `install-e2e` залишається aggregate manual rerun alias для обох provider installer lanes. Chunk `bundled-channels` запускає split lanes `bundled-channel-*` і `bundled-channel-update-*`, а не serial all-in-one lane `bundled-channel-deps`. Кожен chunk uploads `.artifacts/docker-tests/` з lane logs, timings, `summary.json`, `failures.json`, phase timings, scheduler plan JSON, slow-lane tables і per-lane rerun commands. Input workflow `docker_lanes` запускає selected lanes against prepared images замість chunk jobs, що утримує debugging failed-lane в межах одного targeted Docker job і prepares, downloads або reuses package artifact для цього run; якщо selected lane є live Docker lane, targeted job локально збирає live-test image для цього rerun. Generated per-lane GitHub rerun commands містять `package_artifact_run_id`, `package_artifact_name` і prepared image inputs, коли ці values існують, тож failed lane може повторно використати exact package і images з failed run. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker artifacts із GitHub run і вивести combined/per-lane targeted rerun commands; використовуйте `pnpm test:docker:timings ` для slow-lane і phase critical-path summaries. Scheduled live/E2E workflow щодня запускає full release-path Docker suite. Bundled update matrix розділено за update target, щоб повторні npm update і doctor repair passes могли shard з іншими bundled checks. -Поточні release Docker-фрагменти: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `plugins-runtime-install-c`, `plugins-runtime-install-d`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегований фрагмент `bundled-channels` залишається доступним для ручних одноразових повторних запусків, а `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегованими псевдонімами plugin/runtime, але release workflow використовує розділені фрагменти, щоб channel smokes, цілі оновлення, перевірки plugin runtime і повні проходи встановлення/видалення bundled plugin могли виконуватися паралельно. Цільові dispatch-и `docker_lanes` також розділяють кілька вибраних lanes на паралельні jobs після одного спільного кроку підготовки package/image, а lanes оновлення bundled-channel повторюють спробу один раз у разі тимчасових мережевих збоїв npm. +Поточні Docker-фрагменти релізу: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `plugins-runtime-install-c`, `plugins-runtime-install-d`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегований фрагмент `bundled-channels` залишається доступним для ручних одноразових повторних запусків, а `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегованими псевдонімами плагінів/runtime, але релізний workflow використовує розділені фрагменти, щоб smoke-перевірки каналів, цілі оновлення, перевірки runtime плагінів і проходи встановлення/видалення вбудованих плагінів могли виконуватися паралельно. Цільові dispatch-запуски `docker_lanes` також розділяють кілька вибраних lanes на паралельні завдання після одного спільного кроку підготовки пакета/образу, а lanes оновлення вбудованих каналів повторюються один раз у разі тимчасових мережевих збоїв npm. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широкий scope платформи CI: зміни core production запускають core prod і core test typecheck, а також core lint/guards; зміни лише в core tests запускають тільки core test typecheck і core lint; зміни extension production запускають extension prod і extension test typecheck, а також extension lint; зміни лише в extension tests запускають extension test typecheck і extension lint. Зміни публічного Plugin SDK або plugin-contract розширюються до extension typecheck, бо extensions залежать від цих core contracts, але Vitest extension sweeps є явною тестовою роботою. Version bumps лише release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни root/config безпечно переходять до всіх check lanes. -Локальна маршрутизація changed-test міститься в `scripts/test-projects.test-support.mjs` і -навмисно дешевша за `check:changed`: прямі редагування тестів запускають самі себе, -редагування source надають перевагу явним mappings, потім sibling tests і import-graph -dependents. Конфігурація доставки shared group-room є одним із явних mappings: -зміни до group visible-reply config, source reply delivery mode або -message-tool system prompt проходять через core reply tests, а також регресії доставки Discord і -Slack, щоб зміна shared default падала до першого push PR. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широкий scope CI-платформи: зміни у production-коді ядра запускають typecheck production-коду ядра і тестів ядра плюс lint/guards ядра, зміни лише в тестах ядра запускають тільки typecheck тестів ядра плюс lint ядра, зміни у production-коді extension запускають typecheck production-коду extension і тестів extension плюс lint extension, а зміни лише в тестах extension запускають typecheck тестів extension плюс lint extension. Зміни публічного Plugin SDK або контракту плагінів розширюються до typecheck extension, бо extensions залежать від цих контрактів ядра, але Vitest-проходи extension є явною тестовою роботою. Version bump-и лише релізних метаданих запускають цільові перевірки версії/конфігурації/root-залежностей. Невідомі зміни root/config безпечно переходять до всіх check lanes. +Локальний роутинг changed-test міститься в `scripts/test-projects.test-support.mjs` і +навмисно дешевший за `check:changed`: прямі зміни тестів запускають самі себе, +зміни джерел віддають перевагу явним мапінгам, потім sibling-тестам і залежним +за import-graph. Спільна конфігурація доставки group-room є одним із явних мапінгів: +зміни конфігурації visible-reply для групи, режиму доставки source reply або +системного prompt-а message-tool проходять через тести core reply плюс регресії доставки Discord і +Slack, щоб зміна спільного default падала до першого push PR. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна -настільки широка для harness, що дешевий mapped set не є надійною proxy-перевіркою. +настільки широка для harness, що дешевий mapped-набір не є надійним proxy. -Для валідації Testbox запускайте з кореня repo й надавайте перевагу свіжому прогрітому box для -широкого proof. Перед тим як витрачати повільний gate на box, який повторно використали, термін дії якого минув або -який щойно повідомив про неочікувано великий sync, спочатку запустіть `pnpm testbox:sanity` всередині -box. Sanity check швидко падає, коли обов’язкові root files, як-от -`pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 -tracked deletions. Зазвичай це означає, що remote sync state не є надійною -копією PR. Зупиніть цей box і прогрійте свіжий замість того, щоб debug-ити -product test failure. Для навмисних PR із великим видаленням установіть -`OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. +Для валідації Testbox запускайте з root репозиторію і віддавайте перевагу свіжому прогрітому box для +широкого proof. Перед тим як витрачати повільний gate на box, який було повторно використано, термін дії якого минув або +який щойно повідомив про несподівано великий sync, спочатку запустіть `pnpm testbox:sanity` всередині +box. Sanity-перевірка швидко падає, коли обов’язкові root-файли, як-от +`pnpm-lock.yaml`, зникли або коли `git status --short` показує принаймні 200 +відстежуваних видалень. Зазвичай це означає, що remote sync state не є надійною +копією PR. Зупиніть цей box і прогрійте свіжий замість того, щоб налагоджувати +падіння product test. Для PR із навмисними великими видаленнями встановіть +`OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity-запуску. `pnpm +testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у +sync-фазі понад п’ять хвилин без post-sync output. Установіть +`OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше +значення в мілісекундах для незвично великих локальних diff-ів. -Manual CI dispatches запускають `checks-node-compat-node22` як широке compatibility coverage. Android є opt-in для standalone manual CI через `include_android=true` і завжди ввімкнений для `Full Release Validation`. `Plugin Prerelease` є дорожчим product/package coverage, тому це окремий workflow, який запускає `Full Release Validation` або явний оператор. Звичайні pull requests, push-и в `main` і standalone manual CI dispatches тримають цей suite вимкненим. +Ручні CI-dispatches запускають `checks-node-compat-node22` як широке покриття сумісності. Android є opt-in для окремого ручного CI через `include_android=true` і завжди увімкнений для `Full Release Validation`. `Plugin Prerelease` є дорожчим покриттям product/package, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, push-и в `main` і окремі ручні CI-dispatches залишають цей suite вимкненим. -Найповільніші сімейства Node tests розділені або збалансовані так, щоб кожен job залишався малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit lanes поєднані в пари, auto-reply запускається як чотири balanced workers із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards, а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість спільного plugin catch-all. `Plugin Prerelease` балансує bundled plugin tests між вісьмома extension workers; ці extension shard jobs запускають до двох plugin config groups одночасно з одним Vitest worker на групу й більшим Node heap, щоб import-heavy plugin batches не створювали додаткових CI jobs. Широка agents lane використовує спільний Vitest file-parallel scheduler, бо вона домінована import/scheduling, а не одним повільним test file. `runtime-config` запускається з infra core-runtime shard, щоб shared runtime shard не володів tail. Include-pattern shards записують timing entries з використанням CI shard name, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі незалежні guards одночасно всередині одного job. Gateway watch, channel tests і core support-boundary shard запускаються одночасно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі check names як легкі verifier jobs і водночас уникаючи двох додаткових Blacksmith workers та другої artifact-consumer queue. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane усе ще компілює цей flavor із SMS/call-log BuildConfig flags, водночас уникаючи дублювання debug APK packaging job на кожному Android-relevant push. -GitHub може позначати замінені jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це CI noise, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все ще повідомляють звичайні shard failures, але не стають у queue після того, як увесь workflow уже замінено. -Автоматичний CI concurrency key версійований (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безстроково блокувати новіші main runs. Manual full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs. +Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося малим без надмірного резервування runners: контракти каналів виконуються як три weighted shards, малі core unit lanes попарно об’єднані, auto-reply запускається як чотири збалансовані workers із reply subtree, розділеним на shards agent-runner, dispatch і commands/state-routing, а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість спільного plugin catch-all. `Plugin Prerelease` балансує тести вбудованих плагінів між вісьмома extension workers; ці extension shard jobs запускають до двох plugin config groups одночасно з одним Vitest worker на group і більшим Node heap, щоб import-heavy plugin batches не створювали додаткових CI jobs. Широка agents lane використовує спільний Vitest file-parallel scheduler, бо вона dominated by import/scheduling, а не належить одному повільному тестовому файлу. `runtime-config` запускається з infra core-runtime shard, щоб спільний runtime shard не володів tail. Include-pattern shards записують timing entries з використанням імені CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі independent guards concurrently в одному job. Gateway watch, тести каналів і core support-boundary shard виконуються concurrently всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі check names як lightweight verifier jobs і водночас уникаючи двох додаткових Blacksmith workers і другої artifact-consumer queue. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює цей flavor із SMS/call-log BuildConfig flags, уникаючи дубльованого debug APK packaging job на кожному Android-relevant push. +GitHub може позначати superseded jobs як `cancelled`, коли новіший push потрапляє в той самий PR або `main` ref. Вважайте це CI-шумом, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все одно повідомляють нормальні shard failures, але не стають у queue після того, як увесь workflow уже був superseded. +Автоматичний CI concurrency key versioned (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безстроково блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs. ## Runners | Runner | Jobs | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі security jobs і aggregates (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled checks, sharded channel contract checks, shards `check`, крім lint, shards і aggregates `check-additional`, Node test aggregate verifiers, docs checks, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла раніше стати в queue | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, нижчі за вагою extension shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` | +| `ubuntu-24.04` | `preflight`, швидкі security jobs і aggregates (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled checks, sharded channel contract checks, `check` shards окрім lint, `check-additional` shards і aggregates, Node test aggregate verifiers, docs checks, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла ставати в queue раніше | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, lower-weight extension shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` | | `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node test shards, bundled plugin test shards, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо CPU-sensitive, щоб 8 vCPU коштували більше, ніж заощаджували; install-smoke Docker builds, де 32-vCPU queue time коштував більше, ніж заощаджував | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо CPU-sensitive, що 8 vCPU коштували більше, ніж заощаджували; install-smoke Docker builds, де 32-vCPU queue time коштував більше, ніж заощаджував | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; forks fallback до `macos-latest` | | `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; forks fallback до `macos-latest` | diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index 4eb97b596..a66e52fe4 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,28 +1,28 @@ --- read_when: - Налаштування типових параметрів агента (моделі, мислення, робочий простір, Heartbeat, медіа, Skills) - - Налаштування багатоагентної маршрутизації та прив’язок - - Налаштування сеансу, доставлення повідомлень і поведінки режиму розмови -summary: Типові параметри агента, багатоагентна маршрутизація, сесія, повідомлення та конфігурація розмови + - Налаштування мультиагентної маршрутизації та прив’язок + - Налаштування сеансів, доставлення повідомлень і поведінки режиму розмови +summary: Типові параметри агента, маршрутизація між кількома агентами, сеанс, повідомлення та конфігурація розмови title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-28T11:10:40Z" + generated_at: "2026-04-29T09:13:06Z" model: gpt-5.5 provider: openai - source_hash: a664de6b9abf629f31b55927b73610896cf86dafd57cf6708ebbbc9c5e188a0d + source_hash: 0b093332d62836f3564f248e67e68b058777d84f78e8f1e99ab258f44839c400 source_path: gateway/config-agents.md workflow: 16 --- -Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`, +Ключі конфігурації на рівні агента в `agents.*`, `multiAgent.*`, `session.*`, `messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших -ключів верхнього рівня див. [Довідник конфігурації](/uk/gateway/configuration-reference). +ключів верхнього рівня див. [довідник із конфігурації](/uk/gateway/configuration-reference). -## Стандартні налаштування агента +## Типові значення агента ### `agents.defaults.workspace` -За замовчуванням: `~/.openclaw/workspace`. +Типове значення: `~/.openclaw/workspace`. ```json5 { @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, показаний у рядку Runtime системного промпта. Якщо не задано, OpenClaw автоматично визначає його, рухаючись угору від робочої області. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного промпта. Якщо не задано, OpenClaw автоматично визначає його, рухаючись вгору від робочої області. ```json5 { @@ -42,7 +42,7 @@ x-i18n: ### `agents.defaults.skills` -Необов’язковий стандартний список дозволених Skills для агентів, які не задають +Необов’язковий типовий список дозволених Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -58,11 +58,11 @@ x-i18n: } ``` -- Пропустіть `agents.defaults.skills`, щоб Skills за замовчуванням були без обмежень. -- Пропустіть `agents.list[].skills`, щоб успадкувати стандартні значення. -- Задайте `agents.list[].skills: []`, щоб вимкнути Skills. +- Не вказуйте `agents.defaults.skills`, щоб Skills за замовчуванням були необмежені. +- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. +- Задайте `agents.list[].skills: []`, щоб Skills не було. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він - не об’єднується зі стандартними значеннями. + не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` @@ -76,10 +76,10 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочої області вставляються в системний промпт. За замовчуванням: `"always"`. +Керує тим, коли bootstrap-файли робочої області вставляються в системний промпт. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вставлення bootstrap-файлів робочої області, зменшуючи розмір промпта. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. -- `"never"`: вимикає bootstrap робочої області та вставлення файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю контролюють власний життєвий цикл промпта (користувацькі рушії контексту, нативні середовища виконання, що будують власний контекст, або спеціалізовані workflow без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають вставлення. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вставлення bootstrap робочої області, зменшуючи розмір промпта. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"never"`: вимикає bootstrap робочої області та вставлення контекстних файлів на кожному ході. Використовуйте це лише для агентів, які повністю керують власним життєвим циклом промпта (власні рушії контексту, нативні середовища виконання, що будують власний контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають вставлення. ```json5 { @@ -89,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на bootstrap-файл робочої області до обрізання. За замовчуванням: `12000`. +Максимальна кількість символів на один bootstrap-файл робочої області до обрізання. Типове значення: `12000`. ```json5 { @@ -99,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів робочої області. За замовчуванням: `60000`. +Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів робочої області. Типове значення: `60000`. ```json5 { @@ -110,10 +110,10 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` Керує текстом попередження, видимим агенту, коли bootstrap-контекст обрізано. -За замовчуванням: `"once"`. +Типове значення: `"once"`. - `"off"`: ніколи не вставляти текст попередження в системний промпт. -- `"once"`: вставляти попередження один раз для кожної унікальної сигнатури обрізання (рекомендовано). +- `"once"`: вставляти попередження один раз для кожного унікального підпису обрізання (рекомендовано). - `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. ```json5 @@ -122,25 +122,25 @@ x-i18n: } ``` -### Карта власності бюджетів контексту +### Карта відповідальності за бюджет контексту OpenClaw має кілька великих бюджетів промпта/контексту, і вони -навмисно розділені за підсистемами, а не всі проходять через один універсальний -регулятор. +навмисно розділені за підсистемами, а не проходять через один універсальний +параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне вставлення bootstrap-файлів робочої області. + звичайне вставлення bootstrap робочої області. - `agents.defaults.startupContext.*`: - одноразова преамбула запуску моделі під час reset/startup, включно з останніми щоденними - файлами `memory/*.md`. Команди чату `/new` і `/reset` без додаткового тексту + одноразова прелюдія запуску моделі під час скидання/старту, зокрема нещодавні щоденні + файли `memory/*.md`. Команди звичайного чату `/new` і `/reset` підтверджуються без виклику моделі. - `skills.limits.*`: - компактний список Skills, що вставляється в системний промпт. + компактний список Skills, вставлений у системний промпт. - `agents.defaults.contextLimits.*`: - обмежені фрагменти середовища виконання та вставлені блоки, якими володіє runtime. + обмежені фрагменти середовища виконання та вставлені блоки, якими володіє середовище виконання. - `memory.qmd.limits.*`: - розмір фрагмента індексованого пошуку в пам’яті та вставлення. + розмір фрагмента індексованого пошуку пам’яті та вставлення. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -150,9 +150,9 @@ OpenClaw має кілька великих бюджетів промпта/ко #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, що вставляється під час запусків моделі reset/startup. -Команди чату `/new` і `/reset` без додаткового тексту підтверджують reset без виклику -моделі, тому вони не завантажують цю преамбулу. +Керує стартовою прелюдією першого ходу, що вставляється під час запусків моделі після скидання/старту. +Команди звичайного чату `/new` і `/reset` підтверджують скидання без виклику +моделі, тому вони не завантажують цю прелюдію. ```json5 { @@ -173,7 +173,7 @@ OpenClaw має кілька великих бюджетів промпта/ко #### `agents.defaults.contextLimits` -Спільні стандартні значення для обмежених поверхонь runtime-контексту. +Спільні типові значення для обмежених поверхонь контексту середовища виконання. ```json5 { @@ -190,18 +190,18 @@ OpenClaw має кілька великих бюджетів промпта/ко } ``` -- `memoryGetMaxChars`: стандартна межа фрагмента `memory_get` до додавання +- `memoryGetMaxChars`: типове обмеження фрагмента `memory_get` до додавання метаданих обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: стандартне вікно рядків `memory_get`, коли `lines` - пропущено. -- `toolResultMaxChars`: межа результатів live-інструментів, що використовується для збережених результатів і +- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` + опущено. +- `toolResultMaxChars`: обмеження результатів живих інструментів, що використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: межа фрагмента AGENTS.md, що використовується під час вставлення +- `postCompactionMaxChars`: обмеження фрагмента AGENTS.md, що використовується під час вставлення оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних регуляторів `contextLimits`. Пропущені поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Опущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -228,8 +228,8 @@ OpenClaw має кілька великих бюджетів промпта/ко #### `skills.limits.maxSkillsPromptChars` -Глобальна межа для компактного списку Skills, що вставляється в системний промпт. Це -не впливає на читання файлів `SKILL.md` на вимогу. +Глобальне обмеження для компактного списку Skills, вставленого в системний промпт. Це +не впливає на читання файлів `SKILL.md` за запитом. ```json5 { @@ -262,11 +262,11 @@ OpenClaw має кілька великих бюджетів промпта/ко ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. -За замовчуванням: `1200`. +Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/інструментів перед викликами провайдера. +Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скриншотів. -Більші значення зберігають більше візуальних деталей. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скриншотів. +Вищі значення зберігають більше візуальних деталей. ```json5 { @@ -276,7 +276,7 @@ OpenClaw має кілька великих бюджетів промпта/ко ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного промпта (не для timestamp повідомлень). Повертається до часового поясу хоста. +Часовий пояс для контексту системного промпта (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -286,7 +286,7 @@ OpenClaw має кілька великих бюджетів промпта/ко ### `agents.defaults.timeFormat` -Формат часу в системному промпті. За замовчуванням: `auto` (налаштування ОС). +Формат часу в системному промпті. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -345,55 +345,55 @@ OpenClaw має кілька великих бюджетів промпта/ко - `model`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - Рядкова форма задає лише основну модель. - - Об'єктна форма задає основну модель плюс упорядковані резервні моделі для перемикання у разі збою. + - Об'єктна форма задає основну модель і впорядковані моделі резервного перемикання. - `imageModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати зображення на вході. + - Використовується шляхом інструмента `image` як його конфігурація візійної моделі. + - Також використовується як резервна маршрутизація, коли вибрана/стандартна модель не може приймати вхідні зображення. - Надавайте перевагу явним посиланням `provider/model`. Голі ідентифікатори приймаються для сумісності; якщо голий ідентифікатор однозначно відповідає налаштованому запису з підтримкою зображень у `models.providers.*.models`, OpenClaw уточнює його до цього провайдера. Неоднозначні налаштовані збіги потребують явного префікса провайдера. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal, `openai/gpt-image-2` для OpenAI Images або `openai/gpt-image-1.5` для виводу OpenAI PNG/WebP із прозорим фоном. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/плагіна, що генерує зображення. + - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal, `openai/gpt-image-2` для OpenAI Images або `openai/gpt-image-1.5` для виводу OpenAI PNG/WebP із прозорим тлом. - Якщо ви вибираєте провайдера/модель напряму, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` для `fal/*`). - - Якщо пропущено, `image_generate` усе одно може визначити типове значення провайдера, підкріпленого автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. + - Якщо пропущено, `image_generate` все одно може вивести стандартного провайдера з наявною автентифікацією. Спершу він пробує поточного стандартного провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдера. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.6`. - - Якщо пропущено, `music_generate` усе одно може визначити типове значення провайдера, підкріпленого автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. + - Якщо пропущено, `music_generate` все одно може вивести стандартного провайдера з наявною автентифікацією. Спершу він пробує поточного стандартного провайдера, потім решту зареєстрованих провайдерів генерації музики у порядку ідентифікаторів провайдера. - Якщо ви вибираєте провайдера/модель напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо пропущено, `video_generate` усе одно може визначити типове значення провайдера, підкріпленого автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. + - Якщо пропущено, `video_generate` все одно може вивести стандартного провайдера з наявною автентифікацією. Спершу він пробує поточного стандартного провайдера, потім решту зареєстрованих провайдерів генерації відео у порядку ідентифікаторів провайдера. - Якщо ви вибираєте провайдера/модель напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера. - - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалості 10 секунд і параметрів рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об'єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо пропущено, інструмент PDF повертається до `imageModel`, а потім до розв'язаної моделі сеансу/типової моделі. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує резервний режим видобування в інструменті `pdf`. -- `verboseDefault`: типовий рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`. -- `elevatedDefault`: типовий рівень розширеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо пропустити провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка для сумісності, тож надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першої налаштованої пари провайдер/модель замість показу застарілого типового значення видаленого провайдера. -- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`). - - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи allowlist, якщо не передати `--replace`. - - Потоки налаштування/onboarding у межах провайдера об'єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих непов'язаних провайдерів. + - Якщо пропущено, інструмент PDF відкочується до `imageModel`, потім до розв'язаної моделі сеансу/стандартної моделі. +- `pdfMaxBytesMb`: стандартний ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: стандартна максимальна кількість сторінок, яку враховує резервний режим витягування в інструменті `pdf`. +- `verboseDefault`: стандартний рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Стандартно: `"off"`. +- `elevatedDefault`: стандартний рівень підвищеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Стандартно: `"on"`. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви пропускаєте провайдера, OpenClaw спершу пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього відкочується до налаштованого стандартного провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану стандартну модель, OpenClaw відкочується до першого налаштованого провайдера/моделі замість показу застарілого стандартного значення видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених моделей для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`). + - Безпечні редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи. `config set` відхиляє заміни, які видалили б наявні записи зі списку дозволених, якщо ви не передасте `--replace`. + - Потоки налаштування/онбордингу в межах провайдера зливають вибрані моделі провайдера в цю мапу та зберігають уже налаштованих непов'язаних провайдерів. - Для прямих моделей OpenAI Responses серверна Compaction вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити ін'єкцію `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [серверну Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об'єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), потім `agents.list[].params` (відповідний ідентифікатор агента) перевизначає за ключем. Докладніше див. [Кешування промптів](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений наскрізний JSON, що об'єднується в тіла запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, додаткове тіло має пріоритет; ненативні маршрути completions після цього все одно вилучають специфічний для OpenAI `store`. -- `params.chat_template_kwargs`: аргументи чат-шаблону, сумісні з vLLM/OpenAI, що об'єднуються в тіла запитів верхнього рівня `api: "openai-completions"`. Для `vllm/nemotron-3-*` із вимкненим мисленням вбудований Plugin vLLM автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true`; явні `chat_template_kwargs` перевизначають згенеровані типові значення, а `extra_body.chat_template_kwargs` усе ще має остаточний пріоритет. Для елементів керування мисленням vLLM Qwen задайте `params.qwenThinkingFormat` як `"chat-template"` або `"top-level"` у записі цієї моделі. -- `params.preserveThinking`: опційне ввімкнення лише для Z.AI для збереженого мислення. Коли ввімкнено і мислення активне, OpenClaw надсилає `thinking.clear_thinking: false` і відтворює попередній `reasoning_content`; див. [мислення Z.AI і збережене мислення](/uk/providers/zai#thinking-and-preserved-thinking). -- `agentRuntime`: типова низькорівнева політика runtime агента. Пропущений ідентифікатор типово означає OpenClaw Pi. Використовуйте `id: "pi"`, щоб примусово застосувати вбудований PI harness, `id: "auto"`, щоб дозволити зареєстрованим Plugin harnesses заявляти підтримувані моделі, зареєстрований ідентифікатор harness, як-от `id: "codex"`, або підтримуваний псевдонім CLI backend, як-от `id: "claude-cli"`. Задайте `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Явні Plugin runtimes, як-от `codex`, типово завершуються закрито, якщо не задати `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі канонічними як `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші execution backends через конфігурацію runtime замість застарілих префіксів runtime-провайдерів. Див. [Runtime агентів](/uk/concepts/agent-runtimes), щоб зрозуміти відмінність від вибору провайдера/моделі. -- Засоби запису конфігурації, що змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну об'єктну форму та за можливості зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізується). Типово: 4. +- `params`: глобальні стандартні параметри провайдера, застосовані до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), потім `agents.list[].params` (відповідний ідентифікатор агента) перевизначає за ключем. Див. [кешування промптів](/uk/reference/prompt-caching) для подробиць. +- `params.extra_body`/`params.extraBody`: розширений наскрізний JSON, що зливається в тіла запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, додаткове тіло має перевагу; ненативні маршрути completions все одно після цього прибирають OpenAI-специфічний `store`. +- `params.chat_template_kwargs`: OpenAI-сумісні аргументи шаблону чату vLLM, що зливаються в тіла запитів верхнього рівня `api: "openai-completions"`. Для `vllm/nemotron-3-*` з вимкненим мисленням вбудований Plugin vLLM автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true`; явні `chat_template_kwargs` перевизначають згенеровані стандартні значення, а `extra_body.chat_template_kwargs` все одно має остаточний пріоритет. Для керування мисленням Qwen vLLM задайте `params.qwenThinkingFormat` як `"chat-template"` або `"top-level"` у цьому записі моделі. +- `params.preserveThinking`: увімкнення лише для Z.AI для збереженого мислення. Коли ввімкнено й мислення активне, OpenClaw надсилає `thinking.clear_thinking: false` і повторно відтворює попередній `reasoning_content`; див. [мислення Z.AI і збережене мислення](/uk/providers/zai#thinking-and-preserved-thinking). +- `agentRuntime`: стандартна низькорівнева політика середовища виконання агента. Пропущений ідентифікатор за замовчуванням означає OpenClaw Pi. Використовуйте `id: "pi"`, щоб примусово ввімкнути вбудоване середовище PI, `id: "auto"`, щоб дозволити зареєстрованим середовищам плагінів заявляти підтримувані моделі, зареєстрований ідентифікатор середовища, як-от `id: "codex"`, або підтримуваний псевдонім бекенду CLI, як-от `id: "claude-cli"`. Задайте `fallback: "none"`, щоб вимкнути автоматичний відкат до PI. Явні середовища виконання Plugin, як-от `codex`, за замовчуванням завершуються закрито, якщо ви не задасте `fallback: "pi"` в тій самій області перевизначення. Зберігайте посилання на моделі канонічними як `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію середовища виконання замість застарілих префіксів провайдера середовища. Див. [середовища виконання агентів](/uk/concepts/agent-runtimes), щоб дізнатися, чим це відрізняється від вибору провайдера/моделі. +- Автори конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну об'єктну форму та за можливості зберігають наявні списки резервних варіантів. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізований). Стандартно: 4. ### `agents.defaults.agentRuntime` -`agentRuntime` керує тим, який низькорівневий executor виконує ходи агента. Більшість -розгортань мають залишати типовий runtime OpenClaw Pi. Використовуйте його, коли довірений -Plugin надає нативний harness, наприклад вбудований harness app-server Codex, -або коли потрібен підтримуваний CLI backend, як-от Claude CLI. Ментальну -модель див. у [Runtime агентів](/uk/concepts/agent-runtimes). +`agentRuntime` керує тим, який низькорівневий виконавець запускає ходи агента. Більшість +розгортань мають залишати стандартне середовище виконання OpenClaw Pi. Використовуйте його, коли довірений +Plugin надає нативний harness, як-от вбудований harness Codex app-server, +або коли потрібен підтримуваний CLI-бекенд, наприклад Claude CLI. Для ментальної +моделі див. [Середовища виконання агентів](/uk/concepts/agent-runtimes). ```json5 { @@ -409,18 +409,18 @@ Plugin надає нативний harness, наприклад вбудован } ``` -- `id`: `"auto"`, `"pi"`, ідентифікатор зареєстрованого Plugin harness або підтримуваний псевдонім CLI backend. Вбудований Plugin Codex реєструє `codex`; вбудований Plugin Anthropic надає CLI backend `claude-cli`. -- `fallback`: `"pi"` або `"none"`. У `id: "auto"` пропущене резервне значення типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не заявляє запуск. У режимі явного Plugin runtime, як-от `id: "codex"`, пропущене резервне значення типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість тихого використання PI. Перевизначення runtime не успадковують fallback із ширшої області; задавайте `fallback: "pi"` поруч із явним runtime, коли навмисно потрібен цей резервний перехід для сумісності. Збої вибраного Plugin harness завжди показуються напряму. +- `id`: `"auto"`, `"pi"`, id зареєстрованого Plugin harness або підтримуваний псевдонім CLI-бекенда. Вбудований Codex Plugin реєструє `codex`; вбудований Anthropic Plugin надає CLI-бекенд `claude-cli`. +- `fallback`: `"pi"` або `"none"`. У `id: "auto"` пропущений fallback за замовчуванням має значення `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не бере запуск на себе. У явному режимі Plugin runtime, як-от `id: "codex"`, пропущений fallback за замовчуванням має значення `"none"`, щоб відсутній harness спричиняв помилку, а не мовчки використовував PI. Перевизначення runtime не успадковують fallback із ширшої області; задайте `fallback: "pi"` поруч із явним runtime, коли навмисно хочете цей fallback для сумісності. Збої вибраного Plugin harness завжди показуються напряму. - Перевизначення середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає fallback для цього процесу. -- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `agentRuntime.id: "codex"`. Також можна явно задати `agentRuntime.fallback: "none"` для читабельності; це типове значення для явних Plugin runtimes. -- Для розгортань Claude CLI надавайте перевагу `model: "anthropic/claude-opus-4-7"` плюс `agentRuntime.id: "claude-cli"`. Застарілі посилання на модель `claude-cli/claude-opus-4-7` усе ще працюють для сумісності, але нова конфігурація має зберігати вибір провайдера/моделі канонічним і розміщувати execution backend у `agentRuntime.id`. -- Старі ключі політики runtime переписуються в `agentRuntime` командою `openclaw doctor --fix`. -- Вибір harness закріплюється за ідентифікатором сеансу після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сеанси, а не на наявний transcript. Застарілі сеанси з історією transcript, але без записаного закріплення, вважаються закріпленими за PI. `/status` повідомляє ефективний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. -- Це керує лише виконанням текстових ходів агента. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування провайдера/моделі. +- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `agentRuntime.id: "codex"`. Також можна явно задати `agentRuntime.fallback: "none"` для читабельності; це значення за замовчуванням для явних Plugin runtimes. +- Для розгортань Claude CLI віддавайте перевагу `model: "anthropic/claude-opus-4-7"` разом із `agentRuntime.id: "claude-cli"`. Застарілі посилання на моделі `claude-cli/claude-opus-4-7` і далі працюють для сумісності, але нова конфігурація має залишати вибір provider/model канонічним і поміщати бекенд виконання в `agentRuntime.id`. +- Старі ключі runtime-policy переписуються в `agentRuntime` за допомогою `openclaw doctor --fix`. +- Вибір harness закріплюється за id сесії після першого вбудованого запуску. Зміни конфігурації/env впливають на нові або скинуті сесії, а не на наявний transcript. Застарілі сесії з історією transcript, але без записаного закріплення, вважаються закріпленими за PI. `/status` повідомляє фактичний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише виконанням текстових ходів агента. Генерація медіа, vision, PDF, music, video і TTS і далі використовують свої налаштування provider/model. **Вбудовані скорочення псевдонімів** (застосовуються лише коли модель є в `agents.defaults.models`): -| Псевдонім | Модель | +| Псевдонім | Модель | | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -431,11 +431,11 @@ Plugin надає нативний harness, наприклад вбудован | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. +Налаштовані вами псевдоніми завжди мають перевагу над типовими значеннями. -Моделі Z.AI GLM-4.x автоматично вмикають режим мислення, якщо не задати `--thinking off` або самостійно не визначити `agents.defaults.models["zai/"].params.thinking`. -Моделі Z.AI типово вмикають `tool_stream` для потокового передавання викликів інструментів. Задайте `agents.defaults.models["zai/"].params.tool_stream` як `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типово використовується `adaptive` мислення, коли не задано явний рівень мислення. +Моделі Z.AI GLM-4.x автоматично вмикають режим мислення, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI типово вмикають `tool_stream` для потокового передавання викликів інструментів. Щоб вимкнути це, задайте `agents.defaults.models["zai/"].params.tool_stream` значення `false`. +Моделі Anthropic Claude 4.6 типово використовують `adaptive` мислення, коли явний рівень мислення не задано. ### `agents.defaults.cliBackends` @@ -468,13 +468,13 @@ Plugin надає нативний harness, наприклад вбудован } ``` -- Бекенди CLI насамперед текстові; інструменти завжди вимкнено. +- Бекенди CLI передусім текстові; інструменти завжди вимкнені. - Сесії підтримуються, коли задано `sessionArg`. -- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Наскрізне передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь зібраний OpenClaw системний промпт фіксованим рядком. Задайте на рівні типових значень (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із промптами. +Замінює весь системний промпт, зібраний OpenClaw, фіксованим рядком. Задається на рівні типових значень (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із промптами. ```json5 { @@ -488,7 +488,7 @@ Plugin надає нативний harness, наприклад вбудован ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладання промптів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише дружнім шаром стилю взаємодії. +Незалежні від провайдера накладки промптів, застосовані за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки в різних провайдерів; `personality` керує лише дружнім шаром стилю взаємодії. ```json5 { @@ -506,7 +506,7 @@ Plugin надає нативний harness, наприклад вбудован - `"friendly"` (типово) і `"on"` вмикають дружній шар стилю взаємодії. - `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застарілий `plugins.entries.openai.config.personality` досі читається, коли цей спільний параметр не задано. +- Застаріле `plugins.entries.openai.config.personality` досі читається, коли це спільне налаштування не задано. ### `agents.defaults.heartbeat` @@ -523,6 +523,7 @@ Plugin надає нативний harness, наприклад вбудован includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes session: "main", to: "+15555550123", directPolicy: "allow", // allow (default) | block @@ -538,14 +539,15 @@ Plugin надає нативний harness, наприклад вбудован ``` - `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація API-ключем) або `1h` (автентифікація OAuth). Задайте `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли false, опускає розділ Heartbeat із системного промпта та пропускає вставлення `HEARTBEAT.md` у bootstrap-контекст. Типово: `true`. +- `includeSystemPromptSection`: коли false, вилучає розділ Heartbeat із системного промпта та пропускає ін’єкцію `HEARTBEAT.md` у початковий контекст. Типово: `true`. - `suppressToolErrorWarnings`: коли true, пригнічує попереджувальні payload-и про помилки інструментів під час запусків Heartbeat. - `timeoutSeconds`: максимальний час у секундах, дозволений для ходу агента Heartbeat, перш ніж його буде перервано. Не задавайте, щоб використовувати `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика доставлення прямих повідомлень/DM. `allow` (типово) дозволяє доставлення прямій цілі. `block` пригнічує доставлення прямій цілі та виводить `reason=dm-blocked`. -- `lightContext`: коли true, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `isolatedSession`: коли true, кожен Heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі 100K до 2–5K токенів. +- `directPolicy`: політика доставки напряму/DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та виводить `reason=dm-blocked`. +- `lightContext`: коли true, запуски Heartbeat використовують полегшений початковий контекст і зберігають лише `HEARTBEAT.md` із файлів початкового завантаження робочої області. +- `isolatedSession`: коли true, кожен Heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat із ~100K до ~2-5K токенів. +- `skipWhenBusy`: коли true, запуски Heartbeat відкладаються за додаткових зайнятих ліній: робота субагента або вкладених команд. Лінії Cron завжди відкладають Heartbeat, навіть без цього прапорця. - Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, Heartbeat запускають **лише ці агенти**. -- Heartbeat виконують повні ходи агента — коротші інтервали витрачають більше токенів. +- Heartbeat запускають повні ходи агента — коротші інтервали витрачають більше токенів. ### `agents.defaults.compaction` @@ -580,18 +582,18 @@ Plugin надає нативний harness, наприклад вбудован } ``` -- `mode`: `default` або `safeguard` (порційне підсумовування для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: ідентифікатор зареєстрованого Plugin провайдера Compaction. Коли задано, викликається `summarize()` провайдера замість вбудованого підсумовування LLM. У разі помилки повертається до вбудованого варіанта. Задання провайдера примусово встановлює `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `mode`: `default` або `safeguard` (фрагментоване узагальнення для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `provider`: ідентифікатор зареєстрованого плагіна провайдера Compaction. Коли задано, замість вбудованого LLM-узагальнення викликається `summarize()` провайдера. У разі збою повертається до вбудованого варіанта. Задання провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). - `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, перш ніж OpenClaw її перерве. Типово: `900`. -- `keepRecentTokens`: бюджет точки відсікання Pi для дослівного збереження найновішого хвоста транскрипту. Ручний `/compact` враховує це, коли значення задано явно; інакше ручна Compaction є жорсткою контрольною точкою. -- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає на початок вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. -- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`. -- `qualityGuard`: перевірки з повторною спробою для некоректно сформованого виводу в підсумках safeguard. Увімкнено типово в режимі safeguard; задайте `enabled: false`, щоб пропустити аудит. -- `postCompactionSections`: необов’язкові назви H2/H3-розділів AGENTS.md для повторного вставлення після Compaction. Типово `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вставлення. Коли не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий запасний варіант. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction мають виконуватися на іншій; коли не задано, Compaction використовує основну модель сесії. -- `maxActiveTranscriptBytes`: необов’язковий байтовий поріг (`number` або рядки на кшталт `"20mb"`), який запускає звичайну локальну Compaction перед запуском, коли активний JSONL перевищує поріг. Потребує `truncateAfterCompaction`, щоб успішна Compaction могла перейти на менший наступний транскрипт. Вимкнено, коли не задано або дорівнює `0`. -- `notifyUser`: коли `true`, надсилає користувачу короткі сповіщення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction була безшумною. -- `memoryFlush`: безшумний агентний хід перед автоматичною Compaction для збереження тривалих спогадів. Задайте `model` як точний provider/model, наприклад `ollama/qwen3:8b`, коли цей службовий хід має залишатися на локальній моделі; перевизначення не успадковує fallback-ланцюжок активної сесії. Пропускається, коли робочий простір доступний лише для читання. +- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найновішого хвоста транскрипта дослівно. Ручний `/compact` враховує це, коли задано явно; інакше ручна Compaction є жорсткою контрольною точкою. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає на початок вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час узагальнення Compaction. +- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `qualityGuard`: перевірки з повторною спробою при некоректно сформованому виводі для safeguard-узагальнень. Типово ввімкнено в режимі safeguard; задайте `enabled: false`, щоб пропустити аудит. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md для повторної ін’єкції після Compaction. Типово `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторну ін’єкцію. Коли не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для узагальнення Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а узагальнення Compaction мають виконуватися на іншій; коли не задано, Compaction використовує основну модель сесії. +- `maxActiveTranscriptBytes`: необов’язковий поріг у байтах (`number` або рядки на кшталт `"20mb"`), який запускає звичайну локальну Compaction перед запуском, коли активний JSONL перевищує поріг. Потребує `truncateAfterCompaction`, щоб успішна Compaction могла перейти на менший наступний транскрипт. Вимкнено, коли не задано або дорівнює `0`. +- `notifyUser`: коли `true`, надсилає користувачу короткі повідомлення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction відбувалася без повідомлень. +- `memoryFlush`: тихий агентний хід перед автоматичною Compaction для збереження довготривалих спогадів. Задайте `model` як точний provider/model, наприклад `ollama/qwen3:8b`, коли цей сервісний хід має залишатися на локальній моделі; перевизначення не успадковує ланцюжок резервних моделей активної сесії. Пропускається, коли робоча область доступна лише для читання. ### `agents.defaults.contextPruning` @@ -617,10 +619,10 @@ Plugin надає нативний harness, наприклад вбудован } ``` - + - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього звернення до кешу). - Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. **М’яке скорочення** зберігає початок + кінець і вставляє `...` посередині. @@ -629,13 +631,13 @@ Plugin надає нативний harness, наприклад вбудован Примітки: -- Блоки зображень ніколи не скорочуються/очищаються. -- Коефіцієнти базуються на символах (приблизно), а не на точній кількості токенів. +- Блоки зображень ніколи не скорочуються й не очищуються. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. - Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Деталі поведінки див. у [Скорочення сесії](/uk/concepts/session-pruning). +Див. [Обрізання сесії](/uk/concepts/session-pruning) для подробиць поведінки. ### Блокове потокове передавання @@ -657,7 +659,7 @@ Plugin надає нативний harness, наприклад вбудован - Перевизначення каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Signal/Slack/Discord/Google Chat типово мають `minChars: 1500`. - `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Деталі поведінки та поділу на фрагменти див. у [Потокове передавання](/uk/concepts/streaming). +Див. [Потокове передавання](/uk/concepts/streaming) для подробиць поведінки та фрагментації. ### Індикатори набору @@ -672,7 +674,7 @@ Plugin надає нативний harness, наприклад вбудован } ``` -- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. +- Типово: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. - Перевизначення для окремої сесії: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Індикатори набору](/uk/concepts/typing-indicators). @@ -681,7 +683,7 @@ Plugin надає нативний harness, наприклад вбудован ### `agents.defaults.sandbox` -Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Ізоляція](/uk/gateway/sandboxing). +Необов’язкова ізоляція в sandbox для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -778,48 +780,48 @@ Plugin надає нативний harness, наприклад вбудован -**Бекенд:** +**Backend:** - `docker`: локальне середовище виконання Docker (типово) -- `ssh`: універсальне віддалене середовище виконання на основі SSH +- `ssh`: універсальне віддалене середовище виконання на базі SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, параметри, специфічні для середовища виконання, переміщуються до +Коли вибрано `backend: "openshell"`, специфічні для середовища виконання налаштування переміщуються до `plugins.entries.openshell.config`. -**Конфігурація SSH-бекенда:** +**Конфігурація SSH-бекенду:** -- `target`: ціль SSH у форматі `user@host[:port]` +- `target`: ціль SSH у формі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) - `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах кожної області - `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує в тимчасові файли під час виконання -- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хостів OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет автентифікації SSH:** -- `identityData` має пріоритет над `identityFile` -- `certificateData` має пріоритет над `certificateFile` -- `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef розв’язуються з активного знімка середовища виконання секретів до запуску сесії пісочниці +- `identityData` має перевагу над `identityFile` +- `certificateData` має перевагу над `certificateFile` +- `knownHostsData` має перевагу над `knownHostsFile` +- значення `*Data` на базі SecretRef розв’язуються з активного знімка середовища виконання секретів до запуску сесії пісочниці -**Поведінка SSH-бекенда:** +**Поведінка SSH-бекенду:** -- одноразово засіває віддалений робочий простір після створення або повторного створення +- одноразово заповнює віддалений робочий простір після створення або повторного створення - потім зберігає віддалений робочий простір SSH канонічним -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH +- маршрутизує `exec`, файлові інструменти й медіашляхи через SSH - не синхронізує віддалені зміни назад на хост автоматично - не підтримує контейнери браузера пісочниці **Доступ до робочого простору:** -- `none`: робочий простір пісочниці для кожної області під `~/.openclaw/sandboxes` +- `none`: робочий простір пісочниці для кожної області в `~/.openclaw/sandboxes` - `ro`: робочий простір пісочниці в `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` - `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` **Область:** -- `session`: окремий контейнер і робочий простір для кожної сесії +- `session`: контейнер і робочий простір для кожної сесії - `agent`: один контейнер і робочий простір на агента (типово) - `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) @@ -851,29 +853,29 @@ Plugin надає нативний harness, наприклад вбудован **Режим OpenShell:** -- `mirror`: засіває віддалене середовище з локального перед exec, синхронізує назад після exec; локальний робочий простір залишається канонічним -- `remote`: засіває віддалене середовище один раз під час створення пісочниці, потім зберігає віддалений робочий простір канонічним +- `mirror`: заповнювати віддалений простір із локального перед exec, синхронізувати назад після exec; локальний робочий простір лишається канонічним +- `remote`: одноразово заповнити віддалений простір під час створення пісочниці, потім зберігати віддалений робочий простір канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються до пісочниці автоматично після етапу засівання. -Транспортом є SSH у пісочницю OpenShell, але Plugin керує життєвим циклом пісочниці та необов’язковою дзеркальною синхронізацією. +У режимі `remote` локальні для хоста зміни, зроблені поза OpenClaw, не синхронізуються в пісочницю автоматично після кроку заповнення. +Транспортом є SSH у пісочницю OpenShell, але Plugin керує життєвим циклом пісочниці й необов’язковою дзеркальною синхронізацією. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореня з правом запису та користувача root. +**`setupCommand`** запускається один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореневої файлової системи з можливістю запису та користувача root. -**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або власну мостову мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо явно не встановити -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний обхід). +**Для контейнерів типово використовується `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний виняток). **Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремих агентів об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Браузер у пісочниці** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний промпт. Не потребує `browser.enabled` в `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає короткоживучий URL із токеном (замість розкриття пароля в спільному URL). +**Пісочниця браузера** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний промпт. Не потребує `browser.enabled` в `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає короткочасний URL із токеном (замість розкриття пароля в спільному URL). -- `allowHostControl: false` (типово) блокує сесії в пісочниці від націлювання на браузер хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена мостова мережа). Установлюйте `bridge` лише тоді, коли явно потрібне глобальне мостове підключення. -- `cdpSourceRange` необов’язково обмежує вхід CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера пісочниці. Коли задано (включно з `[]`), замінює `docker.binds` для контейнера браузера. +- `allowHostControl: false` (типово) блокує сесіям у пісочниці можливість націлюватися на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. +- `cdpSourceRange` необов’язково обмежує вхід CDP на межі контейнера діапазоном CIDR (наприклад, `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера пісочниці. Коли встановлено (включно з `[]`), це замінює `docker.binds` для контейнера браузера. - Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` @@ -893,37 +895,37 @@ Plugin надає нативний harness, наприклад вбудован - `--metrics-recording-only` - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово ввімкнено, і їх можна вимкнути за допомогою + увімкнено типово; їх можна вимкнути за допомогою `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо це потрібно для використання WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` повторно вмикає розширення, якщо ваш робочий процес залежить від них. - `--renderer-process-limit=2` можна змінити за допомогою - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати - типове обмеження процесів Chromium. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове + обмеження процесів Chromium. - плюс `--no-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовим рівнем образу контейнера; використовуйте власний образ браузера з власною + - Типові значення є базовими для образу контейнера; використовуйте власний образ браузера з власною точкою входу, щоб змінити типові значення контейнера. -Пісочниця браузера та `sandbox.docker.binds` працюють лише з Docker. +Пісочниця браузера й `sandbox.docker.binds` доступні лише для Docker. -Збирання образів: +Зібрати образи: ```bash scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` -### `agents.list` (перевизначення для окремих агентів) +### `agents.list` (перевизначення для окремого агента) -Використовуйте `agents.list[].tts`, щоб надати агенту власного провайдера TTS, голос, модель, -стиль або режим автоматичного TTS. Блок агента глибоко зливається поверх глобального -`messages.tts`, тому спільні облікові дані можуть залишатися в одному місці, а окремі -агенти перевизначають лише потрібні їм поля голосу або провайдера. Перевизначення активного агента +Використовуйте `agents.list[].tts`, щоб надати агенту власного постачальника TTS, голос, модель, +стиль або режим автоматичного TTS. Блок агента глибоко об’єднується поверх глобального +`messages.tts`, тож спільні облікові дані можуть залишатися в одному місці, а окремі +агенти перевизначають лише потрібні їм поля голосу або постачальника. Перевизначення активного агента застосовується до автоматичних озвучених відповідей, `/tts audio`, `/tts status` і -інструмента агента `tts`. Див. [Синтез мовлення](/uk/tools/tts#per-agent-voice-overrides) -для прикладів провайдерів і пріоритетності. +інструмента агента `tts`. Див. [Перетворення тексту на мовлення](/uk/tools/tts#per-agent-voice-overrides) +для прикладів постачальників і пріоритету. ```json5 { @@ -978,27 +980,27 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: стабільний ідентифікатор агента (обов’язково). -- `default`: коли задано кілька, перший має перевагу (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. -- `model`: рядкова форма задає строгий основний model для окремого агента без fallback model; об’єктна форма `{ primary }` також є строгою, якщо не додати `fallbacks`. Використовуйте `{ primary, fallbacks: [...] }`, щоб увімкнути fallback для цього агента, або `{ primary, fallbacks: [] }`, щоб явно задати строгу поведінку. Cron-завдання, які перевизначають лише `primary`, усе ще успадковують типові fallback, якщо не задати `fallbacks: []`. -- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису model в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу model. -- `tts`: необов’язкові перевизначення text-to-speech для окремого агента. Блок глибоко об’єднується поверх `messages.tts`, тому зберігайте спільні облікові дані провайдера та політику fallback у `messages.tts`, а тут задавайте лише специфічні для персони значення, як-от provider, voice, model, style або auto mode. -- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли його задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень мислення для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. Вибраний профіль провайдера/model визначає, які значення допустимі; для Google Gemini `adaptive` зберігає динамічне мислення, кероване провайдером (`thinkingLevel` пропущено в Gemini 3/3.1, `thinkingBudget: -1` у Gemini 2.5). -- `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast-mode для окремого повідомлення або сесії. -- `agentRuntime`: необов’язкове низькорівневе перевизначення політики runtime для окремого агента. Використовуйте `{ id: "codex" }`, щоб зробити одного агента лише Codex, тоді як інші агенти зберігають типовий PI fallback у режимі `auto`. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має за замовчуванням використовувати сесії ACP harness. -- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. +- `default`: коли задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим буде перший запис списку. +- `model`: рядкова форма задає сувору основну модель для окремого агента без резервної моделі; об’єктна форма `{ primary }` також сувора, якщо не додати `fallbacks`. Використайте `{ primary, fallbacks: [...] }`, щоб увімкнути резервні варіанти для цього агента, або `{ primary, fallbacks: [] }`, щоб явно вказати сувору поведінку. Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні варіанти, якщо не задати `fallbacks: []`. +- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `tts`: необов’язкові перевизначення перетворення тексту на мовлення для окремого агента. Блок глибоко об’єднується поверх `messages.tts`, тож зберігайте спільні облікові дані провайдера та політику резервування в `messages.tts`, а тут задавайте лише значення, специфічні для персони, як-от провайдера, голос, модель, стиль або автоматичний режим. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли його задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень мислення для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення є дійсними; для Google Gemini `adaptive` зберігає динамічне мислення, кероване провайдером (`thinkingLevel` пропущено в Gemini 3/3.1, `thinkingBudget: -1` у Gemini 2.5). +- `reasoningDefault`: необов’язкова типова видимість міркування для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення міркування для окремого повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, коли не задано перевизначення швидкого режиму для окремого повідомлення або сесії. +- `agentRuntime`: необов’язкове низькорівневе перевизначення політики середовища виконання для окремого агента. Використайте `{ id: "codex" }`, щоб зробити одного агента лише Codex, тоді як інші агенти зберігатимуть типовий резервний PI у режимі `auto`. +- `runtime`: необов’язковий дескриптор середовища виконання для окремого агента. Використайте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії ACP harness. +- `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: allowlist ідентифікаторів агентів для явних цілей `sessions_spawn.agentId` (`["*"]` = будь-який; типово: лише той самий агент). Додайте ідентифікатор запитувача, коли self-targeted виклики `agentId` мають бути дозволені. -- Запобіжник успадкування sandbox: якщо сесія запитувача sandboxed, `sessions_spawn` відхиляє цілі, які запускалися б unsandboxed. -- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, які пропускають `agentId` (примушує явний вибір профілю; типово: false). +- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для явних цілей `sessions_spawn.agentId` (`["*"]` = будь-який; типово: лише той самий агент). Додайте ідентифікатор запитувача, коли потрібно дозволити самоспрямовані виклики `agentId`. +- Захист успадкування пісочниці: якщо сесію запитувача ізольовано в пісочниці, `sessions_spawn` відхиляє цілі, які запускалися б без пісочниці. +- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, які пропускають `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація з кількома агентами -Запускайте кілька ізольованих агентів в одному Gateway. Див. [Кілька агентів](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1017,11 +1019,11 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Поля зіставлення прив’язки -- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній type типово означає route), `acp` для сталих прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній тип типово означає route), `acp` для сталих прив’язок розмов ACP. - `match.channel` (обов’язково) - `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) - `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок зіставлення:** @@ -1030,16 +1032,16 @@ scripts/sandbox-browser-setup.sh # optional browser image 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний, без peer/guild/team) -5. `match.accountId: "*"` (у межах усього каналу) +5. `match.accountId: "*"` (для всього каналу) 6. Типовий агент -У межах кожного рівня перший відповідний запис `bindings` має перевагу. +У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw виконує resolve за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding. +Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки маршруту. ### Профілі доступу для окремих агентів - + ```json5 { @@ -1057,7 +1059,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1086,7 +1088,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1132,7 +1134,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -Подробиці про пріоритети див. у [пісочниці та інструментах для кількох агентів](/uk/tools/multi-agent-sandbox-tools). +Див. [Багатоагентна пісочниця та інструменти](/uk/tools/multi-agent-sandbox-tools) для деталей пріоритетності. --- @@ -1182,37 +1184,37 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групових чатів. - - `per-sender` (за замовчуванням): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). -- **`dmScope`**: як групуються особисті повідомлення. - - `main`: усі особисті повідомлення спільно використовують головну сесію. - - `per-peer`: ізоляція за ідентифікатором відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатокористувацьких скриньок вхідних повідомлень). +- **`scope`**: базова стратегія групування сесій для контекстів групового чату. + - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст є навмисним). +- **`dmScope`**: спосіб групування приватних повідомлень. + - `main`: усі приватні повідомлення спільно використовують основну сесію. + - `per-peer`: ізоляція за id відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для скриньок вхідних повідомлень із кількома користувачами). - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: зіставляє канонічні ідентифікатори з пірами з префіксом провайдера для спільного використання сесій між каналами. Команди стикування, як-от `/dock_discord`, використовують те саме зіставлення, щоб перемкнути маршрут відповіді активної сесії на інший пов’язаний пір каналу; див. [стикування каналів](/uk/concepts/channel-docking). -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за локальним часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що настає першим. Свіжість щоденного скидання використовує `sessionStartedAt` рядка сесії; свіжість скидання за бездіяльністю використовує `lastInteractionAt`. Фонові записи та записи системних подій, як-от Heartbeat, пробудження Cron, сповіщення `exec` і службові записи Gateway, можуть оновлювати `updatedAt`, але вони не підтримують свіжість щоденних або неактивних сесій. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення відгалуженої сесії потоку (за замовчуванням `100000`). - - Якщо батьківський `totalTokens` перевищує це значення, OpenClaw запускає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. - - Установіть `0`, щоб вимкнути цей запобіжник і завжди дозволяти відгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного контейнера прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість взаємних ходів відповіді між агентами під час обмінів агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. +- **`identityLinks`**: зіставляє канонічні id із вузлами з префіксом провайдера для спільного використання сесій між каналами. Команди докування, як-от `/dock_discord`, використовують те саме зіставлення, щоб перемкнути маршрут відповіді активної сесії на інший пов’язаний вузол каналу; див. [Докування каналів](/uk/concepts/channel-docking). +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Коли налаштовано обидва варіанти, спрацьовує той, що завершується першим. Актуальність щоденного скидання використовує `sessionStartedAt` рядка сесії; актуальність скидання за простоєм використовує `lastInteractionAt`. Фонові/системні записи подій, як-от Heartbeat, пробудження Cron, сповіщення exec і службовий облік Gateway, можуть оновлювати `updatedAt`, але вони не підтримують актуальність сесій daily/idle. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії потоку (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. +- **`mainKey`**: застаріле поле. Під час виконання для основного кошика прямого чату завжди використовується `"main"`. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповідей між агентами під час обмінів агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. - **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сесій + керування зберіганням. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: віковий поріг для застарілих записів (за замовчуванням `30d`). - - `maxEntries`: максимальна кількість записів у `sessions.json` (за замовчуванням `500`). Runtime записує пакетне очищення з невеликим буфером верхнього порога для лімітів виробничого розміру; `openclaw sessions cleanup --enforce` застосовує ліміт негайно. - - `rotateBytes`: застаріло та ігнорується; `openclaw doctor --fix` видаляє його зі старіших конфігурацій. - - `resetArchiveRetention`: зберігання архівів транскриптів `*.reset.`. За замовчуванням дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий дисковий бюджет каталогу сесій. У режимі `warn` він записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення бюджету. За замовчуванням дорівнює `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні значення за замовчуванням для функцій сесій, прив’язаних до потоків. - - `enabled`: головний перемикач за замовчуванням (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: автоматичне зняття фокусу за замовчуванням після бездіяльності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: жорсткий максимальний вік за замовчуванням у годинах (`0` вимикає; провайдери можуть перевизначати) +- **`maintenance`**: очищення сховища сесій + елементи керування збереженням. + - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. + - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). + - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). Під час виконання пакетне очищення записується з невеликим буфером верхнього рівня для лімітів виробничого розміру; `openclaw sessions cleanup --enforce` застосовує ліміт негайно. + - `rotateBytes`: застаріле й ігнорується; `openclaw doctor --fix` видаляє його зі старіших конфігурацій. + - `resetArchiveRetention`: термін збереження архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий дисковий бюджет каталогу сесій. У режимі `warn` записує попередження до журналу; у режимі `enforce` спершу видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово дорівнює `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для можливостей сесій, прив’язаних до потоків. + - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) + - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1250,36 +1252,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Розв’язання (найконкретніше має перевагу): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Визначення (найконкретніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ----------------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | -| `{thinkingLevel}` | Поточний рівень мислення | `high`, `low`, `off` | -| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) | +| Змінна | Опис | Приклад | +| ----------------- | ---------------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | +| `{provider}` | Назва провайдера | `anthropic` | +| `{thinkingLevel}` | Поточний рівень міркування | `high`, `low`, `off` | +| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) | -Змінні не чутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. +Змінні не залежать від регістру. `{think}` є псевдонімом для `{thinkingLevel}`. ### Реакція підтвердження -- За замовчуванням використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для каналів: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок розв’язання: обліковий запис → канал → `messages.ackReaction` → резерв ідентичності. +- За замовчуванням використовується `identity.emoji` активного агента, інакше `"👀"`. Задайте `""`, щоб вимкнути. +- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення ідентичності. - Область дії: `group-mentions` (за замовчуванням), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді в каналах, що підтримують реакції, як-от Slack, Discord, Telegram, WhatsApp і BlueBubbles. +- `removeAckAfterReply`: прибирає підтвердження після відповіді в каналах, що підтримують реакції, як-от Slack, Discord, Telegram, WhatsApp і BlueBubbles. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо значення не задано, реакції статусу лишаються ввімкненими, коли активні реакції підтвердження. - У Telegram явно встановіть `true`, щоб увімкнути реакції статусу життєвого циклу. + У Slack і Discord незадане значення залишає реакції статусу ввімкненими, коли активні реакції підтвердження. + У Telegram задайте його явно як `true`, щоб увімкнути реакції статусу життєвого циклу. -### Дебаунсинг вхідних повідомлень +### Дебаунс вхідних повідомлень -Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення надсилаються негайно. Керівні команди обходять дебаунсинг. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення надсилаються негайно. Керівні команди обходять дебаунс. ### TTS (перетворення тексту на мовлення) @@ -1329,19 +1331,19 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує стандартним режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує ефективний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. -- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням має значення `false` (явне ввімкнення). -- Ключі API використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- Вбудовані провайдери мовлення належать Plugin. Якщо встановлено `plugins.allow`, додайте кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий ідентифікатор провайдера `edge` приймається як псевдонім для `microsoft`. -- `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок розв’язання: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `providers.openai.baseUrl` вказує на кінцеву точку, що не належить OpenAI, OpenClaw трактує її як OpenAI-сумісний сервер TTS і послаблює перевірку моделі/голосу. +- `auto` керує стандартним автоматичним режимом TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує ефективний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного резюме. +- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням має значення `false` (потрібне явне увімкнення). +- API-ключі використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, додайте кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий ідентифікатор провайдера `edge` приймається як псевдонім для `microsoft`. +- `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `providers.openai.baseUrl` вказує на кінцеву точку не OpenAI, OpenClaw розглядає її як OpenAI-сумісний сервер TTS і послаблює перевірку моделі/голосу. --- -## Розмова +## Talk -Значення за замовчуванням для режиму розмови (macOS/iOS/Android). +Значення за замовчуванням для режиму Talk (macOS/iOS/Android). ```json5 { @@ -1370,16 +1372,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів розмови. -- Застарілі пласкі ключі розмови (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) існують лише для сумісності та автоматично мігруються в `talk.providers.`. -- Ідентифікатори голосів використовують резервне значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає рядки відкритим текстом або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли ключ API для розмови не налаштовано. -- `providers.*.voiceAliases` дає змогу директивам розмови використовувати зручні назви. -- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовує локальний допоміжний MLX для macOS. Якщо пропущено, macOS використовує `mlx-community/Soprano-80M-bf16`. -- Відтворення MLX у macOS працює через вбудований допоміжний `openclaw-mlx-tts`, коли він наявний, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до допоміжного засобу для розробки. -- `speechLocale` задає ідентифікатор локалі BCP 47, який використовується розпізнаванням мовлення для розмови в iOS/macOS. Не задавайте значення, щоб використовувати стандарт пристрою. -- `silenceTimeoutMs` керує тим, як довго режим розмови чекає після тиші користувача, перш ніж надсилати стенограму. Якщо не задано, зберігається стандартне вікно паузи платформи (`700 ms on macOS and Android, 900 ms on iOS`). +- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. +- Voice ID використовують резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. +- `providers.*.voiceAliases` дає директивам Talk використовувати дружні назви. +- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовує локальний помічник MLX на macOS. Якщо пропущено, macOS використовує `mlx-community/Soprano-80M-bf16`. +- Відтворення macOS MLX виконується через вбудований помічник `openclaw-mlx-tts`, коли він присутній, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. +- `speechLocale` задає ідентифікатор локалі BCP 47, який використовується розпізнаванням мовлення Talk на iOS/macOS. Залиште незаданим, щоб використовувати стандартне значення пристрою. +- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після мовчання користувача, перш ніж надіслати транскрипт. Незадане значення зберігає стандартне вікно паузи платформи (`700 ms on macOS and Android, 900 ms on iOS`). --- diff --git a/docs/uk/gateway/heartbeat.md b/docs/uk/gateway/heartbeat.md index c80b04987..b2c823aef 100644 --- a/docs/uk/gateway/heartbeat.md +++ b/docs/uk/gateway/heartbeat.md @@ -1,46 +1,46 @@ --- read_when: - - Налаштування частоти Heartbeat або обміну повідомленнями + - Налаштування частоти Heartbeat або повідомлень - Вибір між Heartbeat і Cron для запланованих завдань sidebarTitle: Heartbeat summary: Повідомлення опитування Heartbeat і правила сповіщень title: Heartbeat x-i18n: - generated_at: "2026-04-28T11:12:00Z" + generated_at: "2026-04-29T09:12:59Z" model: gpt-5.5 provider: openai - source_hash: 4a88385f08704b724a22f0d55719043861f94ed6890d2fbaadb3b399ee27c6d2 + source_hash: 2bafae7cafb9163015a112c074d36ab070c71d1d7ba1c7c0834e6720521f4275 source_path: gateway/heartbeat.md workflow: 16 --- -**Heartbeat чи Cron?** Див. [Автоматизація й завдання](/uk/automation), щоб дізнатися, коли використовувати кожен із них. +**Heartbeat чи cron?** Див. [Автоматизація й завдання](/uk/automation), щоб зрозуміти, коли що використовувати. -Heartbeat запускає **періодичні ходи агента** в основній сесії, щоб модель могла повідомляти про все, що потребує уваги, не надсилаючи вам зайвих повідомлень. +Heartbeat запускає **періодичні ходи агента** в головному сеансі, щоб модель могла повідомляти про все, що потребує уваги, не засмічуючи вас повідомленнями. -Heartbeat — це запланований хід в основній сесії; він **не** створює записи [фонових завдань](/uk/automation/tasks). Записи завдань призначені для відокремленої роботи (запуски ACP, субагенти, ізольовані завдання Cron). +Heartbeat — це запланований хід у головному сеансі; він **не** створює записи [фонових завдань](/uk/automation/tasks). Записи завдань призначені для відокремленої роботи (запуски ACP, субагенти, ізольовані cron-завдання). -Усунення несправностей: [Заплановані завдання](/uk/automation/cron-jobs#troubleshooting) +Усунення проблем: [Заплановані завдання](/uk/automation/cron-jobs#troubleshooting) ## Швидкий старт (для початківців) - - Залиште Heartbeat увімкненим (типове значення — `30m`, або `1h` для автентифікації Anthropic через OAuth/токен, зокрема повторного використання Claude CLI) або задайте власну періодичність. + + Залиште Heartbeat увімкненим (типово `30m`, або `1h` для автентифікації Anthropic OAuth/токеном, включно з повторним використанням Claude CLI) або задайте власний інтервал. - - Створіть короткий контрольний список `HEARTBEAT.md` або блок `tasks:` у робочій області агента. + + Створіть короткий контрольний список `HEARTBEAT.md` або блок `tasks:` у робочому просторі агента. - - `target: "none"` — типове значення; задайте `target: "last"`, щоб спрямовувати повідомлення останньому контакту. + + `target: "none"` — типове значення; задайте `target: "last"`, щоб спрямовувати їх останньому контакту. - + - Увімкніть доставку міркувань Heartbeat для прозорості. - - Використовуйте легкий початковий контекст, якщо для запусків Heartbeat потрібен лише `HEARTBEAT.md`. - - Увімкніть ізольовані сесії, щоб не надсилати повну історію розмови під час кожного Heartbeat. - - Обмежте Heartbeat активними годинами (локальний час). + - Використовуйте полегшений початковий контекст, якщо запускам Heartbeat потрібен лише `HEARTBEAT.md`. + - Увімкніть ізольовані сеанси, щоб не надсилати повну історію розмови для кожного Heartbeat. + - Обмежте Heartbeat активними годинами (за місцевим часом). @@ -57,6 +57,7 @@ Heartbeat — це запланований хід в основній сесі directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files isolatedSession: true, // optional: fresh session each run (no conversation history) + skipWhenBusy: true, // optional: also defer when subagent or nested lanes are busy // activeHours: { start: "08:00", end: "24:00" }, // includeReasoning: true, // optional: send separate `Reasoning:` message too }, @@ -67,31 +68,32 @@ Heartbeat — це запланований хід в основній сесі ## Типові значення -- Інтервал: `30m` (або `1h`, коли виявлений режим автентифікації Anthropic через OAuth/токен, зокрема повторне використання Claude CLI). Задайте `agents.defaults.heartbeat.every` або для окремого агента `agents.list[].heartbeat.every`; використовуйте `0m`, щоб вимкнути. +- Інтервал: `30m` (або `1h`, коли виявлений режим автентифікації Anthropic OAuth/токеном, включно з повторним використанням Claude CLI). Задайте `agents.defaults.heartbeat.every` або `agents.list[].heartbeat.every`; використовуйте `0m`, щоб вимкнути. - Тіло промпта (налаштовується через `agents.defaults.heartbeat.prompt`): `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- Промпт Heartbeat надсилається **дослівно** як повідомлення користувача. Системний промпт містить розділ "Heartbeat" лише тоді, коли Heartbeat увімкнено для типового агента, а запуск позначено внутрішньо. -- Коли Heartbeat вимкнено через `0m`, звичайні запуски також пропускають `HEARTBEAT.md` у початковому контексті, щоб модель не бачила інструкцій, призначених лише для Heartbeat. -- Активні години (`heartbeat.activeHours`) перевіряються в налаштованому часовому поясі. Поза цим вікном Heartbeat пропускається до наступного такту всередині вікна. +- Промпт Heartbeat надсилається **дослівно** як повідомлення користувача. Системний промпт містить розділ "Heartbeat" лише тоді, коли Heartbeat увімкнено для типового агента, а запуск позначається внутрішньо. +- Коли Heartbeat вимкнено через `0m`, звичайні запуски також не включають `HEARTBEAT.md` до початкового контексту, щоб модель не бачила інструкцій лише для Heartbeat. +- Активні години (`heartbeat.activeHours`) перевіряються в налаштованому часовому поясі. Поза цим вікном Heartbeat пропускаються до наступного такту всередині вікна. +- Heartbeat автоматично відкладається, поки cron-робота активна або стоїть у черзі. Задайте `heartbeat.skipWhenBusy: true`, щоб також відкладати під час додатково зайнятих ліній (субагента або вкладеної командної роботи); це корисно для локальних Ollama та інших обмежених хостів з одним середовищем виконання. -## Для чого потрібен промпт Heartbeat +## Для чого призначений промпт Heartbeat Типовий промпт навмисно широкий: -- **Фонові завдання**: "Consider outstanding tasks" спонукає агента переглянути подальші дії (вхідні, календар, нагадування, роботу в черзі) і повідомити про все термінове. -- **Перевірка стану людини**: "Checkup sometimes on your human during day time" спонукає час від часу надсилати легке повідомлення "щось потрібно?", але уникає нічного спаму завдяки налаштованому локальному часовому поясу (див. [Часовий пояс](/uk/concepts/timezone)). +- **Фонові завдання**: "Consider outstanding tasks" підштовхує агента переглянути подальші дії (вхідні, календар, нагадування, роботу в черзі) і повідомити про все термінове. +- **Перевірка людини**: "Checkup sometimes on your human during day time" підштовхує до періодичного легкого повідомлення "чи щось потрібно?", але уникає нічного спаму завдяки використанню налаштованого місцевого часового поясу (див. [Часовий пояс](/uk/concepts/timezone)). Heartbeat може реагувати на завершені [фонові завдання](/uk/automation/tasks), але сам запуск Heartbeat не створює запис завдання. -Якщо ви хочете, щоб Heartbeat робив щось дуже конкретне (наприклад, "перевірити статистику Gmail PubSub" або "перевірити стан gateway"), задайте `agents.defaults.heartbeat.prompt` (або `agents.list[].heartbeat.prompt`) як власне тіло (надсилається дослівно). +Якщо ви хочете, щоб Heartbeat виконував щось дуже конкретне (наприклад, "перевірити статистику Gmail PubSub" або "перевірити справність Gateway"), задайте `agents.defaults.heartbeat.prompt` (або `agents.list[].heartbeat.prompt`) із власним тілом (надсилається дослівно). ## Контракт відповіді - Якщо нічого не потребує уваги, відповідайте **`HEARTBEAT_OK`**. -- Під час запусків Heartbeat OpenClaw розглядає `HEARTBEAT_OK` як підтвердження, якщо воно з'являється на **початку або в кінці** відповіді. Токен вилучається, а відповідь відкидається, якщо решта вмісту має **≤ `ackMaxChars`** (типово: 300). -- Якщо `HEARTBEAT_OK` з'являється **посередині** відповіді, воно не обробляється особливим чином. -- Для сповіщень **не** включайте `HEARTBEAT_OK`; повертайте лише текст сповіщення. +- Під час запусків Heartbeat OpenClaw трактує `HEARTBEAT_OK` як підтвердження, коли він з’являється на **початку або в кінці** відповіді. Токен видаляється, а відповідь відкидається, якщо решта вмісту має **≤ `ackMaxChars`** (типово: 300). +- Якщо `HEARTBEAT_OK` з’являється **посередині** відповіді, він не обробляється особливо. +- Для сповіщень **не** включайте `HEARTBEAT_OK`; поверніть лише текст сповіщення. -Поза Heartbeat випадкове `HEARTBEAT_OK` на початку/в кінці повідомлення вилучається й записується в журнал; повідомлення, що складається лише з `HEARTBEAT_OK`, відкидається. +Поза Heartbeat випадковий `HEARTBEAT_OK` на початку/в кінці повідомлення видаляється й логується; повідомлення, що містить лише `HEARTBEAT_OK`, відкидається. ## Конфігурація @@ -105,6 +107,7 @@ Heartbeat може реагувати на завершені [фонові за includeReasoning: false, // default: false (deliver separate Reasoning: message when available) lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes target: "last", // default: none | options: last | none | (core or plugin, e.g. "bluebubbles") to: "+15551234567", // optional channel-specific override accountId: "ops-bot", // optional multi-account channel id @@ -119,16 +122,16 @@ Heartbeat може реагувати на завершені [фонові за ### Обсяг і пріоритет - `agents.defaults.heartbeat` задає глобальну поведінку Heartbeat. -- `agents.list[].heartbeat` зливається поверх; якщо будь-який агент має блок `heartbeat`, **лише ці агенти** запускають Heartbeat. +- `agents.list[].heartbeat` накладається зверху; якщо будь-який агент має блок `heartbeat`, Heartbeat запускають **лише ці агенти**. - `channels.defaults.heartbeat` задає типові параметри видимості для всіх каналів. - `channels..heartbeat` перевизначає типові параметри каналу. -- `channels..accounts..heartbeat` (канали з кількома обліковими записами) перевизначає налаштування для окремого каналу. +- `channels..accounts..heartbeat` (канали з кількома акаунтами) перевизначає налаштування для окремого каналу. ### Heartbeat для окремих агентів -Якщо будь-який запис `agents.list[]` містить блок `heartbeat`, **лише ці агенти** запускають Heartbeat. Блок окремого агента зливається поверх `agents.defaults.heartbeat` (тож можна один раз задати спільні типові значення й перевизначати їх для кожного агента). +Якщо будь-який запис `agents.list[]` містить блок `heartbeat`, Heartbeat запускають **лише ці агенти**. Блок окремого агента накладається поверх `agents.defaults.heartbeat` (тож ви можете один раз задати спільні типові значення й перевизначати їх для кожного агента). -Приклад: два агенти, лише другий агент запускає Heartbeat. +Приклад: два агенти, Heartbeat запускає лише другий агент. ```json5 { @@ -158,7 +161,7 @@ Heartbeat може реагувати на завершені [фонові за ### Приклад активних годин -Обмежте Heartbeat робочими годинами в певному часовому поясі: +Обмежте Heartbeat робочими годинами в конкретному часовому поясі: ```json5 { @@ -178,11 +181,11 @@ Heartbeat може реагувати на завершені [фонові за } ``` -Поза цим вікном (до 9:00 або після 22:00 за східним часом) Heartbeat пропускається. Наступний запланований такт усередині вікна виконається звичайно. +Поза цим вікном (до 9:00 або після 22:00 за східним часом) Heartbeat пропускаються. Наступний запланований такт усередині вікна виконається звичайно. ### Налаштування 24/7 -Якщо ви хочете, щоб Heartbeat працював увесь день, використовуйте один із цих шаблонів: +Якщо ви хочете, щоб Heartbeat працював увесь день, використайте один із цих шаблонів: - Повністю пропустіть `activeHours` (без обмеження часовим вікном; це типова поведінка). - Задайте вікно на весь день: `activeHours: { start: "00:00", end: "24:00" }`. @@ -191,9 +194,9 @@ Heartbeat може реагувати на завершені [фонові за Не задавайте однаковий час `start` і `end` (наприклад, від `08:00` до `08:00`). Це трактується як вікно нульової ширини, тому Heartbeat завжди пропускається. -### Приклад з кількома обліковими записами +### Приклад кількох акаунтів -Використовуйте `accountId`, щоб націлитися на конкретний обліковий запис у каналах із кількома обліковими записами, таких як Telegram: +Використовуйте `accountId`, щоб спрямувати на конкретний акаунт у каналах із кількома акаунтами, як-от Telegram: ```json5 { @@ -220,47 +223,50 @@ Heartbeat може реагувати на завершені [фонові за } ``` -### Примітки щодо полів +### Примітки до полів Інтервал Heartbeat (рядок тривалості; типова одиниця = хвилини). - Необов'язкове перевизначення моделі для запусків Heartbeat (`provider/model`). + Необов’язкове перевизначення моделі для запусків Heartbeat (`provider/model`). - Коли ввімкнено, також доставляє окреме повідомлення `Reasoning:`, якщо воно доступне (така сама форма, як `/reasoning on`). + Коли ввімкнено, також доставляє окреме повідомлення `Reasoning:`, якщо воно доступне (та сама форма, що й `/reasoning on`). - Коли значення true, запуски Heartbeat використовують легкий початковий контекст і залишають лише `HEARTBEAT.md` із початкових файлів робочої області. + Коли true, запуски Heartbeat використовують полегшений початковий контекст і залишають лише `HEARTBEAT.md` із початкових файлів робочого простору. - Коли значення true, кожен Heartbeat запускається у свіжій сесії без попередньої історії розмов. Використовує той самий шаблон ізоляції, що й Cron `sessionTarget: "isolated"`. Значно зменшує вартість токенів на кожен Heartbeat. Поєднуйте з `lightContext: true` для максимальної економії. Маршрутизація доставки все одно використовує контекст основної сесії. + Коли true, кожен Heartbeat запускається в новому сеансі без попередньої історії розмови. Використовує той самий шаблон ізоляції, що й cron `sessionTarget: "isolated"`. Різко зменшує витрати токенів на кожен Heartbeat. Поєднуйте з `lightContext: true` для максимальної економії. Маршрутизація доставки все одно використовує контекст головного сеансу. + + + Коли true, запуски Heartbeat відкладаються на додатково зайнятих лініях: робота субагента або вкладених команд. Cron-лінії завжди відкладають Heartbeat, навіть без цього прапорця, тому хости локальних моделей не запускають cron і промпти Heartbeat одночасно. - Необов'язковий ключ сесії для запусків Heartbeat. + Необов’язковий ключ сеансу для запусків Heartbeat. -- `main` (типово): основна сесія агента. -- Явний ключ сесії (скопіюйте з `openclaw sessions --json` або [CLI сесій](/uk/cli/sessions)). -- Формати ключів сесій: див. [Сесії](/uk/concepts/session) і [Групи](/uk/channels/groups). +- `main` (типово): головний сеанс агента. +- Явний ключ сеансу (скопіюйте з `openclaw sessions --json` або з [CLI сеансів](/uk/cli/sessions)). +- Формати ключів сеансів: див. [Сеанси](/uk/concepts/session) і [Групи](/uk/channels/groups). -- `last`: доставляти до останнього використаного зовнішнього каналу. -- явний канал: будь-який налаштований канал або id Plugin, наприклад `discord`, `matrix`, `telegram` або `whatsapp`. -- `none` (типово): запускати Heartbeat, але **не доставляти** назовні. +- `last`: доставити в останній використаний зовнішній канал. +- явний канал: будь-який налаштований канал або id plugin, наприклад `discord`, `matrix`, `telegram` або `whatsapp`. +- `none` (типово): запустити Heartbeat, але **не доставляти** назовні. - Керує поведінкою доставки напряму/DM. `allow`: дозволяє доставку Heartbeat напряму/DM. `block`: пригнічує доставку напряму/DM (`reason=dm-blocked`). + Керує поведінкою доставки напряму/DM. `allow`: дозволити доставку Heartbeat напряму/DM. `block`: придушити доставку напряму/DM (`reason=dm-blocked`). - Необов'язкове перевизначення одержувача (id, специфічний для каналу, наприклад E.164 для WhatsApp або id чату Telegram). Для тем/гілок Telegram використовуйте `:topic:`. + Необов’язкове перевизначення отримувача (id, специфічний для каналу, наприклад E.164 для WhatsApp або id чату Telegram). Для тем/гілок Telegram використовуйте `:topic:`. - Необов'язковий id облікового запису для каналів із кількома обліковими записами. Коли `target: "last"`, id облікового запису застосовується до визначеного останнього каналу, якщо він підтримує облікові записи; інакше ігнорується. Якщо id облікового запису не відповідає налаштованому обліковому запису для визначеного каналу, доставка пропускається. + Необов’язковий id акаунта для каналів із кількома акаунтами. Коли `target: "last"`, id акаунта застосовується до визначеного останнього каналу, якщо він підтримує акаунти; інакше ігнорується. Якщо id акаунта не відповідає налаштованому акаунту для визначеного каналу, доставка пропускається. @@ -268,19 +274,19 @@ Heartbeat може реагувати на завершені [фонові за - Максимальна кількість символів, дозволена після `HEARTBEAT_OK` перед доставкою. + Максимальна кількість символів після `HEARTBEAT_OK` перед доставкою. - Коли значення true, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat. + Якщо true, приглушує payload-попередження про помилки інструментів під час запусків Heartbeat. - Обмежує запуски Heartbeat часовим вікном. Об'єкт із `start` (HH:MM, включно; використовуйте `00:00` для початку дня), `end` (HH:MM, не включно; `24:00` дозволено для кінця дня) і необов'язковим `timezone`. + Обмежує запуски Heartbeat часовим вікном. Об’єкт із `start` (HH:MM, включно; використовуйте `00:00` для початку дня), `end` (HH:MM виключно; `24:00` дозволено для кінця дня) та необов’язковим `timezone`. - Пропущено або `"user"`: використовує ваш `agents.defaults.userTimezone`, якщо задано, інакше повертається до часового поясу системи хоста. - `"local"`: завжди використовує часовий пояс системи хоста. -- Будь-який ідентифікатор IANA (наприклад, `America/New_York`): використовується напряму; якщо він недійсний, повертається до поведінки `"user"`, описаної вище. +- Будь-який ідентифікатор IANA (наприклад, `America/New_York`): використовується напряму; якщо недійсний, повертається до поведінки `"user"` вище. - `start` і `end` не мають бути однаковими для активного вікна; однакові значення вважаються нульовою шириною (завжди поза вікном). - Поза активним вікном Heartbeat пропускаються до наступного тіку всередині вікна. @@ -290,31 +296,32 @@ Heartbeat може реагувати на завершені [фонові за - - Heartbeat за замовчуванням запускаються в основному сеансі агента (`agent::`) або в `global`, коли `session.scope = "global"`. Установіть `session`, щоб перевизначити на конкретний сеанс каналу (Discord/WhatsApp тощо). + - Heartbeat за замовчуванням працюють в основному сеансі агента (`agent::`) або `global`, коли `session.scope = "global"`. Задайте `session`, щоб перевизначити на конкретний сеанс каналу (Discord/WhatsApp/тощо). - `session` впливає лише на контекст запуску; доставка керується `target` і `to`. - - Щоб доставити в конкретний канал/одержувачу, задайте `target` + `to`. З `target: "last"` доставка використовує останній зовнішній канал для цього сеансу. - - Доставки Heartbeat за замовчуванням дозволяють прямі цілі/DM. Установіть `directPolicy: "block"`, щоб пригнічувати надсилання до прямих цілей, водночас усе ще виконуючи прохід Heartbeat. - - Якщо основна черга зайнята, Heartbeat пропускається і повторюється пізніше. - - Якщо `target` не визначає зовнішнє призначення, запуск усе одно відбувається, але вихідне повідомлення не надсилається. + - Щоб доставити до конкретного каналу/отримувача, задайте `target` + `to`. З `target: "last"` доставка використовує останній зовнішній канал для цього сеансу. + - Доставки Heartbeat за замовчуванням дозволяють прямі/DM-цілі. Задайте `directPolicy: "block"`, щоб приглушити надсилання до прямих цілей, водночас усе ще виконуючи крок Heartbeat. + - Якщо основна черга, lane цільового сеансу, lane cron або активне cron-завдання зайняті, Heartbeat пропускається й повторюється пізніше. + - Якщо `skipWhenBusy: true`, субагентські та вкладені lanes також відкладають запуски Heartbeat. + - Якщо `target` не визначається до зовнішнього призначення, запуск усе одно відбувається, але вихідне повідомлення не надсилається. - Якщо `showOk`, `showAlerts` і `useIndicator` усі вимкнені, запуск пропускається наперед як `reason=alerts-disabled`. - - Якщо вимкнено лише доставку сповіщень, OpenClaw усе ще може запустити Heartbeat, оновити часові мітки належних завдань, відновити часову мітку простою сеансу та пригнітити зовнішнє корисне навантаження сповіщення. - - Якщо визначена ціль Heartbeat підтримує індикацію набору тексту, OpenClaw показує набір тексту, поки запуск Heartbeat активний. Для цього використовується та сама ціль, до якої Heartbeat надсилав би вихідний чат, і це вимикається через `typingMode: "never"`. + - Якщо вимкнена лише доставка сповіщень, OpenClaw усе ще може виконати Heartbeat, оновити позначки часу належних завдань, відновити позначку часу простою сеансу та приглушити зовнішній payload сповіщення. + - Якщо визначена ціль Heartbeat підтримує індикацію набору, OpenClaw показує набір, поки запуск Heartbeat активний. Це використовує ту саму ціль, куди Heartbeat надсилав би вихід чату, і вимикається через `typingMode: "never"`. - - Відповіді лише Heartbeat **не** підтримують сеанс активним. Метадані Heartbeat можуть оновлювати рядок сеансу, але закінчення через простій використовує `lastInteractionAt` з останнього справжнього повідомлення користувача/каналу, а щоденне закінчення використовує `sessionStartedAt`. - - Історія Control UI і WebChat приховує підказки Heartbeat та підтвердження лише OK. Базова транскрипція сеансу все ще може містити ці проходи для аудиту/відтворення. - - Відокремлені [фонові завдання](/uk/automation/tasks) можуть поставити системну подію в чергу й розбудити Heartbeat, коли основний сеанс має швидко щось помітити. Таке пробудження не перетворює запуск Heartbeat на фонове завдання. + - Відповіді лише Heartbeat **не** підтримують сеанс активним. Метадані Heartbeat можуть оновлювати рядок сеансу, але закінчення простою використовує `lastInteractionAt` з останнього справжнього повідомлення користувача/каналу, а щоденне закінчення використовує `sessionStartedAt`. + - Історія Control UI та WebChat приховує підказки Heartbeat і підтвердження лише OK. Базовий транскрипт сеансу все ще може містити ці кроки для аудиту/повторного відтворення. + - Відокремлені [фонові завдання](/uk/automation/tasks) можуть поставити системну подію в чергу й розбудити Heartbeat, коли основний сеанс має швидко щось помітити. Це пробудження не робить запуск Heartbeat фоновим завданням. ## Елементи керування видимістю -За замовчуванням підтвердження `HEARTBEAT_OK` пригнічуються, тоді як вміст сповіщень доставляється. Ви можете налаштувати це для кожного каналу або облікового запису: +За замовчуванням підтвердження `HEARTBEAT_OK` приглушуються, тоді як вміст сповіщень доставляється. Це можна налаштувати для каналу або облікового запису: ```yaml channels: @@ -333,17 +340,17 @@ channels: showAlerts: false # Suppress alert delivery for this account ``` -Пріоритет: для облікового запису → для каналу → типові параметри каналу → вбудовані типові параметри. +Пріоритет: для облікового запису → для каналу → типові значення каналу → вбудовані типові значення. ### Що робить кожен прапорець - `showOk`: надсилає підтвердження `HEARTBEAT_OK`, коли модель повертає відповідь лише OK. -- `showAlerts`: надсилає вміст сповіщення, коли модель повертає не-OK відповідь. -- `useIndicator`: емітує події індикатора для поверхонь стану UI. +- `showAlerts`: надсилає вміст сповіщення, коли модель повертає відповідь не OK. +- `useIndicator`: випромінює події індикатора для поверхонь стану UI. -Якщо **всі три** мають значення false, OpenClaw повністю пропускає запуск Heartbeat (без виклику моделі). +Якщо **всі три** false, OpenClaw повністю пропускає запуск Heartbeat (без виклику моделі). -### Приклади для каналу й облікового запису +### Приклади для каналу й для облікового запису ```yaml channels: @@ -364,24 +371,24 @@ channels: showOk: true ``` -### Поширені шаблони +### Типові шаблони | Мета | Конфігурація | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| Типова поведінка (тихі OK, сповіщення ввімкнено) | _(конфігурація не потрібна)_ | +| Типова поведінка (тихі OK, сповіщення ввімкнені) | _(конфігурація не потрібна)_ | | Повністю тихо (без повідомлень, без індикатора) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | | Лише індикатор (без повідомлень) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | | OK лише в одному каналі | `channels.telegram.heartbeat: { showOk: true }` | ## HEARTBEAT.md (необов’язково) -Якщо файл `HEARTBEAT.md` існує в робочому просторі, типова підказка каже агенту прочитати його. Думайте про нього як про ваш "контрольний список Heartbeat": невеликий, стабільний і безпечний для включення кожні 30 хвилин. +Якщо файл `HEARTBEAT.md` існує в робочому просторі, типова підказка просить агента прочитати його. Вважайте його своїм "контрольним списком Heartbeat": невеликим, стабільним і безпечним для включення кожні 30 хвилин. -Під час звичайних запусків `HEARTBEAT.md` впроваджується лише тоді, коли вказівки Heartbeat увімкнено для типового агента. Вимкнення каденції Heartbeat через `0m` або встановлення `includeSystemPromptSection: false` вилучає його зі звичайного bootstrap-контексту. +Під час звичайних запусків `HEARTBEAT.md` вставляється лише тоді, коли настанови Heartbeat увімкнені для типового агента. Вимкнення cadence Heartbeat через `0m` або встановлення `includeSystemPromptSection: false` вилучає його зі звичайного початкового контексту. -Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки й markdown-заголовки на кшталт `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб заощадити виклики API. Такий пропуск повідомляється як `reason=empty-heartbeat-file`. Якщо файл відсутній, Heartbeat усе одно запускається, а модель вирішує, що робити. +Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки й markdown-заголовки на кшталт `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб заощадити API-виклики. Цей пропуск повідомляється як `reason=empty-heartbeat-file`. Якщо файл відсутній, Heartbeat усе одно запускається, а модель вирішує, що робити. -Тримайте його маленьким (короткий контрольний список або нагадування), щоб уникати роздування підказки. +Тримайте його дуже малим (короткий контрольний список або нагадування), щоб уникнути роздування підказки. Приклад `HEARTBEAT.md`: @@ -417,74 +424,74 @@ tasks: - - OpenClaw розбирає блок `tasks:` і перевіряє кожне завдання за його власним `interval`. - - До підказки Heartbeat для цього тіку включаються лише **належні** завдання. - - Якщо немає належних завдань, Heartbeat повністю пропускається (`reason=no-tasks-due`), щоб уникнути марного виклику моделі. - - Вміст у `HEARTBEAT.md`, який не є завданнями, зберігається і додається як додатковий контекст після списку належних завдань. - - Часові мітки останнього запуску завдань зберігаються в стані сеансу (`heartbeatTaskState`), тож інтервали переживають звичайні перезапуски. - - Часові мітки завдань просуваються лише після того, як запуск Heartbeat завершує свій звичайний шлях відповіді. Пропущені запуски `empty-heartbeat-file` / `no-tasks-due` не позначають завдання як завершені. + - OpenClaw розбирає блок `tasks:` і перевіряє кожне завдання відносно його власного `interval`. + - До підказки Heartbeat для цього тіку включаються лише завдання, строк яких **настав**. + - Якщо немає завдань, строк яких настав, Heartbeat повністю пропускається (`reason=no-tasks-due`), щоб уникнути марного виклику моделі. + - Вміст у `HEARTBEAT.md`, що не належить до завдань, зберігається й додається як додатковий контекст після списку завдань, строк яких настав. + - Позначки часу останнього запуску завдань зберігаються в стані сеансу (`heartbeatTaskState`), тож інтервали переживають звичайні перезапуски. + - Позначки часу завдань просуваються лише після того, як запуск Heartbeat завершує свій звичайний шлях відповіді. Пропущені запуски `empty-heartbeat-file` / `no-tasks-due` не позначають завдання як завершені. -Режим завдань корисний, коли ви хочете, щоб один файл Heartbeat містив кілька періодичних перевірок без оплати за всі з них на кожному тіку. +Режим завдань корисний, коли потрібно, щоб один файл Heartbeat містив кілька періодичних перевірок без оплати за всі з них на кожному тіку. ### Чи може агент оновлювати HEARTBEAT.md? -Так — якщо ви попросите його про це. +Так — якщо ви його про це попросите. `HEARTBEAT.md` — це просто звичайний файл у робочому просторі агента, тож ви можете сказати агенту (у звичайному чаті) щось на кшталт: - "Онови `HEARTBEAT.md`, щоб додати щоденну перевірку календаря." -- "Перепиши `HEARTBEAT.md`, щоб він був коротшим і зосередженим на подальших діях у вхідних." +- "Перепиши `HEARTBEAT.md`, щоб він був коротшим і зосередженим на подальших діях щодо вхідних." -Якщо ви хочете, щоб це відбувалося проактивно, ви також можете включити явний рядок у вашу підказку Heartbeat, наприклад: "Якщо контрольний список застаріє, онови HEARTBEAT.md кращим." +Якщо ви хочете, щоб це відбувалося проактивно, можна також включити явний рядок у підказку Heartbeat, наприклад: "Якщо контрольний список застаріє, онови HEARTBEAT.md кращим варіантом." -Не кладіть секрети (ключі API, номери телефонів, приватні токени) у `HEARTBEAT.md` — він стає частиною контексту підказки. +Не кладіть секрети (API-ключі, номери телефонів, приватні токени) у `HEARTBEAT.md` — він стає частиною контексту підказки. ## Ручне пробудження (на вимогу) -Ви можете поставити системну подію в чергу й запустити негайний Heartbeat за допомогою: +Можна поставити системну подію в чергу й запустити негайний Heartbeat за допомогою: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -Якщо для кількох агентів налаштовано `heartbeat`, ручне пробудження негайно запускає Heartbeat кожного з цих агентів. +Якщо в кількох агентів налаштовано `heartbeat`, ручне пробудження негайно запускає кожен із цих агентських Heartbeat. Використовуйте `--mode next-heartbeat`, щоб дочекатися наступного запланованого тіку. -## Доставка міркувань (необов’язково) +## Доставка reasoning (необов’язково) -За замовчуванням Heartbeat доставляє лише фінальне корисне навантаження "відповіді". +За замовчуванням Heartbeat доставляють лише фінальний payload "відповіді". -Якщо вам потрібна прозорість, увімкніть: +Якщо потрібна прозорість, увімкніть: - `agents.defaults.heartbeat.includeReasoning: true` -Коли це ввімкнено, Heartbeat також доставлятиме окреме повідомлення з префіксом `Reasoning:` (така сама форма, як `/reasoning on`). Це може бути корисним, коли агент керує кількома сеансами/кодексами і ви хочете бачити, чому він вирішив вас пінгувати, але це також може розкрити більше внутрішніх деталей, ніж вам потрібно. У групових чатах краще залишати це вимкненим. +Коли це ввімкнено, Heartbeat також доставлятимуть окреме повідомлення з префіксом `Reasoning:` (та сама форма, що й `/reasoning on`). Це може бути корисно, коли агент керує кількома сеансами/кодексами й ви хочете бачити, чому він вирішив вам написати, але це також може розкрити більше внутрішніх деталей, ніж вам потрібно. У групових чатах краще залишати вимкненим. -## Обізнаність про вартість +## Усвідомлення вартості -Heartbeat запускає повні проходи агента. Коротші інтервали спалюють більше токенів. Щоб зменшити вартість: +Heartbeat запускають повні кроки агента. Коротші інтервали витрачають більше токенів. Щоб зменшити вартість: -- Використовуйте `isolatedSession: true`, щоб уникнути надсилання повної історії розмови (~100K токенів до ~2-5K за запуск). -- Використовуйте `lightContext: true`, щоб обмежити bootstrap-файли лише `HEARTBEAT.md`. -- Установіть дешевшу `model` (наприклад, `ollama/llama3.2:1b`). -- Тримайте `HEARTBEAT.md` маленьким. -- Використовуйте `target: "none"`, якщо вам потрібні лише оновлення внутрішнього стану. +- Використовуйте `isolatedSession: true`, щоб уникнути надсилання повної історії розмови (~100K токенів до ~2-5K на запуск). +- Використовуйте `lightContext: true`, щоб обмежити початкові файли лише `HEARTBEAT.md`. +- Задайте дешевший `model` (наприклад, `ollama/llama3.2:1b`). +- Тримайте `HEARTBEAT.md` малим. +- Використовуйте `target: "none"`, якщо потрібні лише внутрішні оновлення стану. ## Переповнення контексту після Heartbeat -Якщо Heartbeat використовує меншу локальну модель, наприклад модель Ollama з вікном 32k, а наступний прохід основного сеансу повідомляє про переповнення контексту, перевірте, чи попередній Heartbeat не залишив сеанс на моделі Heartbeat. Повідомлення скидання OpenClaw вказує на це, коли остання runtime-модель відповідає налаштованій `heartbeat.model`. +Якщо Heartbeat використовує меншу локальну модель, наприклад модель Ollama з вікном 32k, а наступний крок основного сеансу повідомляє про переповнення контексту, перевірте, чи попередній Heartbeat не залишив сеанс на моделі Heartbeat. Повідомлення скидання OpenClaw вказує на це, коли остання runtime-модель збігається з налаштованою `heartbeat.model`. -Використовуйте `isolatedSession: true`, щоб запускати Heartbeat у свіжому сеансі, поєднайте це з `lightContext: true` для найменшої підказки або виберіть модель Heartbeat з вікном контексту, достатньо великим для спільного сеансу. +Використовуйте `isolatedSession: true`, щоб запускати Heartbeat у свіжому сеансі, поєднайте це з `lightContext: true` для найменшої підказки або виберіть модель Heartbeat із вікном контексту, достатньо великим для спільного сеансу. -## Пов’язане +## Пов’язано -- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації стисло +- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації в одному огляді - [Фонові завдання](/uk/automation/tasks) — як відстежується відокремлена робота - [Часовий пояс](/uk/concepts/timezone) — як часовий пояс впливає на планування Heartbeat - [Усунення несправностей](/uk/automation/cron-jobs#troubleshooting) — налагодження проблем автоматизації diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 0af91b8e0..68d8ac6f2 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,24 +1,24 @@ --- read_when: - - Центр усунення несправностей скерував вас сюди для глибшої діагностики - - Потрібні стабільні розділи інструкції з реагування на основі симптомів із точними командами + - Центр усунення несправностей спрямував вас сюди для поглибленої діагностики + - Вам потрібні стабільні розділи операційного посібника, орієнтовані на симптоми, з точними командами. sidebarTitle: Troubleshooting -summary: Поглиблений плейбук з усунення несправностей для Gateway, каналів, автоматизації, вузлів і браузера +summary: Поглиблений посібник з усунення несправностей для Gateway, каналів, автоматизації, вузлів і браузера title: Усунення несправностей x-i18n: - generated_at: "2026-04-28T20:56:42Z" + generated_at: "2026-04-29T09:12:59Z" model: gpt-5.5 provider: openai - source_hash: 2ad4332803ad43f90e793fba71a0fce874b63cb4d4711c6a308ecfa030257cb3 + source_hash: 48735a68daa92678867a9cafb3ceeb37063bb91dee8c4c94e185f74eb0296fcb source_path: gateway/troubleshooting.md workflow: 16 --- -Ця сторінка є детальним посібником виконання. Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу потрібен швидкий процес тріажу. +Ця сторінка є докладним операційним посібником. Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу потрібен швидкий потік діагностики. -## Послідовність команд +## Командна драбина -Спершу виконайте їх у такому порядку: +Спочатку виконайте ці команди в такому порядку: ```bash openclaw status @@ -31,14 +31,14 @@ openclaw channels status --probe Очікувані ознаки справного стану: - `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`. -- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації чи сервісу. -- `openclaw channels status --probe` показує поточний стан транспорту для кожного облікового запису, а де підтримується, результати probe/audit, як-от `works` або `audit ok`. +- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації або сервісу. +- `openclaw channels status --probe` показує активний статус транспорту для кожного облікового запису і, де підтримується, результати перевірки/аудиту, як-от `works` або `audit ok`. -## Розділені встановлення та захист від новішої конфігурації +## Розділені встановлення й захист від новішої конфігурації Використовуйте це, коли сервіс Gateway несподівано зупиняється після оновлення або журнали показують, що один бінарний файл `openclaw` старіший за версію, яка востаннє записала `openclaw.json`. -OpenClaw позначає записи конфігурації через `meta.lastTouchedVersion`. Команди лише для читання все ще можуть переглядати конфігурацію, записану новішим OpenClaw, але зміни процесів і сервісів відмовляються продовжуватися зі старішого бінарного файла. Заблоковані дії включають запуск, зупинку, перезапуск, видалення сервісу Gateway, примусове перевстановлення сервісу, запуск Gateway у режимі сервісу та очищення порту через `gateway --force`. +OpenClaw позначає записи конфігурації через `meta.lastTouchedVersion`. Команди лише для читання все ще можуть перевіряти конфігурацію, записану новішим OpenClaw, але мутації процесів і сервісів відмовляються продовжувати роботу зі старішого бінарного файлу. Заблоковані дії включають запуск, зупинку, перезапуск, видалення сервісу Gateway, примусове перевстановлення сервісу, запуск Gateway у сервісному режимі та очищення порту `gateway --force`. ```bash which openclaw @@ -49,9 +49,9 @@ openclaw config get meta.lastTouchedVersion - Виправте `PATH`, щоб `openclaw` вказував на новіше встановлення, а потім повторно виконайте дію. + Виправте `PATH`, щоб `openclaw` вказував на новіше встановлення, потім повторно виконайте дію. - + Перевстановіть потрібний сервіс Gateway із новішого встановлення: ```bash @@ -61,17 +61,17 @@ openclaw config get meta.lastTouchedVersion - Видаліть застарілий системний пакет або старі записи обгорток, які все ще вказують на старий бінарний файл `openclaw`. + Видаліть застарілі системні пакети або старі записи обгорток, які все ще вказують на старий бінарний файл `openclaw`. -Лише для навмисного відкату версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для звичайної роботи залишайте це значення невстановленим. +Лише для навмисного пониження версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для звичайної роботи залишайте це значення невстановленим. -## Для довгого контексту Anthropic 429 потрібне додаткове використання +## Anthropic 429 вимагає додаткового використання для довгого контексту -Використовуйте це, коли журнали або помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. +Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash openclaw logs --follow @@ -79,39 +79,39 @@ openclaw models status openclaw config get agents.defaults.models ``` -Шукайте таке: +Шукайте: - Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. - Поточні облікові дані Anthropic не мають права на використання довгого контексту. -- Запити падають лише під час довгих сесій або запусків моделей, яким потрібен шлях 1M beta. +- Запити падають лише в довгих сесіях/запусках моделі, яким потрібен шлях 1M beta. Варіанти виправлення: - Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного контекстного вікна. + Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. - - Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на ключ Anthropic API. + + Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на API-ключ Anthropic. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли запити Anthropic із довгим контекстом відхиляються. -Пов’язано: +Пов’язане: - [Anthropic](/uk/providers/anthropic) - [Використання токенів і витрати](/uk/reference/token-use) - [Чому я бачу HTTP 429 від Anthropic?](/uk/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-сумісний бекенд проходить прямі перевірки, але запуски агента не вдаються +## Локальний OpenAI-сумісний бекенд проходить прямі перевірки, але запуски агента падають Використовуйте це, коли: - `curl ... /v1/models` працює -- крихітні прямі виклики `/v1/chat/completions` працюють -- запуски моделі OpenClaw не вдаються лише під час звичайних ходів агента +- малі прямі виклики `/v1/chat/completions` працюють +- Запуски моделей OpenClaw падають лише під час звичайних кроків агента ```bash curl http://127.0.0.1:1234/v1/models @@ -122,33 +122,33 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -Шукайте таке: +Шукайте: -- прямі крихітні виклики успішні, але запуски OpenClaw не вдаються лише на більших промптах +- прямі малі виклики успішні, але запуски OpenClaw падають лише на більших промптах - помилки `model_not_found` або 404, хоча прямий `/v1/chat/completions` працює з тим самим простим ідентифікатором моделі - помилки бекенду про те, що `messages[].content` очікує рядок - періодичні попередження `incomplete turn detected ... stopReason=stop payloads=0` з OpenAI-сумісним локальним бекендом -- збої бекенду, що з’являються лише з більшими кількостями prompt-token або повними промптами середовища виконання агента +- збої бекенду, які з’являються лише за більшої кількості токенів промпта або повних промптів середовища виконання агента - - - `model_not_found` з локальним сервером у стилі MLX/vLLM → перевірте, що `baseUrl` містить `/v1`, `api` є `"openai-completions"` для бекендів `/v1/chat/completions`, а `models.providers..models[].id` є простим локальним ідентифікатором провайдера. Виберіть його один раз із префіксом провайдера, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; залиште запис каталогу як `mlx-community/Qwen3-30B-A3B-6bit`. - - `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: установіть `models.providers..models[].compat.requiresStringContent: true`. - - `incomplete turn detected ... stopReason=stop payloads=0` → бекенд завершив запит Chat Completions, але не повернув видимий користувачу текст асистента для цього ходу. OpenClaw один раз повторює replay-safe порожні OpenAI-сумісні ходи; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді. - - прямі крихітні запити успішні, але запуски агента OpenClaw падають зі збоями бекенду/моделі (наприклад, Gemma на деяких збірках `inferrs`) → транспорт OpenClaw, імовірно, вже правильний; бекенд падає на більшій формі prompt середовища виконання агента. - - збоїв стає менше після вимкнення інструментів, але вони не зникають → схеми інструментів були частиною навантаження, але решта проблеми все ще належить до місткості висхідної моделі/сервера або помилки бекенду. + + - `model_not_found` з локальним сервером у стилі MLX/vLLM → перевірте, що `baseUrl` містить `/v1`, `api` дорівнює `"openai-completions"` для бекендів `/v1/chat/completions`, а `models.providers..models[].id` є простим локальним для провайдера ідентифікатором. Виберіть його один раз із префіксом провайдера, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; запис каталогу залиште як `mlx-community/Qwen3-30B-A3B-6bit`. + - `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть `models.providers..models[].compat.requiresStringContent: true`. + - `incomplete turn detected ... stopReason=stop payloads=0` → бекенд завершив запит Chat Completions, але не повернув видимого користувачу тексту асистента для цього кроку. OpenClaw один раз повторює безпечні для відтворення порожні OpenAI-сумісні кроки; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді. + - прямі малі запити успішні, але запуски агента OpenClaw падають через збої бекенду/моделі (наприклад Gemma на деяких збірках `inferrs`) → транспорт OpenClaw, імовірно, уже налаштований правильно; бекенд падає на більшій формі промпта середовища виконання агента. + - збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів були частиною навантаження, але решта проблеми все ще в місткості верхньорівневої моделі/сервера або в помилці бекенду. - 1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, які підтримують лише рядки. - 2. Установіть `compat.supportsTools: false` для моделей/бекендів, які не можуть надійно обробляти поверхню схем інструментів OpenClaw. - 3. Зменште навантаження промпта, де це можливо: менший bootstrap робочого простору, коротша історія сесії, легша локальна модель або бекенд із сильнішою підтримкою довгого контексту. - 4. Якщо крихітні прямі запити й надалі проходять, а ходи агента OpenClaw усе ще падають усередині бекенду, розглядайте це як обмеження висхідного сервера/моделі й подайте туди відтворення з прийнятою формою payload. + 1. Встановіть `compat.requiresStringContent: true` для бекендів Chat Completions, які підтримують лише рядки. + 2. Встановіть `compat.supportsTools: false` для моделей/бекендів, які не можуть надійно обробляти поверхню схем інструментів OpenClaw. + 3. Зменште навантаження промпта, де це можливо: менший початковий контекст робочої області, коротша історія сесії, легша локальна модель або бекенд із сильнішою підтримкою довгого контексту. + 4. Якщо малі прямі запити й надалі проходять, а кроки агента OpenClaw усе ще падають усередині бекенду, розглядайте це як обмеження верхньорівневого сервера/моделі й подайте туди відтворення з прийнятою формою payload. -Пов’язано: +Пов’язане: - [Конфігурація](/uk/gateway/configuration) - [Локальні моделі](/uk/gateway/local-models) @@ -156,7 +156,7 @@ openclaw logs --follow ## Немає відповідей -Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. +Якщо канали працюють, але ніщо не відповідає, перевірте маршрутизацію й політику, перш ніж перепідключати будь-що. ```bash openclaw status @@ -166,27 +166,27 @@ openclaw config get channels openclaw logs --follow ``` -Шукайте таке: +Шукайте: -- Очікується pairing для відправників DM. -- Обмеження згадок у групі (`requireMention`, `mentionPatterns`). +- Очікування сполучення для відправників DM. +- Обмеження згадкою в групі (`requireMention`, `mentionPatterns`). - Невідповідності allowlist каналу/групи. -Типові сигнатури: +Поширені сигнатури: - `drop guild message (mention required` → групове повідомлення ігнорується до згадки. -- `pairing request` → відправник потребує схвалення. -- `blocked` / `allowlist` → відправника/канал відфільтровано політикою. +- `pairing request` → відправнику потрібне схвалення. +- `blocked` / `allowlist` → відправника/канал було відфільтровано політикою. -Пов’язано: +Пов’язане: -- [Усунення несправностей каналів](/uk/channels/troubleshooting) +- [Діагностика каналів](/uk/channels/troubleshooting) - [Групи](/uk/channels/groups) -- [Pairing](/uk/channels/pairing) +- [Сполучення](/uk/channels/pairing) -## Підключення Dashboard control UI +## Підключення керівного інтерфейсу панелі керування -Коли Dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо безпечного контексту. +Коли панель керування/керівний інтерфейс не підключається, перевірте URL, режим автентифікації та припущення щодо захищеного контексту. ```bash openclaw gateway status @@ -196,42 +196,42 @@ openclaw doctor openclaw gateway status --json ``` -Шукайте таке: +Шукайте: -- Правильний URL перевірки та URL dashboard. +- Правильний URL перевірки й URL панелі керування. - Невідповідність режиму автентифікації/токена між клієнтом і Gateway. - Використання HTTP там, де потрібна ідентичність пристрою. - - `device identity required` → небезпечний контекст або відсутня автентифікація пристрою. - - `origin not allowed` → браузерний `Origin` не входить до `gateway.controlUi.allowedOrigins` (або ви підключаєтеся з не-loopback походження браузера без явного allowlist). - - `device nonce required` / `device nonce mismatch` → клієнт не завершує challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`). - - `device signature invalid` / `device signature expired` → клієнт підписав неправильний payload (або застарілу часову мітку) для поточного handshake. + - `device identity required` → незахищений контекст або відсутня автентифікація пристрою. + - `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` (або ви підключаєтеся з браузерного джерела не через loopback без явного allowlist). + - `device nonce required` / `device nonce mismatch` → клієнт не завершує потік автентифікації пристрою на основі виклику (`connect.challenge` + `device.nonce`). + - `device signature invalid` / `device signature expired` → клієнт підписав неправильний payload (або застарілу часову мітку) для поточного рукостискання. - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. - - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений із paired токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний набір scope. - - Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спершу явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються перед тим, як limiter записує збій. Тому дві погані одночасні повторні спроби від того самого клієнта можуть показати `retry later` під час другої спроби замість двох простих невідповідностей. - - `too many failed authentication attempts (retry later)` від браузерного loopback-клієнта → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інше походження localhost використовує окремий bucket. - - повторне `unauthorized` після цієї повторної спроби → розсинхронізація спільного токена/токена пристрою; оновіть конфігурацію токена та повторно схваліть/ротіруйте токен пристрою за потреби. - - `gateway connect failed:` → неправильний хост/порт/ціль url. + - Ця повторна спроба з кешованим токеном повторно використовує кешований набір областей, збережений із токеном сполученого пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають свій запитаний набір областей. + - Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач зафіксує збій. Тому дві погані паралельні повторні спроби від того самого клієнта можуть показати `retry later` на другій спробі замість двох простих невідповідностей. + - `too many failed authentication attempts (retry later)` від браузерного loopback-клієнта → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інше localhost-джерело використовує окремий bucket. + - повторне `unauthorized` після цієї повторної спроби → розходження спільного токена/токена пристрою; оновіть конфігурацію токена й за потреби повторно схваліть/ротируйте токен пристрою. + - `gateway connect failed:` → неправильний хост/порт/ціль URL. ### Швидка мапа кодів деталей автентифікації -Використайте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: -| Код подробиць | Значення | Рекомендована дія | +| Код деталі | Значення | Рекомендована дія | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів панелі: `openclaw config get gateway.auth.token`, потім вставте його в налаштування Control UI. | -| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені затверджені області доступу; виклики з явним `deviceToken` / `scopes` зберігають запитані області доступу. Якщо помилка лишається, виконайте [контрольний список відновлення після розходження токенів](/uk/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен окремого пристрою застарів або відкликаний. | Ротуйте/повторно затвердьте токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), потім підключіться знову. | -| `PAIRING_REQUIRED` | Ідентичність пристрою потребує затвердження. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використовуйте `requestId` / `remediationHint`, коли вони наявні. | Затвердьте запит в очікуванні: `openclaw devices list`, потім `openclaw devices approve `. Оновлення області доступу/ролі використовують той самий процес після перегляду запитаного доступу. | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштування Control UI. | +| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з auth-токеном Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені затверджені scopes; явні виклики `deviceToken` / `scopes` зберігають запитані scopes. Якщо помилка не зникає, виконайте [контрольний список відновлення після розсинхронізації токена](/uk/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен окремого пристрою застарів або був відкликаний. | Ротуйте/повторно затвердьте токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), потім підключіться знову. | +| `PAIRING_REQUIRED` | Ідентичність пристрою потребує затвердження. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використайте `requestId` / `remediationHint`, якщо вони наявні. | Затвердьте очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. Оновлення scope/ролі використовують той самий процес після перегляду запитаного доступу. | -Прямі RPC бекенду через loopback, автентифіковані спільним токеном/паролем Gateway, не мають залежати від базової області доступу спареного пристрою CLI. Якщо субагенти або інші внутрішні виклики все ще завершуються помилкою `scope-upgrade`, перевірте, що виклик використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примушує явний `deviceIdentity` або токен пристрою. +Прямі RPC до backend через loopback, автентифіковані спільним токеном/паролем Gateway, не мають залежати від базового scope спареного пристрою CLI. Якщо subagents або інші внутрішні виклики все ще завершуються помилкою `scope-upgrade`, перевірте, що викликач використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примусово задає явний `deviceIdentity` або токен пристрою. Перевірка міграції автентифікації пристроїв v2: @@ -242,26 +242,26 @@ openclaw doctor openclaw gateway status ``` -Якщо журнали показують помилки nonce/signature, оновіть клієнт, що підключається, і перевірте його: +Якщо журнали показують помилки nonce/підпису, оновіть клієнт, що підключається, і перевірте його: - + Клієнт чекає на виданий Gateway `connect.challenge`. - + Клієнт підписує payload, прив’язаний до challenge. - + Клієнт надсилає `connect.params.device.nonce` з тим самим challenge nonce. Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхилено: -- сеанси токенів спарених пристроїв можуть керувати лише **власним** пристроєм, якщо виклик також не має `operator.admin` -- `openclaw devices rotate --scope ...` може запитувати лише операторські області доступу, які вже має сеанс виклику +- сесії з токеном спареного пристрою можуть керувати лише **власним** пристроєм, якщо викликач також не має `operator.admin` +- `openclaw devices rotate --scope ...` може запитувати лише операторські scopes, які вже має сесія викликача -Пов’язане: +Пов’язано: - [Конфігурація](/uk/gateway/configuration) (режими автентифікації Gateway) - [Control UI](/uk/web/control-ui) @@ -269,9 +269,9 @@ openclaw gateway status - [Віддалений доступ](/uk/gateway/remote) - [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth) -## Служба Gateway не працює +## Служба Gateway не запущена -Використовуйте це, коли службу встановлено, але процес не утримується запущеним. +Використовуйте це, коли службу встановлено, але процес не залишається запущеним. ```bash openclaw gateway status @@ -283,25 +283,25 @@ openclaw gateway status --deep # also scan system-level services Шукайте: -- `Runtime: stopped` із підказками щодо завершення. +- `Runtime: stopped` з підказками коду завершення. - Невідповідність конфігурації служби (`Config (cli)` проти `Config (service)`). - Конфлікти порту/слухача. -- Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`. +- Додаткові інсталяції launchd/systemd/schtasks, коли використано `--deep`. - Підказки з очищення `Other gateway-like services detected (best effort)`. - - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим Gateway не ввімкнено, або файл конфігурації було перезаписано й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації: `~/.openclaw/openclaw.json`. - - `refusing to bind gateway ... without auth` → прив’язка не до loopback без чинного шляху автентифікації Gateway (токен/пароль або trusted-proxy, якщо налаштовано). + - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим Gateway не ввімкнено, або файл конфігурації було перезаписано й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб відновити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації — `~/.openclaw/openclaw.json`. + - `refusing to bind gateway ... without auth` → прив’язка не до loopback без чинного шляху автентифікації Gateway (токен/пароль або trusted-proxy, де налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. - - `Other gateway-like services detected (best effort)` → існують застарілі або паралельні одиниці launchd/systemd/schtasks. Більшість налаштувань мають тримати один Gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). - - `System-level OpenClaw gateway service detected` від doctor → існує системна одиниця systemd, тоді як служба рівня користувача відсутня. Видаліть або вимкніть дублікат перед тим, як дозволяти doctor встановити користувацьку службу, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо системна одиниця є очікуваним супервізором. - - `Gateway service port does not match current gateway config` → встановлений супервізор досі фіксує старий `--port`. Запустіть `openclaw doctor --fix` або `openclaw gateway install --force`, потім перезапустіть службу Gateway. + - `Other gateway-like services detected (best effort)` → існують застарілі або паралельні одиниці launchd/systemd/schtasks. У більшості налаштувань має бути один Gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочу область. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). + - `System-level OpenClaw gateway service detected` від doctor → існує системна одиниця systemd, тоді як служба рівня користувача відсутня. Видаліть або вимкніть дублікат, перш ніж дозволити doctor встановити користувацьку службу, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо системна одиниця є очікуваним супервізором. + - `Gateway service port does not match current gateway config` → встановлений супервізор усе ще фіксує старий `--port`. Виконайте `openclaw doctor --fix` або `openclaw gateway install --force`, потім перезапустіть службу Gateway. -Пов’язане: +Пов’язано: - [Фонове виконання та інструмент процесів](/uk/gateway/background-process) - [Конфігурація](/uk/gateway/configuration) @@ -323,19 +323,19 @@ openclaw doctor - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` -- Файл `openclaw.json.clobbered.*` із часовою міткою поруч з активною конфігурацією +- Файл `openclaw.json.clobbered.*` з часовою міткою поруч з активною конфігурацією - Системну подію main-agent, що починається з `Config recovery warning` - Відхилена конфігурація не пройшла валідацію під час запуску або гарячого перезавантаження. - OpenClaw зберіг відхилений payload як `.clobbered.*`. - - Активну конфігурацію було відновлено з останньої валідованої копії last-known-good. + - Активну конфігурацію було відновлено з останньої валідованої last-known-good копії. - Наступний хід main-agent отримує попередження не переписувати відхилену конфігурацію наосліп. - - Якщо всі проблеми валідації були під `plugins.entries....`, OpenClaw не відновлював би весь файл. Локальні для Plugin збої залишаються помітними, тоді як непов’язані користувацькі налаштування лишаються в активній конфігурації. + - Якщо всі проблеми валідації були під `plugins.entries....`, OpenClaw не відновлював би весь файл. Локальні збої Plugin залишаються помітними, тоді як непов’язані користувацькі налаштування залишаються в активній конфігурації. - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -345,29 +345,29 @@ openclaw doctor ``` - - Існує `.clobbered.*` → було відновлено зовнішнє пряме редагування або читання під час запуску. - - Існує `.rejected.*` → запис конфігурації, яким керує OpenClaw, не пройшов перевірки схеми або перезапису перед комітом. - - `Config write rejected:` → запис намагався прибрати обов’язкову структуру, різко зменшити файл або зберегти невалідну конфігурацію. - - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запуск розцінив поточний файл як пошкоджений перезаписом, бо він втратив поля або розмір порівняно з резервною копією last-known-good. - - `Config last-known-good promotion skipped` → кандидат містив відредаговані placeholders секретів, як-от `***`. + - `.clobbered.*` існує → зовнішнє пряме редагування або читання під час запуску було відновлено. + - `.rejected.*` існує → запис конфігурації, ініційований OpenClaw, не пройшов схему або перевірки clobber перед комітом. + - `Config write rejected:` → запис намагався вилучити потрібну форму, різко зменшити файл або зберегти невалідну конфігурацію. + - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запуск розцінив поточний файл як перезаписаний, бо він втратив поля або розмір порівняно з last-known-good резервною копією. + - `Config last-known-good promotion skipped` → кандидат містив відредаговані заповнювачі секретів, наприклад `***`. 1. Залиште відновлену активну конфігурацію, якщо вона правильна. 2. Скопіюйте лише потрібні ключі з `.clobbered.*` або `.rejected.*`, потім застосуйте їх через `openclaw config set` або `config.patch`. - 3. Запустіть `openclaw config validate` перед перезапуском. + 3. Виконайте `openclaw config validate` перед перезапуском. 4. Якщо редагуєте вручну, зберігайте повну конфігурацію JSON5, а не лише частковий об’єкт, який хотіли змінити. -Пов’язане: +Пов’язано: - [Config](/uk/cli/config) - [Конфігурація: гаряче перезавантаження](/uk/gateway/configuration#config-hot-reload) -- [Конфігурація: строга валідація](/uk/gateway/configuration#strict-validation) +- [Конфігурація: сувора валідація](/uk/gateway/configuration#strict-validation) - [Doctor](/uk/gateway/doctor) -## Попередження проби Gateway +## Попередження Gateway probe Використовуйте це, коли `openclaw gateway probe` досягає чогось, але все одно друкує блок попереджень. @@ -380,26 +380,26 @@ openclaw gateway probe --ssh user@gateway-host Шукайте: - `warnings[].code` і `primaryTargetId` у виводі JSON. -- Чи попередження стосується fallback SSH, кількох Gateway, відсутніх областей доступу або нерозв’язаних посилань автентифікації. +- Чи попередження стосується резервного SSH, кількох Gateway, відсутніх scopes або нерозв’язаних auth refs. Поширені ознаки: - `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback цілі. -- `multiple reachable gateways detected` → відповіло більше ніж одна ціль. Зазвичай це означає навмисне налаштування з кількома Gateway або застарілі/дубльовані слухачі. -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежено областю доступу; спаруйте ідентичність пристрою або використайте облікові дані з `operator.read`. -- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення спрацювало, але повний набір діагностичних RPC перевищив час очікування або завершився помилкою. Вважайте це досяжним Gateway із погіршеною діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виводі `--json`. -- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне спарювання/затвердження перед звичайним операторським доступом. -- нерозв’язаний текст попередження SecretRef `gateway.auth.*` / `gateway.remote.*` → матеріали автентифікації були недоступні в цьому шляху команди для цілі, що не пройшла. +- `multiple reachable gateways detected` → відповіла більш ніж одна ціль. Зазвичай це означає навмисне налаштування з кількома Gateway або застарілих/дубльованих слухачів. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але детальний RPC обмежено scope; спарте ідентичність пристрою або використайте облікові дані з `operator.read`. +- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення спрацювало, але повний набір діагностичних RPC перевищив час очікування або завершився помилкою. Розглядайте це як досяжний Gateway з погіршеною діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виводі `--json`. +- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне pairing/затвердження перед звичайним операторським доступом. +- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth-матеріал був недоступний у цьому шляху команди для невдалої цілі. -Пов’язане: +Пов’язано: - [Gateway](/uk/cli/gateway) -- [Кілька Gateway на тому самому хості](/uk/gateway#multiple-gateways-same-host) +- [Кілька Gateway на одному хості](/uk/gateway#multiple-gateways-same-host) - [Віддалений доступ](/uk/gateway/remote) ## Канал підключено, повідомлення не проходять -Якщо стан каналу підключений, але потік повідомлень зупинений, зосередьтеся на політиці, дозволах і специфічних для каналу правилах доставки. +Якщо стан каналу підключений, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставлення, специфічних для каналу. ```bash openclaw channels status --probe @@ -411,26 +411,26 @@ openclaw config get channels Шукайте: -- Політику DM (`pairing`, `allowlist`, `open`, `disabled`). -- Список дозволених груп і вимоги щодо згадок. -- Відсутні дозволи/області доступу API каналу. +- Політика DM (`pairing`, `allowlist`, `open`, `disabled`). +- Allowlist груп і вимоги до згадок. +- Відсутні дозволи/scopes API каналу. Поширені ознаки: - `mention required` → повідомлення проігноровано політикою згадок у групі. - `pairing` / трасування очікування схвалення → відправника не схвалено. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією або дозволами каналу. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією/дозволами каналу. Пов’язано: -- [Усунення проблем із каналами](/uk/channels/troubleshooting) +- [Усунення несправностей каналів](/uk/channels/troubleshooting) - [Discord](/uk/channels/discord) - [Telegram](/uk/channels/telegram) - [WhatsApp](/uk/channels/whatsapp) ## Доставка Cron і Heartbeat -Якщо cron або heartbeat не запустився чи не доставив повідомлення, спочатку перевірте стан планувальника, а потім ціль доставки. +Якщо Cron або Heartbeat не запустився чи не доставив повідомлення, спочатку перевірте стан планувальника, а потім ціль доставки. ```bash openclaw cron status @@ -444,17 +444,17 @@ openclaw logs --follow - Cron увімкнено, і наступне пробудження наявне. - Стан історії запусків завдання (`ok`, `skipped`, `error`). -- Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). +- Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). - - `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. - - `cron: timer tick failed` → збій такту планувальника; перевірте помилки файлів, журналів або середовища виконання. + - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. + - `cron: timer tick failed` → збій такту планувальника; перевірте помилки файлів/логів/середовища виконання. - `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. - - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. - - `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися на цьому такті. + - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / заголовки Markdown, тому OpenClaw пропускає виклик моделі. + - `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має бути виконане на цьому такті. - `heartbeat: unknown accountId` → недійсний ідентифікатор облікового запису для цілі доставки Heartbeat. - - `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat зіставлено з призначенням типу DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для окремого агента) встановлено на `block`. + - `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначено як призначення у стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для окремого агента) встановлено на `block`. @@ -463,7 +463,7 @@ openclaw logs --follow - [Heartbeat](/uk/gateway/heartbeat) - [Заплановані завдання](/uk/automation/cron-jobs) -- [Заплановані завдання: усунення проблем](/uk/automation/cron-jobs#troubleshooting) +- [Заплановані завдання: усунення несправностей](/uk/automation/cron-jobs#troubleshooting) ## Node спарено, інструмент не працює @@ -480,25 +480,25 @@ openclaw status Шукайте: - Node онлайн з очікуваними можливостями. -- Надання дозволів ОС для камери, мікрофона, геолокації й екрана. -- Схвалення exec і стан allowlist. +- Надані дозволи ОС для камери/мікрофона/геолокації/екрана. +- Стан схвалень виконання і списку дозволеного. Поширені сигнатури: - `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути на передньому плані. -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → бракує дозволу ОС. -- `SYSTEM_RUN_DENIED: approval required` → exec-схвалення очікується. -- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist. +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС. +- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення виконання. +- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано списком дозволеного. Пов’язано: -- [Exec-схвалення](/uk/tools/exec-approvals) -- [Усунення проблем із Node](/uk/nodes/troubleshooting) +- [Схвалення виконання](/uk/tools/exec-approvals) +- [Усунення несправностей Node](/uk/nodes/troubleshooting) - [Nodes](/uk/nodes/index) ## Інструмент браузера не працює -Використовуйте це, коли дії інструмента браузера не виконуються, хоча сам gateway справний. +Використовуйте це, коли дії інструмента браузера не працюють, хоча сам Gateway справний. ```bash openclaw browser status @@ -513,36 +513,36 @@ openclaw doctor - Чи встановлено `plugins.allow` і чи містить він `browser`. - Дійсний шлях до виконуваного файлу браузера. - Досяжність профілю CDP. -- Доступність локального Chrome для профілів `existing-session` / `user`. +- Наявність локального Chrome для профілів `existing-session` / `user`. - - `unknown command "browser"` або `unknown command 'browser'` → вбудований browser plugin виключено через `plugins.allow`. - - інструмент браузера відсутній / недоступний, тоді як `browser.enabled=true` → `plugins.allow` виключає `browser`, тому plugin ніколи не завантажився. - - `Failed to start Chrome CDP on port` → не вдалося запустити процес браузера. + - `unknown command "browser"` або `unknown command 'browser'` → вбудований браузерний Plugin виключено через `plugins.allow`. + - інструмент браузера відсутній / недоступний, коли `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився. + - `Failed to start Chrome CDP on port` → процес браузера не вдалося запустити. - `browser.executablePath not found` → налаштований шлях недійсний. - - `browser.cdpUrl must be http(s) or ws(s)` → налаштована CDP-URL-адреса використовує непідтримувану схему, наприклад `file:` або `ftp:`. - - `browser.cdpUrl has invalid port` → налаштована CDP-URL-адреса має неправильний порт або порт поза діапазоном. - - `Playwright is not available in this gateway build; '' is unsupported.` → поточне встановлення gateway не має залежності середовища виконання `playwright-core` для вбудованого browser plugin; виконайте `openclaw doctor --fix`, а потім перезапустіть gateway. ARIA-знімки й базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними. + - `browser.cdpUrl must be http(s) or ws(s)` → налаштована URL-адреса CDP використовує непідтримувану схему, наприклад `file:` або `ftp:`. + - `browser.cdpUrl has invalid port` → налаштована URL-адреса CDP має неправильний або поза межами діапазону порт. + - `Playwright is not available in this gateway build; '' is unsupported.` → поточна інсталяція Gateway не має runtime-залежності `playwright-core` із вбудованого браузерного Plugin; виконайте `openclaw doctor --fix`, а потім перезапустіть Gateway. Знімки ARIA та базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними. - - `Could not find DevToolsActivePort for chrome` → existing-session Chrome MCP ще не зміг приєднатися до вибраної теки даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, залиште браузер відкритим, схваліть перший запит на приєднання, потім повторіть спробу. Якщо стан входу не потрібен, віддайте перевагу керованому профілю `openclaw`. - - `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. - - `Remote CDP for profile "" is not reachable` → налаштована віддалена CDP-кінцева точка недосяжна з хоста gateway. - - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для приєднання не має досяжної цілі, або HTTP-кінцева точка відповіла, але CDP WebSocket усе одно не вдалося відкрити. + - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, залиште браузер відкритим, схваліть перший запит на під’єднання, а потім повторіть спробу. Якщо стан входу не потрібен, віддайте перевагу керованому профілю `openclaw`. + - `No Chrome tabs found for profile="user"` → профіль під’єднання Chrome MCP не має відкритих локальних вкладок Chrome. + - `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста Gateway. + - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для під’єднання не має досяжної цілі, або HTTP-кінцева точка відповіла, але WebSocket CDP усе одно не вдалося відкрити. - `fullPage is not supported for element screenshots` → запит знімка екрана поєднав `--full-page` з `--ref` або `--element`. - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі знімка, а не CSS `--element`. - - `existing-session file uploads do not support element selectors; use ref/inputRef.` → хукам завантаження Chrome MCP потрібні посилання зі знімків, а не CSS-селектори. - - `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP. - - `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення тайм-ауту. - - `existing-session type does not support timeoutMs overrides.` → опустіть `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session або використайте керований/CDP-профіль браузера, коли потрібен власний тайм-аут. - - `existing-session evaluate does not support timeoutMs overrides.` → опустіть `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session або використайте керований/CDP-профіль браузера, коли потрібен власний тайм-аут. - - `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або сирого CDP-профілю. - - застарілі перевизначення viewport / dark-mode / locale / offline у профілях лише для приєднання або віддалених CDP-профілях → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування й звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. + - `existing-session file uploads do not support element selectors; use ref/inputRef.` → хукам завантаження Chrome MCP потрібні посилання зі знімка, а не CSS-селектори. + - `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження на виклик у профілях Chrome MCP. + - `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення таймауту. + - `existing-session type does not support timeoutMs overrides.` → не вказуйте `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний таймаут. + - `existing-session evaluate does not support timeoutMs overrides.` → не вказуйте `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний таймаут. + - `response body is not supported for existing-session profiles yet.` → `responsebody` досі потребує керованого браузера або raw CDP-профілю. + - застарілі перевизначення viewport / темного режиму / локалі / офлайн-режиму в профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керувальну сесію та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway. @@ -550,11 +550,11 @@ openclaw doctor Пов’язано: - [Браузер (керований OpenClaw)](/uk/tools/browser) -- [Усунення проблем із браузером](/uk/tools/browser-linux-troubleshooting) +- [Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting) -## Якщо ви оновилися, і щось раптово зламалося +## Якщо ви оновилися й щось раптом зламалося -Більшість збоїв після оновлення спричинена дрейфом конфігурації або суворішими типовими значеннями, які тепер застосовуються. +Більшість збоїв після оновлення спричинені дрейфом конфігурації або суворішими типовими налаштуваннями, які тепер застосовуються. @@ -567,16 +567,16 @@ openclaw doctor Що перевірити: - - Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на віддалений endpoint, тоді як ваш локальний сервіс справний. - - Явні виклики `--url` не повертаються до збережених облікових даних. + - Якщо `gateway.mode=remote`, виклики CLI можуть націлюватися на віддалений сервіс, тоді як ваш локальний сервіс справний. + - Явні виклики з `--url` не повертаються до збережених облікових даних. Поширені сигнатури: - `gateway connect failed:` → неправильна цільова URL-адреса. - - `unauthorized` → endpoint досяжний, але автентифікація неправильна. + - `unauthorized` → кінцева точка досяжна, але автентифікація неправильна. - + ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode @@ -587,16 +587,16 @@ openclaw doctor Що перевірити: - - Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації gateway: автентифікації спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не до loopback. - - Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. + - Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: автентифікації спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не до loopback. + - Старі ключі, як-от `gateway.token`, не замінюють `gateway.auth.token`. Поширені сигнатури: - - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації gateway. - - `Connectivity probe: failed`, поки середовище виконання працює → gateway активний, але недоступний із поточною автентифікацією/URL. + - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації Gateway. + - `Connectivity probe: failed`, коли середовище виконання запущене → Gateway працює, але недоступний із поточною автентифікацією/URL. - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -606,8 +606,8 @@ openclaw doctor Що перевірити: - - Очікувані схвалення пристроїв для dashboard/nodes. - - Очікувані схвалення DM pairing після змін політики або ідентичності. + - Очікувані схвалення пристроїв для панелі керування/Nodes. + - Очікувані схвалення DM-спарення після змін політики або ідентичності. Поширені сигнатури: @@ -617,7 +617,7 @@ openclaw doctor -Якщо конфігурація сервісу й середовище виконання все ще не узгоджуються після перевірок, перевстановіть метадані сервісу з тієї самої теки профілю/стану: +Якщо конфігурація сервісу та runtime все ще не збігаються після перевірок, перевстановіть метадані сервісу з того самого каталогу профілю/стану: ```bash openclaw gateway install --force @@ -627,11 +627,11 @@ openclaw gateway restart Пов’язано: - [Автентифікація](/uk/gateway/authentication) -- [Фоновий exec і інструмент процесу](/uk/gateway/background-process) -- [Pairing, яким володіє Gateway](/uk/gateway/pairing) +- [Фонове виконання та інструмент процесів](/uk/gateway/background-process) +- [Спарення, кероване Gateway](/uk/gateway/pairing) ## Пов’язано - [Doctor](/uk/gateway/doctor) - [FAQ](/uk/help/faq) -- [Gateway runbook](/uk/gateway) +- [Runbook Gateway](/uk/gateway)