From 2821d8a1b0580c0f522be53885f1943ddcae87d2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 22:55:13 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/ci.md | 205 +++++---- docs/uk/help/testing.md | 791 ++++++++++++++++---------------- docs/uk/logging.md | 153 +++--- docs/uk/plugins/sdk-subpaths.md | 394 ++++++++-------- docs/uk/plugins/sdk-testing.md | 127 ++--- docs/uk/reference/RELEASING.md | 543 +++++++++++----------- docs/uk/tools/index.md | 204 ++++---- 7 files changed, 1233 insertions(+), 1184 deletions(-) diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 162971c86..e2ea55852 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,58 +1,69 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося + - Потрібно зрозуміти, чому завдання CI запустилося або не запустилося - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, обмежувальні правила охоплення та локальні еквіваленти команд +summary: Граф завдань CI, межі перевірок і локальні еквіваленти команд title: Конвеєр CI x-i18n: - generated_at: "2026-04-27T19:39:04Z" + generated_at: "2026-04-27T22:51:29Z" model: gpt-5.4 provider: openai - source_hash: 4b6aef34b73f85ef7dae00d21cebfa7c560173dd7b979ca19829ea5290972047 + source_hash: 4bc5befeb5ad84227dd8b36f4ee3b91166c9e5c4417eacb82f9500d568359558 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` для smoke-перевірок встановлення, перевірки пакунків, наборів Docker release-path, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram. Він також може запускати workflow `NPM Telegram Beta E2E` після публікації, якщо вказано специфікацію опублікованого пакунка. Узагальнювальний workflow записує ідентифікатори запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні результати дочірніх запусків. Якщо дочірній workflow перезапущено й він став зеленим, перезапустіть лише батьківське завдання перевірки, щоб оновити результат узагальнювального workflow. +`Full Release Validation` — це ручний umbrella workflow для сценарію «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` для цієї цілі та запускає `OpenClaw Release Checks` для перевірки встановлення, package acceptance, наборів Docker release-path, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram. Він також може запускати workflow після публікації `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета. Umbrella workflow записує id запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні підсумкові стани дочірніх запусків. Якщо дочірній workflow перезапущено й він став зеленим, перезапустіть лише батьківське завдання перевірки, щоб оновити результат umbrella workflow. -Дочірній workflow live/E2E для релізу зберігає широке нативне охоплення `pnpm test:live`, але запускає його як іменовані шарди (`native-live-src-agents`, `native-live-src-gateway-core`, `native-live-src-gateway-backends`, `native-live-test`, `native-live-extensions-a-k`, `native-live-extensions-l-n`, `native-live-extensions-openai`, `native-live-extensions-o-z` і `native-live-extensions-media`) через `scripts/test-live-shard.mjs` замість одного послідовного завдання. Це зберігає те саме файлове охоплення, але полегшує повторний запуск і діагностику повільних збоїв live-провайдерів. +Для відновлення `Full Release Validation` і `OpenClaw Release Checks` обидва приймають `rerun_group`. Використовуйте `all` для кандидата на реліз, `ci` лише для звичайного дочірнього повного CI, `release-checks` для кожного дочірнього релізного завдання або вужчу групу релізу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` в umbrella workflow. Це дозволяє обмежити повторний запуск збійного релізного бокса після точкового виправлення. -`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 lane для smoke, package, product, full і custom. Профіль `package` використовує офлайнове охоплення Plugin, тому валідація опублікованого пакунка не залежить від доступності live ClawHub. Необов’язкова lane Telegram повторно використовує артефакт `package-under-test` у workflow `NPM Telegram Beta E2E`, а шлях зі специфікацією опублікованого npm зберігається для окремих ручних запусків. +Дочірній live/E2E workflow релізу зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди (`native-live-src-agents`, `native-live-src-gateway-core`, `native-live-src-gateway-backends`, `native-live-test`, `native-live-extensions-a-k`, `native-live-extensions-l-n`, `native-live-extensions-openai`, `native-live-extensions-o-z` і `native-live-extensions-media`) через `scripts/test-live-shard.mjs` замість одного послідовного завдання. Це зберігає те саме файлове покриття, водночас спрощуючи повторний запуск і діагностику повільних збоїв live provider. -## Прийняття пакунка +`Package Acceptance` — це side-run 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 lane для smoke, package, product, full і custom. Профіль `package` використовує offline plugin coverage, тому валідація опублікованого пакета не залежить від доступності live ClawHub. Необов’язковий lane Telegram повторно використовує артефакт `package-under-test` у workflow `NPM Telegram Beta E2E`, при цьому шлях через специфікацію опублікованого npm залишається для автономних запусків. -Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальований пакунок OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі проходять після встановлення або оновлення. +## Package acceptance + +Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі проходять після встановлення або оновлення. Workflow має чотири завдання: -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 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 завантажує цей артефакт, перевіряє inventory tarball, за потреби готує package-digest Docker images і запускає вибрані Docker lanes для цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow один раз готує пакет і спільні образи, а потім розгортає ці lanes як паралельні цільові Docker jobs з унікальними артефактами. +3. `package_telegram` за потреби викликає `NPM Telegram Beta E2E`. Воно запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance визначив його; автономний запуск Telegram і далі може встановлювати опубліковану npm-специфікацію. +4. `summary` позначає workflow як невдалий, якщо не вдалися визначення пакета, Docker acceptance або необов’язковий lane Telegram. -Джерела кандидатів: +Джерела кандидата: - `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для acceptance опублікованих beta/stable. -- `source=ref`: пакує довірену гілку, тег або повний SHA коміту `package_ref`. Визначення пакунка отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілок репозиторію або з тега релізу, встановлює залежності в detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. +- `source=ref`: пакує довірену гілку, тег або повний SHA коміту `package_ref`. Resolver отримує гілки/теги 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/harness, який запускає тест. `package_ref` — це коміт вихідного коду, який пакується, коли `source=ref`. Це дає змогу поточному test harness перевіряти старі довірені коміти вихідного коду без запуску старої логіки workflow. +Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це код довіреного workflow/harness, який запускає тест. `package_ref` — це вихідний коміт, який пакується, коли `source=ref`. Це дозволяє поточному test harness перевіряти старі довірені вихідні коміти без запуску старої логіки workflow. -Профілі відповідають охопленню Docker: +Профілі відповідають покриттю Docker: - `smoke`: `npm-onboard-channel-agent`, `gateway-network`, `config-reload` -- `package`: `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update` -- `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full`: повні Docker release-path chunks з OpenWebUI +- `package`: `npm-onboard-channel-agent`, `doctor-switch`, + `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, + `plugin-update` +- `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, + `openai-web-search-minimal`, `openwebui` +- `full`: повні chunks Docker release-path з OpenWebUI - `custom`: точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Release checks викликають Package Acceptance з `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` і `telegram_mode=mock-openai`. Docker chunks шляху релізу покривають lane пакунка/оновлення/Plugin, що перетинаються, а Package Acceptance зберігає нативне для артефакту підтвердження bundled-channel compat, офлайнового Plugin і Telegram для того самого визначеного tarball пакунка. -Cross-OS release checks і далі покривають специфічну для ОС поведінку онбордингу, інсталятора й платформи; валідацію пакунка/оновлення на рівні продукту слід починати з Package Acceptance. Windows packaged і installer fresh lane також перевіряють, що встановлений пакунок може імпортувати override browser-control із сирого абсолютного шляху Windows. +Release checks викликає Package Acceptance з `source=ref`, +`package_ref=`, `workflow_ref=`, +`suite_profile=custom`, +`docker_lanes='bundled-channel-deps-compat plugins-offline'` і +`telegram_mode=mock-openai`. Docker chunks release-path +покривають перетинні lane для package/update/plugin, тоді як Package +Acceptance зберігає доказову базу для вбудованої сумісності каналів, офлайнових plugin і Telegram на рівні артефакту щодо того самого визначеного tarball пакета. +Cross-OS release checks і далі покривають специфічну для ОС поведінку онбордингу, інсталятора й платформи; перевірку продукту package/update слід починати з Package Acceptance. Лінії свіжого запуску packaged та installer для Windows також перевіряють, що встановлений пакет може імпортувати browser-control override із сирого абсолютного Windows-шляху. -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` з fake git fixture, похідного від tarball, і може журналювати відсутній збережений `update.channel`; Plugin smoke-перевірки можуть читати застарілі розташування записів встановлення або приймати відсутність збереження запису встановлення з marketplace; а `plugin-update` може дозволяти міграцію метаданих конфігурації, водночас усе ще вимагаючи, щоб запис встановлення і поведінка без перевстановлення залишалися незмінними. Пакунки після `2026.4.25` мають відповідати сучасним контрактам; за тих самих умов буде помилка, а не попередження чи пропуск. +Package Acceptance має обмежене вікно legacy-сумісності для вже опублікованих пакетів до `2026.4.25`, включно з `2026.4.25-beta.*`. Ці послаблення задокументовано тут, щоб вони не перетворилися на постійні тихі пропуски: відомі приватні записи QA у `dist/postinstall-inventory.json` можуть спричиняти попередження, якщо tarball не містив цих файлів; `doctor-switch` може пропустити підвипадок persistence для `gateway install --wrapper`, якщо пакет не надає цей прапорець; `update-channel-switch` може обрізати відсутні `pnpm.patchedDependencies` із tarball-derived fake git fixture і може логувати відсутній збережений `update.channel`; plugin smoke можуть читати legacy-розташування install-record або приймати відсутність persistence install-record для marketplace; а `plugin-update` може дозволяти міграцію метаданих конфігурації, водночас і далі вимагаючи, щоб install record і поведінка без перевстановлення залишалися незмінними. Пакети після `2026.4.25` мають відповідати сучасним контрактам; ті самі умови завершуються помилкою замість попередження чи пропуску. Приклади: @@ -95,17 +106,21 @@ 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, а не повторному запуску повної release validation. +Під час налагодження збійного запуску package acceptance починайте з підсумку `resolve_package`, щоб підтвердити джерело пакета, версію і SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: +`.artifacts/docker-tests/**/summary.json`, `failures.json`, логи lane, таймінги фаз і команди повторного запуску. Надавайте перевагу повторному запуску збійного package profile або точних Docker lanes замість повторного запуску повної release validation. -QA Lab має окремі lane CI поза основним workflow з розумним визначенням охоплення. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне QA runtime і порівнює агентні набори mock GPT-5.5 і Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгортає mock parity gate, live Matrix lane і live Telegram та Discord lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують оренди Convex. Matrix використовує `--profile fast` для запланованих і release gate, додаючи `--fail-fast` лише тоді, коли checked-out CLI це підтримує. Значення CLI за замовчуванням і значення ручного вводу workflow залишаються `all`; ручний запуск `matrix_profile=all` завжди розбиває повне охоплення Matrix на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також запускає критичні для релізу lane QA Lab перед затвердженням релізу. +QA Lab має окремі лінії CI поза основним workflow із розумним визначенням меж. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне QA runtime і порівнює mock agentic packs GPT-5.5 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні завдання. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують оренди Convex. Matrix використовує `--profile fast` для запланованих і релізних перевірок, додаючи `--fail-fast` лише тоді, коли це підтримує CLI із checked-out версії. Значення CLI за замовчуванням і ручне введення workflow залишаються `all`; ручний запуск з `matrix_profile=all` +завжди розбиває повне покриття Matrix на завдання `transport`, `media`, +`e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також +запускає критично важливі для релізу лінії QA Lab до схвалення релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідника, призначений для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перш ніж змінювати GitHub, він перевіряє, що злитий PR справді має статус merged і що кожен дублікат має або спільне пов’язане issue, або перетин змінених hunks. +Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для очищення дублікатів після злиття. За замовчуванням він працює в dry-run режимі й закриває лише явно перелічені PR, коли `apply=true`. Перш ніж змінювати GitHub, він перевіряє, що злитий PR справді змерджено, а також що кожен дублікат має або спільне згадане issue, або перетинні змінені hunks. -Workflow `CodeQL` навмисно є вузьким сканером першого проходу, а не повним обходом репозиторію. Щоденні та ручні запуски сканують код workflow Actions, а також найризикованіші поверхні JavaScript/TypeScript, пов’язані з auth, secrets, sandbox, cron і gateway. Критична security lane використовує високоточні запити безпеки, а окрема critical quality lane запускає лише non-security запити рівня error для тієї самої вузької поверхні JavaScript/TypeScript. Розширення CodeQL на Swift, Android, Python, UI і bundled-plugin слід повертати лише як обмежену за охопленням або шардовану подальшу роботу після того, як вузький профіль матиме стабільний runtime і якісний сигнал. +Workflow `CodeQL` навмисно є вузьким першим сканером, а не повним оглядом усього репозиторію. Щоденні й ручні запуски сканують код workflow Actions плюс JavaScript/TypeScript-поверхні з найвищим ризиком, пов’язані з auth, secrets, sandbox, Cron і gateway. Критично важлива security lane використовує високоточні security-запити, а окрема critical quality lane запускає лише non-security-запити рівня error для тієї самої вузької JavaScript/TypeScript-поверхні. Розширення CodeQL на Swift, Android, Python, UI і bundled-plugin слід повертати лише як окрему scoped або sharded подальшу роботу після того, як вузький профіль матиме стабільний час виконання й корисний сигнал. -Workflow `Docs Agent` — це подієвий супровідний lane Codex для підтримання наявної документації у відповідності до нещодавно злитих змін. Він не має чистого розкладу: його може запустити успішний небочий запуск push CI на `main`, а ручний запуск може запустити його напряму. Виклики через workflow-run пропускаються, якщо `main` уже змінився або якщо інший непропущений запуск Docs Agent було створено протягом останньої години. Коли він запускається, він переглядає діапазон комітів від SHA джерела попереднього непропущеного Docs Agent до поточного `main`, тож один щогодинний запуск може охопити всі зміни в main, накопичені з часу останнього проходу документації. +Workflow `Docs Agent` — це event-driven lane обслуговування Codex для підтримання наявної документації у відповідності до нещодавно внесених змін. Він не має окремого розкладу: його може запустити успішний неботовий CI-запуск push у `main`, а також його можна запустити напряму через ручний dispatch. Виклики через workflow-run пропускаються, якщо `main` уже пішов уперед або якщо протягом останньої години вже було створено інший непропущений запуск Docs Agent. Коли він запускається, він переглядає діапазон комітів від попереднього source SHA непропущеного Docs Agent до поточного `main`, тож один щогодинний запуск може охопити всі зміни в `main`, накопичені з часу останнього проходу по документації. -Workflow `Test Performance Agent` — це подієвий lane супроводу Codex для повільних тестів. Він не має окремого розкладу: його може запустити успішний небочий запуск push CI на `main`, але він пропускається, якщо інший виклик через workflow-run уже виконався або виконується в той самий день UTC. Ручний запуск обходить це денне обмеження активності. Lane будує згрупований звіт про продуктивність повного набору Vitest, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів без втрати покриття замість широких рефакторингів, потім повторно запускає звіт повного набору й відхиляє зміни, що зменшують базову кількість тестів, які проходять. Якщо в базовому стані є тести зі збоями, Codex може виправляти лише очевидні збої, а звіт повного набору після агента має пройти перед будь-яким комітом. Коли `main` просувається вперед до того, як push бота буде злитий, lane перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; застарілі патчі з конфліктами пропускаються. Він використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну модель drop-sudo, що й docs agent. +Workflow `Test Performance Agent` — це event-driven lane обслуговування Codex для повільних тестів. Він не має окремого розкладу: його може запустити успішний неботовий CI-запуск push у `main`, але він пропускається, якщо того UTC-дня інший виклик через workflow-run уже відпрацював або ще виконується. Ручний dispatch обходить цей денний activity gate. Lane будує згрупований звіт продуктивності Vitest для повного набору тестів, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору й відхиляє зміни, які зменшують кількість тестів у прохідному baseline. Якщо baseline містить тести, що падають, Codex може виправляти лише очевидні збої, а after-agent звіт повного набору тестів має пройти, перш ніж щось буде закомічено. Коли `main` рухається вперед до того, як бот встигає доставити push, lane перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі патчі пропускаються. Він використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму drop-sudo posture безпеки, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -116,31 +131,31 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Виявлення змін лише в документації, змінених областей охоплення, змінених розширень і побудова маніфесту 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, перевірки built-artifact і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux lane коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шардовані тести bundled-Plugin для всього набору розширень | Зміни, релевантні для Node | -| `checks-node-core-test` | Шардовані тести ядра Node, без lane каналів, bundled, контрактів і розширень | Зміни, релевантні для Node | -| `check` | Шардований еквівалент основної локальної перевірки: production types, lint, guards, типи тестів і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Шарди для архітектури, меж, захисту поверхні розширень, меж пакунків і gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI і smoke-перевірка пам’яті під час запуску | Зміни, релевантні для Node | -| `checks` | Верифікатор для тестів каналів built-artifact | Зміни, релевантні для Node | -| `checks-node-compat-node22` | Lane сумісності з Node 22 для збірки і smoke | Ручний запуск CI для релізів | -| `check-docs` | Форматування документації, lint і перевірки битих посилань | Змінено документацію | -| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Тести процесів/шляхів, специфічні для Windows, плюс спільні регресії import specifier runtime | Зміни, релевантні для Windows | -| `macos-node` | Lane тестів TypeScript на macOS із використанням спільних built artifacts | Зміни, релевантні для macOS | -| `macos-swift` | Lint, build і тести Swift для програми macOS | Зміни, релевантні для macOS | -| `android` | Модульні тести Android для обох варіантів плюс одна збірка debug APK | Зміни, релевантні для Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів через Codex після довіреної активності | Успішний main CI або ручний запуск | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- | +| `preflight` | Визначає зміни лише в документації, змінені межі, змінені extensions і будує CI manifest | Завжди для non-draft push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей на основі npm advisories | Завжди для non-draft push і PR | +| `security-fast` | Обов’язковий aggregate для швидких security jobs | Завжди для non-draft push і PR | +| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі Linux lanes коректності, такі як bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Sharded channel contract checks зі стабільним aggregate результатом перевірки | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шардовані тести bundled-plugin для всього набору extensions | Зміни, релевантні для Node | +| `checks-node-core-test` | Шардовані core Node тести, без channel, bundled, contract і extension lanes | Зміни, релевантні для Node | +| `check` | Sharded еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Shards для architecture, boundary, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести built-CLI і startup-memory smoke | Зміни, релевантні для Node | +| `checks` | Verifier для built-artifact channel tests | Зміни, релевантні для Node | +| `checks-node-compat-node22` | Lane сумісності Node 22 для build і smoke | Ручний dispatch CI для релізів | +| `check-docs` | Перевірки форматування документації, lint і broken links | Документацію змінено | +| `skills-python` | Ruff + pytest для Python-backed Skills | Зміни, релевантні для Python Skills | +| `checks-windows` | Специфічні для Windows тести process/path плюс спільні регресії import specifier runtime | Зміни, релевантні для Windows | +| `macos-node` | Lane тестів TypeScript на macOS із використанням спільних built artifacts | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, build і тести для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Android unit-тести для обох flavor плюс один debug APK build | Зміни, релевантні для Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний CI на main або ручний dispatch | -Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але примусово вмикають кожен lane з обмеженням за охопленням: шардовані Linux Node, шардовані bundled-Plugin, контракти каналів, сумісність із Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python Skills, Windows, macOS, Android і локалізацію Control UI. Ручні запуски використовують унікальну групу concurrency, щоб повний набір для кандидата на реліз не було скасовано іншим запуском push або PR на тому самому ref. Необов’язковий вхід `target_ref` дає змогу довіреному виклику запускати цей граф для гілки, тега або повного SHA коміту, використовуючи файл workflow із вибраного ref запуску. +Ручні dispatch-виклики CI запускають той самий граф завдань, що й звичайний CI, але примусово вмикають усі scoped lanes: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, docs checks, Python Skills, Windows, macOS, Android і Control UI i18n. Ручні запуски використовують унікальну concurrency group, щоб повний набір перевірок для кандидата на реліз не було скасовано іншим push- або PR-запуском на тому самому ref. Необов’язковий вхід `target_ref` дозволяє довіреному виклику запускати цей граф для гілки, тега або повного SHA коміту, використовуючи файл workflow з вибраного dispatch ref. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -150,65 +165,67 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Порядок fail-fast -Завдання впорядковано так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запускаються дорогі: +Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж почнуть виконуватися дорогі: -1. `preflight` вирішує, які lane взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються з помилкою, не чекаючи важчих матричних завдань артефактів і платформ. -3. `build-artifacts` виконується паралельно зі швидкими Linux lane, щоб downstream-споживачі могли стартувати, щойно спільна збірка буде готова. -4. Після цього розгортаються важчі платформні та runtime lane: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` визначає, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи важчих matrix jobs для artifacts і платформ. +3. `build-artifacts` виконується паралельно зі швидкими Linux lanes, щоб downstream consumers могли стартувати, щойно буде готова спільна збірка. +4. Після цього розгортаються важчі platform і runtime lanes: `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` і покрита модульними тестами в `src/scripts/ci-changed-scope.test.ts`. -Ручний запуск пропускає визначення changed-scope і змушує маніфест preflight працювати так, ніби змінилася кожна область з обмеженням охоплення. -Зміни workflow CI перевіряють граф Node CI разом із linting workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці платформні lane і далі залишаються прив’язаними до змін у платформному вихідному коді. -Зміни лише в маршрутизації CI, окремі дешеві зміни fixture для core-test і вузькі зміни helper/test-routing для контрактів Plugin використовують швидкий шлях маніфесту лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях уникає build artifacts, сумісності з Node 22, контрактів каналів, повних шардів ядра, шардів bundled-Plugin і додаткових матриць захисту, коли змінені файли обмежені поверхнями маршрутизації або helper, які швидке завдання безпосередньо перевіряє. -Перевірки Windows Node обмежені Windows-специфічними process/path wrappers, helper для npm/pnpm/UI runner, конфігурацією менеджера пакунків і поверхнями workflow CI, які запускають цей lane; не пов’язані зміни у вихідному коді, Plugin, install-smoke і зміни лише в тестах залишаються в Linux Node lane, щоб не резервувати 16-vCPU Windows worker для охоплення, яке вже перевіряється звичайними test shards. -Окремий workflow `install-smoke` повторно використовує той самий сценарій охоплення через власне завдання `preflight`. Він розділяє smoke-охоплення на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін пакунків/маніфестів bundled Plugin і поверхонь ядра 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, перевіряє аргумент збірки bundled extension і запускає обмежений Docker profile для 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 image-provider додатково контролюється через `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 для lane installer/update/plugin-dependency і функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних lane. Визначення Docker lane містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника — в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для lane через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lane з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте типовий розмір основного пулу 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а розмір tail-пулу 10, чутливого до провайдерів, — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження для важких lane за замовчуванням дорівнюють `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб lane з npm install і кількома сервісами не перевантажували Docker, поки легші lane все ще заповнюють доступні слоти. Один lane, важчий за ефективні обмеження, усе одно може стартувати з порожнього пулу, а потім виконуватиметься самостійно, доки не звільнить ресурси. Запуски lane за замовчуванням розносяться на 2 секунди, щоб уникнути локальних штормів створення Docker daemon; змініть це через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний сукупний запуск виконує preflight Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних lane, зберігає таймінги lane для впорядкування від найдовших до найкоротших і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перевірки планувальника. За замовчуванням він припиняє планування нових lane у пулі після першої помилки, і кожен lane має резервний тайм-аут 120 хвилин, який можна змінити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lane використовують жорсткіші індивідуальні обмеження. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні lane планувальника, включно з lane лише для релізу, як-от `install-e2e`, і розділеними bundled update lane, як-от `bundled-channel-update-acpx`, пропускаючи cleanup smoke, щоб агенти могли відтворити один збійний lane. Повторно використовуваний workflow live/E2E запитує в `scripts/test-docker-all.mjs --plan-json`, який пакунок, тип образу, live image, lane і покриття credentials потрібні, після чого `scripts/docker-e2e.mjs` перетворює цей план на виходи GitHub і підсумки. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує артефакт пакунка з поточного запуску, або завантажує артефакт пакунка з `package_artifact_run_id`; перевіряє інвентар tarball; збирає і публікує bare/functional образи Docker E2E з тегом package-digest у GHCR через кеш шарів Docker від Blacksmith, коли план потребує lane з установленим пакунком; і повторно використовує надані входи `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи package-digest замість повторної збірки. Workflow `Package Acceptance` — це високорівневий пакетний gate: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакту попереднього workflow, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна логіка acceptance могла перевіряти старі довірені коміти без checkout старого коду workflow. Release checks запускають власну custom-різницю Package Acceptance для цільового ref: bundled-channel compat, офлайнові fixture Plugin і package QA для Telegram на основі визначеного tarball. Docker suite для release-path запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk витягував лише потрібний йому тип образу й виконував кілька lane через той самий зважений планувальник (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-core|plugins-runtime-install-a|plugins-runtime-install-b|bundled-channels`). OpenWebUI включено в `plugins-runtime-core`, коли повне охоплення release-path цього вимагає, і окремий chunk `openwebui` зберігається лише для запусків, що стосуються тільки OpenWebUI. Застарілі сукупні назви chunk `package-update`, `plugins-runtime` і `plugins-integrations` усе ще працюють для ручних повторних запусків, але workflow релізу використовує розділені chunks, щоб installer E2E і повні перевірки встановлення/видалення bundled Plugin не домінували в критичному шляху. Псевдонім lane `install-e2e` залишається сукупним псевдонімом для ручного повторного запуску обох lane installer provider. Chunk `bundled-channels` запускає розділені lane `bundled-channel-*` і `bundled-channel-update-*` замість послідовного all-in-one lane `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` із журналами lane, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями повільних lane і командами повторного запуску для кожного lane. Вхід workflow `docker_lanes` запускає вибрані lane на підготовлених образах замість chunk jobs, що обмежує налагодження збійного lane одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакунка для цього запуску; якщо вибраний lane є live Docker lane, цільове завдання локально збирає образ live-test для цього повторного запуску. Згенеровані команди повторного запуску GitHub для кожного lane включають `package_artifact_run_id`, `package_artifact_name` і входи підготовлених образів, коли ці значення існують, щоб збійний lane міг повторно використати точний пакунок і образи зі збійного запуску. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти із запуску GitHub і вивести комбіновані/по-lane команди цільового повторного запуску; використовуйте `pnpm test:docker:timings ` для зведень про повільні lane і критичний шлях фаз. Запланований workflow live/E2E щодня запускає повний Docker suite release-path. Матрицю bundled update розділено за ціллю оновлення, щоб повторні проходи npm update і doctor repair могли шардитися разом з іншими bundled checks. +Логіка меж перевірок живе в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Ручний dispatch пропускає визначення changed-scope і змушує preflight manifest поводитися так, ніби змінилася кожна scoped-ділянка. +Зміни workflow CI перевіряють Node CI graph плюс linting workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці platform lanes і далі залишаються прив’язаними до змін у вихідному коді відповідних платформ. +Зміни лише в маршрутизації CI, окремі дешеві зміни fixture core-test, а також вузькі зміни helper/test-routing для plugin contract використовують швидкий шлях manifest лише для Node: preflight, security і єдине завдання `checks-fast-core`. Цей шлях уникає build artifacts, сумісності Node 22, channel contracts, повних core shards, bundled-plugin shards і додаткових guard matrices, коли змінені файли обмежені поверхнями маршрутизації або helper, які швидке завдання перевіряє безпосередньо. +Перевірки Windows Node обмежені специфічними для Windows process/path wrappers, helper для npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цю lane; не пов’язані зміни вихідного коду, plugin, install-smoke і лише тестів залишаються на Linux Node lanes, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже виконується звичайними test shards. +Окремий workflow `install-smoke` повторно використовує той самий скрипт визначення меж через власне завдання `preflight`. Він ділить smoke coverage на `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 profile bundled-plugin із сумарним тайм-аутом команди 240 секунд, де `docker run` кожного сценарію окремо також обмежено. Повний шлях зберігає QR package install і покриття installer Docker/update для нічних запланованих запусків, ручних dispatch, workflow-call release checks і pull request, які справді зачіпають поверхні installer/package/Docker. Push у `main`, включно з merge commits, не примушують повний шлях; коли логіка changed-scope на push запитувала б повне покриття, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної валідації. Повільний smoke Bun global install image-provider окремо керується через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні dispatch `install-smoke` можуть увімкнути його, але pull request і push у `main` його не запускають. Тести QR та installer Docker зберігають власні install-focused Dockerfile. Локальний `test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: базовий runner Node/Git для lane installer/update/plugin-dependency і функціональний образ, який встановлює той самий tarball у `/app` для звичайних functionality lanes. Визначення Docker lane живуть у `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-пулу 10, чутливого до provider, — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження для важких lane за замовчуванням дорівнюють `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб lanes з npm install і кількома сервісами не перевантажували Docker, поки легші lanes все ще заповнюють доступні слоти. Окрема lane, важча за ефективні обмеження, усе одно може стартувати з порожнього пулу, а потім виконується сама, доки не звільнить місткість. Запуски lane за замовчуванням рознесені на 2 секунди, щоб уникати локальних штормів create у Docker daemon; це можна перевизначити через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний aggregate спочатку перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних lanes, зберігає таймінги lanes для впорядкування longest-first і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перевірки планувальника. За замовчуванням він припиняє планувати нові pooled lanes після першої помилки, а кожна lane має резервний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lanes використовують жорсткіші обмеження для кожної lane. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні scheduler lanes, включно з lane лише для релізу, такими як `install-e2e`, і split bundled update lanes, такими як `bundled-channel-update-acpx`, водночас пропускаючи cleanup smoke, щоб агенти могли відтворити одну збійну lane. Повторно використовуваний workflow live/E2E запитує у `scripts/test-docker-all.mjs --plan-json`, який package, image kind, live image, lane і credential coverage потрібні, після чого `scripts/docker-e2e.mjs` перетворює цей план на outputs і summaries GitHub. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє inventory tarball; збирає і публікує package-digest-tagged bare/functional GHCR Docker E2E images через Docker layer cache Blacksmith, коли плану потрібні lanes з установленим пакетом; і повторно використовує надані входи `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest images замість повторної збірки. Workflow `Package Acceptance` — це високорівневий gate для пакета: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакту попереднього workflow, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна логіка acceptance могла перевіряти старіші довірені коміти без checkout старого коду workflow. Release checks запускають custom Package Acceptance delta для цільового ref: bundled-channel compat, offline plugin fixtures і Telegram package QA для визначеного tarball. Набір Docker release-path запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk витягував лише потрібний йому image kind і виконував кілька lanes через той самий weighted scheduler (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-core|plugins-runtime-install-a|plugins-runtime-install-b|bundled-channels`). OpenWebUI вбудовано в `plugins-runtime-core`, коли повне покриття release-path вимагає його, і окремий chunk `openwebui` залишається лише для dispatch-викликів лише OpenWebUI. Legacy aggregate-імена chunk `package-update`, `plugins-runtime` і `plugins-integrations` і далі працюють для ручних rerun, але workflow релізу використовує split chunks, щоб installer E2E і sweeps install/uninstall bundled plugin не домінували на критичному шляху. Псевдонім lane `install-e2e` залишається aggregate-псевдонімом ручного rerun для обох lanes installer provider. Chunk `bundled-channels` запускає split lanes `bundled-channel-*` і `bundled-channel-update-*` замість послідовної all-in-one lane `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` з логами lanes, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON-планом планувальника, таблицями повільних lanes і командами rerun для кожної lane. Вхід workflow `docker_lanes` запускає вибрані lanes проти підготовлених образів замість chunk jobs, що дозволяє обмежити налагодження збійної lane одним цільовим Docker job і підготувати, завантажити або повторно використати артефакт пакета для цього запуску; якщо вибрана lane є live Docker lane, цільове завдання збирає live-test image локально для цього rerun. Згенеровані команди rerun GitHub для кожної lane включають `package_artifact_run_id`, `package_artifact_name` і входи підготовлених образів, коли ці значення існують, тож збійна lane може повторно використати точний пакет і образи зі збійного запуску. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти із запуску GitHub і вивести комбіновані/покрокові цільові команди rerun; використовуйте `pnpm test:docker:timings ` для підсумків повільних lanes і критичного шляху фаз. Запланований workflow live/E2E щодня запускає повний набір Docker release-path. Матриця bundled update розділена за ціллю оновлення, щоб повторні проходи npm update і doctor repair можна було шардити разом з іншими bundled checks. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Ця локальна перевірка суворіша щодо архітектурних меж, ніж широке платформне охоплення CI: зміни в production ядра запускають перевірку типів core prod і core test разом із core lint/guards, зміни лише в тестах ядра запускають лише перевірку типів core test разом із core lint, зміни в production розширень запускають перевірку типів extension prod і extension test разом із extension lint, а зміни лише в тестах розширень запускають перевірку типів extension test разом із extension lint. Зміни в публічному Plugin SDK або plugin-contract розширюють охоплення до перевірки типів розширень, оскільки розширення залежать від цих контрактів ядра, але повні прогонки Vitest для розширень — це окрема явна тестова робота. Зміни лише в метаданих релізу для підвищення версії запускають цільові перевірки version/config/root-dependency. Невідомі зміни в корені/конфігурації безпечно призводять до запуску всіх lane перевірки. +Поточні release Docker chunks — це `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-core`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Aggregate chunk `bundled-channels` і далі доступний для ручних одноразових rerun, але workflow релізу використовує split chunks, щоб channel smokes, цілі оновлення і setup/runtime contract checks могли виконуватися паралельно. Цільові dispatch-виклики `docker_lanes` також розділяють кілька вибраних lanes на паралельні jobs після одного спільного кроку підготовки package/image, а bundled-channel update lanes повторюють спробу один раз у разі тимчасових збоїв мережі npm. -Ручні запуски CI запускають `checks-node-compat-node22` як перевірку сумісності для кандидатів на реліз. Звичайні pull request і push у `main` пропускають цей lane й залишають матрицю зосередженою на lane тестів/каналів Node 24. +Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо меж архітектури, ніж широке визначення platform scope у CI: зміни core production запускають typecheck core prod і core test плюс core lint/guards, зміни лише core test запускають лише typecheck core test плюс core lint, зміни extension production запускають typecheck extension prod і extension test плюс extension lint, а зміни лише extension test запускають typecheck extension test плюс extension lint. Зміни публічного Plugin SDK або plugin-contract розширюють typecheck на extensions, оскільки extensions залежать від цих core contract, але sweeps Vitest для extensions — це явна тестова робота. Version bumps лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно переводять перевірку на всі check lanes. -Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування раннерів: контракти каналів виконуються як три зважені шарди, тести bundled Plugin балансуються між шістьма workers розширень, малі lane модульних тестів ядра об’єднано в пари, auto-reply виконується на чотирьох збалансованих workers із розділенням піддерева reply на шарди agent-runner, dispatch і commands/state-routing, а agentic-конфігурації gateway/Plugin розподілено між наявними Node jobs лише для вихідного коду замість очікування built artifacts. Широкі browser-, QA-, media- та різні тести Plugin використовують свої окремі конфігурації Vitest замість спільного універсального набору для Plugin. Завдання shard для розширень запускають до двох груп конфігурацій Plugin одночасно з одним worker Vitest на групу та більшим heap Node, щоб пакети Plugin з важкими імпортами не створювали додаткових CI jobs. Широкий lane agents використовує спільний file-parallel scheduler Vitest, оскільки в ньому домінують імпорти/планування, а не один конкретний повільний тестовий файл. `runtime-config` виконується разом із shard `infra core-runtime`, щоб спільний runtime shard не залишався у хвості. Шарди за include-pattern записують записи таймінгів із використанням назви CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізняти цілу конфігурацію від відфільтрованого shard. `check-additional` тримає compile/canary-перевірки меж пакунків разом і відокремлює архітектуру topology runtime від охоплення gateway watch; shard boundary guard запускає свої малі незалежні guard-перевірки паралельно в межах одного job. Gateway watch, тести каналів і shard support-boundary ядра виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи свої старі назви перевірок як легкі jobs-верифікатори та водночас уникаючи двох додаткових Blacksmith workers і другої черги споживачів артефактів. +Ручні dispatch-виклики CI запускають `checks-node-compat-node22` як покриття сумісності для кандидата на реліз. Звичайні pull request і push у `main` пропускають цю lane й зберігають фокус матриці на lanes тестів/каналів Node 24. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає debug APK для Play. Варіант third-party не має окремого набору вихідного коду чи маніфесту; його lane модульних тестів усе одно компілює цей варіант із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK при кожному push, релевантному для Android. +Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts запускаються як три зважені shard-и, тести bundled plugin балансуються між шістьма extension worker-ами, малі 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. Extension shard jobs запускають до двох груп конфігурацій plugin одночасно з одним worker-ом Vitest на групу і більшим heap Node, щоб import-heavy пакети plugin не створювали додаткові CI jobs. Широка lane agents використовує спільний file-parallel scheduler Vitest, оскільки в ній домінують імпорти/планування, а не один окремий повільний тестовий файл. `runtime-config` запускається разом із shard-ом `infra core-runtime`, щоб спільний runtime shard не замикав tail на собі. Shard-и за include-pattern записують entries таймінгів із використанням назви CI shard, тож `.artifacts/vitest-shard-timings.json` може відрізняти цілу конфігурацію від відфільтрованого shard-а. `check-additional` тримає compile/canary-роботи для package-boundary разом і відокремлює архітектуру runtime topology від покриття gateway watch; shard boundary guard запускає свої малі незалежні guard-и паралельно в межах одного job. Gateway watch, channel tests і shard support-boundary для core виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі назви check як легкі jobs-перевірники, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги artifact-consumer. -GitHub може позначати заміщені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не завершується помилкою. Агреговані shard-перевірки використовують `!cancelled() && always()`, тому вони все ще повідомляють про звичайні збої shard, але не стають у чергу після того, як увесь workflow уже було заміщено. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-тестів усе одно компілює цей flavor з прапорцями SMS/call-log у BuildConfig, водночас уникаючи дублювання job пакування debug APK на кожному push, релевантному для Android. -Ключ автоматичної concurrency CI версіоновано (`CI-v7-*`), щоб GitHub-side zombie у старій групі черги не міг безстроково блокувати новіші запуски main. Ручні повні запуски набору використовують `CI-manual-v1-*` і не скасовують запуски, що вже виконуються. +GitHub може позначати витіснені jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Ставтеся до цього як до шуму CI, якщо тільки найновіший запуск для того самого ref також не падає. Aggregate-перевірки shard-ів використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже було витіснено. -## Раннери +Ключ автоматичної concurrency CI версіонований (`CI-v7-*`), щоб zombie на боці GitHub у старій queue group не міг безстроково блокувати новіші запуски main. Ручні full-suite запуски використовують `CI-manual-v1-*` і не скасовують уже виконувані запуски. -| Раннер | Завдання | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані верифікатори 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` | +## Runner-и + +| Runner | Завдання | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі security jobs і aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled checks, sharded channel contract checks, shard-и `check`, крім lint, shard-и й aggregate `check-additional`, aggregate verifier-и Node test, docs checks, Python Skills, workflow-sanity, labeler, auto-response; preflight install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла раніше ставати в чергу | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard-и Linux Node test, shard-и bundled plugin test, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який усе ще достатньо чутливий до CPU, щоб 8 vCPU коштували дорожче, ніж давали вигоди; Docker builds для 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 # розумна локальна перевірка: changed typecheck/lint/guards за lane меж -pnpm check # швидка локальна перевірка: production tsgo + шардований lint + паралельні швидкі guards +pnpm changed:lanes # перевірити локальний класифікатор changed-lane для origin/main...HEAD +pnpm check:changed # розумний локальний check gate: changed typecheck/lint/guards за boundary lane +pnpm check # швидкий локальний gate: production tsgo + sharded lint + паралельні швидкі guards pnpm check:test-types -pnpm check:timed # та сама перевірка з таймінгами для кожного етапу +pnpm check:timed # той самий gate з таймінгами для кожного етапу 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, коли важливі lane CI artifact/build-smoke -pnpm ci:timings # підсумувати останній запуск push CI для origin/main -pnpm ci:timings:recent # порівняти нещодавні успішні запуски main CI -node scripts/ci-run-timings.mjs # підсумувати загальний час, час у черзі та найповільніші jobs -node scripts/ci-run-timings.mjs --latest-main # ігнорувати шум issue/comment і вибрати push CI для origin/main -node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI +pnpm check:docs # форматування документації + lint + broken links +pnpm build # зібрати dist, коли важливі lanes CI artifact/build-smoke +pnpm ci:timings # підсумувати останній CI-запуск push у origin/main +pnpm ci:timings:recent # порівняти нещодавні успішні CI-запуски main +node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші jobs +node scripts/ci-run-timings.mjs --latest-main # ігнорувати шум issue/comment і вибрати CI push у origin/main +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні CI-запуски main 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 ``` @@ -216,4 +233,4 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## Пов’язане - [Огляд встановлення](/uk/install) -- [Канали релізу](/uk/install/development-channels) +- [Канали релізів](/uk/install/development-channels) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 9bcf14685..984d7cc8e 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,24 +1,24 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделі/провайдера + - Додавання регресійних тестів для багів моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та те, що охоплює кожен тест' +summary: 'Набір для тестування: модульні/e2e/live набори, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-27T19:39:03Z" + generated_at: "2026-04-27T22:51:30Z" model: gpt-5.4 provider: openai - source_hash: 142d45ff5b05c38c6a8220752ac683b9b0f4492eaa3f41dc9507f1d0d885c364 + source_hash: f5adf6c223bc489d8c9eceb5a5a5b5b2c0fb774a48f6a71f6b793361e2fd4911 source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір раннерів Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для поширених сценаріїв роботи (локально, перед push, налагодження). -- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. +- Які команди запускати для типових сценаріїв (локально, перед push, налагодження). +- Як live-тести знаходять облікові дані й вибирають моделі/провайдерів. - Як додавати регресійні тести для реальних проблем моделей/провайдерів. @@ -26,162 +26,163 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, написання сценаріїв. - [Matrix QA](/uk/concepts/qa-matrix) — довідник для `pnpm openclaw qa matrix`. -- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовується в сценаріях на основі репозиторію. +- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовується сценаріями на основі репозиторію. -Ця сторінка охоплює запуск звичайних наборів тестів і Docker/Parallels-ранерів. Розділ нижче, присвячений QA-раннерам ([QA-специфічні ранери](#qa-specific-runners)), перелічує конкретні виклики `qa` і спрямовує назад до наведених вище довідкових матеріалів. +Ця сторінка охоплює запуск звичайних тестових наборів і раннерів Docker/Parallels. Розділ із QA-специфічними раннерами нижче ([QA-специфічні раннери](#qa-specific-runners)) перелічує конкретні виклики `qa` і посилається назад на наведені вище довідкові матеріали. ## Швидкий старт У більшості випадків: -- Повний gate (очікується перед 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 на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Якщо ви працюєте над однією помилкою, спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на базі Docker: `pnpm qa:lab:up` +- QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більшої впевненості: +Коли ви змінюєте тести або хочете отримати додаткову впевненість: -- Gate покриття: `pnpm test:coverage` +- Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потребує реальних облікових даних): -- Live-набір (моделі + gateway-перевірки інструментів/зображень): `pnpm test:live` -- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker-прогін live-моделей: `pnpm test:docker:live-models` - - Для кожної вибраної моделі тепер виконується текстовий хід плюс невелика перевірка у стилі читання файлу. - Моделі, чиї метадані вказують на вхід `image`, також виконують маленький хід із зображенням. +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Огляд live-моделей у Docker: `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` і ручний + - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, який містить окремі матричні Docker-job для live-моделей, - розбиті за провайдером. - - Для цільових повторних запусків у CI запускайте `OpenClaw Live And E2E Checks (Reusable)` + `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` і його - виклики за розкладом/релізом. -- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - - Запускає Docker live-лінію проти шляху app-server Codex, прив’язує синтетичний - Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення - із зображенням проходять через native binding Plugin, а не через ACP. -- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` - - Пропускає ходи gateway-агента через harness app-server Codex, що належить Plugin, - перевіряє `/codex status` і `/codex models`, а також за замовчуванням виконує перевірки image, + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + запланованих/релізних викликів. +- Димовий тест native Codex bound-chat: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний + Slack DM за допомогою `/codex bind`, виконує `/codex fast` і + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення + проходять через native-прив’язку Plugin, а не через ACP. +- Димовий тест harness Codex app-server: `pnpm test:docker:live-codex-harness` + - Пропускає ходи агента Gateway через harness app-server, який належить 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_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex + app-server. Для точкової перевірки 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`. - Цей запуск завершується після перевірки sub-agent, якщо не встановлено + Це завершиться після перевірки sub-agent, якщо тільки не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. -- Smoke перевірка команди rescue Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Добровільна додаткова перевірка поверхні команди rescue для message-channel. - Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі, - відповідає `/crestodian yes` і перевіряє шлях запису audit/config. -- Docker smoke планувальника Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з підробленим Claude CLI в `PATH` - і перевіряє, що нечіткий fallback планувальника перетворюється на аудований типізований запис конфігурації. -- Docker smoke першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього каталогу стану OpenClaw, спрямовує простий `openclaw` до - Crestodian, застосовує setup/model/agent/Discord Plugin + записи SecretRef, - валідує конфігурацію та перевіряє записи аудиту. Той самий шлях налаштування Ring 0 +- Димовий тест rescue-команди Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Додаткова opt-in перевірка «belt-and-suspenders» для поверхні rescue-команд + message-channel. Вона виконує `/crestodian status`, ставить у чергу стійку зміну + моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. +- Димовий тест Docker planner Crestodian: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без конфігурації з підставним Claude CLI у `PATH` + і перевіряє, що резервний нечіткий planner перетворюється на audited typed + запис конфігурації. +- Димовий тест першого запуску Crestodian у Docker: `pnpm test:docker:crestodian-first-run` + - Починає з порожнього каталогу стану OpenClaw, спрямовує голий `openclaw` до + Crestodian, застосовує записи setup/model/agent/Discord Plugin + SecretRef, + валідує конфігурацію і перевіряє записи audit. Той самий шлях налаштування Ring 0 також покрито в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Smoke перевірка вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім ізольований +- Димовий тест вартості 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-тестів через env-змінні allowlist, описані нижче. +Коли вам потрібен лише один збійний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. -## QA-специфічні ранери +## QA-специфічні раннери -Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди стоять поруч із основними тестовими наборами, коли вам потрібен реалізм QA-lab: CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR і -через ручний запуск з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний запуск із mock parity gate, live-лінією Matrix, -live-лінією Telegram під керуванням Convex і live-лінією Discord під керуванням Convex -як паралельні job. Заплановані перевірки QA і релізу явно передають Matrix `--profile fast`, -тоді як CLI Matrix і стандартне значення ручного параметра workflow залишаються -`all`; ручний запуск може розбивати `all` на job `transport`, `media`, `e2ee-smoke`, +через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний dispatch із mock parity gate, live Matrix lane, +live Telegram lane під керуванням Convex і live Discord lane під керуванням Convex як +паралельними завданнями. Заплановані QA і релізні перевірки явно передають Matrix `--profile fast`, +тоді як CLI Matrix і стандартне значення ручного вводу workflow лишаються +`all`; ручний dispatch може розбивати `all` на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс -швидкі лінії Matrix і Telegram перед схваленням релізу. +швидкі lane Matrix і Telegram перед схваленням релізу. - `pnpm openclaw qa suite` - Запускає сценарії QA на основі репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - worker gateway. Для `qa-channel` типове значення concurrency — 4 (обмежується - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість - worker, або `--concurrency 1` для старішої послідовної лінії. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли - хочете отримати артефакти без помилкового коду завершення. - - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на основі AIMock для експериментального - покриття фікстур і моків протоколу без заміни сценарійно-орієнтованої - лінії `mock-openai`. + - За замовчуванням паралельно запускає кілька вибраних сценаріїв з ізольованими + worker-процесами Gateway. `qa-channel` за замовчуванням використовує concurrency 4 (обмежену + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати + кількість worker-процесів, або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо якийсь сценарій не вдається. Використовуйте `--allow-failures`, коли + вам потрібні артефакти без коду завершення з помилкою. + - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття фікстур і макетів протоколу без заміни lane `mock-openai`, + орієнтованого на сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані автентифікації QA, які практичні для гостьової системи: - ключі провайдера на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, + - Live-запуски прокидають підтримувані вхідні дані QA auth, практичні для гостьової системи: + ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через - змонтований workspace. - - Записує звичайний звіт QA + підсумок, а також логи Multipass у + - Каталоги виводу мають лишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + змонтовану робочу область. + - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає сайт QA на базі Docker для операторської роботи з QA. + - Запускає QA-сайт на базі Docker для операторської роботи з QA. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball із поточного checkout, глобально встановлює його в - Docker, запускає неінтерактивне онбординг-налаштування ключа OpenAI API, за замовчуванням налаштовує - Telegram, перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму лінію - встановлення з пакета з Discord. + Docker, виконує неінтерактивне onboarding за API-ключем OpenAI, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, + запускає doctor і виконує один локальний хід агента проти змакованого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane + пакетного встановлення з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає детермінований Docker smoke built-app для вбудованих транскриптів runtime context. - Він перевіряє, що прихований runtime context OpenClaw зберігається як - користувацьке повідомлення, яке не відображається, замість витоку у видимий хід користувача, - потім підкладає пошкоджений JSONL сесії й перевіряє, що - `openclaw doctor --fix` переписує його на активну гілку з резервною копією. + - Запускає детермінований Docker smoke built-app для вбудованих стенограм + runtime context. Він перевіряє, що прихований runtime context OpenClaw зберігається як + нестандартне повідомлення, яке не відображається, замість витоку у видимий хід користувача, + а потім підкладає уражений пошкоджений session JSONL і перевіряє, що + `openclaw doctor --fix` переписує його в активну гілку з резервною копією. - `pnpm test:docker:npm-telegram-live` - - Встановлює кандидат пакета OpenClaw у Docker, запускає онбординг встановленого пакета, - налаштовує Telegram через встановлений CLI, а потім повторно використовує - live-лінію Telegram QA з цим встановленим пакетом як Gateway SUT. + - Встановлює кандидата пакета OpenClaw у Docker, виконує onboarding + встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує + live Telegram QA lane із цим встановленим пакетом як SUT Gateway. - За замовчуванням використовується `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 замість встановлення з реєстру. - - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/релізів встановіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс + - Використовує ті самі облікові дані Telegram з env або джерело облікових даних Convex, що й + `pnpm openclaw qa telegram`. Для автоматизації CI/релізу встановіть + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`, а також `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, Docker-обгортка автоматично вибирає Convex. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний - `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цієї лінії. - - GitHub Actions також надає цю лінію як ручний workflow для супровідників - `NPM Telegram Beta E2E`. Вона не запускається під час merge. Workflow використовує + - `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. -- GitHub Actions також надає `Package Acceptance` для побічного підтвердження продукту - проти одного кандидата пакета. Він приймає довірений ref, опубліковану npm-spec, - HTTPS URL tarball із SHA-256 або артефакт tarball з іншого запуску, завантажує - нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає - наявний Docker E2E scheduler з профілями ліній smoke, package, product, full або custom. +- GitHub Actions також надає `Package Acceptance` для побічної перевірки продукту + проти одного кандидата пакета. Він приймає довірений ref, опубліковану npm-специфікацію, + URL HTTPS tarball плюс SHA-256 або артефакт tarball з іншого запуску, + завантажує нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає + наявний планувальник Docker E2E з профілями lane smoke, package, product, full або custom. Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити workflow Telegram QA проти того самого артефакту `package-under-test`. - - Підтвердження продукту для останньої beta: + - Перевірка продукту для останньої beta: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -191,7 +192,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Підтвердження через точний URL tarball потребує digest: +- Перевірка точного URL tarball вимагає digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -201,7 +202,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Підтвердження через артефакт завантажує артефакт tarball з іншого запуску Actions: +- Перевірка артефакта завантажує артефакт tarball з іншого запуску Actions: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -215,78 +216,76 @@ gh workflow run package-acceptance.yml --ref main \ - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, а потім вмикає вбудовані channel/plugins через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає неналаштовані runtime-залежності Plugin - відсутніми, перший налаштований запуск Gateway або doctor встановлює runtime-залежності - кожного вбудованого Plugin за потреби, а другий перезапуск не перевстановлює - залежності, які вже були активовані. - - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском + - Перевіряє, що виявлення налаштування залишає невідсутніми runtime-залежності + неналаштованих Plugin, перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного вбудованого Plugin за потреби, а другий перезапуск не + перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском `openclaw update --tag `, і перевіряє, що - post-update doctor кандидата виправляє runtime-залежності вбудованого channel без - postinstall-виправлення з боку harness. + post-update doctor кандидата відновлює runtime-залежності вбудованого channel без + postinstall-відновлення з боку harness. - `pnpm test:parallels:npm-update` - - Запускає native smoke перевірку оновлення встановленого пакета в гостях Parallels. Для кожної - вибраної платформи спочатку встановлюється запитаний baseline-пакет, потім - у тій самій гостьовій системі запускається встановлена команда `openclaw update`, після чого перевіряються - встановлена версія, статус оновлення, готовність gateway і один локальний - хід агента. - - Використовуйте `--platform macos`, `--platform windows` або `--platform linux`, коли - ітеруєтеся над однією гостьовою системою. Використовуйте `--json` для отримання шляху до артефакту підсумку та - статусу кожної лінії. - - Лінія OpenAI за замовчуванням використовує `openai/gpt-5.5` для live-перевірки + - Запускає smoke-тест оновлення native packaged-install у гостьових системах Parallels. Кожна + вибрана платформа спочатку встановлює запитаний baseline-пакет, потім виконує + встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє встановлену + версію, статус оновлення, готовність gateway і один локальний хід агента. + - Під час ітерацій над однією гостьовою системою використовуйте `--platform macos`, `--platform windows` або `--platform linux`. + Використовуйте `--json` для шляху до підсумкового артефакту та статусу + для кожного lane. + - Lane OpenAI за замовчуванням використовує `openai/gpt-5.5` для live-доказу ходу агента. Передайте `--model ` або встановіть `OPENCLAW_PARALLELS_OPENAI_MODEL`, якщо навмисно перевіряєте іншу модель OpenAI. - Обгортайте тривалі локальні запуски в host timeout, щоб зависання транспорту Parallels - не поглинало решту вікна тестування: + не поглинули решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені логи ліній у `/tmp/openclaw-parallels-npm-update.*`. + - Скрипт записує вкладені журнали lane у `/tmp/openclaw-parallels-npm-update.*`. Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, перш ніж вважати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати 10–15 хвилин на post-update doctor/виправлення - runtime-залежностей на холодній гостьовій системі; це все ще є нормальним станом, якщо вкладений - npm debug log продовжує оновлюватися. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke-лініями Parallels - для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати через - відновлення snapshot, роздачу пакетів або стан gateway у гостьовій системі. - - Post-update-перевірка запускає звичайну поверхню вбудованого Plugin, тому що - фасади можливостей, такі як speech, image generation і media - understanding, завантажуються через вбудовані runtime API навіть тоді, коли сам + - Оновлення Windows може витрачати 10–15 хвилин на post-update doctor/відновлення + runtime-залежностей у «холодній» гостьовій системі; це все ще є нормальним станом, коли + вкладений журнал налагодження npm продовжує оновлюватися. + - Не запускайте цю агреговану обгортку паралельно з окремими smoke-lane Parallels + для macOS, Windows або Linux. Вони використовують спільний стан VM і можуть конфліктувати під час + відновлення snapshot, видачі пакета або стану gateway у гостьовій системі. + - Post-update proof запускає звичайну поверхню вбудованого Plugin, оскільки + фасади можливостей, як-от speech, image generation і media + understanding, завантажуються через вбудовані runtime API, навіть якщо сам хід агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування - протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live-лінію Matrix QA проти тимчасового homeserver Tuwunel на базі Docker. Лише для source-checkout — встановлення з пакета не постачає `qa-lab`. - - Повний CLI, каталог профілів/сценаріїв, env-змінні та структура артефактів: [Matrix QA](/uk/concepts/qa-matrix). + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. Лише для checkout вихідного коду — packaged installs не постачають `qa-lab`. + - Повний CLI, каталог profile/scenario, змінні середовища та розкладка артефактів: [Matrix QA](/uk/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Запускає live-лінію Telegram QA проти реальної приватної групи, використовуючи токени driver і SUT bot з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути оренду зі спільного пулу. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли - хочете отримати артефакти без помилкового коду завершення. - - Потребує двох різних ботів в одній приватній групі, причому SUT bot має мати Telegram username. + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени driver і SUT bot з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулінгові оренди. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли + вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, при цьому SUT bot має мати видиме ім’я користувача Telegram. - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver bot може спостерігати трафік ботів у групі. - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. -Live-лінії transport мають один спільний стандартний контракт, щоб нові transport не розходилися; матриця покриття для окремих ліній знаходиться в [QA overview → Live transport coverage](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір, і він не є частиною цієї матриці. +Live transport lanes мають спільний стандартний контракт, щоб нові транспорти не розходилися; матриця покриття для окремих lane міститься в [Огляд QA → Покриття live transport](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і не входить до цієї матриці. ### Спільні облікові дані Telegram через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -цієї оренди, поки лінія виконується, і звільняє оренду під час завершення роботи. +Коли для +`openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +для цієї оренди, поки lane виконується, і звільняє оренду під час завершення роботи. Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env-змінні: +Обов’язкові змінні середовища: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: @@ -294,24 +293,24 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `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-змінні: +Необов’язкові змінні середовища: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типове значення `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типове значення `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типове значення `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типове значення `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типове значення `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. -У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди супровідника (додавання/видалення/перелік пулу) потребують +Адміністративні команди мейнтейнера (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для супровідників: +Допоміжні команди CLI для мейнтейнерів: ```bash pnpm openclaw qa credentials doctor @@ -320,11 +319,11 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker, -префікс endpoint, HTTP timeout і доступність admin/list без виведення -значень секретів. Використовуйте `--json` для машиночитаного виводу в скриптах і CI-утилітах. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайта Convex, секрети брокера, +префікс endpoint, HTTP timeout і доступність admin/list, не виводячи +секретні значення. Використовуйте `--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 }` @@ -350,73 +349,73 @@ pnpm openclaw qa credentials remove --credential-id Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим Telegram chat id. +- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. -### Додавання channel до QA +### Додавання каналу до QA -Архітектура та назви scenario-helper для нових channel-адаптерів описані в [QA overview → Adding a channel](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна вимога: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті Plugin, змонтувати як `openclaw qa ` і написати сценарії в `qa/scenarios/`. +Архітектура та назви допоміжних сценаріїв для нових адаптерів каналів наведені в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті Plugin, змонтувати як `openclaw qa ` і написати сценарії в `qa/scenarios/`. -## Набори тестів (що де запускається) +## Тестові набори (що де запускається) -Думайте про ці набори як про «зростання реалістичності» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: нетаргетовані запуски використовують набір шардованих конфігів `vitest.full-*.config.ts` і можуть розгортати багатопроєктні shard у конфіги на рівні окремих проєктів для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; unit-тести UI запускаються в окремому shard `unit-ui` +- Конфігурація: нетаргетовані запуски використовують набір шардованих конфігурацій `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в конфігурації для окремих проєктів для паралельного планування +- Файли: core/unit інвентарі в `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; UI unit-тести виконуються в окремому шарді `unit-ui` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресійні тести для відомих багів + - In-process integration-тести (auth Gateway, маршрутизація, tooling, парсинг, конфігурація) + - Детерміновані регресії для відомих багів - Очікування: - Запускається в 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`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` і далі використовує native root-граф проєктів `vitest.config.ts`, тому що цикл watch із багатьма shard непрактичний. - - `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-графа. Зміни 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-синтаксис для live Docker auth-скриптів і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежено `scripts["test:docker:live-*"]`; зміни залежностей, exports, version та інших поверхонь package, як і раніше, використовують ширші guard. - - Полегшені за import unit-тести для agents, commands, plugins, хелперів auto-reply, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через лінію `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом або важкі для runtime лишаються на наявних лініях. - - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски в changed-mode з явними сусідніми тестами в цих легких лініях, тож зміни в хелперах не примушують повторно запускати весь важкий набір для цього каталогу. - - `auto-reply` має окремі кошики для top-level core helper, top-level integration-тестів `reply.*` і піддерева `src/auto-reply/reply/**`. У CI піддерево reply додатково ділиться на шарди agent-runner, dispatch і commands/state-routing, щоб один важкий щодо import кошик не забирав увесь хвіст Node. + - Нетаргетований `pnpm test` запускає дванадцять менших шардованих конфігурацій (`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`) замість одного гігантського native root-project process. Це зменшує піковий RSS на навантажених машинах і не дає роботам `auto-reply`/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл watch із кількома шардами не є практичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через scoped lane, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не змушує оплачувати повну вартість запуску root project. + - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lane: прямі редагування тестів, сусідні файли `*.test.ts`, явні зіставлення вихідного коду та локальні залежні елементи графа імпортів. Зміни config/setup/package не запускають тести широко, якщо ви явно не використовуєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — це звичайний smart local 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 запускають цільові перевірки версій/config/root-dependency, із guard, який відхиляє зміни package поза полем version верхнього рівня. + - Зміни в live Docker ACP harness запускають точкові перевірки: синтаксис shell для live Docker auth-скриптів і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежено `scripts["test:docker:live-*"]`; зміни залежностей, export, version та іншої surface package усе ще використовують ширші guard. + - Unit-тести з малим імпортним навантаженням із agents, commands, plugins, допоміжних модулів auto-reply, `plugin-sdk` та подібних чистих утилітних областей спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lane. + - Вибрані допоміжні вихідні файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lane, тож редагування helper не змушують перезапускати повний важкий набір для цього каталогу. + - `auto-reply` має окремі бакети для допоміжних модулів core верхнього рівня, integration-тестів верхнього рівня `reply.*` і піддерева `src/auto-reply/reply/**`. У CI піддерево reply додатково ділиться на шарди agent-runner, dispatch і commands/state-routing, щоб один bucket із важкими імпортами не володів усім Node tail. - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime context - Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації та + - Коли ви змінюєте входи виявлення message-tool або runtime + context для Compaction, зберігайте обидва рівні покриття. + - Додавайте точкові helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте інтеграційні набори embedded runner у здоровому стані: + - Підтримуйте здоровий стан інтеграційних наборів 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 id і поведінка Compaction, як і раніше, проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести + - Ці набори перевіряють, що scoped id і поведінка Compaction як і раніше проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих інтеграційних шляхів. - + - - Базова конфігурація Vitest типово використовує `threads`. + - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у root projects, e2e та live-конфігах. - - Root-лінія UI зберігає своє налаштування `jsdom` і optimizer, але теж запускається на - спільному неізольованому runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + non-isolated runner у root project, e2e та live config. + - Root UI lane зберігає свій `jsdom` setup та optimizer, але теж працює на + спільному non-isolated runner. + - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів - Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. + - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, + щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. @@ -424,24 +423,24 @@ pnpm openclaw qa credentials remove --credential-id - - `pnpm changed:lanes` показує, які архітектурні лінії зачіпає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно індексує відформатовані файли й + - `pnpm changed:lanes` показує, які архітектурні lane зачіпає diff. + - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до stage і не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передачею чи push, коли вам - потрібен розумний локальний gate перевірок. - - `pnpm test:changed` типово маршрутизує через дешеві scoped lanes. Використовуйте - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент - вирішує, що зміна harness, config, package або contract справді потребує ширшого + - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли + вам потрібен smart local check gate. + - `pnpm test:changed` за замовчуванням маршрутизує через дешеві scoped lane. Використовуйте + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише коли агент + вирішує, що редагування harness, config, package або contract справді потребує ширшого покриття Vitest. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - просто з вищою межею worker. - - Автомасштабування локальних worker навмисно консервативне й зменшує навантаження, + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму логіку маршрутизації, + лише з вищою межею worker. + - Автомасштабування локальних worker навмисно консервативне і зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних - запусків Vitest за замовчуванням завдають менше шкоди. + запусків Vitest за замовчуванням шкодять менше. - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється - wiring тестів. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + `forceRerunTriggers`, щоб повторні запуски в changed-mode лишалися коректними, коли змінюється + обв’язка тестів. + - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. @@ -449,169 +448,169 @@ pnpm openclaw qa credentials remove --credential-id - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import плюс - вивід розбивки import. + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс + вивід import-breakdown. - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд - файлами, зміненими відносно `origin/main`. - - Дані про час shard записуються в `.artifacts/vitest-shard-timings.json`. - Запуски для всього config використовують шлях config як ключ; CI-shard - з include-pattern додають ім’я shard, щоб відфільтровані shard можна було - відстежувати окремо. - - Коли один гарячий тест усе ще витрачає більшість часу на стартові import, + файлами, зміненими з часу `origin/main`. + - Дані про час виконання шардів записуються в `.artifacts/vitest-shard-timings.json`. + Запуски всієї конфігурації використовують шлях до config як ключ; CI-шарди + за include-pattern додають назву шарда, щоб можна було окремо + відстежувати відфільтровані шарди. + - Коли один «гарячий» тест усе ще витрачає більшість часу на стартові імпорти, тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - мокайте цей seam напряму, замість глибокого import runtime-хелперів лише - для того, щоб передати їх через `vi.mock(...)`. + напряму макетуйте цей seam замість глибокого імпорту runtime-helper, лише + щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із native root-project-шляхом для цього зафіксованого + `test:changed` з native root-project path для цього зафіксованого 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-профіль main-thread для - накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner для + - `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне + незакомічене дерево, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для + старту Vitest/Vite і transform overhead. + - `pnpm test:perf:profile:runner` записує профілі runner CPU+heap для unit-набору з вимкненим паралелізмом файлів. -### Стабільність (gateway) +### Стабільність (Gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з діагностикою, увімкненою за замовчуванням - - Проганяє синтетичне навантаження повідомленнями gateway, пам’яттю та великими payload через шлях діагностичних подій - - Опитує `diagnostics.stability` через Gateway WS RPC - - Охоплює хелпери збереження diagnostic stability bundle - - Перевіряє, що recorder лишається обмеженим, синтетичні RSS-вибірки лишаються в межах бюджету тиску, а глибина черг для кожної сесії знову зменшується до нуля + - Запускає реальний loopback Gateway з увімкненою за замовчуванням діагностикою + - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій + - Виконує запит до `diagnostics.stability` через WS RPC Gateway + - Покриває helper-модулі збереження diagnostic stability bundle + - Перевіряє, що recorder лишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибина черги для кожної сесії знову зменшується до нуля - Очікування: - - Безпечно для CI та без ключів - - Вузька лінія для подальших дій щодо регресій стабільності, а не заміна повного набору Gateway + - Безпечно для CI і без ключів + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (gateway smoke) +### E2E (Gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin у `extensions/` -- Типові налаштування runtime: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість worker (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на вивід у консоль. +- Типові значення runtime: + - Використовує Vitest `threads` з `isolate: false`, як і в решті репозиторію. + - Використовує адаптивних worker (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` для примусового встановлення кількості worker (максимум 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути детальний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість worker (обмеження 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end-поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, спарювання Node та складніші мережеві сценарії + - Наскрізна поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження - Очікування: - - Запускається в CI (коли увімкнено в pipeline) - - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Запускається в CI (коли ввімкнено в pipeline) + - Не потребує реальних ключів + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: smoke перевірка backend OpenShell +### E2E: OpenShell backend smoke - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований Gateway OpenShell на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальний `sandbox ssh-config` + виконання через SSH - - Перевіряє поведінку файлової системи в remote-canonical режимі через bridge fs sandbox + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - - Лише за бажанням; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і справного Docker daemon + - Лише opt-in; не входить до типового запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і справного демона Docker - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний двійковий файл CLI або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `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`) +- Типове значення: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit + - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей tool calling, проблем auth і поведінки 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`), або використовуйте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. + - Коштує грошей / витрачає rate limits + - Краще запускати звужені підмножини, а не «все» +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасову тестову home-директорію, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували вашу реальну home-директорію. +- `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`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести виконують повторну спробу при відповідях із rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів було видно як активні навіть тоді, коли захоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі у Vitest, тому рядки прогресу провайдера/gateway передаються відразу під час live-запусків. + - 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`. ## Який набір мені запускати? -Використовуйте таку таблицю рішень: +Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) - Торкаєтеся мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / виклик інструментів: запускайте звужений `pnpm test:live` +- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / tool calling: запускайте звужений `pnpm test:live` -## Live-тести (із доступом до мережі) +## Live-тести (що торкаються мережі) -Для матриці live-моделей, smoke-перевірок backend CLI, ACP smoke, harness -app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також для роботи з обліковими даними під час live-запусків — див. +Для live-матриці моделей, smoke-тестів бекенда CLI, smoke-тестів ACP, harness +Codex app-server і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також обробки облікових даних для live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). -## Docker-ранери (необов’язкові перевірки «працює в Linux») +## Раннери Docker (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці раннери Docker поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл за ключем профілю всередині 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`, +- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл свого ключа профілю всередині 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 runners за замовчуванням мають менший 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-змінні, коли + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env var, коли вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ — це лише Node/Git-ранер для ліній install/update/plugin-dependency; ці лінії монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/app` для ліній функціональності built-app. Визначення Docker-ліній знаходяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегатор використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як обмеження ресурсів не дають важким live-, npm-install- і multi-service-лініям стартувати одночасно. Якщо одна лінія важча за активні обмеження, планувальник усе одно може запустити її, коли пул порожній, а потім триматиме її єдиною активною, доки знову не з’явиться доступна місткість. Типові значення: 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-хост має більший запас ресурсів. Ранер за замовчуванням виконує 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` — це нативний package-gate GitHub для перевірки «чи працює цей installable 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` — package/update/plugin contract і типова native-замiна для більшості пакетних/оновлювальних перевірок Parallels, `product` додає MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI, а `full` запускає Docker-частини шляху релізу з OpenWebUI. Перевірка релізу запускає custom package delta (`bundled-channel-deps-compat plugins-offline`) плюс Telegram package QA, тому що Docker-частини шляху релізу вже покривають лінії package/update/plugin, що перетинаються. Цільові команди повторного запуску Docker у GitHub, згенеровані з артефактів, включають попередній артефакт пакета та підготовлені входи образів, коли вони доступні, тому збійні лінії можуть уникнути повторного збирання пакета й образів. -- Перевірки збирання та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичний built-граф від `dist/entry.js` і `dist/cli/run-main.js` та завершується помилкою, якщо startup-import-и до dispatch завантажують залежності пакета, такі як Commander, prompt UI, undici або logging, ще до диспетчеризації команди. Smoke перевірка запакованого CLI також охоплює root help, onboard help, doctor help, status, schema config і команду model-list. -- Legacy-сумісність `Package Acceptance` обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише прогалини в метаданих уже випущених пакетів: пропущені private QA inventory entries, відсутній `gateway install --wrapper`, відсутні patch-файли у git-фікстурі, похідній від tarball, відсутній збережений `update.channel`, legacy-розташування install-record Plugin, відсутнє збереження marketplace install-record і міграцію метаданих config під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи вважаються строгими збоями. -- Контейнерні 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` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає Docker-образ live через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ — це лише раннер Node/Git для lane встановлення/оновлення/залежностей Plugin; ці lane монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/app` для lane функціональності built-app. Визначення Docker lane містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким lane live, npm-install і multi-service запускатися всі одночасно. Якщо один lane важчий за активні обмеження, планувальник все одно може запустити його, коли пул порожній, а потім тримає його запущеним окремо, доки знову не з’явиться доступна місткість. Типові значення: 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 має більший запас ресурсів. Раннер за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає час виконання успішних lane в `.artifacts/docker-tests/lane-timings.json` і використовує ці часові дані, щоб у наступних запусках першими стартували довші lane. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збірки чи запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб вивести CI-план для вибраних lane, потреб package/image і облікових даних. +- `Package Acceptance` — це GitHub-native перевірка пакета для питання «чи працює цей installable tarball як продукт?». Вона визначає один кандидат пакета з `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає повторно використовувані Docker E2E lane проти саме цього tarball, замість повторного пакування вибраного ref. `workflow_ref` вибирає trusted workflow/harness scripts, а `package_ref` вибирає вихідний commit/branch/tag для пакування, коли `source=ref`; це дає змогу поточній логіці acceptance перевіряти старі trusted commit. Профілі впорядковано за шириною охоплення: `smoke` — це швидке встановлення/channel/agent плюс gateway/config, `package` — це контракт package/update/plugin і типовий native replacement для більшості покриття package/update у Parallels, `product` додає MCP channels, очищення cron/subagent, OpenAI web search і OpenWebUI, а `full` запускає Docker-частини release-path з OpenWebUI. Валідація релізу запускає власну package delta (`bundled-channel-deps-compat plugins-offline`) плюс Telegram package QA, оскільки Docker-частини release-path уже покривають overlap lane package/update/plugin. Цільові команди повторного запуску GitHub Docker, згенеровані з артефактів, включають попередній артефакт пакета та підготовлені входи image, коли вони доступні, тож збійні lane можуть уникнути повторної збірки пакета й образів. +- Перевірки збірки та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичним built graph від `dist/entry.js` і `dist/cli/run-main.js` та завершується з помилкою, якщо до command dispatch startup імпортує залежності package, як-от Commander, prompt UI, undici або logging. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, schema config і команду model-list. +- Legacy compatibility у Package Acceptance обмежено версією `2026.4.25` (включно з `2026.4.25-beta.*`). До цього порогу harness допускає лише прогалини в метаданих shipped-package: пропущені приватні записи інвентарю QA, відсутній `gateway install --wrapper`, відсутні patch-файли у git fixture, похідному від tarball, відсутній збережений `update.channel`, застарілі розташування install-record Plugin, відсутнє збереження install-record marketplace і міграцію метаданих config під час `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` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-моделей також bind-mount-ять лише потрібні CLI auth home (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth store хоста: +Docker-раннери live-моделей також монтують лише потрібні home-каталоги auth CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home-каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище auth на хості: - Прямі моделі: `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 перевірка backend CLI: `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: `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: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Димовий тест harness Codex app-server: `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` — це приватна QA-лінія для source-checkout. Вона навмисно не входить до package Docker-ліній релізу, оскільки npm tarball не містить QA Lab. -- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер онбордингу (TTY, повне scaffold-налаштування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke перевірка npm tarball для онбордингу/channel/agent: `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 rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте channel через `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` повертає вбудовані image-провайдери, а не зависає. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Smoke перевірка Docker-інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm-кеш для своїх root-, update- і direct-npm-контейнерів. Smoke перевірка оновлення за замовчуванням використовує npm `latest` як stable baseline перед оновленням до tarball-кандидата. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`, або через вхід workflow Install Smoke `update_baseline_version` у GitHub. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm у локальних повторних запусках. -- CI Install Smoke пропускає дубльоване пряме глобальне оновлення npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- Smoke перевірка CLI для видалення agents зі спільного 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`. +- Димовий тест observability: `pnpm qa:otel:smoke` — це приватний QA lane для checkout вихідного коду. Він навмисно не входить до Docker lane релізу пакетів, оскільки npm tarball не містить QA Lab. +- Димовий тест live Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Димовий тест onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding env-ref і за замовчуванням Telegram, перевіряє, що doctor відновлює runtime deps активованого Plugin, і виконує один змакований хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змінюйте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Димовий тест перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений channel і роботу Plugin після оновлення, а потім повертається до package `stable` і перевіряє статус оновлення. +- Димовий тест session runtime context: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого стенографічного runtime context, а також doctor-відновлення для уражених дубльованих гілок prompt-rewrite. +- Димовий тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home-каталозі й перевіряє, що `openclaw infer image providers --json` повертає вбудовані image providers замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Димовий тест інсталятора в Docker: `bash scripts/test-install-sh-docker.sh` використовує спільний npm-кеш для своїх контейнерів root, update і direct-npm. Димовий тест оновлення за замовчуванням використовує npm `latest` як stable baseline перед оновленням до tarball кандидата. Локально перевизначайте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22`, або через вхід `update_baseline_version` workflow Install Smoke у GitHub. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб root-owned записи кешу не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- CI Install Smoke пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; локально запускайте скрипт без цього env, коли потрібне покриття прямого `npm install -g`. +- Димовий тест 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 перевірка snapshot для Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E-образ плюс шар Chromium, запускає Chromium з сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshot-и ролі CDP охоплюють 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 bridge channel (seeded Gateway + stdio bridge + raw smoke перевірка кадрів повідомлень Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Pi bundle MCP tools (реальний 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 та увімкнення/перевірка Claude-bundle): `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 перевірка метаданих reload config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності вбудованого Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає малий Docker-образ раннера, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вказуйте на наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегатор і chunk `bundled-channels` для шляху релізу попередньо пакують цей tarball один раз, а потім розбивають перевірки вбудованих channel на незалежні лінії, включно з окремими лініями оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Workflow релізу також розбиває chunks інсталятора провайдера та chunks встановлення/видалення вбудованого Plugin; legacy-chunk-и `package-update`, `plugins-runtime` і `plugins-integrations` залишаються агрегованими псевдонімами для ручних повторних запусків. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю channel під час прямого запуску вбудованої лінії, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Лінія також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують виправлення doctor/runtime-dependency. -- Поки ітеруєтеся, звужуйте runtime-залежності вбудованого Plugin, вимикаючи непов’язані сценарії, наприклад: +- Димовий тест browser CDP snapshot: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає вихідний E2E-образ плюс шар Chromium, запускає Chromium з сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshots ролі CDP покривають URL посилань, clickables із просунутим курсором, refs iframe і метадані 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`, потім примусово викликає відхилення provider schema і перевіряє, що сирі подробиці з’являються в журналах Gateway. +- Міст каналу MCP (seeded Gateway + stdio bridge + димовий тест raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти Pi bundle MCP (реальний stdio MCP server + димовий тест allow/deny для профілю embedded Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення Cron/subagent MCP (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (димовий тест встановлення, встановлення/видалення ClawHub, оновлення marketplace і ввімкнення/перевірка Claude-bundle): `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`. +- Димовий тест Plugin update unchanged: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Димовий тест метаданих config reload: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime deps вбудованих Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker runner, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вкажіть наявний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний агрегат Docker і частини release-path bundled-channel один раз попередньо пакують цей tarball, а потім розбивають перевірки bundled channel на незалежні lane, включно з окремими lane оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Частини релізу розділяють димові тести каналів, цілі оновлення та контракти setup/runtime на `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`; агрегатний блок `bundled-channels` лишається доступним для ручних повторних запусків. Workflow релізу також розділяє частини installer провайдерів і частини встановлення/видалення вбудованих Plugin; застарілі частини `package-update`, `plugins-runtime` і `plugins-integrations` лишаються агрегатними псевдонімами для ручних повторних запусків. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. +- Звужуйте runtime deps вбудованих 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`. Щоб вручну попередньо зібрати та повторно використовувати спільний функціональний образ: @@ -621,110 +620,110 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker: OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів на рівні конкретного набору, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку package/install, а не спільний runtime built-app. +Перевизначення образів для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime built-app. -Docker-ранери live-моделей також монтують поточний checkout лише для читання і -розміщують його у тимчасовому workdir усередині контейнера. Це зберігає runtime-образ -компактним, але водночас дає змогу запускати Vitest точно проти вашого локального source/config. -Етап розміщення пропускає великі локальні кеші та вихідні дані збірки застосунків, такі -як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +Docker-раннери live-моделей також монтують поточний checkout лише для читання і +переміщують його в тимчасовий workdir усередині контейнера. Це зберігає +runtime-образ компактним, але водночас запускає Vitest точно проти вашого локального source/config. +Крок переміщення пропускає великі локальні кеші та результати збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-проби gateway не запускали -реальні worker channel Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` все одно запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway -live з цієї Docker-лінії. -`test:docker:openwebui` — це smoke перевірка сумісності вищого рівня: вона запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +справжні worker-процеси каналів Telegram/Discord/etc. усередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття gateway +live із цього Docker lane. +`test:docker:openwebui` — це суміснісний smoke-тест вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити власне холодне стартове налаштування. -Ця лінія очікує наявності придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` -(за замовчуванням `~/.profile`) — це основний спосіб надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний запит чату через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження +образу Open WebUI, а сам Open WebUI — завершення власного холодного старту. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — це основний спосіб надати його в Dockerized-запусках. +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує +`test:docker:mcp-channels` навмисно детермінований і не потребує реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -у контейнері, запускає другий контейнер, який породжує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованої розмови, читання транскриптів, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідного надсилання та повідомлення у стилі Claude для channel + -permission через реальний stdio MCP bridge. Перевірка повідомлень -безпосередньо аналізує сирі stdio MCP-кадри, тож smoke перевірка валідує те, що -bridge реально випромінює, а не лише те, що певний client SDK випадково показує. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує -ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через runtime вбудованого Pi bundle +контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє маршрутизоване виявлення розмов, читання стенограм, метадані вкладень, +поведінку live event queue, маршрутизацію вихідного надсилання та сповіщення каналу + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +напряму досліджує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що +міст справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live-моделі. +Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через runtime embedded Pi bundle MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. Він запускає seeded Gateway з реальним stdio MCP probe server, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручна smoke перевірка ACP plain-language thread (не в CI): +Ручний smoke-тест ACP thread природною мовою (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для валідації маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. -Корисні env-змінні: +Корисні env var: -- `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-змінні, зчитані з `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/...` перед початком тестів +- `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 var, отримані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішніх auth CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типове значення: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли auth CLI в `$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_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=...`, щоб перевизначити nonce-check prompt, який використовує smoke перевірка Open WebUI +- `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, який використовує smoke-тест Open WebUI - `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Після змін у документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків усередині сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків усередині сторінок: `pnpm docs:check-links:anchors`. -## Офлайн-регресії (безпечні для CI) +## Offline-регресії (безпечні для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів через Gateway (mock OpenAI, реальний Gateway + цикл агента): `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") +- Tool calling 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") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock tool-calling через реальний Gateway + цикл агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, які перевіряють session wiring і вплив config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесії та вплив на config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): - **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і виконує обов’язкові кроки/аргументи? - **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval-набори мають насамперед залишатися детермінованими: +Майбутні оцінювання мають спочатку лишатися детермінованими: -- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і session wiring. -- Невеликий набір сценаріїв, орієнтованих на Skills (використовувати чи уникати, gate, prompt injection). -- Необов’язкові live-eval-набори (за бажанням, із gate через env) лише після того, як буде готовий безпечний для CI набір. +- Раннер сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання файлів Skill і wiring сесії. +- Невеликий набір сценаріїв, орієнтованих на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-оцінювання (opt-in, під контролем env) лише після того, як з’явиться безпечний для CI набір. ## Контрактні тести (форма Plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму -інтерфейсному контракту. Вони проходять усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно +контракту інтерфейсу. Вони перебирають усі виявлені Plugin і запускають набір +перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно пропускає ці файли спільних seam і smoke; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider. @@ -743,53 +742,53 @@ MCP, виконує інструмент, а потім перевіряє, що - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій channel +- **actions** - Обробники дій каналу - **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Примусове застосування group policy +- **directory** - API каталогу/реєстру +- **group-policy** - Застосування групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Проби статусу channel -- **registry** - Форма registry Plugin +- **status** - Перевірки статусу каналу +- **registry** - Форма реєстру Plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/добір автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/селекція auth - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin -- **runtime** - Runtime provider +- **runtime** - Runtime провайдера - **shape** - Форма/інтерфейс Plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export-ів або subpath у plugin-sdk -- Після додавання чи зміни channel або provider Plugin +- Після зміни export або subpath у plugin-sdk +- Після додавання або зміни channel чи provider Plugin - Після рефакторингу реєстрації або виявлення Plugin Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) -- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і добровільним через env-змінні -- Віддавайте перевагу націлюванню на найменший шар, який ловить баг: - - баг конвертації/відтворення запиту provider → тест direct models - - баг у pipeline gateway session/history/tool → live smoke gateway або безпечний для CI mock-тест gateway +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдер або фіксацію точного перетворення форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики auth), зберігайте live-тест вузьким і opt-in через env var +- Віддавайте перевагу націлюванню на найменший шар, який виявляє баг: + - баг перетворення/відтворення запиту провайдера → тест прямих моделей + - баг у pipeline сесії/історії/tool Gateway → live smoke Gateway або безпечний для CI mock-тест Gateway - Захисний механізм обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для не класифікованих target id, щоб нові класи не можна було непомітно пропустити. + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити. -## Пов’язані матеріали +## Пов’язане - [Live-тестування](/uk/help/testing-live) - [CI](/uk/ci) diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 74ff8dd2d..ea76ba59d 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -2,14 +2,14 @@ read_when: - Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців - Ви хочете налаштувати рівні журналювання, формати або редагування конфіденційних даних - - Ви усуваєте несправності й вам потрібно швидко знайти журнали -summary: Журнали файлів, вивід консолі, відстеження CLI та вкладка «Журнали» в Control UI + - Ви усуваєте несправності й хочете швидко знайти журнали +summary: Файлові журнали, виведення консолі, відстеження виведення CLI та вкладка «Журнали» в Control UI title: Журналювання x-i18n: - generated_at: "2026-04-26T22:05:00Z" + generated_at: "2026-04-27T22:51:29Z" model: gpt-5.4 provider: openai - source_hash: 6fb71b94a5c4fb8db9c704552f73f364b45c9d19bfb74c92abe1f22576fe1480 + source_hash: 5c6f0e325540e6daca228a2e9cc6c032ccc27a3c2a38be13a29e87a6a1227081 source_path: logging.md workflow: 15 --- @@ -17,19 +17,20 @@ x-i18n: OpenClaw має дві основні поверхні журналювання: - **Файлові журнали** (рядки JSON), які записує Gateway. -- **Вивід консолі**, що показується в терміналах і в Gateway Debug UI. +- **Виведення консолі**, яке показується в терміналах і в Gateway Debug UI. -Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де розташовані журнали, як їх читати та як налаштовувати рівні й формати журналювання. +Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці +пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. -## Де розташовані журнали +## Де зберігаються журнали -Типово Gateway записує ротаційний файл журналу в: +За замовчуванням Gateway записує циклічний файл журналу в: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` Дата використовує локальний часовий пояс хоста gateway. -Кожен файл ротується, коли досягає `logging.maxFileBytes` (типово: 100 MB). +Кожен файл ротуватиметься, коли досягне `logging.maxFileBytes` (за замовчуванням: 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом, наприклад `openclaw-YYYY-MM-DD.1.log`, і продовжує запис у новий активний журнал замість приглушення діагностичних даних. @@ -46,9 +47,9 @@ OpenClaw зберігає до п’яти нумерованих архівів ## Як читати журнали -### CLI: відстеження в реальному часі (рекомендовано) +### CLI: live tail (рекомендовано) -Використовуйте CLI для відстеження файла журналу gateway через RPC: +Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: ```bash openclaw logs --follow @@ -56,23 +57,23 @@ openclaw logs --follow Корисні поточні параметри: -- `--local-time`: відображати часові мітки у вашому локальному часовому поясі +- `--local-time`: відображати часові позначки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді для RPC, що працює через агента (приймається тут через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді для RPC з підтримкою агента (приймається тут через спільний клієнтський шар) -Режими виводу: +Режими виведення: - **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. - **Не-TTY-сеанси**: звичайний текст. -- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). +- `--json`: JSON з розділенням рядками (одна подія журналу на рядок). - `--plain`: примусово використовувати звичайний текст у TTY-сеансах. - `--no-color`: вимкнути кольори ANSI. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично конфігурацію чи -облікові дані середовища; якщо цільовий Gateway -вимагає автентифікацію, вкажіть `--token` самостійно. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації чи +середовища; додайте `--token` самостійно, якщо цільовий Gateway +вимагає автентифікації. -У режимі JSON CLI виводить об’єкти з міткою `type`: +У режимі JSON CLI виводить об’єкти з тегом `type`: - `meta`: метадані потоку (файл, курсор, розмір) - `log`: розібраний запис журналу @@ -96,7 +97,7 @@ openclaw doctor ### Журнали лише каналу -Щоб відфільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте: +Щоб фільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте: ```bash openclaw channels logs --channel whatsapp @@ -106,23 +107,24 @@ openclaw channels logs --channel whatsapp ### Файлові журнали (JSONL) -Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI розбирають ці -записи для відображення структурованого виводу (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі журналу — це об’єкт JSON. CLI та Control UI аналізують ці +записи, щоб відобразити структурований вивід (час, рівень, підсистема, повідомлення). -Записи JSONL файлового журналу також містять машинно-фільтровані поля верхнього рівня, коли вони доступні: +Записи JSONL у файловому журналі також містять машинно-фільтровані поля верхнього рівня, коли +вони доступні: - `hostname`: ім’я хоста gateway. -- `message`: зведений текст повідомлення журналу для повнотекстового пошуку. -- `agent_id`: id активного агента, коли виклик журналу містить контекст агента. -- `session_id`: id/ключ активної сесії, коли виклик журналу містить контекст сесії. +- `message`: сплощений текст повідомлення журналу для повнотекстового пошуку. +- `agent_id`: ідентифікатор активного агента, коли виклик журналу містить контекст агента. +- `session_id`: ідентифікатор/ключ активного сеансу, коли виклик журналу містить контекст сеансу. - `channel`: активний канал, коли виклик журналу містить контекст каналу. OpenClaw зберігає оригінальні структуровані аргументи журналу поряд із цими полями, -щоб наявні парсери, які читають нумеровані ключі аргументів tslog, продовжували працювати. +щоб наявні аналізатори, які читають нумеровані ключі аргументів tslog, і надалі працювали. -### Вивід консолі +### Виведення консолі -Журнали консолі **з урахуванням TTY** і відформатовані для зручності читання: +Журнали консолі **враховують TTY** і форматуються для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) - Кольорове виділення рівнів (info/warn/error) @@ -130,13 +132,13 @@ OpenClaw зберігає оригінальні структуровані ар Форматування консолі керується через `logging.consoleStyle`. -### Журнали WebSocket Gateway +### Журнали Gateway WebSocket `openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: -- звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики) +- звичайний режим: лише важливі результати (помилки, помилки розбору, повільні виклики) - `--verbose`: увесь трафік запитів/відповідей -- `--ws-log auto|compact|full`: вибір стилю докладного відображення +- `--ws-log auto|compact|full`: вибір стилю детального відображення - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -149,7 +151,7 @@ openclaw gateway --verbose --ws-log full ## Налаштування журналювання -Усі налаштування журналювання розміщені в `logging` у `~/.openclaw/openclaw.json`. +Уся конфігурація журналювання зберігається в розділі `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -169,80 +171,81 @@ openclaw gateway --verbose --ws-log full - `logging.level`: рівень **файлових журналів** (JSONL). - `logging.consoleLevel`: рівень деталізації **консолі**. -Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет за файл конфігурації, тому ви можете підвищити рівень деталізації для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. +Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тож ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. -`--verbose` впливає лише на вивід консолі та рівень деталізації журналів WS; він не змінює -рівні файлових журналів. +`--verbose` впливає лише на виведення консолі та деталізацію журналу WS; він не змінює +рівні файлового журналу. -### Кореляція трасування +### Кореляція трасувань Файлові журнали мають формат JSONL. Коли виклик журналу містить коректний контекст діагностичного трасування, OpenClaw записує поля трасування як JSON-ключі верхнього рівня (`traceId`, `spanId`, -`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли співвідносити рядок -із діапазонами OTEL та поширенням `traceparent` у провайдера. +`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли пов’язати цей рядок +із span OTEL і поширенням `traceparent` у провайдері. -HTTP-запити Gateway і кадри WebSocket Gateway створюють внутрішню область трасування запиту. -Журнали й діагностичні події, створені в межах цієї асинхронної області, успадковують -трасування запиту, якщо їм не передано явний контекст трасування. Трасування запуску агента й -виклику моделі стають дочірніми для активного трасування запиту, тому локальні журнали, -діагностичні знімки, діапазони OTEL і довірені заголовки `traceparent` провайдера можна -об’єднати за `traceId` без журналювання сирого вмісту запиту чи моделі. +HTTP-запити Gateway і кадри Gateway WebSocket створюють внутрішню область +трасування запиту. Журнали й діагностичні події, створені в межах цієї асинхронної області, +успадковують трасування запиту, якщо не передають явний контекст трасування. Трасування запуску агента й +виклику моделі стають дочірніми до активного трасування запиту, тож локальні журнали, +діагностичні знімки, span OTEL і заголовки `traceparent` від довірених провайдерів можна +поєднати за `traceId` без журналювання сирого вмісту запиту чи моделі. -### Розмір і тривалість виклику моделі +### Розмір і час виклику моделі -Діагностичні дані виклику моделі фіксують обмежені вимірювання запиту/відповіді без -захоплення сирого вмісту запиту або відповіді: +Діагностика виклику моделі записує обмежені вимірювання запиту/відповіді без +збереження сирого вмісту промпту чи відповіді: -- `requestPayloadBytes`: розмір у байтах UTF-8 фінального корисного навантаження запиту до моделі +- `requestPayloadBytes`: розмір у байтах UTF-8 фінального payload запиту моделі - `responseStreamBytes`: розмір у байтах UTF-8 подій потокової відповіді моделі -- `timeToFirstByteMs`: минулий час до першої події потокової відповіді +- `timeToFirstByteMs`: затримка до першої події потокової відповіді - `durationMs`: загальна тривалість виклику моделі -Ці поля доступні для діагностичних знімків, хуків Plugin виклику моделі та -діапазонів/метрик виклику моделі OTEL, коли ввімкнено експорт діагностики. +Ці поля доступні для діагностичних знімків, хуків Plugin для викликів моделі та +span/метрик викликів моделі в OTEL, коли ввімкнено експорт діагностики. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручний для читання людиною, кольоровий, із часовими мітками. +- `pretty`: зручний для читання, кольоровий, із часовими позначками. - `compact`: щільніший вивід (найкраще для довгих сеансів). -- `json`: JSON на рядок (для обробників журналів). +- `json`: JSON у кожному рядку (для обробників журналів). ### Редагування конфіденційних даних -OpenClaw може маскувати конфіденційні токени до того, як вони потраплять у вивід консолі, файлові журнали, -записи журналів OTLP або збережений текст стенограми сесії: +OpenClaw може редагувати конфіденційні токени до того, як вони потраплять у виведення консолі, файлові журнали, записи журналів OTLP, збережений текст стенограми сеансу або payload подій інструментів у Control UI +(аргументи запуску інструментів, payload часткових/фінальних результатів, похідне +виведення exec і підсумки патчів): -- `logging.redactSensitive`: `off` | `tools` (типово: `tools`) -- `logging.redactPatterns`: список рядків regex для перевизначення типового набору +- `logging.redactSensitive`: `off` | `tools` (за замовчуванням: `tools`) +- `logging.redactPatterns`: список рядків regex для перевизначення стандартного набору. Власні шаблони застосовуються поверх вбудованих значень за замовчуванням для payload інструментів у Control UI, тож додавання шаблону ніколи не послаблює редагування значень, які вже перехоплюються стандартними шаблонами. -Файлові журнали й стенограми сесій залишаються у форматі JSONL, але значення секретів, які збігаються, -маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується за принципом best-effort: +Файлові журнали та стенограми сеансів залишаються у форматі JSONL, але значення секретів, що збігаються, +маскуються до того, як рядок або повідомлення буде записано на диск. Редагування — це best-effort: воно застосовується до текстового вмісту повідомлень і рядків журналу, але не до кожного -ідентифікатора чи поля двійкового корисного навантаження. +ідентифікатора чи поля бінарного payload. ## Діагностика та OpenTelemetry -Діагностичні дані — це структуровані, машинозчитувані події для запусків моделей і -телеметрії потоку повідомлень (Webhooks, постановка в чергу, стан сесії). Вони **не** -замінюють журнали — вони живлять метрики, трасування та експортери. Події створюються +Діагностика — це структуровані, машиночитані події для запусків моделей і +телеметрії потоку повідомлень (webhook, постановка в чергу, стан сеансу). Вони **не** +замінюють журнали — вони живлять метрики, трасування й експортери. Події створюються в процесі незалежно від того, експортуєте ви їх чи ні. Дві суміжні поверхні: -- **Експорт OpenTelemetry** — надсилає метрики, трасування та журнали через OTLP/HTTP до +- **Експорт OpenTelemetry** — надсилання метрик, трасувань і журналів через OTLP/HTTP до будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, - назви метрик/діапазонів, змінні середовища й модель конфіденційності описані на окремій сторінці: + назви метрик/span, змінні середовища та модель конфіденційності описані на окремій сторінці: [Експорт OpenTelemetry](/uk/gateway/opentelemetry). -- **Прапорці діагностики** — цільові прапорці налагоджувальних журналів, які спрямовують додаткові журнали до +- **Прапорці діагностики** — цільові прапорці налагоджувальних журналів, які спрямовують додаткові журнали в `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру - і підтримують шаблони з підстановками (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` - або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: + і підтримують шаблони (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags` + або через перевизначення змінної середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник: [Прапорці діагностики](/uk/diagnostics/flags). -Щоб увімкнути діагностичні події для Plugins або власних приймачів без експорту OTLP: +Щоб увімкнути діагностичні події для Plugin або власних приймачів без експорту OTLP: ```json5 { @@ -255,13 +258,13 @@ OpenClaw може маскувати конфіденційні токени д ## Поради з усунення несправностей - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Журнали порожні?** Переконайтеся, що Gateway запущено і він записує у шлях до файла, - вказаний у `logging.file`. +- **Журнали порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу, + указаний у `logging.file`. - **Потрібно більше деталей?** Встановіть `logging.level` у `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/діапазонів, модель конфіденційності +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель конфіденційності - [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці налагоджувальних журналів -- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі -- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` +- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і перехоплення консолі +- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 834b239e0..e94dd5d9c 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,219 +1,219 @@ --- read_when: - - Вибір правильного підшляху plugin-sdk для імпорту plugin + - Вибір правильного підшляху plugin-sdk для імпорту в plugin - Аудит підшляхів bundled-plugin і допоміжних поверхонь summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-27T22:22:42Z" + generated_at: "2026-04-27T22:51:30Z" model: gpt-5.4 provider: openai - source_hash: 56f76f2371500ab77dc791ba862cb628daec596059f1f9def7227fecb2826347 + source_hash: cbe2016ada89a5738f9786cd3c31091ea7cddc3131f13e949b63cee228b44913 source_path: plugins/sdk-subpaths.md workflow: 15 --- - Plugin SDK представлений як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці наведено каталог поширено вживаних підшляхів, згрупованих за призначенням. Згенерований + Plugin SDK доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + Ця сторінка каталогізує найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталями - реалізації, якщо лише сторінка документації явно не просуває їх. + зарезервовані допоміжні підшляхи bundled-plugin також там наведені, але є + деталлю реалізації, якщо лише сторінка документації явно не просуває їх. Посібник з розробки plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). ## Точка входу plugin - | Subpath | Основні експорти | - | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `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/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` | - - | Subpath | Основні експорти | + + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `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-core` | Допоміжні засоби багатoоблікового запису для конфігурації/обмеження дій, допоміжні засоби резервного облікового запису за замовчуванням | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного переходу до типового | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків облікових записів/дій з обліковими записами | + | `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/channel-config-schema-legacy` | Застарілі схеми конфігу bundled-channel лише для сумісності з вбудованими компонентами | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю з bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та універсальний побудовник | + | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності з bundled | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації власних команд Telegram із резервною сумісністю bundled-contract | + | `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/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/outbound-send-deps` | Полегшений пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби доставки вихідних повідомлень, ідентичності, делегата надсилання, сесії, форматування та планування навантаження | | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | - | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків та допоміжні засоби адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмов/потоків, pairинг і налаштованих прив’язок | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіанавантаження агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмови/потоку, парування та налаштованих прив’язок | | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації під час виконання | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групових політик під час виконання | + | `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 каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | + | `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/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту direct-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-inbound` | Барель сумісності для вхідного debounce, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів конверта | + | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби вхідного debounce | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні вхідного runtime | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідного конверта | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту місцезнаходження каналу та форматування | + | `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для скидання вхідних повідомлень і збоїв typing/ack | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі рідні допоміжні засоби схем, збережені для сумісності plugin | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі нативні допоміжні засоби схем, збережені для сумісності plugin | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контрактів каналу | - | `plugin-sdk/channel-feedback` | Підключення зворотного зв’язку/реакцій | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контрактів секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | + | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | - - | Subpath | Основні експорти | + + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний runtime-фасад LM Studio для типових локальних серверів, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей | - | `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-ключа під час виконання для plugin провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключів/запису профілів, такі як `upsertApiKeyProfile` | + | `plugin-sdk/lmstudio` | Підтримуваний фасад постачальника LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для локальних типових параметрів сервера, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted постачальників | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted постачальника, сумісного з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення 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` | Допоміжні засоби пошуку env vars для автентифікації провайдерів | + | `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`, спільні побудовники політик повтору, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Хуки runtime каталогу провайдерів і шви реєстру plugin-провайдерів для тестів контрактів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик повтору, допоміжні засоби endpoint постачальника та допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Гуки runtime каталогу постачальника та межі реєстру plugin-постачальників для контрактних тестів | | `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 | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter для облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для провайдерів web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint постачальника, помилки HTTP постачальника та допоміжні засоби multipart-форм для транскрипції аудіо | + | `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 setters/getters облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime постачальника 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-transport-runtime` | Нативні допоміжні засоби транспорту постачальника, як-от guarded fetch, перетворення повідомлень транспорту та потоки подій writable transport | | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд | - | Subpath | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | - | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та автентифікації дій у тому ж чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Native-адаптери можливостей/доставки approval | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення gateway для approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native-адаптерів approval для гарячих точок входу каналів | - | `plugin-sdk/approval-handler-runtime` | Ширші runtime-допоміжні засоби для approval; віддавайте перевагу вужчим адаптерним/Gateway-швам, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + прив’язки облікових записів | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповідей для exec/plugin approval | - | `plugin-sdk/approval-runtime` | Допоміжні засоби payload для exec/plugin approval, native-допоміжні засоби маршрутизації/runtime approval і допоміжні засоби структурованого відображення approval, такі як `formatApprovalDisplayPath` | + | `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` | Ширші допоміжні засоби runtime обробника погодження; надавайте перевагу вужчим adapter/gateway межам, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Нативні допоміжні засоби цілей погодження + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби корисного навантаження відповіді для погодження exec/plugin | + | `plugin-sdk/approval-runtime` | Допоміжні засоби корисного навантаження погодження exec/plugin, допоміжні засоби нативної маршрутизації/runtime погодження та допоміжні засоби структурованого відображення погодження, як-от `formatApprovalDisplayPath` | | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Native-автентифікація команд, форматування меню динамічних аргументів і native-допоміжні засоби цілей сесій | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого бареля тестування | + | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і нативні допоміжні засоби session-target | | `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` | Вузькі допоміжні засоби збирання секретних контрактів для поверхонь секретів channel/plugin | - | `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 і допоміжні засоби політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного введення | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-аутів | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналів/plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталим часом і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватної мережі | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом від SSRF, помилки SSRF і політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору введення секретів | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook і приведення сирого websocket/body | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-ауту | - | Subpath | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі runtime/логування/резервного копіювання/встановлення plugin допоміжні засоби | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору CDP URL і допоміжних засобів автентифікації browser-control | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/журналювання/резервного копіювання/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime, логера, тайм-аутів, повторних спроб і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору URL CDP і допоміжних засобів автентифікації керування браузером | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline Webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивності plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра Webhook/внутрішніх хуків | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого імпорту/прив’язки runtime, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і lazy command-group | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway client, Gateway CLI RPC, помилок протоколу Gateway і патчів статусу каналу | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, таких як `OpenClawConfig` і типи конфігурації каналів/провайдерів | - | `plugin-sdk/plugin-config-runtime` | Runtime-допоміжні засоби пошуку plugin-config, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, такі як `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setter-и тестових знімків | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версії, виклику аргументів і лінивих груп команд | + | `plugin-sdk/gateway-runtime` | Клієнт Gateway, CLI RPC Gateway, помилки протоколу Gateway та допоміжні засоби патчів стану каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, як-от `OpenClawConfig` і типів конфігурації каналів/постачальників | + | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації plugin під час виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot` і сетери тестових знімків | | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого text-runtime barrel | - | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники можливостей approval, допоміжні засоби auth/profile, native-допоміжні засоби routing/runtime і форматування шляху структурованого відображення approval | - | `plugin-sdk/reply-runtime` | Спільні runtime-допоміжні засоби inbound/reply, розбиття на частини, диспетчеризація, Heartbeat, планувальник відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації/фіналізації відповідей і міток розмов | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window history відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого бареля text-runtime | + | `plugin-sdk/approval-runtime` | Допоміжні засоби погодження exec/plugin, побудовники можливостей погодження, допоміжні засоби автентифікації/профілю, нативної маршрутизації/runtime і форматування шляху структурованого відображення погодження | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для вхідних повідомлень/відповідей, чанкінгу, диспетчеризації, Heartbeat, планувальника відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації/фіналізації відповідей і позначок розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби історії відповідей для короткого вікна та маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і мутацій сховища | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби чанкінгу тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, session-key, updated-at і мутації сховища | | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів директорій state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключа сесії/прив’язки облікових записів, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, типові значення runtime-state і допоміжні засоби метаданих проблем | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів стану/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, типових значень стану runtime та метаданих проблем | | `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/request-url` | Витягування рядкових URL з вхідних даних типу fetch/request | + | `plugin-sdk/run-command` | Виконавець команд із тайм-аутом і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування нормалізованих корисних навантажень з об’єктів результатів tool | | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистем і редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown і перетворення | - | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення model/session, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk provider | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | - | `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дедуплікаційного кешу зберігання на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і диспетчеризації відповідей | - | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язки ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації agent runtime | - | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів до тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби логера підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму та перетворення таблиць Markdown | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації постачальника Talk | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного блокування файлів | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковою підтримкою | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесії ACP і диспетчеризації відповідей | + | `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` | Допоміжні засоби початкового налаштування пристрою та pairing token | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models`/провайдера | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів парування | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів пасивних каналів, стану й ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models`/постачальника | | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native-команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness agent: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту OpenClaw tool, допоміжні засоби політики runtime-plan tool, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | - | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих runtime state-файлів | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби керування/переривання активного запуску, допоміжні засоби мосту tools OpenClaw, допоміжні засоби політики tools плану runtime, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tools і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | + | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime | | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності async-завдань | | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті | @@ -224,85 +224,85 @@ x-i18n: | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | - | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте сфокусовані runtime-підшляхи вище | + | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте сфокусовані підшляхи runtime вище | | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace-context | | `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` | Допоміжний засіб читання обмеженого response-body без широкої media runtime-поверхні | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без routing налаштованих прив’язок або pairing stores | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації | - | `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` | Допоміжні засоби директорії/ідентичності/робочого простору agent | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація директорій на основі конфігурації | + | `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Обмежений читач тіла відповіді без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованої прив’язки або сховищ парування | + | `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 | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації повторних спроб і виконавця повторів | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Subpath | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби отримання/перетворення/збереження медіа, а також побудовники media payload | - | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, такі як `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також експорти image/audio helper для провайдерів | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення assistant-visible-text, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти safe-text | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники медіанавантаження | + | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, як-от `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи постачальника розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтовані на постачальника | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту/markdown/журналювання, як-от видалення тексту, видимого помічнику, допоміжні засоби рендерингу/chunking/table Markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи speech provider, а також експорти directive, registry, validation і speech helper для провайдерів | - | `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive, normalization і експорти speech helper | - | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби registry і спільний допоміжний засіб WebSocket session | - | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби registry | - | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і registry | - | `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/speech` | Типи постачальника мовлення, а також експорти допоміжних засобів директив, реєстру, валідації та мовлення, орієнтовані на постачальника | + | `plugin-sdk/speech-core` | Спільні типи постачальника мовлення, експорти допоміжних засобів реєстру, директив, нормалізації та мовлення | + | `plugin-sdk/realtime-transcription` | Типи постачальника транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | + | `plugin-sdk/realtime-voice` | Типи постачальника голосу в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/image-generation` | Типи постачальника генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, автентифікації та реєстру | + | `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/webhook-path` | Допоміжні засоби нормалізації шляхів Webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | Публічні допоміжні засоби тестування extensions, включно з mock-об’єктами registry/runtime plugin, fetch/env/temp fixtures, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби Extension `*.test-support.ts` мають залишатися тут або у сфокусованих підшляхах SDK, а не у внутрішніх компонентах core | + | `plugin-sdk/zod` | Повторно експортований `zod` для користувачів Plugin SDK | + | `plugin-sdk/testing` | Публічні допоміжні засоби тестування розширень, включно з моками реєстру/runtime plugin, захопленням реєстрації постачальника, допоміжними засобами майстра налаштування, фікстурами fetch/env/temp/time, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби розширень `*.test-support.ts` мають лишатися тут або у сфокусованих підшляхах SDK, а не у внутрішніх модулях core | - | Subpath | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI helper | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine host-а пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding host-а пам’яті, доступ до registry, локальний провайдер і загальні пакетні/віддалені helper | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine host-а пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти engine сховища host-а пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні helper host-а пам’яті | - | `plugin-sdk/memory-core-host-query` | Helper запитів host-а пам’яті | - | `plugin-sdk/memory-core-host-secret` | Helper секретів host-а пам’яті | - | `plugin-sdk/memory-core-host-events` | Helper журналу подій host-а пам’яті | - | `plugin-sdk/memory-core-host-status` | Helper статусу host-а пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime helper CLI host-а пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Core runtime helper host-а пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | File/runtime helper host-а пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для core runtime helper host-а пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для helper журналу подій host-а пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для file/runtime helper host-а пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні helper керованого markdown для plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до менеджера пошуку | - | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для helper статусу host-а пам’яті | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/допоміжних засобів CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад 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-qmd` | Експорти QMD engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | + | `plugin-sdk/memory-core-host-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` | Допоміжні засоби 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, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку | + | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів стану хоста пам’яті | | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - | Family | Поточні підшляхи | Призначення | + | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | 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` | Поверхня helper/runtime bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper bundled IRC | - | Специфічні для каналів helper | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/helper для bundled channel. Нові plugins повинні імпортувати загальні підшляхи SDK або plugin-local barrel. | - | Helper автентифікації/специфічні для 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/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви helper для bundled feature/plugin; `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` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` лишається барелем сумісності. | + | 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/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі межі сумісності/допоміжних засобів bundled channel. Нові plugins мають імпортувати загальні підшляхи SDK або локальні барелі plugin. | + | Допоміжні засоби для автентифікації/конкретних 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/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Межі допоміжних засобів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | diff --git a/docs/uk/plugins/sdk-testing.md b/docs/uk/plugins/sdk-testing.md index d41634b84..36062b357 100644 --- a/docs/uk/plugins/sdk-testing.md +++ b/docs/uk/plugins/sdk-testing.md @@ -2,32 +2,32 @@ read_when: - Ви пишете тести для Plugin - Вам потрібні утиліти тестування з SDK Plugin - - Ви хочете зрозуміти контрактні тести для вбудованих Plugin + - Ви хочете зрозуміти контрактні тести для вбудованих плагінів sidebarTitle: Testing -summary: Утиліти та шаблони тестування для Plugin OpenClaw +summary: Утиліти та шаблони тестування для плагінів OpenClaw title: Тестування Plugin x-i18n: - generated_at: "2026-04-27T22:22:43Z" + generated_at: "2026-04-27T22:51:29Z" model: gpt-5.4 provider: openai - source_hash: 358a1e76d6a8e78ad503b040d49bab7f66fa8bfb2f1fe7dcb6088ef932e56860 + source_hash: ad2e95d9db988610931391c37f1fef12014dff717ceb1647bca241a1a438aeae source_path: plugins/sdk-testing.md workflow: 15 --- -Довідник з утиліт тестування, шаблонів і забезпечення правил lint для Plugin OpenClaw. +Довідник з утиліт тестування, шаблонів і примусового застосування lint для плагінів OpenClaw. **Шукаєте приклади тестів?** Практичні посібники містять готові приклади тестів: - [Тести Channel Plugin](/uk/plugins/sdk-channel-plugins#step-6-test) і - [Тести Provider Plugin](/uk/plugins/sdk-provider-plugins#step-6-test). + [Тести плагінів каналів](/uk/plugins/sdk-channel-plugins#step-6-test) і + [Тести плагінів провайдерів](/uk/plugins/sdk-provider-plugins#step-6-test). ## Утиліти тестування **Імпорт:** `openclaw/plugin-sdk/testing` -Підшлях testing експортує вузький набір допоміжних засобів для авторів Plugin: +Підшлях testing експортує вузький набір допоміжних засобів для авторів плагінів: ```typescript import { @@ -39,26 +39,33 @@ import { ### Доступні експорти -| Export | Purpose | -| -------------------------------------- | ------------------------------------------------- | -| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок під час визначення цілі | -| `shouldAckReaction` | Перевіряє, чи повинен канал додавати реакцію-підтвердження | -| `removeAckReactionAfterReply` | Видаляє реакцію-підтвердження після доставки відповіді | -| `createTestRegistry` | Створює фікстуру реєстру Channel Plugin | -| `createEmptyPluginRegistry` | Створює порожню фікстуру реєстру Plugin | -| `setActivePluginRegistry` | Встановлює фікстуру реєстру для runtime-тестів Plugin | -| `createRequestCaptureJsonFetch` | Перехоплює JSON fetch-запити в тестах медіадопоміжників | -| `withFetchPreconnect` | Запускає fetch-тести зі встановленими хуками preconnect | -| `withEnv` / `withEnvAsync` | Тимчасово підміняє змінні середовища | -| `createTempHomeEnv` / `withTempDir` | Створює ізольовані файлові фікстури для тестів | -| `createMockServerResponse` | Створює мінімальний mock-відповідь HTTP-сервера | -| `registerSingleProviderPlugin` | Реєструє один Provider Plugin у smoke-тестах завантажувача | -| `createRuntimeTaskFlow` | Створює ізольований стан runtime TaskFlow | -| `typedCases` | Зберігає literal-типи для табличних тестів | +| Експорт | Призначення | +| -------------------------------------- | ------------------------------------------------------ | +| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок визначення цілі | +| `shouldAckReaction` | Перевіряє, чи повинен канал додавати реакцію підтвердження | +| `removeAckReactionAfterReply` | Видаляє реакцію підтвердження після доставки відповіді | +| `createTestRegistry` | Створює фікстуру реєстру плагінів каналів | +| `createEmptyPluginRegistry` | Створює порожню фікстуру реєстру плагінів | +| `setActivePluginRegistry` | Встановлює фікстуру реєстру для тестів часу виконання плагіна | +| `createRequestCaptureJsonFetch` | Перехоплює запити JSON fetch у тестах допоміжних засобів для медіа | +| `withFetchPreconnect` | Запускає тести fetch із встановленими хуками preconnect | +| `withEnv` / `withEnvAsync` | Тимчасово змінює змінні середовища | +| `createTempHomeEnv` / `withTempDir` | Створює ізольовані файлові фікстури для тестів | +| `createMockServerResponse` | Створює мінімальний мок відповіді HTTP-сервера | +| `registerSingleProviderPlugin` | Реєструє один плагін провайдера в smoke-тестах завантажувача | +| `registerProviderPlugin` | Перехоплює всі типи провайдерів з одного плагіна | +| `requireRegisteredProvider` | Перевіряє, що колекція провайдерів містить id | +| `createProviderUsageFetch` | Створює фікстури fetch для використання провайдера | +| `useFrozenTime` / `useRealTime` | Заморожує та відновлює таймери для чутливих до часу тестів | +| `createRuntimeEnv` | Створює замокане середовище виконання CLI/плагіна | +| `createTestWizardPrompter` | Створює замоканий prompter майстра налаштування | +| `createPluginSetupWizardStatus` | Створює допоміжні засоби стану налаштування для плагінів каналів | +| `createRuntimeTaskFlow` | Створює ізольований стан TaskFlow часу виконання | +| `typedCases` | Зберігає literal-типи для таблично-керованих тестів | ### Типи -Підшлях testing також повторно експортує типи, корисні у тестових файлах: +Підшлях testing також повторно експортує типи, корисні у файлах тестів: ```typescript import type { @@ -79,16 +86,16 @@ import type { import { describe } from "vitest"; import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing"; -describe("my-channel target resolution", () => { +describe("визначення цілі my-channel", () => { installCommonResolveTargetErrorCases({ resolveTarget: ({ to, mode, allowFrom }) => { - // Your channel's target resolution logic + // Логіка визначення цілі вашого каналу return myChannelResolveTarget({ to, mode, allowFrom }); }, implicitAllowFrom: ["user1", "user2"], }); - // Add channel-specific test cases + // Додайте специфічні для каналу тестові випадки it("should resolve @username targets", () => { // ... }); @@ -99,20 +106,22 @@ describe("my-channel target resolution", () => { ### Тестування контрактів реєстрації -Юніт-тести, які передають вручну написаний mock `api` до `register(api)`, не перевіряють acceptance gate завантажувача OpenClaw. Додайте щонайменше один smoke-тест на основі завантажувача для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для hook і ексклюзивних можливостей, таких як memory. +Модульні тести, які передають вручну написаний мок `api` у `register(api)`, не перевіряють ворота прийняття завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі завантажувача для кожної поверхні реєстрації, від якої залежить ваш плагін, особливо для хуків і ексклюзивних можливостей, таких як пам’ять. -Справжній завантажувач відхиляє реєстрацію Plugin, якщо бракує обов’язкових метаданих або якщо Plugin викликає API можливості, якою він не володіє. Наприклад, `api.registerHook(...)` вимагає назву hook, а `api.registerMemoryCapability(...)` вимагає, щоб маніфест Plugin або експортована точка входу оголошували `kind: "memory"`. +Справжній завантажувач завершує реєстрацію плагіна помилкою, якщо відсутні обов’язкові метадані або якщо плагін викликає API можливості, якою він не володіє. Наприклад, +`api.registerHook(...)` вимагає назву хука, а +`api.registerMemoryCapability(...)` вимагає, щоб маніфест плагіна або експортована точка входу оголошували `kind: "memory"`. -### Тестування доступу до runtime-конфігурації +### Тестування доступу до конфігурації часу виконання -Під час тестування вбудованих Plugin віддавайте перевагу спільному mock runtime Plugin із допоміжних засобів тестування репозиторію. Його застарілі mock `runtime.config.loadConfig()` і `runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове використання API сумісності. Перевизначайте ці mock лише тоді, коли тест явно перевіряє застарілу поведінку сумісності. +Під час тестування вбудованих плагінів віддавайте перевагу спільному моку часу виконання плагіна з допоміжних засобів тестування репозиторію. Його моки `runtime.config.loadConfig()` і `runtime.config.writeConfigFile(...)`, які є застарілими, за замовчуванням викидають помилку, щоб тести виявляли нове використання API сумісності. Перевизначайте ці моки лише тоді, коли тест явно покриває застарілу поведінку сумісності. -### Юніт-тестування Channel Plugin +### Модульне тестування плагіна каналу ```typescript import { describe, it, expect, vi } from "vitest"; -describe("my-channel plugin", () => { +describe("плагін my-channel", () => { it("should resolve account from config", () => { const cfg = { channels: { @@ -137,18 +146,18 @@ describe("my-channel plugin", () => { const inspection = myPlugin.setup.inspectAccount(cfg, undefined); expect(inspection.configured).toBe(true); expect(inspection.tokenStatus).toBe("available"); - // No token value exposed + // Значення токена не розкривається expect(inspection).not.toHaveProperty("token"); }); }); ``` -### Юніт-тестування Provider Plugin +### Модульне тестування плагіна провайдера ```typescript import { describe, it, expect } from "vitest"; -describe("my-provider plugin", () => { +describe("плагін my-provider", () => { it("should resolve dynamic models", () => { const model = myProvider.resolveDynamicModel({ modelId: "custom-model-v2", @@ -171,9 +180,9 @@ describe("my-provider plugin", () => { }); ``` -### Мокування runtime Plugin +### Мокання часу виконання плагіна -Для коду, який використовує `createPluginRuntimeStore`, мокайте runtime у тестах: +Для коду, який використовує `createPluginRuntimeStore`, мокуйте runtime у тестах: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -204,9 +213,9 @@ store.setRuntime(mockRuntime); store.clearRuntime(); ``` -### Тестування зі стабами на рівні екземпляра +### Тестування з використанням стабів для окремих екземплярів -Віддавайте перевагу стабам на рівні екземпляра замість мутації прототипу: +Віддавайте перевагу стабам для окремих екземплярів, а не зміні prototype: ```typescript // Preferred: per-instance stub @@ -217,9 +226,9 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // MyChannelClient.prototype.sendMessage = vi.fn(); ``` -## Контрактні тести (Plugin у репозиторії) +## Контрактні тести (плагіни в репозиторії) -Вбудовані Plugin мають контрактні тести, які перевіряють володіння реєстрацією: +Вбудовані плагіни мають контрактні тести, які перевіряють належність реєстрації: ```bash pnpm test -- src/plugins/contracts/ @@ -227,14 +236,14 @@ pnpm test -- src/plugins/contracts/ Ці тести перевіряють: -- Які Plugin реєструють які провайдери -- Які Plugin реєструють які мовленнєві провайдери +- Які плагіни реєструють які провайдери +- Які плагіни реєструють які провайдери мовлення - Коректність форми реєстрації -- Відповідність runtime-контракту +- Відповідність контракту часу виконання ### Запуск тестів з обмеженою областю -Для конкретного Plugin: +Для конкретного плагіна: ```bash pnpm test -- /my-channel/ @@ -248,19 +257,19 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## Забезпечення правил lint (Plugin у репозиторії) +## Примусове застосування lint (плагіни в репозиторії) -`pnpm check` застосовує три правила для Plugin у репозиторії: +Три правила примусово застосовуються через `pnpm check` для плагінів у репозиторії: -1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` відхиляється -2. **Без прямих імпортів `src/`** -- Plugin не можуть напряму імпортувати `../../src/` -3. **Без самоімпортів** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/` +1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` заборонений +2. **Без прямих імпортів `src/`** -- плагіни не можуть напряму імпортувати `../../src/` +3. **Без самоімпортів** -- плагіни не можуть імпортувати власний підшлях `plugin-sdk/` -На зовнішні Plugin ці правила lint не поширюються, але дотримуватися тих самих шаблонів рекомендовано. +Зовнішні плагіни не підпадають під ці lint-правила, але рекомендується дотримуватися тих самих шаблонів. -## Конфігурація тестування +## Конфігурація тестів -OpenClaw використовує Vitest із порогами покриття V8. Для тестів Plugin: +OpenClaw використовує Vitest із порогами покриття V8. Для тестів плагінів: ```bash # Run all tests @@ -276,7 +285,7 @@ pnpm test -- /my-channel/ -t "resolves account" pnpm test:coverage ``` -Якщо локальні запуски створюють тиск на пам’ять: +Якщо локальні запуски спричиняють тиск на пам’ять: ```bash OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test @@ -285,6 +294,6 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- правила імпорту -- [SDK Channel Plugins](/uk/plugins/sdk-channel-plugins) -- інтерфейс Channel Plugin -- [SDK Provider Plugins](/uk/plugins/sdk-provider-plugins) -- hook Provider Plugin -- [Створення Plugin](/uk/plugins/building-plugins) -- посібник для початку роботи +- [Плагіни каналів SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс плагіна каналу +- [Плагіни провайдерів SDK](/uk/plugins/sdk-provider-plugins) -- хуки плагінів провайдерів +- [Створення плагінів](/uk/plugins/building-plugins) -- посібник із початку роботи diff --git a/docs/uk/reference/RELEASING.md b/docs/uk/reference/RELEASING.md index bf07054e6..2b14abf83 100644 --- a/docs/uk/reference/RELEASING.md +++ b/docs/uk/reference/RELEASING.md @@ -1,236 +1,233 @@ --- read_when: - Шукаю визначення публічних каналів релізу - - Запуск валідації релізу або приймання пакета - - Шукаю іменування версій і каденс -summary: Лейни релізу, контрольний список оператора, блоки валідації, іменування версій і каденс -title: Політика релізу + - Виконання валідації релізу або перевірки прийнятності пакета + - Шукаю іменування версій і частоту випусків +summary: Релізні напрямки, контрольний список оператора, блоки валідації, іменування версій і частота випусків +title: Політика релізів x-i18n: - generated_at: "2026-04-27T21:05:08Z" + generated_at: "2026-04-27T22:51:29Z" model: gpt-5.4 provider: openai - source_hash: f3ff3c7887c59005a977522e3a0e80ea3458e29d12f6976397b0749d8001d914 + source_hash: d007af3cf645d1dd84013e686b7a0513fa97f58a5ad1c5758b70a7c93e2458f4 source_path: reference/RELEASING.md workflow: 15 --- -OpenClaw має три публічні лейни релізу: +OpenClaw має три публічні напрями релізу: -- stable: теговані релізи, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, якщо це явно запитано -- beta: теги передрелізів, які публікуються в npm `beta` -- dev: рухома голова `main` +- stable: релізи з тегами, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, якщо це явно запитано +- beta: теги попередніх релізів, які публікуються в npm `beta` +- dev: рухома вершина `main` ## Іменування версій - Версія stable-релізу: `YYYY.M.D` - Git-тег: `vYYYY.M.D` -- Версія коригувального stable-релізу: `YYYY.M.D-N` +- Версія stable-коригувального релізу: `YYYY.M.D-N` - Git-тег: `vYYYY.M.D-N` -- Версія beta-передрелізу: `YYYY.M.D-beta.N` +- Версія beta-попереднього релізу: `YYYY.M.D-beta.N` - Git-тег: `vYYYY.M.D-beta.N` -- Не додавайте провідні нулі до місяця або дня +- Не додавайте ведучі нулі до місяця або дня - `latest` означає поточний просунутий stable-реліз npm - `beta` означає поточну ціль встановлення beta -- Stable-релізи та коригувальні stable-релізи за замовчуванням публікуються в npm `beta`; оператори релізу можуть явно вибрати `latest` або просунути перевірену beta-збірку пізніше +- Stable і stable-коригувальні релізи за замовчуванням публікуються в npm `beta`; оператори релізу можуть явно націлити `latest` або пізніше просунути перевірену beta-збірку - Кожен stable-реліз OpenClaw постачається разом із npm-пакетом і застосунком macOS; beta-релізи зазвичай спочатку проходять валідацію та публікацію шляху npm/package, а - збірка/підпис/нотаризація застосунку macOS зарезервовані для stable, якщо явно не запитано + збірка/підпис/нотаризація застосунку macOS зарезервовані для stable, якщо інше не запитано явно -## Каденс релізів +## Частота випусків релізів -- Релізи рухаються за схемою beta-first -- Stable іде лише після валідації останньої beta -- Мейнтейнери зазвичай роблять релізи з гілки `release/YYYY.M.D`, створеної +- Релізи спочатку проходять через beta +- Stable виходить лише після валідації останньої beta +- Мейнтейнери зазвичай створюють релізи з гілки `release/YYYY.M.D`, створеної з поточної `main`, щоб валідація релізу та виправлення не блокували нову розробку в `main` - Якщо beta-тег уже було запушено або опубліковано й він потребує виправлення, мейнтейнери створюють - наступний тег `-beta.N` замість видалення або повторного створення старого beta-тегу + наступний тег `-beta.N` замість видалення або повторного створення старого beta-тега - Детальна процедура релізу, погодження, облікові дані та примітки щодо відновлення доступні лише мейнтейнерам ## Контрольний список оператора релізу -Цей контрольний список — публічний контур процесу релізу. Приватні облікові дані, -підписування, нотаризація, відновлення dist-tag і деталі аварійного відкату -залишаються в runbook релізу лише для мейнтейнерів. +Цей контрольний список описує публічну форму процесу релізу. Приватні облікові дані, +підписування, нотаризація, відновлення dist-tag і деталі аварійного відкату залишаються +в доступному лише мейнтейнерам runbook релізів. -1. Почніть з поточної `main`: отримайте останні зміни, підтвердьте, що цільовий коміт запушено, - і що поточний CI для `main` достатньо зелений, щоб відгалужуватися від нього. +1. Почніть із поточної `main`: підтягніть останні зміни, підтвердьте, що цільовий коміт запушено, + і що поточний CI для `main` достатньо зелений, щоб від нього відгалужуватися. 2. Перепишіть верхню секцію `CHANGELOG.md` на основі реальної історії комітів за допомогою - `/changelog`, залишайте записи орієнтованими на користувача, закомітьте це, запуште і - ще раз виконайте rebase/pull перед створенням гілки. + `/changelog`, залиште записи орієнтованими на користувача, закомітьте це, запуште й ще раз виконайте rebase/pull перед створенням гілки. 3. Перегляньте записи сумісності релізу в `src/plugins/compat/registry.ts` і - `src/commands/doctor/shared/deprecation-compat.ts`. Видаляйте прострочену + `src/commands/doctor/shared/deprecation-compat.ts`. Видаляйте застарілу сумісність лише тоді, коли шлях оновлення залишається покритим, або зафіксуйте, чому її навмисно збережено. -4. Створіть `release/YYYY.M.D` з поточної `main`; не виконуйте звичайну роботу з релізом +4. Створіть `release/YYYY.M.D` із поточної `main`; не виконуйте звичайну роботу над релізом безпосередньо в `main`. -5. Оновіть кожне обов’язкове місце з версією для запланованого тегу, а потім виконайте +5. Оновіть усі потрібні місця з версіями для запланованого тега, а потім виконайте локальний детермінований preflight: `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build`, і `pnpm release:check`. -6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. До появи тегу - для preflight лише з метою валідації дозволено повний 40-символьний SHA гілки релізу. +6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. Поки тег ще не існує, + для preflight-лише валідації дозволено використовувати повний 40-символьний SHA гілки релізу. Збережіть успішний `preflight_run_id`. 7. Запустіть усі передрелізні тести через `Full Release Validation` для - гілки релізу, тегу або повного SHA коміту. Це єдина ручна точка входу + гілки релізу, тега або повного SHA коміту. Це єдина ручна точка входу для чотирьох великих блоків тестування релізу: Vitest, Docker, QA Lab і Package. -8. Якщо валідація не пройшла, виправте проблему в гілці релізу і повторно запустіть найменший невдалий - файл, лейн, завдання workflow, профіль пакета, allowlist провайдера або моделі, який - підтверджує виправлення. Повторно запускайте повну парасольку лише тоді, коли змінена поверхня - робить попередні докази неактуальними. -9. Для beta створіть тег `vYYYY.M.D-beta.N`, опублікуйте з npm dist-tag `beta`, а потім запустіть - post-publish package acceptance для опублікованого пакета `openclaw@YYYY.M.D-beta.N` +8. Якщо валідація не пройшла, виправте проблему в гілці релізу й повторно запустіть найменший збійний + файл, напрям, завдання workflow, профіль пакета, allowlist провайдера або моделі, який + підтверджує виправлення. Повторно запускайте повну загальну перевірку лише тоді, коли змінена поверхня робить + попередні докази застарілими. +9. Для beta створіть тег `vYYYY.M.D-beta.N`, опублікуйте з npm dist-tag `beta`, а потім виконайте + перевірку прийнятності пакета після публікації для опублікованого пакета `openclaw@YYYY.M.D-beta.N` або `openclaw@beta`. Якщо запушена або опублікована beta потребує виправлення, створіть - наступний `-beta.N`; не видаляйте і не переписуйте стару beta. -10. Для stable продовжуйте лише після того, як перевірена beta або кандидат на реліз матиме - необхідні докази валідації. Stable-публікація в npm повторно використовує успішний - артефакт preflight через `preflight_run_id`; готовність stable-релізу для macOS - також вимагає упакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого + наступний `-beta.N`; не видаляйте й не переписуйте стару beta. +10. Для stable продовжуйте лише після того, як перевірена beta або кандидат у реліз має + потрібні докази валідації. Stable-публікація в npm повторно використовує успішний + preflight-артефакт через `preflight_run_id`; готовність stable-релізу для macOS + також вимагає наявності запакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого `appcast.xml` у `main`. -11. Після публікації запустіть верифікатор npm після публікації, необов’язковий окремий - Telegram E2E для опублікованого npm, коли потрібен доказ каналу після публікації, - просування dist-tag за потреби, примітки GitHub release/prerelease з - повної відповідної секції `CHANGELOG.md`, а також кроки - оголошення релізу. +11. Після публікації запустіть верифікатор npm після публікації, за потреби — + необов’язковий окремий Telegram E2E для опублікованого npm, коли потрібне підтвердження каналу після публікації, + просування dist-tag за потреби, нотатки GitHub release/prerelease з + повної відповідної секції `CHANGELOG.md` і кроки оголошення релізу. ## Preflight релізу -- Запускайте `pnpm check:test-types` перед release preflight, щоб TypeScript для тестів - залишався покритим поза швидшим локальним gate `pnpm check` -- Запускайте `pnpm check:architecture` перед release preflight, щоб ширші перевірки - циклів імпорту та меж архітектури були зеленими поза швидшим локальним gate -- Запускайте `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані - артефакти релізу `dist/*` і бандл Control UI існували для кроку +- Перед preflight релізу запускайте `pnpm check:test-types`, щоб TypeScript для тестів + залишався покритим поза межами швидшого локального етапу `pnpm check` +- Перед preflight релізу запускайте `pnpm check:architecture`, щоб ширші перевірки + циклів імпорту й архітектурних меж були зеленими поза межами швидшого локального етапу +- Перед `pnpm release:check` запускайте `pnpm build && pnpm ui:build`, щоб очікувані + артефакти релізу `dist/*` і пакет Control UI існували для кроку валідації pack -- Запускайте ручний workflow `Full Release Validation` перед погодженням релізу, щоб - запустити всі блоки передрелізного тестування з однієї точки входу. Він приймає гілку, - тег або повний SHA коміту, викликає вручну `CI` і викликає - `OpenClaw Release Checks` для install smoke, package acceptance, наборів Docker - для шляху релізу, live/E2E, OpenWebUI, QA Lab parity, Matrix і лейнів - Telegram. Вказуйте `npm_telegram_package_spec` лише після того, як пакет уже - опубліковано і також має виконуватися Telegram E2E після публікації. Вказуйте - `evidence_package_spec`, коли приватний звіт доказів має підтверджувати, що +- Перед затвердженням релізу запускайте вручну workflow `Full Release Validation`, + щоб запустити всі передрелізні тестові блоки з однієї точки входу. Він приймає гілку, + тег або повний SHA коміту, вручну запускає `CI` і запускає + `OpenClaw Release Checks` для install smoke, package acceptance, наборів + release-path для Docker, live/E2E, OpenWebUI, паритету QA Lab, напрямів Matrix і Telegram. + Указуйте `npm_telegram_package_spec` лише після того, як пакет уже + опубліковано й також потрібно запустити Telegram E2E після публікації. Указуйте + `evidence_package_spec`, коли приватний звіт про докази має підтвердити, що валідація відповідає опублікованому npm-пакету без примусового запуску Telegram E2E. Приклад: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Запускайте ручний workflow `Package Acceptance`, коли потрібен побічний доказ +- Запускайте вручну workflow `Package Acceptance`, коли потрібен побічний доказ для кандидата пакета, поки робота над релізом триває. Використовуйте `source=npm` для `openclaw@beta`, `openclaw@latest` або точної версії релізу; `source=ref`, - щоб упакувати довірену гілку/тег/SHA `package_ref` з поточним harness + щоб запакувати довірену гілку/тег/SHA `package_ref` з поточним harness `workflow_ref`; `source=url` для HTTPS tarball з обов’язковим - SHA-256; або `source=artifact` для tarball, завантаженого іншим запуском GitHub + SHA-256; або `source=artifact` для tarball, завантаженого з іншого запуску GitHub Actions. Workflow визначає кандидата як - `package-under-test`, повторно використовує планувальник Docker E2E шляху релізу для цього - tarball і може запускати Telegram QA проти того самого tarball з + `package-under-test`, повторно використовує планувальник Docker E2E release для цього + tarball і може запускати Telegram QA для того самого tarball з `telegram_mode=mock-openai` або `telegram_mode=live-frontier`. Приклад: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai` - Поширені профілі: - - `smoke`: лейни install/channel/agent, мережі Gateway і перезавантаження конфігурації - - `package`: артефактно-нативні лейни пакета/оновлення/Plugin без OpenWebUI або live ClawHub + Типові профілі: + - `smoke`: напрями install/channel/agent, мережа gateway і перезавантаження конфігурації + - `package`: нативні для артефакта напрями package/update/plugin без OpenWebUI або live ClawHub - `product`: профіль package плюс канали MCP, очищення cron/subagent, вебпошук OpenAI і OpenWebUI - `full`: частини Docker release-path з OpenWebUI - `custom`: точний вибір `docker_lanes` для цільового повторного запуску -- Запускайте ручний workflow `CI` безпосередньо, коли потрібне лише повне звичайне покриття - CI для кандидата на реліз. Ручний запуск CI оминає changed scoping і примусово запускає - Linux Node shards, shards bundled-plugin, контракти каналів, сумісність Node 22, `check`, - `check-additional`, build smoke, перевірки документації, Python Skills, Windows, macOS, Android і - лейни i18n для Control UI. +- Запускайте вручну workflow `CI` безпосередньо, коли потрібне лише повне покриття + звичайного CI для кандидата релізу. Ручний запуск CI обходить змінене scope і + примусово запускає Linux Node shards, shards bundled-plugin, channel + contracts, сумісність з Node 22, напрями `check`, `check-additional`, build smoke, + docs checks, Python Skills, Windows, macOS, Android і Control UI i18n. Приклад: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Запускайте `pnpm qa:otel:smoke` під час валідації телеметрії релізу. Це проганяє - QA-lab через локальний приймач OTLP/HTTP і перевіряє експортовані назви trace span, - обмежені атрибути та редагування вмісту/ідентифікаторів без потреби в - Opik, Langfuse або іншому зовнішньому collector. -- Запускайте `pnpm release:check` перед кожним тегованим релізом -- Перевірки релізу тепер виконуються в окремому ручному workflow: +- Запускайте `pnpm qa:otel:smoke` під час валідації телеметрії релізу. Це перевіряє + QA-lab через локальний приймач OTLP/HTTP і валідує експортовані назви trace span, + обмежені атрибути та редагування content/identifier без + потреби в Opik, Langfuse чи іншому зовнішньому збирачі. +- Перед кожним тегованим релізом запускайте `pnpm release:check` +- Тепер перевірки релізу виконуються в окремому ручному workflow: `OpenClaw Release Checks` -- `OpenClaw Release Checks` також запускає QA Lab mock parity gate разом із швидким - live-профілем Matrix і лейном Telegram QA перед погодженням релізу. Live-лейни використовують - середовище `qa-live-shared`; Telegram також використовує оренду облікових даних Convex CI. - Запускайте ручний workflow `QA-Lab - All Lanes` з - `matrix_profile=all` і `matrix_shards=true`, коли потрібен повний паралельний інвентар - транспорту, медіа та E2EE Matrix. -- Крос-ОС валідація встановлення та оновлення під час виконання є частиною публічних - `OpenClaw Release Checks` і `Full Release Validation`, які викликають +- `OpenClaw Release Checks` також запускає QA Lab mock parity gate і швидкий + live-профіль Matrix та напрям Telegram QA перед затвердженням релізу. Live-напрями використовують середовище `qa-live-shared`; Telegram також використовує оренду CI-облікових даних Convex. Запускайте вручну workflow `QA-Lab - All Lanes` з + `matrix_profile=all` і `matrix_shards=true`, коли потрібен повний паралельний + інвентар транспорту, медіа й E2EE для Matrix. +- Кросплатформна валідація встановлення й оновлення під час виконання входить до публічних + `OpenClaw Release Checks` і `Full Release Validation`, які напряму викликають reusable workflow - `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` безпосередньо -- Цей поділ навмисний: зберігайте справжній шлях npm-релізу коротким, - детермінованим і зосередженим на артефактах, тоді як повільніші live-перевірки залишаються - у власному лейні, щоб не затримувати й не блокувати публікацію + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- Такий поділ навмисний: зберігайте реальний шлях npm-релізу коротким, + детермінованим і зосередженим на артефактах, тоді як повільніші live-перевірки лишаються у + власному напрямі, щоб не затримувати й не блокувати публікацію - Перевірки релізу, що використовують секрети, слід запускати через `Full Release -Validation` або з workflow ref `main`/release, щоб логіка workflow і +Validation` або з workflow ref `main`/release, щоб логіка workflow та секрети залишалися контрольованими -- `OpenClaw Release Checks` приймає гілку, тег або повний SHA коміту, якщо +- `OpenClaw Release Checks` приймає гілку, тег або повний SHA коміту, доки визначений коміт досяжний з гілки OpenClaw або тега релізу - Валідаційний preflight `OpenClaw NPM Release` також приймає поточний - повний 40-символьний SHA коміту гілки workflow без вимоги запушеного тегу -- Цей шлях із SHA призначений лише для валідації і не може бути підвищений до справжньої публікації -- У режимі SHA workflow синтезує `v` лише для - перевірки метаданих пакета; справжня публікація все одно вимагає реального тега релізу -- Обидва workflows залишають справжній шлях публікації та просування на GitHub-hosted - runners, тоді як немутуючий шлях валідації може використовувати більші - Blacksmith Linux runners + повний 40-символьний SHA коміту гілки workflow без потреби в запушеному тегі +- Цей шлях через SHA призначений лише для валідації й не може бути просунутий до реальної публікації +- У режимі SHA workflow синтезує `v` лише для перевірки + метаданих пакета; реальна публікація все одно вимагає реального тега релізу +- Обидва workflow зберігають реальний шлях публікації й просування на GitHub-hosted + runners, тоді як шлях валідації без змін стану може використовувати більші + Linux runners від Blacksmith - Цей workflow запускає `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` з використанням обох workflow secrets: `OPENAI_API_KEY` і `ANTHROPIC_API_KEY` -- npm release preflight більше не чекає на окремий лейн перевірок релізу -- Запускайте `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (або відповідний beta/correction тег) перед погодженням +- Preflight npm-релізу більше не очікує завершення окремого напряму release checks +- Перед затвердженням запускайте + `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + (або відповідний beta/correction тег) - Після публікації в npm запускайте `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (або відповідну beta/correction версію), щоб перевірити шлях встановлення з - опублікованого реєстру в новому тимчасовому префіксі -- Після публікації beta запускайте `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, - щоб перевірити onboarding встановленого пакета, налаштування Telegram і справжній Telegram E2E - проти опублікованого npm-пакета, використовуючи спільний пул орендованих облікових даних Telegram. - Для локальних одноразових перевірок мейнтейнера можна не вказувати змінні Convex і передати - безпосередньо три env-облікові дані `OPENCLAW_QA_TELEGRAM_*`. -- Мейнтейнери можуть запускати ту саму перевірку після публікації через GitHub Actions за допомогою - ручного workflow `NPM Telegram Beta E2E`. Він навмисно лише ручний і + опублікованого реєстру в новому тимчасовому prefix +- Після beta-публікації запускайте `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, + щоб перевірити onboarding встановленого пакета, налаштування Telegram і реальний Telegram E2E + для опублікованого npm-пакета з використанням спільного пулу орендованих Telegram-облікових даних. + Для одноразових локальних запусків мейнтейнера можна не вказувати змінні Convex і передати напряму три + облікові дані середовища `OPENCLAW_QA_TELEGRAM_*`. +- Мейнтейнери можуть запускати ту саму перевірку після публікації з GitHub Actions через + ручний workflow `NPM Telegram Beta E2E`. Він навмисно доступний лише вручну й не запускається після кожного merge. -- Автоматизація релізів мейнтейнера тепер використовує схему preflight-then-promote: - - справжня публікація в npm має пройти успішний npm `preflight_run_id` - - справжню публікацію в npm слід запускати з тієї самої гілки `main` або +- Автоматизація релізів для мейнтейнерів тепер використовує схему preflight-then-promote: + - реальна публікація в npm має пройти успішний npm `preflight_run_id` + - реальна публікація в npm має бути запущена з тієї самої гілки `main` або `release/YYYY.M.D`, що й успішний запуск preflight - - stable npm-релізи за замовчуванням використовують `beta` - - stable-публікація в npm може явно націлюватися на `latest` через вхідні дані workflow - - мутація npm dist-tag на основі токена тепер знаходиться в + - stable-релізи npm за замовчуванням націлені на `beta` + - stable-публікація в npm може явно націлювати `latest` через вхідні параметри workflow + - зміна npm dist-tag на основі токена тепер розташована в `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - з міркувань безпеки, оскільки `npm dist-tag add` досі потребує `NPM_TOKEN`, тоді як + з міркувань безпеки, оскільки `npm dist-tag add` усе ще потребує `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікацію лише через OIDC - публічний `macOS Release` призначений лише для валідації - - справжня приватна публікація mac має пройти успішні приватні `preflight_run_id` - і `validate_run_id` для mac - - справжні шляхи публікації просувають підготовлені артефакти замість їх повторного збирання -- Для коригувальних stable-релізів на кшталт `YYYY.M.D-N` верифікатор після публікації - також перевіряє той самий шлях оновлення в тимчасовому префіксі з `YYYY.M.D` до `YYYY.M.D-N`, - щоб корекції релізу не могли непомітно залишити старі глобальні встановлення на + - реальна приватна mac-публікація має пройти успішні приватні mac + `preflight_run_id` і `validate_run_id` + - реальні шляхи публікації просувають підготовлені артефакти замість їх повторної збірки +- Для stable-коригувальних релізів на кшталт `YYYY.M.D-N` верифікатор після публікації + також перевіряє той самий шлях оновлення через тимчасовий prefix з `YYYY.M.D` до `YYYY.M.D-N`, + щоб коригувальні релізи не могли непомітно залишити старі глобальні встановлення на базовому stable-навантаженні -- npm release preflight завершується із закритою помилкою, якщо tarball не містить і `dist/control-ui/index.html`, - і непорожнє навантаження `dist/control-ui/assets/`, щоб ми знову не - випустили порожню браузерну панель керування -- Перевірка після публікації також перевіряє, що встановлення з опублікованого реєстру - містить непорожні runtime-залежності bundled Plugin у кореневому - макеті `dist/*`. Реліз, який постачається з відсутнім або порожнім навантаженням - залежностей bundled Plugin, не проходить верифікатор після публікації і не може бути просунутий +- Preflight npm-релізу завершується з відмовою за замовчуванням, якщо tarball не містить і + `dist/control-ui/index.html`, і непорожній payload `dist/control-ui/assets/`, + щоб ми знову не випустили порожню браузерну панель +- Верифікація після публікації також перевіряє, що встановлення з опублікованого реєстру + містить непорожні runtime deps bundled plugin у кореневому + layout `dist/*`. Реліз, який постачається з відсутніми або порожніми payload + залежностей bundled plugin, не проходить postpublish verifier і не може бути просунутий до `latest`. -- `pnpm test:install:smoke` також примусово перевіряє бюджет `unpackedSize` для npm pack - у tarball кандидата на оновлення, щоб installer e2e виявляв випадкове збільшення - пакета до шляху публікації релізу -- Якщо робота над релізом торкалася планування CI, маніфестів часу extension або - матриць тестів extension, перед погодженням заново згенеруйте й перегляньте - матричні виводи `checks-node-extensions`, якими володіє planner, з `.github/workflows/ci.yml`, - щоб примітки до релізу не описували застарілу схему CI +- `pnpm test:install:smoke` також застосовує бюджет `unpackedSize` npm pack до + tarball кандидата оновлення, тож installer e2e виявляє випадкове збільшення pack + ще до шляху публікації релізу +- Якщо робота над релізом зачіпала планування CI, маніфести часу для extension або + матриці тестів extension, перед затвердженням регенеруйте й перегляньте керовані планувальником + виходи матриці workflow `checks-node-extensions` з `.github/workflows/ci.yml`, + щоб нотатки релізу не описували застарілу структуру CI - Готовність stable-релізу macOS також включає поверхні оновлювача: - - GitHub release має зрештою містити упаковані `.zip`, `.dmg` і `.dSYM.zip` - - `appcast.xml` у `main` має вказувати на новий stable zip після публікації - - упакований застосунок має зберігати non-debug bundle id, непорожню - Sparkle feed URL і `CFBundleVersion` на рівні або вище канонічного мінімального build-рівня Sparkle - для цієї версії релізу + - GitHub release має в підсумку містити запаковані `.zip`, `.dmg` і `.dSYM.zip` + - `appcast.xml` у `main` має після публікації вказувати на новий stable zip + - запакований застосунок має зберігати non-debug bundle id, непорожній feed + URL для Sparkle і `CFBundleVersion` на рівні canonical Sparkle build floor + або вище для цієї версії релізу -## Блоки тестування релізу +## Тестові блоки релізу `Full Release Validation` — це спосіб, яким оператори запускають усі передрелізні тести з однієї точки входу. Запускайте його з довіреного workflow ref `main` і передавайте @@ -245,38 +242,38 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -Workflow визначає цільовий ref, викликає вручну `CI` з -`target_ref=`, викликає `OpenClaw Release Checks` і -за потреби викликає окремий Telegram E2E після публікації, коли +Workflow визначає цільовий ref, запускає вручну `CI` з +`target_ref=`, запускає `OpenClaw Release Checks` і +за потреби запускає окремий Telegram E2E після публікації, коли встановлено `npm_telegram_package_spec`. Далі `OpenClaw Release Checks` розгалужує -install smoke, крос-ОС перевірки релізу, live/E2E покриття Docker release-path, -Package Acceptance із Telegram package QA, QA Lab parity, live Matrix і -live Telegram. Повний запуск є прийнятним лише тоді, коли у підсумку `Full Release Validation` -показано `normal_ci` і `release_checks` як успішні, а будь-який необов’язковий дочірній +install smoke, кросплатформні перевірки релізу, live/E2E покриття Docker release-path, +Package Acceptance з Telegram package QA, паритет QA Lab, live Matrix і +live Telegram. Повний запуск прийнятний лише тоді, коли підсумок `Full Release Validation` +показує `normal_ci` і `release_checks` як успішні, а будь-який необов’язковий дочірній `npm_telegram` або успішний, або навмисно пропущений. -Дочірні workflows викликаються з довіреного ref, що запускає `Full Release -Validation`, зазвичай `--ref main`, навіть якщо цільовий `ref` вказує на -старішу гілку релізу або тег. Окремого входу workflow-ref для Full Release Validation -немає; вибирайте довірений harness, вибираючи ref запуску workflow. +Дочірні workflow запускаються з довіреного ref, на якому виконується `Full Release +Validation`, зазвичай `--ref main`, навіть коли цільовий `ref` указує на +старішу гілку релізу або тег. Окремого параметра workflow-ref для Full Release Validation +немає; обирайте довірений harness, обираючи ref запуску workflow. Використовуйте ці варіанти залежно від етапу релізу: ```bash -# Валідувати неопубліковану гілку кандидата на реліз. +# Валідація неопублікованої гілки кандидата релізу. gh workflow run full-release-validation.yml \ --ref main \ -f ref=release/YYYY.M.D \ -f provider=openai \ -f mode=both -# Валідувати точний запушений коміт. +# Валідація точного запушеного коміту. gh workflow run full-release-validation.yml \ --ref main \ -f ref=<40-char-sha> \ -f provider=openai \ -f mode=both -# Після публікації beta додати Telegram E2E для опублікованого пакета. +# Після публікації beta додайте Telegram E2E для опублікованого пакета. gh workflow run full-release-validation.yml \ --ref main \ -f ref=release/YYYY.M.D \ @@ -287,33 +284,39 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Не використовуйте повну парасольку як перший повторний запуск після точкового виправлення. Якщо один блок -не пройшов, використовуйте невдалий дочірній workflow, job, Docker lane, профіль пакета, модель -провайдера або QA-лейн для наступного підтвердження. Повторно запускайте повну парасольку лише тоді, коли -виправлення змінило спільну оркестрацію релізу або зробило попередні докази для всіх блоків -неактуальними. Фінальний верифікатор парасольки повторно перевіряє записані run id дочірніх workflow, -тож після успішного повторного запуску дочірнього workflow повторно запускайте лише -невдалий батьківський job `Verify full validation`. +Не використовуйте повну загальну перевірку як перший повторний запуск після цільового виправлення. Якщо один блок +не проходить, використовуйте збійний дочірній workflow, job, Docker-напрям, профіль пакета, модельного +провайдера або QA-напрям для наступного підтвердження. Повторно запускайте повну загальну перевірку лише тоді, коли +виправлення змінило спільну оркестрацію релізу або зробило попередні докази по всіх блоках +застарілими. Фінальний верифікатор загальної перевірки повторно перевіряє записані run id дочірніх workflow, +тому після успішного повторного запуску дочірнього workflow повторно запускайте лише збійне +батьківське job `Verify full validation`. + +Для обмеженого відновлення передайте в загальний workflow `rerun_group`. `all` — це справжній +запуск кандидата на реліз, `ci` запускає лише дочірній звичайний CI, `release-checks` запускає +кожен блок релізу, а вужчі групи релізу — це `install-smoke`, +`cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` і +`npm-telegram`, коли передано окремий напрям Telegram для пакета. ### Vitest -Блок Vitest — це дочірній ручний workflow `CI`. Ручний CI навмисно -оминає changed scoping і примусово запускає звичайний тестовий граф для -кандидата на реліз: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 +Блок Vitest — це ручний дочірній workflow `CI`. Ручний CI навмисно +обходить scope змін і примусово запускає звичайний граф тестів для кандидата на реліз: +Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python -Skills, Windows, macOS, Android і i18n для Control UI. +Skills, Windows, macOS, Android і Control UI i18n. Використовуйте цей блок, щоб відповісти на запитання «чи пройшло дерево вихідного коду повний звичайний набір тестів?» -Це не те саме, що валідація продукту на шляху релізу. Докази, які слід зберігати: +Це не те саме, що валідація продукту за release-path. Докази, які слід зберігати: -- підсумок `Full Release Validation`, що показує URL запущеного прогону `CI` -- зелений прогін `CI` на точному цільовому SHA -- назви shard-ів, що впали або працювали повільно, із job-ів CI під час дослідження регресій +- підсумок `Full Release Validation`, що показує URL запущеного `CI` +- зелений запуск `CI` на точному цільовому SHA +- назви shard із помилками або повільних shard із job CI під час дослідження регресій - артефакти часу Vitest, такі як `.artifacts/vitest-shard-timings.json`, коли запуск потребує аналізу продуктивності -Запускайте ручний CI безпосередньо лише тоді, коли релізу потрібен детермінований звичайний CI, але -не потрібні блоки Docker, QA Lab, live, cross-OS або Package: +Запускайте ручний CI напряму лише тоді, коли релізу потрібен детермінований звичайний CI, але +не потрібні блоки Docker, QA Lab, live, cross-OS або package: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -321,91 +324,91 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Блок Docker знаходиться в `OpenClaw Release Checks` через -`openclaw-live-and-e2e-checks-reusable.yml`, а також через workflow -`install-smoke` у режимі релізу. Він валідовує кандидата на реліз через упаковані -середовища Docker, а не лише через тести на рівні вихідного коду. +Блок Docker розташований у `OpenClaw Release Checks` через +`openclaw-live-and-e2e-checks-reusable.yml`, а також у workflow +`install-smoke` у режимі релізу. Він валідовує кандидата на реліз через запаковані +середовища Docker, а не лише тести на рівні вихідного коду. Покриття Docker для релізу включає: -- повний install smoke з увімкненим повільним smoke глобального встановлення Bun -- лейни E2E для репозиторію -- частини Docker для шляху релізу: `core`, `package-update-openai`, +- повний install smoke з увімкненим повільним Bun global install smoke +- напрями E2E для репозиторію +- частини Docker release-path: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-core`, - `plugins-runtime-install-a`, `plugins-runtime-install-b` і - `bundled-channels` + `plugins-runtime-install-a`, `plugins-runtime-install-b`, + `bundled-channels-core`, `bundled-channels-update-a`, + `bundled-channels-update-b` і `bundled-channels-contracts` - покриття OpenWebUI всередині частини `plugins-runtime-core`, коли це запитано -- розділені лейни залежностей bundled-channel у власній частині `bundled-channels` - замість послідовного all-in-one лейна bundled-channel -- розділені лейни встановлення/видалення bundled Plugin +- розділені напрями залежностей bundled-channel між частинами channel-smoke, update-target + і setup/runtime contract замість одного великого job bundled-channel +- розділені напрями встановлення/видалення bundled plugin `bundled-plugin-install-uninstall-0` до `bundled-plugin-install-uninstall-7` -- live/E2E набори провайдерів і покриття live-моделей Docker, коли перевірки релізу +- набори live/E2E для провайдерів і покриття live-моделей Docker, коли перевірки релізу включають live-набори -Використовуйте артефакти Docker перед повторним запуском. Планувальник шляху релізу -вивантажує `.artifacts/docker-tests/` з логами лейнів, `summary.json`, `failures.json`, -часом фаз, JSON плану планувальника та командами повторного запуску. Для точкового відновлення +Використовуйте артефакти Docker перед повторним запуском. Планувальник release-path вивантажує +`.artifacts/docker-tests/` з логами напрямів, `summary.json`, `failures.json`, +часом фаз, JSON плану планувальника та командами повторного запуску. Для цільового відновлення використовуйте `docker_lanes=` у reusable workflow live/E2E замість -повторного запуску всіх частин релізу. Згенеровані команди повторного запуску включають попередній -`package_artifact_run_id` і підготовлені вхідні дані образів Docker, коли вони доступні, щоб -лейн, що впав, міг повторно використати той самий tarball і образи GHCR. +повторного запуску всіх частин релізу. Згенеровані команди повторного запуску включають попередні +`package_artifact_run_id` і підготовлені вхідні параметри образів Docker, коли вони доступні, тож +напрям із помилкою може повторно використати той самий tarball і образи GHCR. ### QA Lab -Блок QA Lab також є частиною `OpenClaw Release Checks`. Це gate -агентної поведінки та поведінки на рівні каналів для релізу, окремий від механіки пакетів Vitest і Docker. +Блок QA Lab також є частиною `OpenClaw Release Checks`. Це релізний gate для +агентної поведінки та поведінки на рівні каналів, окремий від механіки пакетів Vitest і Docker. Покриття QA Lab для релізу включає: -- mock parity gate, що порівнює кандидатний лейн OpenAI з базовим рівнем Opus 4.6 - за допомогою пакета agentic parity -- швидкий live-профіль Matrix QA з використанням середовища `qa-live-shared` -- live-лейн Telegram QA з орендою облікових даних Convex CI +- mock parity gate, який порівнює напрям кандидата OpenAI з базовою лінією Opus 4.6 + за допомогою agentic parity pack +- швидкий live-профіль QA для Matrix з середовищем `qa-live-shared` +- live-напрям QA для Telegram з орендою облікових даних CI у Convex - `pnpm qa:otel:smoke`, коли телеметрія релізу потребує явного локального підтвердження -Використовуйте цей блок, щоб відповісти на запитання «чи правильно поводиться реліз у QA-сценаріях і -live-потоках каналів?» Під час погодження релізу зберігайте URL артефактів для лейнів parity, Matrix і Telegram. -Повне покриття Matrix залишається доступним як ручний шардований запуск QA-Lab, а не -як типовий критичний для релізу лейн. +Використовуйте цей блок, щоб відповісти на запитання «чи реліз поводиться правильно в QA-сценаріях і +live-потоках каналів?» Під час затвердження релізу зберігайте URL артефактів для +напрямів parity, Matrix і Telegram. Повне покриття Matrix лишається доступним як +ручний шардований запуск QA-Lab, а не як напрям за замовчуванням, критичний для релізу. ### Package -Блок Package — це gate для встановлюваного продукту. Його підтримують +Блок Package — це gate для встановлюваного продукту. Він базується на `Package Acceptance` і resolver `scripts/resolve-openclaw-package-candidate.mjs`. Resolver нормалізує кандидата в tarball `package-under-test`, який споживає Docker E2E, валідовує -інвентар пакета, записує версію пакета і SHA-256 та зберігає -ref harness workflow окремо від ref джерела пакета. +інвентар пакета, записує версію пакета й SHA-256 та зберігає ref harness workflow +окремо від ref джерела пакета. -Підтримувані джерела кандидата: +Підтримувані джерела кандидатів: - `source=npm`: `openclaw@beta`, `openclaw@latest` або точна версія релізу OpenClaw -- `source=ref`: упакувати довірену гілку, тег або повний SHA коміту `package_ref` - з вибраним harness `workflow_ref` +- `source=ref`: запакувати довірену гілку, тег або повний SHA коміту `package_ref` + із вибраним harness `workflow_ref` - `source=url`: завантажити HTTPS `.tgz` з обов’язковим `package_sha256` - `source=artifact`: повторно використати `.tgz`, вивантажений іншим запуском GitHub Actions `OpenClaw Release Checks` запускає Package Acceptance з `source=ref`, `package_ref=`, `suite_profile=custom`, `docker_lanes=bundled-channel-deps-compat plugins-offline` і -`telegram_mode=mock-openai`. Частини Docker для шляху релізу покривають -лейни встановлення, оновлення та оновлення Plugin, що перетинаються; Package Acceptance -зберігає артефактно-нативну сумісність bundled-channel, офлайн-фікстури Plugin і Telegram -package QA проти того самого визначеного tarball. Це GitHub-native -заміна для більшості покриття package/update, яке раніше вимагало -Parallels. Cross-OS перевірки релізу все ще важливі для специфічної для ОС поведінки onboarding, -інсталятора та платформи, але валідація продукту package/update має +`telegram_mode=mock-openai`. Частини Docker release-path покривають +перетинні напрями install, update і plugin-update; Package Acceptance зберігає +нативну для артефакта сумісність bundled-channel, офлайн-фікстури плагінів і Telegram package QA для того самого визначеного tarball. Це нативна для GitHub +заміна більшості покриття package/update, яке раніше вимагало +Parallels. Кросплатформні перевірки релізу все ще важливі для специфічної для ОС +поведінки onboarding, installer і платформи, але валідація продукту package/update повинна віддавати перевагу Package Acceptance. Історична поблажливість package-acceptance навмисно обмежена в часі. Пакети до -`2026.4.25` можуть використовувати шлях сумісності для прогалин у метаданих, уже опублікованих -у npm: приватні записи інвентарю QA, відсутні в tarball; відсутній -`gateway install --wrapper`; відсутні patch-файли у git-фікстурі, похідній від tarball; -відсутній збережений `update.channel`; історичні розташування install-record для Plugin; -відсутнє збереження install-record marketplace; і міграція метаданих конфігурації під час `plugins update`. -Пакети після `2026.4.25` мають відповідати сучасним контрактам пакета; -ті самі прогалини призводять до провалу валідації релізу. +`2026.4.25` можуть використовувати шлях сумісності для прогалин у метаданих, уже +опублікованих у npm: приватні записи QA inventory, відсутні в tarball, +відсутній `gateway install --wrapper`, відсутні patch-файли у git-фікстурі, похідній від tarball, +відсутній збережений `update.channel`, історичні розташування install-record +для плагінів, відсутність збереження marketplace install-record і +міграція метаданих конфігурації під час `plugins update`. Пакети після `2026.4.25` повинні відповідати +сучасним контрактам пакета; ті самі прогалини призведуть до помилки валідації релізу. Використовуйте ширші профілі Package Acceptance, коли питання релізу стосується реального встановлюваного пакета: @@ -421,84 +424,84 @@ gh workflow run package-acceptance.yml \ Поширені профілі пакета: -- `smoke`: швидкі лейни package install/channel/agent, мережі Gateway і +- `smoke`: швидкі напрями встановлення package/channel/agent, мережі gateway і перезавантаження конфігурації - `package`: контракти package install/update/plugin без live ClawHub; це типовий варіант release-check -- `product`: `package` плюс канали MCP, очищення cron/subagent, вебпошук OpenAI - і OpenWebUI -- `full`: частини Docker шляху релізу з OpenWebUI -- `custom`: точний список `docker_lanes` для точкових повторних запусків +- `product`: `package` плюс канали MCP, очищення cron/subagent, OpenAI web + search і OpenWebUI +- `full`: частини Docker release-path з OpenWebUI +- `custom`: точний список `docker_lanes` для цільових повторних запусків -Для доказу Telegram для кандидата пакета вмикайте `telegram_mode=mock-openai` або -`telegram_mode=live-frontier` у Package Acceptance. Workflow передає -визначений tarball `package-under-test` у лейн Telegram; окремий -workflow Telegram як і раніше приймає специфікацію опублікованого npm для перевірок після публікації. +Для підтвердження Telegram для кандидата пакета увімкніть `telegram_mode=mock-openai` або +`telegram_mode=live-frontier` у Package Acceptance. Workflow передає tarball +визначеного `package-under-test` у напрям Telegram; окремий workflow +Telegram усе ще приймає специфікацію опублікованого npm для перевірок після публікації. ## Вхідні параметри workflow npm -`OpenClaw NPM Release` приймає такі вхідні параметри, контрольовані оператором: +`OpenClaw NPM Release` приймає такі керовані оператором вхідні параметри: - `tag`: обов’язковий тег релізу, наприклад `v2026.4.2`, `v2026.4.2-1` або `v2026.4.2-beta.1`; коли `preflight_only=true`, це також може бути поточний - повний 40-символьний SHA коміту гілки workflow для preflight лише з метою валідації -- `preflight_only`: `true` лише для валідації/збирання/пакета, `false` для + повний 40-символьний SHA коміту гілки workflow для preflight, призначеного лише для валідації +- `preflight_only`: `true` для лише валідації/збірки/пакета, `false` для реального шляху публікації -- `preflight_run_id`: обов’язковий у реальному шляху публікації, щоб workflow повторно використав +- `preflight_run_id`: обов’язковий для реального шляху публікації, щоб workflow повторно використав підготовлений tarball з успішного запуску preflight -- `npm_dist_tag`: цільовий npm-тег для шляху публікації; за замовчуванням `beta` +- `npm_dist_tag`: цільовий тег npm для шляху публікації; за замовчуванням `beta` -`OpenClaw Release Checks` приймає такі вхідні параметри, контрольовані оператором: +`OpenClaw Release Checks` приймає такі керовані оператором вхідні параметри: - `ref`: гілка, тег або повний SHA коміту для валідації. Перевірки, що використовують секрети, - вимагають, щоб визначений коміт був досяжний з гілки OpenClaw або + вимагають, щоб визначений коміт був досяжний із гілки OpenClaw або тега релізу. Правила: -- Stable- і correction-теги можуть публікуватися або в `beta`, або в `latest` -- Beta prerelease-теги можуть публікуватися лише в `beta` -- Для `OpenClaw NPM Release` вхідний повний SHA коміту дозволено лише коли +- Теги stable і correction можуть публікуватися як у `beta`, так і в `latest` +- Теги beta prerelease можуть публікуватися лише в `beta` +- Для `OpenClaw NPM Release` повний SHA коміту дозволений лише коли `preflight_only=true` - `OpenClaw Release Checks` і `Full Release Validation` завжди призначені лише для валідації -- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, який використовувався під час preflight; - workflow перевіряє ці метадані, перш ніж публікація продовжиться +- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, що використовувався під час preflight; + workflow перевіряє ці метадані, перш ніж продовжити публікацію ## Послідовність stable npm-релізу Під час випуску stable npm-релізу: 1. Запустіть `OpenClaw NPM Release` з `preflight_only=true` - - До появи тегу можна використовувати поточний повний SHA коміту гілки workflow - для dry run workflow preflight лише з метою валідації -2. Виберіть `npm_dist_tag=beta` для звичайного потоку beta-first або `latest` лише - коли ви навмисно хочете пряму stable-публікацію + - Поки тег ще не існує, ви можете використовувати поточний повний SHA коміту + гілки workflow для dry-run валідації preflight workflow +2. Оберіть `npm_dist_tag=beta` для звичайного потоку beta-first або `latest` лише + тоді, коли ви навмисно хочете напряму опублікувати stable 3. Запустіть `Full Release Validation` для гілки релізу, тега релізу або повного - SHA коміту, коли потрібні звичайний CI плюс покриття live prompt cache, Docker, QA Lab, - Matrix і Telegram з одного ручного workflow -4. Якщо навмисно потрібен лише детермінований звичайний тестовий граф, замість цього запустіть + SHA коміту, коли вам потрібні звичайний CI, live prompt cache, Docker, QA Lab, + Matrix і Telegram coverage з одного ручного workflow +4. Якщо вам навмисно потрібен лише детермінований звичайний граф тестів, натомість запустіть ручний workflow `CI` для ref релізу 5. Збережіть успішний `preflight_run_id` 6. Знову запустіть `OpenClaw NPM Release` з `preflight_only=false`, тим самим `tag`, тим самим `npm_dist_tag` і збереженим `preflight_run_id` -7. Якщо реліз потрапив у `beta`, використайте приватний - workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, +7. Якщо реліз потрапив у `beta`, використайте приватний workflow + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, щоб просунути цю stable-версію з `beta` до `latest` -8. Якщо реліз навмисно був опублікований безпосередньо в `latest`, а `beta` - має одразу слідувати за тією ж stable-збіркою, використайте той самий приватний - workflow, щоб спрямувати обидва dist-tag на stable-версію, або дозвольте його запланованій - self-healing синхронізації перемістити `beta` пізніше +8. Якщо реліз навмисно було одразу опубліковано в `latest`, а `beta` + має одразу вказувати на ту саму stable-збірку, використайте той самий приватний + workflow, щоб спрямувати обидва dist-tag на stable-версію, або дозвольте його + запланованій self-healing синхронізації перемістити `beta` пізніше -Мутація dist-tag живе в приватному репозиторії з міркувань безпеки, оскільки вона все ще +Зміна dist-tag розташована в приватному репозиторії з міркувань безпеки, оскільки вона все ще потребує `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікацію лише через OIDC. -Це зберігає і шлях прямої публікації, і шлях просування beta-first -задокументованими та видимими для оператора. +Це зберігає як шлях прямої публікації, так і шлях просування beta-first +задокументованими й видимими для оператора. -Якщо мейнтейнеру доводиться повертатися до локальної npm-автентифікації, виконуйте будь-які команди -1Password CLI (`op`) лише в окремій сесії tmux. Не викликайте `op` -безпосередньо з основної оболонки агента; запуск усередині tmux робить prompts, -alerts і обробку OTP спостережуваними та запобігає повторним сповіщенням на хості. +Якщо мейнтейнеру доведеться повернутися до локальної автентифікації npm, запускайте будь-які команди +1Password CLI (`op`) лише всередині окремої tmux-сесії. Не викликайте `op` +напряму з основної оболонки агента; запуск усередині tmux робить запити, +сповіщення та обробку OTP видимими й запобігає повторним сповіщенням хоста. ## Публічні посилання @@ -512,10 +515,10 @@ alerts і обробку OTP спостережуваними та запобі - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -Мейнтейнери використовують приватну документацію релізу в +Мейнтейнери використовують приватну документацію релізів у [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) як фактичний runbook. ## Пов’язане -- [Канали релізу](/uk/install/development-channels) +- [Канали релізів](/uk/install/development-channels) diff --git a/docs/uk/tools/index.md b/docs/uk/tools/index.md index 01b742735..ce3547401 100644 --- a/docs/uk/tools/index.md +++ b/docs/uk/tools/index.md @@ -2,125 +2,125 @@ read_when: - Ви хочете зрозуміти, які інструменти надає OpenClaw - Вам потрібно налаштувати, дозволити або заборонити інструменти - - 'Ви вирішуєте, що обрати: вбудовані інструменти, Skills чи Plugin' -summary: 'Огляд інструментів і Plugin в OpenClaw: що агент може робити та як його розширити' -title: Інструменти та Plugin + - Ви обираєте між вбудованими інструментами, Skills і плагінами +summary: 'Огляд інструментів і плагінів OpenClaw: що може робити агент і як його розширити' +title: Інструменти та плагіни x-i18n: - generated_at: "2026-04-26T04:25:31Z" + generated_at: "2026-04-27T22:51:31Z" model: gpt-5.4 provider: openai - source_hash: 47cc0e2de5688328f7c11fcf86c0a2262b488c277f48416f584f5c7913f750c4 + source_hash: 62cde740188c224af03b4425c7f6dfca9a12f95603066db5925724fc6a07dcf0 source_path: tools/index.md workflow: 15 --- Усе, що агент робить понад генерування тексту, відбувається через **інструменти**. -Інструменти — це спосіб, яким агент читає файли, запускає команди, переглядає веб, надсилає +Інструменти — це спосіб, у який агент читає файли, запускає команди, переглядає веб, надсилає повідомлення та взаємодіє з пристроями. -## Інструменти, Skills і Plugin +## Інструменти, Skills і плагіни -OpenClaw має три рівні, які працюють разом: +OpenClaw має три шари, які працюють разом: Інструмент — це типізована функція, яку агент може викликати (наприклад, `exec`, `browser`, `web_search`, `message`). OpenClaw постачається з набором **вбудованих інструментів**, а - plugins можуть реєструвати додаткові. + плагіни можуть реєструвати додаткові. Агент бачить інструменти як структуровані визначення функцій, надіслані до API моделі. - Skill — це markdown-файл (`SKILL.md`), який додається до системного prompt-а. + Skill — це markdown-файл (`SKILL.md`), який додається до системного запиту. Skills надають агенту контекст, обмеження та покрокові вказівки для - ефективного використання інструментів. Skills можуть бути у вашому робочому просторі, у спільних теках - або постачатися всередині plugins. + ефективного використання інструментів. Skills розміщуються у вашому робочому просторі, у спільних папках + або постачаються всередині плагінів. [Довідник Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) - - Plugin — це пакет, який може реєструвати будь-яку комбінацію можливостей: + + Плагін — це пакет, який може реєструвати будь-яку комбінацію можливостей: канали, провайдерів моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, голос у реальному часі, розуміння медіа, генерацію зображень, генерацію відео, - web fetch, web search тощо. Деякі plugins є **core** (постачаються з - OpenClaw), інші — **external** (опубліковані в npm спільнотою). + отримання даних із вебу, пошук у вебі тощо. Деякі плагіни є **core** (постачаються з + OpenClaw), інші — **external** (опубліковані спільнотою в npm). - [Установлення та налаштування plugins](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) + [Установлення та налаштування плагінів](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) ## Вбудовані інструменти -Ці інструменти постачаються з OpenClaw і доступні без установлення будь-яких plugins: +Ці інструменти постачаються з OpenClaw і доступні без установлення будь-яких плагінів: -| Інструмент | Що він робить | Сторінка | -| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ | -| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Підтвердження Exec](/uk/tools/exec-approvals) | -| `code_execution` | Запускає ізольований віддалений аналіз Python | [Code Execution](/uk/tools/code-execution) | -| `browser` | Керує браузером Chromium (перехід, клік, знімок екрана) | [Browser](/uk/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи X, отримує вміст сторінок | [Веб](/uk/tools/web), [Web Fetch](/uk/tools/web-fetch) | -| `read` / `write` / `edit` | Операції введення/виведення файлів у робочому просторі | | -| `apply_patch` | Багатофрагментні патчі файлів | [Apply Patch](/uk/tools/apply-patch) | -| `message` | Надсилає повідомлення в усіх каналах | [Надсилання агентом](/uk/tools/agent-send) | -| `canvas` | Керує node Canvas (present, eval, snapshot) | | -| `nodes` | Виявляє та націлює спарені пристрої | | -| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює Gateway | | -| `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) | -| `music_generate` | Генерує музичні треки | [Генерація музики](/uk/tools/music-generation) | -| `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) | -| `tts` | Одноразове перетворення тексту в мовлення | [TTS](/uk/tools/tts) | -| `sessions_*` / `subagents` / `agents_list`| Керування сесіями, станом і оркестрацією субагентів | [Субагенти](/uk/tools/subagents) | -| `session_status` | Полегшене зчитування в стилі `/status` і перевизначення моделі для сесії | [Інструменти сесій](/uk/concepts/session-tool) | +| Інструмент | Що він робить | Сторінка | +| ------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ | +| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Погодження Exec](/uk/tools/exec-approvals) | +| `code_execution` | Запускає ізольований віддалений аналіз Python | [Code Execution](/uk/tools/code-execution) | +| `browser` | Керує браузером Chromium (перехід, натискання, знімок екрана) | [Browser](/uk/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Веб](/uk/tools/web), [Web Fetch](/uk/tools/web-fetch) | +| `read` / `write` / `edit` | Введення/виведення файлів у робочому просторі | | +| `apply_patch` | Багатоблокові патчі файлів | [Apply Patch](/uk/tools/apply-patch) | +| `message` | Надсилає повідомлення через усі канали | [Надсилання агентом](/uk/tools/agent-send) | +| `canvas` | Керує вузловим Canvas (present, eval, snapshot) | | +| `nodes` | Виявляє та націлюється на спарені пристрої | | +| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює Gateway | | +| `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) | +| `music_generate` | Генерує музичні треки | [Генерація музики](/uk/tools/music-generation) | +| `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) | +| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статус і оркестрація субагентів | [Субагенти](/uk/tools/subagents) | +| `session_status` | Полегшене зчитування у стилі `/status` і перевизначення моделі для сесії | [Інструменти сесії](/uk/concepts/session-tool) | -Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого неосновного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи із зображеннями використовуйте `image` для аналізу, а `image_generate` — для генерації або редагування. Якщо ви націлюєтесь на `openai/*`, `google/*`, `fal/*` або іншого не стандартного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого неосновного провайдера музики, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтесь на `google/*`, `minimax/*` або іншого не стандартного музичного провайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого неосновного провайдера відео, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтесь на `qwen/*` або іншого не стандартного відеопровайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для генерації аудіо, керованої workflow, використовуйте `music_generate`, коли plugin на кшталт -ComfyUI реєструє його. Це окремо від `tts`, який є перетворенням тексту в мовлення. +Для генерації аудіо на основі workflow використовуйте `music_generate`, коли плагін, наприклад +ComfyUI, реєструє його. Це окремо від `tts`, яке є перетворенням тексту на мовлення. -`session_status` — це полегшений інструмент стану/зчитування в групі інструментів сесій. -Він відповідає на запитання в стилі `/status` про поточну сесію та може -за бажанням задавати перевизначення моделі для конкретної сесії; `model=default` очищує -це перевизначення. Як і `/status`, він може заповнювати відсутні лічильники токенів/кешу та -мітку активної моделі середовища виконання з останнього запису використання в транскрипті. +`session_status` — це полегшений інструмент статусу/зчитування в групі сесій. +Він відповідає на запитання у стилі `/status` про поточну сесію та може +за бажанням встановлювати перевизначення моделі для окремої сесії; `model=default` скидає це +перевизначення. Як і `/status`, він може дозаповнювати розріджені лічильники токенів/кешу та +мітку активної моделі середовища виконання з останнього запису про використання в транскрипті. `gateway` — це інструмент середовища виконання лише для власника для операцій Gateway: - `config.schema.lookup` для одного піддерева конфігурації, обмеженого шляхом, перед редагуванням -- `config.get` для поточного знімка конфігурації + hash +- `config.get` для поточного знімка конфігурації + хешу - `config.patch` для часткових оновлень конфігурації з перезапуском - `config.apply` лише для повної заміни конфігурації - `update.run` для явного самооновлення + перезапуску Для часткових змін надавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте `config.apply` лише тоді, коли ви свідомо замінюєте всю конфігурацію. -Докладніше про конфігурацію див. у [Конфігурація](/uk/gateway/configuration) та +Для ширшої документації з конфігурації дивіться [Конфігурація](/uk/gateway/configuration) і [Довідник із конфігурації](/uk/gateway/configuration-reference). Інструмент також відмовляється змінювати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec. -### Інструменти, надані Plugin +### Інструменти, надані плагінами -Plugins можуть реєструвати додаткові інструменти. Деякі приклади: +Плагіни можуть реєструвати додаткові інструменти. Деякі приклади: -- [Diffs](/uk/tools/diffs) — переглядач і рендерер diff +- [Diffs](/uk/tools/diffs) — засіб перегляду та візуалізації diff - [LLM Task](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу -- [Lobster](/uk/tools/lobster) — типізоване середовище виконання workflow з підтвердженнями, які можна відновлювати +- [Lobster](/uk/tools/lobster) — типізоване середовище виконання workflow із відновлюваними погодженнями - [Генерація музики](/uk/tools/music-generation) — спільний інструмент `music_generate` із провайдерами на основі workflow -- [OpenProse](/uk/prose) — оркестрація workflow з орієнтацією на markdown -- [Tokenjuice](/uk/tools/tokenjuice) — компактні результати інструментів `exec` і `bash` з шумним виводом +- [OpenProse](/uk/prose) — оркестрація workflow з пріоритетом markdown +- [Tokenjuice](/uk/tools/tokenjuice) — компактні результати інструментів `exec` і `bash` з великим шумом ## Налаштування інструментів -### Списки дозволених і заборонених +### Списки дозволів і заборон Керуйте тим, які інструменти агент може викликати, через `tools.allow` / `tools.deny` у конфігурації. Заборона завжди має пріоритет над дозволом. @@ -134,63 +134,81 @@ Plugins можуть реєструвати додаткові інструме } ``` -OpenClaw працює в режимі fail-closed, коли явний список дозволених не дає жодного викличного інструмента. -Наприклад, `tools.allow: ["query_db"]` працює лише якщо завантажений plugin справді -реєструє `query_db`. Якщо жоден вбудований, plugin або bundled MCP-інструмент не відповідає -списку дозволених, виконання зупиняється до виклику моделі, а не продовжується як -запуск лише з текстом, що міг би вигадати результати інструментів. +OpenClaw використовує заборону за замовчуванням, якщо явний список дозволів не дає жодного доступного для виклику інструмента. +Наприклад, `tools.allow: ["query_db"]` працює, лише якщо завантажений плагін справді +реєструє `query_db`. Якщо жоден вбудований, плагінний або вбудований у пакет MCP-інструмент не відповідає +списку дозволів, виконання зупиняється до виклику моделі, а не продовжується як +режим лише з текстом, який міг би галюцинувати результати інструментів. ### Профілі інструментів -`tools.profile` задає базовий список дозволених перед застосуванням `allow`/`deny`. -Перевизначення для агента: `agents.list[].tools.profile`. +`tools.profile` задає базовий список дозволів до застосування `allow`/`deny`. +Перевизначення для окремого агента: `agents.list[].tools.profile`. -| Профіль | Що він містить | -| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Без обмежень (те саме, що не задано) | +| Профіль | Що він містить | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `full` | Необмежений базовий рівень для ширшого доступу до команд/керування; те саме, що залишити `tools.profile` не заданим | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | -| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | Лише `session_status` | +| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `minimal` | Лише `session_status` | + + +`tools.profile: "messaging"` навмисно є вузьким для +агентів, орієнтованих на канали. Він не включає ширші інструменти команд/керування, як-от файлову систему, runtime, +browser, canvas, nodes, Cron і керування Gateway. Використовуйте `tools.profile: "full"` +як необмежений базовий рівень для ширшого доступу до команд/керування, а потім звужуйте +доступ за допомогою `tools.allow` / `tools.deny`, коли це потрібно. + `coding` включає полегшені веб-інструменти (`web_search`, `web_fetch`, `x_search`), але не повний інструмент керування браузером. Автоматизація браузера може керувати реальними -сесіями та профілями з входом у систему, тому додавайте її явно через -`tools.alsoAllow: ["browser"]` або перевизначення для агента +сесіями та профілями з виконаним входом, тому додавайте її явно через +`tools.alsoAllow: ["browser"]` або перевизначення для окремого агента `agents.list[].tools.alsoAllow: ["browser"]`. Профілі `coding` і `messaging` також дозволяють налаштовані bundled MCP-інструменти -під ключем plugin `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, коли ви -хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховав усі налаштовані MCP-інструменти. +під ключем плагіна `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, коли +ви хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховав усі налаштовані MCP-інструменти. Профіль `minimal` не включає bundled MCP-інструменти. +Приклад (найширша поверхня інструментів за замовчуванням): + +```json5 +{ + tools: { + profile: "full", + }, +} +``` + ### Групи інструментів -Використовуйте скорочення `group:*` у списках дозволених/заборонених: +Використовуйте скорочення `group:*` у списках дозволів/заборон: -| Група | Інструменти | -| ----------------- | ----------------------------------------------------------------------------------------------------- | -| `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | read, write, edit, apply_patch | -| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | -| `group:memory` | memory_search, memory_get | -| `group:web` | web_search, x_search, web_fetch | -| `group:ui` | browser, canvas | -| `group:automation`| cron, gateway | -| `group:messaging` | message | -| `group:nodes` | nodes | -| `group:agents` | agents_list | -| `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | Усі вбудовані інструменти OpenClaw (не включає інструменти plugins) | +| Група | Інструменти | +| ------------------ | -------------------------------------------------------------------------------------------------------- | +| `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | read, write, edit, apply_patch | +| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | +| `group:memory` | memory_search, memory_get | +| `group:web` | web_search, x_search, web_fetch | +| `group:ui` | browser, canvas | +| `group:automation` | cron, gateway | +| `group:messaging` | message | +| `group:nodes` | nodes | +| `group:agents` | agents_list | +| `group:media` | image, image_generate, music_generate, video_generate, tts | +| `group:openclaw` | Усі вбудовані інструменти OpenClaw (не включає інструменти плагінів) | -`sessions_history` повертає обмежене, відфільтроване з погляду безпеки представлення для відновлення контексту. Воно видаляє -теги thinking, каркас ``, XML-навантаження викликів інструментів у звичайному тексті +`sessions_history` повертає обмежене, відфільтроване з погляду безпеки представлення для відтворення контексту. Воно прибирає +теги мислення, каркас ``, XML-навантаження викликів інструментів у звичайному тексті (включно з `...`, `...`, `...`, -`...` і усіченими блоками викликів інструментів), -каркас викликів інструментів у зниженому форматі, витеклі ASCII/повноширинні токени керування моделлю -та некоректний XML викликів інструментів MiniMax з тексту асистента, а потім застосовує -редагування/усічення й, за потреби, заповнювачі для надто великих рядків замість того, щоб -бути сирим дампом транскрипту. +`...` і скороченими блоками викликів інструментів), +понижений каркас викликів інструментів, витоки ASCII/повноширинних токенів керування моделлю +та некоректний XML викликів інструментів MiniMax з тексту помічника, а потім застосовує +редагування/скорочення та, за потреби, заповнювачі для надто великих рядків, замість того щоб працювати +як сирий дамп транскрипту. ### Обмеження для конкретних провайдерів