diff --git a/docs/uk/ci.md b/docs/uk/ci.md index ce2391475..e997501d3 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,45 +1,87 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI було або не було запущено + - Потрібно зрозуміти, чому завдання CI запустилося або не запустилося - Ви налагоджуєте збої в перевірках GitHub Actions -summary: Граф завдань CI, шлюзи областей дії та локальні еквіваленти команд -title: Конвеєр CI +summary: Граф завдань CI, шлюзи області дії та локальні еквіваленти команд +title: конвеєр CI x-i18n: - generated_at: "2026-04-27T07:07:47Z" + generated_at: "2026-04-27T08:07:51Z" model: gpt-5.4 provider: openai - source_hash: 197ca6bd69f47fc26f8bee3f10c90fab75536cc46c0ca2350a02342d7a3a030c + source_hash: 997474e178b4a9195e4a421c81bbeb0f625ded48f015bc87c4406ddb28aec912 source_path: ci.md workflow: 15 --- -CI запускається для кожного push до `main` і для кожного pull request. Він використовує розумне визначення області дії, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне визначення області дії та розгортають повний звичайний граф CI для кандидатів на реліз або широкої валідації. +Конвеєр CI запускається при кожному push до `main` і для кожного pull request. Він використовує розумне визначення області дії, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне визначення області дії та розгортають увесь звичайний граф CI для кандидатів на реліз або широкої валідації. -`Full Release Validation` — це ручний узагальнювальний workflow для сценарію «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` з цією ціллю та запускає `OpenClaw Release Checks` для перевірки встановлення, приймання пакетів, наборів Docker release-path, live/E2E, OpenWebUI, паритету QA Lab, Matrix і Telegram. Він також може запускати post-publish workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета. +`Full Release Validation` — це ручний umbrella workflow для сценарію «запустити все +перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний +workflow `CI` з цією ціллю та запускає `OpenClaw Release Checks` +для smoke-перевірки встановлення, приймання пакета, наборів Docker release-path, live/E2E, +OpenWebUI, паритету QA Lab, а також доріжок Matrix і Telegram. Він також може запускати +post-publish workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета. -`Package Acceptance` — це побічний workflow для валідації артефакту пакета без блокування workflow релізу. Він визначає один кандидат із опублікованої npm-специфікації, довіреного `package_ref`, зібраного за допомогою вибраного каркаса `workflow_ref`, HTTPS URL tarball-архіву із SHA-256 або tarball-артефакту з іншого запуску GitHub Actions, завантажує його як артефакт `package-under-test`, а потім повторно використовує планувальник Docker release/E2E з цим tarball замість повторного пакування checkout workflow. Профілі охоплюють вибірки Docker lane: smoke, package, product, full і custom. Профіль `package` використовує офлайн-покриття plugin, тому валідація опублікованого пакета не залежить від доступності live ClawHub. Необов’язкова lane Telegram повторно використовує артефакт `package-under-test` у workflow `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації зберігається для окремих запусків. +`Package Acceptance` — це побічний workflow для валідації артефакту пакета +без блокування workflow релізу. Він визначає один кандидат із +опублікованої npm-специфікації, довіреного `package_ref`, зібраного за допомогою +вибраного harness `workflow_ref`, HTTPS URL tarball із SHA-256 або артефакту tarball +з іншого запуску GitHub Actions, завантажує його як артефакт `package-under-test`, а потім повторно +використовує планувальник Docker release/E2E з цим tarball замість перепакування +checkout workflow. Профілі охоплюють вибір доріжок Docker для smoke, package, product, full і custom. +Профіль `package` використовує офлайн-покриття plugin, тому валідація опублікованого пакета +не залежить від доступності live ClawHub. Необов’язкова доріжка Telegram повторно використовує +артефакт `package-under-test` у workflow `NPM Telegram Beta E2E`, при цьому шлях +опублікованої npm-специфікації зберігається для окремих запусків. ## Приймання пакета -Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей встановлюваний пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як приймання пакета перевіряє один tarball через той самий каркас Docker E2E, який користувачі проходять після встановлення або оновлення. +Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей +пакет OpenClaw, придатний до встановлення, як продукт?» Це відрізняється від звичайного CI: +звичайний CI перевіряє дерево вихідного коду, тоді як package acceptance перевіряє +один tarball через той самий harness Docker E2E, який користувачі проходять після +встановлення або оновлення. Workflow має чотири завдання: -1. `resolve_package` виконує checkout `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і виводить у підсумку кроку GitHub джерело, workflow ref, package ref, версію, SHA-256 і профіль. -2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує цей артефакт, перевіряє вміст tarball, за потреби готує Docker-образи з digest пакета та запускає вибрані Docker lane для цього пакета замість пакування checkout workflow. -3. `package_telegram` за потреби викликає `NPM Telegram Beta E2E`. Воно запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance його визначив; окремий запуск Telegram і далі може встановлювати опубліковану npm-специфікацію. -4. `summary` завершує workflow помилкою, якщо не вдалося визначити пакет, не пройшла Docker acceptance або необов’язкова lane Telegram. +1. `resolve_package` виконує checkout `workflow_ref`, визначає одного кандидата пакета, + записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує + `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як + артефакт `package-under-test` і виводить джерело, workflow ref, package + ref, версію, SHA-256 і профіль у зведенні кроку GitHub. +2. `docker_acceptance` викликає + `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і + `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує + цей артефакт, перевіряє вміст tarball, за потреби готує + Docker-образи package-digest і запускає вибрані доріжки Docker для цього + пакета замість пакування checkout workflow. +3. `package_telegram` за потреби викликає `NPM Telegram Beta E2E`. Воно запускається, коли + `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, + якщо Package Acceptance визначив його; окремий запуск Telegram + усе ще може встановити опубліковану npm-специфікацію. +4. `summary` завершує workflow з помилкою, якщо визначення пакета, Docker acceptance або + необов’язкова доріжка Telegram завершилися з помилкою. -Джерела кандидатів: +Джерела кандидата: -- `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для приймання опублікованих beta/stable. -- `source=ref`: пакує довірену гілку, тег або повний SHA коміту `package_ref`. Визначувач отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілок репозиторію або з тега релізу, встановлює залежності у відокремленому worktree та пакує їх за допомогою `scripts/package-openclaw-for-docker.mjs`. +- `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну + версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для + приймання опублікованих beta/stable. +- `source=ref`: пакує довірену гілку, тег або повний SHA коміту `package_ref`. + Модуль визначення кандидата отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт + досяжний з історії гілок репозиторію або тега релізу, встановлює залежності в + detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. - `source=url`: завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим. -- `source=artifact`: завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його слід надавати для артефактів, поширених зовні. +- `source=artifact`: завантажує один `.tgz` з `artifact_run_id` і + `artifact_name`; `package_sha256` необов’язковий, але його слід надавати для + артефактів, якими діляться зовнішнім чином. -Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/каркаса, який запускає тест. `package_ref` — це коміт джерела, який пакується, коли `source=ref`. Це дозволяє поточному тестовому каркасу перевіряти старіші довірені коміти джерела без запуску старої логіки workflow. +Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений +код workflow/harness, який запускає тест. `package_ref` — це вихідний коміт, +який пакується, коли `source=ref`. Це дає змогу поточному harness тестування +перевіряти старіші довірені вихідні коміти без запуску старої логіки workflow. -Профілі відповідають Docker-покриттю: +Профілі відповідають покриттю Docker: - `smoke`: `npm-onboard-channel-agent`, `gateway-network`, `config-reload` - `package`: `npm-onboard-channel-agent`, `doctor-switch`, @@ -47,38 +89,38 @@ Workflow має чотири завдання: `plugin-update` - `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full`: повні Docker-chunk release-path з OpenWebUI +- `full`: повні Docker-чанки release-path з OpenWebUI - `custom`: точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Перевірки релізу викликають Package Acceptance з `source=ref`, +Release checks викликає Package Acceptance з `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=package` і `telegram_mode=mock-openai`. Цей профіль є -GitHub-native заміною для більшості перевірок пакета/оновлення в Parallels, а -Telegram підтверджує той самий артефакт пакета через QA live transport. -Cross-OS перевірки релізу й надалі охоплюють специфічні для ОС сценарії -онбордингу, інсталятора та платформеної поведінки; валідацію продукту для -пакета/оновлення слід починати з Package Acceptance. +GitHub-native заміною для більшості перевірок пакета/оновлення в Parallels, +а Telegram підтверджує той самий артефакт пакета через QA live transport. +Cross-OS release checks усе ще покривають специфічні для ОС onboarding, installer і +поведінку платформи; валідацію пакета/оновлення продукту слід починати з Package +Acceptance. Доріжки Windows packaged та installer fresh також перевіряють, що +встановлений пакет може імпортувати browser-control override із сирого абсолютного +шляху Windows. -Package Acceptance має обмежене вікно legacy-сумісності для вже +Package Acceptance має обмежене вікно сумісності зі старими версіями для вже опублікованих пакетів до `2026.4.25` включно, зокрема `2026.4.25-beta.*`. Ці -послаблення задокументовані тут, щоб вони не перетворилися на постійні -мовчазні пропуски: відомі приватні записи QA в `dist/postinstall-inventory.json` -можуть спричиняти попередження, якщо tarball не містив цих файлів; -`doctor-switch` може пропускати підвипадок збереження `gateway install --wrapper`, -коли пакет не надає цей прапорець; `update-channel-switch` може обрізати -відсутні `pnpm.patchedDependencies` із фальшивої git-фикстури, похідної від tarball, -і може журналювати відсутній збережений `update.channel`; plugin smoke-тести можуть -читати legacy-розташування записів встановлення або приймати відсутність -збереження запису встановлення marketplace; а `plugin-update` може дозволяти -міграцію метаданих конфігурації, водночас і далі вимагаючи, щоб запис -встановлення та поведінка без перевстановлення лишалися незмінними. Пакети після -`2026.4.25` мають відповідати сучасним контрактам; ті самі умови завершуються -помилкою замість попередження або пропуску. +послаблення задокументовано тут, щоб вони не перетворилися на постійні мовчазні пропуски: +відомі приватні записи QA у `dist/postinstall-inventory.json` можуть видавати +попередження, якщо tarball пропустив ці файли; `doctor-switch` може пропускати +підвипадок збереження `gateway install --wrapper`, якщо пакет не надає +цей прапорець; `update-channel-switch` може відкидати відсутні `pnpm.patchedDependencies` +із підробленого git fixture, похідного від tarball, і може журналювати відсутній +збережений `update.channel`; smoke-перевірки plugin можуть читати застарілі розташування +записів встановлення або приймати відсутність збереження запису встановлення marketplace; а +`plugin-update` може дозволяти міграцію метаданих конфігурації, водночас усе ще вимагаючи, +щоб запис встановлення та поведінка без перевстановлення залишалися незмінними. Пакети після `2026.4.25` +мають відповідати сучасним контрактам; ті самі умови завершуються помилкою, а не попередженням чи пропуском. Приклади: ```bash -# Перевірити поточний beta-пакет із product-рівнем покриття. +# Перевірити поточний beta-пакет із покриттям рівня product. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -87,7 +129,7 @@ gh workflow run package-acceptance.yml \ -f suite_profile=product \ -f telegram_mode=mock-openai -# Запакувати та перевірити гілку релізу поточним каркасом. +# Запакувати та перевірити гілку релізу з поточним harness. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -96,7 +138,7 @@ gh workflow run package-acceptance.yml \ -f suite_profile=package \ -f telegram_mode=mock-openai -# Перевірити URL tarball. SHA-256 є обов’язковим для source=url. +# Перевірити URL tarball. Для source=url SHA-256 є обов’язковим. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -116,59 +158,55 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску package acceptance починайте з підсумку -`resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім -перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: -`.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали lane, часові -показники фаз і команди повторного запуску. Надавайте перевагу повторному запуску -профілю пакета, що завершився помилкою, або точних Docker lane замість повторного -запуску повної валідації релізу. +Під час налагодження невдалого запуску package acceptance починайте зі зведення +`resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте +дочірній запуск `docker_acceptance` і його артефакти Docker: +`.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали доріжок, +тривалість фаз і команди повторного запуску. Надавайте перевагу повторному запуску +невдалого профілю пакета або точних доріжок Docker, а не повторному запуску повної валідації релізу. -QA Lab має окремі lane CI поза основним workflow з розумним визначенням області дії. Workflow -`Parity gate` запускається для відповідних змін у PR і при ручному запуску; він -збирає приватне середовище виконання QA і порівнює пакети agentic mock GPT-5.5 та Opus 4.6. -Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і при ручному -запуску; він розгортає mock parity gate, live lane Matrix і live lane Telegram та Discord +QA Lab має окремі доріжки CI поза основним workflow із розумним визначенням області дії. Workflow +`Parity gate` запускається для відповідних змін у PR і при ручному запуску; воно +збирає приватне середовище виконання QA та порівнює agentic packs mock GPT-5.5 і Opus 4.6. +Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і при ручному запуску; +воно розгортає mock parity gate, live-доріжку Matrix і live-доріжки Telegram та Discord як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують оренди Convex. Matrix -використовує `--profile fast --fail-fast` для запланованих запусків і перевірок релізу, тоді як -типове значення CLI та ручний параметр workflow лишаються `all`; ручний запуск з +використовує `--profile fast --fail-fast` для планових і релізних шлюзів, тоді як +типовим значенням CLI і ручного входу workflow залишається `all`; ручний запуск `matrix_profile=all` завжди розбиває повне покриття Matrix на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також -запускає критичні для релізу lane QA Lab перед затвердженням релізу. +запускає критичні для релізу доріжки QA Lab перед затвердженням релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для -очищення дублікатів після злиття. Типово він працює в режимі dry-run і закриває лише -явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що -злитий PR справді об’єднано і що кожен дублікат має або спільну згадану issue, -або перекривні змінені hunks. +Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідників для +очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває +лише явно перелічені PR, коли `apply=true`. Перед зміною стану GitHub +він перевіряє, що злитий PR справді об’єднано і що кожен дублікат має або спільне пов’язане issue, +або перетин змінених hunks. -Workflow `Docs Agent` — це event-driven lane обслуговування Codex для підтримки -наявної документації у відповідності до нещодавно злитих змін. Воно не має окремого -розкладу: його може запустити успішний неботовий запуск push CI на `main`, а -ручний запуск може запускати його безпосередньо. Виклики через workflow-run -пропускаються, коли `main` уже пішов далі або коли інший неперепущений запуск -Docs Agent був створений за останню годину. Коли воно запускається, воно -переглядає діапазон комітів від SHA джерела попереднього неперепущеного запуску -Docs Agent до поточного `main`, тож один щогодинний запуск може охопити всі зміни в -main, накопичені від останнього проходу документації. +Workflow `Docs Agent` — це event-driven lane технічного обслуговування Codex для +підтримання наявної документації у відповідності до нещодавно об’єднаних змін. Воно не має +чистого розкладу: його може запустити успішний небoтовий push-запуск CI на `main`, +а ручний запуск може запускати його безпосередньо. Виклики через workflow-run пропускаються, +коли `main` уже просунувся далі або коли інший непропущений запуск Docs Agent було створено +протягом останньої години. Під час запуску воно переглядає діапазон комітів від +попереднього вихідного SHA останнього непропущеного Docs Agent до поточного `main`, +тому один щогодинний запуск може охопити всі зміни в main, накопичені з часу +останнього проходу документації. -Workflow `Test Performance Agent` — це event-driven lane обслуговування Codex -для повільних тестів. Воно не має окремого розкладу: його може запустити -успішний неботовий запуск push CI на `main`, але воно пропускається, якщо інший -виклик через workflow-run уже виконувався або виконується тієї ж UTC-доби. -Ручний запуск обходить це денне обмеження активності. Lane будує звіт про -продуктивність Vitest для повного набору тестів, згрупований за категоріями, -дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі -збереженням покриття замість широких рефакторингів, потім повторно запускає -звіт для повного набору та відхиляє зміни, що зменшують базову кількість тестів, -які проходять. Якщо в базовому стані є тести, що падають, Codex може виправити -лише очевидні збої, і після агента повторний звіт для повного набору має пройти -перед будь-яким комітом. Коли `main` просувається до того, як bot push буде -застосовано, lane перебазовує перевірений патч, повторно запускає `pnpm check:changed` -і повторює спробу push; конфліктні застарілі патчі пропускаються. Воно -використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму -безпечну позицію без `sudo`, що й агент документації. +Workflow `Test Performance Agent` — це event-driven lane технічного обслуговування Codex +для повільних тестів. Воно не має чистого розкладу: його може запустити успішний +неботовий push-запуск CI на `main`, але воно пропускається, якщо інший виклик через workflow-run +уже виконався або виконується того ж дня UTC. Ручний запуск обходить цей денний +шлюз активності. Доріжка будує повний згрупований звіт про продуктивність Vitest, +дозволяє Codex вносити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість +широких рефакторингів, потім повторно запускає повний звіт і відхиляє зміни, що +зменшують базову кількість тестів, які проходять. Якщо в базовому стані є тести, що падають, +Codex може виправляти лише очевидні збої, а повний звіт після агента має пройти, +перш ніж щось буде закомічено. Коли `main` просувається вперед до того, як bot push буде застосовано, +доріжка перебазовує перевірений patch, повторно запускає `pnpm check:changed` і повторює push; +конфліктні застарілі patch пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб action Codex +міг зберігати ту саму безпечну позицію drop-sudo, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -179,31 +217,38 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| --------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Визначає зміни лише в документації, змінені області дії, змінені extensions і будує маніфест CI | Завжди для non-draft push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей за npm advisory | Завжди для non-draft push і PR | -| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для non-draft push і PR | -| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-ланки коректності, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шардовані тести bundled-plugin для всього набору extension | Зміни, релевантні для Node | -| `checks-node-core-test` | Шардовані core Node тести, без channel, bundled, contract та extension lanes | Зміни, релевантні для Node | -| `check` | Шардований еквівалент основного локального шлюзу: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Шарди architecture, boundary, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI та smoke-тест пам’яті під час запуску | Зміни, релевантні для Node | -| `checks` | Перевіряльник built-artifact тестів channel | Зміни, релевантні для Node | -| `checks-node-compat-node22` | Ланка сумісності Node 22 для збірки та smoke | Ручний запуск CI для релізів | -| `check-docs` | Форматування документації, lint і перевірки битих посилань | Документацію змінено | -| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Специфічні для Windows тестові ланки | Зміни, релевантні для Windows | -| `macos-node` | Ланка тестів TypeScript на macOS із використанням спільних built artifacts | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit-тести для обох flavor плюс одна debug APK-збірка | Зміни, релевантні для Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний CI на main або ручний запуск | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | +| `preflight` | Визначає зміни лише в документації, змінені області дії, змінені extensions і формує маніфест CI | Завжди для нечернеткових push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для нечернеткових push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisories npm | Завжди для нечернеткових push і PR | +| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для нечернеткових push і PR | +| `build-artifacts` | Збирає `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані артефакти для downstream | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі доріжки коректності Linux, такі як перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шардовані тести bundled-plugin для всього набору extension | Зміни, релевантні для Node | +| `checks-node-core-test` | Шардовані тести core Node, без урахування доріжок channel, bundled, contract і extension | Зміни, релевантні для Node | +| `check` | Шардований еквівалент основного локального шлюзу: production types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Шарди для перевірок архітектури, меж, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести зібраного CLI та smoke-перевірка стартової пам’яті | Зміни, релевантні для Node | +| `checks` | Засіб перевірки для тестів каналів на зібраних артефактах | Зміни, релевантні для Node | +| `checks-node-compat-node22` | Доріжка сумісності Node 22 для збірки та smoke | Ручний запуск CI для релізів | +| `check-docs` | Форматування документації, lint і перевірки битих посилань | Документацію змінено | +| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | +| `checks-windows` | Доріжки тестів, специфічні для Windows | Зміни, релевантні для Windows | +| `macos-node` | Доріжка тестів TypeScript на macOS з використанням спільних зібраних артефактів | Зміни, релевантні для macOS | +| `macos-swift` | Lint, збірка і тести Swift для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Модульні тести Android для обох варіантів плюс одна debug-збірка APK | Зміни, релевантні для Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний main CI або ручний запуск | -Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але примусово вмикають кожну scoped-ланку: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python Skills, Windows, macOS, Android і i18n для Control UI. Ручні запуски використовують унікальну групу конкурентності, щоб повний набір для кандидата на реліз не був скасований іншим push або PR-запуском для того самого ref. Необов’язковий параметр `target_ref` дозволяє довіреному виклику запускати цей граф для гілки, тега або повного SHA коміту, використовуючи файл workflow із вибраного dispatch ref. +Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але +примусово вмикають кожну доріжку з визначенням області дії: шарди Linux Node, шарди bundled-plugin, контракти каналів, +сумісність Node 22, `check`, `check-additional`, build smoke, перевірки документації, +Python Skills, Windows, macOS, Android і i18n для Control UI. Ручні запуски використовують +унікальну групу concurrency, щоб повний набір перевірок для кандидата на реліз не був скасований +іншим push або PR-запуском на тому самому ref. Необов’язковий вхід `target_ref` дає змогу +довіреному виклику запускати цей граф для гілки, тегу або повного SHA коміту, +використовуючи файл workflow з вибраного ref запуску. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -213,66 +258,65 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Порядок fail-fast -Завдання впорядковані так, щоб дешеві перевірки завершувалися помилкою раніше, ніж запускатимуться дорогі: +Завдання впорядковано так, щоб дешеві перевірки завершувалися помилкою раніше, ніж запускаються дорогі: -1. `preflight` вирішує, які ланки взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються помилкою без очікування важчих матричних завдань для артефактів і платформ. -3. `build-artifacts` виконується паралельно зі швидкими Linux-ланками, щоб downstream-споживачі могли стартувати, щойно спільна збірка буде готова. -4. Після цього розгортаються важчі платформені й runtime-ланки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які доріжки взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються помилкою, не чекаючи важчих завдань матриці артефактів і платформ. +3. `build-artifacts` виконується паралельно зі швидкими доріжками Linux, щоб downstream-споживачі могли почати роботу, щойно спільна збірка буде готова. +4. Після цього розгортаються важчі платформні та runtime-доріжки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка області дії живе в `scripts/ci-changed-scope.mjs` і покривається unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Логіка області дії розміщена в `scripts/ci-changed-scope.mjs` і покрита модульними тестами в `src/scripts/ci-changed-scope.test.ts`. Ручний запуск пропускає визначення changed-scope і змушує маніфест preflight -поводитися так, ніби змінилася кожна scoped-область. -Редагування workflow CI перевіряють граф Node CI плюс linting workflow, але самі по собі не примушують виконувати native-збірки для Windows, Android або macOS; ці платформені ланки й далі залишаються прив’язаними до змін у платформеному коді. -Редагування лише маршрутизації CI, окремі дешеві зміни fixture core-test і вузькі редагування helper/test-routing для plugin contract використовують швидкий шлях маніфесту лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях уникає build artifacts, сумісності Node 22, channel contracts, повних shard core, shard bundled-plugin і додаткових матриць guard, коли змінені файли обмежуються поверхнями маршрутизації або helper, які швидке завдання перевіряє безпосередньо. -Перевірки Windows Node прив’язані до специфічних для Windows обгорток process/path, helper для npm/pnpm/UI runner, конфігурації package manager і поверхонь workflow CI, які виконують цю ланку; непов’язані зміни вихідного коду, plugin, install-smoke і зміни лише тестів залишаються на Linux Node lanes, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже виконується звичайними test shards. -Окремий workflow `install-smoke` повторно використовує той самий скрипт області дії через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest bundled plugin і поверхонь core plugin/channel/gateway/Plugin SDK, які використовують Docker smoke jobs. Зміни лише вихідного коду bundled plugin, зміни лише тестів і зміни лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає smoke CLI для agents delete shared-workspace, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений профіль Docker для bundled-plugin із сумарним timeout команди 240 секунд, де `docker run` для кожного сценарію окремо також обмежений. Повний шлях зберігає покриття для встановлення QR package і installer Docker/update для нічних запланованих запусків, ручних запусків, release checks через workflow-call і pull request, які справді зачіпають поверхні installer/package/Docker. Push до `main`, включно з merge commits, не примушують повний шлях; коли логіка changed-scope запитує повне покриття для push, workflow зберігає швидкий Docker smoke, а повний install smoke лишає на нічний прогін або валідацію релізу. Повільний smoke для global install image-provider на Bun окремо керується через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні запуски `install-smoke` можуть його ввімкнути, але pull request і push до `main` його не запускають. QR і installer Docker тести зберігають власні install-орієнтовані Dockerfile. Локальний `test:docker:all` заздалегідь збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: базовий runner Node/Git для installer/update/plugin-dependency lanes і функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних lanes. Визначення Docker lanes живуть у `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожної lane через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте типову кількість слотів основного пулу 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів tail-пулу, чутливого до provider, також 10 — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Ліміти для важких lanes типово дорівнюють `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб lanes з npm install і кількома сервісами не перевантажували Docker, тоді як легші lanes все ще заповнюють доступні слоти. Одна lane, важча за ефективні ліміти, усе одно може стартувати з порожнього пулу, а потім працює сама, доки не звільнить ресурси. Запуски lanes типово розносяться на 2 секунди, щоб уникнути локальних storm під час create у Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегований запуск виконує preflight для Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних lanes, зберігає часові показники lanes для longest-first упорядкування і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перевірки планувальника. Типово він припиняє планувати нові pooled lanes після першої помилки, і кожна lane має резервний timeout 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lanes використовують жорсткіші ліміти для конкретної lane. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні lanes планувальника, включно з lane лише для релізу, як-от `install-e2e`, і розділеними lane оновлення bundled, як-от `bundled-channel-update-acpx`, водночас пропускаючи cleanup smoke, щоб agents могли відтворити одну невдалу lane. Повторно використовуваний workflow live/E2E запитує в `scripts/test-docker-all.mjs --plan-json`, які package, kind образу, live image, lane і покриття credentials потрібні, після чого `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує артефакт пакета поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє вміст tarball; збирає і публікує в GHCR bare/functional Docker E2E images, позначені digest пакета, через Docker layer cache Blacksmith, коли план потребує lanes з установленим пакетом; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні images package-digest замість повторної збірки. Workflow `Package Acceptance` — це високорівневий шлюз пакетів: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакту попереднього workflow, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна логіка acceptance могла перевіряти старіші довірені коміти без checkout старого коду workflow. Release checks запускають профіль acceptance `package` для цільового ref; цей профіль покриває контракти package/update/plugin і є типовою GitHub-native заміною для більшості покриття package/update у Parallels. Набір Docker release-path запускає максимум три chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому kind образу і виконував кілька lanes через той самий weighted scheduler (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update|plugins-integrations`). OpenWebUI включається до `plugins-integrations`, коли запитується повне покриття release-path, і зберігає окремий chunk `openwebui` лише для запусків, присвячених тільки OpenWebUI. Chunk `plugins-integrations` запускає розділені lanes `bundled-channel-*` і `bundled-channel-update-*` замість послідовної all-in-one lane `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` із журналами lanes, часовими показниками, `summary.json`, `failures.json`, часовими показниками фаз, JSON плану планувальника, таблицями повільних lanes і командами повторного запуску для кожної lane. Вхід `docker_lanes` workflow запускає вибрані lanes проти підготовлених образів замість chunk jobs, що обмежує налагодження невдалої lane одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана lane є live Docker lane, цільове завдання локально збирає live-test image для цього повторного запуску. Згенеровані для кожної lane GitHub-команди повторного запуску містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, тож невдала lane може повторно використати точний пакет і образи з невдалого запуску. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти із запуску GitHub і вивести об’єднані/поканальні цільові команди повторного запуску; використовуйте `pnpm test:docker:timings ` для підсумків повільних lanes і критичного шляху фаз. Запланований workflow live/E2E щодня запускає повний набір Docker release-path. Матриця bundled update розділена за ціллю оновлення, щоб повторювані проходи npm update і doctor repair могли шардитися разом з іншими bundled-перевірками. +працювати так, ніби кожну область дії було змінено. +Редагування workflow CI перевіряють граф Node CI разом із linting workflow, але самі по собі не примушують запускати нативні збірки для Windows, Android або macOS; ці платформні доріжки й надалі залежать від змін у вихідному коді відповідних платформ. +Редагування лише маршрутизації CI, вибрані дешеві редагування fixture для core-тестів і вузькі редагування helper/test-routing для контрактів plugin використовують швидкий шлях маніфесту лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях уникає build artifacts, сумісності Node 22, контрактів каналів, повних шардів core, шардів bundled-plugin і додаткових матриць guard, коли змінені файли обмежені поверхнями маршрутизації або helper, які швидке завдання перевіряє безпосередньо. +Перевірки Windows Node обмежені специфічними для Windows process/path wrappers, helper для npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які виконують цю доріжку; непов’язані зміни вихідного коду, plugin, install-smoke і лише тестів залишаються на Linux Node lanes, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже забезпечується звичайними test shards. +Окремий workflow `install-smoke` повторно використовує той самий сценарій визначення області дії через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest bundled plugin і поверхонь core plugin/channel/gateway/Plugin SDK, які використовують Docker smoke jobs. Зміни лише у вихідному коді bundled plugin, лише тестові редагування і зміни лише в документації не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke `agents delete shared-workspace`, запускає container gateway-network e2e, перевіряє build arg для bundled extension і запускає обмежений Docker-профіль bundled-plugin з сукупним тайм-аутом команди 240 секунд, при цьому `docker run` для кожного сценарію обмежується окремо. Повний шлях зберігає покриття QR package install і installer Docker/update для нічних запусків за розкладом, ручних запусків, release checks через workflow-call і pull request, які справді зачіпають поверхні installer/package/Docker. Push у `main`, зокрема merge commits, не примушують повний шлях; коли логіка changed-scope вимагала б повного покриття для push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної валідації. Повільний smoke для провайдера образів Bun global install окремо керується через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні запуски `install-smoke` можуть явно його ввімкнути, але pull request і push у `main` його не запускають. Тести QR і installer Docker зберігають власні Dockerfile, орієнтовані на встановлення. Локальний `test:docker:all` заздалегідь збирає один спільний образ live-test, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: базовий runner Node/Git для доріжок installer/update/plugin-dependency і функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних доріжок. Визначення Docker lanes розміщені в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожної доріжки через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає доріжки з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте типову кількість слотів основного пулу 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів хвостового пулу 10, чутливого до провайдерів, — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження для важких доріжок за замовчуванням дорівнюють `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб доріжки npm install і multi-service не перевантажували Docker, тоді як легші доріжки все одно заповнюють доступні слоти. Одна доріжка, важча за ефективні обмеження, усе ж може стартувати з порожнього пулу, а потім працює сама, доки не звільнить ресурси. Запуски доріжок за замовчуванням розводяться на 2 секунди, щоб уникнути локальних штормів create у Docker daemon; змініть це через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегований запуск попередньо перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних доріжок, зберігає тривалість доріжок для впорядкування за принципом longest-first і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перегляду планувальника. За замовчуванням він припиняє планувати нові pooled lanes після першої помилки, а кожна доріжка має резервний тайм-аут 120 хвилин, який можна змінити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lanes використовують жорсткіші індивідуальні обмеження. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні доріжки планувальника, зокрема доріжки лише для релізу, як-от `install-e2e`, і розділені доріжки оновлення bundled, як-от `bundled-channel-update-acpx`, пропускаючи cleanup smoke, щоб агенти могли відтворити одну невдалу доріжку. Повторно використовуваний workflow live/E2E запитує у `scripts/test-docker-all.mjs --plan-json`, який package, тип образу, live image, доріжка та покриття облікових даних потрібні, після чого `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє вміст tarball; збирає та публікує bare/functional Docker E2E images з тегом package-digest у GHCR через Blacksmith Docker layer cache, коли плану потрібні доріжки з установленим package; і повторно використовує надані входи `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи package-digest замість повторної збірки. Workflow `Package Acceptance` — це високорівневий шлюз пакетів: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball із SHA-256 або артефакту попереднього workflow, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E workflow. Він зберігає `workflow_ref` окремо від `package_ref`, щоб поточна логіка acceptance могла перевіряти старіші довірені коміти без checkout старого коду workflow. Release checks запускають профіль acceptance `package` для цільового ref; цей профіль покриває package/update/plugin contracts і є типовою GitHub-native заміною для більшості покриття package/update у Parallels. Набір Docker release-path запускає не більше трьох поділених на частини завдань із `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожна частина завантажувала лише потрібний їй тип образу й виконувала кілька доріжок через той самий зважений планувальник (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update|plugins-integrations`). OpenWebUI входить до `plugins-integrations`, коли це потрібно для повного покриття release-path, і зберігає окремий chunk `openwebui` лише для запусків, призначених тільки для OpenWebUI. Chunk `plugins-integrations` запускає розділені доріжки `bundled-channel-*` і `bundled-channel-update-*` замість послідовної універсальної доріжки `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` із журналами доріжок, тривалостями, `summary.json`, `failures.json`, тривалістю фаз, JSON плану планувальника, таблицями повільних доріжок і командами повторного запуску для кожної доріжки. Вхід `docker_lanes` workflow запускає вибрані доріжки на підготовлених образах замість chunk jobs, що обмежує налагодження невдалих доріжок одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана доріжка є live Docker lane, цільове завдання локально збирає образ live-test для цього повторного запуску. Згенеровані для GitHub команди повторного запуску для кожної доріжки містять `package_artifact_run_id`, `package_artifact_name` і входи підготовлених образів, коли ці значення існують, тож невдала доріжка може повторно використати точний package та образи з невдалого запуску. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker artifacts із запуску GitHub і вивести комбіновані/покрокові цільові команди повторного запуску; використовуйте `pnpm test:docker:timings ` для зведень повільних доріжок і критичного шляху фаз. Workflow scheduled live/E2E щодня запускає повний набір Docker release-path. Матрицю bundled update розділено за ціллю оновлення, щоб повторні проходи npm update і doctor repair можна було шардити разом з іншими bundled-перевірками. -Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо меж архітектури, ніж широка область дії платформ CI: зміни у production core запускають typecheck core prod і core test плюс lint/guards core, зміни лише в core test запускають лише typecheck core test плюс lint core, зміни у production extension запускають typecheck extension prod і extension test плюс lint extension, а зміни лише в extension test запускають typecheck extension test плюс lint extension. Зміни у публічному Plugin SDK або plugin-contract розширюють перевірку до typecheck extension, тому що extensions залежать від цих core-контрактів, але повні проходи Vitest для extension лишаються явною тестовою роботою. Зміни лише метаданих релізу для version bump запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно завершуються переходом на всі check lanes. +Локальна логіка changed-lane розміщена в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний шлюз перевірок суворіше ставиться до архітектурних меж, ніж широка платформна область дії CI: зміни production у core запускають typecheck для core prod і core test плюс core lint/guards, зміни лише в core tests запускають лише typecheck для core test плюс core lint, зміни production в extension запускають typecheck для extension prod і extension test плюс extension lint, а зміни лише в extension tests запускають typecheck лише для extension test плюс extension lint. Зміни у публічному Plugin SDK або plugin-contract розширюються до typecheck для extension, оскільки extensions залежать від цих контрактів core, але повні прогінні перевірки Vitest для extension є явною тестовою роботою. Зміни лише в метаданих релізу для version bumps запускають цільові перевірки version/config/root-dependency. Невідомі зміни root/config безпечно переводять перевірки в усі check lanes. -Ручні запуски CI виконують `checks-node-compat-node22` як покриття сумісності для кандидатів на реліз. Звичайні pull request і push до `main` пропускають цю lane і тримають матрицю зосередженою на test/channel lanes для Node 24. +Ручні запуски CI виконують `checks-node-compat-node22` як покриття сумісності для кандидатів на реліз. Звичайні pull request і push у `main` пропускають цю доріжку та зберігають матрицю зосередженою на доріжках test/channel для Node 24. -Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts запускаються як три зважені shard-и, тести bundled plugin балансуються між шістьма worker-ами extension, малі core unit lanes поєднуються в пари, auto-reply виконується на чотирьох збалансованих worker-ах із розбиттям піддерева reply на shard-и agent-runner, dispatch і commands/state-routing, а agentic-конфігурації gateway/plugin розподіляються по наявних source-only agentic Node jobs замість очікування built artifacts. Широкі browser-, QA-, media- і miscellaneous plugin-тести використовують свої окремі конфігурації Vitest замість спільної catch-all конфігурації plugin. Завдання shard-ів extension запускають до двох груп конфігурацій plugin одночасно з одним worker-ом Vitest на групу та більшим heap Node, щоб import-важкі пакети plugin не створювали додаткові завдання CI. Широка lane agents використовує спільний file-parallel scheduler Vitest, тому що в ній домінують import/планування, а не один конкретний повільний тестовий файл. `runtime-config` запускається разом із shard-ом infra core-runtime, щоб спільний runtime shard не тримав tail. Shard-и include-pattern записують записи таймінгів із використанням назви shard-а CI, тому `.artifacts/vitest-shard-timings.json` може відрізняти цілу конфігурацію від відфільтрованого shard-а. `check-additional` тримає compile/canary-роботи package-boundary разом і відокремлює архітектуру topology runtime від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guard-и паралельно всередині одного завдання. Gateway watch, channel-тести і shard support-boundary core запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі назви перевірок як легкі verifier-завдання та уникаючи двох додаткових worker-ів Blacksmith і другої черги споживачів артефактів. +Найповільніші сімейства тестів Node розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів виконуються як три зважені шарди, тести bundled plugin балансувалися між шістьма worker-ами extension, малі core unit lanes об’єднуються в пари, auto-reply працює на чотирьох збалансованих worker-ах із розбиттям піддерева reply на шарди agent-runner, dispatch і commands/state-routing, а agentic gateway/plugin configs розподіляються по наявних Node jobs лише для вихідного коду agentic замість очікування зібраних артефактів. Широкі browser-, QA-, media- та різні plugin-тести використовують власні конфігурації Vitest замість спільного універсального набору plugin. Завдання шардів extension запускають до двох груп конфігурацій plugin одночасно з одним worker-ом Vitest на групу та більшим heap Node, щоб пакети plugin із важкими import не створювали додаткових завдань CI. Широка доріжка agents використовує спільний file-parallel планувальник Vitest, оскільки в ній домінують import/планування, а не один конкретний повільний тестовий файл. `runtime-config` виконується разом із шардом infra core-runtime, щоб спільний runtime shard не володів хвостом. Шарди include-pattern записують записи тривалості з використанням назви CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізняти цілу конфігурацію від відфільтрованого шарда. `check-additional` тримає compile/canary-роботу package-boundary разом і відокремлює архітектуру runtime topology від покриття gateway watch; shard boundary guard запускає свої малі незалежні guard-и паралельно всередині одного завдання. Gateway watch, тести каналів і shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи їхні старі назви перевірок як легкі verifier jobs і водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-тестів усе одно компілює цей flavor з прапорцями BuildConfig для SMS/call-log, водночас уникаючи дублювання завдання пакування debug APK при кожному push, релевантному для Android. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Варіант third-party не має окремого source set або manifest; його доріжка unit-тестів усе одно компілює цей варіант із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK при кожному push, релевантному для Android. +GitHub може позначати замінені новішими завдання як `cancelled`, коли новіший push потрапляє в той самий ref PR або `main`. Ставтеся до цього як до шуму CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані shard-перевірки використовують `!cancelled() && always()`, тому вони все ще повідомляють про звичайні помилки shard-ів, але не стають у чергу після того, як увесь workflow уже було замінено новішим. -GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо лише найновіший запуск для того самого ref також не падає. Агреговані перевірки shard-ів використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні помилки shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений новішим. - -Автоматичний ключ конкурентності CI має версіонування (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски на main. Ручні повні запуски використовують `CI-manual-v1-*` і не скасовують запуски, що вже виконуються. +Автоматичний ключ concurrency для CI має версію (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски main. Ручні повні запуски набору використовують `CI-manual-v1-*` і не скасовують запуски, що вже виконуються. ## Runner-и -| Runner | Завдання | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, shard-и `check`, окрім lint, shard-и й агрегати `check-additional`, aggregate verifier-и Node-тестів, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node test shards, bundled plugin test shards, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який усе ще настільки чутливий до CPU, що 8 vCPU коштували дорожче, ніж заощаджували; Docker-збірки install-smoke, де вартість часу в черзі для 32-vCPU була вищою за виграш | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для fork використовується резервний `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork використовується резервний `macos-latest` | +| Runner | Завдання | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди та агрегати `check-additional`, aggregate verifier-и тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо чутливим до CPU, що 8 vCPU коштували більше, ніж зекономили; збірки Docker для install-smoke, де вартість часу очікування в черзі для 32-vCPU була більшою, ніж вигода | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; fork-репозиторії повертаються до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; fork-репозиторії повертаються до `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумний локальний check gate: changed typecheck/lint/guards за boundary lane -pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні швидкі guards +pnpm check:changed # розумний локальний шлюз перевірок: changed typecheck/lint/guards за boundary lane +pnpm check # швидкий локальний шлюз: production tsgo + шардований lint + паралельні швидкі guards pnpm check:test-types -pnpm check:timed # той самий gate з таймінгами для кожного етапу +pnpm check:timed # той самий шлюз із тривалістю кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest -pnpm test:changed # дешеві розумні changed-цілі для Vitest +pnpm test:changed # дешеві розумні changed-цілі Vitest pnpm test:channels pnpm test:contracts:channels pnpm check:docs # форматування документації + lint + биті посилання -pnpm build # зібрати dist, коли важливі ланки CI artifact/build-smoke -pnpm ci:timings # підсумувати останній push-запуск CI для origin/main -pnpm ci:timings:recent # порівняти недавні успішні запуски CI для main -node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші завдання +pnpm build # зібрати dist, коли важливі доріжки CI artifact/build-smoke +pnpm ci:timings # звести останній запуск push CI для origin/main +pnpm ci:timings:recent # порівняти нещодавні успішні запуски main CI +node scripts/ci-run-timings.mjs # звести загальний час, час у черзі та найповільніші завдання node scripts/ci-run-timings.mjs --latest-main # ігнорувати шум issue/comment і вибрати push CI для origin/main -node scripts/ci-run-timings.mjs --recent 10 # порівняти недавні успішні запуски CI для main +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` diff --git a/docs/uk/cli/gateway.md b/docs/uk/cli/gateway.md index 5180c53f3..f82480f3c 100644 --- a/docs/uk/cli/gateway.md +++ b/docs/uk/cli/gateway.md @@ -2,27 +2,27 @@ read_when: - Запуск Gateway з CLI (розробка або сервери) - Налагодження автентифікації Gateway, режимів прив’язки та підключення - - Виявлення шлюзів через Bonjour (локально + DNS-SD широкої зони) + - Виявлення шлюзів через Bonjour (локально + DNS-SD широкої області) sidebarTitle: Gateway -summary: CLI шлюзу OpenClaw (`openclaw gateway`) — запуск, запити та виявлення шлюзів +summary: OpenClaw Gateway CLI (`openclaw gateway`) — запуск, запит і виявлення шлюзів title: Gateway x-i18n: - generated_at: "2026-04-27T04:26:19Z" + generated_at: "2026-04-27T08:07:53Z" model: gpt-5.4 provider: openai - source_hash: 795d30511ad7a98093edfcfb862869349e1454d3e01f18dec7912cc2128934de + source_hash: 9c909e8f6e1fb56b612eb1a0826cd993626c9f65b1736924b33c95a37dc60d14 source_path: cli/gateway.md workflow: 15 --- -Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці доступні через `openclaw gateway …`. +Gateway — це сервер WebSocket OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці використовуються під `openclaw gateway …`. - - Налаштування локального mDNS + DNS-SD широкої зони. + + Налаштування локального mDNS + DNS-SD широкої області. - Як OpenClaw оголошує шлюзи та знаходить їх. + Як OpenClaw рекламує та знаходить шлюзи. Ключі конфігурації Gateway верхнього рівня. @@ -37,20 +37,20 @@ Gateway — це WebSocket-сервер OpenClaw (канали, вузли, се openclaw gateway ``` -Псевдонім для запуску у передньому плані: +Псевдонім для запуску на передньому плані: ```bash openclaw gateway run ``` - - - За замовчуванням Gateway відмовляється запускатися, якщо в `~/.openclaw/openclaw.json` не встановлено `gateway.mode=local`. Використовуйте `--allow-unconfigured` для ad-hoc/dev запусків. - - Очікується, що `openclaw onboard --mode local` і `openclaw setup` записують `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією та виправте її, а не припускайте неявно локальний режим. - - Якщо файл існує і `gateway.mode` відсутній, Gateway вважає це підозрілим пошкодженням конфігурації та відмовляється «вгадувати local» за вас. - - Прив’язка поза межами loopback без автентифікації блокується (захисне обмеження). - - `SIGUSR1` запускає перезапуск у межах процесу, якщо це дозволено (`commands.restart` увімкнено за замовчуванням; установіть `commands.restart: false`, щоб заборонити ручний перезапуск, водночас `gateway tool/config apply/update` залишаться дозволеними). - - Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жодний нестандартний стан термінала. Якщо ви обгортаєте CLI через TUI або raw-mode ввід, відновіть термінал перед виходом. + + - За замовчуванням Gateway відмовляється запускатися, якщо в `~/.openclaw/openclaw.json` не встановлено `gateway.mode=local`. Використовуйте `--allow-unconfigured` для одноразових/розробницьких запусків. + - Очікується, що `openclaw onboard --mode local` і `openclaw setup` запишуть `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією та відновіть її замість неявного припущення локального режиму. + - Якщо файл існує, а `gateway.mode` відсутній, Gateway вважає це підозрілим пошкодженням конфігурації й відмовляється «вгадувати local» за вас. + - Прив’язка поза межами loopback без автентифікації заблокована (захисний механізм безпеки). + - `SIGUSR1` запускає перезапуск у межах процесу, якщо це дозволено (`commands.restart` увімкнено за замовчуванням; встановіть `commands.restart: false`, щоб заблокувати ручний перезапуск, тоді як застосування gateway tool/config apply/update залишиться дозволеним). + - Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жоден спеціальний стан термінала. Якщо ви обгортаєте CLI у TUI або введення в raw mode, відновіть термінал перед виходом. @@ -66,37 +66,37 @@ openclaw gateway run Перевизначення режиму автентифікації. - Перевизначення токена (також встановлює `OPENCLAW_GATEWAY_TOKEN` для процесу). + Перевизначення токена (також установлює `OPENCLAW_GATEWAY_TOKEN` для процесу). Перевизначення пароля. - Зчитати пароль gateway з файлу. + Прочитати пароль gateway з файлу. Відкрити Gateway через Tailscale. - Скинути конфігурацію Tailscale serve/funnel під час завершення. + Скинути конфігурацію serve/funnel Tailscale під час завершення роботи. - Дозволити запуск gateway без `gateway.mode=local` у конфігурації. Обходить захист запуску лише для ad-hoc/dev початкового запуску; не записує та не виправляє файл конфігурації. + Дозволити запуск gateway без `gateway.mode=local` у конфігурації. Обходить захист запуску лише для одноразового/розробницького початкового налаштування; не записує і не відновлює файл конфігурації. Створити dev-конфігурацію + робочий простір, якщо вони відсутні (пропускає BOOTSTRAP.md). - Скинути dev-конфігурацію + облікові дані + сесії + робочий простір (потрібен `--dev`). + Скинути dev-конфігурацію + облікові дані + сесії + робочий простір (потребує `--dev`). - Перед запуском завершити будь-який наявний listener на вибраному порту. + Завершити будь-який наявний слухач на вибраному порту перед запуском. Докладні журнали. - Показувати в консолі лише журнали бекенду CLI (і ввімкнути stdout/stderr). + Показувати в консолі лише журнали бекенда CLI (і ввімкнути stdout/stderr). Стиль журналу WebSocket. @@ -105,10 +105,10 @@ openclaw gateway run Псевдонім для `--ws-log compact`. - Записувати необроблені події потоку моделі в jsonl. + Записувати сирі події потоку моделі в jsonl. - Шлях до jsonl необробленого потоку. + Шлях до jsonl сирого потоку. @@ -117,30 +117,30 @@ openclaw gateway run ### Профілювання запуску -- Установіть `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб журналювати тривалість етапів під час запуску Gateway. -- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виміряти запуск Gateway. Бенчмарк фіксує перший вивід процесу, `/healthz`, `/readyz` і часові показники трасування запуску. +- Установіть `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб журналювати час фаз під час запуску Gateway, включно із затримкою `eventLoopMax` для кожної фази та часом таблиці пошуку Plugin для installed-index, реєстру маніфестів, планування запуску та роботи owner-map. +- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виміряти швидкодію запуску Gateway. Бенчмарк фіксує перший вивід процесу, `/healthz`, `/readyz`, час трасування запуску, затримку event loop і деталі часу таблиці пошуку Plugin. ## Запит до запущеного Gateway -Усі команди запитів використовують WebSocket RPC. +Усі команди запиту використовують WebSocket RPC. - - За замовчуванням: читабельний для людини (кольоровий у TTY). - - `--json`: JSON для машинного читання (без стилізації/спінера). + - За замовчуванням: зручний для читання людиною формат (з кольором у TTY). + - `--json`: машинозчитуваний JSON (без стилізації/індикатора). - `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігши людський макет. - `--url `: URL WebSocket Gateway. - `--token `: токен Gateway. - `--password `: пароль Gateway. - - `--timeout `: тайм-аут/бюджет (залежить від команди). + - `--timeout `: тайм-аут/бюджет часу (залежить від команди). - `--expect-final`: чекати на «final» відповідь (виклики агента). -Коли ви встановлюєте `--url`, CLI не використовує облікові дані з конфігурації або середовища як резервні. Явно передайте `--token` або `--password`. Відсутність явно вказаних облікових даних є помилкою. +Коли ви задаєте `--url`, CLI не повертається до облікових даних із конфігурації чи середовища. Передайте `--token` або `--password` явно. Відсутність явно заданих облікових даних є помилкою. ### `gateway health` @@ -149,11 +149,11 @@ openclaw gateway run openclaw gateway health --url ws://127.0.0.1:18789 ``` -HTTP-ендпоінт `/healthz` є перевіркою життєздатності: він повертає відповідь, щойно сервер може відповідати по HTTP. HTTP-ендпоінт `/readyz` є суворішим і залишається червоним, поки стартові sidecar-компоненти, канали або налаштовані хуки ще завершують ініціалізацію. +HTTP-ендпоінт `/healthz` — це перевірка життєздатності: він відповідає, щойно сервер може обробляти HTTP. HTTP-ендпоінт `/readyz` суворіший і лишається неготовим, поки побічні процеси запуску, канали або налаштовані хуки ще завершують ініціалізацію. ### `gateway usage-cost` -Отримати зведення вартості використання з журналів сесій. +Отримати зведення usage-cost із журналів сесій. ```bash openclaw gateway usage-cost @@ -167,7 +167,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -Отримати нещодавній діагностичний журнал стабільності із запущеного Gateway. +Отримати нещодавній записувач діагностичної стабільності із запущеного Gateway. ```bash openclaw gateway stability @@ -184,28 +184,28 @@ openclaw gateway stability --json Фільтрувати за типом діагностичної події, наприклад `payload.large` або `diagnostic.memory.pressure`. - Включати лише події після діагностичного номера послідовності. + Включати лише події після номера послідовності діагностики. - Зчитати збережений пакет стабільності замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого пакета в каталозі стану або передайте шлях до JSON пакета безпосередньо. + Прочитати збережений пакет стабільності замість звернення до запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого пакета в каталозі стану, або передайте шлях до JSON пакета безпосередньо. - Записати zip-файл діагностики підтримки, яким можна поділитися, замість виведення подробиць стабільності. + Записати zip-файл із діагностикою підтримки, придатний для поширення, замість виведення деталей стабільності. Шлях виводу для `--export`. - - - Записи зберігають операційні метадані: назви подій, кількості, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/плагінів і відредаговані зведення сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, необроблені тіла запитів або відповідей, токени, cookie, секретні значення, імена хостів або необроблені ідентифікатори сесій. Установіть `diagnostics.enabled: false`, щоб повністю вимкнути реєстратор. - - Під час аварійного завершення Gateway, тайм-аутів завершення роботи та збоїв запуску після перезапуску OpenClaw записує той самий діагностичний знімок до `~/.openclaw/logs/stability/openclaw-stability-*.json`, якщо реєстратор має події. Перегляньте найновіший пакет за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу пакета. + + - Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/плагінів і відредаговані зведення сесій. Вони не зберігають текст чату, тіла Webhook, результати інструментів, сирі тіла запитів або відповідей, токени, cookies, секретні значення, імена хостів чи сирі id сесій. Установіть `diagnostics.enabled: false`, щоб повністю вимкнути записувач. + - У разі фатального завершення Gateway, тайм-аутів завершення роботи й помилок запуску під час перезапуску OpenClaw записує той самий діагностичний знімок у `~/.openclaw/logs/stability/openclaw-stability-*.json`, якщо записувач має події. Перегляньте найновіший пакет за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу пакета. ### `gateway diagnostics export` -Записати локальний zip-файл діагностики, призначений для прикріплення до звітів про помилки. Модель конфіденційності та вміст пакета дивіться в [Експорт діагностики](/uk/gateway/diagnostics). +Записати локальний zip-файл діагностики, призначений для додавання до звітів про помилки. Модель конфіденційності та вміст пакета див. у [Експорт діагностики](/uk/gateway/diagnostics). ```bash openclaw gateway diagnostics export @@ -214,13 +214,13 @@ openclaw gateway diagnostics export --json ``` - Шлях до вихідного zip-файлу. За замовчуванням — експорт підтримки в каталозі стану. + Шлях до вихідного zip-файлу. За замовчуванням — export для підтримки в каталозі стану. Максимальна кількість очищених рядків журналу для включення. - Максимальна кількість байтів журналу для аналізу. + Максимальна кількість байтів журналу для перевірки. URL WebSocket Gateway для знімка health. @@ -238,12 +238,12 @@ openclaw gateway diagnostics export --json Пропустити пошук збереженого пакета стабільності. - Вивести записаний шлях, розмір і маніфест у форматі JSON. + Вивести записаний шлях, розмір і маніфест як JSON. -Експорт містить маніфест, зведення у Markdown, форму конфігурації, очищені деталі конфігурації, очищені зведення журналів, очищені знімки status/health Gateway та найновіший пакет стабільності, якщо він існує. +Експорт містить маніфест, зведення у Markdown, форму конфігурації, очищені деталі конфігурації, очищені зведення журналів, очищені знімки status/health Gateway і найновіший пакет стабільності, якщо він існує. -Його призначено для спільного використання. Він зберігає операційні деталі, які допомагають під час налагодження, наприклад безпечні поля журналів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, ідентифікатори плагінів, ідентифікатори провайдерів, несекретні налаштування функцій і відредаговані операційні повідомлення журналів. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookie, ідентифікатори облікових записів/повідомлень, текст prompt/інструкцій, імена хостів і секретні значення. Якщо повідомлення у стилі LogTape схоже на текст корисного навантаження користувача/чату/інструмента, експорт зберігає лише факт пропуску повідомлення та кількість його байтів. +Він призначений для поширення. Він зберігає операційні деталі, що допомагають у налагодженні, як-от безпечні поля журналів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, id плагінів, id провайдерів, несекретні налаштування функцій і відредаговані повідомлення операційних журналів. Він пропускає або редагує текст чату, тіла Webhook, результати інструментів, облікові дані, cookies, ідентифікатори облікових записів/повідомлень, текст prompt/інструкцій, імена хостів і секретні значення. Коли повідомлення у стилі LogTape схоже на текст корисного навантаження користувача/чату/інструмента, експорт зберігає лише позначку про те, що повідомлення пропущено, і кількість його байтів. ### `gateway status` @@ -256,7 +256,7 @@ openclaw gateway status --require-rpc ``` - Додати явну ціль перевірки. Налаштовані remote + localhost також перевіряються. + Додати явну ціль перевірки. Налаштований віддалений хост + localhost усе одно перевіряються. Автентифікація токеном для перевірки. @@ -274,25 +274,25 @@ openclaw gateway status --require-rpc Також сканувати служби системного рівня. - Підвищити стандартну перевірку підключення до перевірки читання та завершуватися з ненульовим кодом, якщо ця перевірка читання не вдається. Не можна поєднувати з `--no-probe`. + Підвищити стандартну перевірку підключення до перевірки читання й завершуватися з ненульовим кодом, якщо ця перевірка читання не вдалася. Не можна поєднувати з `--no-probe`. - - - `gateway status` залишається доступною для діагностики, навіть якщо локальна конфігурація CLI відсутня або невалідна. - - Стандартна `gateway status` підтверджує стан служби, підключення WebSocket і можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування. - - Діагностичні перевірки не змінюють стан для первинної автентифікації пристрою: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність CLI-пристрою або запис pairing для пристрою лише з правом читання лише для перевірки status. - - `gateway status` за можливості розв’язує налаштовані SecretRef автентифікації для автентифікації перевірки. - - Якщо потрібний SecretRef автентифікації не розв’язується в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли перевірка підключення/автентифікації RPC не вдається; явно передайте `--token`/`--password` або спочатку виправте джерело секрету. - - Якщо перевірка успішна, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибнопозитивних спрацювань. - - Використовуйте `--require-rpc` у скриптах та автоматизації, коли недостатньо лише служби, що слухає, і потрібно, щоб RPC-виклики з областю читання також були справними. - - `--deep` додає best-effort сканування додаткових установок launchd/systemd/schtasks. Коли виявлено кілька служб, схожих на gateway, вивід для людини показує підказки з очищення й попереджає, що в більшості конфігурацій на одній машині має працювати один gateway. - - Вивід для людини містить розв’язаний шлях до файлового журналу, а також знімок шляхів/валідності конфігурації CLI та служби, щоб допомогти діагностувати розходження профілю або каталогу стану. + + - `gateway status` залишається доступним для діагностики, навіть коли локальна конфігурація CLI відсутня або недійсна. + - Типовий `gateway status` підтверджує стан служби, WebSocket-з’єднання та можливість автентифікації, видиму під час handshake. Він не підтверджує операції читання/запису/адміністрування. + - Діагностичні проби не змінюють стан для першої автентифікації пристрою: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність пристрою CLI або запис pairing read-only пристрою лише для перевірки статусу. + - `gateway status` за можливості розв’язує налаштовані SecretRef автентифікації для probe auth. + - Якщо потрібний SecretRef автентифікації не розв’язується в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли не вдається probe підключення/автентифікації; явно передайте `--token`/`--password` або спочатку виправте джерело секрету. + - Якщо probe успішний, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибнопозитивних спрацьовувань. + - Використовуйте `--require-rpc` у скриптах і автоматизації, коли недостатньо лише служби, що слухає, і потрібно, щоб також були працездатними виклики RPC з областю читання. + - `--deep` додає best-effort-сканування додаткових інсталяцій launchd/systemd/schtasks. Коли виявлено кілька служб, схожих на gateway, людиночитаний вивід показує підказки з очищення та попереджає, що в більшості налаштувань на машині має працювати один gateway. + - Людиночитаний вивід містить розв’язаний шлях до файлового журналу, а також знімок шляхів/дійсності конфігурації CLI-порівняно-зі-службою, щоб допомогти діагностувати дрейф профілю або каталогу стану. - - - В установках Linux systemd перевірки розходження автентифікації служби читають значення `Environment=` і `EnvironmentFile=` з unit-файлу (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами з `-`). - - Перевірки розходження розв’язують SecretRef `gateway.auth.token`, використовуючи об’єднане середовище виконання (спочатку середовище команди служби, потім резервне середовище процесу). - - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy`, або режим не задано, де може перемогти пароль і жоден кандидат токена не може перемогти), перевірки розходження токена пропускають розв’язання токена конфігурації. + + - В інсталяціях Linux systemd перевірки дрейфу автентифікації служби читають значення `Environment=` і `EnvironmentFile=` з unit-файлу (включно з `%h`, шляхами в лапках, кількома файлами й необов’язковими файлами з `-`). + - Перевірки дрейфу розв’язують SecretRef `gateway.auth.token`, використовуючи об’єднане runtime env (спочатку env команди служби, потім резервне env процесу). + - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy`, або mode не задано там, де може перемогти password і жоден кандидат токена не може перемогти), перевірки дрейфу токена пропускають розв’язання токена конфігурації. @@ -301,16 +301,16 @@ openclaw gateway status --require-rpc `gateway probe` — це команда «налагодити все». Вона завжди перевіряє: - ваш налаштований віддалений gateway (якщо задано), і -- localhost (loopback) **навіть якщо налаштовано remote**. +- localhost (loopback) **навіть якщо налаштовано віддалений**. -Якщо ви передаєте `--url`, ця явна ціль додається перед обома. Вивід для людини позначає цілі так: +Якщо ви передасте `--url`, ця явна ціль додається перед обома. Людиночитаний вивід позначає цілі так: - `URL (explicit)` - `Remote (configured)` або `Remote (configured, inactive)` - `Local loopback` -Якщо доступні кілька gateway, команда виведе всі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але в більшості установок усе одно працює один gateway. +Якщо доступно кілька gateway, буде виведено їх усі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але в більшості інсталяцій усе ще працює один gateway. ```bash @@ -320,73 +320,73 @@ openclaw gateway probe --json - - `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-підключення. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що перевірка змогла підтвердити щодо автентифікації. Це окремо від доступності. - - `Read probe: ok` означає, що RPC-виклики деталей з областю читання (`health`/`status`/`system-presence`/`config.get`) також успішні. - - `Read probe: limited - missing scope: operator.read` означає, що підключення успішне, але RPC із областю читання обмежено. Це повідомляється як **degraded** доступність, а не як повна помилка. - - Як і `gateway status`, probe повторно використовує наявну кешовану автентифікацію пристрою, але не створює первинну ідентичність пристрою або стан pairing. - - Код виходу є ненульовим лише тоді, коли жодна перевірена ціль не є доступною. + - `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-з’єднання. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` показує, що probe зміг підтвердити щодо автентифікації. Це окремо від досяжності. + - `Read probe: ok` означає, що також успішно виконалися докладні виклики RPC з областю читання (`health`/`status`/`system-presence`/`config.get`). + - `Read probe: limited - missing scope: operator.read` означає, що з’єднання встановлено успішно, але RPC з областю читання обмежений. Це повідомляється як **погіршена** досяжність, а не повний збій. + - Як і `gateway status`, probe повторно використовує наявну кешовану автентифікацію пристрою, але не створює стан першої ідентичності пристрою чи pairing. + - Код виходу є ненульовим лише тоді, коли жодна перевірена ціль не є досяжною. Верхній рівень: - - `ok`: принаймні одна ціль доступна. - - `degraded`: принаймні одна ціль мала RPC деталей, обмежений областю. - - `capability`: найкраща можливість, виявлена серед доступних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`). - - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем, у такому порядку: явний URL, SSH-тунель, налаштований remote, потім local loopback. - - `warnings[]`: записи попереджень best-effort з `code`, `message` та необов’язковими `targetIds`. - - `network`: підказки URL local loopback/tailnet, виведені з поточної конфігурації та мережі хоста. + - `ok`: принаймні одна ціль є досяжною. + - `degraded`: принаймні для однієї цілі детальний RPC був обмежений за scope. + - `capability`: найкраща можливість, виявлена серед досяжних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`). + - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем, у такому порядку: явний URL, SSH-тунель, налаштований віддалений хост, потім локальний loopback. + - `warnings[]`: записи попереджень best-effort з `code`, `message` і необов’язковими `targetIds`. + - `network`: підказки URL локального loopback/tailnet, виведені з поточної конфігурації та мережі хоста. - `discovery.timeoutMs` і `discovery.count`: фактичний бюджет/кількість результатів виявлення, використані для цього проходу probe. Для кожної цілі (`targets[].connect`): - - `ok`: доступність після підключення + класифікація degraded. - - `rpcOk`: повний успіх RPC деталей. - - `scopeLimited`: RPC деталей не вдалося через відсутню область operator. + - `ok`: досяжність після з’єднання + класифікація degraded. + - `rpcOk`: повний успіх детального RPC. + - `scopeLimited`: детальний RPC не вдався через відсутню operator scope. Для кожної цілі (`targets[].auth`): - - `role`: роль автентифікації, повідомлена в `hello-ok`, коли доступно. - - `scopes`: надані області, повідомлені в `hello-ok`, коли доступно. - - `capability`: класифікація видимої можливості автентифікації для цієї цілі. + - `role`: роль автентифікації, повідомлена в `hello-ok`, якщо доступна. + - `scopes`: надані scope, повідомлені в `hello-ok`, якщо доступні. + - `capability`: показана класифікація можливостей автентифікації для цієї цілі. - - `ssh_tunnel_failed`: не вдалося налаштувати SSH-тунель; команда повернулася до прямих перевірок. - - `multiple_gateways`: була доступна більше ніж одна ціль; це нетипово, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot. - - `auth_secretref_unresolved`: налаштований SecretRef автентифікації не вдалося розв’язати для цілі, що завершилася помилкою. - - `probe_scope_limited`: WebSocket-підключення успішне, але перевірка читання була обмежена через відсутність `operator.read`. + - `ssh_tunnel_failed`: не вдалося налаштувати SSH-тунель; команда переключилася на прямі probe. + - `multiple_gateways`: було досяжно більше ніж одну ціль; це незвично, якщо тільки ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot. + - `auth_secretref_unresolved`: налаштований auth SecretRef не вдалося розв’язати для цілі, що завершилася невдачею. + - `probe_scope_limited`: WebSocket-з’єднання встановлено успішно, але read probe був обмежений через відсутність `operator.read`. -#### Віддалений доступ через SSH (паритет із застосунком Mac) +#### Віддалено через SSH (паритет із Mac app) -Режим застосунку macOS «Remote over SSH» використовує локальне переадресування порту, щоб віддалений gateway (який може бути прив’язаний лише до loopback) став доступним за адресою `ws://127.0.0.1:`. +Режим macOS app «Remote over SSH» використовує локальне переспрямування порту, тому віддалений gateway (який може бути прив’язаний лише до loopback) стає досяжним за адресою `ws://127.0.0.1:`. -Еквівалент CLI: +Еквівалент у CLI: ```bash openclaw gateway probe --ssh user@gateway-host ``` - `user@host` або `user@host:port` (порт за замовчуванням — `22`). + `user@host` або `user@host:port` (порт за замовчуванням `22`). Файл ідентичності. - Вибрати перший виявлений хост gateway як ціль SSH із розв’язаного ендпоінта виявлення (`local.` плюс налаштований домен широкої зони, якщо він є). Підказки лише з TXT ігноруються. + Вибрати перший виявлений хост gateway як SSH-ціль із розв’язаного endpoint виявлення (`local.` плюс налаштований wide-area domain, якщо є). Підказки лише з TXT ігноруються. -Конфігурація (необов’язкова, використовується як типове значення): +Конфігурація (необов’язково, використовується як значення за замовчуванням): - `gateway.remote.sshTarget` - `gateway.remote.sshIdentity` ### `gateway call ` -Низькорівневий помічник RPC. +Низькорівневий допоміжний засіб RPC. ```bash openclaw gateway call status @@ -409,14 +409,14 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Бюджет тайм-ауту. - Переважно для RPC у стилі агента, які передають проміжні події потоком перед фінальним корисним навантаженням. + Головним чином для RPC у стилі агентів, які передають проміжні події потоком перед фінальним корисним навантаженням. - JSON-вивід для машинного читання. + Машинозчитуваний вивід JSON. -`--params` має бути валідним JSON. +`--params` має бути коректним JSON. ## Керування службою Gateway @@ -429,9 +429,11 @@ openclaw gateway restart openclaw gateway uninstall ``` -### Установлення з обгорткою +### Інсталяція з wrapper -Використовуйте `--wrapper`, коли керована служба має запускатися через інший виконуваний файл, наприклад shim менеджера секретів або допоміжну програму run-as. Обгортка отримує звичайні аргументи Gateway і відповідає за те, щоб зрештою виконати `openclaw` або Node з цими аргументами. +Використовуйте `--wrapper`, коли керована служба має запускатися через інший виконуваний файл, наприклад +shim менеджера секретів або допоміжний засіб запуску від іншого користувача. Wrapper отримує звичайні аргументи Gateway і +відповідає за те, щоб зрештою виконати `openclaw` або Node з цими аргументами. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -445,14 +447,16 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -Ви також можете задати обгортку через середовище. `gateway install` перевіряє, що шлях указує на виконуваний файл, записує обгортку в `ProgramArguments` служби та зберігає `OPENCLAW_WRAPPER` у середовищі служби для подальших примусових перевстановлень, оновлень і виправлень doctor. +Ви також можете задати wrapper через середовище. `gateway install` перевіряє, що шлях +вказує на виконуваний файл, записує wrapper у `ProgramArguments` служби та зберігає +`OPENCLAW_WRAPPER` у середовищі служби для подальших примусових перевстановлень, оновлень і виправлень через doctor. ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force openclaw doctor ``` -Щоб видалити збережену обгортку, очистьте `OPENCLAW_WRAPPER` під час перевстановлення: +Щоб видалити збережений wrapper, очистьте `OPENCLAW_WRAPPER` під час перевстановлення: ```bash OPENCLAW_WRAPPER= openclaw gateway install --force @@ -466,36 +470,36 @@ openclaw gateway restart - `gateway uninstall|start|stop|restart`: `--json` - - Використовуйте `gateway restart`, щоб перезапустити керовану службу. Не об’єднуйте `gateway stop` і `gateway start` як заміну перезапуску; у macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупиненням. - - Команди життєвого циклу приймають `--json` для скриптів. + - Використовуйте `gateway restart`, щоб перезапустити керовану службу. Не поєднуйте `gateway stop` і `gateway start` як заміну перезапуску; у macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупинкою. + - Команди життєвого циклу підтримують `--json` для скриптів. - - - Коли автентифікація токеном вимагає токен, а `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у метаданих середовища служби. - - Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язується, установлення завершується в закритому режимі замість збереження резервного відкритого тексту. + + - Коли для автентифікації токеном потрібен токен і `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у метаданих середовища служби. + - Якщо для автентифікації токеном потрібен токен, а налаштований SecretRef токена не розв’язується, інсталяція завершується в безпечному режимі замість збереження резервного відкритого тексту. - Для автентифікації паролем у `gateway run` надавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password` на основі SecretRef замість вбудованого `--password`. - - У режимі автентифікації, що визначається автоматично, лише shell-змінна `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час установлення; використовуйте стійку конфігурацію (`gateway.auth.password` або config `env`) під час установлення керованої служби. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, установлення блокується, доки режим не буде задано явно. + - У режимі виведеної автентифікації лише shell-змінна `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час інсталяції; використовуйте стійку конфігурацію (`gateway.auth.password` або config `env`) під час інсталяції керованої служби. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, інсталяцію буде заблоковано, доки режим не буде задано явно. -## Виявлення шлюзів (Bonjour) +## Виявлення gateway (Bonjour) `gateway discover` сканує маяки Gateway (`_openclaw-gw._tcp`). -- Multicast DNS-SD: `local.` -- Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [Bonjour](/uk/gateway/bonjour). +- Багатоадресний DNS-SD: `local.` +- Одноадресний DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [Bonjour](/uk/gateway/bonjour). -Лише шлюзи з увімкненим виявленням Bonjour (типово ввімкнено) оголошують маяк. +Лише gateway з увімкненим виявленням Bonjour (типово ввімкнено) рекламують маяк. Записи виявлення Wide-Area містять (TXT): - `role` (підказка ролі gateway) - `transport` (підказка транспорту, наприклад `gateway`) - `gatewayPort` (порт WebSocket, зазвичай `18789`) -- `sshPort` (необов’язково; клієнти за замовчуванням використовують для SSH-цілей `22`, якщо він відсутній) +- `sshPort` (необов’язково; клієнти за замовчуванням використовують `22` для SSH-цілей, якщо його немає) - `tailnetDns` (ім’я хоста MagicDNS, якщо доступне) - `gatewayTls` / `gatewayTlsSha256` (TLS увімкнено + відбиток сертифіката) -- `cliPath` (підказка віддаленого встановлення, записана до зони wide-area) +- `cliPath` (підказка віддаленої інсталяції, записана в wide-area zone) ### `gateway discover` @@ -504,10 +508,10 @@ openclaw gateway discover ``` - Тайм-аут на команду (browse/resolve). + Тайм-аут для кожної команди (browse/resolve). - Вивід для машинного читання (також вимикає стилізацію/spinner). + Машинозчитуваний вивід (також вимикає стилізацію/індикатор). Приклади: @@ -518,12 +522,12 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- CLI сканує `local.` плюс налаштований домен широкої зони, коли його увімкнено. -- `wsUrl` у JSON-виводі виводиться з розв’язаного ендпоінта служби, а не з підказок лише TXT, таких як `lanHost` або `tailnetDns`. -- У `local.` mDNS `sshPort` і `cliPath` транслюються лише коли `discovery.mdns.mode` має значення `full`. Wide-Area DNS-SD усе одно записує `cliPath`; `sshPort` там також залишається необов’язковим. +- CLI сканує `local.` плюс налаштований wide-area domain, коли його увімкнено. +- `wsUrl` у JSON-виводі виводиться з розв’язаного endpoint служби, а не з підказок лише з TXT, таких як `lanHost` або `tailnetDns`. +- Для mDNS у `local.` `sshPort` і `cliPath` транслюються лише тоді, коли `discovery.mdns.mode` має значення `full`. Wide-area DNS-SD усе одно записує `cliPath`; `sshPort` там також залишається необов’язковим. ## Пов’язане - [Довідник CLI](/uk/cli) -- [Операційний посібник Gateway](/uk/gateway) +- [Runbook Gateway](/uk/gateway) diff --git a/docs/uk/cli/migrate.md b/docs/uk/cli/migrate.md new file mode 100644 index 000000000..bb4ba9e03 --- /dev/null +++ b/docs/uk/cli/migrate.md @@ -0,0 +1,152 @@ +--- +read_when: + - Ви хочете мігрувати з Hermes або іншої агентної системи до OpenClaw + - Ви додаєте provider міграції, що належить Plugin +summary: Довідник CLI для `openclaw migrate` (імпорт стану з іншої агентної системи) +title: Міграція +x-i18n: + generated_at: "2026-04-27T08:07:52Z" + model: gpt-5.4 + provider: openai + source_hash: 8bb986558e2ce09e7fecbfc78beb149890965df8b6d82924cbfbcadb74b9f3c1 + source_path: cli/migrate.md + workflow: 15 +--- + +# `openclaw migrate` + +Імпортуйте стан з іншої агентної системи через provider міграції, що належить Plugin. + + +Щоб переглянути орієнтований на користувача покроковий посібник з переходу з Hermes, див. [Міграція з Hermes](/uk/install/migrating-hermes). + + +## Команди + +```bash +openclaw migrate list +openclaw migrate hermes --dry-run +openclaw migrate hermes +openclaw migrate apply hermes --yes +openclaw migrate apply hermes --include-secrets --yes +openclaw onboard --flow import +openclaw onboard --import-from hermes --import-source ~/.hermes +``` + + + Назва зареєстрованого provider міграції, наприклад `hermes`. Запустіть `openclaw migrate list`, щоб побачити встановлені provider-и. + + + Побудувати план і завершити роботу без зміни стану. + + + Перевизначити каталог вихідного стану. Для Hermes типовим є `~/.hermes`. + + + Імпортувати підтримувані облікові дані. За замовчуванням вимкнено. + + + Дозволити apply замінювати наявні цілі, коли план повідомляє про конфлікти. + + + Пропустити запит на підтвердження. Обов’язково в неінтерактивному режимі. + + + Пропустити резервне копіювання перед apply. Потребує `--force`, коли існує локальний стан OpenClaw. + + + Обов’язково разом із `--no-backup`, коли apply інакше відмовився б пропускати резервне копіювання. + + + Вивести план або результат apply у форматі JSON. Якщо вказано `--json` без `--yes`, apply виводить план і не змінює стан. + + +## Модель безпеки + +`openclaw migrate` спочатку показує попередній перегляд. + + + + Provider повертає деталізований план до внесення будь-яких змін, зокрема конфлікти, пропущені елементи та чутливі елементи. Плани JSON, вивід apply і звіти про міграцію маскують вкладені ключі, схожі на секрети, як-от API-ключі, токени, заголовки авторизації, cookies і паролі. + + `openclaw migrate apply ` показує попередній перегляд плану й запитує підтвердження перед зміною стану, якщо не вказано `--yes`. У неінтерактивному режимі apply потребує `--yes`. + + + Apply створює та перевіряє резервну копію OpenClaw перед застосуванням міграції. Якщо локального стану OpenClaw ще немає, крок резервного копіювання пропускається, і міграція може продовжитися. Щоб пропустити резервне копіювання, коли стан існує, передайте одночасно `--no-backup` і `--force`. + + + Apply відмовляється продовжувати, якщо в плані є конфлікти. Перегляньте план, а потім повторно запустіть із `--overwrite`, якщо заміна наявних цілей є навмисною. Provider-и все одно можуть записувати резервні копії окремих елементів для перезаписаних файлів у каталог звіту про міграцію. + + + Секрети ніколи не імпортуються за замовчуванням. Використовуйте `--include-secrets`, щоб імпортувати підтримувані облікові дані. + + + +## Provider Hermes + +Вбудований provider Hermes за замовчуванням виявляє стан у `~/.hermes`. Використовуйте `--from `, якщо Hermes розташований в іншому місці. + +### Що імпортується + +- Типова конфігурація моделі з `config.yaml`. +- Налаштовані provider-и моделей і користувацькі OpenAI-сумісні кінцеві точки з `providers` і `custom_providers`. +- Визначення MCP-серверів з `mcp_servers` або `mcp.servers`. +- `SOUL.md` і `AGENTS.md` у робочий простір агента OpenClaw. +- `memories/MEMORY.md` і `memories/USER.md`, додані до файлів пам’яті робочого простору. +- Типові налаштування пам’яті для файлової пам’яті OpenClaw, а також елементи архіву або ручної перевірки для зовнішніх provider-ів пам’яті, таких як Honcho. +- Skills, які містять файл `SKILL.md` у `skills//`. +- Значення конфігурації для кожного Skill з `skills.config`. +- Підтримувані API-ключі з `.env`, лише з `--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`. + +### Стан лише для архіву + +Стан Hermes, який OpenClaw не може безпечно інтерпретувати, копіюється до звіту про міграцію для ручної перевірки, але не завантажується в активну конфігурацію чи облікові дані OpenClaw. Це дає змогу зберегти непрозорий або потенційно небезпечний стан без удавання, що OpenClaw може автоматично виконувати або довіряти йому: + +- `plugins/` +- `sessions/` +- `logs/` +- `cron/` +- `mcp-tokens/` +- `auth.json` +- `state.db` + +### Після застосування + +```bash +openclaw doctor +``` + +## Контракт Plugin + +Джерела міграції — це plugins. Plugin оголошує ідентифікатори своїх provider-ів у `openclaw.plugin.json`: + +```json +{ + "contracts": { + "migrationProviders": ["hermes"] + } +} +``` + +Під час виконання Plugin викликає `api.registerMigrationProvider(...)`. Provider реалізує `detect`, `plan` і `apply`. Core відповідає за оркестрацію CLI, політику резервного копіювання, запити підтвердження, вивід JSON і попередню перевірку конфліктів. Core передає перевірений план до `apply(ctx, plan)`, а provider-и можуть перебудовувати план лише тоді, коли цей аргумент відсутній, для сумісності. + +Plugins provider-ів можуть використовувати `openclaw/plugin-sdk/migration` для побудови елементів і підсумкових підрахунків, а також `openclaw/plugin-sdk/migration-runtime` для копіювання файлів з урахуванням конфліктів, копіювання звітів лише для архіву та звітів про міграцію. + +## Інтеграція з онбордингом + +Під час онбордингу можна запропонувати міграцію, коли provider виявляє відоме джерело. І `openclaw onboard --flow import`, і `openclaw setup --wizard --import-from hermes` використовують той самий plugin provider міграції та все одно показують попередній перегляд перед застосуванням. + + +Імпорт під час онбордингу потребує свіжого налаштування OpenClaw. Спочатку скиньте конфігурацію, облікові дані, сесії та робочий простір, якщо у вас уже є локальний стан. Імпорт із резервним копіюванням і перезаписом або злиттям для наявних налаштувань доступний лише за feature gate. + + +## Пов’язане + +- [Міграція з Hermes](/uk/install/migrating-hermes): орієнтований на користувача покроковий посібник. +- [Міграція](/uk/install/migrating): переміщення OpenClaw на нову машину. +- [Doctor](/uk/gateway/doctor): перевірка стану після застосування міграції. +- [Plugins](/uk/tools/plugin): встановлення та реєстрація Plugin. diff --git a/docs/uk/cli/onboard.md b/docs/uk/cli/onboard.md index af93f1be3..b56361fe3 100644 --- a/docs/uk/cli/onboard.md +++ b/docs/uk/cli/onboard.md @@ -1,38 +1,38 @@ --- read_when: - - Ви хочете покрокове налаштування Gateway, робочого простору, автентифікації, каналів і Skills -summary: Довідник CLI для `openclaw onboard` (інтерактивне початкове налаштування) -title: Початкове налаштування + - Ви хочете покрокове налаштування для Gateway, робочого простору, автентифікації, каналів і Skills +summary: Довідник CLI для `openclaw onboard` (інтерактивне налаштування) +title: Налаштування x-i18n: - generated_at: "2026-04-27T04:37:17Z" + generated_at: "2026-04-27T08:07:54Z" model: gpt-5.4 provider: openai - source_hash: 98985c119f64ba41ed1a74fbb0bf1feb78b3c5daa4844e66f3aa1ae73ef6d0f5 + source_hash: 041063bce6616ed32225cb411f385dcbfd750c0bb2779ec17bc58e1aa9ada254 source_path: cli/onboard.md workflow: 15 --- # `openclaw onboard` -Інтерактивне початкове налаштування для локального або віддаленого налаштування Gateway. +Інтерактивне налаштування для локальної або віддаленої конфігурації Gateway. ## Пов’язані посібники - - Покроковий огляд інтерактивного процесу в CLI. + + Покроковий огляд інтерактивного процесу CLI. - - Як організовано початкове налаштування OpenClaw. + + Як поєднуються етапи налаштування OpenClaw. - - Вивід, внутрішня логіка та поведінка на кожному кроці. + + Виводи, внутрішня логіка та поведінка на кожному кроці. - Неінтерактивні прапорці та налаштування через сценарії. + Неінтерактивні прапорці та сценарії налаштування. - - Процес початкового налаштування для застосунку macOS у рядку меню. + + Процес налаштування для програми macOS у рядку меню. @@ -43,19 +43,23 @@ openclaw onboard openclaw onboard --modern openclaw onboard --flow quickstart openclaw onboard --flow manual +openclaw onboard --flow import +openclaw onboard --import-from hermes --import-source ~/.hermes openclaw onboard --skip-bootstrap openclaw onboard --mode remote --remote-url wss://gateway-host:18789 ``` -`--modern` запускає попередній перегляд розмовного початкового налаштування Crestodian. Без -`--modern` команда `openclaw onboard` використовує класичний процес початкового налаштування. +`--flow import` використовує провайдери міграції, що належать Plugin, як-от Hermes. Він запускається лише для нової конфігурації OpenClaw; якщо вже існують файли конфігурації, облікові дані, сесії або файли пам’яті/ідентичності робочого простору, перед імпортом виконайте скидання або виберіть нове налаштування. + +`--modern` запускає попередню версію розмовного налаштування Crestodian. Без +`--modern` команда `openclaw onboard` використовує класичний процес налаштування. Для цілей `ws://` у приватній мережі без шифрування (лише для довірених мереж) установіть -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у середовищі процесу початкового налаштування. -Еквівалента `openclaw.json` для цього аварійного обходу клієнтського транспорту -немає. +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у середовищі процесу налаштування. +Еквівалента в `openclaw.json` для цього аварійного клієнтського +обходу транспортного захисту немає. -Неінтерактивний власний провайдер: +Неінтерактивний користувацький провайдер: ```bash openclaw onboard --non-interactive \ @@ -67,7 +71,7 @@ openclaw onboard --non-interactive \ --custom-compatibility openai ``` -`--custom-api-key` є необов’язковим у неінтерактивному режимі. Якщо його не вказано, початкове налаштування перевіряє `CUSTOM_API_KEY`. +`--custom-api-key` є необов’язковим у неінтерактивному режимі. Якщо його не вказано, налаштування перевіряє `CUSTOM_API_KEY`. LM Studio також підтримує прапорець ключа, специфічний для провайдера, у неінтерактивному режимі: @@ -90,9 +94,9 @@ openclaw onboard --non-interactive \ --accept-risk ``` -`--custom-base-url` типово має значення `http://127.0.0.1:11434`. `--custom-model-id` є необов’язковим; якщо його не вказано, початкове налаштування використовує рекомендовані типові значення Ollama. Ідентифікатори хмарних моделей, як-от `kimi-k2.5:cloud`, також тут працюють. +`--custom-base-url` типово має значення `http://127.0.0.1:11434`. `--custom-model-id` є необов’язковим; якщо його не вказано, налаштування використовує рекомендовані типові значення Ollama. Ідентифікатори хмарних моделей, як-от `kimi-k2.5:cloud`, тут також працюють. -Зберігайте ключі провайдера як посилання, а не як відкритий текст: +Зберігайте ключі провайдера як посилання, а не у відкритому вигляді: ```bash openclaw onboard --non-interactive \ @@ -101,26 +105,26 @@ openclaw onboard --non-interactive \ --accept-risk ``` -З `--secret-input-mode ref` початкове налаштування записує посилання, підкріплені змінними середовища, замість значень ключів у відкритому тексті. -Для провайдерів на основі auth-profile це записує записи `keyRef`; для власних провайдерів це записує `models.providers..apiKey` як посилання env (наприклад, `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). +З `--secret-input-mode ref` налаштування записує посилання, що використовують змінні середовища, замість значень ключів у відкритому вигляді. +Для провайдерів на основі auth-profile це записує записи `keyRef`; для користувацьких провайдерів це записує `models.providers..apiKey` як env ref (наприклад, `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). -Контракт неінтерактивного режиму `ref`: +Умови неінтерактивного режиму `ref`: -- Установіть змінну середовища провайдера в середовищі процесу початкового налаштування (наприклад, `OPENAI_API_KEY`). +- Установіть змінну середовища провайдера в середовищі процесу налаштування (наприклад, `OPENAI_API_KEY`). - Не передавайте вбудовані прапорці ключів (наприклад, `--openai-api-key`), якщо цю змінну середовища також не встановлено. -- Якщо вбудований прапорець ключа передано без обов’язкової змінної середовища, початкове налаштування негайно завершується з помилкою та підказкою. +- Якщо вбудований прапорець ключа передано без потрібної змінної середовища, налаштування негайно завершується з підказками. Параметри токена Gateway у неінтерактивному режимі: -- `--gateway-auth token --gateway-token ` зберігає токен у відкритому тексті. +- `--gateway-auth token --gateway-token ` зберігає токен у відкритому вигляді. - `--gateway-auth token --gateway-token-ref-env ` зберігає `gateway.auth.token` як env SecretRef. - `--gateway-token` і `--gateway-token-ref-env` є взаємовиключними. -- `--gateway-token-ref-env` потребує непорожньої змінної середовища в середовищі процесу початкового налаштування. -- З `--install-daemon`, коли автентифікація токеном потребує токен, токени Gateway під керуванням SecretRef проходять перевірку, але не зберігаються як розв’язаний відкритий текст у метаданих середовища служби супервізора. -- З `--install-daemon`, якщо режим токена потребує токен, а налаштований SecretRef токена не розв’язується, початкове налаштування завершується за принципом fail closed з інструкціями щодо усунення проблеми. -- З `--install-daemon`, якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, але `gateway.auth.mode` не задано, початкове налаштування блокує інсталяцію, доки режим не буде явно встановлено. -- Локальне початкове налаштування записує `gateway.mode="local"` у конфігурацію. Якщо в пізнішому файлі конфігурації відсутній `gateway.mode`, вважайте це пошкодженням конфігурації або неповним ручним редагуванням, а не коректним скороченням для локального режиму. -- `--allow-unconfigured` — це окремий аварійний обхід для середовища виконання Gateway. Це не означає, що під час початкового налаштування можна пропустити `gateway.mode`. +- `--gateway-token-ref-env` потребує непорожньої змінної середовища в середовищі процесу налаштування. +- Із `--install-daemon`, коли автентифікація токеном вимагає токен, токени Gateway під керуванням SecretRef перевіряються, але не зберігаються як розв’язаний відкритий текст у метаданих середовища служби supervisor. +- Із `--install-daemon`, якщо режим токена вимагає токен, а налаштований токен SecretRef не розв’язується, налаштування блокує виконання з підказками щодо усунення проблеми. +- Із `--install-daemon`, якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, але `gateway.auth.mode` не задано, налаштування блокує встановлення, доки режим не буде вказано явно. +- Локальне налаштування записує `gateway.mode="local"` у конфігурацію. Якщо в пізнішому файлі конфігурації бракує `gateway.mode`, вважайте це пошкодженням конфігурації або неповним ручним редагуванням, а не коректним скороченням для локального режиму. +- `--allow-unconfigured` — це окремий аварійний механізм середовища виконання Gateway. Це не означає, що під час налаштування можна пропустити `gateway.mode`. Приклад: @@ -136,22 +140,22 @@ openclaw onboard --non-interactive \ Стан локального Gateway у неінтерактивному режимі: -- Якщо не передано `--skip-health`, початкове налаштування чекає, доки локальний Gateway стане доступним, перш ніж успішно завершитися. -- `--install-daemon` спочатку запускає керований шлях інсталяції Gateway. Без нього у вас уже має працювати локальний Gateway, наприклад `openclaw gateway run`. +- Якщо ви не передасте `--skip-health`, налаштування чекатиме доступності локального Gateway перед успішним завершенням. +- `--install-daemon` спочатку запускає шлях установленого керованого Gateway. Без нього локальний Gateway уже має працювати, наприклад через `openclaw gateway run`. - Якщо в автоматизації вам потрібні лише записи конфігурації/робочого простору/bootstrap, використовуйте `--skip-health`. -- Якщо ви самі керуєте файлами робочого простору, передайте `--skip-bootstrap`, щоб установити `agents.defaults.skipBootstrap: true` і пропустити створення `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` і `BOOTSTRAP.md`. -- У нативному Windows `--install-daemon` спочатку намагається використати Scheduled Tasks і переходить до елемента входу в систему в папці Startup для поточного користувача, якщо створення завдання заборонено. +- Якщо ви самостійно керуєте файлами робочого простору, передайте `--skip-bootstrap`, щоб установити `agents.defaults.skipBootstrap: true` і пропустити створення `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` і `BOOTSTRAP.md`. +- У рідному Windows `--install-daemon` спочатку пробує Scheduled Tasks, а якщо створення завдання заборонено — переходить до елемента входу в систему для поточного користувача в папці Startup. -Поведінка інтерактивного початкового налаштування в режимі посилань: +Поведінка інтерактивного налаштування з режимом посилань: - Коли з’явиться запит, виберіть **Use secret reference**. - Потім виберіть один із варіантів: - Змінна середовища - Налаштований провайдер секретів (`file` або `exec`) -- Початкове налаштування виконує швидку попередню перевірку перед збереженням посилання. - - Якщо перевірка не пройде, початкове налаштування покаже помилку й дозволить повторити спробу. +- Перед збереженням посилання налаштування виконує швидку попередню перевірку. + - Якщо перевірка не проходить, налаштування покаже помилку й дозволить повторити спробу. -### Варіанти кінцевих точок Z.AI у неінтерактивному режимі +### Неінтерактивні варіанти кінцевих точок Z.AI `--auth-choice zai-api-key` автоматично визначає найкращу кінцеву точку Z.AI для вашого ключа (надає перевагу загальному API з `zai/glm-5.1`). Якщо вам потрібні саме кінцеві точки GLM Coding Plan, виберіть `zai-coding-global` або `zai-coding-cn`. @@ -181,26 +185,28 @@ openclaw onboard --non-interactive \ - - `quickstart`: мінімум запитів, автоматично генерує токен Gateway. - - `manual`: повні запити для порту, bind і автентифікації (псевдонім для `advanced`). + - `quickstart`: мінімум запитів, автоматично створює токен Gateway. + - `manual`: повні запити для порту, прив’язки та автентифікації (псевдонім для `advanced`). + - `import`: запускає виявлений провайдер міграції, показує попередній план, а потім застосовує його після підтвердження. - Коли вибір автентифікації передбачає бажаного провайдера, початкове налаштування попередньо фільтрує засоби вибору моделі за замовчуванням і allowlist до цього провайдера. Для Volcengine і BytePlus це також охоплює варіанти coding-plan (`volcengine-plan/*`, `byteplus-plan/*`). + Коли варіант автентифікації передбачає бажаного провайдера, налаштування попередньо фільтрує засоби вибору типової моделі та списку дозволених моделей до цього провайдера. Для Volcengine і BytePlus це також охоплює варіанти coding-plan (`volcengine-plan/*`, `byteplus-plan/*`). - Якщо фільтр бажаного провайдера ще не дає жодної завантаженої моделі, початкове налаштування повертається до нефільтрованого каталогу замість того, щоб залишати засіб вибору порожнім. + Якщо фільтр бажаного провайдера ще не дає жодної завантаженої моделі, налаштування повертається до нефільтрованого каталогу, а не залишає засіб вибору порожнім. Деякі провайдери вебпошуку запускають додаткові запити, специфічні для провайдера: - **Grok** може запропонувати необов’язкове налаштування `x_search` з тим самим `XAI_API_KEY` і вибором моделі `x_search`. - - **Kimi** може запитати регіон Moonshot API (`api.moonshot.ai` чи `api.moonshot.cn`) і модель вебпошуку Kimi за замовчуванням. + - **Kimi** може запитати регіон Moonshot API (`api.moonshot.ai` чи `api.moonshot.cn`) і типову модель вебпошуку Kimi. - - - Поведінка області DM під час локального початкового налаштування: [Довідник налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals). - - Найшвидший спосіб почати перший чат: `openclaw dashboard` (Control UI, без налаштування каналів). - - Власний провайдер: підключення до будь-якої сумісної кінцевої точки OpenAI або Anthropic, зокрема розміщених провайдерів, яких немає в списку. Використовуйте Unknown для автоматичного визначення. + + - Поведінка області DM під час локального налаштування: [Довідник із налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals). + - Найшвидший шлях до першого чату: `openclaw dashboard` (Control UI, без налаштування каналу). + - Користувацький провайдер: підключайте будь-яку кінцеву точку, сумісну з OpenAI або Anthropic, включно з розміщеними провайдерами, яких немає в списку. Використовуйте Unknown для автоматичного визначення. + - Якщо виявлено стан Hermes, налаштування запропонує процес міграції. Використовуйте [Migrate](/uk/cli/migrate) для планів dry-run, режиму перезапису, звітів і точних відповідностей. diff --git a/docs/uk/cli/setup.md b/docs/uk/cli/setup.md index dff8a25d0..3b331939f 100644 --- a/docs/uk/cli/setup.md +++ b/docs/uk/cli/setup.md @@ -2,22 +2,22 @@ read_when: - Ви виконуєте початкове налаштування без повного онбордингу CLI - Ви хочете встановити типовий шлях до робочого простору -summary: Довідка CLI для `openclaw setup` (ініціалізація конфігурації + робочого простору) +summary: Довідник CLI для `openclaw setup` (ініціалізація конфігурації та робочого простору) title: Налаштування x-i18n: - generated_at: "2026-04-24T04:12:58Z" + generated_at: "2026-04-27T08:07:52Z" model: gpt-5.4 provider: openai - source_hash: 650b0faf99ef1bc24ec6514661093a9a2ba7edead2e2622b863d51553c44f267 + source_hash: 68e5c07a6b1769420c2125677f3eda9bd4841c938b4fc62583c5bed2a2596250 source_path: cli/setup.md workflow: 15 --- # `openclaw setup` -Ініціалізуйте `~/.openclaw/openclaw.json` і робочий простір агента. +Ініціалізує `~/.openclaw/openclaw.json` і робочий простір агента. -Пов’язане: +Пов’язано: - Початок роботи: [Початок роботи](/uk/start/getting-started) - Онбординг CLI: [Онбординг (CLI)](/uk/start/wizard) @@ -28,6 +28,7 @@ x-i18n: openclaw setup openclaw setup --workspace ~/.openclaw/workspace openclaw setup --wizard +openclaw setup --wizard --import-from hermes --import-source ~/.hermes openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token ``` @@ -37,6 +38,9 @@ openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:1 - `--wizard`: запустити онбординг - `--non-interactive`: запустити онбординг без запитів - `--mode `: режим онбордингу +- `--import-from `: провайдер міграції, який слід запустити під час онбордингу +- `--import-source `: вихідний домашній каталог агента для `--import-from` +- `--import-secrets`: імпортувати підтримувані секрети під час міграції в онбордингу - `--remote-url `: URL WebSocket віддаленого Gateway - `--remote-token `: токен віддаленого Gateway @@ -48,10 +52,11 @@ openclaw setup --wizard Примітки: -- Звичайний `openclaw setup` ініціалізує конфігурацію + робочий простір без повного потоку онбордингу. -- Онбординг запускається автоматично, коли присутні будь-які прапорці онбордингу (`--wizard`, `--non-interactive`, `--mode`, `--remote-url`, `--remote-token`). +- Звичайний `openclaw setup` ініціалізує конфігурацію та робочий простір без повного процесу онбордингу. +- Онбординг запускається автоматично, якщо присутні будь-які прапорці онбордингу (`--wizard`, `--non-interactive`, `--mode`, `--import-from`, `--import-source`, `--import-secrets`, `--remote-url`, `--remote-token`). +- Якщо виявлено стан Hermes, інтерактивний онбординг може автоматично запропонувати міграцію. Онбординг імпорту потребує нового налаштування; використовуйте [Міграція](/uk/cli/migrate) для планів dry-run, резервних копій і режиму перезапису поза межами онбордингу. -## Пов’язане +## Пов’язано -- [Довідка CLI](/uk/cli) +- [Довідник CLI](/uk/cli) - [Огляд встановлення](/uk/install) diff --git a/docs/uk/gateway/local-models.md b/docs/uk/gateway/local-models.md index 7f9887553..f432618f9 100644 --- a/docs/uk/gateway/local-models.md +++ b/docs/uk/gateway/local-models.md @@ -1,26 +1,26 @@ --- read_when: - - Ви хочете обслуговувати моделі зі свого власного GPU-сервера - - Ви налаштовуєте LM Studio або сумісний з OpenAI proxy - - Вам потрібні найбезпечніші рекомендації щодо локальних моделей -summary: Запуск OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, користувацькі OpenAI endpoint-и) + - Ви хочете обслуговувати моделі з власного GPU-сервера + - Ви налаштовуєте LM Studio або проксі, сумісний з OpenAI + - Вам потрібні найнадійніші рекомендації щодо локальних моделей +summary: Запустіть OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, власні кінцеві точки OpenAI) title: Локальні моделі x-i18n: - generated_at: "2026-04-27T06:25:14Z" + generated_at: "2026-04-27T08:07:53Z" model: gpt-5.4 provider: openai - source_hash: 1fe9f5f7e3fc4f5660769fddef1f524b303d309f77551880cd74f3395286816c + source_hash: 4a42076e542448018eaf8633c18dfd290c822be502d78a135d03d138e9713668 source_path: gateway/local-models.md workflow: 15 --- -Локальний запуск можливий, але OpenClaw очікує великий контекст і сильний захист від prompt injection. Невеликі карти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 повністю укомплектовані Mac Studio або еквівалентний GPU-стенд (~$30k+)**. Одна GPU на **24 GB** підходить лише для легших промптів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який ви можете запустити**; агресивно квантизовані або «малі» checkpoints підвищують ризик prompt injection (див. [Безпека](/uk/gateway/security)). +Локальний запуск можливий, але OpenClaw очікує великий контекст + сильний захист від інʼєкцій у підказки. Малі карти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 Mac Studio з максимальною конфігурацією або еквівалентна GPU-установка (~$30k+)**. Одна GPU на **24 GB** підходить лише для легших підказок із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “small” чекпойнти підвищують ризик інʼєкцій у підказки (див. [Security](/uk/gateway/security)). -Якщо вам потрібне найпростіше локальне налаштування, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) та `openclaw onboard`. Ця сторінка — практичний посібник для потужніших локальних стеків і користувацьких локальних серверів, сумісних з OpenAI. +Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — це практичний посібник для продуктивніших локальних стеків і власних локальних серверів, сумісних з OpenAI. ## Рекомендовано: LM Studio + велика локальна модель (Responses API) -Найкращий поточний локальний стек. Завантажте велику модель у LM Studio (наприклад, повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово `http://127.0.0.1:1234`) і використовуйте Responses API, щоб тримати міркування окремо від фінального тексту. +Найкращий поточний локальний стек. Завантажте велику модель у LM Studio (наприклад, повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово `http://127.0.0.1:1234`) і використовуйте Responses API, щоб відокремити міркування від фінального тексту. ```json5 { @@ -60,15 +60,15 @@ x-i18n: **Контрольний список налаштування** - Встановіть LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте «малих»/сильно квантизованих варіантів), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` показує її. -- Замініть `my-local-model` на фактичний ID моделі, показаний у LM Studio. +- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small” / сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` її показує. +- Замініть `my-local-model` на фактичний ідентифікатор моделі, показаний у LM Studio. - Тримайте модель завантаженою; холодне завантаження додає затримку запуску. - Скоригуйте `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється. - Для WhatsApp дотримуйтеся Responses API, щоб надсилався лише фінальний текст. -Тримайте хостингові моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб запасні варіанти лишалися доступними. +Навіть під час локального запуску залишайте налаштованими хостовані моделі; використовуйте `models.mode: "merge"`, щоб резервні варіанти залишалися доступними. -### Гібридна конфігурація: хостингова primary, локальна fallback +### Гібридна конфігурація: хостована основна модель, локальна резервна ```json5 { @@ -109,18 +109,18 @@ x-i18n: } ``` -### Спочатку локально, із хостинговою страховкою +### Спочатку локально, із хостованим запасним варіантом -Поміняйте місцями порядок primary і fallback; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було перейти на Sonnet або Opus, коли локальний сервер недоступний. +Поміняйте місцями основну модель і порядок резервних; залиште той самий блок providers і `models.mode: "merge"`, щоб мати змогу переключитися на Sonnet або Opus, коли локальний сервер недоступний. ### Регіональний хостинг / маршрутизація даних -- Хостингові варіанти MiniMax/Kimi/GLM також існують в OpenRouter з endpoint-ами, прив’язаними до регіону (наприклад, розміщеними в США). Виберіть там регіональний варіант, щоб зберігати трафік у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для fallback на Anthropic/OpenAI. -- Повністю локальний режим лишається найсильнішим варіантом приватності; регіональна хостингова маршрутизація — це компроміс, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних. +- Хостовані варіанти MiniMax/Kimi/GLM також доступні в OpenRouter з кінцевими точками, прив’язаними до регіону (наприклад, хостинг у США). Виберіть там регіональний варіант, щоб трафік залишався у вибраній вами юрисдикції, і водночас використовуйте `models.mode: "merge"` для резервних варіантів Anthropic/OpenAI. +- Лише локальний запуск залишається найсильнішим варіантом щодо приватності; регіональна маршрутизація при хостингу — це компромісний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних. -## Інші локальні proxy, сумісні з OpenAI +## Інші локальні проксі, сумісні з OpenAI -vLLM, LiteLLM, OAI-proxy або користувацькі Gateway працюють, якщо вони надають endpoint `/v1` у стилі OpenAI. Замініть блок provider вище на свій endpoint та ID моделі: +vLLM, LiteLLM, OAI-proxy або власні шлюзи працюють, якщо вони надають кінцеву точку `/v1` у стилі OpenAI. Замініть блок provider вище на свою кінцеву точку та ідентифікатор моделі: ```json5 { @@ -149,33 +149,37 @@ vLLM, LiteLLM, OAI-proxy або користувацькі Gateway працюю } ``` -Залишайте `models.mode: "merge"`, щоб хостингові моделі лишалися доступними як fallback. -Використовуйте `models.providers..timeoutSeconds` для повільних локальних або віддалених серверів моделей перед тим, як збільшувати `agents.defaults.timeoutSeconds`. Таймаут provider застосовується лише до HTTP-запитів до моделі, включно з підключенням, заголовками, потоковою передачею тіла й загальним abort у guarded-fetch. +Залишайте `models.mode: "merge"`, щоб хостовані моделі були доступні як резервні. +Використовуйте `models.providers..timeoutSeconds` для повільних локальних або віддалених серверів моделей, перш ніж збільшувати `agents.defaults.timeoutSeconds`. Тайм-аут провайдера застосовується лише до HTTP-запитів до моделей, включно зі зʼєднанням, заголовками, потоковою передачею тіла відповіді та загальним перериванням guarded-fetch. -Примітка щодо поведінки локальних/proxy `/v1` backend-ів: +Примітка щодо поведінки для локальних / проксійованих бекендів `/v1`: -- OpenClaw обробляє їх як proxy-маршрути, сумісні з OpenAI, а не як нативні endpoint-и OpenAI -- нативне формування запитів лише для OpenAI тут не застосовується: без `service_tier`, без Responses `store`, без формування payload для сумісності reasoning OpenAI і без підказок prompt-cache -- приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) не додаються до цих користувацьких proxy URL +- OpenClaw розглядає їх як проксі-маршрути, сумісні з OpenAI, а не як нативні кінцеві точки OpenAI +- формування запитів, яке застосовується лише до нативного OpenAI, тут не використовується: немає `service_tier`, немає `store` для Responses, немає формування payload для сумісності міркування OpenAI і немає підказок для кешу підказок +- приховані службові заголовки OpenClaw (`originator`, `version`, `User-Agent`) не додаються до цих користувацьких URL проксі -Примітки щодо сумісності для суворіших backend-ів, сумісних з OpenAI: +Примітки щодо сумісності для суворіших бекендів, сумісних з OpenAI: -- Деякі сервери приймають у Chat Completions лише рядковий `messages[].content`, а не структуровані масиви частин контенту. Для таких endpoint-ів установіть `models.providers..models[].compat.requiresStringContent: true`. -- Деякі менші або суворіші локальні backend-и нестабільні з повною формою промпта runtime агента OpenClaw, особливо коли включено схеми інструментів. Якщо backend працює для крихітних прямих викликів `/v1/chat/completions`, але не проходить на звичайних ходах агента OpenClaw, спочатку спробуйте `agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі типові інструменти, як-от `browser`, `cron` і `message`; це експериментальний прапорець, а не стабільне типове налаштування режиму. Див. [Експериментальні можливості](/uk/concepts/experimental-features). Якщо це не допоможе, спробуйте `models.providers..models[].compat.supportsTools: false`. -- Якщо backend усе ще не працює лише на більших запусках OpenClaw, то решта проблеми зазвичай полягає у потужності моделі/сервера на боці upstream або в помилці backend-а, а не в транспортному шарі OpenClaw. +- Деякі сервери приймають у Chat Completions лише рядковий `messages[].content`, а не структуровані масиви частин контенту. Для таких кінцевих точок установіть `models.providers..models[].compat.requiresStringContent: true`. +- Деякі локальні моделі виводять окремі запити до інструментів у дужках як текст, наприклад `[tool_name]`, далі JSON і `[END_TOOL_REQUEST]`. OpenClaw перетворює їх на справжні виклики інструментів лише тоді, коли назва точно збігається з зареєстрованим інструментом для цього ходу; інакше блок вважається непідтримуваним текстом і приховується з видимих для користувача відповідей. +- Деякі менші або суворіші локальні бекенди нестабільно працюють із повною формою підказки runtime агента OpenClaw, особливо коли включені схеми інструментів. Якщо бекенд працює для крихітних прямих викликів `/v1/chat/completions`, але не працює у звичайних ходах агента OpenClaw, спочатку спробуйте `agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі типові інструменти на кшталт `browser`, `cron` і `message`; це експериментальний прапорець, а не стабільне налаштування режиму за замовчуванням. Див. [Experimental Features](/uk/concepts/experimental-features). Якщо це не допоможе, спробуйте `models.providers..models[].compat.supportsTools: false`. +- Якщо бекенд усе ще не працює лише на більших запусках OpenClaw, то проблема зазвичай полягає у можливостях моделі/сервера на боці апстриму або в помилці бекенда, а не в транспортному шарі OpenClaw. -## Усунення несправностей +## Усунення проблем -- Gateway може дістатися до proxy? `curl http://127.0.0.1:1234/v1/models`. -- Модель LM Studio вивантажена? Завантажте знову; холодний старт — поширена причина «зависання». -- OpenClaw попереджає, коли виявлене вікно контексту менше за **32k**, і блокує роботу нижче **16k**. Якщо ви натрапили на цей preflight, збільште ліміт контексту сервера/моделі або виберіть більшу модель. -- Помилки контексту? Зменште `contextWindow` або збільште ліміт вашого сервера. +- Gateway може дістатися до проксі? `curl http://127.0.0.1:1234/v1/models`. +- Модель LM Studio вивантажена? Завантажте її знову; холодний старт — часта причина “зависання”. +- OpenClaw попереджає, коли виявлене вікно контексту менше за **32k**, і блокує запуск, якщо воно менше за **16k**. Якщо ви впираєтеся в цю попередню перевірку, збільште ліміт контексту сервера/моделі або виберіть більшу модель. +- Помилки контексту? Зменште `contextWindow` або збільшіть ліміт сервера. - Сервер, сумісний з OpenAI, повертає `messages[].content ... expected a string`? - Додайте `compat.requiresStringContent: true` у запис цієї моделі. -- Прямі маленькі виклики `/v1/chat/completions` працюють, але `openclaw infer model run` падає на Gemma або іншій локальній моделі? Спочатку вимкніть схеми інструментів через `compat.supportsTools: false`, а потім перевірте знову. Якщо сервер усе ще падає лише на більших промптах OpenClaw, вважайте це обмеженням моделі/сервера на боці upstream. -- Безпека: локальні моделі обходять фільтри провайдера; тримайте агентів вузькоспрямованими, а Compaction увімкненим, щоб обмежити радіус ураження prompt injection. + Додайте `compat.requiresStringContent: true` до цього запису моделі. +- Прямі крихітні виклики `/v1/chat/completions` працюють, але `openclaw infer model run` + не працює на Gemma або іншій локальній моделі? Спочатку вимкніть схеми інструментів через + `compat.supportsTools: false`, а потім перевірте знову. Якщо сервер і далі аварійно завершується лише + на більших підказках OpenClaw, вважайте це обмеженням сервера/моделі на боці апстриму. +- Безпека: локальні моделі оминають фільтри на боці провайдера; звужуйте агентів і тримайте увімкненим Compaction, щоб обмежити радіус ураження від інʼєкцій у підказки. ## Пов’язане - [Довідник із конфігурації](/uk/gateway/configuration-reference) -- [Перемикання моделей при збої](/uk/concepts/model-failover) +- [Відмовостійкість моделей](/uk/concepts/model-failover) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 50a17f821..ee266e15f 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,21 +3,20 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір тестування: модульні/e2e/live набори, Docker runners і те, що покриває кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-27T06:26:01Z" + generated_at: "2026-04-27T08:07:56Z" model: gpt-5.4 provider: openai - source_hash: bcd7c0413e52f11486ffd06a6fb4d25f12ca79fb605fec114076a179b01f6c42 + source_hash: dfc4d1044ddaf1adfdcdde4f018156d36d5874f9be507a53bdc637dc3a772f2f source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір -Docker runners. Цей документ — це посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває). +- Що охоплює кожен набір (і чого він навмисно _не_ охоплює). - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. - Як додавати регресійні тести для реальних проблем моделей/провайдерів. @@ -26,149 +25,149 @@ Docker runners. Цей документ — це посібник «як ми т У більшості випадків: -- Повна перевірка (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Повний набір перевірок (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Під час ітерації над однією помилкою спочатку надавайте перевагу цільовим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- QA-прохід на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете більшої впевненості: - Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): -- Live-набір (моделі + probes інструментів/зображень gateway): `pnpm test:live` +- Набір live (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` - Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker-обхід live-моделей: `pnpm test:docker:live-models` - - Для кожної вибраної моделі тепер запускається текстовий хід плюс невеликий probe у стилі читання файлу. - Моделі, у чиїх метаданих заявлено вхід `image`, також запускають невеликий хід із зображенням. - Вимкніть додаткові probes через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Docker-прогін live-моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку в стилі читання файла. + Моделі, чиї метадані вказують вхід `image`, також виконують маленький хід із зображенням. + Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають багаторазово використовуваний workflow live/E2E з - `include_live_suites: true`, що включає окремі Docker live model - matrix jobs, розбиті за провайдерами. + `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з + `include_live_suites: true`, який включає окремі матричні завдання Docker live model, + поділені за провайдерами. - Для цільових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів у `scripts/ci-hydrate-live-auth.sh` - плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - виклики зі schedule/release. -- Нативний smoke bound-chat Codex: `pnpm test:docker:live-codex-bind` - - Запускає Docker live lane проти шляху app-server Codex, прив’язує синтетичний - Slack DM через `/codex bind`, перевіряє `/codex fast` і - `/codex permissions`, а потім підтверджує, що звичайна відповідь і вкладення-зображення - проходять через нативну прив’язку Plugin, а не через ACP. -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` - - Проганяє ходи агента gateway через harness app-server Codex, що належить Plugin, - перевіряє `/codex status` і `/codex models`, а за замовчуванням перевіряє probes для image, - Cron MCP, sub-agent і Guardian. Вимкніть probe sub-agent через - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої - app-server Codex. Для цільової перевірки sub-agent вимкніть інші probes: + - Додавайте нові high-signal секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + запланованих/release-викликів. +- Перевірка native Codex bound-chat: `pnpm test:docker:live-codex-bind` + - Запускає Docker live-прохід проти шляху Codex app-server, прив’язує синтетичний + Slack DM через `/codex bind`, виконує `/codex fast` і + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення + із зображенням проходять через native Plugin binding замість ACP. +- Перевірка Codex app-server harness: `pnpm test:docker:live-codex-harness` + - Запускає ходи агента Gateway через harness app-server Codex, що належить Plugin, + перевіряє `/codex status` і `/codex models`, а також за замовчуванням виконує перевірки image, + cron MCP, sub-agent і Guardian. Вимкніть перевірку sub-agent через + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої app-server Codex. + Для цільової перевірки sub-agent вимкніть інші перевірки: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Це завершується після probe sub-agent, якщо тільки - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` не встановлено. -- Smoke команди rescue Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Додаткова opt-in перевірка belt-and-suspenders для поверхні команди rescue message-channel. - Вона перевіряє `/crestodian status`, ставить у чергу постійну - зміну моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. -- Docker smoke planner Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у container без конфігурації з фальшивим Claude CLI у `PATH` - і перевіряє, що резервний fuzzy planner перетворюється на типізований запис конфігурації з audit. -- Docker smoke першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` - - Запускається з порожнього каталогу стану OpenClaw, маршрутизує голий `openclaw` до - Crestodian, застосовує записи setup/model/agent/Discord plugin + SecretRef, - перевіряє конфігурацію та записи аудиту. Той самий шлях налаштування Ring 0 + Це завершується після перевірки sub-agent, якщо тільки не встановлено + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. +- Перевірка rescue-команди Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Додаткова opt-in перевірка з підвищеною надійністю для поверхні rescue-команди каналу повідомлень. + Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі, + відповідає `/crestodian yes` і перевіряє шлях запису audit/config. +- Docker-перевірка planner Crestodian: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` + і перевіряє, що fallback нечіткого planner перетворюється на аудійований типізований запис у конфігурацію. +- Docker-перевірка першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` + - Запускається з порожнього каталогу стану OpenClaw, маршрутизує простий `openclaw` до + Crestodian, застосовує записи setup/model/agent/Discord Plugin + SecretRef, + валідує конфігурацію та перевіряє записи аудиту. Той самий шлях налаштування Ring 0 також покривається в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Smoke cost Moonshot/Kimi: якщо задано `MOONSHOT_API_KEY`, запустіть +- Перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте `openclaw models list --provider moonshot --json`, а потім ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON звітує Moonshot/K2.6, а - транскрипт помічника зберігає нормалізований `usage.cost`. + проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що + транскрипт помічника зберігає нормалізоване `usage.cost`. -Коли вам потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через allowlist env vars, описані нижче. +Коли вам потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## Runners для QA +## Спеціалізовані QA-ранери Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflows. `Parity gate` запускається для відповідних PR -і з ручного запуску з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного запуску з mock parity gate, live lane Matrix, -live lane Telegram під керуванням Convex і live lane Discord під керуванням Convex як -паралельні jobs. Заплановані QA та перевірки release явно передають Matrix `--profile fast`, -тоді як Matrix CLI і типовий ручний вхід workflow залишаються `all`; ручний запуск може розбивати `all` на jobs `transport`, `media`, `e2ee-smoke`, +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і +з ручного виклику з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного виклику з mock parity gate, live Matrix lane, +live Telegram lane під керуванням Convex і live Discord lane під керуванням Convex як +паралельні завдання. Заплановані QA і release-перевірки явно передають Matrix `--profile fast`, +тоді як CLI Matrix і значення ручного вводу workflow за замовчуванням залишаються `all`; +ручний виклик може розбивати `all` на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс -швидкі lanes Matrix і Telegram перед схваленням release. +швидкі проходи Matrix і Telegram перед затвердженням release. - `pnpm openclaw qa suite` - - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - Запускає сценарії QA з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - gateway workers. `qa-channel` типово має concurrency 4 (обмежене - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість workers, або `--concurrency 1` для старого послідовного lane. - - Завершується з ненульовим кодом, якщо хоч один сценарій завершується помилкою. Використовуйте `--allow-failures`, коли + працівниками Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежено + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість + працівників, або `--concurrency 1` для старішого послідовного проходу. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний AIMock-backed сервер провайдера для експериментального - покриття фікстур і mock протоколу без заміни lane `mock-openai`, - обізнаного про сценарії. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття fixture і protocol-mock без заміни сценарно-орієнтованого проходу `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий набір QA у тимчасовій Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані вхідні дані автентифікації QA, які практичні для guest: + - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для гостьової системи: ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через - змонтований робочий простір. - - Записує звичайний QA report + summary плюс логи Multipass у + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + змонтований workspace. + - Записує звичайний звіт і підсумок QA, а також журнали Multipass до `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в стилі operator. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball з поточної checkout, глобально встановлює його в - Docker, запускає неінтерактивний онбординг OpenAI API key, типово налаштовує Telegram, - перевіряє, що ввімкнення Plugin за потреби встановлює runtime dependencies, - запускає doctor і один локальний хід агента проти mocked endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane - packaged-install з Discord. + - Збирає npm tarball з поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивне онбординг-налаштування ключа OpenAI API, налаштовує Telegram + за замовчуванням, перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, + запускає doctor і виконує один локальний хід агента проти змоканого OpenAI endpoint. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий + packaged-install прохід з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає детермінований Docker smoke built-app для transcript вбудованого runtime context. - Він перевіряє, що прихований runtime context OpenClaw зберігається як - недемонстроване custom message, а не витікає у видимий хід користувача, - потім засіває пошкоджений session JSONL і перевіряє, що + - Запускає детерміновану Docker-перевірку built-app для вбудованих транскриптів runtime context. + Вона перевіряє, що прихований runtime context OpenClaw зберігається як + користувацьке повідомлення, яке не відображається, замість витоку у видимий хід користувача, + а потім підкладає пошкоджений JSONL сеансу та перевіряє, що `openclaw doctor --fix` переписує його в активну гілку з резервною копією. - `pnpm test:docker:npm-telegram-live` - - Встановлює кандидат пакета OpenClaw у Docker, запускає онбординг - встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує - live QA lane Telegram з цим встановленим пакетом як Gateway SUT. - - Типово використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; задайте + - Встановлює пакет-кандидат OpenClaw у Docker, виконує онбординг встановленого пакета, + налаштовує Telegram через встановлений CLI, а потім повторно використовує + live Telegram QA lane з цим встановленим пакетом як Gateway SUT. + - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або - `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб протестувати визначений локальний tarball замість + `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати визначений локальний tarball замість встановлення з реєстру. - - Використовує ті самі облікові дані Telegram через env або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/release задайте - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, - Docker wrapper автоматично вибирає Convex. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний - `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - - GitHub Actions також надає цей lane як ручний workflow для супроводу - `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує - середовище `qa-live-shared` і оренду облікових даних Convex CI. + - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й + `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`, а також + `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо + `OPENCLAW_QA_CONVEX_SITE_URL` і рольовий секрет Convex присутні в CI, + Docker-обгортка автоматично вибирає Convex. + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільне + `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього проходу. + - GitHub Actions також надає цей прохід як ручний workflow для maintainer: + `NPM Telegram Beta E2E`. Він не запускається при merge. Workflow використовує + середовище `qa-live-shared` і оренду CI-облікових даних Convex. - GitHub Actions також надає `Package Acceptance` для побічного продуктового підтвердження - проти одного кандидата пакета. Він приймає довірений ref, опублікований npm spec, - HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого запуску, завантажує + щодо одного пакета-кандидата. Він приймає довірений ref, опубліковану npm-специфікацію, + URL HTTPS tarball плюс SHA-256 або артефакт tarball з іншого запуску, завантажує нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає - наявний Docker E2E scheduler з профілями lane smoke, package, product, full або custom. Задайте `telegram_mode=mock-openai` або `live-frontier`, щоб запустити - workflow Telegram QA проти того самого artifact `package-under-test`. + наявний Docker E2E scheduler з профілями проходів smoke, package, product, full або custom. + Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити Telegram QA workflow + проти того самого артефакту `package-under-test`. - Підтвердження продукту для останньої beta: ```bash @@ -179,7 +178,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Підтвердження точної tarball URL вимагає digest: +- Підтвердження через точний URL tarball вимагає digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -189,7 +188,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Підтвердження artifact завантажує tarball artifact з іншого запуску Actions: +- Підтвердження через артефакт завантажує артефакт tarball з іншого запуску Actions: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -200,106 +199,108 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані канали/Plugins через + - Пакує й установлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає неналаштовані runtime dependencies Plugin - відсутніми, що перший налаштований запуск Gateway або doctor встановлює runtime dependencies - кожного вбудованого Plugin на вимогу, і що другий перезапуск не - перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском + - Перевіряє, що виявлення setup залишає невстановленими runtime-залежності + непідключених Plugin, що перший налаштований запуск Gateway або doctor + встановлює runtime-залежності кожного bundled Plugin за потреби, і що + повторний перезапуск не перевстановлює залежності, які вже були активовані. + - Також установлює відому старішу базову версію npm, вмикає Telegram перед запуском `openclaw update --tag `, а потім перевіряє, що - post-update doctor кандидата відновлює runtime dependencies вбудованих каналів без - postinstall repair на боці harness. + post-update doctor у версії-кандидаті відновлює runtime-залежності bundled channel без + postinstall-відновлення з боку harness. - `pnpm test:parallels:npm-update` - - Запускає нативний smoke оновлення встановленого пакета в Parallels guests. Кожна + - Запускає native packaged-install update smoke у гостьових системах Parallels. Кожна вибрана платформа спочатку встановлює запитаний базовий пакет, потім виконує - встановлену команду `openclaw update` у тому самому guest і перевіряє встановлену - версію, стан оновлення, готовність gateway і один локальний хід агента. - - Під час ітерації на одному guest використовуйте `--platform macos`, `--platform windows` або `--platform linux`. - Використовуйте `--json` для шляху до summary artifact і - статусу кожного lane. - - За замовчуванням lane OpenAI використовує `openai/gpt-5.5` для підтвердження live agent-turn. - Передайте `--model ` або задайте - `OPENCLAW_PARALLELS_OPENAI_MODEL`, коли навмисно перевіряєте іншу + встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє + встановлену версію, статус оновлення, готовність gateway і один локальний + хід агента. + - Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час + ітерації над однією гостьовою системою. Використовуйте `--json` для шляху до підсумкового артефакту та + статусу кожного проходу. + - За замовчуванням прохід OpenAI використовує `openai/gpt-5.5` для підтвердження live agent-turn. + Передайте `--model ` або встановіть + `OPENCLAW_PARALLELS_OPENAI_MODEL`, якщо навмисно перевіряєте іншу модель OpenAI. - - Обгортайте довгі локальні запуски в host timeout, щоб збої транспорту Parallels - не поглинули решту вікна тестування: + - Обгортайте довгі локальні запуски в host timeout, щоб зависання транспорту Parallels не + забирало решту тестового вікна: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені логи lane в `/tmp/openclaw-parallels-npm-update.*`. + - Скрипт записує вкладені журнали проходів у `/tmp/openclaw-parallels-npm-update.*`. Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, перш ніж вважати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати від 10 до 15 хвилин на post-update doctor/runtime - dependency repair на холодному guest; це все ще нормальний стан, якщо вкладений + - На Windows update може витрачати від 10 до 15 хвилин на post-update doctor/runtime + dependency repair у холодній гостьовій системі; це все ще вважається нормальним, якщо вкладений npm debug log продовжує оновлюватися. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke lanes Parallels + - Не запускайте цю агреговану обгортку паралельно з окремими smoke-проходами Parallels для macOS, Windows або Linux. Вони використовують спільний стан VM і можуть конфліктувати під час відновлення snapshot, видачі пакета або стану guest gateway. - - Підтвердження після оновлення запускає звичайну поверхню вбудованого Plugin, оскільки - фасади можливостей, такі як speech, генерація зображень і - розуміння медіа, завантажуються через вбудовані runtime API, навіть якщо сам - хід агента перевіряє лише просту текстову відповідь. + - Post-update підтвердження запускає звичайну поверхню bundled Plugin, тому що + capability facades, як-от speech, image generation і media + understanding, завантажуються через bundled runtime API, навіть якщо сам + agent turn перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого protocol smoke + testing. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA host наразі призначений лише для repo/dev. Встановлені пакети OpenClaw не постачають - `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout репозиторію завантажують вбудований runner безпосередньо; окремий крок + - Запускає Matrix live QA lane проти тимчасового homeserver Tuwunel на базі Docker. + - Цей QA host наразі призначений лише для repo/dev. У packaged OpenClaw installs не постачається + `qa-lab`, тож вони не надають `openclaw qa`. + - Checkout репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення Plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Plugin Matrix як транспортом SUT. - - За замовчуванням використовує `--profile all`. Використовуйте `--profile fast --fail-fast` для transport proof, критичного для release, або `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` для шардингу повного каталогу. - - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює тимчасових користувачів. - - Записує QA report Matrix, summary, artifact observed-events і комбінований stdout/stderr log в `.artifacts/qa-e2e/...`. - - За замовчуванням показує прогрес і застосовує жорсткий timeout виконання через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` налаштовує негативні тихі вікна no-reply, а очищення обмежується через `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, причому збої містять команду відновлення `docker compose ... down --remove-orphans`. + - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Matrix Plugin як транспортом SUT. + - За замовчуванням використовується `--profile all`. Використовуйте `--profile fast --fail-fast` для критично важливого transport proof перед release або `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` під час шардування повного каталогу. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки цей прохід локально створює тимчасових користувачів. + - Записує звіт Matrix QA, підсумок, артефакт observed-events і об’єднаний журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - За замовчуванням виводить поступ виконання та примусово застосовує жорсткий timeout запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` налаштовує негативні quiet window для відсутності відповіді, а cleanup обмежується через `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`; у разі збоїв також виводиться команда відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи з використанням токенів bot driver і SUT з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. - - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли + - Запускає Telegram live QA lane проти реальної приватної групи з токенами ботів driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів у тій самій приватній групі, причому бот SUT має надавати username Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати бот-трафік у групі. - - Записує QA report Telegram, summary і artifact observed-messages в `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. -Live transport lanes використовують один стандартний контракт, щоб нові транспорти не відхилялися: +Live transport lanes використовують єдиний стандартний контракт, щоб нові транспорти не відхилялися від нього: -`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. +`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live transport. -| Lane | Канарейка | Обмеження згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в треді | Ізоляція треду | Спостереження реакцій | Команда help | Реєстрація нативних команд | -| -------- | --------- | ------------------ | -------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | --------------------- | ------------ | -------------------------- | -| Matrix | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | | | | | | | x | | -| Discord | x | x | | | | | | | | x | +| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | Native command registration | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- | +| Matrix | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | | | | | | | x | | +| Discord | x | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на базі Convex, підтримує Heartbeat -цієї оренди, поки lane виконується, і звільняє її під час завершення роботи. +QA lab отримує ексклюзивну lease із пулу на базі Convex, надсилає Heartbeat +для цієї lease під час виконання проходу та звільняє lease під час завершення роботи. -Еталонний каркас проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env vars: +Обов’язкові змінні середовища: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI типово `ci`, інакше `maintainer`) -Необов’язкові env vars: +Необов’язкові змінні середовища: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -309,12 +310,12 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. -У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди maintainer (додавання/видалення/перелік пулу) потребують +Команди адміністрування maintainer (додавання/видалення/список пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainer: +Допоміжні CLI-команди для maintainer: ```bash pnpm openclaw qa credentials doctor @@ -325,10 +326,9 @@ pnpm openclaw qa credentials remove --credential-id Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker, префікс endpoint, HTTP timeout і доступність admin/list без виведення -значень секретів. Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI -утилітах. +значень секретів. Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. -Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -346,7 +346,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -354,60 +354,60 @@ pnpm openclaw qa credentials remove --credential-id Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком числового ідентифікатора чату Telegram. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. +- `groupId` має бути рядком із числовим Telegram chat id. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. ### Додавання каналу до QA Додавання каналу до markdown-системи QA потребує рівно двох речей: -1. Адаптер транспорту для каналу. -2. Набір сценаріїв, який перевіряє контракт каналу. +1. Транспортного адаптера для каналу. +2. Пакета сценаріїв, що перевіряє контракт каналу. -Не додавайте новий кореневий рівень команди QA, якщо спільний хост `qa-lab` може -керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` +може керувати цим потоком. -`qa-lab` відповідає за спільні механізми хоста: +`qa-lab` володіє спільною механікою хоста: -- корінь команди `openclaw qa` -- запуск і завершення набору -- паралелізм workers -- запис артефактів -- генерацію звітів -- виконання сценаріїв +- коренем команди `openclaw qa` +- запуском і завершенням набору +- concurrency працівників +- записом артефактів +- генерацією звітів +- виконанням сценаріїв - alias сумісності для старіших сценаріїв `qa-channel` -Runner Plugins відповідають за контракт транспорту: +Runner plugins володіють транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` -- як gateway налаштовується для цього транспорту +- як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як вставляються вхідні події +- як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як відкриваються транскрипти та нормалізований стан транспорту -- як виконуються дії, підкріплені транспортом -- як обробляється специфічне для транспорту скидання або очищення +- як надаються транскрипти й нормалізований стан транспорту +- як виконуються дії на базі транспорту +- як обробляються reset або cleanup, специфічні для транспорту -Мінімальний поріг інтеграції для нового каналу такий: +Мінімальний поріг інтеграції для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Утримуйте специфічні для транспорту механізми всередині runner Plugin або harness каналу. -4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner Plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoints. +2. Реалізуйте transport runner на спільному host seam `qa-lab`. +3. Залишайте транспортно-специфічну механіку всередині runner plugin або channel harness. +4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI та runner має залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Для нових сценаріїв використовуйте узагальнені helpers сценаріїв. +6. Використовуйте загальні допоміжні засоби сценаріїв для нових сценаріїв. 7. Зберігайте роботу наявних alias сумісності, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішення є суворим: +Правило ухвалення рішення суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспортного каналу, залишайте її в цьому runner Plugin або harness Plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте узагальнений helper замість специфічної для каналу гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно позначайте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного channel transport, залишайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку може використати більш ніж один канал, додавайте загальний helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію. -Рекомендовані назви узагальнених helpers для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -422,7 +422,7 @@ Runner Plugins відповідають за контракт транспорт - `formatTransportTranscript` - `resetTransport` -Для наявних сценаріїв aliases сумісності залишаються доступними, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -430,70 +430,69 @@ Runner Plugins відповідають за контракт транспорт - `formatConversationTranscript` - `resetBus` -Для нової роботи з каналами слід використовувати узагальнені назви helpers. -Aliases сумісності існують, щоб уникнути міграції за принципом flag day, а не як модель для +Нова робота над каналами має використовувати загальні назви helper. +Alias сумісності існують, щоб уникнути міграції в стилі flag day, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «щораз реалістичніші» (і щораз менш стабільні/дорожчі): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): -### Unit / integration (за замовчуванням) +### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: ненаправлені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації для кожного проєкту для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Конфігурація: ненаправлені запуски використовують набір шардованих конфігурацій `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в конфігурації на рівні окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; UI unit-тести запускаються в окремому shard `unit-ui` - Обсяг: - Чисті unit-тести - Внутрішньопроцесні integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - Детерміновані регресії для відомих помилок - Очікування: - - Запускаються в CI + - Запускається в CI - Реальні ключі не потрібні - - Мають бути швидкими й стабільними + - Має бути швидким і стабільним - - Ненаправлений `pnpm test` запускає дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного велетенського нативного root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти непов’язані набори. - - `pnpm test --watch` усе ще використовує нативний граф проєктів root `vitest.config.ts`, тому що цикл спостереження з кількома шардами є непрактичним. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lanes: прямі редагування тестів, сусідні файли `*.test.ts`, явні мапінги вихідного коду та локальні import-graph dependents. Редагування config/setup/package не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` — це звичайний розумний локальний gate перевірки для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для підтвердження тестів викликайте `pnpm test:changed` або явний `pnpm test `. Підвищення версій лише в release metadata запускає цільові перевірки version/config/root-dependency із guard, який відхиляє зміни package поза полем версії верхнього рівня. - - Редагування live Docker ACP harness запускають фокусні перевірки: shell syntax для скриптів live Docker auth і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; редагування dependency, export, version та іншої package-поверхні все ще використовують ширші guards. - - Легкі щодо import unit-тести з agents, commands, plugins, helpers auto-reply, `plugin-sdk` та подібних чистих утилітних ділянок маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються в наявних lanes. - - Вибрані файли вихідного коду helpers `plugin-sdk` і `commands` також маплять запуски в changed-режимі на явні сусідні тести в цих легких lanes, тож редагування helpers не змушують повторно запускати весь важкий набір для цього каталогу. - - `auto-reply` має окремі buckets для helpers верхнього рівня core, integration-тестів верхнього рівня `reply.*` і піддерева `src/auto-reply/reply/**`. Додатково CI розбиває піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один важкий на imports bucket не визначав увесь tail Node. + - Ненаправлені запуски `pnpm test` використовують дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу root-project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати нерелевантні набори. + - `pnpm test --watch` усе ще використовує нативний граф проєктів root `vitest.config.ts`, тому що цикл watch із багатьма шардами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lanes: прямі зміни тестів, сусідні файли `*.test.ts`, явні зіставлення з вихідним кодом і локальні залежні елементи графа імпорту. Зміни config/setup/package не запускають тести широко, якщо ви явно не використовуєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — це звичайний розумний локальний gate перевірки для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає Vitest-тести; для підтвердження тестами викликайте `pnpm test:changed` або явний `pnpm test `. Оновлення версії лише в метаданих release запускають цільові перевірки version/config/root-dependency із guard, який відхиляє зміни package поза полем версії верхнього рівня. + - Редагування harness live Docker ACP запускають сфокусовані перевірки: синтаксис shell для скриптів автентифікації live Docker і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни dependencies, exports, version та інших поверхонь package як і раніше використовують ширші guard. + - Unit-тести з легким імпортом із agents, commands, plugins, helper auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lanes. + - Окремі вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними сусідніми тестами в цих легких lanes, щоб зміни helper не змушували повторно запускати весь важкий набір для цього каталогу. + - `auto-reply` має окремі buckets для top-level core helper, top-level integration-тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково ділить піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один bucket із важким імпортом не контролював увесь хвіст Node. - - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, - зберігайте обидва рівні покриття. - - Додавайте цільові helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте в робочому стані integration-набори embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime context Compaction, зберігайте обидва рівні покриття. + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації та нормалізації. + - Підтримуйте healthy стан integration-наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка Compaction як і раніше проходять + - Ці набори перевіряють, що scoped id і поведінка Compaction як і раніше проходять через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є достатньою заміною для цих integration-шляхів. - + - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner для root projects, e2e і live configs. - - Root UI lane зберігає своє налаштування `jsdom` та optimizer, але теж працює на + неізольований runner у root projects, конфігураціях e2e і live. + - Root UI lane зберігає свій `jsdom` setup та optimizer, але теж працює на спільному неізольованому runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` - зі спільної конфігурації Vitest. + - Кожен shard `pnpm test` успадковує ті самі типові значення + `threads` + `isolate: false` зі спільної конфігурації Vitest. - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. @@ -501,51 +500,52 @@ Aliases сумісності існують, щоб уникнути мігра - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно індексує відформатовані файли і - не запускає lint, typecheck чи тести. - - Перед передачею або push явно запускайте `pnpm check:changed`, коли + - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до staging і + не запускає lint, typecheck або тести. + - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли вам потрібен розумний локальний gate перевірки. - `pnpm test:changed` за замовчуванням маршрутизує через дешеві scoped lanes. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент вирішує, що редагування harness, config, package або contract справді потребує ширшого покриття Vitest. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом workers. - - Автоматичне масштабування локальних workers навмисно консервативне й зменшується, - коли середнє навантаження хоста вже високе, тому кілька паралельних + лише з вищою межею кількості працівників. + - Автоматичне масштабування локальних працівників навмисно консервативне й зменшується, + коли середнє навантаження host уже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в changed-режимі залишалися коректними, коли змінюється wiring тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; задайте `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо вам потрібне - одне явне розташування кешу для прямого профілювання. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, тож повторні запуски в режимі changed залишаються коректними, коли змінюється + wiring тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + host; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість imports плюс - вивід розбивки imports. - - `pnpm test:perf:imports:changed` обмежує той самий профільований вигляд + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту та + вивід деталізації імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими відносно `origin/main`. - - Дані часу shard записуються в `.artifacts/vitest-shard-timings.json`. - Запуски цілої конфігурації використовують шлях config як ключ; CI-шарди з include-pattern - додають назву shard, щоб відфільтровані шарди можна було - відстежувати окремо. - - Коли один гарячий тест усе ще витрачає більшість часу на startup imports, - тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - мокайте цей seam безпосередньо замість глибокого імпорту runtime helpers - лише для того, щоб передати їх через `vi.mock(...)`. + - Дані про час shard записуються в `.artifacts/vitest-shard-timings.json`. + Запуски всієї конфігурації використовують шлях до конфігурації як ключ; шарди CI з include-pattern + додають назву shard, щоб відфільтровані шарди можна було відстежувати + окремо. + - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, + тримайте важкі залежності за вузькою локальною межею `*.runtime.ts` і + напряму мокуйте цю межу замість глибокого імпорту runtime helper лише + для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із нативним шляхом root-project для цього зафіксованого - diff і виводить wall time плюс max RSS на macOS. - - `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, - маршрутизуючи список змінених файлів через + diff і виводить wall time плюс macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного + незакоміченого дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU profile основного потоку для - startup і transform overhead у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для - unit-набору з вимкненим паралелізмом файлів. + - `pnpm test:perf:profile:main` записує CPU profile головного потоку для + старту Vitest/Vite та накладних витрат transform. + - `pnpm test:perf:profile:runner` записує CPU+heap profile runner для + unit-набору з вимкненим файловим паралелізмом. @@ -553,317 +553,317 @@ Aliases сумісності існують, щоб уникнути мігра ### Stability (gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один worker +- Конфігурація: `vitest.gateway.config.ts`, примусово один працівник - Обсяг: - - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Проганяє синтетичний churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - - Опитує `diagnostics.stability` через Gateway WS RPC - - Покриває helpers збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні RSS samples залишаються в межах бюджету тиску, а глибини черг для кожної сесії повертаються до нуля + - Запускає реальний loopback Gateway з diagnostics, увімкненими за замовчуванням + - Проганяє синтетичне churn повідомлень gateway, пам’яті й великих payload через шлях діагностичних подій + - Запитує `diagnostics.stability` через WS RPC Gateway + - Охоплює helper збереження пакета stability diagnostics + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибини черг на рівні сеансу повертаються до нуля - Очікування: - - Безпечний для CI і не потребує ключів - - Вузький lane для подальшої роботи над stability-regressions, а не заміна повного набору Gateway + - Безпечний для CI і без ключів + - Вузький lane для подальшої роботи з регресіями стабільності, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin у `extensions/` -- Типові значення середовища виконання: +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` +- Типові значення runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивних workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на console I/O. + - Використовує адаптивну кількість працівників (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням запускається в silent-режимі, щоб зменшити накладні витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість workers (обмежено 16). + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість працівників (обмеження — 16). - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, сполучення Node і важче мережеве навантаження + - End-to-end поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing Node і важча мережева взаємодія - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: OpenShell backend smoke +### E2E: backend smoke OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований Gateway OpenShell на хості через Docker + - Запускає ізольований Gateway OpenShell на host через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через bridge fs sandbox + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` і SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і справного Docker daemon + - Потребує локального CLI `openshell` і працездатного Docker daemon - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugin у `extensions/` -- Типово: **увімкнено** через `pnpm test:live` (задає `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - «Чи справді цей провайдер/модель працює _сьогодні_ зі справжніми обліковими даними?» - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є CI-стабільним (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits - - Перевагу слід надавати запуску звужених підмножин, а не «всього» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap gateway/Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API keys (специфічно для провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюються у разі відповідей про rate limit. + - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / витрачає rate limit + - Краще запускати звужені підмножини, а не «все» +- Live-запуски джерелять `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує журнали bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні журнали запуску. +- Ротація API-ключів (специфічна для провайдера): встановлюйте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для окремого live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера залишаються помітно активними, навіть коли перехоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. - - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів помітно активні навіть коли перехоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/Gateway транслюються негайно під час live-запусків. + - Налаштовуйте Heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Скористайтеся цією таблицею рішень: +Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтеся мережевого шару gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / виклик інструментів: запускайте звужений `pnpm test:live` +- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Зміни в мережевій взаємодії gateway / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` -## Live-тести (які торкаються мережі) +## Live-тести (з доступом до мережі) -Для live matrix моделей, smoke-тестів CLI backend, ACP smoke, harness app-server Codex -і всіх live-тестів media-provider (Deepgram, BytePlus, ComfyUI, image, +Для матриці live-моделей, smoke-тестів CLI backend, ACP smoke, harness +Codex app-server і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, music, video, media harness) — а також обробки облікових даних для live-запусків — див. -[Тестування — live suites](/uk/help/testing-live). +[Тестування — live-набори](/uk/help/testing-live). -## Docker runners (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві групи: +Ці Docker-ранери поділяються на дві категорії: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл ключа профілю всередині Docker image репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і робочий простір (і використовують `~/.profile`, якщо він змонтований). Відповідні локальні точки входу — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням мають менший ліміт smoke, щоб повний Docker-обхід залишався практичним: - `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і джерелять `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують меншу межу smoke, щоб повний Docker-прогін залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - вам явно потрібне ширше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два image `scripts/e2e/Dockerfile`. Базовий image — це лише runner Node/Git для lanes install/update/plugin-dependency; ці lanes монтують попередньо зібраний tarball. Функціональний image встановлює той самий tarball у `/app` для lanes built-app functionality. Визначення Docker lanes живуть у `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує локальний scheduler з вагами: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як resource caps не дають усім важким lanes live, npm-install і multi-service стартувати одночасно. Якщо один lane важчий за активні caps, scheduler все одно може запустити його, коли пул порожній, а потім триматиме його єдиним, доки знову не з’явиться доступна ємність. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker host має більший запас ресурсів. Runner за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає часи успішних lanes у `.artifacts/docker-tests/lane-timings.json` і використовує ці часи, щоб на наступних запусках стартувати довші lanes першими. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест lane без збирання або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати план CI для вибраних lanes, потреб package/image і облікових даних. -- `Package Acceptance` — це нативний для GitHub gate пакетів на запитання «чи працює цей встановлюваний tarball як продукт?». Він визначає один кандидат пакета з `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає багаторазово використовувані Docker E2E lanes саме проти цього tarball замість повторного пакування вибраного ref. `workflow_ref` вибирає довірені workflow/harness-скрипти, а `package_ref` вибирає вихідний commit/branch/tag для пакування, коли `source=ref`; це дає змогу поточній логіці acceptance перевіряти старі довірені commits. Профілі впорядковані за шириною: `smoke` — це швидкий install/channel/agent плюс gateway/config, `package` — це контракт package/update/plugin і типовий нативний replacement для більшості покриття package/update у Parallels, `product` додає MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI, а `full` запускає Docker chunks шляху release з OpenWebUI. Перевірка release запускає профіль `package` для цільового ref з увімкненим Telegram package QA. Команди цільового повторного запуску GitHub Docker, згенеровані з artifacts, включають попередні package artifact і підготовлені image inputs, коли вони доступні, тож для помилкових lanes можна уникнути повторного збирання package та images. -- Legacy-сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише прогалини метаданих shipped-package: пропущені приватні записи інвентарю QA, відсутній `gateway install --wrapper`, відсутні patch files у git fixture, похідному від tarball, відсутній збережений `update.channel`, застарілі розташування записів встановлення Plugin, відсутнє збереження записів встановлення marketplace і міграцію метаданих конфігурації під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи вважаються жорсткими збоями. -- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли + явно хочете більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ — це лише Node/Git runner для проходів install/update/plugin-dependency; ці проходи монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/app` для проходів built-app functionality. Визначення Docker-проходів розміщені в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким проходам live, npm-install і multi-service запускатися одночасно. Якщо один прохід важчий за активні ліміти, scheduler все одно може запустити його, коли пул порожній, а потім триматиме його єдиним запущеним, доки знову не з’явиться доступна ємність. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-host має більший запас ресурсів. Runner за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає час успішних проходів у `.artifacts/docker-tests/lane-timings.json` і використовує ці дані, щоб у наступних запусках стартувати з довших проходів. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест проходів без збирання або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати план CI для вибраних проходів, потреб package/image і облікових даних. +- `Package Acceptance` — це GitHub-native package gate для питання «чи працює цей інстальований tarball як продукт?». Він визначає один пакет-кандидат із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає повторно використовувані Docker E2E-проходи проти саме цього tarball замість перепаковування вибраного ref. `workflow_ref` вибирає довірені workflow/harness-скрипти, тоді як `package_ref` вибирає вихідний commit/branch/tag для пакування, коли `source=ref`; це дозволяє поточній логіці acceptance перевіряти старіші довірені commit. Профілі впорядковано за широтою: `smoke` — це швидка перевірка install/channel/agent плюс gateway/config, `package` — пакетний/update/plugin contract і типова native-замiна для більшості покриття Parallels package/update, `product` додає MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI, а `full` запускає Docker-chunks release-шляху з OpenWebUI. Перевірка release запускає профіль `package` для цільового ref з увімкненим Telegram package QA. Цільові команди повторного запуску GitHub Docker, згенеровані з артефактів, включають попередній package artifact і підготовлені вхідні дані image, коли вони доступні, тож проходи з помилками можуть уникнути повторного збирання package та image. +- Legacy-сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише пропуски метаданих shipped-package: пропущені записи приватного QA inventory, відсутній `gateway install --wrapper`, відсутні patch-файли у git fixture, похідному від tarball, відсутній збережений `update.channel`, застарілі розташування записів встановлення Plugin, відсутнє збереження запису встановлення marketplace та міграція метаданих конфігурації під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи вважаються суворими помилками. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker runners live-model також bind-mount лише потрібні домівки автентифікації CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи сховище автентифікації хоста: +Docker-ранери live-моделей також bind-mount лише потрібні CLI auth home (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі auth на host: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово покриває Claude, Codex і Gemini, а суворе покриття Droid/OpenCode доступне через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) -- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; за замовчуванням охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Smoke спостережуваності: `pnpm qa:otel:smoke` — це приватний lane QA для перевірки checkout вихідного коду. Його навмисно не включено до Docker lanes release пакета, оскільки npm tarball не містить QA Lab. -- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер онбордингу (TTY, повне створення каркаса): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke онбордингу/каналу/агента з npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref плюс типово Telegram, перевіряє, що doctor відновлює активовані runtime dependencies Plugin, і запускає один mocked хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову хоста через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на package `stable` і перевіряє стан оновлення. -- Smoke runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого transcript runtime context плюс відновлення doctor для уражених дубльованих гілок prompt-rewrite. -- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає вбудовані провайдери image замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збирання хоста через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` використовує спільний npm cache для контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільний baseline перед оновленням до candidate tarball. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`, або через вхід `update_baseline_version` workflow Install Smoke у GitHub. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи cache, створені root, не маскували поведінку локального встановлення користувача. Задайте `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm у локальних повторних запусках. -- Install Smoke у CI пропускає дубльоване глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- CLI smoke видалення agents зі спільним робочим простором: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає root Dockerfile image, засіває двох агентів з одним робочим простором в ізольований container home, запускає `agents delete --json` і перевіряє коректний JSON плюс поведінку збереженого робочого простору. Повторно використовуйте install-smoke image через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Мережевий шар Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Smoke знімка Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image плюс шар Chromium, запускає Chromium з сирим CDP, виконує `browser doctor --deep` і перевіряє, що знімки ролі CDP охоплюють URL посилань, елементи clickables, підвищені курсором, iframe refs і frame metadata. -- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mocked сервер OpenAI через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення схеми провайдера і перевіряє, що сира деталь з’являється в логах Gateway. -- MCP bridge каналу (засіяний Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP bundle Pi (реальний stdio MCP server + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Observability smoke: `pnpm qa:otel:smoke` — це приватний прохід QA для source checkout. Він навмисно не входить до Docker-проходів release для пакетів, оскільки npm tarball не містить QA Lab. +- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke-тест онбордингу/каналу/агента через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і за замовчуванням Telegram, перевіряє, що doctor відновлює активовані runtime-залежності Plugin, і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на host через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-тест перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, а потім повертається до package `stable` і перевіряє статус оновлення. +- Smoke-тест runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого транскрипту runtime context, а також відновлення doctor для уражених дубльованих гілок prompt-rewrite. +- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте збирання на host через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Docker smoke для інсталятора: `bash scripts/test-install-sh-docker.sh` використовує спільний npm cache для своїх контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільну базову версію перед оновленням до tarball-кандидата. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через вхід `update_baseline_version` workflow Install Smoke на GitHub. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи cache, що належать root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm між локальними повторними запусками. +- Install Smoke у CI пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Smoke CLI для видалення спільного workspace агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає образ root Dockerfile, підкладає два агенти з одним workspace в ізольованому home контейнера, виконує `agents delete --json` і перевіряє коректний JSON та збереження workspace. Повторно використовуйте образ install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Smoke CDP snapshot браузера: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E-образ плюс шар Chromium, запускає Chromium із сирим CDP, виконує `browser doctor --deep` і перевіряє, що CDP role snapshot охоплюють URL посилань, clickables, підвищені курсором, iframe refs і метадані frame. +- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` із `minimal` до `low`, а потім примусово викликає відхилення схеми провайдера й перевіряє, що сирі деталі з’являються в журналах Gateway. +- Міст MCP channel (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти Pi bundle MCP (реальний stdio MCP server + smoke allow/deny для вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) - Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення, встановлення/видалення ClawHub, оновлення marketplace і ввімкнення/перевірка bundle Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Задайте `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити live-блок ClawHub, або перевизначте типовий package через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. -- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime dependencies вбудованого Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову хоста після свіжого локального збирання через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вказуйте на наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегат і chunk release-path `plugins-integrations` попередньо пакують цей tarball один раз, а потім розбивають перевірки вбудованих каналів на незалежні lanes, включно з окремими lanes оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску вбудованого lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. -- Під час ітерації звужуйте runtime dependencies вбудованого Plugin, вимикаючи непов’язані сценарії, наприклад: +- Plugins (install smoke, встановлення/видалення ClawHub, оновлення marketplace і ввімкнення/перевірка пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) + Встановіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити live-блок ClawHub, або перевизначте типовий пакет через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. +- Smoke-тест незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke-тест метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності bundled Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker runner, один раз збирає й пакує OpenClaw на host, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову на host після свіжого локального збирання через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вказуйте на наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегат і `plugins-integrations` chunk шляху release один раз попередньо пакують цей tarball, а потім розподіляють перевірки bundled channel на незалежні проходи, включно з окремими проходами оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю channel під час прямого запуску bundled-проходу, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Прохід також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime dependency. +- Під час ітерації звужуйте runtime-залежності bundled Plugin, вимикаючи нерелевантні сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використати спільний функціональний image: +Щоб вручну попередньо зібрати й повторно використовувати спільний функціональний образ: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для окремих наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний image, скрипти завантажують його, якщо локально його ще немає. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільне середовище виконання built-app. +Перевизначення образів для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Тести Docker для QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime built-app. -Docker runners live-model також монтують поточний checkout лише для читання та -переносять його в тимчасовий workdir всередині контейнера. Це дозволяє зберігати -runtime image компактним і водночас запускати Vitest точно на вашому локальному source/config. -Крок перенесення пропускає великі локальні cache і вихідні артефакти збірки застосунку, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунку каталоги `.build` або -виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live probes gateway не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття -gateway live з цього Docker lane. -`test:docker:openwebui` є smoke-тестом сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoints, сумісними з OpenAI, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +Docker-ранери live-моделей також монтують поточний checkout лише для читання і +розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime-образ +компактним, водночас дозволяючи запускати Vitest проти вашого точного локального source/config. +Крок staging пропускає великі локальні cache і результати збирання застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків `.build` або +каталоги виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +специфічних для машини артефактів. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб Gateway live-probe не запускали +реальні працівники каналів Telegram/Discord/etc. усередині контейнера. +`test:docker:live-models` усе ще виконує `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live-покриття з цього Docker-проходу. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний чат-запит через проксі `/api/chat/completions` Open WebUI. +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -image Open WebUI, а самому Open WebUI може знадобитися завершити власне холодне налаштування. -Цей lane очікує придатний live key моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. -Успішні запуски друкують невеликий JSON payload, наприклад `{ "ok": true, "model": +образу Open WebUI, а самому Open WebUI може знадобитися завершити власне холодне стартове налаштування. +Цей прохід очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — це основний спосіб надати його в Dockerized-запусках. +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає засіяний контейнер -Gateway, запускає другий контейнер, який виконує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live events, маршрутизацію вихідного надсилання та сповіщення в стилі Claude про канал + -дозволи через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frames, тож smoke перевіряє саме те, що -bridge фактично видає, а не лише те, що випадково показує конкретний client SDK. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує -live key моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей сервер через runtime вбудованого bundle MCP Pi, -виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають -інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live key моделі. -Він запускає засіяний Gateway з реальним stdio MCP probe server, виконує -ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, -що дочірній процес MCP завершується після кожного запуску. +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord чи iMessage. Він запускає seeded Gateway +у контейнері, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання, а також channel + +повідомлення про permissions у стилі Claude через реальний stdio MCP bridge. Перевірка повідомлень +аналізує сирі stdio MCP frame безпосередньо, тож smoke перевіряє те, що міст +справді надсилає, а не лише те, що певний client SDK випадково показує назовні. +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує ключа live-моделі. +Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через вбудований runtime Pi bundle +MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +Він запускає seeded Gateway з реальним stdio MCP probe server, виконує +ізольований хід Cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +що дочірній MCP-процес завершується після кожного запуску. -Ручний smoke простого мовного ACP-треду (не CI): +Ручний ACP smoke для plain-language thread (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для потоків регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв і налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. -Корисні env vars: +Корисні змінні середовища: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевірити лише env vars, завантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI-автентифікації -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли CLI-автентифікації в `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і джерелиться перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, джерелені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішніх CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих CLI-встановлень у Docker +- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, які не потребують перебудови -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища profile (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway надає для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілю (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt nonce-check, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте перевірки документації після редагування docs: `pnpm check:docs`. Запускайте повну перевірку якорів Mintlify, коли також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайнова регресія (безпечна для CI) +## Offline-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (змоканий OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінки надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінки надійності агента»: -- Mock виклику інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Змоканий виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end потоки майстра, що перевіряють wiring сеансу та ефекти конфігурації (`src/gateway/gateway.test.ts`). Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сеансу та межі sandbox. -Майбутні evals мають залишатися детермінованими насамперед: +Майбутні evals спочатку мають залишатися детермінованими: -- Scenario runner із mock-провайдерами для перевірки викликів інструментів + їх порядку, читання файлів Skill і wiring сесії. -- Невеликий набір сценаріїв, зосереджених на Skills (використати чи уникнути, обмеження, prompt injection). -- Необов’язкові live-evals (opt-in, із керуванням через env) — лише після того, як буде готовий набір, безпечний для CI. +- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + їх порядку, читання skill-файлів і wiring сеансу. +- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live evals (opt-in, із захистом через env) лише після появи безпечного для CI набору. -## Контрактні тести (форма Plugin і каналу) +## Contract-тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає -своєму контракту інтерфейсу. Вони проходять по всіх виявлених Plugins і запускають набір -перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; явно запускайте контрактні команди, -коли торкаєтеся спільних поверхонь каналу або провайдера. +Contract-тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму +контракту інтерфейсу. Вони проходять по всіх виявлених Plugin і запускають набір +перевірок форми та поведінки. Типовий unit-прохід `pnpm test` навмисно +пропускає ці файли спільних меж і smoke; явно запускайте contract-команди, +коли змінюєте спільні поверхні channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти каналів: `pnpm test:contracts:channels` -- Лише контракти провайдерів: `pnpm test:contracts:plugins` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` -### Контракти каналів +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (`id`, `name`, `capabilities`) +- **plugin** - Базова форма Plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки сесії +- **session-binding** - Поведінка прив’язки сеансу - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу -- **threading** - Обробка ідентифікаторів тредів -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування group policy +- **actions** - Обробники дій channel +- **threading** - Обробка thread ID +- **directory** - API каталогу/списку учасників +- **group-policy** - Застосування групової політики -### Контракти статусу провайдера +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Status probes каналу +- **status** - Перевірки статусу channel - **registry** - Форма реєстру Plugin -### Контракти провайдерів +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/відбір автентифікації +- **auth-choice** - Вибір/селектор автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin -- **runtime** - Середовище виконання провайдера +- **runtime** - Runtime provider - **shape** - Форма/інтерфейс Plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export або subpaths у plugin-sdk -- Після додавання або зміни Plugin каналу чи провайдера +- Після зміни export або subpath у plugin-sdk +- Після додавання або зміни channel чи provider Plugin - Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести запускаються в CI і не потребують реальних API keys. +Contract-тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему provider/model, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або фіксація точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live-типу (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars -- Надавайте перевагу найменшому шару, який може зловити помилку: - - помилка перетворення/відтворення запиту провайдера → тест direct models - - помилка в pipeline session/history/tool gateway → gateway live smoke або безпечний для CI gateway mock test -- Guardrail обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. +- За можливості додавайте безпечну для CI регресію (mock/stub provider або захоплення точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), зберігайте live-тест вузьким і opt-in через змінні середовища +- Намагайтеся націлюватися на найменший шар, який ловить помилку: + - помилка перетворення/повторення запиту provider → тест direct models + - помилка в pipeline сеансу/історії/інструментів gateway → live smoke gateway або безпечний для CI mock-тест gateway +- Guardrail для обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було пропустити непомітно. ## Пов’язане -- [Тестування live](/uk/help/testing-live) +- [Live-тестування](/uk/help/testing-live) - [CI](/uk/ci) diff --git a/docs/uk/install/docker.md b/docs/uk/install/docker.md index b4ce51420..454f0078f 100644 --- a/docs/uk/install/docker.md +++ b/docs/uk/install/docker.md @@ -1,46 +1,46 @@ --- read_when: - - Вам потрібен контейнеризований Gateway замість локальних установок + - Ви хочете контейнеризований Gateway замість локальних встановлень - Ви перевіряєте потік Docker -summary: Необов’язкове налаштування та онбординг OpenClaw на основі Docker +summary: Необов’язкове налаштування та початок роботи з OpenClaw на основі Docker title: Docker x-i18n: - generated_at: "2026-04-27T07:08:09Z" + generated_at: "2026-04-27T08:07:53Z" model: gpt-5.4 provider: openai - source_hash: 56766c90b2751d186b0e9a7b55241fb45f05a37c2e8d7c0d0155b41eefc2177a + source_hash: 434d11db92060c20902db626f48e79077d24446450dd186af820c0a08a773c47 source_path: install/docker.md workflow: 15 --- -Docker **необов’язковий**. Використовуйте його лише якщо вам потрібен контейнеризований Gateway або ви хочете перевірити потік Docker. +Docker **необов’язковий**. Використовуйте його лише якщо вам потрібен контейнеризований Gateway або якщо ви хочете перевірити потік Docker. ## Чи підходить мені Docker? -- **Так**: вам потрібне ізольоване, тимчасове середовище Gateway або ви хочете запускати OpenClaw на хості без локальних установок. -- **Ні**: ви запускаєте його на власному комп’ютері й просто хочете найшвидший цикл розробки. Натомість використовуйте звичайний потік встановлення. -- **Примітка щодо ізоляції**: типовий бекенд ізоляції використовує Docker, коли ізоляцію ввімкнено, але ізоляція за замовчуванням вимкнена і **не** вимагає запуску всього Gateway у Docker. Також доступні бекенди ізоляції SSH і OpenShell. Див. [Ізоляція](/uk/gateway/sandboxing). +- **Так**: вам потрібне ізольоване, тимчасове середовище Gateway або ви хочете запускати OpenClaw на хості без локальних встановлень. +- **Ні**: ви запускаєте на власній машині й просто хочете найшвидший цикл розробки. Натомість скористайтеся звичайним потоком встановлення. +- **Примітка щодо ізоляції**: типовий бекенд ізоляції використовує Docker, коли ізоляцію увімкнено, але ізоляція вимкнена типово й **не** вимагає запуску повного Gateway у Docker. Також доступні бекенди ізоляції SSH і OpenShell. Див. [Ізоляція](/uk/gateway/sandboxing). ## Передумови - Docker Desktop (або Docker Engine) + Docker Compose v2 -- Щонайменше 2 ГБ RAM для збирання образу (`pnpm install` може бути примусово завершено через OOM на хостах із 1 ГБ із кодом виходу 137) -- Достатньо дискового простору для образів і журналів -- Якщо запуск відбувається на VPS/публічному хості, перегляньте - [Посилення безпеки для мережевого доступу](/uk/gateway/security), - особливо політику фаєрвола Docker `DOCKER-USER`. +- Щонайменше 2 ГБ RAM для збирання образу (`pnpm install` може бути примусово завершено через OOM на хостах із 1 ГБ з кодом виходу 137) +- Достатньо місця на диску для образів і журналів +- Якщо запускаєте на VPS/публічному хості, перегляньте + [Посилення безпеки для мережевої доступності](/uk/gateway/security), + особливо політику брандмауера Docker `DOCKER-USER`. ## Контейнеризований Gateway - Із кореня репозиторію запустіть скрипт налаштування: + З кореня репозиторію запустіть скрипт налаштування: ```bash ./scripts/docker/setup.sh ``` - Це локально збере образ Gateway. Щоб замість цього використовувати попередньо зібраний образ: + Це локально збере образ Gateway. Щоб натомість використовувати попередньо зібраний образ: ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" @@ -53,23 +53,23 @@ Docker **необов’язковий**. Використовуйте його - - Скрипт налаштування запускає онбординг автоматично. Він: + + Скрипт налаштування запускає початкове налаштування автоматично. Він: - - запросить API-ключі провайдера - - згенерує токен Gateway і запише його до `.env` + - запросить API-ключі провайдерів + - згенерує токен Gateway і запише його в `.env` - запустить Gateway через Docker Compose - Під час налаштування онбординг до запуску й запис конфігурації виконуються - безпосередньо через `openclaw-gateway`. `openclaw-cli` призначений для команд, які ви запускаєте після того, як контейнер Gateway уже існує. + Під час налаштування передстартове початкове налаштування та запис конфігурації виконуються безпосередньо через + `openclaw-gateway`. `openclaw-cli` призначений для команд, які ви запускаєте вже після того, як контейнер Gateway існує. - Відкрийте `http://127.0.0.1:18789/` у браузері й вставте налаштований - спільний секрет у Settings. Скрипт налаштування за замовчуванням записує токен у `.env`; якщо ви перемкнете конфігурацію контейнера на автентифікацію паролем, використовуйте натомість цей пароль. + Відкрийте `http://127.0.0.1:18789/` у браузері та вставте налаштований + спільний секрет у Settings. Скрипт налаштування типово записує токен у `.env`; якщо ви перемкнете конфігурацію контейнера на автентифікацію за паролем, використовуйте натомість цей пароль. - Потрібна URL-адреса ще раз? + Потрібна URL-адреса знову? ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -98,7 +98,7 @@ Docker **необов’язковий**. Використовуйте його ### Ручний потік -Якщо ви віддаєте перевагу запуску кожного кроку вручну замість використання скрипта налаштування: +Якщо ви надаєте перевагу запуску кожного кроку самостійно замість використання скрипта налаштування: ```bash docker build -t openclaw:local -f Dockerfile . @@ -112,12 +112,13 @@ docker compose up -d openclaw-gateway Запускайте `docker compose` з кореня репозиторію. Якщо ви ввімкнули `OPENCLAW_EXTRA_MOUNTS` або `OPENCLAW_HOME_VOLUME`, скрипт налаштування записує `docker-compose.extra.yml`; -додайте його за допомогою `-f docker-compose.yml -f docker-compose.extra.yml`. +додавайте його через `-f docker-compose.yml -f docker-compose.extra.yml`. -Оскільки `openclaw-cli` використовує спільний простір імен мережі з `openclaw-gateway`, це інструмент для використання після запуску. До `docker compose up -d openclaw-gateway` виконуйте онбординг -і записи конфігурації під час налаштування через `openclaw-gateway` з +Оскільки `openclaw-cli` спільно використовує простір назв мережі `openclaw-gateway`, це +інструмент для використання після запуску. До `docker compose up -d openclaw-gateway` виконуйте початкове налаштування +та записи конфігурації під час налаштування через `openclaw-gateway` з `--no-deps --entrypoint node`. @@ -128,32 +129,32 @@ docker compose up -d openclaw-gateway | Variable | Purpose | | ------------------------------------------ | --------------------------------------------------------------- | | `OPENCLAW_IMAGE` | Використовувати віддалений образ замість локального збирання | -| `OPENCLAW_DOCKER_APT_PACKAGES` | Встановити додаткові пакети apt під час збирання (імена через пробіл) | -| `OPENCLAW_EXTENSIONS` | Попередньо встановити залежності plugin під час збирання (імена через пробіл) | -| `OPENCLAW_EXTRA_MOUNTS` | Додаткові bind mounts хоста (через кому у форматі `source:target[:opts]`) | +| `OPENCLAW_DOCKER_APT_PACKAGES` | Установити додаткові apt-пакети під час збирання (назви через пробіл) | +| `OPENCLAW_EXTENSIONS` | Попередньо встановити залежності plugin під час збирання (назви через пробіл) | +| `OPENCLAW_EXTRA_MOUNTS` | Додаткові bind mount хоста (через кому `source:target[:opts]`) | | `OPENCLAW_HOME_VOLUME` | Зберігати `/home/node` в іменованому томі Docker | | `OPENCLAW_SANDBOX` | Увімкнути початкове налаштування ізоляції (`1`, `true`, `yes`, `on`) | | `OPENCLAW_DOCKER_SOCKET` | Перевизначити шлях до сокета Docker | -| `OPENCLAW_DISABLE_BONJOUR` | Вимкнути рекламу Bonjour/mDNS (для Docker за замовчуванням `1`) | -| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Вимкнути bind-mount overlays для вихідного коду вбудованих plugin | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Спільна кінцева точка колектора OTLP/HTTP для експорту OpenTelemetry | -| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Кінцеві точки OTLP для traces, metrics або logs, специфічні для сигналу | +| `OPENCLAW_DISABLE_BONJOUR` | Вимкнути рекламу Bonjour/mDNS (типово `1` для Docker) | +| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | Вимкнути bind-mount overlays для вбудованих джерел plugin | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Спільна кінцева точка OTLP/HTTP collector для експорту OpenTelemetry | +| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | Кінцеві точки OTLP для певних сигналів: traces, metrics або logs | | `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначення протоколу OTLP. Наразі підтримується лише `http/protobuf` | | `OTEL_SERVICE_NAME` | Назва сервісу, що використовується для ресурсів OpenTelemetry | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Увімкнути новітні експериментальні семантичні атрибути GenAI | -| `OPENCLAW_OTEL_PRELOADED` | Пропустити запуск другого SDK OpenTelemetry, якщо один уже попередньо завантажено | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Увімкнути найновіші експериментальні семантичні атрибути GenAI | +| `OPENCLAW_OTEL_PRELOADED` | Не запускати другий SDK OpenTelemetry, якщо один уже попередньо завантажений | -Супровідники можуть тестувати вихідний код вбудованого plugin із запакованим образом, змонтувавши -один каталог вихідного коду plugin поверх його шляху запакованого вихідного коду, наприклад +Супроводжувачі можуть тестувати вбудований код plugin з упакованим образом, змонтувавши +один каталог вихідного коду plugin поверх його шляху до упакованого коду, наприклад `OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`. Цей змонтований каталог вихідного коду перевизначає відповідний скомпільований -бандл `/app/dist/extensions/synology-chat` для того самого ідентифікатора plugin. +bundle `/app/dist/extensions/synology-chat` для того самого ідентифікатора plugin. ### Спостережуваність -Експорт OpenTelemetry є вихідним із контейнера Gateway до вашого колектора OTLP. -Для нього не потрібен опублікований порт Docker. Якщо ви локально збираєте образ і хочете, щоб вбудований експортер OpenTelemetry був доступний усередині образу, -додайте його залежності часу виконання: +Експорт OpenTelemetry є вихідним трафіком із контейнера Gateway до вашого OTLP +collector. Для цього не потрібен опублікований порт Docker. Якщо ви локально збираєте образ і хочете, щоб вбудований експортер OpenTelemetry був доступний усередині образу, +додайте його залежності виконання: ```bash export OPENCLAW_EXTENSIONS="diagnostics-otel" @@ -162,93 +163,118 @@ export OTEL_SERVICE_NAME="openclaw-gateway" ./scripts/docker/setup.sh ``` -Офіційний релізний Docker-образ OpenClaw містить вихідний код вбудованого -plugin `diagnostics-otel`. Залежно від стану образу й кешу, -Gateway може все одно підготувати локальні залежності OpenTelemetry для plugin -під час першого ввімкнення plugin, тому дозвольте цьому першому запуску мати доступ до реєстру пакетів -або попередньо прогрійте образ у вашому релізному потоці. Щоб увімкнути експорт, дозвольте й +Офіційний Docker-образ релізу OpenClaw містить вбудований вихідний код plugin +`diagnostics-otel`. Залежно від образу та стану кешу, +Gateway усе ще може підготувати локальні залежності виконання OpenTelemetry plugin +під час першого ввімкнення plugin, тому дозвольте цьому першому запуску доступ до реєстру пакетів +або попередньо прогрійте образ у вашому релізному конвеєрі. Щоб увімкнути експорт, дозвольте та увімкніть plugin `diagnostics-otel` у конфігурації, а потім установіть -`diagnostics.otel.enabled=true` або скористайтеся прикладом конфігурації з -[Експорт OpenTelemetry](/uk/gateway/opentelemetry). Заголовки автентифікації колектора -налаштовуються через `diagnostics.otel.headers`, а не через змінні середовища Docker. +`diagnostics.otel.enabled=true` або скористайтеся прикладом конфігурації в +[Експорт OpenTelemetry](/uk/gateway/opentelemetry). Заголовки автентифікації collector налаштовуються через +`diagnostics.otel.headers`, а не через змінні середовища Docker. Метрики Prometheus використовують уже опублікований порт Gateway. Увімкніть -plugin `diagnostics-prometheus`, а потім виконуйте збирання: +plugin `diagnostics-prometheus`, а потім збирайте: ```text http://:18789/api/diagnostics/prometheus ``` Маршрут захищено автентифікацією Gateway. Не відкривайте окремий -публічний порт `/metrics` або неавтентифікований шлях зворотного проксі. Див. +публічний порт `/metrics` або неавтентифікований шлях через reverse proxy. Див. [Метрики Prometheus](/uk/gateway/prometheus). -### Перевірки стану +### Перевірки працездатності Кінцеві точки probe контейнера (автентифікація не потрібна): ```bash -curl -fsS http://127.0.0.1:18789/healthz # liveness -curl -fsS http://127.0.0.1:18789/readyz # readiness +curl -fsS http://127.0.0.1:18789/healthz # live +curl -fsS http://127.0.0.1:18789/readyz # готовність ``` Docker-образ містить вбудований `HEALTHCHECK`, який опитує `/healthz`. -Якщо перевірки продовжують завершуватися помилкою, Docker позначає контейнер як `unhealthy`, і +Якщо перевірки продовжують провалюватися, Docker позначає контейнер як `unhealthy`, і системи оркестрації можуть перезапустити або замінити його. -Автентифікований докладний знімок стану: +Автентифікований глибокий знімок стану: ```bash docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN" ``` -### LAN чи loopback +### LAN проти loopback -`scripts/docker/setup.sh` за замовчуванням встановлює `OPENCLAW_GATEWAY_BIND=lan`, щоб доступ хоста до -`http://127.0.0.1:18789` працював із публікацією портів Docker. +`scripts/docker/setup.sh` типово використовує `OPENCLAW_GATEWAY_BIND=lan`, щоб доступ хоста до +`http://127.0.0.1:18789` працював із публікацією порту Docker. -- `lan` (типово): браузер і CLI на хості можуть отримати доступ до опублікованого порту Gateway. -- `loopback`: лише процеси всередині простору імен мережі контейнера можуть - напряму отримати доступ до Gateway. +- `lan` (типово): браузер хоста та CLI хоста можуть досягати опублікованого порту Gateway. +- `loopback`: лише процеси всередині простору назв мережі контейнера можуть + напряму досягати Gateway. Використовуйте значення режиму прив’язки в `gateway.bind` (`lan` / `loopback` / `custom` / `tailnet` / `auto`), а не псевдоніми хоста на кшталт `0.0.0.0` або `127.0.0.1`. +### Локальні провайдери хоста + +Коли OpenClaw працює в Docker, `127.0.0.1` всередині контейнера — це сам контейнер, +а не ваша хост-машина. Для провайдерів AI, які працюють на хості, використовуйте `host.docker.internal`: + +| Provider | Host default URL | Docker setup URL | +| --------- | ------------------------ | ----------------------------------- | +| LM Studio | `http://127.0.0.1:1234` | `http://host.docker.internal:1234` | +| Ollama | `http://127.0.0.1:11434` | `http://host.docker.internal:11434` | + +Вбудоване налаштування Docker використовує ці URL хоста як типові значення для LM Studio та Ollama +під час початкового налаштування, а `docker-compose.yml` відображає `host.docker.internal` на +шлюз хоста Docker для Linux Docker Engine. Docker Desktop уже надає +те саме ім’я хоста на macOS і Windows. + +Служби хоста також мають слухати на адресі, досяжній із Docker: + +```bash +lms server start --port 1234 --bind 0.0.0.0 +OLLAMA_HOST=0.0.0.0:11434 ollama serve +``` + +Якщо ви використовуєте власний файл Compose або команду `docker run`, додайте те саме +відображення хоста самостійно, наприклад +`--add-host=host.docker.internal:host-gateway`. + ### Bonjour / mDNS -Мережа Docker bridge зазвичай ненадійно пересилає мультикаст Bonjour/mDNS -(`224.0.0.251:5353`). Тому вбудоване налаштування Compose типово встановлює -`OPENCLAW_DISABLE_BONJOUR=1`, щоб Gateway не потрапляв у цикл аварійних перезапусків і -не перезапускав рекламу знову й знову, коли bridge втрачає мультикаст-трафік. +Мережа Docker bridge зазвичай не пересилає multicast Bonjour/mDNS +(`224.0.0.251:5353`) надійно. Тому вбудоване налаштування Compose типово використовує +`OPENCLAW_DISABLE_BONJOUR=1`, щоб Gateway не потрапляв у цикл аварійних перезапусків і не +перезапускав рекламу повторно, коли bridge втрачає multicast-трафік. Для Docker-хостів використовуйте опубліковану URL-адресу Gateway, Tailscale або wide-area DNS-SD. -Установлюйте `OPENCLAW_DISABLE_BONJOUR=0` лише під час роботи з host networking, macvlan -або іншою мережею, де мультикаст mDNS гарантовано працює. +Установлюйте `OPENCLAW_DISABLE_BONJOUR=0` лише під час запуску з host networking, macvlan +або іншою мережею, де multicast mDNS гарантовано працює. -Про типові проблеми та усунення несправностей див. -[Виявлення Bonjour](/uk/gateway/bonjour). +Щоб дізнатися про типові проблеми та способи усунення несправностей, див. [Виявлення Bonjour](/uk/gateway/bonjour). ### Сховище та збереження даних -Docker Compose монтує через bind `OPENCLAW_CONFIG_DIR` до `/home/node/.openclaw` і -`OPENCLAW_WORKSPACE_DIR` до `/home/node/.openclaw/workspace`, тож ці шляхи +Docker Compose монтує `OPENCLAW_CONFIG_DIR` у `/home/node/.openclaw` і +`OPENCLAW_WORKSPACE_DIR` у `/home/node/.openclaw/workspace`, тому ці шляхи зберігаються після заміни контейнера. У цьому змонтованому каталозі конфігурації OpenClaw зберігає: - `openclaw.json` для конфігурації поведінки -- `agents//agent/auth-profiles.json` для збереженої OAuth/API-key автентифікації провайдера -- `.env` для секретів часу виконання на основі змінних середовища, таких як `OPENCLAW_GATEWAY_TOKEN` +- `agents//agent/auth-profiles.json` для збереженої OAuth/API-key автентифікації провайдерів +- `.env` для секретів виконання на основі змінних середовища, таких як `OPENCLAW_GATEWAY_TOKEN` -Повні відомості про збереження даних у розгортаннях на VM див. у -[Середовище виконання Docker VM — що і де зберігається](/uk/install/docker-vm-runtime#what-persists-where). +Повні відомості про збереження даних у розгортаннях VM див. у +[Docker VM Runtime - Що зберігається де](/uk/install/docker-vm-runtime#what-persists-where). -**Точки зростання диска:** стежте за `media/`, файлами JSONL сеансів, `cron/runs/*.jsonl`, -і файлами циклічних журналів у `/tmp/openclaw/`. +**Точки зростання диска:** стежте за `media/`, JSONL-файлами сесій, `cron/runs/*.jsonl`, +і журналами rolling file у `/tmp/openclaw/`. -### Допоміжні команди оболонки (необов’язково) +### Допоміжні команди shell (необов’язково) Для зручнішого повсякденного керування Docker установіть `ClawDock`: @@ -257,11 +283,11 @@ mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/open echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -Якщо ви встановлювали ClawDock зі старого шляху raw `scripts/shell-helpers/clawdock-helpers.sh`, повторно виконайте команду встановлення вище, щоб ваш локальний файл helper відстежував нове розташування. +Якщо ви встановили `ClawDock` зі старого raw-шляху `scripts/shell-helpers/clawdock-helpers.sh`, повторно виконайте наведену вище команду встановлення, щоб ваш локальний файл помічника відстежував нове розташування. -Потім використовуйте `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` тощо. Виконайте +Потім використовуйте `clawdock-start`, `clawdock-stop`, `clawdock-dashboard` тощо. Запустіть `clawdock-help`, щоб побачити всі команди. -Див. [ClawDock](/uk/install/clawdock), щоб ознайомитися з повним посібником з helper. +Повний посібник щодо помічника див. у [ClawDock](/uk/install/clawdock). @@ -270,7 +296,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - Нестандартний шлях до сокета (наприклад, rootless Docker): + Власний шлях до сокета (наприклад, rootless Docker): ```bash export OPENCLAW_SANDBOX=1 @@ -278,7 +304,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - Скрипт монтує `docker.sock` лише після успішного проходження передумов ізоляції. Якщо + Скрипт монтує `docker.sock` лише після того, як передумови ізоляції успішно пройдено. Якщо налаштування ізоляції не вдається завершити, скрипт скидає `agents.defaults.sandbox.mode` до `off`. @@ -295,15 +321,15 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - `openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тож команди CLI - можуть звертатися до Gateway через `127.0.0.1`. Розглядайте це як спільну - межу довіри. Конфігурація compose прибирає `NET_RAW`/`NET_ADMIN` і вмикає + `openclaw-cli` використовує `network_mode: "service:openclaw-gateway"`, тому команди CLI + можуть досягати gateway через `127.0.0.1`. Розглядайте це як спільну + межу довіри. Конфігурація compose скидає `NET_RAW`/`NET_ADMIN` і вмикає `no-new-privileges` для `openclaw-cli`. - - Образ працює від імені `node` (uid 1000). Якщо ви бачите помилки прав доступу на - `/home/node/.openclaw`, переконайтеся, що bind mounts на хості належать uid 1000: + + Образ запускається як `node` (uid 1000). Якщо ви бачите помилки дозволів для + `/home/node/.openclaw`, переконайтеся, що ваші bind mount хоста належать uid 1000: ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -313,7 +339,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc Упорядкуйте Dockerfile так, щоб шари залежностей кешувалися. Це дозволяє уникнути повторного запуску - `pnpm install`, якщо lockfiles не змінювалися: + `pnpm install`, якщо lockfile не змінювалися: ```dockerfile FROM node:24-bookworm @@ -335,13 +361,13 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - - Типовий образ насамперед орієнтований на безпеку й працює від імені непривілейованого `node`. Для більш + + Типовий образ орієнтований насамперед на безпеку і працює як непривілейований `node`. Для більш функціонального контейнера: 1. **Зберігайте `/home/node`**: `export OPENCLAW_HOME_VOLUME="openclaw_home"` 2. **Вбудуйте системні залежності**: `export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` - 3. **Встановіть браузери Playwright**: + 3. **Установіть браузери Playwright**: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium @@ -354,44 +380,44 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc Якщо у майстрі ви виберете OpenAI Codex OAuth, він відкриє URL-адресу в браузері. У - Docker або headless-середовищах скопіюйте повну URL-адресу перенаправлення, на яку ви потрапите, і вставте + Docker або headless-налаштуваннях скопіюйте повну URL-адресу перенаправлення, на яку ви потрапите, і вставте її назад у майстер, щоб завершити автентифікацію. - Основний Docker-образ середовища виконання використовує `node:24-bookworm-slim` і публікує OCI + Основний runtime-образ Docker використовує `node:24-bookworm-slim` і публікує OCI анотації базового образу, зокрема `org.opencontainers.image.base.name`, `org.opencontainers.image.source` та інші. Digest базового образу Node - оновлюється через PR Dependabot для базових Docker-образів; релізні збірки не виконують + оновлюється через PR Dependabot для базових Docker-образів; релізні збірки не запускають шар оновлення дистрибутива. Див. - [Анотації образів OCI](https://github.com/opencontainers/image-spec/blob/main/annotations.md). + [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md). -### Запуск на VPS? +### Запускаєте на VPS? Див. [Hetzner (Docker VPS)](/uk/install/hetzner) і -[Docker VM Runtime](/uk/install/docker-vm-runtime), щоб переглянути кроки розгортання на спільних VM -включно з вбудовуванням бінарних файлів, збереженням даних і оновленнями. +[Docker VM Runtime](/uk/install/docker-vm-runtime), щоб ознайомитися з кроками розгортання на спільній VM, +включно з вбудовуванням бінарників, збереженням даних і оновленнями. ## Ізоляція агента -Коли `agents.defaults.sandbox` увімкнено з Docker-бекендом, Gateway -виконує інструменти агента (shell, читання/запис файлів тощо) в ізольованих Docker- -контейнерах, тоді як сам Gateway залишається на хості. Це створює жорстку межу -навколо недовірених або мультитенантних сеансів агентів без контейнеризації всього -Gateway. +Коли `agents.defaults.sandbox` увімкнено з Docker-бекендом, gateway +виконує інструменти агента (shell, читання/запис файлів тощо) в ізольованих Docker +контейнерах, тоді як сам gateway залишається на хості. Це створює жорстку межу +навколо недовірених або багатокористувацьких сеансів агентів без контейнеризації всього +gateway. -Область ізоляції може бути для кожного агента окремо (типово), для кожного сеансу або спільною. Кожна область +Область ізоляції може бути для агента (типово), для сеансу або спільною. Кожна область отримує власний workspace, змонтований у `/workspace`. Ви також можете налаштувати -політики дозволу/заборони інструментів, ізоляцію мережі, обмеження ресурсів і -контейнери браузера. +політики дозволу/заборони інструментів, ізоляцію мережі, обмеження ресурсів і браузерні +контейнери. -Повну інформацію про конфігурацію, образи, примітки щодо безпеки й профілі з кількома агентами див. у: +Повну інформацію про конфігурацію, образи, примітки щодо безпеки та профілі для кількох агентів див. тут: - [Ізоляція](/uk/gateway/sandboxing) -- повний довідник з ізоляції -- [OpenShell](/uk/gateway/openshell) -- інтерактивний доступ shell до контейнерів ізоляції -- [Ізоляція й інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів +- [OpenShell](/uk/gateway/openshell) -- інтерактивний shell-доступ до контейнерів ізоляції +- [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів ### Швидке ввімкнення @@ -420,27 +446,27 @@ scripts/sandbox-setup.sh Зберіть образ ізоляції за допомогою [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) - або встановіть `agents.defaults.sandbox.docker.image` на ваш власний образ. + або встановіть `agents.defaults.sandbox.docker.image` на власний образ. Контейнери автоматично створюються за потреби для кожного сеансу. - + Установіть `docker.user` на UID:GID, що відповідає власнику змонтованого workspace, - або змініть власника папки workspace через chown. + або змініть власника теки workspace за допомогою chown. - OpenClaw запускає команди через `sh -lc` (login shell), який завантажує - `/etc/profile` і може скинути PATH. Установіть `docker.env.PATH`, щоб додати - ваші власні шляхи до інструментів на початок, або додайте скрипт до `/etc/profile.d/` у вашому Dockerfile. + OpenClaw запускає команди через `sh -lc` (login shell), який зчитує + `/etc/profile` і може скидати PATH. Установіть `docker.env.PATH`, щоб додати + ваші шляхи до власних інструментів на початок, або додайте скрипт у `/etc/profile.d/` у вашому Dockerfile. - VM потребує щонайменше 2 ГБ RAM. Використайте більший клас машини та повторіть спробу. + VM потребує щонайменше 2 ГБ RAM. Використайте більший клас машини й повторіть спробу. - - Отримайте нове посилання на dashboard і схваліть пристрій браузера: + + Отримайте нове посилання dashboard і схваліть браузерний пристрій: ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -448,12 +474,12 @@ scripts/sandbox-setup.sh docker compose run --rm openclaw-cli devices approve ``` - Докладніше: [Dashboard](/uk/web/dashboard), [Пристрої](/uk/cli/devices). + Докладніше: [Dashboard](/uk/web/dashboard), [Devices](/uk/cli/devices). - - Скиньте режим Gateway і прив’язку: + + Скиньте mode і bind gateway: ```bash docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]' @@ -463,10 +489,10 @@ scripts/sandbox-setup.sh -## Пов’язане +## Пов’язані матеріали -- [Огляд встановлення](/uk/install) — усі способи встановлення +- [Огляд установлення](/uk/install) — усі способи встановлення - [Podman](/uk/install/podman) — альтернатива Docker у вигляді Podman - [ClawDock](/uk/install/clawdock) — спільнотне налаштування Docker Compose -- [Оновлення](/uk/install/updating) — як підтримувати OpenClaw в актуальному стані -- [Конфігурація](/uk/gateway/configuration) — конфігурація Gateway після встановлення +- [Оновлення](/uk/install/updating) — підтримання OpenClaw в актуальному стані +- [Конфігурація](/uk/gateway/configuration) — конфігурація gateway після встановлення diff --git a/docs/uk/install/migrating-hermes.md b/docs/uk/install/migrating-hermes.md new file mode 100644 index 000000000..677425643 --- /dev/null +++ b/docs/uk/install/migrating-hermes.md @@ -0,0 +1,174 @@ +--- +read_when: + - Ви переходите з Hermes і хочете зберегти конфігурацію моделі, підказки, пам’ять і Skills + - Ви хочете знати, що OpenClaw імпортує автоматично, а що залишається лише в архіві + - Вам потрібен чистий, скриптований шлях міграції (CI, новий ноутбук, автоматизація) +summary: Перейдіть із Hermes до OpenClaw за допомогою попередньо переглянутого імпорту з можливістю скасування +title: Міграція з Hermes +x-i18n: + generated_at: "2026-04-27T08:08:07Z" + model: gpt-5.4 + provider: openai + source_hash: 2fdf09f21398d10a8cdf8e98237fbdfb3c56ade5b56e73a6e6ae01b5c201440d + source_path: install/migrating-hermes.md + workflow: 15 +--- + +OpenClaw імпортує стан Hermes через вбудований провайдер міграції. Провайдер попередньо показує все перед зміною стану, редагує секрети в планах і звітах та створює перевірену резервну копію перед застосуванням. + + +Імпорт потребує нового налаштування OpenClaw. Якщо у вас уже є локальний стан OpenClaw, спочатку скиньте конфігурацію, облікові дані, сесії та робочий простір або використайте `openclaw migrate` безпосередньо з `--overwrite` після перегляду плану. + + +## Два способи імпорту + + + + Найшвидший шлях. Майстер виявляє Hermes у `~/.hermes` і показує попередній перегляд перед застосуванням. + + ```bash + openclaw onboard --flow import + ``` + + Або вкажіть конкретне джерело: + + ```bash + openclaw onboard --import-from hermes --import-source ~/.hermes + ``` + + + Використовуйте `openclaw migrate` для скриптованих або повторюваних запусків. Див. [`openclaw migrate`](/uk/cli/migrate) для повного довідника. + + ```bash + openclaw migrate hermes --dry-run # лише попередній перегляд + openclaw migrate apply hermes --yes # застосувати без підтвердження + ``` + + Додайте `--from `, якщо Hermes розташований поза `~/.hermes`. + + + +## Що імпортується + + + + - Вибір типової моделі з Hermes `config.yaml`. + - Налаштовані провайдери моделей і власні OpenAI-сумісні кінцеві точки з `providers` і `custom_providers`. + + + Визначення серверів MCP з `mcp_servers` або `mcp.servers`. + + + - `SOUL.md` і `AGENTS.md` копіюються до робочого простору агента OpenClaw. + - `memories/MEMORY.md` і `memories/USER.md` **додаються** до відповідних файлів пам’яті OpenClaw замість перезапису. + + + Типові налаштування пам’яті для файлової пам’яті OpenClaw. Зовнішні провайдери пам’яті, такі як Honcho, записуються як архівні елементи або елементи для ручної перевірки, щоб ви могли перенести їх свідомо. + + + 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`. Без цього прапорця секрети ніколи не копіюються. + + + +## Що залишається лише в архіві + +Провайдер копіює це до каталогу звіту про міграцію для ручної перевірки, але **не** завантажує до активної конфігурації чи облікових даних OpenClaw: + +- `plugins/` +- `sessions/` +- `logs/` +- `cron/` +- `mcp-tokens/` +- `auth.json` +- `state.db` + +OpenClaw відмовляється автоматично виконувати або вважати цей стан довіреним, оскільки формати та припущення про довіру можуть відрізнятися між системами. Перенесіть потрібне вручну після перегляду архіву. + +## Рекомендований процес + + + + ```bash + openclaw migrate hermes --dry-run + ``` + + У плані перелічено все, що буде змінено, включно з конфліктами, пропущеними елементами та будь-якими чутливими елементами. Вивід плану редагує вкладені ключі, схожі на секрети. + + + ```bash + openclaw migrate apply hermes --yes + ``` + + OpenClaw створює та перевіряє резервну копію перед застосуванням. Якщо вам потрібно імпортувати ключі API, додайте `--include-secrets`. + + + ```bash + openclaw doctor + ``` + + [Doctor](/uk/gateway/doctor) повторно застосовує всі незавершені міграції конфігурації та перевіряє наявність проблем, які могли з’явитися під час імпорту. + + + ```bash + openclaw gateway restart + openclaw status + ``` + + Підтвердьте, що Gateway працює справно і що ваші імпортовані модель, пам’ять і Skills завантажені. + + + +## Обробка конфліктів + +Застосування відмовляється продовжувати, якщо план повідомляє про конфлікти (файл або значення конфігурації вже існує в цільовому місці). + + +Повторно запускайте з `--overwrite` лише тоді, коли заміна наявної цілі справді є навмисною. Провайдери все одно можуть записувати резервні копії окремих елементів для перезаписаних файлів до каталогу звіту про міграцію. + + +Для нового встановлення OpenClaw конфлікти трапляються рідко. Зазвичай вони з’являються, коли ви повторно запускаєте імпорт у налаштуванні, де вже є користувацькі зміни. + +## Секрети + +Секрети ніколи не імпортуються типово. + +- Спочатку запустіть `openclaw migrate apply hermes --yes`, щоб імпортувати стан без секретів. +- Якщо ви також хочете скопіювати підтримувані ключі `.env`, повторіть запуск із `--include-secrets`. +- Для облікових даних, якими керує SecretRef, налаштуйте джерело SecretRef після завершення імпорту. + +## Вивід JSON для автоматизації + +```bash +openclaw migrate hermes --dry-run --json +openclaw migrate apply hermes --json --yes +``` + +З `--json` і без `--yes` застосування виводить план і не змінює стан. Це найбезпечніший режим для CI та спільних скриптів. + +## Усунення проблем + + + + Перегляньте вивід плану. Кожен конфлікт визначає вихідний шлях і наявну ціль. Для кожного елемента вирішіть, чи пропустити його, змінити ціль або повторно запустити з `--overwrite`. + + + Передайте `--from /actual/path` (CLI) або `--import-source /actual/path` (онбординг). + + + Імпорт через онбординг потребує нового налаштування. Або скиньте стан і пройдіть онбординг знову, або використайте `openclaw migrate apply hermes` безпосередньо, що підтримує `--overwrite` і явне керування резервними копіями. + + + Потрібен `--include-secrets`, і розпізнаються лише перелічені вище ключі. Інші змінні в `.env` ігноруються. + + + +## Пов’язано + +- [`openclaw migrate`](/uk/cli/migrate): повний довідник CLI, контракт Plugin і форми JSON. +- [Онбординг](/uk/cli/onboard): процес майстра та неінтерактивні прапорці. +- [Міграція](/uk/install/migrating): перенесення встановлення OpenClaw між машинами. +- [Doctor](/uk/gateway/doctor): перевірка стану після міграції. +- [Робочий простір агента](/uk/concepts/agent-workspace): де розташовані `SOUL.md`, `AGENTS.md` і файли пам’яті. diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 7a188f6c2..39a90365d 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -1,188 +1,202 @@ --- read_when: - - Створення або налагодження нативних Plugins OpenClaw + - Створення або налагодження власних plugins OpenClaw - Розуміння моделі можливостей Plugin або меж володіння - Робота над конвеєром завантаження Plugin або реєстром - - Реалізація хуків runtime постачальника або каналів Plugins + - Реалізація runtime hooks provider-а або plugins каналів sidebarTitle: Internals -summary: 'Внутрішні компоненти Plugin: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби runtime' +summary: 'Внутрішні компоненти Plugin: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' title: Внутрішні компоненти Plugin x-i18n: - generated_at: "2026-04-26T07:49:37Z" + generated_at: "2026-04-27T08:08:26Z" model: gpt-5.4 provider: openai - source_hash: 16664d284a8bfbfcb9914bb012d1f36dfdd60406636d6bf4b011f76e886cb518 + source_hash: 5b7622b361c6d19069106785f2b80cb3155e58f9a27a2fac9733e976d7c27f13 source_path: plugins/architecture.md workflow: 15 --- -Це **поглиблений довідник з архітектури** системи Plugin в OpenClaw. Для практичних посібників почніть з однієї з наведених нижче сторінок. +Це **детальний довідник з архітектури** системи Plugin в OpenClaw. Для практичних посібників почніть з однієї з наведених нижче спеціалізованих сторінок. - - Посібник для кінцевих користувачів щодо додавання, увімкнення та усунення несправностей Plugins. + + Посібник для кінцевих користувачів з додавання, увімкнення та усунення проблем із plugins. - - Навчальний посібник зі створення першого Plugin з найменшим працездатним manifest. + + Навчальний посібник зі створення першого plugin з найменшим робочим маніфестом. - - Створіть Plugin каналу обміну повідомленнями. + + Створіть plugin каналу обміну повідомленнями. - - Створіть Plugin постачальника моделей. + + Створіть plugin provider-а моделей. - - Довідник щодо import map і API реєстрації. + + Довідник з мапи імпортів і API реєстрації. ## Публічна модель можливостей -Можливості — це публічна модель **нативних Plugins** всередині OpenClaw. Кожен нативний Plugin OpenClaw реєструється для одного або кількох типів можливостей: +Можливості — це публічна модель **власних plugins** у межах OpenClaw. Кожен власний plugin OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади Plugins | -| ---------------------- | ----------------------------------------------- | ------------------------------------- | -| Text inference | `api.registerProvider(...)` | `openai`, `anthropic` | -| Бекенд CLI inference | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Realtime transcription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Realtime voice | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | -| Виявлення Gateway | `api.registerGatewayDiscoveryService(...)` | `bonjour` | +| Можливість | Метод реєстрації | Приклади plugins | +| ---------------------- | --------------------------------------------- | ----------------------------------- | +| Текстовий inference | `api.registerProvider(...)` | `openai`, `anthropic` | +| CLI backend inference | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | +| Виявлення Gateway | `api.registerGatewayDiscoveryService(...)` | `bonjour` | -Plugin, який реєструє нуль можливостей, але надає hooks, tools, служби виявлення або фонові служби, є **застарілим Plugin лише з hooks**. Цей шаблон усе ще повністю підтримується. +Plugin, який реєструє нуль можливостей, але надає hooks, tools, служби виявлення або фонові служби, є **застарілим plugin лише з hooks**. Цей шаблон усе ще повністю підтримується. ### Позиція щодо зовнішньої сумісності -Модель можливостей уже впроваджена в core і сьогодні використовується вбудованими/нативними Plugins, але сумісність із зовнішніми Plugins усе ще потребує вищої планки, ніж «це експортується, отже, це зафіксовано». +Модель можливостей реалізована в core і вже сьогодні використовується вбудованими/власними plugins, але сумісність із зовнішніми plugins усе ще потребує вищої планки, ніж «це експортується, отже це незмінне». -| Ситуація Plugin | Рекомендація | -| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -| Наявні зовнішні Plugins | Підтримуйте працездатність інтеграцій на основі hooks; це базовий рівень сумісності. | -| Нові вбудовані/нативні Plugins | Віддавайте перевагу явній реєстрації можливостей замість специфічних для постачальника втручань або нових дизайнів лише з hooks. | -| Зовнішні Plugins, що переходять на реєстрацію можливостей | Дозволено, але вважайте допоміжні поверхні, специфічні для можливостей, такими, що розвиваються, якщо документація не позначає їх як стабільні. | +| Ситуація з plugin | Рекомендація | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- | +| Наявні зовнішні plugins | Підтримуйте інтеграції на основі hooks; це базовий рівень сумісності. | +| Нові вбудовані/власні plugins | Віддавайте перевагу явній реєстрації можливостей замість vendor-специфічних звернень або нових дизайнів лише з hooks. | +| Зовнішні plugins, що впроваджують реєстрацію можливостей | Дозволено, але вважайте допоміжні surface-и для конкретних можливостей такими, що еволюціонують, якщо документація не позначає їх як стабільні. | -Реєстрація можливостей — це цільовий напрямок. Застарілі hooks залишаються найбезпечнішим шляхом без ламання для зовнішніх Plugins під час переходу. Експортовані допоміжні subpath не всі однакові — віддавайте перевагу вузьким задокументованим контрактам, а не випадковим допоміжним експортам. +Реєстрація можливостей — це бажаний напрям розвитку. Застарілі hooks залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх plugins під час переходу. Експортовані допоміжні підшляхи не всі однакові — надавайте перевагу вузьким задокументованим контрактам, а не побічним експортам helper-ів. ### Форми Plugin -OpenClaw класифікує кожен завантажений Plugin за формою на основі його фактичної поведінки реєстрації (а не лише статичних метаданих): +OpenClaw класифікує кожен завантажений plugin за формою на основі його фактичної поведінки під час реєстрації, а не лише статичних метаданих: - Реєструє рівно один тип можливостей (наприклад, Plugin лише постачальника, як-от `mistral`). + Реєструє рівно один тип можливості (наприклад, plugin лише provider-а, як-от `mistral`). - Реєструє кілька типів можливостей (наприклад, `openai` володіє text inference, speech, media understanding і image generation). + Реєструє кілька типів можливостей (наприклад, `openai` володіє текстовим inference, мовленням, розумінням медіа та генерацією зображень). - Реєструє лише hooks (типізовані або власні), без capabilities, tools, команд чи служб. + Реєструє лише hooks (типізовані або користувацькі), без можливостей, tools, команд або служб. - Реєструє tools, команди, служби або routes, але не capabilities. + Реєструє tools, команди, служби або routes, але не можливості. -Використовуйте `openclaw plugins inspect `, щоб побачити форму Plugin і розкладку можливостей. Докладніше див. у [CLI reference](/uk/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму plugin та розбивку за можливостями. Докладніше див. у [довіднику CLI](/uk/cli/plugins#inspect). ### Застарілі hooks -Hook `before_agent_start` залишається підтримуваним шляхом сумісності для Plugins лише з hooks. Застарілі реальні Plugins усе ще від нього залежать. +Hook `before_agent_start` залишається підтримуваним як шлях сумісності для plugins лише з hooks. Реальні застарілі plugins і далі від нього залежать. -Напрямок: +Напрям: -- зберігати його працездатним -- документувати як застарілий -- для перевизначення моделі/постачальника віддавати перевагу `before_model_resolve` -- для змінювання prompt віддавати перевагу `before_prompt_build` -- видаляти лише після падіння реального використання й коли покриття фікстурами доведе безпечність міграції +- зберігати його працездатність +- документувати його як застарілий +- для перевизначення моделі/provider-а віддавати перевагу `before_model_resolve` +- для зміни prompt віддавати перевагу `before_prompt_build` +- видаляти лише після зменшення реального використання й підтвердження безпеки міграції покриттям fixtures ### Сигнали сумісності -Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити одну з таких позначок: +Під час запуску `openclaw doctor` або `openclaw plugins inspect ` ви можете побачити одну з таких міток: -| Сигнал | Значення | -| -------------------------- | ------------------------------------------------------------ | -| **config valid** | Конфігурація коректно розбирається, і Plugins успішно визначаються | +| Сигнал | Значення | +| ------------------------- | ------------------------------------------------------------ | +| **config valid** | Config успішно парситься, а plugins успішно визначаються | | **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Plugin використовує `before_agent_start`, який є застарілим | -| **hard error** | Конфігурація недійсна або Plugin не вдалося завантажити | +| **legacy warning** | Plugin використовує `before_agent_start`, який є застарілим | +| **hard error** | Config недійсний або plugin не вдалося завантажити | -Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш Plugin: `hook-only` є рекомендаційним сигналом, а `before_agent_start` лише викликає попередження. Ці сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. +Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш plugin: `hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури Система Plugin в OpenClaw має чотири шари: - - OpenClaw знаходить кандидатів у Plugins зі сконфігурованих шляхів, коренів workspace, глобальних коренів Plugins і вбудованих Plugins. Виявлення спочатку читає нативні manifests `openclaw.plugin.json` і manifests підтримуваних bundle. + + OpenClaw знаходить кандидатів у plugins у налаштованих шляхах, коренях робочого простору, глобальних коренях plugins і серед вбудованих plugins. Під час виявлення спочатку зчитуються власні маніфести `openclaw.plugin.json`, а потім підтримувані маніфести bundles. - - Core вирішує, чи є виявлений Plugin увімкненим, вимкненим, заблокованим або вибраним для ексклюзивного слота, наприклад пам’яті. + + Core вирішує, чи є виявлений plugin увімкненим, вимкненим, заблокованим або вибраним для ексклюзивного слота, наприклад пам’яті. - - Нативні Plugins OpenClaw завантажуються в процесі через jiti і реєструють можливості в центральному реєстрі. Сумісні bundles нормалізуються в записи реєстру без імпорту коду runtime. + + Власні plugins OpenClaw завантажуються в тому ж процесі через jiti і реєструють можливості в центральному реєстрі. Сумісні bundles нормалізуються в записи реєстру без імпортування runtime-коду. - - Решта OpenClaw читає реєстр, щоб відкрити tools, канали, налаштування постачальників, hooks, HTTP routes, CLI-команди та служби. + + Решта OpenClaw читає реєстр, щоб надавати tools, канали, налаштування provider-ів, hooks, HTTP-routes, CLI-команди та служби. -Зокрема для CLI Plugin виявлення кореневої команди поділено на дві фази: +Зокрема для CLI plugins, виявлення кореневих команд поділено на дві фази: -- метадані на етапі розбору походять з `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI Plugin може залишатися лінивим і реєструватися під час першого виклику +- метадані на етапі парсингу надходять із `registerCli(..., { descriptors: [...] })` +- справжній CLI-модуль plugin може залишатися лінивим і реєструватися під час першого виклику -Це дає змогу тримати CLI-код, яким володіє Plugin, усередині Plugin, водночас дозволяючи OpenClaw резервувати імена кореневих команд до розбору. +Це дає змогу зберігати код CLI, що належить plugin, усередині plugin, водночас дозволяючи OpenClaw резервувати імена кореневих команд до парсингу. -Важлива межа дизайну: +Важлива межа проєктування: -- перевірка manifest/config має працювати на основі **метаданих manifest/schema** без виконання коду Plugin -- виявлення нативних можливостей може завантажувати код входу довіреного Plugin, щоб побудувати знімок реєстру без активації -- нативна поведінка runtime походить зі шляху модуля Plugin `register(api)` з `api.registrationMode === "full"` +- валідація маніфесту/config має працювати на основі **метаданих маніфесту/схеми** без виконання коду plugin +- виявлення власних можливостей може завантажувати код входу довіреного plugin для побудови знімка реєстру без активації +- власна runtime-поведінка надходить із шляху `register(api)` модуля plugin, коли `api.registrationMode === "full"` -Це розділення дозволяє OpenClaw перевіряти config, пояснювати відсутні/вимкнені Plugins і будувати підказки UI/schema до повної активації runtime. +Цей поділ дозволяє OpenClaw перевіряти config, пояснювати відсутні/вимкнені plugins і будувати підказки для UI/схем до повної активації runtime. + +### Таблиця пошуку Plugin + +Під час запуску Gateway створюється `PluginLookUpTable` з індексу встановлених plugins і реєстру маніфестів для поточного знімка config. Ця таблиця містить лише метадані: вона зберігає ідентифікатори plugins, записи маніфестів, діагностику, мапи володіння, нормалізатор ідентифікаторів plugins і стартовий план plugins. Вона не містить завантажених модулів plugins, SDK provider-ів, вмісту package чи runtime-експортів. + +Таблиця пошуку утримує повторювані рішення під час запуску на швидкому шляху: + +- володіння каналами +- відкладений запуск каналів +- ідентифікатори plugins для запуску +- володіння provider-ами та CLI backend-ами +- володіння setup provider-ами, псевдонімами команд, provider-ами каталогів моделей і контрактами маніфестів + +Межа безпеки — це заміна знімка, а не мутація. Перебудовуйте таблицю, коли змінюються config, інвентар plugins, записи встановлення або політика збереженого індексу. Не сприймайте її як широкий змінний глобальний реєстр і не зберігайте необмежену кількість історичних таблиць. Runtime-завантаження plugins залишається окремим від метаданих таблиці пошуку, щоб застарілий runtime-стан не міг бути прихований за кешем метаданих. ### Планування активації -Планування активації є частиною control plane. Викликачі можуть запитати, які Plugins стосуються конкретної команди, постачальника, каналу, route, harness агента або можливості, до завантаження ширших реєстрів runtime. +Планування активації є частиною control plane. Викликаючі сторони можуть запитати, які plugins релевантні для конкретної команди, provider-а, каналу, route, harness агента або можливості, до завантаження ширших runtime-реєстрів. -Планувальник зберігає сумісність із поточною поведінкою manifest: +Планувальник зберігає сумісність із поточною поведінкою маніфестів: -- поля `activation.*` є явними підказками для планувальника -- `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks залишаються запасним варіантом володіння в manifest -- API планувальника лише з id залишається доступним для наявних викликачів -- API плану повідомляє мітки причин, щоб діагностика могла відрізняти явні підказки від запасного варіанта володіння +- поля `activation.*` — це явні підказки для планувальника +- `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks залишаються резервним варіантом володіння з боку маніфесту +- API планувальника лише з ідентифікаторами залишається доступним для наявних викликачів +- API плану повідомляє мітки причин, щоб діагностика могла відрізняти явні підказки від резервного визначення володіння -Не сприймайте `activation` як lifecycle hook або заміну `register(...)`. Це метадані, які використовуються для звуження завантаження. Віддавайте перевагу полям володіння, коли вони вже описують цей зв’язок; використовуйте `activation` лише для додаткових підказок планувальника. +Не сприймайте `activation` як hook життєвого циклу або як заміну `register(...)`. Це метадані, які використовуються для звуження завантаження. Віддавайте перевагу полям володіння, коли вони вже описують зв’язок; використовуйте `activation` лише для додаткових підказок планувальнику. ### Plugins каналів і спільний tool повідомлень -Plugins каналів не повинні реєструвати окремий tool надсилання/редагування/реакції для звичайних дій чату. OpenClaw зберігає один спільний tool `message` у core, а Plugins каналів володіють специфічним для каналу виявленням і виконанням за ним. +Plugins каналів не потрібно реєструвати окремий tool для send/edit/react для звичайних дій чату. OpenClaw зберігає один спільний tool `message` у core, а plugins каналів відповідають за специфічне для каналу виявлення та виконання за ним. Поточна межа така: -- core володіє спільним host tool `message`, wiring prompt, веденням session/thread і диспетчеризацією виконання -- Plugins каналів володіють scoped виявленням дій, виявленням можливостей і будь-якими фрагментами schema, специфічними для каналу -- Plugins каналів володіють граматикою conversation сесії, специфічною для постачальника, наприклад тим, як id conversation кодують id thread або успадковуються від батьківських conversations -- Plugins каналів виконують фінальну дію через свій adapter дій +- core володіє хостом спільного tool `message`, wiring prompt-ів, обліком сесій/гілок і диспетчеризацією виконання +- plugins каналів володіють виявленням scoped actions, виявленням можливостей і будь-якими фрагментами схеми, специфічними для каналу +- plugins каналів володіють специфічною для provider-а граматикою розмов у сесіях, наприклад тим, як conversation id кодують thread id або успадковуються від батьківських conversations +- plugins каналів виконують фінальну дію через свій action adapter -Для Plugins каналів поверхнею SDK є `ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення дає Plugin змогу повертати видимі дії, можливості та внески у schema разом, щоб ці частини не розходилися. +Для plugins каналів поверхнею SDK є `ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення дає plugin змогу повертати видимі actions, можливості та внески до схеми разом, щоб ці частини не розходилися. -Коли параметр tool повідомлення, специфічний для каналу, містить джерело медіа, таке як локальний шлях або віддалена URL-адреса медіа, Plugin також має повертати `mediaSourceParams` з `describeMessageTool(...)`. Core використовує цей явний список для застосування нормалізації шляхів sandbox і підказок доступу до вихідних медіа без жорсткого кодування назв параметрів, якими володіє Plugin. Там варто віддавати перевагу картам у межах дії, а не одному плоскому списку на весь канал, щоб параметр медіа лише для профілю не нормалізувався для не пов’язаних дій, як-от `send`. +Коли параметр специфічного для каналу tool повідомлень містить джерело медіа, наприклад локальний шлях або віддалений URL медіа, plugin також має повертати `mediaSourceParams` із `describeMessageTool(...)`. Core використовує цей явний список, щоб застосовувати нормалізацію шляхів sandbox і підказки доступу до вихідних медіа без жорсткого кодування назв параметрів, що належать plugin. Там слід віддавати перевагу мапам на рівні action, а не одному плоскому списку на весь канал, щоб параметр медіа лише для профілю не нормалізувався для не пов’язаних actions, таких як `send`. -Core передає область runtime на цьому етапі виявлення. Важливі поля: +Core передає runtime-scope до цього кроку виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -193,57 +207,57 @@ Core передає область runtime на цьому етапі виявл - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для Plugins, чутливих до контексту. Канал може приховувати або відкривати дії повідомлень залежно від активного облікового запису, поточної кімнати/thread/message або довіреної особи-відправника запиту без жорсткого кодування специфічних для каналу гілок у core tool `message`. +Це важливо для plugins, чутливих до контексту. Канал може приховувати або показувати дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або довіреної ідентичності запитувача без жорстко закодованих специфічних для каналу гілок у core tool `message`. -Ось чому зміни маршрутизації embedded-runner усе ще є роботою Plugin: runner відповідає за передавання поточної ідентичності chat/session у межу виявлення Plugin, щоб спільний tool `message` відкривав правильну поверхню, якою володіє канал, для поточного ходу. +Саме тому зміни маршрутизації embedded-runner усе ще належать до роботи plugin: runner відповідає за пересилання поточної ідентичності чату/сесії до межі виявлення plugin, щоб спільний tool `message` показував правильну поверхню, що належить каналу, для поточного ходу. -Для допоміжних засобів виконання, якими володіє канал, вбудовані Plugins мають зберігати runtime виконання у своїх власних модулях extension. Core більше не володіє runtime дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. Ми не публікуємо окремі subpath `plugin-sdk/*-action-runtime`, і вбудовані Plugins мають імпортувати свій власний локальний код runtime безпосередньо зі своїх модулів extension. +Для допоміжних засобів виконання, що належать каналу, вбудовані plugins мають зберігати runtime виконання у власних модулях extension. Core більше не володіє runtime-реалізаціями дій повідомлень для Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, а вбудовані plugins мають імпортувати власний локальний runtime-код безпосередньо зі своїх модулів, що належать extension. -Та сама межа застосовується і до загальних швів SDK, названих на честь постачальників: core не повинен імпортувати специфічні для каналу зручні barrels для Slack, Discord, Signal, WhatsApp або подібних extensions. Якщо core потрібна певна поведінка, слід або використовувати власний barrel `api.ts` / `runtime-api.ts` вбудованого Plugin, або підняти цю потребу до вузької загальної можливості в спільному SDK. +Та сама межа застосовується й до named SDK seams provider-ів загалом: core не повинен імпортувати специфічні для каналів convenience barrels для Slack, Discord, Signal, WhatsApp або подібних extensions. Якщо core потрібна певна поведінка, він має або використовувати власний barrel `api.ts` / `runtime-api.ts` вбудованого plugin, або підняти цю потребу до вузької узагальненої можливості в спільному SDK. -Зокрема для опитувань є два шляхи виконання: +Зокрема для опитувань існують два шляхи виконання: - `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній моделі опитувань -- `actions.handleAction("poll")` — це бажаний шлях для специфічної для каналу семантики опитувань або додаткових параметрів опитування +- `actions.handleAction("poll")` — це бажаний шлях для специфічної семантики опитувань каналу або додаткових параметрів опитувань -Тепер core відкладає спільний розбір опитувань до моменту, коли dispatch опитування через Plugin відхилить дію, щоб обробники опитувань, якими володіє Plugin, могли приймати специфічні для каналу поля опитування без блокування з боку загального парсера опитувань. +Тепер Core відкладає спільний парсинг опитувань до моменту, коли dispatch plugin опитувань відхиляє дію, щоб обробники опитувань, що належать plugin, могли приймати специфічні для каналу поля опитувань без блокування загальним парсером опитувань на початку. -Повну послідовність запуску див. у [Plugin architecture internals](/uk/plugins/architecture-internals). +Див. [Внутрішні компоненти архітектури Plugin](/uk/plugins/architecture-internals), щоб переглянути повну послідовність запуску. ## Модель володіння можливостями -OpenClaw розглядає нативний Plugin як межу володіння для **компанії** або **можливості**, а не як випадковий набір не пов’язаних інтеграцій. +OpenClaw розглядає власний plugin як межу володіння для **компанії** або **функції**, а не як набір не пов’язаних інтеграцій. Це означає: -- Plugin компанії зазвичай має володіти всіма поверхнями цієї компанії в OpenClaw -- Plugin можливості зазвичай має володіти повною поверхнею можливості, яку він додає -- канали мають споживати спільні можливості core замість того, щоб спеціальним чином повторно реалізовувати поведінку постачальника +- plugin компанії зазвичай повинен володіти всіма поверхнями цієї компанії, орієнтованими на OpenClaw +- plugin функції зазвичай повинен володіти повною поверхнею функції, яку він додає +- канали повинні використовувати спільні можливості core замість того, щоб щоразу заново реалізовувати поведінку provider-а - - `openai` володіє text inference, speech, realtime voice, media understanding і image generation. `google` володіє text inference, а також media understanding, image generation і web search. `qwen` володіє text inference, а також media understanding і video generation. + + `openai` володіє текстовим inference, мовленням, голосом у реальному часі, розумінням медіа та генерацією зображень. `google` володіє текстовим inference, а також розумінням медіа, генерацією зображень і вебпошуком. `qwen` володіє текстовим inference, а також розумінням медіа й генерацією відео. - - `elevenlabs` і `microsoft` володіють speech; `firecrawl` володіє web-fetch; `minimax` / `mistral` / `moonshot` / `zai` володіють бекендами media-understanding. + + `elevenlabs` і `microsoft` володіють мовленням; `firecrawl` володіє web-fetch; `minimax` / `mistral` / `moonshot` / `zai` володіють backends розуміння медіа. - - `voice-call` володіє transport викликів, tools, CLI, routes і мостом медіапотоків Twilio, але споживає спільні можливості speech, realtime transcription і realtime voice замість прямого імпорту Plugins постачальників. + + `voice-call` володіє transport викликів, tools, CLI, routes і мостом медіапотоків Twilio, але використовує спільні можливості мовлення, транскрибування в реальному часі та голосу в реальному часі замість прямого імпорту plugins vendor-ів. -Цільовий кінцевий стан такий: +Бажаний кінцевий стан: -- OpenAI живе в одному Plugin, навіть якщо він охоплює текстові моделі, speech, зображення та майбутнє відео -- інший постачальник може так само зробити це для власної області -- канали не повинні зважати, який Plugin постачальника володіє provider; вони споживають спільний контракт можливостей, який відкриває core +- OpenAI знаходиться в одному plugin, навіть якщо він охоплює текстові моделі, мовлення, зображення та майбутнє відео +- інший vendor може робити те саме для власної області +- каналам не важливо, який plugin vendor-а володіє provider-ом; вони використовують спільний контракт можливостей, який надає core Ось ключова відмінність: - **plugin** = межа володіння -- **capability** = контракт core, який можуть реалізовувати або споживати кілька Plugins +- **capability** = контракт core, який кілька plugins можуть реалізовувати або використовувати -Тому якщо OpenClaw додає нову область, як-от відео, перше питання не таке: «який постачальник має жорстко закодувати обробку відео?» Перше питання таке: «який контракт можливостей відео в core?» Щойно такий контракт з’явиться, Plugins постачальників зможуть реєструватися щодо нього, а Plugins каналів/можливостей — споживати його. +Тому якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не таке: «який provider має жорстко закодувати обробку відео?» Перше запитання таке: «який контракт можливості відео в core?» Після появи цього контракту plugins vendor-ів можуть реєструватися для нього, а plugins каналів/функцій можуть його використовувати. Якщо можливість ще не існує, правильний крок зазвичай такий: @@ -251,46 +265,46 @@ OpenClaw розглядає нативний Plugin як межу володін Визначте відсутню можливість у core. - - Відкрийте її через API/runtime Plugin у типізованому вигляді. + + Надайте її через plugin API/runtime у типізований спосіб. - - Під’єднайте канали/можливості до цієї можливості. + + Підключіть канали/функції до цієї можливості. - - Дозвольте Plugins постачальників реєструвати реалізації. + + Дозвольте plugins vendor-ів реєструвати реалізації. -Це зберігає явне володіння й водночас уникає поведінки core, яка залежить від одного постачальника або одноразового специфічного для Plugin шляху коду. +Це зберігає явне володіння й водночас уникає поведінки core, що залежить від одного vendor-а або одноразового специфічного шляху коду plugin. ### Шарування можливостей -Використовуйте таку ментальну модель, коли вирішуєте, де має розміщуватися код: +Використовуйте цю ментальну модель, коли вирішуєте, де має розміщуватися код: Спільна оркестрація, політика, fallback, правила злиття config, семантика доставки та типізовані контракти. - - Специфічні для постачальника API, auth, каталоги моделей, синтез мовлення, генерація зображень, майбутні відеобекенди, endpoint-и використання. + + Специфічні для vendor-а API, автентифікація, каталоги моделей, синтез мовлення, генерація зображень, майбутні backends відео, endpoints використання. - - Інтеграція Slack/Discord/voice-call/тощо, яка споживає можливості core і представляє їх на певній поверхні. + + Інтеграція Slack/Discord/voice-call тощо, яка використовує можливості core і представляє їх на певній поверхні. Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канал +- core володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канали - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає допоміжний засіб runtime телекомунікаційного TTS +- `voice-call` використовує helper runtime TTS для телефонії -Тому ж шаблону слід віддавати перевагу і для майбутніх можливостей. +Тому самому шаблону слід надавати перевагу й для майбутніх можливостей. -### Приклад Plugin компанії з кількома можливостями +### Приклад plugin компанії з кількома можливостями -Plugin компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні контракти для моделей, speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch і web search, постачальник може володіти всіма своїми поверхнями в одному місці: +Plugin компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні контракти для моделей, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації відео, web fetch і вебпошуку, vendor може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -344,126 +358,126 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви допоміжних засобів. Важлива форма: +Важливі не точні назви helper-ів. Важлива форма: -- один Plugin володіє поверхнею постачальника +- один plugin володіє поверхнею vendor-а - core усе ще володіє контрактами можливостей -- канали й Plugins можливостей споживають допоміжні засоби `api.runtime.*`, а не код постачальника -- контрактні тести можуть перевіряти, що Plugin зареєстрував можливості, якими він заявляє, що володіє +- plugins каналів і функцій використовують helper-и `api.runtime.*`, а не код vendor-а +- contract tests можуть перевіряти, що plugin зареєстрував можливості, якими він заявляє володіти ### Приклад можливості: розуміння відео -OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну можливість. Та сама модель володіння застосовується і тут: +OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну можливість. Та сама модель володіння застосовується й тут: Core визначає контракт media-understanding. - - Plugins постачальників реєструють `describeImage`, `transcribeAudio` і `describeVideo`, де це застосовно. + + Plugins vendor-ів реєструють `describeImage`, `transcribeAudio` і `describeVideo`, де це доречно. - Канали й Plugins можливостей споживають спільну поведінку core замість прямого під’єднання до коду постачальника. + Plugins каналів і функцій використовують спільну поведінку core замість прямого підключення до коду vendor-а. -Це дозволяє не вшивати в core припущення одного постачальника щодо відео. Plugin володіє поверхнею постачальника; core володіє контрактом можливостей і поведінкою fallback. +Це не дозволяє вбудовувати припущення одного provider-а про відео в core. Plugin володіє поверхнею vendor-а; core володіє контрактом можливості та fallback-поведінкою. -Генерація відео вже використовує ту саму послідовність: core володіє типізованим контрактом можливостей і допоміжним засобом runtime, а Plugins постачальників реєструють щодо нього реалізації `api.registerVideoGenerationProvider(...)`. +Генерація відео вже використовує ту саму послідовність: core володіє типізованим контрактом можливості та helper-ом runtime, а plugins vendor-ів реєструють для нього реалізації `api.registerVideoGenerationProvider(...)`. Потрібен конкретний контрольний список розгортання? Див. [Capability Cookbook](/uk/plugins/architecture). -## Контракти та примусове дотримання +## Контракти та забезпечення виконання -Поверхня API Plugin навмисно типізована й централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та допоміжні засоби runtime, на які може покладатися Plugin. +Поверхня plugin API навмисно типізована й централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та helper-и runtime, на які може покладатися plugin. Чому це важливо: -- автори Plugins отримують один стабільний внутрішній стандарт -- core може відхиляти дублювання володіння, наприклад коли два Plugins реєструють той самий id постачальника -- під час запуску можна показувати практичні діагностичні повідомлення для некоректної реєстрації -- контрактні тести можуть забезпечувати володіння вбудованих Plugins і запобігати непомітному дрейфу +- автори plugins отримують єдиний стабільний внутрішній стандарт +- core може відхиляти дубльоване володіння, наприклад коли два plugins реєструють той самий ідентифікатор provider-а +- під час запуску можна показувати діагностику з конкретними діями для некоректної реєстрації +- contract tests можуть забезпечувати володіння вбудованими plugins і запобігати непомітному дрейфу -Є два шари примусового дотримання: +Існує два рівні забезпечення виконання: - - Реєстр Plugins перевіряє реєстрації під час завантаження Plugins. Приклади: дубльовані id постачальників, дубльовані id постачальників speech і некоректні реєстрації призводять до діагностики Plugins замість невизначеної поведінки. + + Реєстр plugin перевіряє реєстрації під час завантаження plugins. Наприклад, дубльовані ідентифікатори provider-ів, дубльовані ідентифікатори provider-ів мовлення й некоректні реєстрації породжують діагностику plugin замість невизначеної поведінки. - - Вбудовані Plugins фіксуються в контрактних реєстрах під час тестових запусків, щоб OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для постачальників моделей, постачальників speech, постачальників web search і володіння вбудованою реєстрацією. + + Вбудовані plugins фіксуються в contract registries під час виконання тестів, щоб OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для provider-ів моделей, provider-ів мовлення, provider-ів вебпошуку та володіння реєстрацією вбудованих компонентів. -Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який Plugin якою поверхнею володіє. Це дає змогу core і каналам безшовно поєднуватися, тому що володіння оголошене, типізоване й придатне до тестування, а не неявне. +Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який plugin володіє якою поверхнею. Це дозволяє core і каналам безшовно компонуватися, оскільки володіння оголошене, типізоване й придатне для тестування, а не неявне. -### Що належить до контракту +### Що має належати до контракту - типізовані - - малі - - специфічні для можливостей + - невеликі + - специфічні для можливості - належать core - - повторно використовуються кількома Plugins - - можуть споживатися каналами/можливостями без знання постачальника + - повторно використовуються кількома plugins + - можуть використовуватися каналами/функціями без знання про vendor-а - - специфічна для постачальника політика, прихована в core - - одноразові аварійні виходи Plugin, які оминають реєстр - - код каналу, який напряму звертається до реалізації постачальника - - ad hoc об’єкти runtime, які не є частиною `OpenClawPluginApi` або `api.runtime` + - специфічна для vendor-а політика, прихована в core + - одноразові обхідні шляхи plugin, що обходять реєстр + - код каналу, який напряму звертається до реалізації vendor-а + - ad hoc runtime-об’єкти, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо є сумніви, піднімайте рівень абстракції: спочатку визначте можливість, а вже потім дозвольте Plugins підключатися до неї. +Якщо є сумніви, піднімайте рівень абстракції: спочатку визначте можливість, а потім дозвольте plugins підключатися до неї. ## Модель виконання -Нативні Plugins OpenClaw виконуються **в процесі** разом із Gateway. Вони не ізольовані. Завантажений нативний Plugin має ту саму межу довіри на рівні процесу, що й код core. +Власні plugins OpenClaw працюють **у межах того самого процесу** разом із Gateway. Вони не ізольовані. Завантажений власний plugin має ту саму межу довіри на рівні процесу, що й код core. Наслідки: -- нативний Plugin може реєструвати tools, обробники мережі, hooks і служби -- помилка в нативному Plugin може призвести до збою або дестабілізації gateway -- зловмисний нативний Plugin еквівалентний довільному виконанню коду всередині процесу OpenClaw +- власний plugin може реєструвати tools, мережеві handlers, hooks і служби +- помилка власного plugin може зламати або дестабілізувати gateway +- зловмисний власний plugin еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні bundles за замовчуванням безпечніші, тому що зараз OpenClaw розглядає їх як пакети метаданих/вмісту. У поточних релізах це переважно означає вбудовані Skills. +Сумісні bundles за замовчуванням безпечніші, оскільки наразі OpenClaw розглядає їх як пакети метаданих/контенту. У поточних релізах це здебільшого означає вбудовані Skills. -Для невбудованих Plugins використовуйте allowlist-и й явні шляхи встановлення/завантаження. Сприймайте Plugins workspace як код для часу розробки, а не як типові production-налаштування. +Використовуйте allowlists і явні шляхи встановлення/завантаження для невбудованих plugins. Розглядайте plugins робочого простору як код для часу розробки, а не як типові виробничі налаштування. -Для імен пакетів вбудованого workspace зберігайте id Plugin прив’язаним до npm-імені: типово `@openclaw/` або із затвердженим типізованим суфіксом, як-от `-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли пакет навмисно відкриває вужчу роль Plugin. +Для назв package у вбудованому робочому просторі зберігайте прив’язку ідентифікатора plugin до npm-імені: `@openclaw/` за замовчуванням або затверджений типізований суфікс, такий як `-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли package навмисно надає вужчу роль plugin. **Примітка щодо довіри:** -- `plugins.allow` довіряє **id Plugin**, а не походженню джерела. -- Plugin workspace з тим самим id, що й у вбудованого Plugin, навмисно затіняє вбудовану копію, коли такий Plugin workspace увімкнено/додано до allowlist. +- `plugins.allow` довіряє **ідентифікаторам plugin**, а не походженню джерела. +- Plugin робочого простору з тим самим ідентифікатором, що й у вбудованого plugin, навмисно затіняє вбудовану копію, коли цей plugin робочого простору увімкнений/доданий до allowlist. - Це нормально й корисно для локальної розробки, тестування патчів і hotfix-ів. -- Довіра до вбудованого Plugin визначається зі знімка джерела — manifest і коду на диску під час завантаження — а не з метаданих встановлення. Пошкоджений або підмінений запис встановлення не може непомітно розширити поверхню довіри вбудованого Plugin понад те, що заявляє фактичне джерело. +- Довіра до вбудованого plugin визначається зі знімка джерела — маніфесту й коду на диску під час завантаження — а не з метаданих встановлення. Пошкоджений або підмінений запис встановлення не може непомітно розширити поверхню довіри вбудованого plugin понад те, що фактично заявляє джерело. ## Межа експорту -OpenClaw експортує можливості, а не зручні засоби реалізації. +OpenClaw експортує можливості, а не зручні реалізації. -Зберігайте публічною реєстрацію можливостей. Скорочуйте експорти допоміжних засобів, що не є частиною контракту: +Зберігайте публічною реєстрацію можливостей. Скорочуйте експорти helper-ів, які не є частиною контракту: -- subpath допоміжних засобів, специфічних для вбудованих Plugins -- subpath plumbing runtime, які не призначені бути публічним API -- специфічні для постачальника зручні допоміжні засоби -- допоміжні засоби setup/onboarding, які є деталями реалізації +- підшляхи helper-ів, специфічних для вбудованих plugins +- підшляхи runtime plumbing, не призначені як публічний API +- специфічні для vendor-а convenience helper-и +- helper-и setup/onboarding, які є деталями реалізації -Деякі subpath допоміжних засобів вбудованих Plugins усе ще залишаються в згенерованій export map SDK для сумісності й підтримки вбудованих Plugins. Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Сприймайте їх як зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх Plugins. +Деякі підшляхи helper-ів вбудованих plugins усе ще залишаються в згенерованій мапі експорту SDK для сумісності та супроводу вбудованих plugins. Поточні приклади: `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і кілька seams `plugin-sdk/matrix*`. Розглядайте їх як зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх plugins. ## Внутрішні компоненти та довідка -Щодо конвеєра завантаження, моделі реєстру, хуків runtime постачальника, HTTP routes Gateway, schema tool повідомлень, визначення цілі каналу, каталогів постачальників, Plugins context engine і посібника з додавання нової можливості див. [Plugin architecture internals](/uk/plugins/architecture-internals). +Щоб дізнатися про конвеєр завантаження, модель реєстру, runtime hooks provider-ів, HTTP-routes Gateway, схеми tool повідомлень, визначення цілей каналів, каталоги provider-ів, plugins рушія контексту та посібник з додавання нової можливості, див. [Внутрішні компоненти архітектури Plugin](/uk/plugins/architecture-internals). ## Пов’язане -- [Building plugins](/uk/plugins/building-plugins) -- [Plugin manifest](/uk/plugins/manifest) -- [Plugin SDK setup](/uk/plugins/sdk-setup) +- [Створення plugins](/uk/plugins/building-plugins) +- [Маніфест Plugin](/uk/plugins/manifest) +- [Налаштування SDK Plugin](/uk/plugins/sdk-setup) diff --git a/docs/uk/plugins/google-meet.md b/docs/uk/plugins/google-meet.md index 1923ea974..61081dd4b 100644 --- a/docs/uk/plugins/google-meet.md +++ b/docs/uk/plugins/google-meet.md @@ -2,35 +2,37 @@ read_when: - Ви хочете, щоб агент OpenClaw приєднався до виклику Google Meet - Ви хочете, щоб агент OpenClaw створив новий виклик Google Meet - - Ви налаштовуєте Chrome, вузол Chrome або Twilio як транспорт Google Meet -summary: 'Plugin Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio з типовими налаштуваннями голосу в реальному часі' + - Ви налаштовуєте Chrome, Node Chrome або Twilio як транспорт для Google Meet +summary: 'Plugin Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio із типовими параметрами голосу в реальному часі' title: Plugin Google Meet x-i18n: - generated_at: "2026-04-26T11:07:59Z" + generated_at: "2026-04-27T08:08:30Z" model: gpt-5.4 provider: openai - source_hash: 1bd53db711e4729a9a7b18f7aaa3eedffd71a1e19349fc858537652b5d17cfcb + source_hash: 4b0196c35c06ce884bf14f8e6c94e49ae17e309527854b4e17d3ce01d57ee6be source_path: plugins/google-meet.md workflow: 15 --- -Підтримка учасника Google Meet для OpenClaw — Plugin є навмисно явним за дизайном: +Підтримка учасників Google Meet для OpenClaw — Plugin навмисно зроблено явним: - Він приєднується лише до явного URL `https://meet.google.com/...`. -- Він може створити новий простір Meet через API Google Meet, а потім приєднатися за поверненим URL. -- Голос `realtime` є типовим режимом. -- Голос у режимі реального часу може повертатися до повного агента OpenClaw, коли потрібні глибші міркування або інструменти. -- Агенти вибирають поведінку приєднання за допомогою `mode`: використовуйте `realtime` для живого прослуховування/зворотного мовлення або `transcribe`, щоб приєднатися/керувати браузером без голосового мосту реального часу. -- Автентифікація починається як персональний Google OAuth або вже виконаний вхід у профілі Chrome. -- Автоматичного оголошення про згоду немає. +- Він може створити новий простір Meet через Google Meet API, а потім приєднатися за поверненим URL. +- Типовим режимом є голос `realtime`. +- Голос `realtime` може повертатися до повного агента OpenClaw, коли потрібні глибші міркування або інструменти. +- Агенти вибирають поведінку приєднання через `mode`: використовуйте `realtime` для живого прослуховування/зворотного мовлення або `transcribe`, щоб приєднатися/керувати браузером без голосового мосту `realtime`. +- Автентифікація починається з особистого Google OAuth або вже виконаного входу в профіль Chrome. +- Автоматичного оголошення згоди немає. - Типовий аудіобекенд Chrome — `BlackHole 2ch`. - Chrome може працювати локально або на підключеному хості Node. -- Twilio приймає номер для дозвону та необов’язковий PIN або послідовність DTMF. -- Команда CLI — `googlemeet`; `meet` зарезервовано для ширших робочих процесів телеконференцій агента. +- Twilio приймає номер для дозвону та необов’язкову послідовність PIN або DTMF. +- Команда CLI — `googlemeet`; `meet` зарезервовано для ширших сценаріїв телеконференцій агента. ## Швидкий старт -Установіть локальні аудіозалежності та налаштуйте провайдера голосу в режимі реального часу для бекенда. OpenAI є типовим; Google Gemini Live також працює з `realtime.provider: "google"`: +Установіть локальні аудіозалежності та налаштуйте бекенд-провайдера голосу `realtime`. +Типовим є OpenAI; Google Gemini Live також працює з +`realtime.provider: "google"`: ```bash brew install blackhole-2ch sox @@ -39,7 +41,8 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` установлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор Homebrew потребує перезавантаження, перш ніж macOS відкриє цей пристрій: +`blackhole-2ch` установлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор +Homebrew вимагає перезавантаження, перш ніж macOS покаже цей пристрій: ```bash sudo reboot @@ -73,12 +76,15 @@ command -v rec play openclaw googlemeet setup ``` -Вивід налаштування призначений для читання агентом. Він повідомляє про профіль Chrome, аудіоміст, прив’язку до Node, відкладений вступ у `realtime` і, коли налаштовано делегування Twilio, чи готові Plugin `voice-call` та облікові дані Twilio. -Будь-яку перевірку `ok: false` слід вважати блокером перед тим, як просити агента приєднатися. -Використовуйте `openclaw googlemeet setup --json` для скриптів або машинозчитуваного виводу. -Використовуйте `--transport chrome`, `--transport chrome-node` або `--transport twilio`, щоб попередньо перевірити конкретний транспорт до того, як агент спробує його використати. +Вивід налаштування призначено для читання агентом. Він повідомляє про профіль Chrome, +аудіоміст, прив’язку до Node, відкладений вступ `realtime` і, коли налаштовано делегування Twilio, +чи готові Plugin `voice-call` і облікові дані Twilio. +Будь-яку перевірку `ok: false` слід вважати блокером, перш ніж просити агента приєднатися. +Для сценаріїв або машинозчитуваного виводу використовуйте `openclaw googlemeet setup --json`. +Використовуйте `--transport chrome`, `--transport chrome-node` або `--transport twilio`, +щоб попередньо перевірити конкретний транспорт перед тим, як агент спробує його використати. -Приєднайтеся до зустрічі: +Приєднання до зустрічі: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -95,13 +101,13 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij } ``` -Створіть нову зустріч і приєднайтеся до неї: +Створення нової зустрічі та приєднання до неї: ```bash openclaw googlemeet create --transport chrome-node --mode realtime ``` -Створіть лише URL без приєднання: +Створити лише URL без приєднання: ```bash openclaw googlemeet create --no-join @@ -109,14 +115,26 @@ openclaw googlemeet create --no-join `googlemeet create` має два шляхи: -- Створення через API: використовується, коли налаштовано облікові дані Google Meet OAuth. Це найдетермінованіший шлях, який не залежить від стану UI браузера. -- Резервний варіант через браузер: використовується, коли облікові дані OAuth відсутні. OpenClaw використовує закріплений Chrome Node, відкриває `https://meet.google.com/new`, чекає, поки Google перенаправить на справжній URL із кодом зустрічі, а потім повертає цей URL. Цей шлях вимагає, щоб профіль OpenClaw Chrome на Node уже мав виконаний вхід у Google. - Автоматизація браузера обробляє власний початковий запит Meet до мікрофона; цей запит не вважається помилкою входу в Google. - Потоки приєднання та створення також намагаються повторно використати наявну вкладку Meet перед відкриттям нової. Підбір ігнорує нешкідливі рядки запиту URL, такі як `authuser`, тому повторна спроба агента має сфокусувати вже відкриту зустріч замість створення другої вкладки Chrome. +- Створення через API: використовується, коли налаштовано облікові дані Google Meet OAuth. Це + найдетермінованіший шлях, який не залежить від стану інтерфейсу браузера. +- Резервний шлях через браузер: використовується, коли облікові дані OAuth відсутні. OpenClaw використовує + закріплений Node Chrome, відкриває `https://meet.google.com/new`, чекає, поки Google + перенаправить на справжній URL із кодом зустрічі, а потім повертає цей URL. Цей шлях вимагає, + щоб профіль Chrome OpenClaw на Node вже мав виконаний вхід у Google. + Автоматизація браузера обробляє власний початковий запит Meet на мікрофон; цей запит + не вважається збоєм входу в Google. + Потоки приєднання та створення також намагаються повторно використати наявну вкладку Meet, перш ніж відкривати + нову. Під час зіставлення ігноруються нешкідливі рядки запиту URL, як-от `authuser`, тому + повторна спроба агента має сфокусувати вже відкриту зустріч замість створення другої вкладки Chrome. -Вивід команди/інструмента містить поле `source` (`api` або `browser`), щоб агенти могли пояснити, який шлях було використано. `create` типово приєднується до нової зустрічі та повертає `joined: true` разом із сеансом приєднання. Щоб лише згенерувати URL, використовуйте `create --no-join` у CLI або передайте `"join": false` в інструмент. +Вивід команди/інструмента містить поле `source` (`api` або `browser`), щоб агенти +могли пояснити, який шлях було використано. `create` типово приєднується до нової зустрічі та +повертає `joined: true` разом із сесією приєднання. Щоб лише створити URL, використовуйте +`create --no-join` у CLI або передайте `"join": false` в інструмент. -Або скажіть агенту: "Створи Google Meet, приєднайся до нього з голосом у режимі реального часу та надішли мені посилання". Агент має викликати `google_meet` з `action: "create"`, а потім поділитися поверненим `meetingUri`. +Або скажіть агенту: «Створи Google Meet, приєднайся до нього з голосом realtime і надішли +мені посилання». Агент має викликати `google_meet` з `action: "create"`, +а потім поділитися поверненим `meetingUri`. ```json { @@ -126,21 +144,37 @@ openclaw googlemeet create --no-join } ``` -Для приєднання лише для спостереження/керування браузером встановіть `"mode": "transcribe"`. Це не запускає двосторонній міст моделі реального часу, тому він не відповідатиме голосом у зустрічі. +Для приєднання лише зі спостереженням/керуванням браузером установіть `"mode": "transcribe"`. Це +не запускає дуплексний міст моделі `realtime`, тому агент не говоритиме назад у +зустріч. -Під час сеансів у режимі реального часу статус `google_meet` включає стан браузера та аудіомосту, зокрема `inCall`, `manualActionRequired`, `providerConnected`, `realtimeReady`, `audioInputActive`, `audioOutputActive`, часові мітки останнього вводу/виводу, лічильники байтів і стан закриття мосту. Якщо з’являється безпечний запит сторінки Meet, автоматизація браузера обробляє його, коли може. Вхід, допуск хостом і запити дозволів браузера/ОС повідомляються як ручна дія з причиною та повідомленням, яке агент має передати. +Під час сесій realtime стан `google_meet` включає інформацію про браузер і стан аудіомосту, +зокрема `inCall`, `manualActionRequired`, `providerConnected`, +`realtimeReady`, `audioInputActive`, `audioOutputActive`, часові мітки останнього входу/виходу, +лічильники байтів і стан закриття мосту. Якщо з’являється безпечний запит сторінки Meet, +автоматизація браузера обробляє його, коли це можливо. Запити на вхід, допуск хостом і запити +дозволів браузера/ОС повідомляються як ручна дія з причиною та повідомленням, яке агент має передати. -Chrome приєднується як профіль Chrome, у якому виконано вхід. У Meet виберіть `BlackHole 2ch` для шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого двостороннього аудіо використовуйте окремі віртуальні пристрої або граф у стилі Loopback; одного пристрою BlackHole достатньо для першого smoke-тесту, але може виникати відлуння. +Chrome приєднується як профіль Chrome із виконаним входом. У Meet виберіть `BlackHole 2ch` для +шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого дуплексного аудіо використовуйте +окремі віртуальні пристрої або граф типу Loopback; одного пристрою BlackHole +достатньо для першої smoke-перевірки, але може виникати луна. ### Локальний Gateway + Parallels Chrome -Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM лише для того, щоб VM володіла Chrome. Запустіть Gateway і агента локально, а потім запустіть хост Node у VM. Увімкніть у VM вбудований Plugin один раз, щоб Node анонсував команду Chrome: +Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM +лише для того, щоб VM володіла Chrome. Запустіть Gateway і агента локально, а потім запустіть +хост Node у VM. Один раз увімкніть у VM вбудований Plugin, щоб Node +оголошував команду Chrome: -Що де запускається: +Що працює де: -- Хост Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, провайдер `realtime` і конфігурація Plugin Google Meet. -- macOS VM у Parallels: OpenClaw CLI/хост Node, Google Chrome, SoX, BlackHole 2ch і профіль Chrome з виконаним входом у Google. -- Не потрібно у VM: служба Gateway, конфігурація агента, ключ OpenAI/GPT або налаштування провайдера моделі. +- Хост Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, провайдер realtime + і конфігурація Plugin Google Meet. +- macOS VM у Parallels: OpenClaw CLI/хост Node, Google Chrome, SoX, BlackHole 2ch + і профіль Chrome із виконаним входом у Google. +- Не потрібно у VM: служба Gateway, конфігурація агента, ключ OpenAI/GPT або налаштування + провайдера моделі. Установіть залежності VM: @@ -148,13 +182,13 @@ Chrome приєднується як профіль Chrome, у якому вик brew install blackhole-2ch sox ``` -Перезавантажте VM після встановлення BlackHole, щоб macOS відкрила `BlackHole 2ch`: +Після встановлення BlackHole перезавантажте VM, щоб macOS показала `BlackHole 2ch`: ```bash sudo reboot ``` -Після перезавантаження перевірте, що VM бачить аудіопристрій і команди SoX: +Після перезавантаження переконайтеся, що VM бачить аудіопристрій і команди SoX: ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -173,14 +207,15 @@ openclaw plugins enable google-meet openclaw node run --host --port 18789 --display-name parallels-macos ``` -Якщо `` — це LAN IP і ви не використовуєте TLS, Node відхиляє простий WebSocket, якщо ви явно не дозволите це для цієї довіреної приватної мережі: +Якщо `` — це LAN IP і ви не використовуєте TLS, Node відхиляє +WebSocket без шифрування, якщо ви явно не дозволите це для цієї довіреної приватної мережі: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Використовуйте ту саму змінну середовища, коли встановлюєте Node як LaunchAgent: +Використовуйте ту саму змінну середовища під час встановлення Node як LaunchAgent: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -188,16 +223,19 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це змінна середовища процесу, а не параметр `openclaw.json`. `openclaw node install` зберігає її в середовищі LaunchAgent, якщо вона присутня під час команди встановлення. +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це змінна середовища процесу, а не +параметр `openclaw.json`. `openclaw node install` зберігає її в середовищі LaunchAgent, +коли вона присутня в команді встановлення. -Схваліть Node з хоста Gateway: +Схваліть Node із хоста Gateway: ```bash openclaw devices list openclaw devices approve ``` -Підтвердьте, що Gateway бачить Node і що він анонсує як `googlemeet.chrome`, так і можливість браузера/`browser.proxy`: +Підтвердьте, що Gateway бачить Node і що він оголошує і `googlemeet.chrome`, +і можливість браузера/`browser.proxy`: ```bash openclaw nodes status @@ -233,7 +271,7 @@ openclaw nodes status } ``` -Тепер приєднуйтеся звичайним способом із хоста Gateway: +Тепер приєднуйтесь звичайним способом із хоста Gateway: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -241,69 +279,101 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij або попросіть агента використати інструмент `google_meet` з `transport: "chrome-node"`. -Для однокомандного smoke-тесту, який створює або повторно використовує сеанс, промовляє відому фразу та виводить стан сеансу: +Для smoke-перевірки однією командою, яка створює або повторно використовує сесію, +вимовляє відому фразу й друкує стан сесії: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Під час приєднання автоматизація браузера OpenClaw заповнює ім’я гостя, натискає Join/Ask to join і приймає початковий вибір Meet "Use microphone", коли з’являється цей запит. Під час створення зустрічі лише через браузер вона також може продовжити після цього самого запиту без мікрофона, якщо Meet не показує кнопку використання мікрофона. -Якщо в профілі браузера не виконано вхід, Meet очікує допуску хостом, Chrome потребує дозволу на мікрофон/камеру або Meet застряг на запиті, який автоматизація не змогла розв’язати, результат join/test-speech повідомляє +Під час приєднання автоматизація браузера OpenClaw заповнює ім’я гостя, натискає Join/Ask +to join і приймає початковий вибір Meet «Use microphone», коли з’являється цей запит. +Під час створення зустрічі лише через браузер вона також може продовжити після +того самого запиту без мікрофона, якщо Meet не показує кнопку use-microphone. +Якщо вхід у профіль браузера не виконано, Meet чекає +допуску від хоста, Chrome потребує дозволу на мікрофон/камеру або Meet завис на +запиті, який автоматизація не змогла розв’язати, результат join/test-speech повідомляє `manualActionRequired: true` з `manualActionReason` і -`manualActionMessage`. Агенти мають припинити повторні спроби приєднання, передати це точне повідомлення разом із поточними `browserUrl`/`browserTitle` і повторювати спробу лише після завершення ручної дії в браузері. +`manualActionMessage`. Агенти мають припинити повторні спроби приєднання, +передати саме це повідомлення разом із поточними `browserUrl`/`browserTitle` +і повторювати спробу лише після завершення ручної дії в браузері. -Якщо `chromeNode.node` пропущено, OpenClaw виконує автовибір лише тоді, коли рівно один підключений Node анонсує і `googlemeet.chrome`, і керування браузером. Якщо підключено кілька придатних Node, установіть `chromeNode.node` на id Node, відображуване ім’я або віддалену IP-адресу. +Якщо `chromeNode.node` не вказано, OpenClaw автоматично вибирає Node лише тоді, коли рівно один +підключений Node оголошує і `googlemeet.chrome`, і керування браузером. Якщо +підключено кілька придатних Node, установіть `chromeNode.node` на id Node, +відображуване ім’я або віддалену IP-адресу. -Типові перевірки збоїв: +Поширені перевірки збоїв: -- `Configured Google Meet node ... is not usable: offline`: закріплений Node відомий Gateway, але недоступний. Агенти мають розглядати цей Node як діагностичний стан, а не як придатний хост Chrome, і повідомляти про блокер налаштування замість переходу до іншого транспорту, якщо користувач прямо цього не просив. -- `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, схваліть сполучення та переконайтеся, що у VM було виконано `openclaw plugins enable google-meet` і `openclaw plugins enable browser`. Також підтвердьте, що хост Gateway дозволяє обидві команди Node за допомогою +- `Configured Google Meet node ... is not usable: offline`: закріплений Node + відомий Gateway, але недоступний. Агенти мають розглядати цей Node як + діагностичний стан, а не як придатний хост Chrome, і повідомляти про блокер + налаштування замість переходу до іншого транспорту, якщо користувач явно не попросив про це. +- `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, + схваліть з’єднання та переконайтеся, що у VM було виконано `openclaw plugins enable google-meet` і + `openclaw plugins enable browser`. Також підтвердьте, що + хост Gateway дозволяє обидві команди Node через `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. -- `BlackHole 2ch audio device not found`: установіть `blackhole-2ch` на хості, який перевіряється, і перезавантажте його перед використанням локального аудіо Chrome. -- `BlackHole 2ch audio device not found on the node`: установіть `blackhole-2ch` у VM і перезавантажте VM. -- Chrome відкривається, але не може приєднатися: виконайте вхід у профіль браузера всередині VM або залиште `chrome.guestName` увімкненим для гостьового приєднання. Автоматичне гостьове приєднання використовує автоматизацію браузера OpenClaw через проксі браузера Node; переконайтеся, що конфігурація браузера Node вказує на потрібний профіль, наприклад - `browser.defaultProfile: "user"` або іменований профіль наявного сеансу. -- Дубльовані вкладки Meet: залиште `chrome.reuseExistingTab: true` увімкненим. OpenClaw активує наявну вкладку для того самого URL Meet перед відкриттям нової, а створення зустрічі через браузер повторно використовує вкладку `https://meet.google.com/new`, що вже в процесі, або вкладку запиту облікового запису Google перед відкриттям іншої. -- Немає аудіо: у Meet спрямовуйте мікрофон/динамік через шлях віртуального аудіопристрою, який використовує OpenClaw; використовуйте окремі віртуальні пристрої або маршрутизацію у стилі Loopback для чистого двостороннього аудіо. +- `BlackHole 2ch audio device not found`: установіть `blackhole-2ch` на хості, + який перевіряється, і перезавантажте його перед використанням локального аудіо Chrome. +- `BlackHole 2ch audio device not found on the node`: установіть `blackhole-2ch` + у VM і перезавантажте VM. +- Chrome відкривається, але не може приєднатися: виконайте вхід у профіль браузера всередині VM або + залиште `chrome.guestName` установленим для гостьового приєднання. Автоматичне гостьове приєднання використовує + автоматизацію браузера OpenClaw через проксі браузера Node; переконайтеся, що конфігурація браузера Node + вказує на потрібний профіль, наприклад + `browser.defaultProfile: "user"` або іменований профіль наявної сесії. +- Дубльовані вкладки Meet: залишайте `chrome.reuseExistingTab: true` увімкненим. OpenClaw + активує наявну вкладку для того самого URL Meet перед відкриттям нової, а + створення зустрічі через браузер повторно використовує вкладку `https://meet.google.com/new`, + яка вже триває, або вкладку запиту акаунта Google, замість відкриття ще однієї. +- Немає аудіо: у Meet спрямовуйте мікрофон/динамік через шлях віртуального аудіопристрою, + який використовує OpenClaw; для чистого дуплексного аудіо використовуйте окремі віртуальні пристрої + або маршрутизацію типу Loopback. ## Примітки щодо встановлення -Типовий режим Chrome `realtime` використовує два зовнішні інструменти: +Типовий режим realtime для Chrome використовує два зовнішні інструменти: -- `sox`: аудіоутиліта командного рядка. Plugin використовує її команди `rec` і `play` для типового аудіомосту G.711 mu-law 8 кГц. -- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, через який Chrome/Meet можуть маршрутизувати звук. +- `sox`: утиліта командного рядка для аудіо. Plugin використовує її команди `rec` і `play` + для типового аудіомосту G.711 mu-law 8 кГц. +- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, + через який Chrome/Meet може маршрутизувати звук. -OpenClaw не комплектує і не розповсюджує жоден із цих пакетів. У документації користувачам пропонується встановлювати їх як залежності хоста через Homebrew. SoX ліцензовано як -`LGPL-2.0-only AND GPL-2.0-only`; BlackHole — за GPL-3.0. Якщо ви збираєте інсталятор або appliance, який комплектує BlackHole разом з OpenClaw, перегляньте умови ліцензування BlackHole в апстримі або отримайте окрему ліцензію від Existential Audio. +OpenClaw не постачає і не розповсюджує жоден із цих пакунків. Документація просить користувачів +установлювати їх як залежності хоста через Homebrew. SoX ліцензовано як +`LGPL-2.0-only AND GPL-2.0-only`; BlackHole — за GPL-3.0. Якщо ви створюєте +інсталятор або appliance, що постачає BlackHole разом з OpenClaw, перегляньте +вихідні умови ліцензування BlackHole або отримайте окрему ліцензію від Existential Audio. ## Транспорти ### Chrome Транспорт Chrome відкриває URL Meet у Google Chrome і приєднується як профіль -Chrome, у якому виконано вхід. У macOS Plugin перед запуском перевіряє наявність -`BlackHole 2ch`. Якщо налаштовано, він також запускає команду перевірки стану -аудіомосту та команду запуску перед відкриттям Chrome. Використовуйте `chrome`, -коли Chrome/аудіо працюють на хості Gateway; використовуйте `chrome-node`, -коли Chrome/аудіо працюють на підключеному Node, наприклад у macOS VM Parallels. +Chrome із виконаним входом. На macOS Plugin перевіряє наявність `BlackHole 2ch` перед запуском. +Якщо налаштовано, він також запускає команду перевірки стану аудіомосту та команду запуску +перед відкриттям Chrome. Використовуйте `chrome`, коли Chrome/аудіо працюють на хості Gateway; +використовуйте `chrome-node`, коли Chrome/аудіо працюють на підключеному Node, наприклад у Parallels +macOS VM. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Спрямуйте аудіо мікрофона та динаміка Chrome через локальний аудіоміст -OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднання завершується -помилкою налаштування замість тихого приєднання без аудіошляху. +Спрямуйте аудіо мікрофона й динаміка Chrome через локальний аудіоміст OpenClaw. +Якщо `BlackHole 2ch` не встановлено, приєднання завершується з помилкою налаштування, +а не тихо приєднується без аудіошляху. ### Twilio Транспорт Twilio — це суворий план набору, делегований Plugin Voice Call. Він -не аналізує сторінки Meet у пошуку номерів телефонів. +не аналізує сторінки Meet у пошуку телефонних номерів. -Використовуйте це, коли участь через Chrome недоступна або коли вам потрібен -резервний варіант дозвону телефоном. Google Meet має надавати номер для -телефонного підключення та PIN для зустрічі; OpenClaw не виявляє їх на сторінці Meet. +Використовуйте його, коли участь через Chrome недоступна або коли вам потрібен резервний +варіант дозвону телефоном. Google Meet має показувати номер для телефонного дозвону та PIN для +зустрічі; OpenClaw не знаходить ці дані на сторінці Meet. Увімкніть Plugin Voice Call на хості Gateway, а не на Node Chrome: @@ -316,7 +386,7 @@ OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднан enabled: true, config: { defaultTransport: "chrome-node", - // or set "twilio" if Twilio should be the default + // або встановіть "twilio", якщо Twilio має бути типовим варіантом }, }, "voice-call": { @@ -330,8 +400,8 @@ OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднан } ``` -Надайте облікові дані Twilio через середовище або конфігурацію. Середовище -дозволяє не зберігати секрети в `openclaw.json`: +Надайте облікові дані Twilio через середовище або конфігурацію. Середовище дозволяє +не зберігати секрети в `openclaw.json`: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -339,8 +409,8 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни -конфігурації Plugin не з’являються в уже запущеному процесі Gateway, доки він не перезавантажиться. +Після ввімкнення `voice-call` перезапустіть або перезавантажте Gateway; зміни конфігурації Plugin +не з’являються в уже запущеному процесі Gateway, доки його не буде перезавантажено. Потім перевірте: @@ -350,8 +420,8 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Коли делегування Twilio підключено, `googlemeet setup` включає успішні -перевірки `twilio-voice-call-plugin` і `twilio-voice-call-credentials`. +Коли делегування Twilio налаштовано, `googlemeet setup` містить успішні перевірки +`twilio-voice-call-plugin` і `twilio-voice-call-credentials`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -360,7 +430,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -Використовуйте `--dtmf-sequence`, коли зустріч вимагає спеціальної послідовності: +Використовуйте `--dtmf-sequence`, коли зустріч потребує спеціальної послідовності: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -371,21 +441,20 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth і попередня перевірка -OAuth є необов’язковим для створення посилання Meet, оскільки `googlemeet create` -може перейти на резервний варіант через автоматизацію браузера. Налаштуйте OAuth, -коли вам потрібне офіційне створення через API, розв’язання простору або попередні -перевірки Meet Media API. +OAuth є необов’язковим для створення посилання Meet, оскільки `googlemeet create` може +перейти на резервний шлях через автоматизацію браузера. Налаштуйте OAuth, якщо вам потрібні офіційне створення через API, +визначення простору або перевірки готовності Meet Media API. -Доступ до API Google Meet використовує користувацький OAuth: створіть клієнт OAuth у Google Cloud, -запитайте потрібні області доступу, авторизуйте обліковий запис Google, а потім збережіть -отриманий refresh token у конфігурації Plugin Google Meet або надайте змінні середовища -`OPENCLAW_GOOGLE_MEET_*`. +Доступ до Google Meet API використовує OAuth користувача: створіть клієнт Google Cloud OAuth, +запросіть потрібні області доступу, авторизуйте обліковий запис Google, а потім збережіть +отриманий refresh token у конфігурації Plugin Google Meet або надайте +змінні середовища `OPENCLAW_GOOGLE_MEET_*`. OAuth не замінює шлях приєднання через Chrome. Транспорти Chrome і Chrome-node усе одно приєднуються через профіль Chrome із виконаним входом, BlackHole/SoX -і підключений Node, коли ви використовуєте участь через браузер. OAuth потрібен лише -для офіційного шляху API Google Meet: створення просторів зустрічей, розв’язання просторів -і виконання попередніх перевірок Meet Media API. +і підключений Node, коли ви використовуєте участь через браузер. OAuth потрібен лише для офіційного шляху Google +Meet API: створення просторів зустрічей, визначення просторів і виконання перевірок +готовності Meet Media API. ### Створення облікових даних Google @@ -394,41 +463,41 @@ OAuth не замінює шлях приєднання через Chrome. Тр 1. Створіть або виберіть проєкт Google Cloud. 2. Увімкніть **Google Meet REST API** для цього проєкту. 3. Налаштуйте екран згоди OAuth. - - **Internal** є найпростішим для організації Google Workspace. - - **External** працює для персональних/тестових налаштувань; поки застосунок перебуває в режимі Testing, + - **Internal** — найпростіший варіант для організації Google Workspace. + - **External** підходить для особистих/тестових конфігурацій; поки застосунок перебуває в режимі Testing, додайте кожен обліковий запис Google, який авторизуватиме застосунок, як тестового користувача. 4. Додайте області доступу, які запитує OpenClaw: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` -5. Створіть ідентифікатор клієнта OAuth. +5. Створіть OAuth client ID. - Тип застосунку: **Web application**. - - Авторизований URI перенаправлення: + - Дозволений URI переспрямування: ```text http://localhost:8085/oauth2callback ``` -6. Скопіюйте ідентифікатор клієнта та секрет клієнта. +6. Скопіюйте client ID і client secret. -`meetings.space.created` потрібен для `spaces.create` у Google Meet. -`meetings.space.readonly` дозволяє OpenClaw розв’язувати URL/коди Meet у простори. -`meetings.conference.media.readonly` призначений для попередніх перевірок Meet Media API та роботи з медіа; +`meetings.space.created` потрібен для `spaces.create` Google Meet. +`meetings.space.readonly` дозволяє OpenClaw визначати простори за URL/кодами Meet. +`meetings.conference.media.readonly` потрібен для перевірок готовності Meet Media API і роботи з медіа; Google може вимагати участі в Developer Preview для фактичного використання Media API. -Якщо вам потрібні лише приєднання через Chrome на основі браузера, OAuth можна повністю пропустити. +Якщо вам потрібні лише приєднання через Chrome на основі браузера, можете повністю пропустити OAuth. ### Отримання refresh token -Налаштуйте `oauth.clientId` і, за потреби, `oauth.clientSecret`, або передайте їх як +Налаштуйте `oauth.clientId` і, за бажанням, `oauth.clientSecret`, або передайте їх як змінні середовища, а потім виконайте: ```bash openclaw googlemeet auth login --json ``` -Команда виводить блок конфігурації `oauth` з refresh token. Вона використовує PKCE, -локальний callback на `http://localhost:8085/oauth2callback` і ручний -потік копіювання/вставлення з `--manual`. +Команда виводить блок конфігурації `oauth` із refresh token. Вона використовує PKCE, +зворотний виклик localhost на `http://localhost:8085/oauth2callback` і ручний +режим копіювання/вставлення з `--manual`. Приклади: @@ -438,7 +507,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -Використовуйте ручний режим, коли браузер не може дістатися локального callback: +Використовуйте ручний режим, коли браузер не може звернутися до локального зворотного виклику: ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -446,7 +515,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json --manual ``` -JSON-вивід містить: +Вивід JSON містить: ```json { @@ -482,51 +551,51 @@ JSON-вивід містить: } ``` -Віддавайте перевагу змінним середовища, якщо не хочете зберігати refresh token у конфігурації. +Надавайте перевагу змінним середовища, якщо не хочете зберігати refresh token у конфігурації. Якщо присутні і значення конфігурації, і значення середовища, Plugin спочатку використовує конфігурацію, а потім резервні значення середовища. -Згода OAuth включає створення просторів Meet, доступ на читання просторів Meet і доступ -на читання медіа конференцій Meet. Якщо ви автентифікувалися до появи підтримки -створення зустрічей, повторно виконайте `openclaw googlemeet auth login --json`, щоб refresh token -містив область доступу `meetings.space.created`. +Згода OAuth включає створення просторів Meet, доступ на читання просторів Meet і доступ на читання +медіа конференцій Meet. Якщо ви проходили автентифікацію до появи підтримки +створення зустрічей, знову виконайте `openclaw googlemeet auth login --json`, щоб refresh +token мав область доступу `meetings.space.created`. -### Перевірка OAuth за допомогою doctor +### Перевірка OAuth через doctor -Запустіть doctor OAuth, коли вам потрібна швидка перевірка стану без секретів: +Запустіть doctor для OAuth, коли потрібна швидка перевірка стану без секретів: ```bash openclaw googlemeet doctor --oauth --json ``` -Це не завантажує рантайм Chrome і не вимагає підключеного Node Chrome. Воно -перевіряє, що конфігурація OAuth існує і що refresh token може отримати access token. -JSON-звіт містить лише поля стану, такі як `ok`, `configured`, -`tokenSource`, `expiresAt` і повідомлення перевірок; він не виводить access -token, refresh token або секрет клієнта. +Він не завантажує середовище виконання Chrome і не потребує підключеного Node Chrome. Команда +перевіряє, що конфігурація OAuth існує і що refresh token може отримати access +token. Звіт JSON містить лише поля стану, як-от `ok`, `configured`, +`tokenSource`, `expiresAt`, і повідомлення перевірок; він не виводить access +token, refresh token або client secret. -Типові результати: +Поширені результати: -| Перевірка | Значення | -| -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | Наявні `oauth.clientId` плюс `oauth.refreshToken` або кешований access token. | -| `oauth-token` | Кешований access token усе ще дійсний, або refresh token отримав новий access token. | -| `meet-spaces-get` | Необов’язкова перевірка `--meeting` розв’язала наявний простір Meet. | -| `meet-spaces-create` | Необов’язкова перевірка `--create-space` створила новий простір Meet. | +| Перевірка | Значення | +| --------------------- | --------------------------------------------------------------------------------------- | +| `oauth-config` | Наявні `oauth.clientId` і `oauth.refreshToken` або кешований access token. | +| `oauth-token` | Кешований access token усе ще чинний, або refresh token отримав новий access token. | +| `meet-spaces-get` | Необов’язкова перевірка `--meeting` визначила наявний простір Meet. | +| `meet-spaces-create` | Необов’язкова перевірка `--create-space` створила новий простір Meet. | -Щоб також підтвердити ввімкнення API Google Meet і область доступу `spaces.create`, -виконайте перевірку створення з побічним ефектом: +Щоб також підтвердити ввімкнення Google Meet API і область доступу `spaces.create`, виконайте +перевірку створення з побічним ефектом: ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` створює тимчасовий URL Meet. Використовуйте це, коли потрібно підтвердити, +`--create-space` створює тимчасовий URL Meet. Використовуйте його, коли потрібно підтвердити, що в проєкті Google Cloud увімкнено Meet API і що авторизований обліковий запис має область доступу `meetings.space.created`. -Щоб підтвердити доступ на читання для наявного простору зустрічі: +Щоб підтвердити доступ на читання до наявного простору зустрічі: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json @@ -535,13 +604,13 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij `doctor --oauth --meeting` і `resolve-space` підтверджують доступ на читання до наявного простору, до якого має доступ авторизований обліковий запис Google. `403` від цих перевірок -зазвичай означає, що Google Meet REST API вимкнено, у refresh token після надання згоди -бракує потрібної області доступу або обліковий запис Google не має доступу до цього простору Meet. -Помилка refresh token означає, що потрібно повторно виконати `openclaw googlemeet auth login +зазвичай означає, що Google Meet REST API вимкнено, у погодженого refresh token +немає потрібної області доступу або обліковий запис Google не має доступу до цього простору Meet. +Помилка refresh token означає, що потрібно знову виконати `openclaw googlemeet auth login --json` і зберегти новий блок `oauth`. -Для резервного варіанту через браузер облікові дані OAuth не потрібні. У цьому режимі Google -автентифікація походить із профілю Chrome з виконаним входом на вибраному Node, а не з +Для резервного шляху через браузер облікові дані OAuth не потрібні. У цьому режимі Google +автентифікація походить із профілю Chrome із виконаним входом на вибраному Node, а не з конфігурації OpenClaw. Як резервні підтримуються такі змінні середовища: @@ -555,13 +624,13 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` або `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` або `GOOGLE_MEET_PREVIEW_ACK` -Розв’яжіть URL Meet, код або `spaces/{id}` через `spaces.get`: +Визначте URL Meet, код або `spaces/{id}` через `spaces.get`: ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -Виконайте попередню перевірку перед роботою з медіа: +Запустіть попередню перевірку перед роботою з медіа: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij @@ -576,10 +645,10 @@ openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --outp ``` З `--meeting` команди `artifacts` і `attendance` типово використовують останній запис конференції. -Передайте `--all-conference-records`, якщо вам потрібен кожен збережений запис +Передайте `--all-conference-records`, якщо хочете отримати всі збережені записи для цієї зустрічі. -Пошук у Calendar може розв’язати URL зустрічі з Google Calendar перед читанням +Пошук у Calendar може визначити URL зустрічі з Google Calendar перед читанням артефактів Meet: ```bash @@ -590,10 +659,10 @@ openclaw googlemeet attendance --today --format csv --output attendance.csv ``` `--today` шукає в сьогоднішньому календарі `primary` подію Calendar з -посиланням Google Meet. Використовуйте `--event ` для пошуку подій за відповідним текстом, -а `--calendar ` — для календаря, що не є основним. Пошук у Calendar вимагає -свіжого входу OAuth, який включає область доступу лише для читання подій Calendar. -`calendar-events` попередньо показує відповідні події Meet і позначає подію, яку +посиланням Google Meet. Використовуйте `--event ` для пошуку за відповідним текстом події, а +`--calendar ` — для неосновного календаря. Пошук у Calendar потребує свіжого +входу OAuth, який включає область доступу лише для читання подій Calendar. +`calendar-events` показує попередній перегляд відповідних подій Meet і позначає подію, яку виберуть `latest`, `artifacts`, `attendance` або `export`. Якщо ви вже знаєте id запису конференції, звертайтеся до нього безпосередньо: @@ -604,7 +673,7 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -Запишіть зрозумілий звіт: +Створіть зручний для читання звіт: ```bash openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \ @@ -619,30 +688,31 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -`artifacts` повертає метадані запису конференції, а також метадані ресурсів учасників, записів, -транскриптів, структурованих записів транскрипту та smart-note, коли Google -надає їх для цієї зустрічі. Використовуйте `--no-transcript-entries`, щоб пропустити -пошук записів для великих зустрічей. `attendance` розгортає учасників у -рядки сеансів учасників із часом першої/останньої появи, загальною тривалістю сеансу, -прапорцями запізнення/раннього виходу та об’єднанням дублікатів ресурсів учасників за користувачем із виконаним входом -або відображуваним іменем. Передайте `--no-merge-duplicates`, щоб залишити сирі ресурси учасників -окремими, `--late-after-minutes`, щоб налаштувати виявлення запізнення, і +`artifacts` повертає метадані запису конференції, а також метадані ресурсів учасників, запису, +транскрипту, структурованих записів транскрипту та smart-note, коли +Google надає їх для цієї зустрічі. Використовуйте `--no-transcript-entries`, щоб пропустити +отримання записів для великих зустрічей. `attendance` розгортає учасників у +рядки сесій учасників із часом першої/останньої появи, загальною тривалістю сесії, +прапорцями запізнення/раннього виходу та об’єднанням дубльованих ресурсів учасників за +користувачем із виконаним входом або відображуваним іменем. Передайте `--no-merge-duplicates`, щоб залишити сирі ресурси учасників +окремо, `--late-after-minutes`, щоб налаштувати виявлення запізнення, і `--early-before-minutes`, щоб налаштувати виявлення раннього виходу. -`export` записує папку, що містить `summary.md`, `attendance.csv`, +`export` записує теку, що містить `summary.md`, `attendance.csv`, `transcript.md`, `artifacts.json`, `attendance.json` і `manifest.json`. `manifest.json` фіксує вибраний вхід, параметри експорту, записи конференції, -вихідні файли, кількість, джерело токена, подію Calendar, коли її було використано, і будь-які -попередження про часткове отримання. Передайте `--zip`, щоб також записати переносний архів поруч із папкою. Передайте -`--include-doc-bodies`, щоб експортувати текст пов’язаних Google Docs транскрипту та smart-note через Google Drive `files.export`; для цього потрібен +вихідні файли, лічильники, джерело токена, подію Calendar, якщо її було використано, і будь-які +попередження про часткове отримання. Передайте `--zip`, щоб також записати переносний архів поруч +із текою. Передайте `--include-doc-bodies`, щоб експортувати текст пов’язаних Google Docs +для транскрипту та smart-note через Google Drive `files.export`; для цього потрібен свіжий вхід OAuth, який включає область доступу Drive Meet readonly. Без -`--include-doc-bodies` експорти включають лише метадані Meet і структуровані записи -транскрипту. Якщо Google повертає часткову помилку артефакту, наприклад помилку -переліку smart-note, запису транскрипту або тіла документа Drive, підсумок і -маніфест зберігають попередження замість завершення всього експорту помилкою. +`--include-doc-bodies` експорт містить лише метадані Meet і структуровані записи +транскрипту. Якщо Google повертає частковий збій артефактів, наприклад помилку +переліку smart-note, запису транскрипту або тіла документа Drive, summary і +manifest зберігають попередження замість завершення збоєм усього експорту. Використовуйте `--dry-run`, щоб отримати ті самі дані артефактів/відвідуваності та вивести -JSON маніфесту без створення папки або ZIP. Це корисно перед записом -великого експорту або коли агенту потрібні лише кількості, вибрані записи та +JSON маніфесту без створення теки або ZIP-архіву. Це корисно перед записом +великого експорту або коли агенту потрібні лише лічильники, вибрані записи та попередження. Агенти також можуть створити той самий пакет через інструмент `google_meet`: @@ -657,9 +727,9 @@ JSON маніфесту без створення папки або ZIP. Це к } ``` -Установіть `"dryRun": true`, щоб повернути лише маніфест експорту та пропустити запис файлів. +Установіть `"dryRun": true`, щоб повернути лише маніфест експорту й пропустити запис файлів. -Запустіть захищений live smoke для реальної збереженої зустрічі: +Запустіть захищену live smoke-перевірку проти реальної збереженої зустрічі: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -667,13 +737,13 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Середовище live smoke: +Середовище live smoke-перевірки: - `OPENCLAW_LIVE_TEST=1` вмикає захищені live-тести. - `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` вказує на збережений URL Meet, код або `spaces/{id}`. -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` або `GOOGLE_MEET_CLIENT_ID` надає - client id OAuth. +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` або `GOOGLE_MEET_CLIENT_ID` надає OAuth + client id. - `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` або `GOOGLE_MEET_REFRESH_TOKEN` надає refresh token. - Необов’язково: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`, @@ -681,11 +751,11 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` використовують ті самі резервні назви без префікса `OPENCLAW_`. -Базовий live smoke артефактів/відвідуваності потребує +Базова live smoke-перевірка артефактів/відвідуваності потребує `https://www.googleapis.com/auth/meetings.space.readonly` і `https://www.googleapis.com/auth/meetings.conference.media.readonly`. Пошук у Calendar потребує `https://www.googleapis.com/auth/calendar.events.readonly`. Експорт -тіла документа Drive потребує +тіла документів Drive потребує `https://www.googleapis.com/auth/drive.meet.readonly`. Створіть новий простір Meet: @@ -694,13 +764,13 @@ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts openclaw googlemeet create ``` -Команда виводить новий `meeting uri`, джерело та сеанс приєднання. За наявності облікових даних OAuth -вона використовує офіційний API Google Meet. Без облікових даних OAuth вона -використовує профіль браузера з виконаним входом закріпленого Chrome Node як резервний варіант. Агенти можуть +Команда виводить новий `meeting uri`, джерело та сесію приєднання. За наявності облікових даних OAuth +вона використовує офіційний Google Meet API. Без облікових даних OAuth вона +використовує профіль браузера із виконаним входом на закріпленому Node Chrome як резервний варіант. Агенти можуть використовувати інструмент `google_meet` з `action: "create"`, щоб створити й приєднатися за один крок. Для створення лише URL передайте `"join": false`. -Приклад JSON-виводу з резервного варіанту через браузер: +Приклад виводу JSON із резервного шляху через браузер: ```json { @@ -720,17 +790,17 @@ openclaw googlemeet create } ``` -Якщо резервний варіант через браузер натрапляє на вхід у Google або блокування дозволу Meet до того, -як зможе створити URL, метод Gateway повертає відповідь із помилкою, а -інструмент `google_meet` повертає структуровані деталі замість простого рядка: +Якщо резервний шлях через браузер натрапляє на вхід у Google або блокер дозволів Meet до того, +як він зможе створити URL, метод Gateway повертає відповідь про збій, а інструмент +`google_meet` повертає структуровані деталі замість звичайного рядка: ```json { "source": "browser", - "error": "google-login-required: Sign in to Google in the OpenClaw browser profile, then retry meeting creation.", + "error": "google-login-required: Увійдіть у Google в профілі браузера OpenClaw, а потім повторіть створення зустрічі.", "manualActionRequired": true, "manualActionReason": "google-login-required", - "manualActionMessage": "Sign in to Google in the OpenClaw browser profile, then retry meeting creation.", + "manualActionMessage": "Увійдіть у Google в профілі браузера OpenClaw, а потім повторіть створення зустрічі.", "browser": { "nodeId": "ba0f4e4bc...", "targetId": "tab-1", @@ -741,10 +811,10 @@ openclaw googlemeet create ``` Коли агент бачить `manualActionRequired: true`, він має повідомити -`manualActionMessage` разом із контекстом вузла/вкладки браузера та припинити відкривати нові +`manualActionMessage` разом із контекстом Node/вкладки браузера й припинити відкривати нові вкладки Meet, доки оператор не завершить крок у браузері. -Приклад JSON-виводу зі створення через API: +Приклад виводу JSON зі створення через API: ```json { @@ -765,20 +835,20 @@ openclaw googlemeet create } ``` -Створення Meet типово також приєднує до нього. Транспорт Chrome або Chrome-node усе ще -потребує профілю Google Chrome з виконаним входом, щоб приєднатися через браузер. Якщо -в профілі виконано вихід, OpenClaw повідомляє `manualActionRequired: true` або -помилку резервного варіанту через браузер і просить оператора завершити вхід у Google перед +Створення Meet типово також приєднує до нього. Транспорт Chrome або Chrome-node усе одно +потребує профілю Google Chrome з виконаним входом для приєднання через браузер. Якщо +у профілі не виконано вхід, OpenClaw повідомляє `manualActionRequired: true` або +помилку резервного шляху браузера й просить оператора завершити вхід у Google перед повторною спробою. Установлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш Cloud проєкт, принципал OAuth і учасники зустрічі зареєстровані в Google -Workspace Developer Preview Program для медіа-API Meet. +Workspace Developer Preview Program для Meet media APIs. ## Конфігурація -Поширений шлях Chrome `realtime` потребує лише ввімкненого Plugin, BlackHole, SoX -та ключа провайдера голосу реального часу бекенда. OpenAI є типовим; установіть +Поширений шлях realtime через Chrome потребує лише ввімкненого Plugin, BlackHole, SoX +і ключа бекенд-провайдера голосу `realtime`. OpenAI є типовим; установіть `realtime.provider: "google"`, щоб використовувати Google Gemini Live: ```bash @@ -807,16 +877,16 @@ export GEMINI_API_KEY=... - `defaultTransport: "chrome"` - `defaultMode: "realtime"` -- `chromeNode.node`: необов’язковий id/ім’я/IP вузла для `chrome-node` +- `chromeNode.node`: необов’язковий id/ім’я/IP Node для `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: ім’я, яке використовується на екрані гостя Meet +- `chrome.guestName: "OpenClaw Agent"`: ім’я, що використовується на екрані гостя Meet без виконаного входу -- `chrome.autoJoin: true`: заповнення імені гостя та натискання Join Now у режимі best-effort - через автоматизацію браузера OpenClaw на `chrome-node` +- `chrome.autoJoin: true`: найкраща спроба заповнення імені гостя та натискання Join Now + через автоматизацію браузера OpenClaw у `chrome-node` - `chrome.reuseExistingTab: true`: активувати наявну вкладку Meet замість відкриття дублікатів - `chrome.waitForInCallMs: 20000`: чекати, поки вкладка Meet повідомить про стан in-call, - перш ніж буде запущено вступне повідомлення `realtime` + перед запуском вступу `realtime` - `chrome.audioInputCommand`: команда SoX `rec`, що записує аудіо 8 кГц G.711 mu-law у stdout - `chrome.audioOutputCommand`: команда SoX `play`, що читає аудіо 8 кГц G.711 mu-law @@ -825,8 +895,10 @@ export GEMINI_API_KEY=... - `realtime.toolPolicy: "safe-read-only"` - `realtime.instructions`: короткі усні відповіді з `openclaw_agent_consult` для глибших відповідей -- `realtime.introMessage`: коротка усна перевірка готовності, коли міст - `realtime` підключається; установіть `""`, щоб приєднатися беззвучно +- `realtime.introMessage`: коротка усна перевірка готовності, коли міст realtime + підключається; установіть `""`, щоб приєднуватися беззвучно +- `realtime.agentId`: необов’язковий id агента OpenClaw для + `openclaw_agent_consult`; типово `main` Необов’язкові перевизначення: @@ -845,8 +917,9 @@ export GEMINI_API_KEY=... }, realtime: { provider: "google", + agentId: "jay", toolPolicy: "owner", - introMessage: "Say exactly: I'm here.", + introMessage: "Скажи рівно: I'm here.", providers: { google: { model: "gemini-2.5-flash-native-audio-preview-12-2025", @@ -873,9 +946,9 @@ export GEMINI_API_KEY=... ``` `voiceCall.enabled` типово має значення `true`; із транспортом Twilio він делегує -фактичний PSTN-виклик і DTMF Plugin Voice Call. Якщо `voice-call` не ввімкнено, -Google Meet усе ще може перевірити та зафіксувати план набору, але не може -здійснити виклик Twilio. +фактичний PSTN-виклик і DTMF Plugin Voice Call. Якщо `voice-call` не +увімкнено, Google Meet усе ще може перевіряти й записувати план набору, але не +може виконати дзвінок через Twilio. ## Інструмент @@ -892,64 +965,68 @@ Google Meet усе ще може перевірити та зафіксуват Використовуйте `transport: "chrome"`, коли Chrome працює на хості Gateway. Використовуйте `transport: "chrome-node"`, коли Chrome працює на підключеному Node, наприклад у Parallels -VM. В обох випадках модель `realtime` і `openclaw_agent_consult` працюють на -хості Gateway, тому облікові дані моделі залишаються там. +VM. В обох випадках модель realtime і `openclaw_agent_consult` працюють на +хості Gateway, тож облікові дані моделі залишаються там. -Використовуйте `action: "status"`, щоб перелічити активні сеанси або перевірити ID сеансу. Використовуйте -`action: "speak"` із `sessionId` і `message`, щоб змусити агента `realtime` -говорити негайно. Використовуйте `action: "test_speech"`, щоб створити або повторно використати сеанс, -запустити відому фразу та повернути стан `inCall`, якщо хост Chrome може -його повідомити. Використовуйте `action: "leave"`, щоб позначити сеанс завершеним. +Використовуйте `action: "status"`, щоб перелічити активні сесії або перевірити ID сесії. Використовуйте +`action: "speak"` із `sessionId` і `message`, щоб змусити агента realtime +негайно говорити. Використовуйте `action: "test_speech"`, щоб створити або повторно використати сесію, +запустити відому фразу й повернути стан `inCall`, якщо хост Chrome може його +повідомити. Використовуйте `action: "leave"`, щоб позначити сесію як завершену. -`status` включає стан Chrome, коли доступно: +`status` містить стан Chrome, коли він доступний: -- `inCall`: схоже, що Chrome перебуває всередині виклику Meet -- `micMuted`: стан мікрофона Meet у режимі best-effort +- `inCall`: схоже, Chrome перебуває всередині виклику Meet +- `micMuted`: найкраща оцінка стану мікрофона Meet - `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профіль браузера потребує ручного входу, допуску хостом Meet, дозволів або відновлення керування браузером, перш ніж мовлення зможе працювати -- `providerConnected` / `realtimeReady`: стан голосового мосту реального часу -- `lastInputAt` / `lastOutputAt`: останнє аудіо, отримане від мосту або надіслане до нього +- `providerConnected` / `realtimeReady`: стан голосового мосту realtime +- `lastInputAt` / `lastOutputAt`: час останнього аудіо, отриманого мостом або надісланого до нього ```json { "action": "speak", "sessionId": "meet_...", - "message": "Say exactly: I'm here and listening." + "message": "Скажи рівно: I'm here and listening." } ``` -## Консультація з агентом realtime +## Консультація агента realtime -Режим Chrome `realtime` оптимізовано для живого голосового циклу. Провайдер голосу -реального часу чує аудіо зустрічі та говорить через налаштований аудіоміст. -Коли моделі `realtime` потрібні глибші міркування, актуальна інформація або звичайні +Режим realtime для Chrome оптимізовано для живого голосового циклу. Провайдер голосу realtime +чує аудіо зустрічі й говорить через налаштований аудіоміст. +Коли моделі realtime потрібні глибші міркування, актуальна інформація або звичайні інструменти OpenClaw, вона може викликати `openclaw_agent_consult`. -Інструмент консультації запускає звичайного агента OpenClaw у фоновому режимі з контекстом -нещодавнього транскрипту зустрічі та повертає лаконічну усну відповідь у голосовий сеанс -реального часу. Потім голосова модель може озвучити цю відповідь назад у зустріч. -Він використовує той самий спільний інструмент консультації реального часу, що й Voice Call. +Інструмент консультації запускає звичайного агента OpenClaw у фоновому режимі з недавнім +контекстом транскрипту зустрічі й повертає стислу усну відповідь до голосової сесії realtime. +Потім голосова модель може озвучити цю відповідь назад у зустріч. +Він використовує той самий спільний інструмент консультації realtime, що й Voice Call. + +Типово консультації виконуються для агента `main`. Установіть `realtime.agentId`, якщо +канал Meet має консультуватися з виділеним робочим простором агента OpenClaw, типовими значеннями моделі, +політикою інструментів, пам’яттю та історією сесій. `realtime.toolPolicy` керує запуском консультації: -- `safe-read-only`: надати інструмент консультації та обмежити звичайного агента +- `safe-read-only`: відкривати інструмент консультації та обмежувати звичайного агента інструментами `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. -- `owner`: надати інструмент консультації та дозволити звичайному агенту використовувати +- `owner`: відкривати інструмент консультації та дозволяти звичайному агенту використовувати звичайну політику інструментів агента. -- `none`: не надавати інструмент консультації моделі голосу `realtime`. +- `none`: не відкривати інструмент консультації для голосової моделі realtime. -Ключ сеансу консультації має область дії в межах кожного сеансу Meet, тому подальші виклики консультації +Ключ сесії консультації має область дії в межах кожної сесії Meet, тому подальші виклики консультації можуть повторно використовувати попередній контекст консультації під час тієї самої зустрічі. -Щоб примусово виконати усну перевірку готовності після того, як Chrome повністю приєднається до виклику: +Щоб примусово виконати усну перевірку готовності після того, як Chrome повністю приєднався до виклику: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Для повного smoke-тесту приєднання та мовлення: +Для повної smoke-перевірки приєднання та мовлення: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -957,7 +1034,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: I'm here and listening." ``` -## Контрольний список live-тесту +## Контрольний список live-тестування Використовуйте цю послідовність перед передачею зустрічі агенту без нагляду: @@ -971,11 +1048,11 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ Очікуваний стан Chrome-node: -- `googlemeet setup` повністю зелений. -- `googlemeet setup` включає `chrome-node-connected`, коли `chrome-node` є - типовим транспортом або коли закріплено вузол. -- `nodes status` показує, що вибраний вузол підключений. -- Вибраний вузол анонсує і `googlemeet.chrome`, і `browser.proxy`. +- У `googlemeet setup` усі перевірки зелені. +- `googlemeet setup` містить `chrome-node-connected`, коли `chrome-node` є + типовим транспортом або коли Node закріплено. +- `nodes status` показує, що вибраний Node підключено. +- Вибраний Node оголошує і `googlemeet.chrome`, і `browser.proxy`. - Вкладка Meet приєднується до виклику, а `test-speech` повертає стан Chrome з `inCall: true`. @@ -991,11 +1068,11 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Це доводить, що Plugin Gateway завантажено, вузол VM підключено з -поточним токеном, а аудіоміст Meet доступний ще до того, як агент відкриє -реальну вкладку зустрічі. +Це підтверджує, що Plugin Gateway завантажено, Node VM підключено з +поточним токеном, а аудіоміст Meet доступний до того, як агент відкриє +справжню вкладку зустрічі. -Для smoke-тесту Twilio використовуйте зустріч, яка надає деталі телефонного підключення: +Для smoke-перевірки Twilio використовуйте зустріч, яка показує деталі телефонного дозвону: ```bash openclaw googlemeet setup @@ -1007,17 +1084,17 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Очікуваний стан Twilio: -- `googlemeet setup` включає зелені перевірки `twilio-voice-call-plugin` і +- `googlemeet setup` містить зелені перевірки `twilio-voice-call-plugin` і `twilio-voice-call-credentials`. - `voicecall` доступний у CLI після перезавантаження Gateway. -- Повернений сеанс має `transport: "twilio"` і `twilio.voiceCallId`. +- Повернена сесія має `transport: "twilio"` і `twilio.voiceCallId`. - `googlemeet leave ` завершує делегований голосовий виклик. -## Усунення несправностей +## Усунення неполадок ### Агент не бачить інструмент Google Meet -Переконайтеся, що Plugin увімкнено в конфігурації Gateway, і перезавантажте Gateway: +Підтвердьте, що Plugin увімкнено в конфігурації Gateway, і перезавантажте Gateway: ```bash openclaw plugins list | grep google-meet @@ -1025,11 +1102,12 @@ openclaw googlemeet setup ``` Якщо ви щойно змінили `plugins.entries.google-meet`, перезапустіть або перезавантажте Gateway. -Запущений агент бачить лише інструменти Plugin, зареєстровані поточним процесом Gateway. +Запущений агент бачить лише інструменти Plugin, зареєстровані поточним процесом +Gateway. -### Немає підключеного вузла з підтримкою Google Meet +### Немає підключеного Node з підтримкою Google Meet -На хості вузла виконайте: +На хості Node виконайте: ```bash openclaw plugins enable google-meet @@ -1038,7 +1116,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -На хості Gateway схваліть вузол і перевірте команди: +На хості Gateway схваліть Node і перевірте команди: ```bash openclaw devices list @@ -1046,8 +1124,8 @@ openclaw devices approve openclaw nodes status ``` -Вузол має бути підключений і містити `googlemeet.chrome` та `browser.proxy`. -Конфігурація Gateway має дозволяти ці команди вузла: +Node має бути підключений і містити `googlemeet.chrome` та `browser.proxy`. +Конфігурація Gateway має дозволяти ці команди Node: ```json5 { @@ -1059,9 +1137,9 @@ openclaw nodes status } ``` -Якщо `googlemeet setup` завершується невдачею для `chrome-node-connected` або журнал Gateway повідомляє -`gateway token mismatch`, перевстановіть або перезапустіть вузол із поточним токеном Gateway. -Для LAN Gateway це зазвичай означає: +Якщо `googlemeet setup` не проходить `chrome-node-connected` або журнал Gateway повідомляє +`gateway token mismatch`, перевстановіть або перезапустіть Node з поточним токеном +Gateway. Для LAN Gateway це зазвичай означає: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -1072,7 +1150,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -Потім перезавантажте службу вузла і знову виконайте: +Потім перезавантажте службу Node і знову виконайте: ```bash openclaw googlemeet setup @@ -1081,57 +1159,56 @@ openclaw nodes status --connected ### Браузер відкривається, але агент не може приєднатися -Запустіть `googlemeet test-speech` і перевірте повернений стан Chrome. Якщо він -повідомляє `manualActionRequired: true`, покажіть `manualActionMessage` оператору +Запустіть `googlemeet test-speech` і перевірте повернутий стан Chrome. Якщо він +повідомляє `manualActionRequired: true`, покажіть оператору `manualActionMessage` і припиніть повторні спроби, доки дію в браузері не буде завершено. -Типові ручні дії: +Поширені ручні дії: - Увійти в профіль Chrome. - Допустити гостя з облікового запису хоста Meet. -- Надати Chrome дозволи на мікрофон/камеру, коли з’являється рідний - запит дозволу Chrome. -- Закрити або виправити завислий діалог дозволу Meet. +- Надати Chrome дозволи на мікрофон/камеру, коли з’являється власний запит дозволу Chrome. +- Закрити або відновити зависле діалогове вікно дозволів Meet. -Не повідомляйте "not signed in" лише тому, що Meet показує "Do you want people to -hear you in the meeting?" Це проміжний екран вибору аудіо Meet; OpenClaw -натискає **Use microphone** через автоматизацію браузера, коли це можливо, і продовжує -чекати реального стану зустрічі. Для резервного створення лише через браузер OpenClaw -може натискати **Continue without microphone**, оскільки створення URL не потребує -аудіошляху `realtime`. +Не повідомляйте «вхід не виконано» лише тому, що Meet показує «Do you want people to +hear you in the meeting?». Це проміжний екран вибору аудіо Meet; OpenClaw +натискає **Use microphone** через автоматизацію браузера, коли це можливо, і далі чекає +справжнього стану зустрічі. Для резервного шляху створення лише через браузер OpenClaw +може натиснути **Continue without microphone**, оскільки створення URL не потребує +аудіошляху realtime. ### Не вдається створити зустріч -`googlemeet create` спочатку використовує endpoint `spaces.create` API Google Meet, +`googlemeet create` спочатку використовує кінцеву точку Google Meet API `spaces.create`, коли налаштовано облікові дані OAuth. Без облікових даних OAuth він переходить -на браузер закріпленого Chrome Node. Переконайтеся: +на резервний шлях через браузер закріпленого Node Chrome. Підтвердьте: - Для створення через API: налаштовано `oauth.clientId` і `oauth.refreshToken`, або присутні відповідні змінні середовища `OPENCLAW_GOOGLE_MEET_*`. - Для створення через API: refresh token було отримано після додавання - підтримки створення. У старіших токенах може бракувати області доступу `meetings.space.created`; повторно виконайте + підтримки створення. Старіші токени можуть не мати області доступу `meetings.space.created`; повторно виконайте `openclaw googlemeet auth login --json` і оновіть конфігурацію Plugin. -- Для резервного варіанту через браузер: `defaultTransport: "chrome-node"` і - `chromeNode.node` вказують на підключений вузол із `browser.proxy` і +- Для резервного шляху через браузер: `defaultTransport: "chrome-node"` і + `chromeNode.node` вказують на підключений Node з `browser.proxy` і `googlemeet.chrome`. -- Для резервного варіанту через браузер: профіль OpenClaw Chrome на цьому вузлі має виконаний вхід +- Для резервного шляху через браузер: профіль Chrome OpenClaw на цьому Node має виконаний вхід у Google і може відкрити `https://meet.google.com/new`. -- Для резервного варіанту через браузер: повторні спроби повторно використовують наявну вкладку `https://meet.google.com/new` - або вкладку запиту облікового запису Google перед відкриттям нової вкладки. Якщо агент перевищив час очікування, - повторіть виклик інструмента, а не відкривайте вручну іншу вкладку Meet. -- Для резервного варіанту через браузер: якщо інструмент повертає `manualActionRequired: true`, використовуйте +- Для резервного шляху через браузер: повторні спроби повторно використовують наявну вкладку `https://meet.google.com/new` + або вкладку запиту облікового запису Google перед відкриттям нової. Якщо агент завершився за тайм-аутом, + повторіть виклик інструмента замість ручного відкриття ще однієї вкладки Meet. +- Для резервного шляху через браузер: якщо інструмент повертає `manualActionRequired: true`, використовуйте повернені `browser.nodeId`, `browser.targetId`, `browserUrl` і - `manualActionMessage`, щоб скерувати оператора. Не повторюйте спроби в циклі, доки цю + `manualActionMessage`, щоб підказати оператору потрібну дію. Не повторюйте спроби в циклі, доки цю дію не буде завершено. -- Для резервного варіанту через браузер: якщо Meet показує "Do you want people to hear you in the - meeting?", залиште вкладку відкритою. OpenClaw має натиснути **Use microphone** або, для - резервного створення лише URL, **Continue without microphone** через автоматизацію - браузера й продовжити чекати згенерований URL Meet. Якщо це не вдається, у +- Для резервного шляху через браузер: якщо Meet показує «Do you want people to hear you in the + meeting?», залиште вкладку відкритою. OpenClaw має натиснути **Use microphone** або, для + резервного шляху створення лише URL, **Continue without microphone** через автоматизацію + браузера й продовжити чекати згенерований URL Meet. Якщо цього не вдається зробити, у помилці має згадуватися `meet-audio-choice-required`, а не `google-login-required`. ### Агент приєднується, але не говорить -Перевірте шлях `realtime`: +Перевірте шлях realtime: ```bash openclaw googlemeet setup @@ -1139,27 +1216,27 @@ openclaw googlemeet doctor ``` Використовуйте `mode: "realtime"` для прослуховування/зворотного мовлення. `mode: "transcribe"` навмисно -не запускає двосторонній голосовий міст `realtime`. +не запускає дуплексний голосовий міст realtime. Також перевірте: -- На хості Gateway доступний ключ провайдера `realtime`, наприклад +- На хості Gateway доступний ключ провайдера realtime, наприклад `OPENAI_API_KEY` або `GEMINI_API_KEY`. -- `BlackHole 2ch` видимий на хості Chrome. +- `BlackHole 2ch` видно на хості Chrome. - `rec` і `play` існують на хості Chrome. - Мікрофон і динамік Meet спрямовано через шлях віртуального аудіо, який використовує OpenClaw. -`googlemeet doctor [session-id]` виводить сеанс, вузол, стан in-call, -причину ручної дії, підключення провайдера `realtime`, `realtimeReady`, активність -входу/виходу аудіо, часові мітки останнього аудіо, лічильники байтів і URL браузера. +`googlemeet doctor [session-id]` виводить сесію, Node, стан in-call, +причину ручної дії, підключення провайдера realtime, `realtimeReady`, аудіоактивність +входу/виходу, часові мітки останнього аудіо, лічильники байтів і URL браузера. Використовуйте `googlemeet status [session-id]`, коли потрібен сирий JSON. Використовуйте `googlemeet doctor --oauth`, коли потрібно перевірити оновлення OAuth Google Meet -без розкриття токенів; додайте `--meeting` або `--create-space`, коли також потрібен -доказ API Google Meet. +без показу токенів; додайте `--meeting` або `--create-space`, коли також потрібне +підтвердження Google Meet API. -Якщо в агента вийшов тайм-аут і ви бачите, що вкладка Meet уже відкрита, перевірте цю вкладку -без відкриття нової: +Якщо агент завершився за тайм-аутом і ви бачите вже відкриту вкладку Meet, перевірте цю вкладку, +не відкриваючи іншу: ```bash openclaw googlemeet recover-tab @@ -1169,19 +1246,19 @@ openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij Еквівалентна дія інструмента — `recover_current_tab`. Вона фокусує і перевіряє наявну вкладку Meet для вибраного транспорту. З `chrome` вона використовує локальне керування браузером через Gateway; з `chrome-node` вона використовує налаштований -Chrome Node. Вона не відкриває нову вкладку і не створює новий сеанс; вона повідомляє -про поточний блокер, такий як вхід, допуск, дозволи або стан вибору аудіо. -Команда CLI звертається до налаштованого Gateway, тому Gateway має бути запущений; -`chrome-node` також вимагає, щоб Chrome Node був підключений. +Node Chrome. Вона не відкриває нову вкладку й не створює нову сесію; натомість повідомляє про +поточний блокер, як-от вхід, допуск, дозволи або стан вибору аудіо. +Команда CLI звертається до налаштованого Gateway, тож Gateway має бути запущений; +`chrome-node` також вимагає, щоб Node Chrome був підключений. -### Перевірки налаштування Twilio завершуються невдачею +### Не проходять перевірки налаштування Twilio -`twilio-voice-call-plugin` завершується невдачею, коли `voice-call` не дозволено або не ввімкнено. +`twilio-voice-call-plugin` не проходить, коли `voice-call` не дозволено або не ввімкнено. Додайте його до `plugins.allow`, увімкніть `plugins.entries.voice-call` і перезавантажте Gateway. -`twilio-voice-call-credentials` завершується невдачею, коли в бекенді Twilio відсутні account -SID, auth token або номер виклику. Установіть їх на хості Gateway: +`twilio-voice-call-credentials` не проходить, коли в бекенді Twilio відсутні account +SID, auth token або номер абонента. Установіть це на хості Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1197,23 +1274,23 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` типово виконує лише перевірку готовності. Щоб виконати dry-run для конкретного номера: +`voicecall smoke` типово виконує лише перевірку готовності. Щоб зробити dry-run для конкретного номера: ```bash openclaw voicecall smoke --to "+15555550123" ``` Додавайте `--yes` лише тоді, коли ви свідомо хочете здійснити реальний вихідний -сповіщувальний виклик: +сповіщувальний дзвінок: ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### Виклик Twilio починається, але ніколи не входить до зустрічі +### Дзвінок Twilio починається, але ніколи не входить у зустріч -Переконайтеся, що подія Meet надає деталі телефонного підключення. Передайте точний номер -для дозвону та PIN або спеціальну послідовність DTMF: +Підтвердьте, що подія Meet показує деталі телефонного дозвону. Передайте точний номер для дозвону +та PIN або спеціальну послідовність DTMF: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1227,29 +1304,29 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## Примітки -Офіційний медіа-API Google Meet орієнтований на отримання, тому для мовлення в дзвінку Meet -усе ще потрібен шлях учасника. Цей Plugin зберігає цю межу видимою: +Офіційний media API Google Meet орієнтований на отримання, тому мовлення в дзвінок Meet +усе одно потребує шляху участі. Цей Plugin робить цю межу видимою: Chrome обробляє участь через браузер і локальну маршрутизацію аудіо; Twilio обробляє участь через телефонний дозвін. -Режим Chrome `realtime` потребує одного з варіантів: +Режиму realtime для Chrome потрібне одне з такого: - `chrome.audioInputCommand` плюс `chrome.audioOutputCommand`: OpenClaw керує - мостом моделі `realtime` і передає аудіо 8 кГц G.711 mu-law між цими - командами та вибраним провайдером голосу `realtime`. + мостом моделі realtime і передає аудіо 8 кГц G.711 mu-law між цими + командами та вибраним провайдером голосу realtime. - `chrome.audioBridgeCommand`: зовнішня команда мосту керує всім локальним аудіошляхом і має завершитися після запуску або перевірки свого демона. -Для чистого двостороннього аудіо маршрутизуйте вихід Meet і мікрофон Meet через окремі -віртуальні пристрої або граф віртуальних пристроїв у стилі Loopback. Один спільний -пристрій BlackHole може повертати інших учасників луною назад у виклик. +Для чистого дуплексного аудіо маршрутизуйте вивід Meet і мікрофон Meet через окремі +віртуальні пристрої або граф віртуальних пристроїв типу Loopback. Один спільний +пристрій BlackHole може повертати голоси інших учасників назад у дзвінок. -`googlemeet speak` запускає активний аудіоміст `realtime` для сеансу Chrome. -`googlemeet leave` зупиняє цей міст. Для сеансів Twilio, делегованих через Plugin Voice Call, -`leave` також завершує базовий голосовий виклик. +`googlemeet speak` запускає активний аудіоміст realtime для сесії Chrome. +`googlemeet leave` зупиняє цей міст. Для сесій Twilio, делегованих +через Plugin Voice Call, `leave` також завершує базовий голосовий виклик. ## Пов’язане -- [Plugin Voice call](/uk/plugins/voice-call) +- [Plugin Voice Call](/uk/plugins/voice-call) - [Режим talk](/uk/nodes/talk) - [Створення Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index e0b5af6bf..ef97be4a3 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -2,52 +2,63 @@ read_when: - Ви створюєте Plugin для OpenClaw - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) -title: маніфест Plugin +summary: Маніфест Plugin + вимоги до схеми JSON (сувора валідація конфігурації) +title: Маніфест Plugin x-i18n: - generated_at: "2026-04-26T08:15:41Z" + generated_at: "2026-04-27T08:08:31Z" model: gpt-5.4 provider: openai - source_hash: b86920ad774c5ef4ace7b546ef44e5b087a8ca694dea622ddb440258ffff4237 + source_hash: 9d6e1da1cc57f6ba89ef511b01636439dd34f0b847a306b96271ccf9c2b878d4 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка призначена лише для **рідного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. -Сумісні структури пакетів описані в [Пакети Plugin](/uk/plugins/bundles). +Для сумісних макетів пакетів див. [Пакети Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфесту: -- пакет Codex: `.codex-plugin/plugin.json` -- пакет Claude: `.claude-plugin/plugin.json` або стандартна структура компонента Claude без маніфесту -- пакет Cursor: `.cursor-plugin/plugin.json` +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude + без маніфесту +- Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці структури пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять +валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skills, корені команд Claude, стандартні значення Claude-пакета з `settings.json`, стандартні значення LSP для Claude-пакета та підтримувані набори хуків, якщо структура відповідає очікуванням середовища виконання OpenClaw. +Для сумісних пакетів OpenClaw наразі читає метадані пакета разом з оголошеними +коренями Skills, коренями команд Claude, типовими значеннями `settings.json` для пакетів Claude, +типовими значеннями LSP для пакетів Claude та підтримуваними наборами хуків, коли макет відповідає +очікуванням runtime 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**. Усе нижче має бути достатньо легким для перевірки без запуску +runtime Plugin. **Використовуйте його для:** - ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу й налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) - підказок активації для поверхонь control-plane -- володіння скороченими сімействами моделей +- скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації для конкретних каналів, об’єднаних у поверхні каталогу та валідації +- метаданих QA runner, які спільний хост `openclaw qa` може перевіряти +- метаданих конфігурації для конкретних каналів, об’єднаних у каталог і поверхні валідації -**Не використовуйте його для:** реєстрації поведінки середовища виконання, оголошення точок входу коду або метаданих встановлення npm. Вони належать коду вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки runtime, оголошення +точок входу коду або метаданих встановлення npm. Це належить коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -68,7 +79,7 @@ OpenClaw також автоматично визначає ці структу { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "Плагін провайдера OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -96,19 +107,19 @@ OpenClaw також автоматично визначає ці структу "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Ключ API OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Ключ API OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Ключ API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -127,68 +138,72 @@ OpenClaw також автоматично визначає ці структу ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Не вказуйте його або задайте будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього 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. Це контракт control-plane для майбутнього доступного лише для читання списку, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | -| `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 runner, які спільний хост `openclaw qa` використовує до завантаження середовища виконання Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Полегшені стандартні значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту і об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного runtime Plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту і використовуються для автозавантаження Plugin до запуску runtime. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього читання списків, онбордингу, вибору моделей, псевдонімів і приховування без завантаження runtime Plugin. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей Plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких слід перевіряти синтетичний хук автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або стан облікових даних середовища. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це впродовж періоду зворотної сумісності. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, що спільно використовує базовий ключ API провайдера та профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легковагові метадані env для каналів, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, ініційованого провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактична поведінка все ще належить runtime Plugin. | +| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime Plugin. | +| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, що використовуються спільним хостом `openclaw qa` до завантаження runtime Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення для розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, що належать маніфесту й об’єднуються з поверхнями виявлення та валідації до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | +| `description` | Ні | `string` | Короткий опис, який показується на поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки про чутливість для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw читає це до завантаження середовища виконання провайдера. -Списки налаштування провайдерів використовують ці варіанти з маніфесту, варіанти налаштування, похідні від дескрипторів, і метадані каталогу встановлення без завантаження середовища виконання провайдера. +OpenClaw читає це до завантаження runtime провайдера. +Списки налаштування провайдера використовують ці варіанти маніфесту, варіанти +налаштування, отримані з дескриптора, і метадані каталогу встановлення без +завантаження runtime провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| `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"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| -------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `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 володіє назвою runtime-команди, яку користувачі можуть +помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду runtime Plugin. ```json { @@ -202,22 +217,37 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для CLI-операцій, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як команду чату зі слешем, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо така існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може недорого оголосити, які події control-plane мають включати його в план активації/завантаження. +Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane +мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку середовища виконання, не замінює `register(...)` і не гарантує, що код Plugin уже було виконано. Планувальник активації використовує ці поля, щоб звузити перелік кандидатів Plugin перед поверненням до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє +поведінку runtime, не замінює `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` призначений лише для вбудованих ідентифікаторів harness агента, які ще не мають поля володіння. +Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте +`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, +коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових +підказок планувальнику, які не можна подати через ці поля володіння. +Для псевдонімів runtime CLI, таких як `claude-cli`, +`codex-cli` або `google-gemini-cli`, використовуйте `cliBackends` верхнього рівня; `activation.onAgentHarnesses` призначене лише для +вбудованих ідентифікаторів harness агента, які ще не мають поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/Plugin. Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тож відсутність метаданих активації зазвичай лише впливає на продуктивність; це не повинно змінювати коректність, доки ще існують застарілі резервні механізми володіння з маніфесту. +Цей блок — лише метадані. Він не реєструє поведінку runtime і не +замінює `register(...)`, `setupEntry` чи інші точки входу runtime/Plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тож +відсутні метадані активації зазвичай впливають лише на продуктивність; +це не має змінювати коректність, доки ще існують застарілі резервні варіанти володіння маніфестом. ```json { @@ -231,51 +261,61 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin у плани активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих harness агента, які мають включати цей Plugin у плани активації/завантаження. Для псевдонімів CLI-бекенду використовуйте верхньорівневий `cliBackends`. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin у плани активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin у плани активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin у плани активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються під час планування активації control-plane. Якщо можливо, надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори runtime вбудованих harness агента, які мають включати цей Plugin до планів активації/завантаження. Для псевдонімів backend CLI використовуйте `cliBackends` верхнього рівня. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control-plane. За можливості віддавайте перевагу вужчим полям. | -Поточні живі споживачі: +Поточні активні споживачі: -- CLI-планування, запущене командою, повертається до застарілих +- планування CLI, ініційоване командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску agent-runtime використовує `activation.onAgentHarnesses` для - вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI -- планування setup/каналу, запущене каналом, повертається до застарілого володіння `channels[]`, +- планування запуску runtime агента використовує `activation.onAgentHarnesses` для + вбудованих harness і `cliBackends[]` верхнього рівня для псевдонімів runtime CLI +- планування setup/каналів, ініційоване каналом, повертається до застарілого володіння `channels[]`, якщо явні метадані активації каналу відсутні -- планування setup/середовища виконання, запущене провайдером, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні +- планування setup/runtime, ініційоване провайдером, повертається до застарілого + володіння `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 додає один або кілька transport runner під +спільним коренем `openclaw qa`. Тримайте ці метадані легковаговими й статичними; фактичною +реєстрацією CLI все ще керує runtime Plugin через легковагову +поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" + "description": "Запустити live QA lane Matrix на базі Docker проти одноразового homeserver" } ] } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | ---------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні дешеві метадані, що належать Plugin, до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, +що належать Plugin, до завантаження runtime. ```json { @@ -294,47 +334,72 @@ OpenClaw читає це до завантаження середовища ви } ``` -Верхньорівневий `cliBackends` залишається чинним і надалі описує CLI-бекенди інференсу. `setup.cliBackends` — це поверхня дескриптора, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише метаданими. +`cliBackends` верхнього рівня залишається валідним і далі описує +backend CLI inference. `setup.cliBackends` — це поверхня дескриптора, специфічна для setup, +для потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо вказано, `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку descriptor-first для виявлення setup. Якщо дескриптор лише звужує кандидатний Plugin, а setup усе ще потребує багатших хуків середовища виконання на етапі setup, задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +Коли вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною +поверхнею пошуку setup за принципом “спочатку дескриптор” для виявлення setup. Якщо дескриптор лише +звужує кандидат Plugin, а setup усе ще потребує багатших runtime-хуків часу налаштування, +встановіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до узагальнених пошуків автентифікації провайдера та змінних середовища. `providerAuthEnvVars` і далі підтримується через адаптер сумісності протягом перехідного періоду відмови, але невбудовані Plugins, які досі його використовують, отримують діагностику маніфесту. Нові Plugins мають розміщувати метадані змінних середовища для setup/статусу в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та +env-змінних. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності +протягом періоду зворотної сумісності, але невбудовані Plugin, які досі його використовують, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу +в `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` вказує, що середовище виконання setup не потрібне. Явні записи `providerAuthChoices` і далі мають перевагу для користувацьких міток, прапорців CLI, області онбордингу та метаданих асистента. +OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, +коли запис setup недоступний або коли `setup.requiresRuntime: false` +оголошує runtime setup непотрібним. Явні записи `providerAuthChoices` залишаються +пріоритетними для власних міток, прапорців CLI, області онбордингу та метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на основі дескриптора і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо Plugin, що має працювати лише через дескриптор, усе ж постачає один із цих записів середовища виконання setup, OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущене `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugins, які додали дескриптори без цього прапорця, не ламалися. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw розглядає явне `false` як контракт лише на рівні дескрипторів +і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо +Plugin, що працює лише через дескриптори, все ж постачає один із цих runtime-записів setup, +OpenClaw повідомляє додаткову діагностику й надалі ігнорує його. Якщо +`requiresRuntime` пропущено, зберігається застаріла резервна поведінка, щоб наявні Plugin, +які додали дескриптори без цього прапорця, не зламалися. -Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед усіх виявлених Plugins. Неоднозначне володіння завершується безпечною відмовою замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані +значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед +усіх виявлених Plugin. Неоднозначне володіння завершується відмовою без вибору +переможця за порядком виявлення. -Коли середовище виконання setup все ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо `setup-api` реєструє провайдера або CLI-бекенд, який не оголошено в дескрипторах маніфесту, або якщо дескриптор не має відповідної реєстрації середовища виконання. Ці діагностики є додатковими і не відхиляють застарілі Plugins. +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про +розходження дескрипторів, якщо `setup-api` реєструє провайдера або backend CLI, які +не оголошені в дескрипторах маніфесту, або якщо для дескриптора немає відповідної +runtime-реєстрації. Ця діагностика є додатковою і не відхиляє застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, доступний під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. | -| `envVars` | Ні | `string[]` | Змінні середовища, які узагальнені поверхні setup/статусу можуть перевіряти до завантаження середовища виконання Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | ----------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор провайдера, що показується під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env-змінні, які загальні поверхні setup/статусу можуть перевіряти до завантаження runtime Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдера, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів на етапі setup, які використовуються для descriptor-first пошуку setup. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи setup усе ще потребує виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, що показуються під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup за принципом “спочатку дескриптор”. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup після пошуку за дескриптором виконання `setup-api`. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення. ```json { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "Ключ API", + "help": "Використовується для запитів OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -342,20 +407,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 може +прочитати без імпорту runtime Plugin. ```json { @@ -371,6 +437,7 @@ OpenClaw також може виводити прості варіанти setu "videoGenerationProviders": ["qwen"], "webFetchProviders": ["firecrawl"], "webSearchProviders": ["gemini"], + "migrationProviders": ["hermes"], "tools": ["firecrawl_search", "firecrawl_scrape"] } } @@ -378,31 +445,47 @@ OpenClaw також може виводити прості варіанти setu Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ------------------------------------------------------------------------ | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень Codex app-server, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Ідентифікатори середовища виконання, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чиї зовнішні хуки профілів автентифікації належать цьому Plugin. | -| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів embedding для пам’яті, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ---------------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик extension app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований 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[]` | Ідентифікатори провайдерів вебпошуку, якими володіє цей Plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | | `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для перевірок контрактів вбудованих компонентів. | -`contracts.embeddedExtensionFactories` збережено для фабрик розширень лише для вбудованого Codex app-server. Вбудовані перетворення результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugins не можуть реєструвати middleware результатів інструментів, оскільки цей seam може переписувати результати інструментів із високим рівнем довіри до того, як модель їх побачить. +`contracts.embeddedExtensionFactories` збережено для вбудованих фабрик +extension app-server лише для Codex. Вбудовані трансформації результатів інструментів мають +оголошувати `contracts.agentToolResultMiddleware` і реєструватися через +`api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть +реєструвати middleware результатів інструментів, оскільки цей шов може переписувати +високодовірений вивід інструментів до того, як модель його побачить. -Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugins без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але цей механізм повільніший і буде видалений після завершення перехідного періоду. +Plugin провайдерів, що реалізують `resolveExternalAuthProfiles`, повинні оголошувати +`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через +застарілий сумісний резервний механізм, але він повільніший і буде видалений після +завершення перехідного періоду. -Вбудовані провайдери embedding для пам’яті мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway зареєструє провайдерів. +Вбудовані провайдери ембедингів пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з +вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, +щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway +зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має стандартні моделі, пріоритет резервної автоавтентифікації або рідну підтримку документів, які потрібні узагальненим допоміжним компонентам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +типові моделі, пріоритет резервної автоавтентифікації або нативну підтримку документів, які +потрібні загальним допоміжним засобам ядра до завантаження runtime. Ключі також мають бути оголошені в +`contracts.mediaUnderstandingProviders`. ```json { @@ -427,27 +510,41 @@ Plugins провайдерів, які реалізують `resolveExternalAuth Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Стандартні значення «можливість → модель», які використовуються, коли конфігурація не вказує модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Рідні формати введення документів, які підтримує провайдер. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові значення “можливість → модель”, які використовуються, коли конфігурація не вказує модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного переходу провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні формати документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до завантаження середовища виконання. Виявлення setup/статусу каналу лише для читання може безпосередньо використовувати ці метадані для налаштованих зовнішніх каналів, коли запис setup недоступний або коли `setup.requiresRuntime: false` вказує, що середовище виконання setup не потрібне. +Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до +завантаження runtime. Виявлення setup/статусу каналу лише для читання може використовувати ці метадані +безпосередньо для налаштованих зовнішніх каналів, якщо запис setup недоступний або +коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним. -`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ конфігурації користувача. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим каналом, до виконання коду середовища виконання Plugin. +`channelConfigs` — це метадані маніфесту Plugin, а не новий розділ конфігурації користувача +верхнього рівня. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. +OpenClaw читає метадані маніфесту, щоб визначити, якому Plugin належить цей налаштований +канал, до виконання коду runtime Plugin. -Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: +Для Plugin каналу `configSchema` і `channelConfigs` описують різні +шляхи: - `configSchema` валідує `plugins.entries..config` - `channelConfigs..schema` валідує `channels.` -Невбудовані Plugins, які оголошують `channels[]`, також мають оголошувати відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але поверхні схеми конфігурації холодного шляху, setup і Control UI не знатимуть форму параметрів, що належать каналу, доки не виконається середовище виконання Plugin. +Невбудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але поверхні +схеми конфігурації холодного шляху, setup і Control UI не знатимуть форму +параметрів каналу, що належать Plugin, доки не виконається runtime Plugin. -`channelConfigs..commands.nativeCommandsAutoEnabled` і `nativeSkillsAutoEnabled` можуть оголошувати статичні стандартні значення `auto` для перевірок конфігурації команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати ті самі стандартні значення через `package.json#openclaw.channel.commands` поряд з іншими метаданими каталогу каналів, що належать пакету. +`channelConfigs..commands.nativeCommandsAutoEnabled` і +`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок +конфігурації команд, які виконуються до завантаження runtime каналу. Вбудовані канали також можуть +публікувати ті самі типові значення через `package.json#openclaw.channel.commands` разом з +іншими метаданими каталогу каналів, що належать їхньому пакету. ```json { @@ -462,12 +559,12 @@ Plugins провайдерів, які реалізують `resolveExternalAuth }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Підключення до homeserver Matrix", "commands": { "nativeCommandsAutoEnabled": true, "nativeSkillsAutoEnabled": true @@ -480,18 +577,21 @@ Plugins провайдерів, які реалізують `resolveExternalAuth Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та перегляду, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | -| `commands` | `object` | Статичні стандартні значення native command і native skill для перевірок конфігурації до запуску середовища виконання. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugins, які цей канал має перевершувати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | +| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI / заповнювачі / підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору та перегляду, коли runtime-метадані ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | +| `commands` | `object` | Статичні автотипові значення нативних команд і нативних Skills для перевірок конфігурації до запуску runtime. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати на поверхнях вибору. | ### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який також може надавати інший Plugin. Типові випадки — це перейменований ідентифікатор Plugin, окремий Plugin, який замінює вбудований Plugin, або підтримуваний fork, що зберігає той самий ідентифікатор каналу для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш Plugin є пріоритетним власником для ідентифікатора каналу, який +також може надавати інший Plugin. Типові випадки — це перейменований ідентифікатор Plugin, +окремий Plugin, що замінює вбудований Plugin, або підтримуваний форк, який +зберігає той самий ідентифікатор каналу для сумісності конфігурації. ```json { @@ -512,13 +612,22 @@ Plugins провайдерів, які реалізують `resolveExternalAuth } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує як ідентифікатор каналу, так і бажаний ідентифікатор Plugin. Якщо Plugin із нижчим пріоритетом було вибрано лише тому, що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній конфігурації середовища виконання, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugins, OpenClaw зберігає цей вибір і повідомляє про діагностику дубльованого каналу/інструментів замість того, щоб тихо змінювати запитаний набір Plugins. +Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та +ідентифікатор пріоритетного Plugin. Якщо менш пріоритетний Plugin було вибрано лише тому, +що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній +runtime-конфігурації, щоб каналом і його інструментами володів один Plugin. Явний вибір +користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw +зберігає цей вибір і повідомляє про діагностику дубльованих каналів/інструментів замість +тихого змінення запитаного набору Plugin. -Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той самий канал. Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. +Обмежуйте `preferOver` лише ідентифікаторами Plugin, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера зі скорочених ідентифікаторів моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з +коротких ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження +runtime Plugin. ```json { @@ -531,21 +640,26 @@ Plugins провайдерів, які реалізують `resolveExternalAuth OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника -- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера +- явні посилання `provider/model` використовують метадані маніфесту `providers` власника +- `modelPatterns` мають перевагу над `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований + Plugin +- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера Поля: | Поле | Тип | Що воно означає | | --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | +| `modelPrefixes` | `string[]` | Префікси, що перевіряються через `startsWith` для коротких ідентифікаторів моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що перевіряються для коротких ідентифікаторів моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до завантаження середовища виконання Plugin. Це джерело фіксованих рядків каталогу, псевдонімів провайдера, правил приглушення та режиму виявлення, що належить маніфесту. Оновлення в середовищі виконання, як і раніше, належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли середовище виконання є обов’язковим. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до +завантаження runtime Plugin. Це джерело, що належить маніфесту, для фіксованих рядків +каталогу, псевдонімів провайдерів, правил приховування та режиму виявлення. Оновлення runtime +і далі належить коду runtime провайдера, але маніфест повідомляє ядру, коли +runtime потрібен. ```json { @@ -584,7 +698,7 @@ OpenClaw застосовує такий пріоритет: { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", - "reason": "not available on Azure OpenAI Responses" + "reason": "недоступно в Azure OpenAI Responses" } ], "discovery": { @@ -596,116 +710,165 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають бути вказані у верхньорівневому `providers`. | -| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися в провайдера-власника для каталогу або планування приглушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати його в кеш чи для нього потрібне середовище виконання. | +| Поле | Тип | Що воно означає | +| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають бути присутні у `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися у провайдера-власника для планування каталогу або приховування. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приховує з причини, специфічної для провайдера. | +| `discovery` | `Record` | Чи можна прочитати каталог провайдера з метаданих маніфесту, оновити його в кеш, чи він потребує runtime. | Поля провайдера: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | --------------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язковий стандартний `baseUrl` для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий стандартний адаптер API для моделей у цьому каталозі провайдера. | -| `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що воно означає | +| --------- | ------------------------ | ------------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у цьому каталозі провайдера. | +| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | +| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу провайдера. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що воно означає | -| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Рідне вікно контексту провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту середовища виконання, якщо воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| Поле | Тип | Що воно означає | +| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку міркування. | +| `contextWindow` | `number` | Нативне вікно контексту провайдера. | +| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту runtime, якщо воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | | `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | -| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Використовуйте приглушення лише тоді, коли рядок взагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується разом зі статусом, відмінним від доступного. | +| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приховуйте лише тоді, коли рядок взагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, яка показується разом зі статусом, відмінним від доступного. | | `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору й фільтрами. | +| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | -Не додавайте до `modelCatalog` дані, доступні лише в середовищі виконання. Якщо провайдеру потрібен стан облікового запису, API-запит або виявлення локального процесу, щоб визначити повний набір моделей, оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. +Не розміщуйте в `modelCatalog` дані лише для runtime. Якщо провайдеру потрібен +стан облікового запису, API-запит або виявлення локального процесу, щоб знати повний набір +моделей, оголосіть цей провайдер як `refreshable` або `runtime` у `discovery`. ### Індекс провайдерів OpenClaw -Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, Plugins яких можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugins. Індекс провайдерів — це внутрішній резервний контракт, який у майбутньому використовуватимуть поверхні встановлюваних провайдерів і засобів вибору моделей до встановлення, коли Plugin провайдера ще не встановлено. +Індекс провайдерів OpenClaw — це попередні метадані провайдерів, що належать OpenClaw, для провайдерів, +чиї Plugin можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. +Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — +це внутрішній резервний контракт, який використовуватимуть майбутні поверхні +провайдерів для встановлення та засоби вибору моделей до встановлення, коли Plugin провайдера не встановлено. -Порядок пріоритету джерел каталогу: +Порядок авторитетності каталогу: 1. Конфігурація користувача. 2. `modelCatalog` маніфесту встановленого Plugin. 3. Кеш каталогу моделей після явного оновлення. -4. Preview-рядки Індексу провайдерів OpenClaw. +4. Попередні рядки Індексу провайдерів OpenClaw. -Індекс провайдерів не повинен містити секрети, стан увімкнення, хуки середовища виконання або живі дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають обмежуватися стабільними метаданими відображення, якщо тільки поля адаптера середовища виконання, такі як `api`, `baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом встановленого Plugin. Провайдери з живим виявленням через `/models` мають записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, щоб під час звичайного відображення списків або онбордингу викликати API провайдера. +Індекс провайдерів не повинен містити секрети, стан увімкнення, runtime-хуки чи +актуальні дані моделей, специфічні для облікового запису. Його попередні каталоги використовують ту саму +форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають залишатися обмеженими +стабільними метаданими відображення, якщо лише поля runtime-адаптера, такі як `api`, +`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно в узгодженому стані з +маніфестом встановленого Plugin. Провайдери з актуальним виявленням `/models` мають +записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, щоб під час +звичайного виведення списків або онбордингу викликати API провайдера. -Записи Індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, Plugin яких винесено з ядра або які з інших причин ще не встановлено. Ці метадані повторюють шаблон каталогу каналів: назви пакета, специфікації встановлення npm, очікувана цілісність і недорогі мітки варіантів автентифікації достатні, щоб показати варіант налаштування встановлюваного компонента. Після встановлення Plugin його маніфест отримує пріоритет, а запис Індексу провайдерів для цього провайдера ігнорується. +Записи Індексу провайдерів також можуть містити метадані Plugin, доступного для встановлення, для провайдерів, +чий Plugin було винесено з ядра або він інакше ще не встановлений. Ці +метадані наслідують шаблон каталогу каналів: назви пакета, специфікації встановлення npm, +очікуваної цілісності та легковагових міток варіантів автентифікації достатньо, щоб показати +варіант setup, доступний для встановлення. Щойно Plugin встановлено, його маніфест отримує перевагу, і запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі верхньорівневі ключі можливостей більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перенести `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці верхньорівневі поля як володіння можливостями. +Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб +перемістити `speechProviders`, `realtimeTranscriptionProviders`, +`realtimeVoiceProviders`, `mediaUnderstandingProviders`, +`imageGenerationProviders`, `videoGenerationProviders`, +`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне +завантаження маніфесту більше не розглядає ці поля верхнього рівня як +володіння можливостями. -## Маніфест порівняно з `package.json` +## Маніфест і `package.json` Ці два файли виконують різні завдання: -| Файл | Використовуйте для | +| Файл | Для чого його використовувати | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, контролю встановлення, setup або метаданих каталогу | Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw повинен знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` - якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані Plugin, потрібні до запуску середовища виконання, навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані Plugin до запуску runtime навмисно розміщуються в `package.json` у блоці +`openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує точки входу рідного Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу зібраного JavaScript середовища виконання для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Полегшена точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup для зібраного JavaScript у встановлених пакетах. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Недорогі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.commands` | Статичні метадані стандартних значень native command і native skill, які використовуються поверхнями конфігурації, аудиту та списку команд до завантаження середовища виконання каналу. | -| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного середовища виконання каналу. | -| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на питання «чи вже десь виконано вхід?» без завантаження повного середовища виконання каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих Plugins. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, як-от `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація некоректна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує нативні точки входу Plugin. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує runtime-точки входу зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Легковагові метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.commands` | Статичні метадані автотипових значень нативних команд і нативних Skills, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання “чи вже існує налаштування лише через env?” без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання “чи вже десь виконано вхід?” без завантаження повного runtime каналу. | +| `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` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в +онбордингу до завантаження runtime. `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, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та джерела з некоректним стандартним вибором. Вона також попереджає, коли `expectedIntegrity` задано, але немає коректного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` задано, потоки встановлення/оновлення примусово його застосовують; коли його пропущено, розв’язання через реєстр фіксується без закріплення цілісності. +Точне закріплення версії npm уже існує в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися +безпечною відмовою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. +Інтерактивний онбординг і далі пропонує довірені npm-специфікації реєстру, включно з голими +іменами пакетів і dist-tag, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без закріплення цілісності, з невідповідністю +імені пакета та невалідні джерела default-choice. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає валідного джерела npm, до якого його можна прив’язати. +Коли `expectedIntegrity` присутній, +потоки встановлення/оновлення застосовують його; коли його пропущено, результат розв’язання реєстру +фіксується без закріплення цілісності. -Plugins каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів або сканування SecretRef потрібно визначати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу setup має надавати метадані каналу разом із безпечними для setup адаптерами конфігурації, статусу й секретів; мережеві клієнти, прослуховувачі Gateway і transport runtime слід залишати в основній точці входу розширення. +Plugin каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів +або сканування SecretRef потрібно визначити налаштовані облікові записи без завантаження повного +runtime. Запис setup має надавати метадані каналу разом із безпечними для setup адаптерами +конфігурації, статусу й секретів; мережеві клієнти, слухачі Gateway і transport runtime +мають залишатися в основній точці входу extension. -Поля точки входу середовища виконання не перевизначають перевірки меж пакета для полів точки входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета. +Поля runtime-точок входу не скасовують перевірки меж пакета для полів +точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. -`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно не робить довільно зламані конфігурації придатними до встановлення. На сьогодні воно лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, наприклад відсутнього шляху до вбудованого Plugin або застарілого запису `channels.` для того самого вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно +не робить довільні зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам +встановлення відновлюватися після певних збоїв оновлення застарілого вбудованого Plugin, як-от +відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для цього ж +вбудованого Plugin. Інші помилки конфігурації все одно блокують встановлення й спрямовують операторів +до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -721,9 +884,13 @@ Plugins каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel середовища виконання каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка +автентифікації типу yes/no до завантаження повного Plugin каналу. Цільовий експорт має бути +невеликою функцією, яка читає лише збережений стан; не маршрутизуйте її через повний +barrel runtime каналу. -`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок налаштованого стану лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -739,66 +906,68 @@ Plugins каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли канал може визначити налаштований стан на основі env або інших мінімальних нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або реального середовища виконання каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може визначити налаштований стан через env або інші малі +вхідні дані без runtime. Якщо перевірка потребує повного розв’язання конфігурації або реального +runtime каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дубльовані ідентифікатори Plugin) +## Пріоритет виявлення (однакові ідентифікатори Plugin) -OpenClaw виявляє Plugins із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені Plugins мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість одночасного завантаження. +OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобально встановлені, робочий простір, явно вибрані в конфігурації шляхи). Якщо два результати виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. -Пріоритет від найвищого до найнижчого: +Пріоритет, від найвищого до найнижчого: 1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — Plugins, що постачаються разом з OpenClaw -3. **Глобальне встановлення** — Plugins, встановлені до глобального кореня Plugin OpenClaw -4. **Workspace** — Plugins, виявлені відносно поточного workspace +2. **Вбудований** — Plugin, що постачаються разом з OpenClaw +3. **Глобально встановлений** — Plugin, установлені в глобальний корінь Plugin OpenClaw +4. **Робочий простір** — Plugin, виявлені відносно поточного робочого простору Наслідки: -- Fork або застаріла копія вбудованого Plugin у workspace не зможе затінити вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. -- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Форк або застаріла копія вбудованого Plugin, що лежить у робочому просторі, не перекриє вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі. +- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -## Вимоги до JSON Schema +## Вимоги до схеми JSON -- **Кожен Plugin повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. +- **Кожен Plugin повинен постачати схему JSON**, навіть якщо він не приймає конфігурацію. - Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми валідуються під час читання/запису конфігурації, а не в середовищі виконання. +- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено - в маніфесті Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо лише ідентифікатор каналу не оголошено + маніфестом Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. -- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему, + мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. +- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і - в Doctor + журналах відображається **попередження**. +- Якщо конфігурація Plugin існує, але сам Plugin **вимкнений**, конфігурація зберігається, а + у Doctor + логах з’являється **попередження**. -Повну схему `plugins.*` див. у [Довіднику конфігурації](/uk/gateway/configuration). +Див. [Довідник із конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. ## Примітки -- Маніфест є **обов’язковим для рідних Plugins OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання і далі завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. -- Рідні маніфести розбираються за допомогою JSON5, тож коментарі, кінцеві коми й ключі без лапок дозволені, якщо підсумкове значення все ще є об’єктом. -- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня. +- Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime і далі завантажує модуль 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 і ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Метадані wizard середовища виконання, які потребують коду провайдера, див. у [Хуки середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані env-змінних (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Поверхні статусу, аудиту, валідації доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env-змінну налаштованою. +- Для метаданих runtime wizard, які потребують коду провайдера, див. [Хуки runtime провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від нативних модулів, задокументуйте етапи збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з Plugins. + + Початок роботи з Plugin. Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin та імпорти підшляхів. + Довідник SDK Plugin і імпорти підшляхів. diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 627e0d568..5dbfd8858 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,245 +1,247 @@ --- read_when: - - Вибір правильного підшляху plugin-sdk для імпорту плагіна - - Аудит підшляхів bundled-plugin і допоміжних поверхонь -summary: 'Каталог підшляхів Plugin SDK: які імпорти де знаходяться, згруповано за областями' + - Вибір правильного підшляху plugin-sdk для імпорту Plugin + - Аудит підшляхів вбудованих Plugin і допоміжних поверхонь +summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-26T09:19:30Z" + generated_at: "2026-04-27T08:08:42Z" model: gpt-5.4 provider: openai - source_hash: fcb49ee51301b79985d43470cd8c149c858e79d685908605317de253121d4736 + source_hash: 7ab23b42341d981e4ad85027682be603048a0a57d19604fe9024767ffbb78c50 source_path: plugins/sdk-subpaths.md workflow: 15 --- Plugin SDK доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - Ця сторінка містить каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований - повний список із понад 200 підшляхів знаходиться в `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталлю - реалізації, якщо лише сторінка документації явно не просуває їх. + На цій сторінці наведено каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований + повний список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`; + зарезервовані допоміжні підшляхи для вбудованих Plugin також наведено там, але вони є + деталями реалізації, якщо лише якась сторінка документації прямо не рекомендує їх. - Посібник з розробки плагінів дивіться в [Огляд Plugin SDK](/uk/plugins/sdk-overview). + Посібник з розробки Plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). - ## Точка входу плагіна + ## Точка входу Plugin - | Підшлях | Ключові експорти | - | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | - | `plugin-sdk/plugin-entry` | `definePluginEntry` | - | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | - | `plugin-sdk/config-schema` | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | Підшлях | Ключові експорти | + | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/migration` | Допоміжні функції елементів провайдера міграції, такі як `createMigrationItem`, константи причин, маркери статусу елементів, допоміжні функції редагування та `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Допоміжні функції міграції для середовища виконання, такі як `copyMigrationFileItem` і `writeMigrationReport` | | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Експорт кореневої схеми Zod для `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки allowlist, будівники статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування, запити allowlist, побудовники статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для багатокористувацької конфігурації/керування шлюзами дій, допоміжні засоби резервного переходу до облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ID облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного переходу за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні функції для конфігурації/шлюзу дій мультиакаунтів, допоміжні функції резервного типового акаунта | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації ID акаунта | + | `plugin-sdk/account-resolution` | Допоміжні функції пошуку акаунта та резервного типового значення | + | `plugin-sdk/account-helpers` | Вузькі допоміжні функції для списку акаунтів/дій акаунтів | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram з резервним переходом до bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд | + | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із резервною підтримкою контракту вбудованих компонентів | + | `plugin-sdk/command-gating` | Вузькі допоміжні функції шлюзу авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоків чернеток | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для маршрутів вхідних повідомлень + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних відповідей | - | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби доставки вихідних повідомлень, ідентифікації, делегування надсилання, сесій, форматування та планування payload | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий будівник payload медіа агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язок розмов/потоків, pairing і налаштованих прив’язок | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку статусу каналу | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні функції життєвого циклу/фіналізації потоку чернеток | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршрутизації вхідних даних і побудови конвертів | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису та диспетчеризації вхідних відповідей | + | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей надсилання вихідних даних для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні функції доставки вихідних даних, ідентичності, делегата надсилання, сесій, форматування та планування payload | + | `plugin-sdk/poll-runtime` | Вузькі допоміжні функції нормалізації опитувань | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції життєвого циклу прив’язок потоків і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіа-payload агента | + | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки розмов/потоків, спарювання та налаштованих прив’язок | + | `plugin-sdk/runtime-config-snapshot` | Допоміжна функція знімка конфігурації середовища виконання | + | `plugin-sdk/runtime-group-policy` | Допоміжні функції визначення групової політики в середовищі виконання | + | `plugin-sdk/channel-status` | Спільні допоміжні функції знімка/підсумку стану каналу | | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагіна каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби визначення доступу до груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту прямих DM | - | `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів envelope | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce вхідних повідомлень | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок і тексту згадок без ширшої поверхні inbound runtime | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідного envelope | - | `plugin-sdk/channel-location` | Допоміжні засоби контексту розташування каналу та форматування | - | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для відкидання вхідних повідомлень і збоїв typing/ack | + | `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільні прелюдійні експорти Plugin каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні функції читання/редагування конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо доступу до груп | + | `plugin-sdk/direct-dm` | Спільні допоміжні функції авторизації/захисту прямих DM | + | `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні функції інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних даних, зіставлення згадок, допоміжних функцій політики згадок і допоміжних функцій конвертів | + | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні функції debounce вхідних даних | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні функції політики згадок і тексту згадок без ширшої поверхні середовища виконання вхідних даних | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні функції форматування конвертів вхідних даних | + | `plugin-sdk/channel-location` | Допоміжні функції контексту та форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні функції журналювання каналу для відкинутих вхідних даних і помилок typing/ack | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі нативні допоміжні засоби схем, збережені для сумісності з плагінами | - | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | + | `plugin-sdk/channel-actions` | Допоміжні функції дій із повідомленнями каналу, а також застарілі допоміжні функції нативної схеми, збережені для сумісності Plugin | + | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контрактів каналу | - | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретних контрактів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | + | `plugin-sdk/channel-feedback` | Зв’язування відгуків/реакцій | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції контрактів секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Значення за замовчуванням для CLI backend + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів у runtime для плагінів провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілів API-ключів, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний будівник результатів OAuth-автентифікації | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для плагінів провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var для автентифікації провайдерів | + | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні функції налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення бекенда CLI та константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції визначення API-ключів у середовищі виконання для Plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth-автентифікації | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для Plugin провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку змінних середовища автентифікації провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні будівники політики replay, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політики повторення, допоміжні функції кінцевих точок провайдера та допоміжні функції нормалізації ID моделей, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдерів, HTTP-помилки провайдерів і допоміжні засоби multipart form для аудіотранскрипції | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контрактів конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch провайдерів | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення ввімкнення плагіна | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для web-search провайдерів | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/можливостей кінцевих точок провайдера, помилки HTTP провайдера та допоміжні функції multipart form для транскрипції аудіо | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні функції контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні функції конфігурації/облікових даних web-search для провайдерів, яким не потрібне вмикання Plugin у конфігурації | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped сетери/гетери облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешування/середовища виконання провайдера web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini та діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби транспорту провайдерів, такі як guarded fetch, перетворення транспортних повідомлень і потоки записуваних транспортних подій | - | `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні функції обгорток для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні функції нативного транспорту провайдера, такі як guarded fetch, трансформації транспортних повідомлень і потоки подій транспорту з можливістю запису | + | `plugin-sdk/provider-onboard` | Допоміжні функції патчів конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні функції локальних для процесу singleton/map/cache | + | `plugin-sdk/group-activation` | Вузькі допоміжні функції режиму активації групи та розбору команд | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні засоби авторизації відправника | - | `plugin-sdk/command-status` | Будівники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача й автентифікації дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра нативного затвердження exec | - | `plugin-sdk/approval-delivery-runtime` | Нативні адаптери можливостей/доставки затверджень | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення approval Gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження нативного адаптера затвердження для гарячих точок входу каналів | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника затверджень; віддавайте перевагу вужчим поверхням adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Нативні допоміжні засоби для цілей затвердження + прив’язки облікових записів | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді на затвердження exec/plugin | - | `plugin-sdk/approval-runtime` | Допоміжні засоби payload затвердження exec/plugin, нативні допоміжні засоби маршрутизації/runtime затверджень і допоміжні засоби структурованого відображення затверджень, такі як `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і нативні допоміжні засоби цілей сесій | - | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні функції авторизації відправника | + | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції визначення затверджувача та автентифікації дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра нативного затвердження exec | + | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки нативного затвердження | + | `plugin-sdk/approval-gateway-runtime` | Спільна допоміжна функція визначення Gateway для затвердження | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні функції завантаження адаптера нативного затвердження для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні функції середовища виконання обробника затвердження; надавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілі нативного затвердження та прив’язки акаунта | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді для затвердження exec/Plugin | + | `plugin-sdk/approval-runtime` | Допоміжні функції payload затвердження exec/Plugin, допоміжні функції маршрутизації/середовища виконання нативного затвердження та структуровані допоміжні функції відображення затвердження, такі як `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькі допоміжні функції скидання дедуплікації вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні функції тестування контракту каналу без широкого testing barrel | + | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні функції цілі нативної сесії | + | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди й поверхні команд | + | `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні функції поверхні команди | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання секретних контрактів для секретних поверхонь каналів/плагінів | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби обмеження розміру body/timeout запитів | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції збору секретних контрактів для поверхонь секретів каналу/Plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні функції `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, шлюзу DM, зовнішнього вмісту та збору секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватної мережі | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні функції pinned-dispatcher без широкої поверхні infra runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF та політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні функції розбору введення секретів | + | `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі Webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру тіла запиту/тайм-ауту | - + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервного копіювання/встановлення плагінів | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу | + | `plugin-sdk/runtime` | Широкі допоміжні функції середовища виконання/журналювання/резервного копіювання/встановлення Plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні функції env середовища виконання, logger, timeout, retry і backoff | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні функції реєстрації та пошуку контексту середовища виконання каналу | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для плагінів | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/внутрішніх hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy-імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, wait, version, виклику аргументів і lazy command-group | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і патчів status каналу | - | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації та пошуку конфігурації плагіна | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled контракту Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення autolink для посилань на файли без широкого text-runtime barrel | - | `plugin-sdk/approval-runtime` | Допоміжні засоби затвердження exec/plugin, будівники можливостей затвердження, допоміжні засоби auth/profile, нативні допоміжні засоби маршрутизації/runtime та форматування шляхів структурованого відображення затверджень | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для inbound/reply, chunking, dispatch, Heartbeat, планувальник відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей і підписів розмов | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції команд/hook/http/interactive для Plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні функції pipeline Webhook/внутрішніх hook | + | `plugin-sdk/lazy-runtime` | Допоміжні функції лінивого імпорту/прив’язки середовища виконання, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні функції виконання процесів | + | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, очікування, версії, виклику аргументів і лінивих груп команд | + | `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта Gateway і патчів статусу каналу | + | `plugin-sdk/config-runtime` | Допоміжні функції завантаження/запису конфігурації та пошуку конфігурації Plugin | + | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого text-runtime barrel | + | `plugin-sdk/approval-runtime` | Допоміжні функції затвердження exec/Plugin, побудовники можливостей затвердження, допоміжні функції auth/profile, допоміжні функції нативної маршрутизації/середовища виконання та форматування шляху структурованого відображення затвердження | + | `plugin-sdk/reply-runtime` | Спільні допоміжні функції середовища виконання вхідних даних/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize відповідей і міток розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні функції історії відповідей у короткому вікні, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + `updated-at` | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку status каналу/облікового запису, значення runtime-state за замовчуванням і допоміжні засоби метаданих issue | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних входів | - | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні функції chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні функції шляху сховища сесій і `updated-at` | + | `plugin-sdk/state-paths` | Допоміжні функції шляхів каталогів state/OAuth | + | `plugin-sdk/routing` | Допоміжні функції прив’язки маршруту/ключа сесії/акаунта, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні функції підсумку стану каналу/акаунта, типові значення стану середовища виконання та допоміжні функції метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції визначення цілі | + | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації slug/рядків | + | `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних вхідних даних | + | `plugin-sdk/run-command` | Виконавець команд із таймінгом і нормалізованими результатами stdout/stderr | | `plugin-sdk/param-readers` | Загальні зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування нормалізованих payload із об’єктів результатів tool | + | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистем і редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режимів і перетворення таблиць Markdown | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби повторного входу до file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з опорою на диск | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесій ACP і dispatch відповідей | - | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язок ACP тільки для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою й токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей для команди `/models`/провайдерів | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих agent harness: типи harness, допоміжні засоби steer/abort для active-run, міст tools OpenClaw, допоміжні засоби політики tools runtime-plan, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tools і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | - | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/Heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | - | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Зчитувач обмеженого body відповіді без широкої поверхні media runtime | + | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні функції logger підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму та перетворення таблиць Markdown | + | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису стану JSON | + | `plugin-sdk/file-lock` | Допоміжні функції повторно вхідного блокування файлів | + | `plugin-sdk/persistent-dedupe` | Допоміжні функції кешу дедуплікації з підтримкою диска | + | `plugin-sdk/acp-runtime` | Допоміжні функції середовища виконання/сесії ACP і dispatch відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язки ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації середовища виконання агента | + | `plugin-sdk/boolean-param` | Гнучкий зчитувач boolean-параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції визначення збігів небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні функції початкового налаштування пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу, стану та ambient proxy helper | + | `plugin-sdk/models-provider-runtime` | Допоміжні функції відповіді команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні функції списку команд Skill | + | `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/побудови/серіалізації нативних команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих agent harness: типи harness, допоміжні функції steer/abort активного запуску, допоміжні функції bridge tool OpenClaw, допоміжні функції політики tool плану середовища виконання, класифікація результатів terminal, форматування/деталізація прогресу tool і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення кінцевих точок Z.AI | + | `plugin-sdk/infra-runtime` | Допоміжні функції системних подій/Heartbeat | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичних прапорців і подій | + | `plugin-sdk/error-runtime` | Допоміжні функції графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/runtime-fetch` | Dispatcher-aware fetch середовища виконання без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Зчитувач обмеженого тіла відповіді без широкої поверхні media runtime | | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби читання сховища сесій без широких імпортів запису/обслуговування конфігурації | - | `plugin-sdk/context-visibility-runtime` | Допоміжні засоби визначення видимості контексту та фільтрації додаткового контексту без широких імпортів config/security | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення й нормалізації примітивних record/string без імпортів markdown/logging | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імен хостів і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запити директорій із конфігурації/dedup | + | `plugin-sdk/session-store-runtime` | Допоміжні функції читання сховища сесій без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Допоміжні функції визначення видимості контексту та фільтрації додаткового контексту без широких імпортів config/security | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні функції приведення та нормалізації primitive record/string без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і SCP host | + | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry та виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні функції каталогу/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/dedup каталогів із підтримкою конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також будівники payload медіа | - | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, такі як `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/Markdown/logging, такі як видалення тексту, видимого асистенту, допоміжні засоби рендерингу/chunking/таблиць Markdown, допоміжні засоби редагування чутливих даних, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів експорти директив, реєстру, валідації та допоміжних засобів мовлення | - | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, реєстр, директиви, нормалізація та експорти допоміжних засобів мовлення | - | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні засоби реєстру | - | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошуку провайдерів і розбору model-ref | - | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошуку провайдерів і розбору model-ref | - | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | + | `plugin-sdk/media-runtime` | Спільні допоміжні функції отримання/перетворення/збереження медіа, а також побудовники media payload | + | `plugin-sdk/media-store` | Вузькі допоміжні функції сховища медіа, такі як `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа та провайдер-орієнтовані експорти допоміжних функцій для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту/markdown/журналювання, такі як вилучення тексту, видимого асистенту, допоміжні функції render/chunking/table для markdown, допоміжні функції редагування, directive-tag helper і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту | + | `plugin-sdk/speech` | Типи провайдера мовлення та провайдер-орієнтовані експорти directive, registry, validation і speech helper | + | `plugin-sdk/speech-core` | Спільні типи провайдера мовлення, registry, directive, normalizaton і speech helper exports | + | `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі, допоміжні функції registry і спільна допоміжна функція сесії WebSocket | + | `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі та допоміжні функції registry | + | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і registry helper | + | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, lookup провайдера та розбору model-ref | + | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, lookup провайдера та розбору model-ref | + | `plugin-sdk/webhook-targets` | Допоміжні функції реєстру цілей Webhook і встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа | | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | @@ -247,43 +249,43 @@ x-i18n: | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/допоміжних засобів CLI | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексації/пошуку пам’яті | + | `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для допоміжних функцій manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання індексу/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний провайдер і загальні допоміжні засоби batch/remote | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до registry, локальний провайдер і загальні допоміжні функції batch/remote | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби status хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого Markdown для плагінів, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до менеджера пошуку | - | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для допоміжних засобів status хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні функції секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні функції стану хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції середовища виконання CLI хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Основні допоміжні функції середовища виконання хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/середовища виконання хоста пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний щодо вендора псевдонім для основних допоміжних функцій середовища виконання хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний щодо вендора псевдонім для допоміжних функцій журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний щодо вендора псевдонім для допоміжних функцій файлів/середовища виконання хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції керованого markdown для Plugin, пов’язаних із пам’яттю | + | `plugin-sdk/memory-host-search` | Фасад середовища виконання Active Memory для доступу до менеджера пошуку | + | `plugin-sdk/memory-host-status` | Нейтральний щодо вендора псевдонім для допоміжних функцій стану хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb | - - | Сімейство | Поточні підшляхи | Призначене використання | + + | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається compatibility barrel. | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | - | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Поверхні сумісності/допоміжних засобів bundled каналів | - | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Поверхні допоміжних засобів bundled функцій/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки вбудованого Browser Plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається compatibility barrel. | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних функцій/середовища виконання вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/середовища виконання вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій вбудованого IRC | + | Допоміжні функції, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних функцій вбудованих каналів | + | Допоміжні функції, специфічні для auth/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних функцій вбудованих можливостей/Plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | -## Пов’язане +## Пов’язано - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення плагінів](/uk/plugins/building-plugins) +- [Створення Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/providers/lmstudio.md b/docs/uk/providers/lmstudio.md index 565687ae0..ed122f57d 100644 --- a/docs/uk/providers/lmstudio.md +++ b/docs/uk/providers/lmstudio.md @@ -2,18 +2,18 @@ read_when: - Ви хочете запускати OpenClaw з моделями з відкритим кодом через LM Studio - Ви хочете налаштувати та сконфігурувати LM Studio -summary: Запустіть OpenClaw за допомогою LM Studio +summary: Запустіть OpenClaw з LM Studio title: LM Studio x-i18n: - generated_at: "2026-04-27T07:19:09Z" + generated_at: "2026-04-27T08:09:15Z" model: gpt-5.4 provider: openai - source_hash: 0077108b7ab3171084f89234e25f5f5e8b68239a6fa6c11fa70c65f52d56670f + source_hash: 98edefa8b57ab2a89d1c4405827335a421c3157f51c5d23ac5f83c1cbeab20a9 source_path: providers/lmstudio.md workflow: 15 --- -LM Studio — це дружній, але водночас потужний застосунок для запуску моделей з відкритими вагами на вашому власному обладнанні. Він дає змогу запускати моделі llama.cpp (GGUF) або MLX (Apple Silicon). Доступний як GUI-пакет або безголовий демон (`llmster`). Докладніше про продукт і налаштування дивіться в [lmstudio.ai](https://lmstudio.ai/). +LM Studio — це зручна, але водночас потужна програма для запуску моделей з відкритими вагами на власному обладнанні. Вона дає змогу запускати моделі llama.cpp (GGUF) або MLX (Apple Silicon). Доступна як GUI-застосунок або headless-демон (`llmster`). Документацію про продукт і налаштування див. на [lmstudio.ai](https://lmstudio.ai/). ## Швидкий старт @@ -25,7 +25,7 @@ curl -fsSL https://lmstudio.ai/install.sh | bash 2. Запустіть сервер -Переконайтеся, що ви або запустили desktop-застосунок, або запустили демон за допомогою такої команди: +Переконайтеся, що ви або запускаєте desktop-застосунок, або запускаєте демон такою командою: ```bash lms daemon up @@ -35,7 +35,7 @@ lms daemon up lms server start --port 1234 ``` -Якщо ви використовуєте застосунок, переконайтеся, що у вас увімкнено JIT для комфортної роботи. Докладніше в [посібнику LM Studio щодо JIT і TTL](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict). +Якщо ви використовуєте застосунок, переконайтеся, що у вас увімкнено JIT для комфортної роботи. Докладніше див. у [посібнику LM Studio про JIT і TTL](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict). 3. Якщо в LM Studio увімкнено автентифікацію, установіть `LM_API_TOKEN`: @@ -43,31 +43,31 @@ lms server start --port 1234 export LM_API_TOKEN="your-lm-studio-api-token" ``` -Якщо автентифікацію LM Studio вимкнено, під час інтерактивного налаштування OpenClaw можна залишити ключ API порожнім. +Якщо автентифікацію LM Studio вимкнено, під час інтерактивного налаштування OpenClaw можна залишити API-ключ порожнім. -Докладніше про налаштування автентифікації LM Studio дивіться в [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication). +Докладніше про налаштування автентифікації LM Studio див. у [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication). -4. Запустіть початкове налаштування й виберіть `LM Studio`: +4. Запустіть початкове налаштування та виберіть `LM Studio`: ```bash openclaw onboard ``` -5. Під час початкового налаштування використайте запит `Default model`, щоб вибрати свою модель LM Studio. +5. Під час початкового налаштування використайте запит `Default model`, щоб вибрати вашу модель LM Studio. -Також ви можете встановити або змінити її пізніше: +Ви також можете встановити або змінити її пізніше: ```bash openclaw models set lmstudio/qwen/qwen3.5-9b ``` -Ключі моделей LM Studio мають формат `author/model-name` (наприклад, `qwen/qwen3.5-9b`). У OpenClaw -посилання на моделі додають префікс провайдера: `lmstudio/qwen/qwen3.5-9b`. Точний ключ +Ключі моделей LM Studio мають формат `author/model-name` (наприклад, `qwen/qwen3.5-9b`). OpenClaw +додає до посилань на моделі префікс назви провайдера: `lmstudio/qwen/qwen3.5-9b`. Точний ключ моделі можна знайти, виконавши `curl http://localhost:1234/api/v1/models` і переглянувши поле `key`. ## Неінтерактивне початкове налаштування -Використовуйте неінтерактивне початкове налаштування, якщо хочете автоматизувати налаштування (CI, підготовка середовища, віддалений bootstrap): +Використовуйте неінтерактивне початкове налаштування, якщо хочете автоматизувати встановлення (CI, підготовка, віддалений bootstrap): ```bash openclaw onboard \ @@ -76,7 +76,7 @@ openclaw onboard \ --auth-choice lmstudio ``` -Або вкажіть базову URL-адресу, модель і необов’язковий ключ API: +Або вкажіть базову URL-адресу, модель і необов’язковий API-ключ: ```bash openclaw onboard \ @@ -94,20 +94,21 @@ openclaw onboard \ Для автентифікованих серверів LM Studio передайте `--lmstudio-api-key` або встановіть `LM_API_TOKEN`. Для серверів LM Studio без автентифікації не вказуйте ключ; OpenClaw збереже локальний несекретний маркер. -`--custom-api-key` і надалі підтримується для сумісності, але для LM Studio рекомендовано `--lmstudio-api-key`. +`--custom-api-key` і надалі підтримується для сумісності, але для LM Studio бажано використовувати `--lmstudio-api-key`. -Це записує `models.providers.lmstudio` і встановлює типову модель на -`lmstudio/`. Якщо ви надаєте ключ API, налаштування також записує +Це записує `models.providers.lmstudio` і встановлює типовою модель +`lmstudio/`. Якщо ви надаєте API-ключ, налаштування також записує профіль автентифікації `lmstudio:default`. Інтерактивне налаштування може запропонувати вказати необов’язкову бажану довжину контексту завантаження та застосовує її до виявлених моделей LM Studio, які зберігає в конфігурації. +Конфігурація plugin LM Studio довіряє налаштованій кінцевій точці LM Studio для запитів моделей, зокрема на хостах loopback, LAN і tailnet. Ви можете відмовитися від цього, встановивши `models.providers.lmstudio.request.allowPrivateNetwork: false`. ## Конфігурація -### Сумісність із використанням streaming +### Сумісність із використанням потокової передачі -LM Studio сумісний із використанням streaming. Якщо він не повертає об’єкт -`usage` у форматі OpenAI, OpenClaw відновлює кількість токенів із метаданих +LM Studio сумісний із використанням потокової передачі. Якщо він не повертає +об’єкт `usage` у форматі OpenAI, OpenClaw відновлює кількість токенів із метаданих `timings.prompt_n` / `timings.predicted_n` у стилі llama.cpp. Така сама поведінка застосовується до цих локальних бекендів, сумісних з OpenAI: @@ -147,18 +148,18 @@ LM Studio сумісний із використанням streaming. Якщо } ``` -## Усунення проблем +## Усунення несправностей ### LM Studio не виявлено -Переконайтеся, що LM Studio запущено. Якщо автентифікацію ввімкнено, також установіть `LM_API_TOKEN`: +Переконайтеся, що LM Studio запущено. Якщо автентифікацію увімкнено, також установіть `LM_API_TOKEN`: ```bash # Запуск через desktop-застосунок або в headless-режимі: lms server start --port 1234 ``` -Перевірте, що API доступний: +Переконайтеся, що API доступне: ```bash curl http://localhost:1234/api/v1/models @@ -166,17 +167,38 @@ curl http://localhost:1234/api/v1/models ### Помилки автентифікації (HTTP 401) -Якщо під час налаштування повідомляється про HTTP 401, перевірте свій ключ API: +Якщо під час налаштування повідомляється про HTTP 401, перевірте ваш API-ключ: - Переконайтеся, що `LM_API_TOKEN` збігається з ключем, налаштованим у LM Studio. -- Докладніше про налаштування автентифікації LM Studio дивіться в [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication). +- Докладніше про налаштування автентифікації LM Studio див. у [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication). - Якщо ваш сервер не вимагає автентифікації, залиште ключ порожнім під час налаштування. ### Завантаження моделі just-in-time -LM Studio підтримує завантаження моделей just-in-time (JIT), коли моделі завантажуються під час першого запиту. Переконайтеся, що це ввімкнено, щоб уникнути помилок «Model not loaded». +LM Studio підтримує завантаження моделей just-in-time (JIT), коли моделі завантажуються під час першого запиту. Переконайтеся, що цю функцію увімкнено, щоб уникнути помилок на кшталт "Model not loaded". -## Пов’язане +### Хост LM Studio у LAN або tailnet + +Використовуйте досяжну адресу хоста LM Studio, зберігайте `/v1` і переконайтеся, що LM Studio на цій машині прив’язано не лише до loopback: + +```json5 +{ + models: { + providers: { + lmstudio: { + baseUrl: "http://gpu-box.local:1234/v1", + apiKey: "lmstudio", + api: "openai-completions", + models: [{ id: "qwen/qwen3.5-9b" }], + }, + }, + }, +} +``` + +На відміну від загальних провайдерів, сумісних з OpenAI, `lmstudio` автоматично довіряє своїй налаштованій локальній/приватній кінцевій точці для захищених запитів моделей. Якщо ви використовуєте власний ідентифікатор провайдера замість `lmstudio`, явно встановіть `models.providers..request.allowPrivateNetwork: true`. + +## Пов’язані матеріали - [Вибір моделі](/uk/concepts/model-providers) - [Ollama](/uk/providers/ollama)