From cbda0f587b9162e29db07196fd2317c125345450 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 08:48:46 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/automation/cron-jobs.md | 214 +++--- docs/uk/cli/browser.md | 118 ++-- docs/uk/concepts/queue.md | 74 +- docs/uk/install/migrating-hermes.md | 86 +-- docs/uk/plugins/manifest.md | 1003 +++++++++++++-------------- docs/uk/tools/browser.md | 482 ++++++------- 6 files changed, 980 insertions(+), 997 deletions(-) diff --git a/docs/uk/automation/cron-jobs.md b/docs/uk/automation/cron-jobs.md index e46b16b41..eedbae1aa 100644 --- a/docs/uk/automation/cron-jobs.md +++ b/docs/uk/automation/cron-jobs.md @@ -1,21 +1,21 @@ --- read_when: - Планування фонових завдань або пробуджень - - Підключення зовнішніх тригерів (Webhook-ів, Gmail) до OpenClaw + - Підключення зовнішніх тригерів (Webhook, Gmail) до OpenClaw - Вибір між Heartbeat і Cron для запланованих завдань sidebarTitle: Scheduled tasks -summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway +summary: Заплановані завдання, Webhook та тригери Gmail PubSub для планувальника Gateway title: Заплановані завдання x-i18n: - generated_at: "2026-04-27T08:37:00Z" + generated_at: "2026-04-27T08:45:04Z" model: gpt-5.4 provider: openai - source_hash: 52d48c5d6f19fe9bcaae63afd6a736d953de3f25a710faae9c1ac1df0c081354 + source_hash: a8764103e2d6a9b35b3112e3e95c9570d196c03ed86f4fcdcf4536049a05ac6d source_path: automation/cron-jobs.md workflow: 15 --- -Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у канал чату або на кінцеву точку Webhook. +Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента у потрібний час і може повертати результат назад у канал чату або на endpoint Webhook. ## Швидкий старт @@ -47,38 +47,38 @@ Cron — це вбудований планувальник Gateway. Він зб ## Як працює Cron - Cron працює **всередині процесу Gateway** (а не всередині моделі). -- Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тож перезапуски не призводять до втрати розкладів. -- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення Cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте в gitignore. -- Після цього розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть сприймати завдання як нові, оскільки поля виконання тепер зберігаються в `jobs-state.json`. -- Коли `jobs.json` редагується під час роботи або зупинки Gateway, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного слота виконання й очищає застарілі значення `nextRunAtMs`. Переформатування або переписування лише зі зміною порядку ключів зберігає очікуваний слот. -- Усі виконання Cron створюють записи [фонових завдань](/uk/automation/tasks). -- Одноразові завдання (`--at`) типово автоматично видаляються після успішного виконання. -- Для ізольованих запусків Cron виконує best-effort закриття відстежуваних вкладок/процесів браузера для їхньої сесії `cron:` після завершення запуску, щоб відокремлена автоматизація браузера не залишала сирітські процеси. -- Ізольовані запуски Cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення стану (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw один раз повторно надсилає запит на фактичний результат перед доставкою. -- Ізольовані запуски Cron віддають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім використовують відомі маркери підсумку/виводу, як-от `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не позначалася як успішний запуск. -- Ізольовані запуски Cron також трактують збої агента на рівні запуску як помилки завдання, навіть коли корисне навантаження відповіді відсутнє, тож збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збої замість позначення завдання як успішного. +- Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів. +- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте до gitignore. +- Після розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть трактувати завдання як нові, оскільки поля стану виконання тепер містяться в `jobs-state.json`. +- Коли `jobs.json` редагується під час роботи Gateway або коли він зупинений, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного слота виконання і очищує застарілі значення `nextRunAtMs`. Зміни лише форматування або переписування лише порядку ключів зберігають очікуваний слот. +- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks). +- Одноразові завдання (`--at`) після успішного виконання типово видаляються автоматично. +- Ізольовані запуски cron у режимі best-effort закривають відстежувані вкладки/процеси браузера для їхньої сесії `cron:` після завершення запуску, щоб відокремлена автоматизація браузера не залишала сирітські процеси. +- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw один раз повторно надсилає запит для отримання фактичного результату перед доставкою. +- Ізольовані запуски cron віддають перевагу структурованим метаданим відмови виконання з вбудованого запуску, а потім використовують відомі маркери фінального підсумку/виводу, такі як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не була позначена як успішний запуск. +- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть якщо payload відповіді не створюється, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збої замість того, щоб позначати завдання як успішне. -Узгодження завдань для Cron спочатку належить середовищу виконання, а вже потім спирається на стійку історію: активне завдання Cron лишається активним, доки середовище виконання Cron все ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно середовище виконання перестає володіти завданням і минає 5-хвилинне вікно пільгового часу, перевірки обслуговування звіряють збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця стійка історія показує термінальний результат, журнал завдань фіналізується на її основі; інакше обслуговування, яким володіє Gateway, може позначити завдання як `lost`. Автономний аудит CLI може відновитися зі стійкої історії, але не трактує власний порожній набір активних завдань у процесі як доказ того, що запуск Cron, яким володіє Gateway, зник. +Узгодження завдань для cron насамперед належить runtime, а вже потім спирається на стійку історію: активне завдання cron залишається активним, доки runtime cron і далі відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і минає 5-хвилинне вікно очікування, перевірки обслуговування аналізують збережені журнали запусків і стан завдання для відповідного запуску `cron::`. Якщо ця стійка історія містить термінальний результат, журнал завдань фіналізується на її основі; інакше обслуговування, що належить Gateway, може позначити завдання як `lost`. Автономний аудит CLI може відновитися зі стійкої історії, але не трактує власний порожній внутрішньопроцесний набір активних завдань як доказ того, що запуск cron, яким володіє Gateway, зник. ## Типи розкладу -| Вид | Прапорець CLI | Опис | -| ------- | ------------- | ------------------------------------------------------- | +| Вид | Прапорець CLI | Опис | +| ------- | ------------- | ---------------------------------------------------------- | | `at` | `--at` | Одноразова мітка часу (ISO 8601 або відносна, наприклад `20m`) | -| `every` | `--every` | Фіксований інтервал | -| `cron` | `--cron` | 5-польовий або 6-польовий cron-вираз з необов’язковим `--tz` | +| `every` | `--every` | Фіксований інтервал | +| `cron` | `--cron` | Cron-вираз із 5 або 6 полів з необов’язковим `--tz` | -Мітки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за місцевим часом. +Мітки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним часом. -Періодичні вирази на початок години автоматично розподіляються зі зсувом до 5 хвилин, щоб зменшити пікове навантаження. Використовуйте `--exact`, щоб примусово встановити точний час, або `--stagger 30s` для явного вікна. +Періодичні вирази на початок кожної години автоматично розподіляються зі зсувом до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово встановити точний час, або `--stagger 30s` для явного вікна. -### День місяця та день тижня використовують логіку OR +### День місяця і день тижня використовують логіку OR -Cron-вирази розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner знаходить збіг, коли **збігається будь-яке** з полів, а не обидва. Це стандартна поведінка Vixie cron. +Cron-вирази розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner вважає вираз таким, що збігається, коли збігається **будь-яке** з цих полів — а не обидва. Це стандартна поведінка Vixie cron. ``` # Intended: "9 AM on the 15th, only if it's a Monday" @@ -86,34 +86,34 @@ Cron-вирази розбираються за допомогою [croner](http 0 9 15 * 1 ``` -Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує стандартну OR-поведінку Croner. Щоб вимагати виконання обох умов, використайте модифікатор дня тижня `+` у Croner (`0 9 15 * +1`) або заплануйте за одним полем, а іншу умову перевіряйте в запиті чи команді вашого завдання. +Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує типову OR-поведінку Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` із Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання. ## Стилі виконання -| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | -| --------------- | -------------------- | ------------------------ | -------------------------------- | -| Основна сесія | `main` | Наступного Heartbeat | Нагадувань, системних подій | -| Ізольований | `isolated` | Окремій `cron:` | Звітів, фонових задач | -| Поточна сесія | `current` | Прив’язується під час створення | Періодичної роботи з контекстом | -| Власна сесія | `session:custom-id` | Постійній іменованій сесії | Робочих процесів, що будуються на історії | +| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | +| -------------- | -------------------- | ------------------------- | ------------------------------- | +| Основна сесія | `main` | Наступний такт Heartbeat | Нагадувань, системних подій | +| Ізольований | `isolated` | Окремий `cron:` | Звітів, фонових завдань | +| Поточна сесія | `current` | Прив’язується під час створення | Періодичної роботи з контекстом | +| Власна сесія | `session:custom-id` | Постійна іменована сесія | Робочих процесів, що накопичують історію | - Завдання **основної сесії** ставлять системну подію в чергу й за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Такі системні події не подовжують актуальність щоденного/idle скидання для цільової сесії. **Ізольовані** завдання запускають окремий хід агента зі свіжою сесією. **Власні сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу будувати робочі процеси на кшталт щоденних стендапів на основі попередніх підсумків. + Завдання **основної сесії** ставлять системну подію в чергу й за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують актуальність щоденного/неактивного скидання для цільової сесії. **Ізольовані** завдання виконують окремий такт агента з новою сесією. **Власні сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу реалізувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. - - Для ізольованих завдань «свіжа сесія» означає новий ідентифікатор транскрипту/сесії для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення моделі/автентифікації, але не успадковує фоновий контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищення прав, походження або прив’язку середовища виконання ACP. Використовуйте `current` або `session:`, коли періодичне завдання має навмисно розвиватися в межах того самого контексту розмови. + + Для ізольованих завдань «нова сесія» означає новий ідентифікатор transcript/session для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явні перевизначення моделі/автентифікації, вибрані користувачем, але не успадковує фоновий контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищені привілеї, origin або прив’язку runtime ACP. Використовуйте `current` або `session:`, якщо періодичне завдання має свідомо продовжувати той самий контекст розмови. - - Для ізольованих завдань завершення середовища виконання тепер також включає best-effort очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, щоб фактичний результат Cron усе одно залишався визначальним. + + Для ізольованих завдань завершення runtime тепер включає best-effort очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, тому фактичний результат cron усе одно має пріоритет. - Ізольовані запуски Cron також звільняють усі вбудовані екземпляри середовища виконання MCP, створені для завдання, через спільний шлях очищення середовища виконання. Це відповідає тому, як завершується робота клієнтів MCP для основної та власної сесій, тож ізольовані Cron-завдання не залишають процеси stdio child або довготривалі MCP-з’єднання між запусками. + Ізольовані запуски cron також звільняють будь-які екземпляри runtime MCP, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як завершується робота клієнтів MCP основної сесії та власних сесій, тому ізольовані cron-завдання не спричиняють витоків дочірніх stdio-процесів або довготривалих MCP-з’єднань між запусками. - - Коли ізольовані запуски Cron оркеструють субагентів, під час доставки також надається перевага фінальному виводу дочірнього нащадка, а не застарілому проміжному тексту батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського запуску, замість того щоб оголошувати його. + + Коли ізольовані запуски cron оркеструють субагентів, доставка також віддає перевагу фінальному виводу нащадка замість застарілого проміжного тексту батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського запуску замість того, щоб оголошувати його. - Для цілей оголошення в Discord, що підтримують лише текст, OpenClaw надсилає канонічний фінальний текст асистента один раз, замість повторного відтворення як потокових/проміжних текстових payload-ів, так і фінальної відповіді. Медіа та структуровані payload-и Discord, як і раніше, доставляються окремо, щоб не втрачалися вкладення та компоненти. + Для цілей оголошення Discord лише з текстом OpenClaw надсилає канонічний фінальний текст помічника один раз замість повторного програвання і потокового/проміжного текстового payload, і фінальної відповіді. Медіа та структуровані payload Discord, як і раніше, доставляються окремими payload, щоб не втрачалися вкладення й компоненти. @@ -121,7 +121,7 @@ Cron-вирази розбираються за допомогою [croner](http ### Параметри payload для ізольованих завдань - Текст запиту (обов’язковий для ізольованих). + Текст prompt (обов’язковий для isolated). Перевизначення моделі; використовує вибрану дозволену модель для завдання. @@ -130,46 +130,46 @@ Cron-вирази розбираються за допомогою [croner](http Перевизначення рівня thinking. - Пропустити ін’єкцію файлів початкового налаштування робочого простору. + Пропустити ін’єкцію bootstrap-файла робочого простору. - Обмежити інструменти, які може використовувати завдання, наприклад `--tools exec,read`. + Обмежити, які інструменти може використовувати завдання, наприклад `--tools exec,read`. -`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, Cron записує попередження в журнал і замість цього повертається до вибору моделі агента/типової моделі для завдання. Налаштовані ланцюжки резервних варіантів, як і раніше, застосовуються, але просте перевизначення моделі без явного списку резервних варіантів для завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. +`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/типової моделі для завдання. Налаштовані ланцюжки fallback як і раніше застосовуються, але просте перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби. Пріоритет вибору моделі для ізольованих завдань: -1. Перевизначення моделі Gmail hook (коли запуск походить із Gmail і це перевизначення дозволене) -2. `model` у payload завдання -3. Збережене перевизначення моделі сесії Cron, вибране користувачем +1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) +2. `model` у payload конкретного завдання +3. Збережене перевизначення моделі cron-сесії, вибране користувачем 4. Вибір моделі агента/типової моделі -Швидкий режим також дотримується визначеного активного вибору. Якщо в конфігурації вибраної моделі задано `params.fastMode`, ізольований Cron типово використовує це значення. Збережене перевизначення `fastMode` для сесії все одно має вищий пріоритет над конфігурацією в будь-якому напрямку. +Швидкий режим також наслідує визначений актуальний вибір. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron типово використовує це значення. Збережене перевизначення сесії `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках. -Якщо ізольований запуск стикається з передачею на живе перемикання моделі, Cron повторює спробу з перемкненим провайдером/моделлю та зберігає цей активний вибір для поточного запуску перед повторною спробою. Коли перемикання також містить новий профіль автентифікації, Cron теж зберігає це перевизначення профілю автентифікації для поточного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб перемикання Cron перериває роботу, замість того щоб зациклитися назавжди. +Якщо ізольований запуск під час роботи натрапляє на передачу керування через перемикання моделі, cron повторює спробу з перемкненим провайдером/моделлю та зберігає цей актуальний вибір для поточного запуску перед повторною спробою. Якщо перемикання також містить новий профіль автентифікації, cron теж зберігає це перевизначення профілю автентифікації для поточного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб із перемиканням cron перериває виконання замість нескінченного циклу. -## Доставка та вивід +## Доставка і вивід -| Режим | Що відбувається | -| ---------- | ------------------------------------------------------------------ | -| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент його не надіслав | -| `webhook` | Надсилає payload завершеної події методом POST на URL | -| `none` | Без резервної доставки з боку виконавця | +| Режим | Що відбувається | +| ---------- | ----------------------------------------------------------------- | +| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент не надіслав його | +| `webhook` | Надсилає payload події завершення через POST на URL | +| `none` | Немає резервної доставки з боку виконавця | Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:`, `user:`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ідентифікатор кімнати або форму `room:!room:server` із Matrix. -Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли для завдання задано `--no-deliver`. Якщо агент надсилає повідомлення в налаштовану/поточну ціль, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` лише визначають, що виконавець робить із фінальною відповіддю після ходу агента. +Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` керують лише тим, що виконавець робить із фінальною відповіддю після такту агента. -Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену активну ціль доставки для маршруту резервного оголошення. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставки провайдера не реконструюються з цих ключів, коли доступний контекст поточного чату. +Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену актуальну ціль доставки для маршруту резервного оголошення. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставки провайдера не відновлюються з цих ключів, коли доступний поточний контекст чату. -Сповіщення про збої йдуть окремим маршрутом призначення: +Сповіщення про збої використовують окремий шлях призначення: -- `cron.failureDestination` задає глобове типове значення для сповіщень про збої. +- `cron.failureDestination` задає глобальне типове місце призначення для сповіщень про збої. - `job.delivery.failureDestination` перевизначає його для окремого завдання. -- Якщо не задано жодного з них, а завдання вже доставляється через `announce`, сповіщення про збої тепер резервно надсилаються до цієї основної цілі оголошення. +- Якщо не задано жодного з них і завдання вже доставляє результати через `announce`, сповіщення про збої тепер резервно використовують цю основну ціль оголошення. - `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`. -- `failureAlert.includeSkipped: true` дозволяє для завдання або глобальної політики сповіщень Cron повторювані сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому не впливають на відкладення після помилок виконання. +- `failureAlert.includeSkipped: true` дає змогу для завдання або глобальної політики сповіщень cron повторювати сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому вони не впливають на backoff для помилок виконання. ## Приклади CLI @@ -212,9 +212,9 @@ Cron-вирази розбираються за допомогою [croner](http -## Webhook-и +## Webhook -Gateway може відкривати HTTP-кінцеві точки Webhook для зовнішніх тригерів. Увімкніть це в конфігурації: +Gateway може відкривати HTTP endpoint-и Webhook для зовнішніх тригерів. Увімкніть це в конфігурації: ```json5 { @@ -233,11 +233,11 @@ Gateway може відкривати HTTP-кінцеві точки Webhook д - `Authorization: Bearer ` (рекомендовано) - `x-openclaw-token: ` -Токени в query-string відхиляються. +Токени в рядку запиту відхиляються. - Додає системну подію в чергу для основної сесії: + Поставити системну подію в чергу для основної сесії: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -255,7 +255,7 @@ Gateway може відкривати HTTP-кінцеві точки Webhook д - Запускає ізольований хід агента: + Запустити ізольований такт агента: ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -264,23 +264,23 @@ Gateway може відкривати HTTP-кінцеві точки Webhook д -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}' ``` - Поля: `message` (обов’язкове), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`. + Поля: `message` (обов’язково), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`. - Власні назви hook-ів зіставляються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload-и на дії `wake` або `agent` за допомогою шаблонів або перетворень коду. + Власні назви hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload у дії `wake` або `agent` за допомогою шаблонів або кодових трансформацій. -Тримайте кінцеві точки hook за loopback, tailnet або довіреним reverse proxy. +Тримайте endpoint-и hook-ів за loopback, tailnet або довіреним зворотним проксі. - Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway. - Тримайте `hooks.path` на окремому підшляху; `/` відхиляється. -- Встановіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. -- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, які вибирає викликач. -- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також встановіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесій. -- Payload-и hook-ів типово обгортаються межами безпеки. +- Установіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. +- Тримайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. +- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесії. +- Payload hook-ів типово обгортаються межами безпеки. ## Інтеграція Gmail PubSub @@ -288,26 +288,26 @@ Gateway може відкривати HTTP-кінцеві точки Webhook д Підключіть тригери вхідних Gmail до OpenClaw через Google PubSub. -**Передумови:** CLI `gcloud`, `gog` (gogcli), увімкнені hook-и OpenClaw, Tailscale для публічної HTTPS-кінцевої точки. +**Передумови:** CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint. -### Налаштування майстром (рекомендовано) +### Налаштування через майстер (рекомендовано) ```bash openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Це записує конфігурацію `hooks.gmail`, вмикає Gmail preset і використовує Tailscale Funnel для push-кінцевої точки. +Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push endpoint. ### Автозапуск Gateway -Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час завантаження запускає `gog gmail watch serve` і автоматично поновлює watch. Щоб відмовитися від цього, встановіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`. +Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час запуску запускає `gog gmail watch serve` і автоматично поновлює watch. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися від цього. ### Ручне одноразове налаштування - Виберіть проєкт GCP, якому належить OAuth-клієнт, що використовується `gog`: + Виберіть проєкт GCP, якому належить клієнт OAuth, що використовується `gog`: ```bash gcloud auth login @@ -356,13 +356,13 @@ openclaw cron list # Показати одне завдання, включно з визначеним маршрутом доставки openclaw cron show -# Редагувати завдання +# Відредагувати завдання openclaw cron edit --message "Updated prompt" --model "opus" # Примусово запустити завдання зараз openclaw cron run -# Запустити лише якщо настав час +# Запустити лише якщо час настав openclaw cron run --due # Переглянути історію запусків @@ -371,18 +371,18 @@ openclaw cron runs --id --limit 50 # Видалити завдання openclaw cron remove -# Вибір агента (у конфігураціях із кількома агентами) +# Вибір агента (конфігурації з кількома агентами) openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` -Примітка про перевизначення моделі: +Примітка щодо перевизначення моделі: - `openclaw cron add|edit --model ...` змінює вибрану модель завдання. -- Якщо модель дозволена, саме ця пара провайдер/модель потрапляє до ізольованого запуску агента. -- Якщо вона не дозволена, cron попереджає й повертається до вибору моделі агента/типової моделі для завдання. -- Налаштовані ланцюжки резервних варіантів, як і раніше, застосовуються, але просте перевизначення `--model` без явного списку резервних варіантів для завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби. +- Якщо модель дозволена, саме цей провайдер/модель потрапляє до ізольованого запуску агента. +- Якщо вона не дозволена, cron показує попередження і повертається до вибору моделі агента/типової моделі завдання. +- Налаштовані ланцюжки fallback як і раніше застосовуються, але просте перевизначення `--model` без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби. ## Конфігурація @@ -405,29 +405,29 @@ openclaw cron edit --clear-agent } ``` -`maxConcurrentRuns` обмежує як заплановане диспетчеризування cron, так і виконання ізольованих ходів агента. Ізольовані ходи агента cron внутрішньо використовують lane виконання `nested` у черзі, тому збільшення цього значення дає змогу незалежним запуском Cron LLM просуватися паралельно, а не лише запускати їхні зовнішні обгортки cron. +`maxConcurrentRuns` обмежує як запланований dispatch cron, так і виконання ізольованих тактів агента. Ізольовані такти агента cron внутрішньо використовують окрему чергу виконання `cron-nested`, тому збільшення цього значення дає змогу незалежним cron-запускам LLM просуватися паралельно, а не лише запускати їхні зовнішні cron-обгортки. Спільна некронова смуга `nested` цим параметром не розширюється. -Sidecar стану виконання виводиться з `cron.store`: сховище `.json`, таке як `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, тоді як до шляху сховища без суфікса `.json` додається `-state.json`. +Стан runtime у sidecar-файлі визначається на основі `cron.store`: для сховища `.json`, такого як `~/clawd/cron/jobs.json`, використовується `~/clawd/cron/jobs-state.json`, а для шляху сховища без суфікса `.json` додається `-state.json`. -Якщо ви редагуєте `jobs.json` вручну, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для очікуваних слотів, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка підказує планувальнику, коли завданню, відредагованому зовні, потрібен свіжий `nextRunAtMs`. +Якщо ви редагуєте `jobs.json` вручну, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для очікуваних слотів, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка повідомляє планувальнику, коли завданню, відредагованому поза системою, потрібен новий `nextRunAtMs`. Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. - **Повторна спроба для одноразового завдання**: тимчасові помилки (ліміт запитів, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційною затримкою. Постійні помилки вимикають завдання негайно. + **Повторна спроба одноразового завдання**: тимчасові помилки (ліміт швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикають завдання негайно. - **Повторна спроба для періодичного завдання**: експоненційна затримка (від 30 с до 60 хв) між повторними спробами. Затримка скидається після наступного успішного запуску. + **Повторна спроба періодичного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску. - `cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналу запусків. + `cron.sessionRetention` (типово `24h`) очищує записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищують файли журналів запусків. ## Усунення несправностей -### Послідовність команд +### Ланцюжок команд ```bash openclaw status @@ -444,32 +444,32 @@ openclaw doctor - Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`. - Переконайтеся, що Gateway працює безперервно. - - Для розкладів `cron` перевірте часовий пояс (`--tz`) відносно часового поясу хоста. - - `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due`, але час для завдання ще не настав. + - Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста. + - `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due` і час завдання ще не настав. - - Режим доставки `none` означає, що резервне надсилання з боку виконавця не очікується. Агент усе ще може надсилати напряму через інструмент `message`, коли маршрут чату доступний. - - Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено. - - Для Matrix скопійовані або застарілі завдання з ідентифікаторами кімнат `delivery.to` у нижньому регістрі можуть не спрацювати, оскільки ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` із Matrix. + - Режим доставки `none` означає, що резервне надсилання з боку виконавця не очікується. Агент усе ще може надсилати повідомлення напряму через інструмент `message`, коли доступний маршрут чату. + - Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідну доставку було пропущено. + - Для Matrix скопійовані або застарілі завдання з room ID у `delivery.to`, записаними в нижньому регістрі, можуть не працювати, оскільки ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` із Matrix. - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку було заблоковано обліковими даними. - - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне надсилання, а також резервний шлях підсумку через чергу, тож назад у чат нічого не публікується. - - Якщо агент має сам написати користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль). + - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також резервний шлях queued summary, тому в чат нічого не буде опубліковано. + - Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` з попереднім чатом або явний канал/ціль). - - - Актуальність щоденного та idle скидання не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). - - Пробудження Cron, запуски Heartbeat, сповіщення exec і службові дії gateway можуть оновлювати рядок сесії для маршрутизації/стану, але не подовжують `sessionStartedAt` або `lastInteractionAt`. - - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії transcript JSONL, якщо файл усе ще доступний. Для застарілих idle-рядків без `lastInteractionAt` як idle-базову мітку використовується цей відновлений час початку. + + - Актуальність щоденного скидання та скидання за неактивністю не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle). + - Пробудження cron, запуски heartbeat, сповіщення exec і службові операції gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`. + - Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії в JSONL transcript, якщо файл усе ще доступний. Застарілі неактивні рядки без `lastInteractionAt` використовують цей відновлений час початку як базу неактивності. - + - Cron без `--tz` використовує часовий пояс хоста gateway. - Розклади `at` без часового поясу трактуються як UTC. - - `activeHours` у Heartbeat використовує визначення часового поясу з конфігурації. + - `activeHours` Heartbeat використовує налаштоване визначення часового поясу. ## Пов’язане -- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації з першого погляду +- [Автоматизація і завдання](/uk/automation) — усі механізми автоматизації з одного погляду - [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron -- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії +- [Heartbeat](/uk/gateway/heartbeat) — періодичні такти основної сесії - [Часовий пояс](/uk/concepts/timezone) — конфігурація часового поясу diff --git a/docs/uk/cli/browser.md b/docs/uk/cli/browser.md index bd7b2fcac..25db991f8 100644 --- a/docs/uk/cli/browser.md +++ b/docs/uk/cli/browser.md @@ -1,35 +1,35 @@ --- read_when: - - Ви використовуєте `openclaw browser` і хочете приклади для поширених завдань - - Ви хочете керувати браузером, що працює на іншій машині, через хост node - - Ви хочете підключитися до свого локального Chrome, у якому вже виконано вхід, через Chrome MCP + - Ви використовуєте `openclaw browser` і хочете приклади для типових завдань + - Ви хочете керувати браузером, що працює на іншій машині, через вузол-хост + - Ви хочете під’єднатися до вашого локального Chrome із виконаним входом через Chrome MCP summary: Довідник CLI для `openclaw browser` (життєвий цикл, профілі, вкладки, дії, стан і налагодження) title: Браузер x-i18n: - generated_at: "2026-04-26T03:54:40Z" + generated_at: "2026-04-27T08:45:03Z" model: gpt-5.4 provider: openai - source_hash: b42511e841e768bfa4031463f213d78c67d5c63efb655a90f65c7e8c71da9881 + source_hash: c7b5112c61e8289ab6a02bc30c9aefe640c053271f82197c0ee810b4a5efa580 source_path: cli/browser.md workflow: 15 --- # `openclaw browser` -Керуйте поверхнею керування браузером OpenClaw і виконуйте дії браузера (життєвий цикл, профілі, вкладки, знімки, знімки екрана, навігація, введення, емуляція стану та налагодження). +Керуйте поверхнею керування браузером OpenClaw і виконуйте дії браузера (життєвий цикл, профілі, вкладки, знімки, скриншоти, навігація, введення, емуляція стану та налагодження). Пов’язане: -- Інструмент і API браузера: [Інструмент браузера](/uk/tools/browser) +- Інструмент Browser + API: [інструмент Browser](/uk/tools/browser) ## Поширені прапорці -- `--url `: URL Gateway WebSocket (типово береться з конфігурації). -- `--token `: токен Gateway (якщо потрібен). +- `--url `: URL WebSocket Gateway (типово з конфігурації). +- `--token `: токен Gateway (за потреби). - `--timeout `: тайм-аут запиту (мс). - `--expect-final`: чекати на фінальну відповідь Gateway. -- `--browser-profile `: вибрати профіль браузера (типовий береться з конфігурації). -- `--json`: машинозчитуваний вивід (де підтримується). +- `--browser-profile `: вибрати профіль браузера (типовий — із конфігурації). +- `--json`: машиночитаний вивід (де підтримується). ## Швидкий старт (локально) @@ -40,11 +40,11 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Агенти можуть виконати таку саму перевірку готовності за допомогою `browser({ action: "doctor" })`. +Агенти можуть виконати ту саму перевірку готовності за допомогою `browser({ action: "doctor" })`. ## Швидке усунення несправностей -Якщо `start` завершується помилкою `not reachable after start`, спочатку усуньте проблеми з готовністю CDP. Якщо `start` і `tabs` працюють, але `open` або `navigate` завершується помилкою, то площина керування браузером справна, а збій зазвичай пов’язаний із політикою SSRF навігації. +Якщо `start` завершується помилкою `not reachable after start`, спочатку усуньте проблему з готовністю CDP. Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером справна, а причина збою зазвичай полягає в політиці SSRF для навігації. Мінімальна послідовність: @@ -55,7 +55,7 @@ openclaw browser --browser-profile openclaw tabs openclaw browser --browser-profile openclaw open https://example.com ``` -Докладні вказівки: [Усунення несправностей браузера](/uk/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block) +Детальні вказівки: [усунення несправностей Browser](/uk/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block) ## Життєвий цикл @@ -71,17 +71,19 @@ openclaw browser --browser-profile openclaw reset-profile Примітки: -- `doctor --deep` додає live-перевірку знімка. Це корисно, коли базова готовність CDP зелена, але вам потрібне підтвердження, що поточну вкладку можна інспектувати. -- Для профілів `attachOnly` і віддалених профілів CDP `openclaw browser stop` закриває активну сесію керування та скидає тимчасові перевизначення емуляції, навіть якщо OpenClaw не запускав процес браузера самостійно. +- `doctor --deep` додає перевірку живого знімка. Це корисно, коли базова готовність CDP позначена як справна, але вам потрібне підтвердження, що поточну вкладку можна інспектувати. +- Для профілів `attachOnly` і віддалених профілів CDP команда `openclaw browser stop` закриває активну сесію керування та скидає тимчасові перевизначення емуляції, навіть якщо OpenClaw не запускав процес браузера самостійно. - Для локальних керованих профілів `openclaw browser stop` зупиняє запущений процес браузера. -- `openclaw browser start --headless` застосовується лише до цього запиту запуску і лише коли OpenClaw запускає локальний керований браузер. Це не переписує `browser.headless` або конфігурацію профілю й не має ефекту для вже запущеного браузера. -- На Linux-хостах без `DISPLAY` або `WAYLAND_DISPLAY` локальні керовані профілі автоматично працюють у режимі headless, якщо тільки `OPENCLAW_BROWSER_HEADLESS=0`, `browser.headless=false` або `browser.profiles..headless=false` явно не вимагає видимий браузер. +- `openclaw browser start --headless` застосовується лише до цього запиту запуску й лише тоді, коли OpenClaw запускає локальний керований браузер. Це не переписує `browser.headless` або конфігурацію профілю й не має ефекту для браузера, який уже працює. +- На Linux-хостах без `DISPLAY` або `WAYLAND_DISPLAY` локальні керовані профілі автоматично працюють у режимі headless, якщо лише `OPENCLAW_BROWSER_HEADLESS=0`, `browser.headless=false` або `browser.profiles..headless=false` явно не вимагає видимого браузера. ## Якщо команда відсутня -Якщо `openclaw browser` є невідомою командою, перевірте `plugins.allow` у `~/.openclaw/openclaw.json`. +Якщо `openclaw browser` є невідомою командою, перевірте `plugins.allow` у +`~/.openclaw/openclaw.json`. -Коли `plugins.allow` присутній, вбудований Plugin браузера має бути явно вказаний у списку: +Коли `plugins.allow` присутній, явно перелічіть вбудований плагін браузера, +якщо лише конфігурація вже не містить кореневий блок `browser`: ```json5 { @@ -91,17 +93,19 @@ openclaw browser --browser-profile openclaw reset-profile } ``` -`browser.enabled=true` не відновлює підкоманду CLI, коли список дозволених Plugin не містить `browser`. +Явний кореневий блок `browser`, наприклад `browser.enabled=true` або +`browser.profiles.`, також активує вбудований плагін браузера за +обмежувального allowlist плагінів. -Пов’язане: [Інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool) +Пов’язане: [інструмент Browser](/uk/tools/browser#missing-browser-command-or-tool) ## Профілі Профілі — це іменовані конфігурації маршрутизації браузера. На практиці: -- `openclaw`: запускає або підключається до окремого екземпляра Chrome під керуванням OpenClaw (ізольований каталог користувацьких даних). -- `user`: керує вашою наявною сесією Chrome, у якій уже виконано вхід, через Chrome DevTools MCP. -- власні профілі CDP: вказують на локальну або віддалену кінцеву точку CDP. +- `openclaw`: запускає або під’єднується до окремого екземпляра Chrome, керованого OpenClaw (ізольований каталог даних користувача). +- `user`: керує вашою наявною сесією Chrome із виконаним входом через Chrome DevTools MCP. +- спеціальні профілі CDP: вказують на локальну або віддалену кінцеву точку CDP. ```bash openclaw browser profiles @@ -130,9 +134,17 @@ openclaw browser focus docs openclaw browser close t1 ``` -`tabs` спочатку повертає `suggestedTargetId`, потім стабільний `tabId`, наприклад `t1`, необов’язкову мітку та сирий `targetId`. Агенти мають передавати `suggestedTargetId` назад у `focus`, `close`, знімки та дії. Ви можете призначити мітку через `open --label`, `tab new --label` або `tab label`; підтримуються мітки, ідентифікатори вкладок, сирі ідентифікатори цілей і унікальні префікси target-id. Коли Chromium замінює базову сиру ціль під час навігації або надсилання форми, OpenClaw зберігає стабільний `tabId`/мітку, прив’язану до вкладки-замінника, коли може підтвердити відповідність. Сирі target-id залишаються нестабільними; надавайте перевагу `suggestedTargetId`. +`tabs` спочатку повертає `suggestedTargetId`, потім стабільний `tabId`, наприклад `t1`, +необов’язкову мітку та сирий `targetId`. Агенти мають передавати +`suggestedTargetId` назад у `focus`, `close`, знімки та дії. Ви можете +призначити мітку за допомогою `open --label`, `tab new --label` або `tab label`; мітки, +ідентифікатори вкладок, сирі ідентифікатори цілей і унікальні префікси target-id — усе це приймається. +Коли Chromium замінює базову сиру ціль під час навігації або надсилання форми, +OpenClaw зберігає стабільний `tabId`/мітку прив’язаними до вкладки-замінника, +коли може довести збіг. Сирі ідентифікатори цілей залишаються нестабільними; віддавайте перевагу +`suggestedTargetId`. -## Знімок / знімок екрана / дії +## Знімок / скриншот / дії Знімок: @@ -141,7 +153,7 @@ openclaw browser snapshot openclaw browser snapshot --urls ``` -Знімок екрана: +Скриншот: ```bash openclaw browser screenshot @@ -152,12 +164,15 @@ openclaw browser screenshot --labels Примітки: -- `--full-page` призначений лише для захоплення сторінки; його не можна поєднувати з `--ref` або `--element`. -- Профілі `existing-session` / `user` підтримують знімки екрана сторінки та знімки екрана з `--ref` із виводу знімка, але не підтримують знімки екрана CSS `--element`. -- `--labels` накладає поточні refs зі знімка на знімок екрана. -- `snapshot --urls` додає виявлені адреси посилань до AI-знімків, щоб агенти могли вибирати прямі цілі навігації замість припущень лише за текстом посилання. +- `--full-page` призначений лише для захоплення сторінок; його не можна поєднувати з `--ref` + або `--element`. +- Профілі `existing-session` / `user` підтримують скриншоти сторінок і скриншоти `--ref` + з виводу знімка, але не скриншоти CSS `--element`. +- `--labels` накладає поточні посилання знімка на скриншот. +- `snapshot --urls` додає виявлені адреси посилань до AI-знімків, щоб + агенти могли вибирати прямі цілі навігації замість того, щоб вгадувати лише за текстом посилання. -Навігація/клік/введення (автоматизація UI на основі ref): +Navigate/click/type (автоматизація UI на основі ref): ```bash openclaw browser navigate https://example.com @@ -174,7 +189,9 @@ openclaw browser wait --text "Done" openclaw browser evaluate --fn '(el) => el.textContent' --ref ``` -Відповіді на дії повертають поточний сирий `targetId` після заміни сторінки, спричиненої дією, коли OpenClaw може підтвердити вкладку-замінник. Скрипти все одно мають зберігати й передавати `suggestedTargetId`/мітки для довготривалих робочих процесів. +Відповіді дій повертають поточний сирий `targetId` після заміни сторінки, спричиненої дією, +коли OpenClaw може довести вкладку-замінник. Скрипти все одно мають +зберігати й передавати `suggestedTargetId`/мітки для довготривалих робочих процесів. Допоміжні команди для файлів і діалогів: @@ -185,7 +202,10 @@ openclaw browser download report.pdf openclaw browser dialog --accept ``` -Керовані профілі Chrome зберігають звичайні завантаження, ініційовані кліком, до каталогу завантажень OpenClaw (`/tmp/openclaw/downloads` типово або налаштований тимчасовий корінь). Використовуйте `waitfordownload` або `download`, коли агенту потрібно дочекатися конкретного файла й повернути його шлях; ці явні очікувачі керують наступним завантаженням. +Керовані профілі Chrome зберігають звичайні завантаження, ініційовані кліком, до каталогу завантажень OpenClaw +(типово `/tmp/openclaw/downloads` або налаштований тимчасовий +корінь). Використовуйте `waitfordownload` або `download`, коли агенту потрібно дочекатися +певного файлу та повернути його шлях; ці явні очікувачі беруть на себе наступне завантаження. ## Стан і сховище @@ -239,32 +259,36 @@ openclaw browser create-profile --name brave-live --driver existing-session --us openclaw browser --browser-profile chrome-live tabs ``` -Цей шлях працює лише на хості. Для Docker, headless-серверів, Browserless або інших віддалених налаштувань використовуйте профіль CDP. +Цей шлях працює лише на хості. Для Docker, headless-серверів, Browserless або інших віддалених конфігурацій використовуйте профіль CDP. Поточні обмеження existing-session: -- дії на основі знімків використовують refs, а не селектори CSS -- `browser.actionTimeoutMs` встановлює типовий тайм-аут 60000 мс для підтримуваних запитів `act`, коли виклики не передають `timeoutMs`; `timeoutMs` для окремого виклику все одно має пріоритет. +- дії на основі знімків використовують ref, а не CSS-селектори +- `browser.actionTimeoutMs` встановлює для підтримуваних запитів `act` типове значення 60000 мс, коли + виклики не передають `timeoutMs`; значення `timeoutMs` для конкретного виклику все одно має пріоритет. - `click` підтримує лише клік лівою кнопкою - `type` не підтримує `slowly=true` - `press` не підтримує `delayMs` -- `hover`, `scrollintoview`, `drag`, `select`, `fill` і `evaluate` відхиляють перевизначення тайм-ауту для окремого виклику +- `hover`, `scrollintoview`, `drag`, `select`, `fill` і `evaluate` відхиляють + перевизначення тайм-ауту для окремого виклику - `select` підтримує лише одне значення - `wait --load networkidle` не підтримується -- завантаження файлів вимагає `--ref` / `--input-ref`, не підтримує CSS `--element` і наразі підтримує один файл за раз +- завантаження файлів вимагає `--ref` / `--input-ref`, не підтримує CSS + `--element` і наразі підтримує по одному файлу за раз - хуки діалогів не підтримують `--timeout` -- знімки екрана підтримують захоплення сторінки та `--ref`, але не CSS `--element` -- `responsebody`, перехоплення завантажень, експорт PDF і пакетні дії все ще потребують керованого браузера або сирого профілю CDP +- скриншоти підтримують захоплення сторінок і `--ref`, але не CSS `--element` +- `responsebody`, перехоплення завантажень, експорт PDF і пакетні дії все ще + вимагають керованого браузера або сирого профілю CDP -## Віддалене керування браузером (проксі node host) +## Віддалене керування браузером (проксі вузла-хоста) -Якщо Gateway працює на іншій машині, ніж браузер, запустіть **node host** на машині, де є Chrome/Brave/Edge/Chromium. Gateway проксуватиме дії браузера до цього node (окремий сервер керування браузером не потрібен). +Якщо Gateway працює на іншій машині, ніж браузер, запустіть **вузол-хост** на машині, де є Chrome/Brave/Edge/Chromium. Gateway проксуватиме дії браузера до цього вузла (окремий сервер керування браузером не потрібен). -Використовуйте `gateway.nodes.browser.mode` для керування автоматичною маршрутизацією та `gateway.nodes.browser.node` для прив’язки до конкретного node, якщо підключено кілька. +Використовуйте `gateway.nodes.browser.mode`, щоб керувати автомаршрутизацією, і `gateway.nodes.browser.node`, щоб закріпити конкретний вузол, якщо під’єднано кілька вузлів. -Безпека та віддалене налаштування: [Інструмент браузера](/uk/tools/browser), [Віддалений доступ](/uk/gateway/remote), [Tailscale](/uk/gateway/tailscale), [Безпека](/uk/gateway/security) +Безпека й віддалене налаштування: [інструмент Browser](/uk/tools/browser), [віддалений доступ](/uk/gateway/remote), [Tailscale](/uk/gateway/tailscale), [безпека](/uk/gateway/security) ## Пов’язане - [Довідник CLI](/uk/cli) -- [Браузер](/uk/tools/browser) +- [Browser](/uk/tools/browser) diff --git a/docs/uk/concepts/queue.md b/docs/uk/concepts/queue.md index f23c3d277..932263353 100644 --- a/docs/uk/concepts/queue.md +++ b/docs/uk/concepts/queue.md @@ -1,52 +1,52 @@ --- read_when: - - Зміна виконання автоматичних відповідей або паралелізму -summary: Проєктування черги команд, яка серіалізує вхідні запуски автоматичних відповідей + - Зміна виконання або паралелізму автовідповіді +summary: Проєктування черги команд, яка серіалізує вхідні запуски автовідповіді title: черга команд x-i18n: - generated_at: "2026-04-27T08:36:59Z" + generated_at: "2026-04-27T08:45:01Z" model: gpt-5.4 provider: openai - source_hash: 90824e592379b46b568b9f7ab017c2d68bf9b741349fe88f63e358a4c8754751 + source_hash: 8fa2d4953ba8a3d9be7080599e550c796ccedf622a9467bf77e50454b6ea4c4a source_path: concepts/queue.md workflow: 15 --- -Ми серіалізуємо вхідні запуски автоматичних відповідей (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти колізіям між кількома запусками агентів, водночас зберігаючи безпечний паралелізм між сесіями. +Ми серіалізуємо вхідні запуски автовідповіді (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти конфліктам між кількома запусками агента, водночас зберігаючи безпечний паралелізм між сесіями. -## Навіщо +## Чому -- Запуски автоматичних відповідей можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно. -- Серіалізація допомагає уникнути конкуренції за спільні ресурси (файли сесій, журнали, stdin CLI) і зменшує ймовірність обмежень швидкості з боку зовнішніх сервісів. +- Запуски автовідповіді можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно. +- Серіалізація дозволяє уникнути конкуренції за спільні ресурси (файли сесії, журнали, CLI stdin) і зменшує ймовірність лімітів з боку зовнішніх сервісів. ## Як це працює -- Черга FIFO з урахуванням смуг обробляє кожну смугу з налаштовуваним лімітом паралелізму (типово 1 для неналаштованих смуг; `main` типово 4, `subagent` — 8). -- `runEmbeddedPiAgent` ставить завдання в чергу за **ключем сесії** (смуга `session:`), щоб гарантувати лише один активний запуск на сесію. -- Потім кожен запуск сесії ставиться в **глобальну смугу** (`main` типово), щоб загальний паралелізм обмежувався `agents.defaults.maxConcurrent`. -- Коли ввімкнено докладне логування, запуски в черзі виводять коротке повідомлення, якщо вони чекали понад ~2 с перед стартом. -- Індикатори набору тексту, як і раніше, спрацьовують одразу під час додавання до черги (якщо це підтримує канал), тому користувацький досвід не змінюється, поки ми чекаємо своєї черги. +- FIFO-черга з урахуванням смуг обробляє кожну смугу з налаштовуваним обмеженням паралелізму (типово 1 для неналаштованих смуг; для main типово 4, для subagent — 8). +- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (смуга `session:`), щоб гарантувати лише один активний запуск на сесію. +- Потім кожен запуск сесії ставиться в **глобальну смугу** (`main` типово), щоб загальний паралелізм обмежувався через `agents.defaults.maxConcurrent`. +- Коли увімкнено докладне журналювання, запуски в черзі виводять коротке повідомлення, якщо вони чекали понад ~2 с перед стартом. +- Індикатори набору тексту все одно спрацьовують одразу під час додавання в чергу (коли це підтримується каналом), тому користувацький досвід не змінюється, поки ми чекаємо своєї черги. ## Режими черги (для кожного каналу) -Вхідні повідомлення можуть спрямовувати поточний запуск, чекати наступного ходу, або робити і те, і інше: +Вхідні повідомлення можуть керувати поточним запуском, чекати наступного ходу або робити обидва варіанти: -- `steer`: негайно вбудувати в поточний запуск (скасовує відкладені виклики інструментів після наступної межі інструмента). Якщо потокове передавання не активне, повертається до `followup`. -- `followup`: поставити в чергу на наступний хід агента після завершення поточного запуску. -- `collect`: об’єднати всі повідомлення в черзі в **один** наступний хід (типово). Якщо повідомлення націлені на різні канали/гілки, вони обробляються окремо, щоб зберегти маршрутизацію. -- `steer-backlog` (також `steer+backlog`): спрямувати зараз **і** зберегти повідомлення для наступного ходу. -- `interrupt` (застаріле): перервати активний запуск для цієї сесії, а потім запустити найновіше повідомлення. +- `steer`: негайно інʼєктується в поточний запуск (скасовує відкладені виклики інструментів після наступної межі інструмента). Якщо потокова передача не активна, використовується резервний перехід до followup. +- `followup`: ставиться в чергу на наступний хід агента після завершення поточного запуску. +- `collect`: обʼєднує всі повідомлення в черзі в **один** наступний хід (типово). Якщо повідомлення націлені на різні канали/гілки, вони обробляються окремо, щоб зберегти маршрутизацію. +- `steer-backlog` (також `steer+backlog`): спрямовує зараз **і** зберігає повідомлення для наступного ходу. +- `interrupt` (застаріле): перериває активний запуск для цієї сесії, а потім запускає найновіше повідомлення. - `queue` (застарілий псевдонім): те саме, що `steer`. -`Steer-backlog` означає, що після спрямованого запуску ви можете отримати відповідь у наступному ході, тому на поверхнях із потоковим передаванням це може виглядати як дублікати. Віддавайте перевагу `collect`/`steer`, якщо хочете -одну відповідь на кожне вхідне повідомлення. +Steer-backlog означає, що ви можете отримати наступну відповідь після спрямованого запуску, тому на поверхнях зі стримінгом це може виглядати як дублікати. Віддавайте перевагу `collect`/`steer`, якщо хочете +одну відповідь на одне вхідне повідомлення. Надішліть `/queue collect` як окрему команду (для конкретної сесії) або встановіть `messages.queue.byChannel.discord: "collect"`. -Типові значення (якщо в конфігурації не задано): +Типові значення (якщо не задані в конфігурації): - Усі поверхні → `collect` -Налаштовуйте глобально або для окремого каналу через `messages.queue`: +Налаштуйте глобально або для кожного каналу через `messages.queue`: ```json5 { @@ -64,33 +64,33 @@ x-i18n: ## Параметри черги -Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer`, коли він повертається до `followup`): +Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer`, коли він резервно переходить до followup): -- `debounceMs`: чекати тиші перед запуском наступного ходу (запобігає «continue, continue»). -- `cap`: максимальна кількість повідомлень у черзі для однієї сесії. +- `debounceMs`: очікувати тиші перед початком наступного ходу (запобігає “continue, continue”). +- `cap`: максимальна кількість повідомлень у черзі на сесію. - `drop`: політика переповнення (`old`, `new`, `summarize`). -`Summarize` зберігає короткий список маркерів видалених повідомлень і додає його як синтетичний prompt наступного ходу. +Summarize зберігає короткий маркований список відкинутих повідомлень і інʼєктує його як синтетичний followup-промпт. Типові значення: `debounceMs: 1000`, `cap: 20`, `drop: summarize`. -## Перевизначення для конкретної сесії +## Перевизначення для сесії - Надішліть `/queue ` як окрему команду, щоб зберегти режим для поточної сесії. -- Параметри можна поєднувати: `/queue collect debounce:2s cap:25 drop:summarize` -- `/queue default` або `/queue reset` очищує перевизначення для сесії. +- Параметри можна комбінувати: `/queue collect debounce:2s cap:25 drop:summarize` +- `/queue default` або `/queue reset` очищає перевизначення для сесії. ## Область дії та гарантії -- Застосовується до запусків агентів автоматичних відповідей в усіх вхідних каналах, які використовують конвеєр відповідей Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо). -- Типова смуга (`main`) є загальнопроцесною для вхідних повідомлень + основних Heartbeat; установіть `agents.defaults.maxConcurrent`, щоб дозволити паралельну обробку кількох сесій. -- Можуть існувати додаткові смуги (наприклад, `cron`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно й не блокували вхідні відповіді. Ізольовані ходи агентів Cron утримують слот `cron`, тоді як їхнє внутрішнє виконання агента використовує `nested`; обидва використовують `cron.maxConcurrentRuns`. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks). -- Смуги на рівні сесії гарантують, що лише один запуск агента одночасно працює з конкретною сесією. -- Жодних зовнішніх залежностей або фонових робочих потоків; лише чистий TypeScript і promise. +- Застосовується до запусків агента автовідповіді в усіх вхідних каналах, які використовують конвеєр відповіді Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо). +- Типова смуга (`main`) є загальнопроцесною для вхідних подій і основних Heartbeat; установіть `agents.defaults.maxConcurrent`, щоб дозволити паралельну обробку кількох сесій. +- Можуть існувати додаткові смуги (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно без блокування вхідних відповідей. Ізольовані ходи Cron-агента утримують слот `cron`, тоді як їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-Cron-потоки `nested` зберігають власну поведінку смуг. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks). +- Смуги на рівні сесії гарантують, що лише один запуск агента одночасно працює з певною сесією. +- Жодних зовнішніх залежностей або фонових worker-потоків; лише TypeScript + promises. ## Усунення несправностей -- Якщо команди виглядають завислими, увімкніть докладні журнали й шукайте рядки на кшталт «queued for …ms», щоб підтвердити, що черга обробляється. -- Якщо вам потрібна глибина черги, увімкніть докладні журнали та стежте за рядками з часом черги. +- Якщо здається, що команди зависли, увімкніть докладні журнали та шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється. +- Якщо вам потрібна глибина черги, увімкніть докладні журнали та відстежуйте рядки з таймінгами черги. ## Пов’язане diff --git a/docs/uk/install/migrating-hermes.md b/docs/uk/install/migrating-hermes.md index 2332ac21b..4f299b3c4 100644 --- a/docs/uk/install/migrating-hermes.md +++ b/docs/uk/install/migrating-hermes.md @@ -1,29 +1,29 @@ --- read_when: - - Ви переходите з Hermes і хочете зберегти конфігурацію моделі, промпти, пам’ять і Skills + - Ви переходите з Hermes і хочете зберегти свою конфігурацію моделей, промпти, пам’ять і Skills - Ви хочете знати, що OpenClaw імпортує автоматично, а що залишається лише в архіві - Вам потрібен чистий, скриптований шлях міграції (CI, новий ноутбук, автоматизація) -summary: Перейдіть з Hermes на OpenClaw за допомогою попередньо переглянутого імпорту з можливістю скасування -title: Перехід з Hermes +summary: Перейдіть з Hermes на OpenClaw за допомогою попередньо переглянутого імпорту, який можна скасувати +title: Міграція з Hermes x-i18n: - generated_at: "2026-04-27T08:25:07Z" + generated_at: "2026-04-27T08:45:03Z" model: gpt-5.4 provider: openai - source_hash: f424defc61e4f1127adb6e99b504c1f3a84c59635293208bb24bf3113aa7724d + source_hash: 59aa622f9c60095db19f54d51b8bbde0d61b97402dc49bc9b7a3cb855176e16a source_path: install/migrating-hermes.md workflow: 15 --- -OpenClaw імпортує стан Hermes через вбудований провайдер міграції. Провайдер показує попередній перегляд усього перед зміною стану, приховує секрети в планах і звітах та створює перевірену резервну копію перед застосуванням. +OpenClaw імпортує стан Hermes через вбудований провайдер міграції. Провайдер показує попередній перегляд усього перед зміною стану, редагує секрети в планах і звітах та створює перевірену резервну копію перед застосуванням. -Для імпорту потрібне свіже налаштування OpenClaw. Якщо у вас уже є локальний стан OpenClaw, спочатку скиньте config, credentials, sessions і workspace, або використайте `openclaw migrate` безпосередньо з `--overwrite` після перегляду плану. +Для імпорту потрібне свіже налаштування OpenClaw. Якщо у вас уже є локальний стан OpenClaw, спочатку скиньте config, credentials, sessions і робочий простір або використайте `openclaw migrate` напряму з `--overwrite` після перегляду плану. ## Два способи імпорту - + Найшвидший шлях. Майстер виявляє Hermes у `~/.hermes` і показує попередній перегляд перед застосуванням. ```bash @@ -38,46 +38,46 @@ OpenClaw імпортує стан Hermes через вбудований про - Використовуйте `openclaw migrate` для скриптованих або повторюваних запусків. Повний довідник дивіться в [`openclaw migrate`](/uk/cli/migrate). + Використовуйте `openclaw migrate` для скриптованих або повторюваних запусків. Див. [`openclaw migrate`](/uk/cli/migrate) для повного довідника. ```bash openclaw migrate hermes --dry-run # лише попередній перегляд - openclaw migrate apply hermes --yes # застосувати без запиту підтвердження + openclaw migrate apply hermes --yes # застосувати без підтвердження ``` - Додайте `--from `, якщо Hermes розташований поза `~/.hermes`. + Додайте `--from `, якщо Hermes розташований не в `~/.hermes`. -## Що буде імпортовано +## Що імпортується - + - Вибір моделі за замовчуванням із Hermes `config.yaml`. - - Налаштовані провайдери моделей і власні сумісні з OpenAI endpoint-и з `providers` і `custom_providers`. + - Налаштовані провайдери моделей і користувацькі OpenAI-сумісні endpoint-и з `providers` і `custom_providers`. Визначення MCP-серверів із `mcp_servers` або `mcp.servers`. - - - `SOUL.md` і `AGENTS.md` копіюються до workspace агента OpenClaw. - - `memories/MEMORY.md` і `memories/USER.md` **додаються** до відповідних файлів пам’яті OpenClaw, а не перезаписують їх. + + - `SOUL.md` і `AGENTS.md` копіюються до робочого простору агента OpenClaw. + - `memories/MEMORY.md` і `memories/USER.md` **додаються** до відповідних файлів пам’яті OpenClaw замість перезапису. - Типові параметри конфігурації пам’яті для файлової пам’яті OpenClaw. Зовнішні провайдери пам’яті, такі як Honcho, фіксуються як елементи архіву або ручної перевірки, щоб ви могли перенести їх усвідомлено. + Типові налаштування пам’яті для файлової пам’яті OpenClaw. Зовнішні провайдери пам’яті, як-от Honcho, записуються як елементи архіву або ручної перевірки, щоб ви могли перенести їх навмисно. - Skills із файлом `SKILL.md` у `skills//` копіюються разом із значеннями конфігурації для кожного skill із `skills.config`. + Skills із файлом `SKILL.md` у `skills//` копіюються разом зі значеннями конфігурації для кожного Skill із `skills.config`. - + Установіть `--include-secrets`, щоб імпортувати підтримувані ключі `.env`: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. Без цього прапорця секрети ніколи не копіюються. ## Що залишається лише в архіві -Провайдер копіює це до каталогу звіту міграції для ручної перевірки, але **не** завантажує до активних config або credentials OpenClaw: +Провайдер копіює це до каталогу звіту міграції для ручної перевірки, але **не** завантажує це в активні config або credentials OpenClaw: - `plugins/` - `sessions/` @@ -87,9 +87,9 @@ OpenClaw імпортує стан Hermes через вбудований про - `auth.json` - `state.db` -OpenClaw відмовляється автоматично виконувати або довіряти цьому стану, оскільки формати та припущення щодо довіри можуть відрізнятися між системами. Перенесіть потрібне вручну після перегляду архіву. +OpenClaw відмовляється автоматично виконувати або довіряти цьому стану, оскільки формати й припущення щодо довіри можуть відрізнятися між системами. Перенесіть потрібне вручну після перегляду архіву. -## Рекомендований порядок дій +## Рекомендований процес @@ -97,7 +97,7 @@ OpenClaw відмовляється автоматично виконувати openclaw migrate hermes --dry-run ``` - План перелічує все, що буде змінено, зокрема конфлікти, пропущені елементи та будь-які чутливі елементи. Вивід плану приховує вкладені ключі, схожі на секрети. + План перелічує все, що буде змінено, включно з конфліктами, пропущеними елементами та будь-якими чутливими елементами. Вивід плану редагує вкладені ключі, схожі на секрети. @@ -105,7 +105,7 @@ OpenClaw відмовляється автоматично виконувати openclaw migrate apply hermes --yes ``` - Перед застосуванням OpenClaw створює та перевіряє резервну копію. Якщо вам потрібно імпортувати ключі API, додайте `--include-secrets`. + OpenClaw створює й перевіряє резервну копію перед застосуванням. Якщо вам також потрібно імпортувати ключі API, додайте `--include-secrets`. @@ -113,7 +113,7 @@ OpenClaw відмовляється автоматично виконувати openclaw doctor ``` - [Doctor](/uk/gateway/doctor) повторно застосовує всі відкладені міграції config і перевіряє наявність проблем, внесених під час імпорту. + [Doctor](/uk/gateway/doctor) повторно застосовує всі незавершені міграції config і перевіряє проблеми, що могли з’явитися під час імпорту. @@ -122,20 +122,22 @@ OpenClaw відмовляється автоматично виконувати openclaw status ``` - Переконайтеся, що Gateway працює справно і ваші імпортовані модель, пам’ять і Skills завантажені. + Підтвердьте, що Gateway працює справно, а імпортовані модель, пам’ять і Skills завантажені. ## Обробка конфліктів -Застосування відмовляється продовжувати, коли план повідомляє про конфлікти (файл або значення config уже існує в цільовому місці). +Застосування відмовляється продовжувати, якщо в плані є конфлікти (файл або значення config уже існує в цільовому розташуванні). -Повторно запускайте з `--overwrite` лише тоді, коли заміна наявної цілі є свідомим рішенням. Провайдери все одно можуть записувати резервні копії окремих елементів для перезаписаних файлів у каталог звіту міграції. +Повторно запускайте з `--overwrite` лише тоді, коли заміна наявної цілі дійсно задумана. Провайдери все одно можуть записувати резервні копії окремих елементів для перезаписаних файлів у каталог звіту міграції. -Для свіжої інсталяції OpenClaw конфлікти нетипові. Зазвичай вони з’являються, коли ви повторно запускаєте імпорт у налаштуванні, де вже є внесені користувачем зміни. +Для свіжого встановлення OpenClaw конфлікти трапляються рідко. Зазвичай вони з’являються, коли ви повторно запускаєте імпорт у середовищі, де вже є користувацькі зміни. + +Якщо конфлікт виникає посеред застосування (наприклад, через неочікувану гонку на файлі config), Hermes позначає решту залежних елементів config як `skipped` із причиною `blocked by earlier apply conflict` замість часткового запису. Звіт міграції фіксує кожен заблокований елемент, щоб ви могли усунути початковий конфлікт і повторно запустити імпорт. ## Секрети @@ -143,7 +145,7 @@ OpenClaw відмовляється автоматично виконувати - Спочатку виконайте `openclaw migrate apply hermes --yes`, щоб імпортувати стан без секретів. - Якщо ви також хочете скопіювати підтримувані ключі `.env`, повторно запустіть із `--include-secrets`. -- Для credentials під керуванням SecretRef налаштуйте джерело SecretRef після завершення імпорту. +- Для credentials, якими керує SecretRef, налаштуйте джерело SecretRef після завершення імпорту. ## Вивід JSON для автоматизації @@ -158,23 +160,23 @@ openclaw migrate apply hermes --json --yes - Перегляньте вивід плану. Кожен конфлікт указує вихідний шлях і наявну ціль. Для кожного елемента вирішіть, чи потрібно пропустити його, відредагувати ціль або повторно запустити з `--overwrite`. + Перегляньте вивід плану. Кожен конфлікт указує шлях джерела й наявну ціль. Для кожного елемента вирішіть, чи пропустити його, відредагувати ціль або повторно запустити з `--overwrite`. - - Передайте `--from /actual/path` (CLI) або `--import-source /actual/path` (початкове налаштування). + + Передайте `--from /actual/path` (CLI) або `--import-source /actual/path` (онбординг). - - Імпорт через початкове налаштування потребує свіжого налаштування. Або скиньте стан і знову пройдіть початкове налаштування, або безпосередньо використайте `openclaw migrate apply hermes`, що підтримує `--overwrite` і явне керування резервними копіями. + + Імпорт через онбординг потребує свіжого налаштування. Або скиньте стан і знову пройдіть онбординг, або використайте `openclaw migrate apply hermes` напряму, що підтримує `--overwrite` і явне керування резервними копіями. - - Потрібен `--include-secrets`, і розпізнаються лише перелічені вище ключі. Інші змінні в `.env` ігноруються. + + Потрібен `--include-secrets`, і розпізнаються лише ключі, наведені вище. Інші змінні в `.env` ігноруються. ## Пов’язане - [`openclaw migrate`](/uk/cli/migrate): повний довідник CLI, контракт Plugin і форми JSON. -- [Початкове налаштування](/uk/cli/onboard): сценарій майстра та неінтерактивні прапорці. -- [Міграція](/uk/install/migrating): перенесення інсталяції OpenClaw між машинами. -- [Doctor](/uk/gateway/doctor): перевірка працездатності після міграції. -- [Workspace агента](/uk/concepts/agent-workspace): де розташовані `SOUL.md`, `AGENTS.md` і файли пам’яті. +- [Onboarding](/uk/cli/onboard): процес майстра й неінтерактивні прапорці. +- [Migrating](/uk/install/migrating): перенесення встановлення OpenClaw між машинами. +- [Doctor](/uk/gateway/doctor): перевірка стану після міграції. +- [Робочий простір агента](/uk/concepts/agent-workspace): де розташовані `SOUL.md`, `AGENTS.md` і файли пам’яті. diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index d4fa0920e..cddfaae44 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,65 +1,64 @@ --- read_when: - - Ви створюєте plugin для OpenClaw - - Вам потрібно надати схему конфігурації plugin або налагодити помилки валідації plugin -summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації) + - Ви створюєте Plugin для OpenClaw + - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin +summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-27T08:31:09Z" + generated_at: "2026-04-27T08:45:02Z" model: gpt-5.4 provider: openai - source_hash: 5b3ffcdfcf09b4480d0cec007d645daebdaeb86a051a233dec192f555359162a + source_hash: b656e2d80716e7a1fd8dae1f63bc7cc7ab4b2a1ebdb4790ab3c6b211558b35eb source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка стосується лише **власного маніфесту plugin OpenClaw**. +Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. -Сумісні макети bundle описано тут: [Пакети Plugin](/uk/plugins/bundles). +Сумісні компонування пакетів описано в [Plugin bundles](/uk/plugins/bundles). -Сумісні формати bundle використовують інші файли маніфесту: +Сумісні формати пакетів використовують інші файли маніфесту: -- Codex bundle: `.codex-plugin/plugin.json` -- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту -- Cursor bundle: `.cursor-plugin/plugin.json` +- Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію +OpenClaw також автоматично визначає ці компонування пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних bundle OpenClaw наразі читає метадані bundle разом з оголошеними -коренями skill, коренями команд Claude, типовими значеннями `settings.json` у bundle Claude, -типовими значеннями LSP у bundle Claude та підтримуваними наборами hook, якщо макет відповідає +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом із заявленими +коренями Skills, коренями команд Claude, типовими значеннями `settings.json` пакета Claude, +типовими значеннями LSP пакета Claude та підтримуваними наборами хуків, коли компонування відповідає очікуванням середовища виконання OpenClaw. -Кожен власний plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у -**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду plugin**. Відсутні або недійсні маніфести розглядаються як -помилки plugin і блокують валідацію конфігурації. +Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у +**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються +помилками Plugin і блокують валідацію конфігурації. -Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin). -Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: +Повний посібник із системи Plugin див. у [Plugins](/uk/tools/plugin). +Щодо власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду -вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску -середовища виконання plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого +Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску +середовища виконання Plugin. **Використовуйте його для:** -- ідентичності plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих auth, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища provider, варіанти auth) -- підказок активації для поверхонь control-plane -- скороченого володіння сімействами моделей +- ідентифікації Plugin, валідації конфігурації та підказок для UI конфігурації +- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь площини керування +- скороченого володіння сімейством моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` +- метаданих запускальника QA, які може перевіряти спільний хост `openclaw qa` - метаданих конфігурації, специфічних для каналу, що об’єднуються в каталог і поверхні валідації **Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення -точок входу коду або метаданих встановлення npm. Для цього призначені код вашого plugin -і `package.json`. +точок входу коду або метаданих встановлення npm. Це належить до вашого коду Plugin і `package.json`. ## Мінімальний приклад @@ -80,7 +79,7 @@ OpenClaw також автоматично визначає ці макети bu { "id": "openrouter", "name": "OpenRouter", - "description": "Плагін provider OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -108,19 +107,19 @@ OpenClaw також автоматично визначає ці макети bu "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Ключ API OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Ключ API OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Ключ API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -139,74 +138,72 @@ OpenClaw також автоматично визначає ці макети bu ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | +| Поле | Обов’язкове | Тип | Що це означає | | ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON schema для конфігурації цього plugin. | -| `enabledByDefault` | Ні | `true` | Позначає bundle plugin як увімкнений типово. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався типово вимкненим. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли auth, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори channel, якими володіє цей plugin. Використовуються для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори provider, якими володіє цей plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення provider, відносний до кореня plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного середовища виконання plugin. | -| `modelSupport` | Ні | `object` | Метадані скороченого запису для сімейств моделей, якими володіє маніфест, що використовуються для автозавантаження plugin до запуску середовища виконання. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для provider, якими володіє цей plugin. Це контракт control-plane для майбутнього читання списків у режимі лише для читання, онбордингу, вибору моделей, аліасів і приховування без завантаження середовища виконання plugin. | -| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, якою володіє provider. Використовуйте її, щоб виключити локальні/self-hosted provider із віддалених каталогів цін або зіставити посилання provider з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів provider у core. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів provider, які core має класифікувати до завантаження середовища виконання provider. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend виведення CLI, якими володіє цей plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевірити синтетичний hook auth, яким володіє plugin, під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, якими володіє bundle plugin, що представляють не секретний локальний стан, OAuth або стан облікових даних середовища. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin, що мають створювати обізнану про plugin конфігурацію та діагностику CLI до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку auth/статусу provider. Для нових plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час вікна знецінення. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку auth, наприклад provider для кодування, який спільно використовує базовий ключ API provider та профілі auth. | -| `channelEnvVars` | Ні | `Record` | Легковагові метадані env для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel на основі env або поверхонь auth, які мають бачити загальні допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів auth для селекторів онбордингу, визначення бажаного provider і простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, яке запускається provider, командою, channel, маршрутом і можливістю. Лише метадані; фактичною поведінкою, як і раніше, володіє середовище виконання plugin. | -| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | -| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання plugin. | -| `contracts` | Ні | `object` | Статичний знімок bundle можливостей для зовнішніх hook auth, speech, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення для розуміння медіа для ідентифікаторів provider, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, якими володіє маніфест, що об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | -| `name` | Ні | `string` | Зрозуміла людині назва plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. | -| `version` | Ні | `string` | Інформаційна версія plugin. | +| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin лишався типово вимкненим. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до полегшеного модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, і використовуються для автозавантаження Plugin до запуску середовища виконання. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт площини керування для майбутнього доступного лише для читання переліку, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | +| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, що належить провайдеру. Використовуйте її, щоб виключити локальні або self-hosted провайдери з віддалених каталогів цін або зіставити посилання на провайдерів з ідентифікаторами каталогу OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі. | +| `providerEndpoints` | Ні | `object[]` | Метадані хоста/`baseUrl` кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження середовища виконання провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску за явними посиланнями з конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або CLI-бекенди, чий синтетичний хук автентифікації, що належить Plugin, слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому Plugin і представляють несекретний локальний стан, стан OAuth або стан облікових даних середовища. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають генерувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані змінних середовища для пошуку автентифікації/стану провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це поле протягом періоду виведення з ужитку. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує API-ключ базового провайдера й профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації, керованих змінними середовища, які мають бачити узагальнені допоміжні засоби запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання Plugin. | +| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | +| `qaRunners` | Ні | `object[]` | Полегшені дескриптори запускальників QA, які використовує спільний хост `openclaw qa` до завантаження середовища виконання Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Полегшені типові значення розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skill для завантаження, відносно кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | +| `description` | Ні | `string` | Короткий опис, який показується в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | | `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth. -OpenClaw читає це до завантаження середовища виконання provider. -Списки налаштування provider використовують ці варіанти маніфесту, варіанти -налаштування, похідні від дескрипторів, і метадані каталогу встановлення без -завантаження середовища виконання provider. +Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. +OpenClaw зчитує це до завантаження середовища виконання провайдера. +Списки налаштування провайдера використовують ці варіанти маніфесту, варіанти +налаштування, похідні від дескрипторів, і метадані каталогу встановлення без завантаження середовища виконання провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор provider, до якого належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу auth, до якого слід спрямувати. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта auth, який використовується в онбордингу та потоках CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються вище в інтерактивних селекторах, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків auth з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має відображатися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| -------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямовувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується потоками онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | +| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища -виконання, яку користувачі можуть помилково вказати в `plugins.allow` або -спробувати запустити як кореневу команду CLI. OpenClaw використовує ці -метадані для діагностики без імпорту коду середовища виконання plugin. +Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть +помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. ```json { @@ -220,41 +217,37 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | +| Поле | Обов’язкове | Тип | Що це означає | | ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ | -| `name` | Так | `string` | Назва команди, що належить цьому plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо вона існує. | +| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку можна запропонувати для операцій CLI, якщо така існує. | ## Довідник `activation` -Використовуйте `activation`, коли plugin може дешево оголосити, які події -control-plane мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли Plugin може дешево оголосити, які події площини керування +мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не -реєструє поведінку середовища виконання, не замінює `register(...)` і не -гарантує, що код plugin уже виконувався. Планувальник активації використовує -ці поля, щоб звузити коло кандидатів plugin, перш ніж переходити до наявних -метаданих володіння маніфестом, таких як `providers`, `channels`, -`commandAliases`, `setup.providers`, `contracts.tools` і hooks. +Цей блок — метадані планувальника, а не API життєвого циклу. Він не реєструє +поведінку середовища виконання, не замінює `register(...)` і не обіцяє, що +код Plugin уже виконано. Планувальник активації використовує ці поля, щоб +звузити коло кандидатів Plugin, перш ніж повертатися до наявних метаданих володіння маніфесту, таких як +`providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. -Надавайте перевагу найвужчим метаданим, які вже описують володіння. -Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або -`contracts`, коли ці поля виражають відповідний зв’язок. Використовуйте -`activation` для додаткових підказок планувальнику, які не можна подати через -ці поля володіння. -Використовуйте верхньорівневий `cliBackends` для аліасів середовища виконання -CLI, таких як `claude-cli`, `codex-cli` або `google-gemini-cli`; -`activation.onAgentHarnesses` призначений лише для вбудованих ідентифікаторів -agent harness, які ще не мають поля володіння. +Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте +`providers`, `channels`, `commandAliases`, дескриптори налаштування або `contracts`, +коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальника, +які не можна подати цими полями володіння. +Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища виконання CLI, таких як `claude-cli`, +`codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначений лише для +вбудованих ідентифікаторів harness агентів, які ще не мають поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку середовища -виконання і не замінює `register(...)`, `setupEntry` або інші точки входу -середовища виконання/plugin. Поточні споживачі використовують його як підказку -для звуження кола перед ширшим завантаженням plugin, тому відсутність -метаданих активації зазвичай лише впливає на продуктивність; це не повинно -змінювати коректність, доки ще існують застарілі резервні механізми володіння -маніфестом. +Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і не +замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/Plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому +відсутність метаданих активації зазвичай впливає лише на продуктивність; це не має +змінювати коректність, поки все ще існують застарілі резервні механізми володіння маніфесту. ```json { @@ -263,69 +256,69 @@ agent harness, які ще не мають поля володіння. "onCommands": ["models"], "onChannels": ["web"], "onRoutes": ["gateway-webhook"], + "onConfigPaths": ["browser"], "onCapabilities": ["provider", "tool"] } } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають включати цей plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей plugin до планів активації/завантаження. Для аліасів backend CLI використовуйте верхньорівневий `cliBackends`. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають включати цей plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються плануванням активації control-plane. За можливості надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих harness агентів, які мають включати цей Plugin до планів активації/завантаження. Для псевдонімів CLI-бекендів використовуйте верхньорівневий `cliBackends`. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються плануванням активації площини керування. За можливості віддавайте перевагу вужчим полям. | -Поточні активні споживачі: +Поточні реальні споживачі: -- планування CLI, що запускається командою, повертається до застарілих +- CLI-планування, запущене командою, повертається до застарілого `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску середовища виконання agent використовує - `activation.onAgentHarnesses` для вбудованих harness і верхньорівневий - `cliBackends[]` для аліасів середовища виконання CLI -- планування setup/channel, що запускається channel, повертається до - застарілого володіння `channels[]`, коли явні метадані активації channel - відсутні -- планування setup/runtime, що запускається provider, повертається до - застарілого володіння `providers[]` і верхньорівневого `cliBackends[]`, коли - явні метадані активації provider відсутні +- планування запуску середовища виконання агента використовує `activation.onAgentHarnesses` для + вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI +- планування налаштування/каналу, запущене каналом, повертається до застарілого володіння `channels[]`, + коли явні метадані активації каналу відсутні +- планування Plugin під час запуску використовує `activation.onConfigPaths` для некональних кореневих + поверхонь конфігурації, таких як блок `browser` вбудованого Plugin браузера +- планування налаштування/середовища виконання, запущене провайдером, повертається до застарілого + володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та резервний -механізм володіння маніфестом. Наприклад, `activation-command-hint` означає, -що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, -що планувальник натомість використав володіння `commandAliases`. Ці мітки -причин призначені для діагностики хоста та тестів; авторам plugin слід і надалі -оголошувати метадані, які найкраще описують володіння. +Діагностика планувальника може відрізняти явні підказки активації від резервного +володіння маніфесту. Наприклад, `activation-command-hint` означає, що +збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що +планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для +діагностики хоста й тестів; автори Plugin мають і надалі оголошувати метадані, +які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner -під спільним коренем `openclaw qa`. Зберігайте ці метадані простими й -статичними; фактичною реєстрацією CLI, як і раніше, володіє середовище -виконання plugin через легковагову поверхню `runtime-api.ts`, яка експортує -`qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька запускальників транспорту під +спільним коренем `openclaw qa`. Зберігайте ці метадані дешевими та статичними; фактичною реєстрацією CLI +все одно володіє середовище виконання Plugin через полегшену +поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Запускає lane live QA для Matrix на базі Docker на одноразовому homeserver" + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------ | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | -------- | ----------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням setup та онбордингу потрібні дешеві -метадані plugin, якими він володіє, до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, +що належать Plugin, до завантаження середовища виконання. ```json { @@ -344,78 +337,72 @@ agent harness, які ще не мають поля володіння. } ``` -Верхньорівневий `cliBackends` залишається чинним і надалі описує backend -виведення CLI. `setup.cliBackends` — це поверхня дескриптора, специфічна для -setup, для потоків control-plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається чинним і далі описує +бекенди інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, +для потоків площини керування/налаштування, які мають лишатися лише метаданими. -Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною -поверхнею пошуку setup за принципом “спочатку дескриптор” для виявлення setup. -Якщо дескриптор лише звужує коло кандидатів plugin, а setup все ще потребує -багатших hook середовища виконання на час setup, установіть -`requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +За наявності `setup.providers` і `setup.cliBackends` є бажаною +поверхнею пошуку для виявлення налаштування за принципом descriptor-first. Якщо дескриптор лише +звужує кандидата Plugin, а налаштуванню все ще потрібні багатші хуки середовища виконання на етапі налаштування, +установіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні механізми пошуку -auth provider і змінних середовища. `providerAuthEnvVars` залишається -підтримуваним через адаптер сумісності протягом вікна знецінення, але -неbundle plugin, які все ще його використовують, отримують діагностику -маніфесту. Нові plugin мають розміщувати метадані env для setup/статусу в -`setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до узагальнених пошуків автентифікації провайдера та +змінних середовища. `providerAuthEnvVars` лишається підтримуваним через адаптер сумісності +протягом періоду виведення з ужитку, але небудовані Plugin, які все ще його використовують, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані змінних середовища +для налаштування/стану в `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup із -`setup.providers[].authMethods`, коли запис setup відсутній або коли -`setup.requiresRuntime: false` оголошує, що середовище виконання setup не -потрібне. Явні записи `providerAuthChoices` усе ще мають перевагу для власних -міток, прапорців CLI, області онбордингу та метаданих асистента. +OpenClaw також може виводити прості варіанти налаштування з `setup.providers[].authMethods`, +коли запис налаштування недоступний або коли `setup.requiresRuntime: false` +оголошує, що середовище виконання налаштування не потрібне. Явні записи `providerAuthChoices` залишаються +бажаними для власних міток, прапорців CLI, області онбордингу та метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів -достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише -на дескриптор і не виконуватиме `setup-api` або `openclaw.setupEntry` для -пошуку setup. Якщо plugin, що працює лише через дескриптор, усе ж містить один -із цих записів середовища виконання setup, OpenClaw повідомляє додаткову -діагностику й надалі ігнорує його. Якщо `requiresRuntime` не вказано, -зберігається застаріла резервна поведінка, щоб наявні plugin, які додали +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні налаштування. OpenClaw трактує явне `false` як контракт лише з дескрипторами +і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку налаштування. Якщо +Plugin лише з дескрипторами все ж постачає один із цих записів середовища виконання налаштування, +OpenClaw повідомляє додаткову діагностику й продовжує її ігнорувати. Пропущене +`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugin, які додали дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, яким володіє plugin, -нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають -залишатися унікальними серед усіх виявлених plugin. Неоднозначне володіння -завершується безпечним блокуванням замість вибору переможця за порядком -виявлення. +Оскільки пошук налаштування може виконувати код `setup-api`, що належить Plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними +в усіх виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою замість вибору +переможця за порядком виявлення. -Коли середовище виконання setup усе ж виконується, діагностика реєстру setup -повідомляє про розходження дескрипторів, якщо `setup-api` реєструє provider -або backend CLI, яких не оголошують дескриптори маніфесту, або якщо для -дескриптора немає відповідної реєстрації в середовищі виконання. Ці -діагностичні повідомлення є додатковими й не відхиляють застарілі plugin. +Коли середовище виконання налаштування все ж виконується, діагностика реєстру налаштування повідомляє про +розходження дескрипторів, якщо `setup-api` реєструє провайдера або CLI-бекенд, який дескриптори маніфесту не оголошують, +або якщо для дескриптора немає відповідної реєстрації середовища виконання. Ці діагностики є додатковими +і не відхиляють застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | +| Поле | Обов’язкове | Тип | Що це означає | | ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | Так | `string` | Ідентифікатор provider, який показується під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей provider підтримує без завантаження повного середовища виконання. | -| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/статусу можуть перевіряти до завантаження середовища виконання plugin. | +| `id` | Так | `string` | Ідентифікатор провайдера, доступний під час налаштування або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які підтримує цей провайдер без завантаження повного середовища виконання. | +| `envVars` | Ні | `string[]` | Змінні середовища, які узагальнені поверхні налаштування/стану можуть перевіряти до завантаження середовища виконання Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup за принципом “спочатку дескриптор”. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час налаштування та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів часу налаштування, які використовуються для пошуку налаштування за принципом descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня налаштування цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для -рендерингу. +`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу. ```json { "uiHints": { "apiKey": { - "label": "Ключ API", - "help": "Використовується для запитів OpenRouter", + "label": "API key", + "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -423,22 +410,21 @@ OpenClaw також може виводити прості варіанти setu } ``` -Кожна підказка для поля може містити: +Кожна підказка поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що це означає | +| ------------- | ---------- | -------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння -можливостями, які OpenClaw може читати без імпорту середовища виконання -plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +зчитувати без імпорту середовища виконання Plugin. ```json { @@ -462,48 +448,46 @@ plugin. Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ----------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик extension для app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Ідентифікатори середовища виконання, для яких bundle plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори provider, hook зовнішнього профілю auth яких належить цьому plugin. | -| `speechProviders` | `string[]` | Ідентифікатори provider speech, якими володіє цей plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider транскрипції в реальному часі, якими володіє цей plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори provider голосу в реальному часі, якими володіє цей plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори provider embedding для пам’яті, якими володіє цей plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider розуміння медіа, якими володіє цей plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори provider генерації зображень, якими володіє цей plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори provider генерації відео, якими володіє цей plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори provider web-fetch, якими володіє цей plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори provider web search, якими володіє цей plugin. | -| `migrationProviders` | `string[]` | Ідентифікатори provider імпорту, якими володіє цей plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви agent tool, якими володіє цей plugin для перевірок контрактів bundle. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | ------------------------------------------------------------------------ | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори середовища виконання, для яких вбудований Plugin може зареєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хуком зовнішнього профілю автентифікації яких володіє цей Plugin. | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрипції в реальному часі, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів вбудовувань пам’яті, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для перевірок вбудованих контрактів. | -`contracts.embeddedExtensionFactories` збережено для фабрик extension лише для -app-server Codex у bundle. Bundle-трансформації результатів інструментів мають +`contracts.embeddedExtensionFactories` зберігається для вбудованих +фабрик розширень лише для app-server Codex. Вбудовані перетворення результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugin не можуть -реєструвати middleware результатів інструментів, тому що цей seam може -переписувати високодовірений вивід інструмента до того, як модель його побачить. +`api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть +реєструвати middleware результатів інструментів, оскільки цей шов може переписувати вивід інструмента високої довіри +до того, як модель його побачить. -Plugin provider, які реалізують `resolveExternalAuthProfiles`, мають -оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все -ще працюють через застарілий механізм сумісності, але він повільніший і буде -видалений після завершення вікна міграції. +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати +`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють +через застарілий резервний механізм сумісності, але цей резервний механізм повільніший і +буде видалений після вікна міграції. -Bundle provider embedding для пам’яті мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, -який вони надають, включно з вбудованими адаптерами, такими як `local`. -Окремі шляхи CLI використовують цей контракт маніфесту, щоб завантажувати -лише plugin-власник до того, як повне середовище виконання Gateway зареєструє -provider. +Вбудовані провайдери вбудовувань пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з +вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, +щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway зареєструє +провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли provider розуміння -медіа має типові моделі, пріоритет резервного автоматичного auth або вбудовану -підтримку документів, які потрібні загальним допоміжним засобам core до -завантаження середовища виконання. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +типові моделі, пріоритет резервного автоматичного вибору автентифікації або вбудовану підтримку документів, які +узагальненим допоміжним засобам ядра потрібні до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -527,46 +511,42 @@ provider. } ``` -Кожен запис provider може містити: +Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. | -| `defaultModels` | `Record` | Типові значення “можливість → модель”, що використовуються, коли в конфігурації не вказано модель. | -| `autoPriority` | `Record` | Менші числа сортуються вище для автоматичного резервного вибору provider на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані входи документів, які підтримує provider. | +| Поле | Тип | Що це означає | +| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові відповідності можливість-модель, які використовуються, коли конфігурація не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані вхідні типи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли plugin channel потребує дешевих -метаданих конфігурації до завантаження середовища виконання. Виявлення setup/статусу -channel у режимі лише для читання може використовувати ці метадані безпосередньо -для налаштованих зовнішніх channel, коли запис setup недоступний або коли -`setup.requiresRuntime: false` оголошує, що середовище виконання setup не потрібне. +Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до +завантаження середовища виконання. Виявлення налаштування/стану каналу лише для читання може використовувати ці метадані +безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний або +коли `setup.requiresRuntime: false` оголошує, що середовище виконання налаштування не потрібне. -`channelConfigs` — це метадані маніфесту plugin, а не новий верхньорівневий -розділ конфігурації користувача. Користувачі, як і раніше, налаштовують -екземпляри channel у `channels.`. OpenClaw читає метадані -маніфесту, щоб визначити, який plugin володіє цим налаштованим channel, до -виконання коду середовища виконання plugin. +`channelConfigs` — це метадані маніфесту Plugin, а не новий розділ +користувацької конфігурації верхнього рівня. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. +OpenClaw зчитує метадані маніфесту, щоб визначити, якому Plugin належить цей налаштований +канал, до виконання коду середовища виконання Plugin. -Для plugin channel `configSchema` і `channelConfigs` описують різні шляхи: +Для Plugin каналу `configSchema` і `channelConfigs` описують різні +шляхи: -- `configSchema` валідує `plugins.entries..config` -- `channelConfigs..schema` валідує `channels.` +- `configSchema` валідовує `plugins.entries..config` +- `channelConfigs..schema` валідовує `channels.` -Неbundle plugin, які оголошують `channels[]`, також мають оголошувати -відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити -plugin, але поверхні схем конфігурації холодного шляху, setup і Control UI не -знатимуть форми параметрів, якими володіє channel, доки не виконається -середовище виконання plugin. +Небудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні записи +`channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але поверхні схеми конфігурації холодного шляху, налаштування й Control UI не можуть знати форму параметрів, що належать +каналу, доки не виконається середовище виконання Plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` -для перевірок конфігурації команд, які виконуються до завантаження середовища -виконання channel. Bundle channel також можуть публікувати такі самі типові -значення через `package.json#openclaw.channel.commands` разом з іншими -метаданими каталогу channel, якими володіє пакет. +`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок конфігурації команд, +які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати +ті самі типові значення через `package.json#openclaw.channel.commands` разом зі своїми +іншими метаданими каталогу каналів, що належать пакету. ```json { @@ -581,12 +561,12 @@ plugin, але поверхні схем конфігурації холодно }, "uiHints": { "homeserverUrl": { - "label": "URL homeserver", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Підключення до homeserver Matrix", + "description": "Matrix homeserver connection", "commands": { "nativeCommandsAutoEnabled": true, "nativeSkillsAutoEnabled": true @@ -597,24 +577,23 @@ plugin, але поверхні схем конфігурації холодно } ``` -Кожен запис channel може містити: +Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | +| Поле | Тип | Що це означає | | ------------- | ------------------------ | ---------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації channel. | -| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки щодо чутливості для цього розділу конфігурації channel. | -| `label` | `string` | Мітка channel, що об’єднується з поверхнями вибору та перегляду, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис channel для поверхонь перегляду та каталогу. | -| `commands` | `object` | Статичні автотипові значення для native command і native skill для перевірок конфігурації до запуску середовища виконання. | -| `preferOver` | `string[]` | Ідентифікатори застарілих plugin або plugin із нижчим пріоритетом, які цей channel має випереджати на поверхнях вибору. | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, яка об’єднується з поверхнями вибору та інспекції, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. | +| `commands` | `object` | Статичні типові авто-значення native command і native Skill для перевірок конфігурації до запуску середовища виконання. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | -### Заміна іншого plugin channel +### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш plugin є бажаним власником для -ідентифікатора channel, який також може надавати інший plugin. Типові випадки -— перейменований ідентифікатор plugin, окремий plugin, що замінює bundle -plugin, або підтримуваний fork, який зберігає той самий ідентифікатор channel -для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який +також може надавати інший Plugin. Поширені випадки — перейменований ідентифікатор Plugin, +окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який +зберігає той самий ідентифікатор каналу для сумісності конфігурації. ```json { @@ -635,24 +614,21 @@ plugin, або підтримуваний fork, який зберігає той } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор channel і -бажаний ідентифікатор plugin. Якщо plugin із нижчим пріоритетом було вибрано -лише тому, що він входить до bundle або увімкнений типово, OpenClaw вимикає -його в ефективній конфігурації середовища виконання, щоб channel і його -інструментами володів один plugin. Явний вибір користувача все одно має -перевагу: якщо користувач явно вмикає обидва plugin, OpenClaw зберігає цей -вибір і повідомляє діагностику дубльованих channel/інструментів замість -мовчазної зміни запитаного набору plugin. +Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу і +бажаний ідентифікатор Plugin. Якщо нижчопріоритетний Plugin було вибрано лише тому, +що він вбудований або увімкнений типово, OpenClaw вимикає його в ефективній +конфігурації середовища виконання, щоб один Plugin володів каналом і його інструментами. Явний +вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw +зберігає цей вибір і повідомляє діагностику дубльованого каналу/інструмента замість +мовчазної зміни запитаного набору Plugin. -Обмежуйте `preferOver` ідентифікаторами plugin, які справді можуть надавати -той самий channel. Це не загальне поле пріоритету і воно не перейменовує -ключі конфігурації користувача. +Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш plugin provider -за скороченими ідентифікаторами моделей на кшталт `gpt-5.5` або -`claude-sonnet-4.6` до завантаження середовища виконання plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з +скорочених ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання Plugin. ```json { @@ -665,29 +641,26 @@ plugin, або підтримуваний fork, який зберігає той OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` - плагіна-власника -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один небundle plugin і один bundle plugin, перемагає - небundle plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не - вкаже provider +- явні посилання `provider/model` використовують метадані маніфесту володіння `providers` +- `modelPatterns` мають перевагу над `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований + Plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що це означає | +| --------------- | ---------- | --------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей -provider до завантаження середовища виконання plugin. Це джерело фіксованих -рядків каталогу, аліасів provider, правил приховування та режиму виявлення, -яким володіє маніфест. Оновлення під час виконання, як і раніше, належить коду -середовища виконання provider, але маніфест повідомляє core, коли середовище -виконання потрібне. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до +завантаження середовища виконання Plugin. Це джерело, що належить маніфесту, для фіксованих рядків +каталогу, псевдонімів провайдера, правил приглушення та режиму виявлення. Оновлення під час виконання +і далі належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли середовище виконання +потрібне. ```json { @@ -726,7 +699,7 @@ provider до завантаження середовища виконання p { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", - "reason": "недоступно в Azure OpenAI Responses" + "reason": "not available on Azure OpenAI Responses" } ], "discovery": { @@ -738,54 +711,53 @@ provider до завантаження середовища виконання p Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів provider, якими володіє цей plugin. Ключі також мають бути присутні у верхньорівневому `providers`. | -| `aliases` | `Record` | Аліаси provider, які мають зводитися до provider-власника для планування каталогу або приховування. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей plugin приховує з причини, специфічної для provider. | -| `discovery` | `Record` | Чи можна читати каталог provider з метаданих маніфесту, оновлювати в кеш або чи він потребує середовища виконання. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають з’являтися у верхньорівневому `providers`. | +| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися до провайдера-власника для планування каталогу або приглушення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | +| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати в кеш або для нього потрібне середовище виконання. | -Поля provider: +Поля провайдера: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | ------------------------------------------------------------------ | -| `baseUrl` | `string` | Необов’язковий типовий `baseUrl` для моделей у цьому каталозі provider. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі provider. | -| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу provider. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що це означає | +| --------- | ------------------------ | -------------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язковий типовий `baseUrl` для моделей у цьому каталозі провайдера. | +| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | +| `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що воно означає | -| --------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | -| `id` | `string` | Локальний для provider ідентифікатор моделі без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Власне вікно контексту provider. | +| Поле | Тип | Що це означає | +| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `id` | `string` | Ідентифікатор моделі, локальний для провайдера, без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку міркування. | +| `contextWindow` | `number` | Власне вікно контексту провайдера. | | `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту під час виконання, якщо воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | | `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приховуйте лише тоді, коли рядок взагалі не повинен відображатися. | -| `statusReason` | `string` | Необов’язкова причина, що показується для статусу “не доступно”. | -| `replaces` | `string[]` | Старіші локальні для provider ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для provider ідентифікатор моделі-замінника для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приглушуйте лише тоді, коли рядок взагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується разом зі статусом, відмінним від доступного. | +| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору й фільтрами. | -Не розміщуйте в `modelCatalog` дані лише для середовища виконання. Якщо -provider потребує стану облікового запису, запиту API або виявлення локального -процесу, щоб визначити повний набір моделей, оголосіть цей provider як -`refreshable` або `runtime` у `discovery`. +Не розміщуйте в `modelCatalog` дані, які доступні лише під час виконання. Якщо провайдеру для +визначення повного набору моделей потрібен стан облікового запису, запит API або виявлення локального процесу, +оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. ## Довідник `modelPricing` -Використовуйте `modelPricing`, коли provider потребує поведінки цін у -control-plane до завантаження середовища виконання. Кеш цін Gateway читає ці -метадані без імпорту коду середовища виконання provider. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення площини керування до +завантаження середовища виконання. Кеш ціноутворення Gateway зчитує ці метадані без імпорту +коду середовища виконання провайдера. ```json { @@ -806,151 +778,139 @@ control-plane до завантаження середовища виконан } ``` -Поля provider: +Поля провайдера: -| Поле | Тип | Що воно означає | -| ------------ | ----------------- | --------------------------------------------------------------------------------------------------- | -| `external` | `boolean` | Установіть `false` для локальних/self-hosted provider, які ніколи не повинні отримувати ціни з OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Мапінг пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього provider. | -| `liteLLM` | `false \| object` | Мапінг пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього provider. | +| Поле | Тип | Що це означає | +| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | Установіть `false` для локальних/self-hosted провайдерів, які ніколи не мають отримувати ціни з OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Мапування пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Мапування пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: -| Поле | Тип | Що воно означає | -| -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор provider у зовнішньому каталозі, коли він відрізняється від ідентифікатора provider OpenClaw, наприклад `z-ai` для provider `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей зі slash як вкладені посилання provider/model; корисно для proxy provider, таких як OpenRouter. | -| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей у зовнішньому каталозі. `version-dots` перевіряє ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | +| Поле | Тип | Що це означає | +| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ | +| `provider` | `string` | Ідентифікатор провайдера зовнішнього каталогу, якщо він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | +| `passthroughProviderModel`| `boolean` | Розглядати ідентифікатори моделей, що містять слеш, як вкладені посилання provider/model; корисно для проксі-провайдерів, таких як OpenRouter. | +| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує ідентифікатори версій із крапками, такі як `claude-opus-4.6`. | -### Індекс Provider OpenClaw +### Індекс провайдерів OpenClaw -Індекс Provider OpenClaw — це preview-метадані, якими володіє OpenClaw, для -provider, plugin яких ще можуть бути не встановлені. Він не є частиною -маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом для -встановлених plugin. Індекс Provider — це внутрішній резервний контракт, який -в майбутньому використовуватимуть поверхні installable-provider і селектори -моделей до встановлення, коли plugin provider не встановлено. +Індекс провайдерів OpenClaw — це preview-метадані провайдерів, що належать OpenClaw, для провайдерів, +Plugin яких, можливо, ще не встановлено. Він не є частиною маніфесту Plugin. +Маніфести Plugin залишаються джерелом істини для встановлених Plugin. Індекс провайдерів — це +внутрішній резервний контракт, який майбутні поверхні для встановлюваних провайдерів і вибору моделей до встановлення +споживатимуть, коли Plugin провайдера не встановлено. -Порядок авторитетності каталогу: +Порядок пріоритету джерел каталогу: 1. Конфігурація користувача. -2. `modelCatalog` маніфесту встановленого plugin. +2. `modelCatalog` маніфесту встановленого Plugin. 3. Кеш каталогу моделей після явного оновлення. -4. Preview-рядки Індексу Provider OpenClaw. +4. Preview-рядки Індексу провайдерів OpenClaw. -Індекс Provider не повинен містити секрети, стан увімкнення, hooks середовища -виконання або живі дані моделей, специфічні для облікового запису. Його -preview-каталоги використовують ту саму форму рядків provider `modelCatalog`, -що й маніфести plugin, але мають обмежуватися стабільними метаданими -відображення, якщо тільки поля адаптера середовища виконання, такі як `api`, -`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно -узгодженими з маніфестом встановленого plugin. Provider із живим виявленням -через `/models` мають записувати оновлені рядки через явний шлях кешу каталогу -моделей, а не змушувати звичайне відображення списків або онбординг викликати -API provider. +Індекс провайдерів не повинен містити секрети, стан увімкнення, хуки середовища виконання або +живі дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму +форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають обмежуватися +стабільними метаданими відображення, якщо тільки поля адаптера середовища виконання, такі як `api`, +`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з +маніфестом встановленого Plugin. Провайдери з живим виявленням `/models` мають +записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, щоб +у звичайному переліку або онбордингу викликати API провайдера. -Записи Індексу Provider також можуть містити метадані installable-plugin для -provider, plugin яких було винесено з core або які ще не встановлено. Ці -метадані повторюють шаблон каталогу channel: назви пакета, специфікація -встановлення npm, очікувана цілісність і легковагові мітки варіантів auth -достатні, щоб показати варіант налаштування встановлюваного plugin. Після -встановлення plugin його маніфест має пріоритет, а запис Індексу Provider для -цього provider ігнорується. +Записи Індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, +Plugin яких було винесено з ядра або які ще не встановлено з інших причин. Ці +метадані повторюють шаблон каталогу каналів: назви пакета, специфікація npm install, +очікувана цілісність і дешеві мітки варіантів автентифікації достатні, щоб показати +встановлюваний варіант налаштування. Після встановлення Plugin його маніфест має перевагу, а +запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі верхньорівневі ключі можливостей є deprecated. Використовуйте -`openclaw doctor --fix`, щоб перемістити `speechProviders`, -`realtimeTranscriptionProviders`, `realtimeVoiceProviders`, -`mediaUnderstandingProviders`, `imageGenerationProviders`, -`videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під -`contracts`; звичайне завантаження маніфесту більше не трактує ці -верхньорівневі поля як володіння можливостями. +Застарілі ключі можливостей верхнього рівня виводяться з ужитку. Використовуйте `openclaw doctor --fix`, щоб +перемістити `speechProviders`, `realtimeTranscriptionProviders`, +`realtimeVoiceProviders`, `mediaUnderstandingProviders`, +`imageGenerationProviders`, `videoGenerationProviders`, +`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне +завантаження маніфесту більше не трактує ці поля верхнього рівня як +володіння можливостями. ## Маніфест проти package.json Ці два файли виконують різні завдання: -| Файл | Для чого його використовувати | +| Файл | Для чого використовувати | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів auth і підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, контролю встановлення, setup або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмежень встановлення, налаштування або метаданих каталогу | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте -таке правило: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати це до завантаження коду plugin, розмістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розмістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки npm install, розміщуйте це в `package.json` -### Поля `package.json`, які впливають на виявлення +### Поля package.json, які впливають на виявлення -Деякі метадані plugin, що потрібні до запуску середовища виконання, -навмисно зберігаються в `package.json` у блоці `openclaw`, а не в -`openclaw.plugin.json`. +Деякі метадані Plugin до запуску середовища виконання навмисно розміщуються в `package.json` у блоці +`openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує точки входу власного plugin. Має залишатися в каталозі пакета plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript середовища виконання для встановлених пакетів. Має залишатися в каталозі пакета plugin. | -| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel і виявлення статусу channel/SecretRef у режимі лише для читання. Має залишатися в каталозі пакета plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в каталозі пакета plugin. | -| `openclaw.channel` | Легковагові метадані каталогу channel, такі як мітки, шляхи до документації, аліаси та текст для вибору. | -| `openclaw.channel.commands` | Статичні метадані автотипових значень для native command і native skill, які використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження середовища виконання channel. | -| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання channel. | -| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану auth, які можуть відповісти на запитання «чи вже є якийсь вхід у систему?» без завантаження повного середовища виконання channel. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки щодо встановлення/оновлення для bundle plugin і plugin, опублікованих зовнішньо. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімально підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним отриманий артефакт. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundle plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. | +| Поле | Що це означає | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує точки входу власних Plugin. Мають залишатися всередині каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу побудованого JavaScript середовища виконання для встановлених пакетів. Мають залишатися всередині каталогу пакета Plugin. | +| `openclaw.setupEntry` | Полегшена точка входу лише для налаштування, яка використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися всередині каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує точку входу побудованого JavaScript налаштування для встановлених пакетів. Має залишатися всередині каталогу пакета Plugin. | +| `openclaw.channel` | Полегшені метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.commands` | Статичні метадані авто-значень native command і native Skill, які використовуються поверхнями конфігурації, аудиту та списку команд до завантаження середовища виконання каналу. | +| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. | +| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже є хоч один виконаний вхід?» без завантаження повного середовища виконання каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих Plugin. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, як-от `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного Plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються -в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` -повідомляє онбордингу, як отримати або ввімкнути цей plugin, коли користувач -обирає один із цих варіантів. Не переносіть підказки щодо встановлення в -`openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в +онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих +варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та -завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але -коректні значення пропускають plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру +маніфесту. Недійсні значення відхиляються; новіші, але коректні значення пропускають +Plugin на старіших хостах. Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього -каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки -оновлення завершувалися безпечним блокуванням, якщо отриманий артефакт npm -більше не відповідає закріпленому релізу. Інтерактивний онбординг, як і -раніше, пропонує довірені специфікації npm реєстру, включно з голими назвами -пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти -точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю -назви пакета та з недійсним source default-choice. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає коректного npm source, який можна -закріпити. Коли `expectedIntegrity` присутній, потоки встановлення/оновлення -застосовують його; коли його пропущено, розв’язання реєстру записується без -закріплення за цілісністю. +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення +завершувалися безпечною відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. +Інтерактивний онбординг усе ще пропонує довірені npm-специфікації реєстру, включно з простими +назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та недійсні джерела типового вибору. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає коректного джерела npm, яке можна ним закріпити. +Коли `expectedIntegrity` присутній, +потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру +фіксується без закріплення цілісності. -Plugin channel мають надавати `openclaw.setupEntry`, коли статус, список -channel або сканування SecretRef потребують визначення налаштованих облікових -записів без завантаження повного середовища виконання. Запис setup має -експонувати метадані channel разом із безпечними для setup адаптерами -конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і -transport runtime слід тримати в основній точці входу extension. +Plugin каналів мають надавати `openclaw.setupEntry`, коли статус, список каналів +або сканування SecretRef повинні визначати налаштовані облікові записи без завантаження повного +середовища виконання. Запис налаштування має надавати метадані каналу разом із безпечними для налаштування +адаптерами конфігурації, стану та секретів; залишайте мережеві клієнти, слухачі gateway і +середовища виконання транспорту в основній точці входу розширення. -Поля точки входу середовища виконання не скасовують перевірки меж пакета для -полів точки входу джерела. Наприклад, `openclaw.runtimeExtensions` не може -зробити шлях `openclaw.extensions`, що виходить за межі пакета, придатним до -завантаження. +Поля точок входу середовища виконання не перевизначають перевірки меж пакета для полів +точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +завантажуваним шлях `openclaw.extensions`, що виходить за межі. -`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке -призначення. Він не робить довільні зламані конфігурації придатними для -встановлення. Наразі він лише дозволяє потокам встановлення відновлюватися -після певних застарілих збоїв оновлення bundle plugin, наприклад відсутнього -шляху до bundle plugin або застарілого запису `channels.` для того самого -bundle plugin. Непов’язані помилки конфігурації, як і раніше, блокують -встановлення та спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно +не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення +відновлюватися після певних застарілих збоїв оновлення вбудованих Plugin, таких як +відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого +вбудованого Plugin. Не пов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів +до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного -модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -966,10 +926,10 @@ bundle plugin. Непов’язані помилки конфігурації, } ``` -Використовуйте його, коли потокам setup, doctor або configured-state потрібна -дешева перевірка auth “так/ні” до завантаження повного plugin channel. -Цільовий export має бути невеликою функцією, яка лише читає збережений стан; -не маршрутизуйте його через повний barrel середовища виконання channel. +Використовуйте це, коли потокам налаштування, doctor або configured-state потрібна дешева перевірка +автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою +функцією, яка лише читає збережений стан; не спрямовуйте її через широкий модуль повного +середовища виконання каналу. `openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: @@ -988,71 +948,68 @@ bundle plugin. Непов’язані помилки конфігурації, } ``` -Використовуйте це, коли channel може визначити налаштований стан на основі env -або інших невеликих невиконавчих вхідних даних. Якщо перевірка потребує -повного розв’язання конфігурації або справжнього середовища виконання channel, -залишайте цю логіку в hook `config.hasConfiguredState` plugin. +Використовуйте це, коли канал може визначити налаштований стан з env або інших малих +невиконуваних входів. Якщо перевірка потребує повного розв’язання конфігурації або реального +середовища виконання каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дубльовані ідентифікатори plugin) +## Пріоритет виявлення (дубльовані ідентифікатори Plugin) -OpenClaw виявляє plugin із кількох коренів (bundle, глобальне встановлення, -workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені plugin мають -однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; -дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч із ним. +OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, робоча область, явно вибрані конфігурацією шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест **із найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. Пріоритет від найвищого до найнижчого: -1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` -2. **Bundled** — plugin, що постачаються з OpenClaw -3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw -4. **Workspace** — plugin, виявлені відносно поточного workspace +1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — Plugin, що постачаються з OpenClaw +3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw +4. **Робоча область** — Plugin, виявлені відносно поточної робочої області Наслідки: -- Fork або застаріла копія bundled plugin у workspace не перекриє bundled-збірку. -- Щоб справді перевизначити bundled plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. -- Відкинуті дублікати записуються в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Форк або застаріла копія вбудованого Plugin, що лежить у робочій області, не затьмарить вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення в робочій області. +- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен plugin повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня schema є допустимою (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання. +- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми валідуються під час читання/запису конфігурації, а не під час виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошено в маніфесті plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено + маніфестом Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **plugin id, які можна виявити**. Невідомі ідентифікатори є **помилками**. -- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи schema, - валідація завершується помилкою, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і + мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. +- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, + валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і в Doctor + журналах з’являється **попередження**. -Повну схему `plugins.*` дивіться в [Довіднику з конфігурації](/uk/gateway/configuration). +Повну схему `plugins.*` див. у [Довіднику конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для власних plugin OpenClaw**, зокрема для завантаження з локальної файлової системи. Середовище виконання, як і раніше, завантажує модуль plugin окремо; маніфест використовується лише для виявлення + валідації. -- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. -- Завантажувач маніфесту читає лише документовані поля маніфесту. Уникайте користувацьких верхньорівневих ключів. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів виявлення, а не для виконання під час запитів. -- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Метадані wizard середовища виконання, які потребують коду provider, дивіться в [Хуки середовища виконання Provider](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш plugin залежить від власних модулів, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання все одно завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. +- Власні маніфести аналізуються за допомогою JSON5, тож коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широке середовище виконання; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри Plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Метадані майстра середовища виконання, які потребують коду провайдера, див. у [Хуках середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з plugin. + + Початок роботи з Plugin. - + Внутрішня архітектура та модель можливостей. - Довідник SDK plugin та імпорти підшляхів. + Довідник SDK Plugin та імпорти підшляхів. diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md index a16cb7d40..f3c1c9504 100644 --- a/docs/uk/tools/browser.md +++ b/docs/uk/tools/browser.md @@ -1,41 +1,41 @@ --- read_when: - - Додавання автоматизації браузера, керованої агентом + - Додавання автоматизації браузера під керуванням агента - Налагодження того, чому openclaw заважає вашому власному Chrome - - Реалізація налаштувань браузера та його життєвого циклу в застосунку для macOS + - Реалізація налаштувань браузера та його життєвого циклу в застосунку macOS summary: Інтегрований сервіс керування браузером + команди дій -title: Browser (керований OpenClaw) +title: Браузер (під керуванням OpenClaw) x-i18n: - generated_at: "2026-04-27T07:10:11Z" + generated_at: "2026-04-27T08:45:05Z" model: gpt-5.4 provider: openai - source_hash: 0e576b013e49917b6d5b118c22d7b91a65e1f1997dc86eb51881ed30806dafe9 + source_hash: 65397ea2405aeb34d4e08c8968f3dc15ab8ed446c69d77274f069fc72f90c59a source_path: tools/browser.md workflow: 15 --- OpenClaw може запускати **окремий профіль Chrome/Brave/Edge/Chromium**, яким керує агент. Він ізольований від вашого особистого браузера та керується через невеликий локальний -сервіс керування всередині Gateway (лише local loopback). +сервіс керування всередині Gateway (лише loopback). -Погляд для початківців: +Пояснення для початківців: -- Сприймайте це як **окремий браузер лише для агента**. -- Профіль `openclaw` **не** торкається вашого особистого профілю браузера. +- Думайте про це як про **окремий браузер лише для агента**. +- Профіль `openclaw` **не** торкається профілю вашого особистого браузера. - Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі. -- Вбудований профіль `user` під’єднується до вашої справжньої авторизованої сесії Chrome через Chrome MCP. +- Вбудований профіль `user` підключається до вашої справжньої авторизованої сесії Chrome через Chrome MCP. -## Що ви отримаєте +## Що ви отримуєте - Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом). -- Детерміноване керування вкладками (список/відкрити/фокус/закрити). -- Дії агента (натискання/введення/перетягування/вибір), знімки стану, знімки екрана, PDF. -- Вбудований skill `browser-automation`, який навчає агентів циклу відновлення snapshot, - stable-tab, stale-ref і manual-blocker, коли Plugin браузера увімкнено. -- Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...). +- Детерміноване керування вкладками (перелік/відкриття/фокусування/закриття). +- Дії агента (натискання/введення/перетягування/вибір), знімки стану, скриншоти, PDF. +- Вбудований навик `browser-automation`, який навчає агентів циклу відновлення snapshot, + stable-tab, stale-ref і manual-blocker, коли увімкнено браузерний Plugin. +- Необов’язкову підтримку кількох профілів (`openclaw`, `work`, `remote`, ...). -Цей браузер **не** призначений для вашого щоденного використання. Це безпечна, ізольована поверхня для -автоматизації та перевірки агентом. +Цей браузер **не** є вашим основним щоденним браузером. Це безпечна, ізольована поверхня для +автоматизації агентом і перевірки. ## Швидкий старт @@ -48,15 +48,15 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Якщо ви отримуєте “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть +Якщо ви бачите повідомлення “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть Gateway. -Якщо `openclaw browser` повністю відсутній або агент каже, що інструмент браузера -недоступний, перейдіть до [Відсутня команда або інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool). +Якщо `openclaw browser` взагалі відсутній або агент каже, що браузерний інструмент +недоступний, перейдіть до [Відсутня команда або інструмент browser](/uk/tools/browser#missing-browser-command-or-tool). ## Керування Plugin -Типовий інструмент `browser` — це вбудований Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє той самий інструмент з назвою `browser`: +Типовий інструмент `browser` — це вбудований Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє той самий інструмент із назвою `browser`: ```json5 { @@ -70,15 +70,15 @@ Gateway. } ``` -Для типових значень потрібні і `plugins.entries.browser.enabled`, і `browser.enabled=true`. Вимкнення лише Plugin прибирає CLI `openclaw browser`, метод Gateway `browser.request`, інструмент агента та сервіс керування як єдине ціле; ваш конфіг `browser.*` залишається незмінним для заміни. +Для типових налаштувань потрібні і `plugins.entries.browser.enabled`, і `browser.enabled=true`. Якщо вимкнути лише Plugin, це як єдиний блок прибере CLI `openclaw browser`, метод Gateway `browser.request`, інструмент агента та сервіс керування; ваша конфігурація `browser.*` залишиться недоторканою для заміни. -Зміни конфігурації браузера потребують перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс. +Зміни конфігурації браузера вимагають перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс. -## Вказівки для агента +## Рекомендації для агента -Примітка щодо профілю інструментів: `tools.profile: "coding"` включає `web_search` і +Примітка про профіль інструментів: `tools.profile: "coding"` включає `web_search` і `web_fetch`, але не включає повний інструмент `browser`. Якщо агент або -породжений sub-agent має використовувати автоматизацію браузера, додайте browser на етапі профілю: +породжений підагент має використовувати автоматизацію браузера, додайте browser на етапі профілю: ```json5 { @@ -90,25 +90,26 @@ Gateway. ``` Для одного агента використовуйте `agents.list[].tools.alsoAllow: ["browser"]`. -Лише `tools.subagents.tools.allow: ["browser"]` недостатньо, тому що політика sub-agent +Одного лише `tools.subagents.tools.allow: ["browser"]` недостатньо, оскільки політика підагента застосовується після фільтрації профілю. -Plugin браузера постачається з двома рівнями вказівок для агента: +Browser Plugin постачається з двома рівнями рекомендацій для агента: -- Опис інструмента `browser` містить компактний, завжди активний контракт: оберіть - правильний профіль, зберігайте refs у межах тієї самої вкладки, використовуйте `tabId`/мітки для націлювання на вкладки та завантажуйте skill браузера для багатокрокової роботи. -- Вбудований skill `browser-automation` містить довший робочий цикл: - спочатку перевірити статус/вкладки, позначити вкладки завдання, зробити snapshot перед дією, повторно зробити snapshot - після змін в UI, один раз відновити stale refs і повідомляти про login/2FA/captcha або - блокування camera/microphone як ручну дію замість здогадок. +- Опис інструмента `browser` містить компактний, завжди активний контракт: обирайте + правильний профіль, тримайте ref у межах однієї вкладки, використовуйте `tabId`/мітки для + вибору вкладки та завантажуйте browser skill для багатокрокових завдань. +- Вбудований навик `browser-automation` містить довший робочий цикл: + спочатку перевіряйте status/tabs, позначайте вкладки завдання, робіть snapshot перед дією, + повторно знімайте snapshot після змін UI, один раз відновлюйте stale refs і повідомляйте про + login/2FA/captcha або блокування camera/microphone як про ручну дію, а не вгадуйте. -Skills, вбудовані в Plugin, показуються в списку доступних skills агента, коли -Plugin увімкнений. Повні інструкції skill завантажуються за потреби, тому звичайні -звернення не несуть повної вартості токенів. +Навички, вбудовані в Plugin, перелічуються серед доступних навичок агента, коли +Plugin увімкнено. Повні інструкції навички завантажуються на вимогу, тому звичайні +звернення не оплачують повну вартість у токенах. -## Відсутня команда або інструмент браузера +## Відсутня команда або інструмент browser -Якщо після оновлення `openclaw browser` невідома, `browser.request` відсутній або агент повідомляє, що інструмент браузера недоступний, звичайна причина — список `plugins.allow`, у якому немає `browser`. Додайте його: +Якщо після оновлення `openclaw browser` невідомий, `browser.request` відсутній або агент повідомляє, що інструмент browser недоступний, звичайна причина — список `plugins.allow`, у якому немає `browser`, і відсутній кореневий блок конфігурації `browser`. Додайте його: ```json5 { @@ -118,25 +119,25 @@ Plugin увімкнений. Повні інструкції skill завант } ``` -`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство в allowlist — allowlist керує завантаженням Plugin, а політика інструментів запускається лише після завантаження. Видалення `plugins.allow` повністю також відновлює типову поведінку. +Явний кореневий блок `browser`, наприклад `browser.enabled=true` або `browser.profiles.`, активує вбудований browser Plugin навіть за обмежувального `plugins.allow`, що відповідає поведінці конфігурації каналів. `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` самі по собі не замінюють членство у списку дозволених. Повне видалення `plugins.allow` також відновлює типову поведінку. ## Профілі: `openclaw` проти `user` - `openclaw`: керований, ізольований браузер (розширення не потрібне). -- `user`: вбудований профіль під’єднання Chrome MCP до вашої **справжньої авторизованої сесії Chrome**. +- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої авторизованої сесії Chrome**. -Для викликів інструмента браузера агентом: +Для викликів браузерного інструмента агентом: - Типово: використовуйте ізольований браузер `openclaw`. -- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії та користувач - перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на під’єднання. +- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії, а користувач + перебуває за комп’ютером і може натиснути/підтвердити будь-який запит на підключення. - `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера. -Установіть `browser.defaultProfile: "openclaw"`, якщо хочете типово використовувати керований режим. +Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. ## Конфігурація -Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`. +Налаштування браузера зберігаються у `~/.openclaw/openclaw.json`. ```json5 { @@ -195,57 +196,55 @@ Plugin увімкнений. Повні інструкції skill завант -- Сервіс керування прив’язується до local loopback на порту, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в цій самій родині. -- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; установлюйте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типово використовується керований локальний порт CDP. -- `remoteCdpTimeoutMs` застосовується до перевірок HTTP-доступності віддаленого й `attachOnly` CDP - та HTTP-запитів на відкриття вкладок; `remoteCdpHandshakeTimeoutMs` застосовується до - їхніх CDP WebSocket handshakes. -- `localLaunchTimeoutMs` — це бюджет часу для локально запущеного керованого процесу Chrome, - щоб він відкрив свій CDP HTTP endpoint. `localCdpReadyTimeoutMs` — це - подальший бюджет для готовності CDP websocket після виявлення процесу. - Збільшуйте ці значення на Raspberry Pi, бюджетних VPS або старішому обладнанні, де Chromium +- Сервіс керування прив’язується до local loopback на порті, похідному від `gateway.port` (типово `18791` = Gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в тій самій групі. +- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типово використовується локальний керований порт CDP. +- `remoteCdpTimeoutMs` застосовується до перевірок доступності HTTP для віддалених і `attachOnly` CDP, а також до HTTP-запитів відкриття вкладок; `remoteCdpHandshakeTimeoutMs` застосовується до їхніх WebSocket-handshake CDP. +- `localLaunchTimeoutMs` — це бюджет часу, протягом якого локально запущений керований процес Chrome + має відкрити свій CDP HTTP endpoint. `localCdpReadyTimeoutMs` — це + наступний бюджет часу для готовності CDP websocket після виявлення процесу. + Збільшуйте ці значення на Raspberry Pi, малопотужних VPS або старішому обладнанні, де Chromium запускається повільно. Значення мають бути додатними цілими числами до `120000` мс; некоректні значення конфігурації відхиляються. -- `actionTimeoutMs` — це типовий бюджет для запитів browser `act`, коли викликач не передає `timeoutMs`. Транспорт клієнта додає невелике вікно запасу, щоб довгі очікування могли завершитися, а не завершувалися за таймаутом на межі HTTP. -- `tabCleanup` — це best-effort очищення вкладок, відкритих первинними сесіями браузера агента. Очищення життєвого циклу subagent, Cron і ACP, як і раніше, закриває їхні явно відстежувані вкладки наприкінці сесії; первинні сесії залишають активні вкладки придатними для повторного використання, а потім у фоновому режимі закривають неактивні або зайві відстежувані вкладки. +- `actionTimeoutMs` — це типовий бюджет часу для запитів browser `act`, коли виклик не передає `timeoutMs`. Транспорт клієнта додає невелике запасне вікно, щоб довгі очікування могли завершитися, а не обривалися на межі HTTP-таймауту. +- `tabCleanup` — це best-effort очищення вкладок, відкритих основними сесіями browser агента. Очищення життєвого циклу підагента, Cron і ACP усе ще закриває їхні явно відстежувані вкладки наприкінці сесії; основні сесії зберігають активні вкладки придатними до повторного використання, а потім у фоновому режимі закривають неактивні або зайві відстежувані вкладки. -- Навігація браузера й open-tab захищені від SSRF перед переходом і best-effort повторно перевіряються на фінальному `http(s)` URL після нього. -- У строгому режимі SSRF також перевіряються виявлення віддаленого endpoint CDP і запити `/json/version` (`cdpUrl`). -- Змінні середовища `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` і `NO_PROXY` Gateway/провайдера не проксіюють автоматично браузер, керований OpenClaw. Керований Chrome типово запускається напряму, щоб налаштування проксі провайдера не послаблювали перевірки SSRF браузера. -- Щоб проксіювати сам керований браузер, передайте явні прапорці проксі Chrome через `browser.extraArgs`, наприклад `--proxy-server=...` або `--proxy-pac-url=...`. Строгий режим SSRF блокує явну проксі-маршрутизацію браузера, якщо доступ браузера до приватної мережі не увімкнено навмисно. -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі свідомо вважається довіреним. -- `browser.ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. +- Навігація браузера та open-tab захищені SSRF-перевіркою перед переходом і повторно best-effort перевіряються на фінальній URL-адресі `http(s)` після цього. +- У строгому режимі SSRF також перевіряються виявлення віддаленого CDP endpoint і зондування `/json/version` (`cdpUrl`). +- Змінні середовища `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` і `NO_PROXY` для Gateway/provider не проксіюють автоматично браузер під керуванням OpenClaw. Керований Chrome типово запускається напряму, щоб налаштування проксі provider не послаблювали SSRF-перевірки браузера. +- Щоб проксіювати сам керований браузер, передайте явні прапорці проксі Chrome через `browser.extraArgs`, наприклад `--proxy-server=...` або `--proxy-pac-url=...`. Строгий режим SSRF блокує явну маршрутизацію браузерного проксі, якщо доступ браузера до приватної мережі не був навмисно увімкнений. +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте його лише тоді, коли доступ браузера до приватної мережі свідомо вважається довіреним. +- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім. -- `attachOnly: true` означає ніколи не запускати локальний браузер; лише під’єднуватися, якщо він уже працює. -- `headless` можна задавати глобально або для окремого локального керованого профілю. Значення на рівні профілю перевизначають `browser.headless`, тому один локально запущений профіль може залишатися headless, тоді як інший — видимим. +- `attachOnly: true` означає ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений. +- `headless` можна задавати глобально або для окремого локального керованого профілю. Значення на рівні профілю перевизначають `browser.headless`, тож один локально запущений профіль може залишатися headless, а інший — видимим. - `POST /start?headless=true` і `openclaw browser start --headless` запитують - одноразовий headless-запуск для локальних керованих профілів без перезапису + одноразовий запуск у режимі headless для локальних керованих профілів без перезапису `browser.headless` або конфігурації профілю. Профілі existing-session, attach-only і remote CDP відхиляють це перевизначення, тому що OpenClaw не запускає ці процеси браузера. -- На Linux-хостах без `DISPLAY` або `WAYLAND_DISPLAY` локальні керовані профілі - типово автоматично переходять у headless, якщо ні середовище, ні конфігурація профілю/глобальна +- На хостах Linux без `DISPLAY` або `WAYLAND_DISPLAY` локальні керовані профілі + типово автоматично переходять у режим headless, якщо ні середовище, ні конфігурація профілю/глобальна конфігурація явно не вибирають режим із вікном. `openclaw browser status --json` - показує `headlessSource` як `env`, `profile`, `config`, + повідомляє `headlessSource` як `env`, `profile`, `config`, `request`, `linux-display-fallback` або `default`. -- `OPENCLAW_BROWSER_HEADLESS=1` примусово запускає локальні керовані профілі в headless для +- `OPENCLAW_BROWSER_HEADLESS=1` примусово вмикає запуск локальних керованих браузерів у режимі headless для поточного процесу. `OPENCLAW_BROWSER_HEADLESS=0` примусово вмикає режим із вікном для звичайних - запусків і повертає зрозумілу помилку на Linux-хостах без display server; + запусків і повертає придатну до дії помилку на хостах Linux без display server; явний запит `start --headless` усе одно має пріоритет для цього одного запуску. -- `executablePath` можна задавати глобально або для окремого локального керованого профілю. Значення на рівні профілю перевизначають `browser.executablePath`, тому різні керовані профілі можуть запускати різні браузери на базі Chromium. Обидві форми приймають `~` для домашнього каталогу вашої ОС. +- `executablePath` можна задавати глобально або для окремого локального керованого профілю. Значення на рівні профілю перевизначають `browser.executablePath`, тож різні керовані профілі можуть запускати різні браузери на базі Chromium. Обидві форми підтримують `~` для домашнього каталогу вашої ОС. - `color` (верхній рівень і рівень профілю) тонує UI браузера, щоб ви могли бачити, який профіль активний. -- Типовий профіль — `openclaw` (керований автономний). Використовуйте `defaultProfile: "user"`, щоб за замовчуванням працювати з авторизованим браузером користувача. -- Порядок автовиявлення: системний типовий браузер, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. +- Типовий профіль — `openclaw` (керований автономний). Використовуйте `defaultProfile: "user"`, щоб типово перейти на авторизований браузер користувача. +- Порядок автовиявлення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. - `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не задавайте `cdpUrl` для цього драйвера. -- Установіть `browser.profiles..userDataDir`, коли профіль existing-session має під’єднуватися до нетипового профілю користувача Chromium (Brave, Edge тощо). Цей шлях також приймає `~` для домашнього каталогу вашої ОС. +- Установіть `browser.profiles..userDataDir`, коли профіль existing-session має підключатися до нестандартного профілю користувача Chromium (Brave, Edge тощо). Цей шлях також підтримує `~` для домашнього каталогу вашої ОС. @@ -253,9 +252,9 @@ Plugin увімкнений. Повні інструкції skill завант ## Використання Brave або іншого браузера на базі Chromium -Якщо ваш **системний типовий** браузер працює на базі Chromium (Chrome/Brave/Edge тощо), +Якщо ваш **системний браузер за замовчуванням** побудований на Chromium (Chrome/Brave/Edge тощо), OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити -автовиявлення. Значення `executablePath` верхнього рівня та рівня профілю приймають `~` +автовиявлення. Значення `executablePath` на верхньому рівні й рівні профілю підтримують `~` для домашнього каталогу вашої ОС: ```bash @@ -295,21 +294,21 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C -`executablePath` на рівні профілю впливає лише на локальні керовані профілі, які запускає OpenClaw. -Профілі `existing-session` натомість під’єднуються до вже запущеного браузера, +`executablePath` на рівні профілю впливає лише на локальні керовані профілі, які +запускає OpenClaw. Натомість профілі `existing-session` підключаються до вже запущеного браузера, а віддалені профілі CDP використовують браузер за `cdpUrl`. ## Локальне та віддалене керування -- **Локальне керування (типово):** Gateway запускає сервіс керування на loopback і може запускати локальний браузер. +- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер. - **Віддалене керування (хост Node):** запустіть хост Node на машині, де є браузер; Gateway проксіюватиме до нього дії браузера. -- **Віддалений CDP:** задайте `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб - під’єднатися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер. -- Для зовнішньо керованих сервісів CDP на loopback (наприклад, Browserless у - Docker, опублікований на `127.0.0.1`) також задайте `attachOnly: true`. CDP на - loopback без `attachOnly` вважається локальним профілем браузера, керованим OpenClaw. +- **Віддалений CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб + підключитися до віддаленого браузера на базі Chromium. У цьому разі OpenClaw не запускатиме локальний браузер. +- Для зовнішньо керованих сервісів CDP на loopback (наприклад Browserless у + Docker, опублікований на `127.0.0.1`) також установіть `attachOnly: true`. CDP на loopback + без `attachOnly` розглядається як локальний профіль браузера під керуванням OpenClaw. - `headless` впливає лише на локальні керовані профілі, які запускає OpenClaw. Він не перезапускає і не змінює браузери existing-session або віддалені браузери CDP. -- `executablePath` підпорядковується тому ж правилу локального керованого профілю. Його зміна для +- `executablePath` дотримується того самого правила для локальних керованих профілів. Його зміна для запущеного локального керованого профілю позначає цей профіль для перезапуску/узгодження, щоб наступний запуск використовував новий бінарний файл. @@ -319,40 +318,40 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C запустив OpenClaw - профілі attach-only і віддалені профілі CDP: `openclaw browser stop` закриває активну сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport, - колірну схему, locale, часовий пояс, offline-режим та подібний стан), - хоча OpenClaw не запускав жодного процесу браузера + колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть + якщо OpenClaw не запускав процес браузера -Віддалені URL CDP можуть містити автентифікацію: +URL-адреси віддаленого CDP можуть містити автентифікацію: -- токени запиту (наприклад, `https://provider.example?token=`) +- Токени в параметрах запиту (наприклад, `https://provider.example?token=`) - HTTP Basic auth (наприклад, `https://user:pass@provider.example`) -OpenClaw зберігає цю автентифікацію під час виклику endpoint-ів `/json/*` і під час підключення -до CDP WebSocket. Для токенів надавайте перевагу змінним середовища або менеджерам секретів -замість збереження їх у файлах конфігурації. +OpenClaw зберігає ці дані автентифікації під час виклику endpoint-ів `/json/*` і при підключенні +до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів, +а не комітити їх у файли конфігурації. -## Проксі браузера Node (типова поведінка без додаткового налаштування) +## Проксі браузера Node (типовий режим без конфігурації) Якщо ви запускаєте **хост Node** на машині, де є ваш браузер, OpenClaw може -автоматично маршрутизувати виклики інструмента браузера до цього node без жодної додаткової конфігурації браузера. -Це типовий шлях для віддалених gateway. +автоматично спрямовувати виклики браузерного інструмента на цей вузол без жодної додаткової конфігурації браузера. +Це типовий шлях для віддалених Gateway. Примітки: -- Хост node надає свій локальний сервер керування браузером через **proxy command**. -- Профілі беруться з власної конфігурації `browser.profiles` node (такої самої, як локально). -- `nodeHost.browserProxy.allowProfiles` — необов’язковий. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. -- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw трактує це як межу найменших привілеїв: можна націлюватися лише на профілі з allowlist, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі. +- Хост Node надає свій локальний сервер керування браузером через **проксі-команду**. +- Профілі беруться з власної конфігурації `browser.profiles` вузла (так само, як локально). +- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. +- Якщо ви встановите `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядатиме його як межу мінімальних привілеїв: можна буде націлюватися лише на профілі зі списку дозволених, а маршрути створення/видалення постійних профілів будуть заблоковані на поверхні проксі. - Вимкніть це, якщо воно вам не потрібне: - - На node: `nodeHost.browserProxy.enabled=false` + - На вузлі: `nodeHost.browserProxy.enabled=false` - На gateway: `gateway.nodes.browser.mode="off"` -## Browserless (хостинговий віддалений CDP) +## Browserless (розміщений віддалений CDP) -[Browserless](https://browserless.io) — це хостингова служба Chromium, яка надає -URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але +[Browserless](https://browserless.io) — це розміщений сервіс Chromium, який надає +URL-адреси підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку з форм, але для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket -з документації Browserless щодо підключення. +із документації Browserless про підключення. Приклад: @@ -377,13 +376,13 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може - Замініть `` на ваш справжній токен Browserless. - Виберіть endpoint регіону, який відповідає вашому обліковому запису Browserless (див. їхню документацію). -- Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на - `wss://` для прямого CDP-підключення, або залишити URL HTTPS і дозволити OpenClaw +- Якщо Browserless надає вам базову URL-адресу HTTPS, ви можете або перетворити її на + `wss://` для прямого підключення CDP, або залишити HTTPS URL і дозволити OpenClaw виявити `/json/version`. -### Browserless Docker на тому ж хості +### Browserless Docker на тому самому хості -Коли Browserless самостійно розгорнуто в Docker, а OpenClaw працює на хості, розглядайте +Коли Browserless самостійно розміщений у Docker, а OpenClaw працює на хості, розглядайте Browserless як зовнішньо керований сервіс CDP: ```json5 @@ -403,47 +402,46 @@ Browserless як зовнішньо керований сервіс CDP: ``` Адреса в `browser.profiles.browserless.cdpUrl` має бути досяжною з процесу -OpenClaw. Browserless також має оголошувати відповідний досяжний endpoint; задайте -для Browserless `EXTERNAL` на ту саму публічно-доступну для OpenClaw базу WebSocket, наприклад -`ws://127.0.0.1:3000`, `ws://browserless:3000` або стабільну приватну адресу -мережі Docker. Якщо `/json/version` повертає `webSocketDebuggerUrl`, що вказує на -адресу, недосяжну для OpenClaw, CDP HTTP може виглядати справним, тоді як під’єднання до WebSocket усе одно не вдасться. +OpenClaw. Browserless також має оголошувати відповідний досяжний endpoint; установіть Browserless `EXTERNAL` на ту саму доступну OpenClaw публічну WebSocket-базу, наприклад +`ws://127.0.0.1:3000`, `ws://browserless:3000` або стабільну приватну адресу мережі Docker. +Якщо `/json/version` повертає `webSocketDebuggerUrl`, що вказує на адресу, недосяжну для OpenClaw, +HTTP CDP може виглядати справним, тоді як підключення WebSocket усе одно не вдасться. Не залишайте `attachOnly` незаданим для профілю Browserless на loopback. Без -`attachOnly` OpenClaw розглядає порт loopback як локальний керований профіль браузера -і може повідомити, що порт зайнятий, але не належить OpenClaw. +`attachOnly` OpenClaw розглядає loopback-порт як локальний керований профіль браузера +і може повідомляти, що порт використовується, але не належить OpenClaw. -## Провайдери прямого WebSocket CDP +## Прямі провайдери WebSocket CDP -Деякі хостингові сервіси браузерів надають **прямий endpoint WebSocket** замість -стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три -форми URL CDP і автоматично вибирає правильну стратегію підключення: +Деякі розміщені браузерні сервіси надають **прямий endpoint WebSocket**, а не +стандартне HTTP-виявлення CDP (`/json/version`). OpenClaw приймає три форми +URL CDP і автоматично вибирає правильну стратегію підключення: - **HTTP(S) виявлення** — `http://host[:port]` або `https://host[:port]`. - OpenClaw викликає `/json/version`, щоб виявити URL відладчика WebSocket, а потім - підключається. Резервного переходу на WebSocket немає. + OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім + підключається. Без запасного варіанта WebSocket. - **Прямі endpoint-и WebSocket** — `ws://host[:port]/devtools//` або `wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/`. - OpenClaw підключається безпосередньо через handshake WebSocket і повністю пропускає + OpenClaw підключається напряму через handshake WebSocket і повністю пропускає `/json/version`. -- **Базові корені WebSocket** — `ws://host[:port]` або `wss://host[:port]` без - шляху `/devtools/...` (наприклад, [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує HTTP - виявлення `/json/version` (нормалізуючи схему до `http`/`https`); +- **Кореневі WebSocket без шляху** — `ws://host[:port]` або `wss://host[:port]` без + шляху `/devtools/...` (наприклад [Browserless](https://browserless.io), + [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує HTTP-виявлення + `/json/version` (нормалізуючи схему до `http`/`https`); якщо виявлення повертає `webSocketDebuggerUrl`, він використовується, інакше OpenClaw - переходить до прямого handshake WebSocket на базовому корені. Якщо оголошений - endpoint WebSocket відхиляє handshake CDP, але налаштований базовий корінь - його приймає, OpenClaw також переходить до цього кореня. Це дозволяє базовому `ws://`, - спрямованому на локальний Chrome, усе ж під’єднатися, оскільки Chrome приймає оновлення - WebSocket лише на конкретному шляху для цілі з `/json/version`, тоді як хостингові - провайдери все ще можуть використовувати свій кореневий endpoint WebSocket, коли їхній endpoint - виявлення оголошує короткоживучий URL, непридатний для Playwright CDP. + переходить до прямого handshake WebSocket на голому корені. Якщо оголошений + endpoint WebSocket відхиляє handshake CDP, але налаштований голий корінь + його приймає, OpenClaw також повертається до цього кореня. Це дає змогу голому `ws://`, + спрямованому на локальний Chrome, усе одно підключатися, оскільки Chrome приймає оновлення WebSocket + лише на конкретному шляху для цілі з `/json/version`, тоді як розміщені + провайдери все ще можуть використовувати свій кореневий endpoint WebSocket, коли їхній endpoint виявлення + оголошує короткоживучу URL-адресу, непридатну для Playwright CDP. ### Browserbase [Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску -headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth-режимом і residential -proxy. +headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та резидентними +проксі. ```json5 { @@ -464,76 +462,76 @@ proxy. Примітки: -- [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте ваш **API Key** +- [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key** з [панелі Overview](https://www.browserbase.com/overview). - Замініть `` на ваш справжній API-ключ Browserbase. -- Browserbase автоматично створює сесію браузера під час WebSocket-підключення, тож - окремий крок ручного створення сесії не потрібен. -- Безкоштовний тариф дозволяє одну одночасну сесію і одну browser-hour на місяць. - Обмеження платних тарифів дивіться в [pricing](https://www.browserbase.com/pricing). -- Повний довідник API, посібники з SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). +- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому + ручний крок створення сесії не потрібен. +- Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. + Обмеження платних тарифів дивіться в розділі [pricing](https://www.browserbase.com/pricing). +- Повний довідник API, посібники SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). ## Безпека Ключові ідеї: -- Керування браузером доступне лише через loopback; доступ проходить через auth Gateway або pairing node. -- Окремий HTTP API браузера на loopback використовує **лише автентифікацію спільним секретом**: - bearer auth токеном gateway, `x-openclaw-password` або HTTP Basic auth із +- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або спаровування вузлів. +- Автономний loopback HTTP API браузера використовує **лише автентифікацію спільним секретом**: + bearer auth за токеном gateway, `x-openclaw-password` або HTTP Basic auth із налаштованим паролем gateway. -- Заголовки ідентифікації Tailscale Serve та `gateway.auth.mode: "trusted-proxy"` - **не** автентифікують цей окремий loopback API браузера. +- Заголовки ідентифікації Tailscale Serve і `gateway.auth.mode: "trusted-proxy"` + **не** автентифікують цей автономний loopback API браузера. - Якщо керування браузером увімкнено і не налаштовано жодної автентифікації спільним секретом, OpenClaw автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації. -- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` вже встановлено в +- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` вже має значення `password`, `none` або `trusted-proxy`. -- Тримайте Gateway і будь-які хости node у приватній мережі (Tailscale); уникайте публічного доступу. -- Розглядайте віддалені URL/токени CDP як секрети; надавайте перевагу змінним середовища або менеджеру секретів. +- Тримайте Gateway і будь-які хости вузлів у приватній мережі (Tailscale); уникайте публічної доступності. +- Вважайте URL-адреси/токени віддаленого CDP секретами; віддавайте перевагу змінним середовища або менеджеру секретів. Поради щодо віддаленого CDP: -- За можливості надавайте перевагу зашифрованим endpoint-ам (HTTPS або WSS) і короткоживучим токенам. +- За можливості віддавайте перевагу зашифрованим endpoint-ам (HTTPS або WSS) і короткоживучим токенам. - Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації. ## Профілі (кілька браузерів) -OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути такими: +OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути: -- **керовані OpenClaw**: окремий екземпляр браузера на базі Chromium із власним каталогом даних користувача + портом CDP -- **віддалені**: явний URL CDP (браузер на базі Chromium працює деінде) -- **наявна сесія**: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP +- **під керуванням OpenClaw**: окремий екземпляр браузера на базі Chromium із власним каталогом даних користувача + портом CDP +- **віддалені**: явна URL-адреса CDP (браузер на базі Chromium працює деінде) +- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP Типові значення: -- Профіль `openclaw` створюється автоматично, якщо відсутній. -- Профіль `user` вбудований для під’єднання existing-session через Chrome MCP. -- Профілі existing-session, окрім `user`, вмикаються явно; створюйте їх за допомогою `--driver existing-session`. +- Профіль `openclaw` створюється автоматично, якщо його немає. +- Профіль `user` вбудований для підключення до existing-session через Chrome MCP. +- Профілі existing-session, окрім `user`, вмикаються за бажанням; створюйте їх за допомогою `--driver existing-session`. - Локальні порти CDP типово виділяються з діапазону **18800–18899**. -- Видалення профілю переміщує його локальний каталог даних у Trash. +- Видалення профілю переміщує його локальний каталог даних до кошика. Усі endpoint-и керування приймають `?profile=`; CLI використовує `--browser-profile`. -## Existing session через Chrome DevTools MCP +## Наявна сесія через Chrome DevTools MCP -OpenClaw також може під’єднатися до запущеного профілю браузера на базі Chromium через -офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу, +OpenClaw також може підключатися до запущеного профілю браузера на базі Chromium через +офіційний сервер Chrome DevTools MCP. Це дає змогу повторно використовувати вкладки та стан входу, які вже відкриті в цьому профілі браузера. -Офіційні матеріали та посилання з налаштування: +Офіційні довідкові матеріали та посилання на налаштування: -- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers: Використання Chrome DevTools MCP із сесією вашого браузера](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [README Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) Вбудований профіль: - `user` -Необов’язково: створіть власний профіль existing-session, якщо хочете +Необов’язково: створіть власний кастомний профіль existing-session, якщо хочете іншу назву, колір або каталог даних браузера. Типова поведінка: -- Вбудований профіль `user` використовує автоматичне підключення Chrome MCP, яке націлюється на +- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на типовий локальний профіль Google Chrome. Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome. @@ -558,7 +556,7 @@ OpenClaw також може під’єднатися до запущеного 1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження. 2. Увімкніть віддалене налагодження. -3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw приєднається. +3. Не закривайте браузер і підтвердьте запит на підключення, коли OpenClaw під’єднається. Поширені сторінки inspect: @@ -566,7 +564,7 @@ OpenClaw також може під’єднатися до запущеного - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -Живий smoke-тест під’єднання: +Живий smoke-тест підключення: ```bash openclaw browser --browser-profile user start @@ -575,86 +573,88 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Ознаки успішної роботи: +Ознаки успішного підключення: - `status` показує `driver: existing-session` - `status` показує `transport: chrome-mcp` - `status` показує `running: true` -- `tabs` показує список уже відкритих вкладок вашого браузера +- `tabs` перелічує вже відкриті вкладки вашого браузера - `snapshot` повертає refs із вибраної живої вкладки -Що перевірити, якщо під’єднання не працює: +Що перевірити, якщо підключення не працює: - цільовий браузер на базі Chromium має версію `144+` -- у сторінці inspect цього браузера увімкнено remote debugging -- браузер показав запит на згоду на під’єднання, і ви його підтвердили -- `openclaw doctor` мігрує стару конфігурацію браузера на базі розширення та перевіряє, - що Chrome локально встановлено для типових профілів auto-connect, але він не може - увімкнути remote debugging у самому браузері за вас +- у сторінці inspect цього браузера увімкнено віддалене налагодження +- браузер показав запит на підключення, і ви його підтвердили +- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення та перевіряє, + що Chrome встановлено локально для типових профілів автопідключення, але він не може + увімкнути віддалене налагодження на боці браузера за вас Використання агентом: -- Використовуйте `profile="user"`, коли потрібен авторизований стан браузера користувача. +- Використовуйте `profile="user"`, коли вам потрібен стан авторизованого браузера користувача. - Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю. -- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити - запит на під’єднання. -- Gateway або хост node може запускати `npx chrome-devtools-mcp@latest --autoConnect` +- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером і може підтвердити + запит на підключення. +- Gateway або хост Node може запускати `npx chrome-devtools-mcp@latest --autoConnect` Примітки: -- Цей шлях є ризикованішим, ніж ізольований профіль `openclaw`, оскільки він може +- Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може виконувати дії у вашій авторизованій сесії браузера. -- OpenClaw не запускає браузер для цього драйвера; він лише під’єднується. +- OpenClaw не запускає браузер для цього драйвера; він лише підключається. - Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо - задано `userDataDir`, його буде передано далі для націлювання на цей каталог даних користувача. -- Existing-session може під’єднуватися на вибраному хості або через підключений - браузерний node. Якщо Chrome працює деінде і жоден browser node не підключено, використовуйте - віддалений CDP або хост node. + встановлено `userDataDir`, його буде передано далі для націлювання на цей каталог + користувацьких даних. +- Existing-session може підключатися на вибраному хості або через підключений + браузерний вузол. Якщо Chrome розміщено деінде і жоден браузерний вузол не підключено, використовуйте + віддалений CDP або хост Node. -### Власний запуск Chrome MCP +### Користувацький запуск Chrome MCP -Перевизначте сервер Chrome DevTools MCP, який запускається для кожного профілю, коли типовий +Перевизначте запущений сервер Chrome DevTools MCP для кожного профілю, якщо типовий потік `npx chrome-devtools-mcp@latest` вам не підходить (офлайн-хости, -зафіксовані версії, вендорні бінарні файли): +закріплені версії, вендорні бінарні файли): -| Поле | Що воно робить | -| ----------- | --------------------------------------------------------------------------------------------------------------------------- | -| `mcpCommand` | Виконуваний файл, який запускається замість `npx`. Розв’язується як є; абсолютні шляхи підтримуються. | -| `mcpArgs` | Масив аргументів, який без змін передається до `mcpCommand`. Замінює типові аргументи `chrome-devtools-mcp@latest --autoConnect`. | +| Поле | Що воно робить | +| ------------ | -------------------------------------------------------------------------------------------------------------------------- | +| `mcpCommand` | Виконуваний файл, який потрібно запустити замість `npx`. Визначається як є; абсолютні шляхи підтримуються. | +| `mcpArgs` | Масив аргументів, який безпосередньо передається до `mcpCommand`. Замінює типові аргументи `chrome-devtools-mcp@latest --autoConnect`. | -Коли для профілю existing-session задано `cdpUrl`, OpenClaw пропускає +Коли для профілю existing-session встановлено `cdpUrl`, OpenClaw пропускає `--autoConnect` і автоматично передає endpoint до Chrome MCP: -- `http(s)://...` → `--browserUrl ` (endpoint HTTP-виявлення DevTools). -- `ws(s)://...` → `--wsEndpoint ` (прямий CDP WebSocket). +- `http(s)://...` → `--browserUrl ` (HTTP endpoint виявлення DevTools). +- `ws(s)://...` → `--wsEndpoint ` (прямий WebSocket CDP). -Прапорці endpoint-ів і `userDataDir` не можна поєднувати: коли задано `cdpUrl`, -`userDataDir` ігнорується під час запуску Chrome MCP, оскільки Chrome MCP під’єднується до -запущеного браузера за цим endpoint-ом, а не відкриває каталог профілю. +Прапорці endpoint-ів і `userDataDir` не можна поєднувати: коли встановлено `cdpUrl`, +`userDataDir` ігнорується під час запуску Chrome MCP, оскільки Chrome MCP підключається до +вже запущеного браузера за endpoint-ом, а не відкриває каталог +профілю. Порівняно з керованим профілем `openclaw`, драйвери existing-session мають більше обмежень: -- **Знімки екрана** — працюють захоплення сторінки та захоплення елементів через `--ref`; CSS-селектори `--element` не підтримуються. `--full-page` не можна поєднувати з `--ref` або `--element`. Playwright не потрібен для знімків екрана сторінки або елементів на основі ref. -- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` вимагають snapshot refs (без CSS-селекторів). `click-coords` натискає по видимих координатах viewport і не вимагає snapshot ref. `click` підтримує лише ліву кнопку миші. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують таймаути для окремих викликів. `select` приймає одне значення. -- **Очікування / вивантаження / діалоги** — `wait --url` підтримує точні, підрядкові та glob-шаблони; `wait --load networkidle` не підтримується. Хуки вивантаження вимагають `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки діалогів не підтримують перевизначення таймаутів. -- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще вимагають шляху керованого браузера. +- **Скриншоти** — працюють захоплення сторінки та захоплення елементів через `--ref`; CSS-селектори `--element` не підтримуються. `--full-page` не можна поєднувати з `--ref` або `--element`. Для скриншотів сторінки або елементів на основі ref Playwright не потрібен. +- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують snapshot refs (без CSS-селекторів). `click-coords` натискає у видимих координатах viewport і не потребує snapshot ref. `click` підтримує лише ліву кнопку миші. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують таймаути для окремих викликів. `select` приймає одне значення. +- **Очікування / завантаження файлів / діалоги** — `wait --url` підтримує точні, підрядкові та glob-шаблони; `wait --load networkidle` не підтримується. Хуки завантаження файлів вимагають `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки діалогів не підтримують перевизначення таймаутів. +- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще потребують шляху керованого браузера. ## Гарантії ізоляції -- **Окремий user data dir**: ніколи не торкається вашого особистого профілю браузера. -- **Окремі порти**: уникає `9222`, щоб не було конфліктів із dev-робочими процесами. -- **Детерміноване керування вкладками**: `tabs` спочатку повертає `suggestedTargetId`, а потім - стабільні обробники `tabId`, як-от `t1`, необов’язкові мітки та сирий `targetId`. - Агенти мають повторно використовувати `suggestedTargetId`; сирі id залишаються доступними для +- **Окремий каталог користувацьких даних**: ніколи не торкається профілю вашого особистого браузера. +- **Окремі порти**: уникає `9222`, щоб не конфліктувати з робочими процесами розробки. +- **Детерміноване керування вкладками**: `tabs` спочатку повертає `suggestedTargetId`, потім + стабільні дескриптори `tabId`, такі як `t1`, необов’язкові мітки та сирий `targetId`. + Агенти мають повторно використовувати `suggestedTargetId`; сирі ідентифікатори залишаються доступними для налагодження та сумісності. ## Вибір браузера -Під час локального запуску OpenClaw вибирає перший доступний варіант: +Під час локального запуску OpenClaw вибирає перший доступний: 1. Chrome 2. Brave @@ -666,17 +666,17 @@ openclaw browser --browser-profile user snapshot --format ai Платформи: -- macOS: перевіряє `/Applications` і `~/Applications`. -- Linux: перевіряє поширені розташування Chrome/Brave/Edge/Chromium у `/usr/bin`, +- macOS: перевіряються `/Applications` і `~/Applications`. +- Linux: перевіряються поширені розташування Chrome/Brave/Edge/Chromium у `/usr/bin`, `/snap/bin`, `/opt/google`, `/opt/brave.com`, `/usr/lib/chromium` і `/usr/lib/chromium-browser`. -- Windows: перевіряє поширені місця встановлення. +- Windows: перевіряються типові місця встановлення. ## API керування (необов’язково) -Для скриптів і налагодження Gateway надає невеликий **HTTP API керування -лише для loopback** плюс відповідний CLI `openclaw browser` (snapshots, refs, wait -power-ups, вивід JSON, робочі процеси налагодження). Повний довідник дивіться в +Для сценаріїв автоматизації та налагодження Gateway надає невеликий **HTTP API керування лише через loopback** +разом із відповідним CLI `openclaw browser` (snapshots, refs, розширення wait, +вивід JSON, робочі процеси налагодження). Повний довідник дивіться в [API керування браузером](/uk/tools/browser-control). ## Усунення несправностей @@ -684,15 +684,15 @@ power-ups, вивід JSON, робочі процеси налагодження Для проблем, специфічних для Linux (особливо snap Chromium), дивіться [Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting). -Для конфігурацій WSL2 Gateway + Windows Chrome на розділених хостах дивіться -[Усунення несправностей WSL2 + Windows + віддалений Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting). +Для конфігурацій із розділеними хостами WSL2 Gateway + Windows Chrome дивіться +[Усунення несправностей WSL2 + Windows + віддаленого Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting). ### Помилка запуску CDP проти блокування SSRF під час навігації Це різні класи помилок, і вони вказують на різні шляхи в коді. -- **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити, що площина керування браузером працює справно. -- **Блокування SSRF під час навігації** означає, що площина керування браузером працює справно, але ціль переходу сторінки відхилено політикою. +- **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити, що площина керування браузером справна. +- **Блокування SSRF під час навігації** означає, що площина керування браузером справна, але ціль переходу на сторінку відхиляється політикою. Поширені приклади: @@ -702,9 +702,9 @@ power-ups, вивід JSON, робочі процеси налагодження - `Port is in use for profile "" but not by openclaw`, коли зовнішній сервіс CDP на loopback налаштовано без `attachOnly: true` - Блокування SSRF під час навігації: - - потоки `open`, `navigate`, snapshot або відкриття вкладок завершуються з помилкою політики браузера/мережі, тоді як `start` і `tabs` усе ще працюють + - потоки `open`, `navigate`, snapshot або відкриття вкладок завершуються помилкою політики браузера/мережі, тоді як `start` і `tabs` усе ще працюють -Використайте цю мінімальну послідовність, щоб розрізнити ці два випадки: +Використайте цю мінімальну послідовність, щоб відрізнити одне від іншого: ```bash openclaw browser --browser-profile openclaw start @@ -714,22 +714,22 @@ openclaw browser --browser-profile openclaw open https://example.com Як читати результати: -- Якщо `start` завершується з `not reachable after start`, спочатку усувайте проблеми готовності CDP. +- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте проблему готовності CDP. - Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему досяжності CDP, а не проблему навігації сторінкою. -- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершуються помилкою, площина керування браузером працює, а проблема в політиці навігації або в цільовій сторінці. -- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером працює справно. +- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером працює, а проблема полягає в політиці навігації або цільовій сторінці. +- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером справний. Важливі деталі поведінки: - Конфігурація браузера типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`. -- Для локального керованого профілю `openclaw` на loopback перевірки справності CDP навмисно пропускають перевірку досяжності SSRF браузера для власної локальної площини керування OpenClaw. -- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що подальша ціль `open` або `navigate` дозволена. +- Для локального керованого профілю `openclaw` на loopback перевірки справності CDP навмисно пропускають застосування політики досяжності SSRF браузера для власної локальної площини керування OpenClaw. +- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що пізніша ціль `open` або `navigate` дозволена. -Вказівки з безпеки: +Рекомендації з безпеки: - **Не** послаблюйте політику SSRF браузера типово. -- Надавайте перевагу вузьким виняткам для хостів, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі. -- Використовуйте `dangerouslyAllowPrivateNetwork: true` лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібен і перевірений. +- Віддавайте перевагу вузьким виняткам для хостів, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі. +- Використовуйте `dangerouslyAllowPrivateNetwork: true` лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібен і пройшов перевірку. ## Інструменти агента + як працює керування @@ -737,23 +737,23 @@ openclaw browser --browser-profile openclaw open https://example.com - `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act -Як це зіставляється: +Як це відображається: - `browser snapshot` повертає стабільне дерево UI (AI або ARIA). -- `browser act` використовує `ref` ID із snapshot для натискання/введення/перетягування/вибору. -- `browser screenshot` захоплює пікселі (усю сторінку, елемент або позначені refs). -- `browser doctor` перевіряє готовність Gateway, Plugin, профілю, браузера та вкладки. +- `browser act` використовує ідентифікатори `ref` зі snapshot для click/type/drag/select. +- `browser screenshot` захоплює пікселі (повна сторінка, елемент або позначені refs). +- `browser doctor` перевіряє готовність Gateway, Plugin, профілю, браузера та вкладок. - `browser` приймає: - - `profile` для вибору іменованого профілю браузера (openclaw, chrome або віддалений CDP). - - `target` (`sandbox` | `host` | `node`) для вибору, де розташований браузер. - - У сесіях із sandbox `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`. - - Якщо `target` не задано: сесії в sandbox типово використовують `sandbox`, а сесії без sandbox — `host`. - - Якщо підключено node з підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви не зафіксуєте `target="host"` або `target="node"`. + - `profile`, щоб вибрати іменований профіль браузера (openclaw, chrome або віддалений CDP). + - `target` (`sandbox` | `host` | `node`), щоб вибрати, де розташований браузер. + - У sandboxed-сесіях `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`. + - Якщо `target` не вказано: sandboxed-сесії типово використовують `sandbox`, несandboxed-сесії — `host`. + - Якщо підключено вузол із підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви не зафіксуєте `target="host"` або `target="node"`. -Це зберігає детермінованість агента й допомагає уникати крихких селекторів. +Це робить поведінку агента детермінованою та дає змогу уникати крихких селекторів. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента -- [Ізоляція sandbox](/uk/gateway/sandboxing) — керування браузером у sandbox-середовищах +- [Ізоляція sandbox](/uk/gateway/sandboxing) — керування браузером у sandboxed-середовищах - [Безпека](/uk/gateway/security) — ризики керування браузером і посилення захисту