diff --git a/docs/uk/ci.md b/docs/uk/ci.md index c984bf2ce..9079e7217 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,27 +1,60 @@ --- read_when: - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося. - - Ви налагоджуєте збої перевірок GitHub Actions. -summary: Граф завдань CI, обмеження області перевірок і локальні еквіваленти команд + - Ви налагоджуєте збої в перевірках GitHub Actions. +summary: Граф завдань CI, межі перевірок і локальні еквіваленти команд title: конвеєр CI x-i18n: - generated_at: "2026-04-24T19:39:41Z" + generated_at: "2026-04-24T19:51:03Z" model: gpt-5.4 provider: openai - source_hash: 8890c5e518bcc98d4980018b3bb3f67eb131cb5781c0b5c7251b2d8e75d9b19e + source_hash: 8407768803b8d92e03a7fb453307a64cb4f2342ba3894b51d4c928dd434fede6 source_path: ci.md workflow: 15 --- -CI запускається під час кожного push до `main` і для кожного pull request. Він використовує розумне обмеження області, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. +CI запускається для кожного push до `main` і кожного pull request. Він використовує розумне визначення меж, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. -QA Lab має окремі доріжки CI поза основним workflow з розумним обмеженням області. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне QA runtime і порівнює агентні набори mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а доріжка Telegram використовує Convex leases. `OpenClaw Release Checks` також запускає ті самі доріжки QA Lab перед затвердженням релізу. +QA Lab має виділені смуги CI поза межами основного workflow з розумним визначенням меж. Workflow +`Parity gate` запускається для відповідних змін у PR і через ручний dispatch; він +збирає приватний runtime QA і порівнює agentic-паки mock GPT-5.4 та Opus 4.6. +Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через +ручний dispatch; він розгалужує mock parity gate, live Matrix lane і live +Telegram lane як паралельні завдання. Live-завдання використовують environment `qa-live-shared`, +а смуга Telegram використовує оренди Convex. `OpenClaw Release +Checks` також запускає ті самі смуги QA Lab перед погодженням релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для післямержевого очищення дублікатів. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що замержений PR дійсно злитий, і що кожен дублікат має або спільне пов’язане issue, або перетин змінених фрагментів. +Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для +очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і +закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub +він перевіряє, що злитий PR має статус merged, і що кожен дублікат має або +спільну згадану issue, або перекривні змінені hunks. -Workflow `Docs Agent` — це керована подіями доріжка обслуговування Codex для підтримання наявної документації у відповідності до нещодавно злитих змін. Вона не має окремого запуску за розкладом: її може запустити успішний небoтовий CI-run після push у `main`, а також її можна запустити напряму вручну. Виклики через workflow-run пропускаються, якщо `main` уже пішов далі або якщо протягом останньої години вже було створено інший непроґавлений запуск Docs Agent. Коли вона виконується, вона переглядає діапазон комітів від source SHA попереднього непроґавленого запуску Docs Agent до поточного `main`, тож один погодинний запуск може охопити всі зміни `main`, накопичені з часу останнього проходу документації. +Workflow `Docs Agent` — це event-driven смуга технічного обслуговування Codex для підтримання +наявної документації у відповідності до нещодавно злитих змін. У нього немає окремого запуску за розкладом: +його може запустити успішний неботовий CI run push до `main`, а +ручний dispatch може запустити його напряму. Виклики через workflow-run пропускаються, +якщо `main` уже пішов далі або якщо інший непропущений запуск Docs Agent +було створено протягом останньої години. Коли він запускається, він +переглядає діапазон комітів від SHA джерела попереднього непропущеного Docs Agent до +поточного `main`, тож один щогодинний запуск може охопити всі зміни в main, +накопичені з часу останнього проходу документації. -Workflow `Test Performance Agent` — це керована подіями доріжка обслуговування Codex для повільних тестів. Вона не має окремого запуску за розкладом: її може запустити успішний небoтовий CI-run після push у `main`, але вона пропускається, якщо інший виклик через workflow-run уже виконався або виконується того самого дня за UTC. Ручний запуск обходить це денне обмеження активності. Доріжка будує згрупований звіт продуктивності Vitest для повного набору тестів, дозволяє Codex робити лише невеликі виправлення продуктивності тестів без втрати покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору тестів і відхиляє зміни, які зменшують базову кількість тестів, що проходять. Якщо в базовому стані є тести, що не проходять, Codex може виправляти лише очевидні збої, а після цього повний звіт має пройти, перш ніж щось буде закомічено. Коли `main` просувається далі до того, як bot push буде застосовано, доріжка перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; застарілі патчі з конфліктами пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну політику drop-sudo, що й docs agent. +Workflow `Test Performance Agent` — це event-driven смуга технічного обслуговування Codex +для повільних тестів. У нього немає окремого запуску за розкладом: +його може запустити успішний неботовий CI run push до `main`, але +він пропускається, якщо інший виклик через workflow-run уже виконався або виконується +цього дня за UTC. Ручний dispatch обходить це денне обмеження активності. +Смуга будує повний згрупований звіт продуктивності Vitest, дозволяє Codex +робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість +широких рефакторингів, потім повторно запускає повний звіт і відхиляє +зміни, які зменшують базову кількість тестів, що проходять. Якщо в базовому стані є тести зі збоями, +Codex може виправляти лише очевидні збої, а повний звіт після роботи агента +має пройти, перш ніж щось буде закомічено. Коли `main` просувається далі до того, +як bot push буде застосовано, смуга перебазовує перевірений патч, +повторно запускає `pnpm check:changed` і повторює push; +застарілі патчі з конфліктами пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб +дія Codex могла зберігати ту саму безпекову модель drop-sudo, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -32,72 +65,72 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Визначення змін лише в документації, змінених областей, змінених extensions і побудова CI manifest | Завжди для недрафтових push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для недрафтових push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory з npm | Завжди для недрафтових push і PR | -| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для недрафтових push і PR | -| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані downstream-артефакти | Зміни, релевантні Node | -| `checks-fast-core` | Швидкі Linux-доріжки коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні Node | -| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, релевантні Node | -| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extensions | Зміни, релевантні Node | -| `checks-node-core-test` | Шарди core Node tests, без channel, bundled, contract і extension-доріжок | Зміни, релевантні Node | -| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request із змінами в extensions | -| `check` | Шардований еквівалент головної локальної перевірки: prod types, lint, guards, test types і strict smoke | Зміни, релевантні Node | -| `check-additional` | Архітектурні, boundary, extension-surface guards, package-boundary і gateway-watch шарди | Зміни, релевантні Node | -| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка стартової пам’яті | Зміни, релевантні Node | -| `checks` | Верифікатор для channel tests на зібраних артефактах плюс сумісність Node 22 тільки для push | Зміни, релевантні Node | -| `check-docs` | Форматування docs, lint і перевірки битих посилань | Змінено docs | -| `skills-python` | Ruff + pytest для Skills на Python | Зміни, релевантні Python Skills | -| `checks-windows` | Специфічні для Windows тестові доріжки | Зміни, релевантні Windows | -| `macos-node` | Доріжка TypeScript-тестів на macOS із використанням спільних зібраних артефактів | Зміни, релевантні macOS | -| `macos-swift` | Swift lint, build і tests для застосунку macOS | Зміни, релевантні macOS | -| `android` | Android unit tests для обох flavor плюс одна debug APK build | Зміни, релевантні Android | -| `test-performance-agent` | Щоденна Codex-оптимізація повільних тестів після довіреної активності | Успіх Main CI або ручний запуск | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | +| `preflight` | Визначає зміни лише в документації, змінені межі, змінені extensions і будує маніфест CI | Завжди для push і PR не в draft | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для push і PR не в draft | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для push і PR не в draft | +| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для push і PR не в draft | +| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі смуги коректності Linux, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extension | Зміни, релевантні для Node | +| `checks-node-core-test` | Шарди основних Node-тестів, без channel, bundled, contract і extension-смуг | Зміни, релевантні для Node | +| `extension-fast` | Точкові тести лише для змінених bundled plugins | Pull request зі змінами в extension | +| `check` | Шардований еквівалент основної локальної перевірки: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Архітектурні, boundary, extension-surface guards, package-boundary і gateway-watch шарди | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke startup-memory | Зміни, релевантні для Node | +| `checks` | Перевіряльник для built-artifact channel tests плюс сумісність Node 22 лише для push | Зміни, релевантні для Node | +| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Змінено документацію | +| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | +| `checks-windows` | Специфічні для Windows тестові смуги | Зміни, релевантні для Windows | +| `macos-node` | Смуга тестів TypeScript на macOS із використанням спільних built artifacts | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, build і тести для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Модульні тести Android для обох flavor плюс одна збірка debug APK | Зміни, релевантні для Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх main CI або ручний dispatch | -## Порядок Fail-Fast +## Порядок fail-fast -Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запустяться дорогі: +Завдання впорядковані так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запускатимуться дорогі: -1. `preflight` вирішує, які доріжки взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих matrix-завдань для артефактів і платформ. -3. `build-artifacts` перекривається з швидкими Linux-доріжками, щоб downstream-споживачі могли стартувати, щойно буде готова спільна збірка. -4. Після цього розгалужуються важчі платформні та runtime-доріжки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише PR-ове `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які смуги взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються з помилкою без очікування важчих artifact- і platform-matrix-завдань. +3. `build-artifacts` виконується паралельно зі швидкими Linux-смугами, щоб downstream-споживачі могли стартувати, щойно спільна збірка готова. +4. Після цього розгалужуються важчі platform- і runtime-смуги: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише для PR `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка області знаходиться в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. -Редагування CI workflow перевіряє Node CI graph плюс linting workflow, але саме по собі не примушує запускати нативні збірки Windows, Android або macOS; ці платформні доріжки залишаються прив’язаними до змін у вихідному коді відповідних платформ. -Windows Node checks обмежені Windows-специфічними обгортками для process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями CI workflow, що запускають цю доріжку; непов’язані зміни у вихідному коді, plugin, install-smoke і зміни лише в тестах залишаються на Linux Node lanes, щоб не резервувати Windows worker із 16 vCPU для покриття, яке вже перевіряється звичайними test shards. -Окремий workflow `install-smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він ділить smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest у bundled plugin, а також поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише у вихідному коді bundled plugin, зміни лише в тестах і лише в docs не резервують Docker workers. Швидкий шлях один раз збирає root Dockerfile image, перевіряє CLI, запускає container gateway-network e2e, перевіряє bundled extension build arg і запускає обмежений Docker profile bundled-plugin з тайм-аутом команди 120 секунд. Повний шлях зберігає QR package install і покриття installer Docker/update для нічних запусків за розкладом, ручних запусків, workflow-call release checks і pull request, які справді зачіпають installer/package/Docker surface. Push у `main`, включно з merge commit, не примушують повний шлях; коли логіка 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 image і один спільний built-app image з `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke lanes паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте стандартний паралелізм основного пулу 8 через `OPENCLAW_DOCKER_ALL_PARALLELISM` і паралелізм tail-пулу 8, чутливого до провайдерів, через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Запуски доріжок за замовчуванням розносяться на 2 секунди, щоб уникати локальних бур створення в Docker daemon; перевизначте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегатор за замовчуванням припиняє планувати нові pooled lanes після першої помилки, а кожна доріжка має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Повторно використовуваний live/E2E workflow віддзеркалює шаблон спільного image, збираючи й пушачи один Docker E2E image у GHCR з SHA-тегом перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний Docker suite релізного шляху. Повна матриця bundled update/channel лишається manual/full-suite, оскільки виконує повторні справжні проходи npm update і doctor repair. +Логіка меж знаходиться в `scripts/ci-changed-scope.mjs` і покрита модульними тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці platform-смуги лишаються прив’язаними до змін у платформенному коді. +Перевірки Windows Node прив’язані до специфічних для Windows обгорток process/path, npm/pnpm/UI runner helpers, конфігурації package manager і поверхонь workflow CI, які запускають цю смугу; не пов’язані зміни вихідного коду, plugin, install-smoke і лише тестів залишаються на Linux Node-смугах, щоб не резервувати Windows worker на 16 vCPU заради покриття, яке вже проходить у звичайних test shards. +Окремий workflow `install-smoke` повторно використовує той самий сценарій визначення меж через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest bundled plugin і поверхонь core plugin/channel/gateway/Plugin SDK, які використовують Docker smoke-завдання. Зміни лише у вихідному коді bundled plugin, лише в тестах і лише в документації не резервують Docker workers. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд. Повний шлях зберігає покриття 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-орієнтовані Dockerfile. Локальний агрегат `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke lanes із зваженим планувальником і `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте типову кількість слотів основного пулу 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM` і кількість слотів tail-pool 10, чутливих до provider, через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження важких смуг за замовчуванням становлять `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`, щоб смуги npm install і multi-service не перевантажували Docker, поки легші смуги все ще заповнюють доступні слоти. Запуски смуг за замовчуванням розносяться на 2 секунди, щоб уникати локальних штормів створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегат за замовчуванням припиняє планування нових pooled lanes після першої помилки, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Повторно використовуваний workflow live/E2E віддзеркалює шаблон спільного image, збираючи й публікуючи один Docker E2E image з тегом SHA у GHCR перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker-набір релізного шляху. Повна матриця bundled update/channel залишається ручною/повною, оскільки виконує повторні справжні проходи `npm update` і `doctor repair`. -Локальна логіка changed-lane знаходиться в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Ця локальна перевірка суворіша щодо архітектурних меж, ніж широка платформна область CI: зміни в core production запускають core prod typecheck плюс core tests, зміни лише в core tests запускають лише core test typecheck/tests, зміни в extension production запускають extension prod typecheck плюс extension tests, а зміни лише в extension tests запускають лише extension test typecheck/tests. Зміни в публічному Plugin SDK або plugin-contract розширюють валідацію на extensions, тому що extensions залежать від цих core contracts. Зміни лише в release metadata зі збільшенням версії запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно переводять перевірку на всі доріжки. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Ця локальна перевірка суворіше ставиться до архітектурних меж, ніж широка platform-scope CI: зміни в core production запускають typecheck для core prod плюс тести core, зміни лише в тестах core запускають лише typecheck/тести для core test, зміни в extension production запускають typecheck для extension prod плюс тести extension, а зміни лише в тестах extension запускають лише typecheck/тести для extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extension, оскільки extension залежать від цих контрактів core. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config переходять у безпечний режим і запускають усі смуги. -Під час push матриця `checks` додає доріжку `compat-node22`, яка запускається лише для push. Для pull request цю доріжку пропущено, і матриця залишається зосередженою на звичайних test/channel lanes. +Для push матриця `checks` додає смугу `compat-node22`, що виконується лише для push. Для pull request ця смуга пропускається, і матриця зосереджується на звичайних test/channel-смугах. -Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts запускаються як три зважені шарди, bundled plugin tests балансуються між шістьма workers для extensions, малі core unit lanes поєднуються в пари, auto-reply запускається як три збалансовані workers замість шести крихітних workers, а agentic gateway/plugin configs розподіляються між наявними source-only agentic Node jobs замість очікування на зібрані артефакти. Широкі browser-, QA-, media- та інші plugin tests використовують свої спеціалізовані конфігурації Vitest замість спільного універсального набору plugin. Завдання shard для extensions запускають до двох груп конфігурацій plugin одночасно з одним worker Vitest на групу та більшим heap Node, щоб batch-набори plugin з важкими import не створювали додаткових CI jobs. Широка доріжка agents використовує спільний file-parallel scheduler Vitest, оскільки в ній домінують import/планування, а не один окремий повільний тестовий файл. `runtime-config` запускається разом із шардом infra core-runtime, щоб спільний runtime-shard не залишався найдовшим. `check-additional` тримає разом compile/canary-роботи для package-boundary і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guards паралельно в межах одного job. Gateway watch, channel tests і shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи свої старі назви checks як легкі jobs-верифікатори й водночас уникаючи двох додаткових Blacksmith workers і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його доріжка unit-test однаково компілює цей flavor із прапорцями SMS/call-log у BuildConfig, водночас уникаючи дубльованого job пакування debug APK на кожен Android-релевантний push. -`extension-fast` доступний лише для PR, оскільки push-запуски вже виконують повні shard-и bundled plugin. Це зберігає зворотний зв’язок щодо змінених plugin для рев’ю, не резервуючи додатковий Blacksmith worker у `main` для покриття, яке вже є в `checks-node-extensions`. +Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим і не резервувало зайві runner-и: channel contracts виконуються як три зважені шарди, тести bundled plugin балансуються між шістьма workers для extension, невеликі core unit-смуги об’єднані попарно, auto-reply працює на трьох збалансованих workers замість шести маленьких, а конфігурації agentic gateway/plugin розподілені між наявними source-only agentic Node-завданнями замість очікування built artifacts. Широкі browser-, QA-, media- та різні plugin-тести використовують свої виділені конфігурації Vitest замість спільного catch-all для plugin. Завдання шардованих extension запускають до двох груп конфігурацій plugin одночасно з одним worker Vitest на групу та збільшеною купою Node, щоб партії plugin з великою кількістю імпортів не створювали додаткові CI-завдання. Широка смуга agents використовує спільний file-parallel scheduler Vitest, оскільки в ній домінують імпорти/планування, а не один окремий повільний тестовий файл. `runtime-config` виконується разом із шардом infra core-runtime, щоб спільний runtime-shard не тягнув хвіст. `check-additional` тримає разом package-boundary compile/canary-роботи й відокремлює архітектуру runtime topology від покриття gateway watch; шард boundary guard запускає свої невеликі незалежні guards паралельно всередині одного завдання. Gateway watch, channel tests і шард core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі імена перевірок як легкі verifier-завдання та уникаючи двох додаткових workers Blacksmith і другої черги споживачів artifact. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає debug APK для Play. Для third-party flavor немає окремого source set або manifest; його смуга unit-тестів усе одно компілює цей flavor з прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK при кожному push, релевантному для Android. +`extension-fast` призначено лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це дає зворотний зв’язок для changed-plugin під час рев’ю, не резервуючи додатковий worker Blacksmith на `main` для покриття, яке вже є в `checks-node-extensions`. -GitHub може позначати витіснені jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані shard-checks використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був витіснений. -Ключ concurrency CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски `main`. +GitHub може позначати витіснені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший run для того самого ref також не завершується збоєм. Агреговані шардовані перевірки використовують `!cancelled() && always()`, тому вони все ще повідомляють про звичайні збої шардів, але не стають у чергу після того, як увесь workflow уже був витіснений. +Ключ concurrency CI має версію (`CI-v7-*`), тож zombie на боці GitHub у старій queue group не може безкінечно блокувати новіші запуски main. ## Runner-и -| Runner | Завдання | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, shard-и `check`, окрім lint, shard-и й агрегати `check-additional`, aggregate-верифікатори Node tests, перевірки docs, 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 tests, shard-и bundled plugin tests, `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`; forks переходять на `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; forks переходять на `macos-latest` | +| Runner | Завдання | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, шарди `check` окрім lint, шарди й агрегати `check-additional`, aggregate verifiers тестів 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`; форки переходять на `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки переходять на `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD pnpm check:changed # розумна локальна перевірка: changed typecheck/lint/tests за boundary lane -pnpm check # швидка локальна перевірка: production tsgo + шардований lint + паралельні fast guards +pnpm check # швидка локальна перевірка: production tsgo + шардований lint + паралельні швидкі guards pnpm check:test-types pnpm check:timed # та сама перевірка з таймінгами для кожного етапу pnpm build:strict-smoke @@ -106,10 +139,10 @@ pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування docs + lint + биті посилання -pnpm build # зібрати dist, коли важливі CI-доріжки artifact/build-smoke -node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші jobs -node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI +pnpm check:docs # форматування документації + lint + зламані посилання +pnpm build # збірка dist, коли важливі смуги CI artifact/build-smoke +node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші завдання +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 ``` diff --git a/docs/uk/cli/infer.md b/docs/uk/cli/infer.md index fa3db8b7b..92ad2f79a 100644 --- a/docs/uk/cli/infer.md +++ b/docs/uk/cli/infer.md @@ -1,21 +1,21 @@ --- read_when: - Додавання або змінення команд `openclaw infer` - - Проєктування стабільної автоматизації headless-можливостей -summary: CLI з підходом infer-first для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом і ембедингами на базі провайдерів -title: CLI для інференсу + - Проєктування стабільної автоматизації можливостей без графічного інтерфейсу +summary: CLI з infer-first для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом та ембедингами на основі провайдера +title: CLI для inference x-i18n: - generated_at: "2026-04-24T03:15:20Z" + generated_at: "2026-04-24T19:51:03Z" model: gpt-5.4 provider: openai - source_hash: 5a5a2ca9da4b5c26fbd61c271801d50a3d533bd4cc8430aa71f65e2cdc4fdee6 + source_hash: b2127deec34c5cf8431035c6cc02fc4acb35e4a107f70de0c7654fe4806c0d43 source_path: cli/infer.md workflow: 15 --- -`openclaw infer` — це канонічна headless-поверхня для робочих процесів інференсу на базі провайдерів. +`openclaw infer` — це канонічна headless-поверхня для робочих процесів inference на основі провайдера. -Вона навмисно відкриває сімейства можливостей, а не сирі імена RPC Gateway і не сирі id інструментів агентів. +Вона навмисно надає сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агентів. ## Перетворіть infer на skill @@ -28,12 +28,12 @@ Focus on model runs, image generation, video generation, audio transcription, TT Хороший skill на основі infer має: -- зіставляти поширені наміри користувача з правильними підкомандами infer +- зіставляти поширені наміри користувача з правильним підкомандним викликом infer - містити кілька канонічних прикладів infer для робочих процесів, які він охоплює -- віддавати перевагу `openclaw infer ...` у прикладах і рекомендаціях -- уникати повторного документування всієї поверхні infer в тілі skill +- надавати перевагу `openclaw infer ...` у прикладах і рекомендаціях +- уникати повторного документування всієї поверхні infer всередині тіла skill -Типове покриття skill, зосередженого на infer: +Типове охоплення skill, зосередженого на infer: - `openclaw infer model run` - `openclaw infer image generate` @@ -44,16 +44,18 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## Навіщо використовувати infer -`openclaw infer` надає один узгоджений CLI для завдань інференсу на базі провайдерів в OpenClaw. +`openclaw infer` надає єдиний узгоджений CLI для завдань inference на основі провайдера всередині OpenClaw. Переваги: -- Використовуйте провайдерів і моделі, уже налаштовані в OpenClaw, замість створення окремих одноразових обгорток для кожного бекенда. -- Тримайте робочі процеси для моделей, зображень, транскрибування аудіо, TTS, відео, вебу та ембедингів в одному дереві команд. +- Використовуйте провайдерів і моделі, уже налаштовані в OpenClaw, замість підключення одноразових обгорток для кожного бекенда. +- Тримайте робочі процеси з моделями, зображеннями, транскрипцією аудіо, TTS, відео, вебом та ембедингами в межах одного дерева команд. - Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентами. -- Віддавайте перевагу власній поверхні OpenClaw, коли завдання по суті є «виконати інференс». +- Надавайте перевагу першочерговій поверхні OpenClaw, коли завдання по суті полягає в тому, щоб «запустити inference». - Використовуйте звичайний локальний шлях без потреби в Gateway для більшості команд infer. +Для наскрізних перевірок провайдерів віддавайте перевагу `openclaw infer ...`, щойно пройдено тести провайдера нижчого рівня. Це перевіряє постачений CLI, завантаження конфігурації, визначення агента за замовчуванням, активацію вбудованих plugin, відновлення залежностей середовища виконання та спільне середовище виконання можливостей до того, як буде зроблено запит до провайдера. + ## Дерево команд ```text @@ -107,15 +109,15 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## Поширені завдання -Ця таблиця зіставляє поширені завдання інференсу з відповідною командою infer. +Ця таблиця зіставляє поширені завдання inference з відповідною командою infer. | Завдання | Команда | Примітки | | ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | -| Запустити текстовий/модельний запит | `openclaw infer model run --prompt "..." --json` | Типово використовує звичайний локальний шлях | -| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, якщо починаєте з наявного файлу | -| Описати файл зображення | `openclaw infer image describe --file ./image.png --json` | `--model` має бути зображувально-здатною `` | +| Запустити текстовий/модельний запит | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях | +| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, якщо починаєте з наявного файла | +| Описати файл зображення | `openclaw infer image describe --file ./image.png --json` | `--model` має бути зображувально-сумісним `` | | Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `` | -| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтована на gateway | +| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтований на Gateway | | Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | | | Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `` | | Шукати у вебі | `openclaw infer web search --query "..." --json` | | @@ -124,18 +126,18 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## Поведінка -- `openclaw infer ...` — це основна CLI-поверхня для цих робочих процесів. +- `openclaw infer ...` — основна поверхня CLI для цих робочих процесів. - Використовуйте `--json`, коли вивід споживатиметься іншою командою або скриптом. - Використовуйте `--provider` або `--model provider/model`, коли потрібен конкретний бекенд. -- Для `image describe`, `audio transcribe` і `video describe` `--model` має використовувати форму ``. -- Для `image describe` явний `--model` запускає цей provider/model безпосередньо. Модель має підтримувати роботу із зображеннями в каталозі моделей або конфігурації провайдера. `codex/` запускає обмежений turn розуміння зображень через сервер застосунку Codex; `openai-codex/` використовує шлях провайдера OpenAI Codex OAuth. -- Команди безстанового виконання типово працюють локально. -- Команди стану, керованого Gateway, типово працюють через gateway. +- Для `image describe`, `audio transcribe` і `video describe` параметр `--model` має використовувати форму ``. +- Для `image describe` явний `--model` запускає цей провайдер/модель безпосередньо. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/` запускає обмежений хід розуміння зображень Codex app-server; `openai-codex/` використовує шлях провайдера OpenAI Codex OAuth. +- Команди stateless-виконання за замовчуванням використовують локальний режим. +- Команди стану, керованого Gateway, за замовчуванням використовують Gateway. - Звичайний локальний шлях не вимагає, щоб Gateway був запущений. ## Model -Використовуйте `model` для текстового інференсу на базі провайдерів та перевірки моделей/провайдерів. +Використовуйте `model` для текстового inference на основі провайдера та перевірки моделей/провайдерів. ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json @@ -146,7 +148,7 @@ openclaw infer model inspect --name gpt-5.5 --json Примітки: -- `model run` повторно використовує середовище виконання агента, тому перевизначення provider/model поводяться так само, як у звичайному виконанні агента. +- `model run` повторно використовує runtime агента, тож перевизначення провайдера/моделі поводяться як під час звичайного виконання агента. - `model auth login`, `model auth logout` і `model auth status` керують збереженим станом автентифікації провайдера. ## Image @@ -164,12 +166,26 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j Примітки: - Використовуйте `image edit`, якщо починаєте з наявних вхідних файлів. -- Для `image describe` `--model` має бути зображувально-здатною ``. -- Для локальних моделей Ollama з підтримкою зору спочатку завантажте модель і встановіть `OLLAMA_API_KEY` у будь-яке значення-заглушку, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description). +- Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень можна виявити, які налаштовані, вибрані та які можливості генерації/редагування надає кожен провайдер. +- Використовуйте `image generate --model --json` як найвужчу живу CLI-перевірку для змін генерації зображень. Приклад: + + ```bash + openclaw infer image providers --json + openclaw infer image generate \ + --model google/gemini-3.1-flash-image-preview \ + --prompt "Minimal flat test image: one blue square on a white background, no text." \ + --output ./openclaw-infer-image-smoke.png \ + --json + ``` + + JSON-відповідь повідомляє `ok`, `provider`, `model`, `attempts` і шляхи записаних файлів. Якщо задано `--output`, фінальне розширення може відповідати MIME-типу, повернутому провайдером. + +- Для `image describe` параметр `--model` має бути зображувально-сумісним ``. +- Для локальних моделей Ollama з підтримкою візуального аналізу спочатку завантажте модель і встановіть `OLLAMA_API_KEY` у будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description). ## Audio -Використовуйте `audio` для транскрибування файлів. +Використовуйте `audio` для транскрипції файлів. ```bash openclaw infer audio transcribe --file ./memo.m4a --json @@ -179,12 +195,12 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso Примітки: -- `audio transcribe` призначена для транскрибування файлів, а не для керування сесіями в реальному часі. +- `audio transcribe` призначено для транскрипції файлів, а не для керування сесіями в реальному часі. - `--model` має бути ``. ## TTS -Використовуйте `tts` для синтезу мовлення та стану TTS-провайдера. +Використовуйте `tts` для синтезу мовлення та стану провайдера TTS. ```bash openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json @@ -195,7 +211,7 @@ openclaw infer tts status --json Примітки: -- `tts status` типово використовує gateway, оскільки відображає стан TTS, керований gateway. +- `tts status` за замовчуванням використовує Gateway, оскільки відображає стан TTS, керований Gateway. - Використовуйте `tts providers`, `tts voices` і `tts set-provider` для перевірки та налаштування поведінки TTS. ## Video @@ -211,11 +227,11 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js Примітки: -- Для `video describe` `--model` має бути ``. +- Для `video describe` параметр `--model` має бути ``. ## Web -Використовуйте `web` для робочих процесів пошуку та отримання вмісту. +Використовуйте `web` для робочих процесів пошуку та отримання. ```bash openclaw infer web search --query "OpenClaw docs" --json @@ -240,7 +256,7 @@ openclaw infer embedding providers --json ## Вивід JSON -Команди infer нормалізують вивід JSON у спільну оболонку: +Команди infer нормалізують вивід JSON у спільній оболонці: ```json { @@ -265,21 +281,23 @@ openclaw infer embedding providers --json - `outputs` - `error` -## Типові помилки +Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте `path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві для автоматизації замість аналізу людиночитаного stdout. + +## Поширені помилки ```bash -# Bad +# Погано openclaw infer media image generate --prompt "friendly lobster" -# Good +# Добре openclaw infer image generate --prompt "friendly lobster" ``` ```bash -# Bad +# Погано openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json -# Good +# Добре openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json ``` diff --git a/docs/uk/cli/onboard.md b/docs/uk/cli/onboard.md index 548a3c862..7684f4cc6 100644 --- a/docs/uk/cli/onboard.md +++ b/docs/uk/cli/onboard.md @@ -1,28 +1,28 @@ --- read_when: - - Ви хочете покрокове налаштування для Gateway, робочого простору, автентифікації, каналів і Skills -summary: Довідник CLI для `openclaw onboard` (інтерактивне онбординг) -title: Онбординг + - Ви хочете покрокове налаштування Gateway, робочого простору, автентифікації, каналів і Skills +summary: Довідник CLI для `openclaw onboard` (інтерактивне налаштування) +title: Налаштування x-i18n: - generated_at: "2026-04-24T06:45:23Z" + generated_at: "2026-04-24T19:50:59Z" model: gpt-5.4 provider: openai - source_hash: c1959ad7014b891230e497a2e0ab494ba316090c81629f25b8147614b694ead5 + source_hash: 2b09191f95ff6012c340976dbae1045d24b736a9e9e06fc4e15e1f15785f20f5 source_path: cli/onboard.md workflow: 15 --- # `openclaw onboard` -Інтерактивний онбординг для налаштування локального або віддаленого Gateway. +Інтерактивне налаштування для локального або віддаленого налаштування Gateway. ## Пов’язані посібники -- Центр онбордингу CLI: [Онбординг (CLI)](/uk/start/wizard) -- Огляд онбордингу: [Огляд онбордингу](/uk/start/onboarding-overview) -- Довідник CLI онбордингу: [Довідник з налаштування CLI](/uk/start/wizard-cli-reference) +- Центр налаштування CLI: [Налаштування (CLI)](/uk/start/wizard) +- Огляд налаштування: [Огляд налаштування](/uk/start/onboarding-overview) +- Довідник налаштування CLI: [Довідник налаштування CLI](/uk/start/wizard-cli-reference) - Автоматизація CLI: [Автоматизація CLI](/uk/start/wizard-cli-automation) -- Онбординг macOS: [Онбординг (додаток macOS)](/uk/start/onboarding) +- Налаштування macOS: [Налаштування (застосунок macOS)](/uk/start/onboarding) ## Приклади @@ -30,15 +30,16 @@ x-i18n: openclaw onboard openclaw onboard --flow quickstart openclaw onboard --flow manual +openclaw onboard --skip-bootstrap openclaw onboard --mode remote --remote-url wss://gateway-host:18789 ``` -Для цілей приватної мережі `ws://` у відкритому тексті (лише для довірених мереж) встановіть -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у середовищі процесу онбордингу. -Еквівалента `openclaw.json` для цього аварійного обходу -клієнтського транспорту не існує. +Для цілей приватної мережі з відкритим текстом `ws://` (лише для довірених мереж) встановіть +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у середовищі процесу налаштування. +Для цього клієнтського аварійного обходу транспортного рівня немає еквівалента +`openclaw.json`. -Некерований користувачем custom provider: +Некастомний провайдер у неінтерактивному режимі: ```bash openclaw onboard --non-interactive \ @@ -50,7 +51,7 @@ openclaw onboard --non-interactive \ --custom-compatibility openai ``` -`--custom-api-key` є необов’язковим у неінтерактивному режимі. Якщо його не вказано, онбординг перевіряє `CUSTOM_API_KEY`. +`--custom-api-key` необов’язковий у неінтерактивному режимі. Якщо його пропущено, налаштування перевіряє `CUSTOM_API_KEY`. LM Studio також підтримує прапорець ключа, специфічний для провайдера, у неінтерактивному режимі: @@ -63,7 +64,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -Неінтерактивний Ollama: +Некастомний Ollama у неінтерактивному режимі: ```bash openclaw onboard --non-interactive \ @@ -73,7 +74,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -Для `--custom-base-url` типовим значенням є `http://127.0.0.1:11434`. `--custom-model-id` є необов’язковим; якщо його не вказано, онбординг використовує рекомендовані Ollama значення за замовчуванням. Хмарні ідентифікатори моделей, як-от `kimi-k2.5:cloud`, тут також працюють. +`--custom-base-url` типово має значення `http://127.0.0.1:11434`. `--custom-model-id` необов’язковий; якщо його пропущено, налаштування використовує рекомендовані типові значення Ollama. Ідентифікатори хмарних моделей, такі як `kimi-k2.5:cloud`, також тут працюють. Зберігайте ключі провайдера як посилання, а не як відкритий текст: @@ -84,26 +85,26 @@ openclaw onboard --non-interactive \ --accept-risk ``` -З `--secret-input-mode ref` онбординг записує посилання, що спираються на змінні середовища, замість значень ключів у відкритому тексті. -Для провайдерів, що спираються на auth-profile, це записує записи `keyRef`; для custom providers це записує `models.providers..apiKey` як env ref (наприклад, `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). +З `--secret-input-mode ref` налаштування записує посилання на основі env замість значень ключів у відкритому тексті. +Для провайдерів на основі профілю автентифікації це записує записи `keyRef`; для кастомних провайдерів це записує `models.providers..apiKey` як env-посилання (наприклад, `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`). Контракт неінтерактивного режиму `ref`: -- Встановіть env var провайдера в середовищі процесу онбордингу (наприклад, `OPENAI_API_KEY`). -- Не передавайте вбудовані прапорці ключів (наприклад, `--openai-api-key`), якщо цю env var також не встановлено. -- Якщо прапорець вбудованого ключа передано без обов’язкової env var, онбординг негайно завершується з підказками. +- Встановіть змінну середовища провайдера в середовищі процесу налаштування (наприклад, `OPENAI_API_KEY`). +- Не передавайте вбудовані прапорці ключа (наприклад, `--openai-api-key`), якщо цю змінну середовища також не встановлено. +- Якщо вбудований прапорець ключа передано без потрібної змінної середовища, налаштування швидко завершується з повідомленням-підказкою. Параметри токена Gateway у неінтерактивному режимі: - `--gateway-auth token --gateway-token ` зберігає токен у відкритому тексті. - `--gateway-auth token --gateway-token-ref-env ` зберігає `gateway.auth.token` як env SecretRef. -- `--gateway-token` і `--gateway-token-ref-env` є взаємовиключними. -- `--gateway-token-ref-env` потребує непорожню env var у середовищі процесу онбордингу. -- З `--install-daemon`, коли автентифікація токеном потребує токена, токени Gateway, керовані через SecretRef, проходять перевірку, але не зберігаються як розгорнутий відкритий текст у метаданих середовища сервісу supervisor. -- З `--install-daemon`, якщо режим токена потребує токена, а налаштований SecretRef токена не розв’язано, онбординг завершується за принципом fail-closed із вказівками щодо виправлення. -- З `--install-daemon`, якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, онбординг блокує встановлення, доки режим не буде явно задано. -- Локальний онбординг записує `gateway.mode="local"` у конфігурацію. Якщо в подальшому у файлі конфігурації бракує `gateway.mode`, розглядайте це як пошкодження конфігурації або неповне ручне редагування, а не як коректне скорочення для локального режиму. -- `--allow-unconfigured` — це окремий аварійний обхід для середовища виконання Gateway. Це не означає, що онбординг може пропустити `gateway.mode`. +- `--gateway-token` і `--gateway-token-ref-env` взаємовиключні. +- `--gateway-token-ref-env` вимагає непорожньої змінної середовища в середовищі процесу налаштування. +- З `--install-daemon`, коли автентифікація токеном вимагає токен, токени Gateway під керуванням SecretRef перевіряються, але не зберігаються як розв’язаний відкритий текст у метаданих середовища служби supervisor. +- З `--install-daemon`, якщо режим токена вимагає токен і налаштований SecretRef токена не розв’язується, налаштування завершується в закритому режимі з підказками щодо усунення проблеми. +- З `--install-daemon`, якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, налаштування блокує встановлення, доки режим не буде встановлено явно. +- Локальне налаштування записує `gateway.mode="local"` у конфігурацію. Якщо в пізнішому файлі конфігурації бракує `gateway.mode`, вважайте це пошкодженням конфігурації або неповним ручним редагуванням, а не дійсним скороченням для локального режиму. +- `--allow-unconfigured` — це окремий аварійний обхід часу виконання Gateway. Це не означає, що під час налаштування можна пропустити `gateway.mode`. Приклад: @@ -119,38 +120,39 @@ openclaw onboard --non-interactive \ Стан локального Gateway у неінтерактивному режимі: -- Якщо ви не передасте `--skip-health`, онбординг чекає на досяжний локальний Gateway, перш ніж успішно завершитися. -- `--install-daemon` спочатку запускає керований шлях встановлення Gateway. Без нього у вас уже має працювати локальний Gateway, наприклад `openclaw gateway run`. -- Якщо вам в автоматизації потрібні лише записи конфігурації/робочого простору/bootstrap, використовуйте `--skip-health`. -- У native Windows `--install-daemon` спочатку намагається використати Scheduled Tasks, а якщо створення завдання заборонене — переходить до елемента входу користувача у теці Startup. +- Якщо не передано `--skip-health`, налаштування чекає на доступний локальний Gateway, перш ніж успішно завершитися. +- `--install-daemon` спочатку запускає шлях керованого встановлення Gateway. Без нього у вас уже має працювати локальний Gateway, наприклад `openclaw gateway run`. +- Якщо в автоматизації вам потрібні лише записи конфігурації/робочого простору/bootstrap, використовуйте `--skip-health`. +- Якщо ви самостійно керуєте файлами робочого простору, передайте `--skip-bootstrap`, щоб установити `agents.defaults.skipBootstrap: true` і пропустити створення `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` і `BOOTSTRAP.md`. +- У native Windows `--install-daemon` спочатку намагається використати Scheduled Tasks і переходить до елемента входу per-user у папці Startup, якщо створення завдання заборонено. -Поведінка інтерактивного онбордингу з режимом посилань: +Поведінка інтерактивного налаштування в режимі посилань: -- Коли буде запит, виберіть **Use secret reference**. -- Потім виберіть один із варіантів: +- Коли буде запит, виберіть **Використати посилання на секрет**. +- Потім виберіть одне з двох: - Змінна середовища - Налаштований провайдер секретів (`file` або `exec`) -- Перед збереженням посилання онбординг виконує швидку попередню перевірку. - - Якщо перевірка не проходить, онбординг показує помилку й дає змогу повторити спробу. +- Перед збереженням посилання налаштування виконує швидку перевірку preflight. + - Якщо перевірка не пройде, налаштування покаже помилку й дозволить повторити спробу. -Вибір endpoint для Z.AI у неінтерактивному режимі: +Варіанти кінцевих точок Z.AI у неінтерактивному режимі: -Примітка: `--auth-choice zai-api-key` тепер автоматично визначає найкращий endpoint Z.AI для вашого ключа (надає перевагу загальному API з `zai/glm-5.1`). -Якщо вам конкретно потрібні endpoint плану GLM Coding, виберіть `zai-coding-global` або `zai-coding-cn`. +Примітка: `--auth-choice zai-api-key` тепер автоматично визначає найкращу кінцеву точку Z.AI для вашого ключа (надає перевагу загальному API з `zai/glm-5.1`). +Якщо вам конкретно потрібні кінцеві точки GLM Coding Plan, виберіть `zai-coding-global` або `zai-coding-cn`. ```bash -# Вибір endpoint без запиту +# Вибір кінцевої точки без запитів openclaw onboard --non-interactive \ --auth-choice zai-coding-global \ --zai-api-key "$ZAI_API_KEY" -# Інші варіанти endpoint Z.AI: +# Інші варіанти кінцевих точок Z.AI: # --auth-choice zai-coding-cn # --auth-choice zai-global # --auth-choice zai-cn ``` -Неінтерактивний приклад Mistral: +Приклад Mistral у неінтерактивному режимі: ```bash openclaw onboard --non-interactive \ @@ -162,20 +164,23 @@ openclaw onboard --non-interactive \ - `quickstart`: мінімум запитів, автоматично генерує токен Gateway. - `manual`: повні запити для порту/bind/auth (псевдонім `advanced`). -- Коли вибір автентифікації передбачає пріоритетного провайдера, онбординг попередньо фільтрує засоби вибору default-model і allowlist за цим провайдером. Для Volcengine і BytePlus це також охоплює варіанти coding-plan +- Коли вибір автентифікації передбачає бажаного провайдера, налаштування попередньо фільтрує + засоби вибору моделі за замовчуванням і allowlist до цього провайдера. Для Volcengine і + BytePlus це також охоплює варіанти coding-plan (`volcengine-plan/*`, `byteplus-plan/*`). -- Якщо фільтр пріоритетного провайдера поки не дає жодної завантаженої моделі, онбординг повертається до нефільтрованого каталогу, а не залишає список вибору порожнім. -- На етапі web-search деякі провайдери можуть запускати додаткові запити, специфічні для провайдера: +- Якщо фільтр бажаного провайдера ще не дає жодної завантаженої моделі, + налаштування повертається до нефільтрованого каталогу замість того, щоб залишити засіб вибору порожнім. +- На кроці web-search деякі провайдери можуть запускати додаткові запити, специфічні для провайдера: - **Grok** може запропонувати необов’язкове налаштування `x_search` з тим самим `XAI_API_KEY` і вибором моделі `x_search`. - **Kimi** може запитати регіон Moonshot API (`api.moonshot.ai` чи `api.moonshot.cn`) і типову модель web-search Kimi. -- Поведінка області DM у локальному онбордингу: [Довідник з налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals). +- Поведінка області DM для локального налаштування: [Довідник налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals). - Найшвидший перший чат: `openclaw dashboard` (Control UI, без налаштування каналів). -- Custom Provider: підключайте будь-який endpoint, сумісний з OpenAI або Anthropic, - включно з розміщеними провайдерами, яких немає у списку. Використовуйте Unknown для автовизначення. +- Кастомний провайдер: підключіть будь-яку кінцеву точку, сумісну з OpenAI або Anthropic, + зокрема хостингових провайдерів, яких немає в списку. Використовуйте Unknown для автовизначення. -## Поширені подальші команди +## Поширені команди після налаштування ```bash openclaw configure @@ -183,5 +188,5 @@ openclaw agents add ``` -`--json` не означає неінтерактивний режим. Для сценаріїв використовуйте `--non-interactive`. +`--json` не означає неінтерактивний режим. Для скриптів використовуйте `--non-interactive`. diff --git a/docs/uk/concepts/agent-workspace.md b/docs/uk/concepts/agent-workspace.md index bd54b2c46..27222fbdf 100644 --- a/docs/uk/concepts/agent-workspace.md +++ b/docs/uk/concepts/agent-workspace.md @@ -1,88 +1,92 @@ --- read_when: - - Вам потрібно пояснити робочий простір агента або його структуру файлів + - Вам потрібно пояснити робочий простір агента або структуру його файлів - Ви хочете створити резервну копію або перенести робочий простір агента summary: 'Робочий простір агента: розташування, структура та стратегія резервного копіювання' title: Робочий простір агента x-i18n: - generated_at: "2026-04-23T22:57:57Z" + generated_at: "2026-04-24T19:51:01Z" model: gpt-5.4 provider: openai - source_hash: d6441991b5f9f71b13b2423d3c36b688a2d7d96386381e610a525aaccd55c9bf + source_hash: 51f9531dbd0f7d0c297f448a5e37f413bae48d75068f15ac88b6fdf7f153c974 source_path: concepts/agent-workspace.md workflow: 15 --- -Робочий простір — це дім агента. Це єдина робоча директорія, яка використовується -для файлових інструментів і для контексту робочого простору. Зберігайте його приватним і ставтеся до нього як до пам’яті. +Робочий простір — це домівка агента. Це єдина робоча директорія, яка використовується для +інструментів роботи з файлами та для контексту робочого простору. Зберігайте його приватним і сприймайте як пам’ять. Це окремо від `~/.openclaw/`, де зберігаються конфігурація, облікові дані та -сесії. +сеанси. -**Важливо:** робочий простір — це **типовий cwd**, а не жорстка пісочниця. Інструменти -розв’язують відносні шляхи відносно робочого простору, але абсолютні шляхи все ще можуть звертатися -до інших місць на хості, якщо не ввімкнено sandboxing. Якщо вам потрібна ізоляція, використовуйте -[`agents.defaults.sandbox`](/uk/gateway/sandboxing) (та/або конфігурацію пісочниці для окремого агента). -Коли sandboxing увімкнено і `workspaceAccess` не дорівнює `"rw"`, інструменти працюють +**Важливо:** робочий простір — це **cwd за замовчуванням**, а не жорстка пісочниця. Інструменти +визначають відносні шляхи відносно робочого простору, але абсолютні шляхи все одно можуть дістатися +інших місць на хості, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте +[`agents.defaults.sandbox`](/uk/gateway/sandboxing) (і/або конфігурацію пісочниці для кожного агента). +Коли пісочницю ввімкнено і `workspaceAccess` не дорівнює `"rw"`, інструменти працюють усередині робочого простору пісочниці в `~/.openclaw/sandboxes`, а не у вашому робочому просторі хоста. -## Типове розташування +## Розташування за замовчуванням -- Типово: `~/.openclaw/workspace` -- Якщо встановлено `OPENCLAW_PROFILE` і він не дорівнює `"default"`, типовим значенням стає +- За замовчуванням: `~/.openclaw/workspace` +- Якщо `OPENCLAW_PROFILE` встановлено і це не `"default"`, розташування за замовчуванням стає `~/.openclaw/workspace-`. - Перевизначення в `~/.openclaw/openclaw.json`: ```json5 { - agent: { - workspace: "~/.openclaw/workspace", + agents: { + defaults: { + workspace: "~/.openclaw/workspace", + }, }, } ``` `openclaw onboard`, `openclaw configure` або `openclaw setup` створять -робочий простір і додадуть початкові bootstrap-файли, якщо їх бракує. -Копії початкових даних пісочниці приймають лише звичайні файли всередині робочого простору; псевдоніми symlink/hardlink, які ведуть за межі вихідного робочого простору, ігноруються. +робочий простір і додадуть початкові bootstrap-файли, якщо вони відсутні. +Початкові копії для пісочниці приймають лише звичайні файли всередині робочого простору; псевдоніми symlink/hardlink, +які вказують за межі вихідного робочого простору, ігноруються. -Якщо ви вже самі керуєте файлами робочого простору, можна вимкнути створення bootstrap-файлів: +Якщо ви вже самі керуєте файлами робочого простору, ви можете вимкнути створення bootstrap-файлів: ```json5 -{ agent: { skipBootstrap: true } } +{ agents: { defaults: { skipBootstrap: true } } } ``` ## Додаткові папки робочого простору -Старіші інсталяції могли створювати `~/openclaw`. Наявність кількох директорій -робочого простору може спричиняти плутанину з автентифікацією або розсинхронізацію стану, оскільки одночасно активний лише один робочий простір. +У старіших інсталяціях міг бути створений `~/openclaw`. Наявність кількох директорій робочого простору +може спричинити плутанину з автентифікацією або розходження стану, тому що водночас +активним є лише один робочий простір. -**Рекомендація:** залишайте лише один активний робочий простір. Якщо ви більше не використовуєте -додаткові папки, заархівуйте їх або перемістіть до кошика (наприклад `trash ~/openclaw`). +**Рекомендація:** залишайте один активний робочий простір. Якщо ви більше не використовуєте +додаткові папки, архівуйте їх або перемістіть до кошика (наприклад, `trash ~/openclaw`). Якщо ви навмисно зберігаєте кілька робочих просторів, переконайтеся, що `agents.defaults.workspace` вказує на активний. `openclaw doctor` попереджає, коли виявляє додаткові директорії робочого простору. -## Мапа файлів робочого простору (що означає кожен файл) +## Карта файлів робочого простору (що означає кожен файл) -Ось стандартні файли, які OpenClaw очікує всередині робочого простору: +Ось стандартні файли, які OpenClaw очікує побачити в робочому просторі: - `AGENTS.md` - - Робочі інструкції для агента та як він має використовувати пам’ять. - - Завантажується на початку кожної сесії. - - Добре підходить для правил, пріоритетів і деталей «як поводитися». + - Інструкції з роботи для агента і правила використання пам’яті. + - Завантажується на початку кожного сеансу. + - Добре підходить для правил, пріоритетів і деталей про те, "як поводитися". - `SOUL.md` - Персона, тон і межі. - - Завантажується в кожній сесії. - - Посібник: [SOUL.md Personality Guide](/uk/concepts/soul) + - Завантажується в кожному сеансі. + - Посібник: [Посібник із особистості SOUL.md](/uk/concepts/soul) - `USER.md` - Хто такий користувач і як до нього звертатися. - - Завантажується в кожній сесії. + - Завантажується в кожному сеансі. - `IDENTITY.md` - - Ім’я агента, вайб та емодзі. + - Ім’я агента, вайб і емодзі. - Створюється/оновлюється під час bootstrap-ритуалу. - `TOOLS.md` @@ -90,11 +94,11 @@ x-i18n: - Не керує доступністю інструментів; це лише рекомендації. - `HEARTBEAT.md` - - Необов’язковий невеликий чеклист для запусків Heartbeat. - - Робіть його коротким, щоб не витрачати токени. + - Необов’язковий короткий контрольний список для запусків Heartbeat. + - Тримайте його коротким, щоб не витрачати токени. - `BOOT.md` - - Необов’язковий стартовий чеклист, який автоматично запускається під час перезапуску Gateway (коли ввімкнено [внутрішні хуки](/uk/automation/hooks)). + - Необов’язковий стартовий контрольний список, який автоматично запускається під час перезапуску Gateway (коли ввімкнено [внутрішні хуки](/uk/automation/hooks)). - Тримайте його коротким; для вихідних надсилань використовуйте інструмент повідомлень. - `BOOTSTRAP.md` @@ -104,53 +108,52 @@ x-i18n: - `memory/YYYY-MM-DD.md` - Щоденний журнал пам’яті (один файл на день). - - Рекомендується читати сьогоднішній і вчорашній файли на початку сесії. + - Рекомендовано читати сьогоднішній і вчорашній файли на початку сеансу. - `MEMORY.md` (необов’язково) - - Кураторована довготривала пам’ять. - - Завантажуйте лише в основній приватній сесії (не в спільних/групових контекстах). + - Курована довготривала пам’ять. + - Завантажуйте лише в основному приватному сеансі (не в спільних/групових контекстах). -Див. [Пам’ять](/uk/concepts/memory), щоб дізнатися про робочий процес і автоматичне скидання пам’яті. +Див. [Пам’ять](/uk/concepts/memory) щодо процесу роботи та автоматичного скидання пам’яті. - `skills/` (необов’язково) - Skills, специфічні для цього робочого простору. - Розташування Skills із найвищим пріоритетом для цього робочого простору. - - Перевизначає Skills агента проєкту, особисті Skills агента, керовані Skills, вбудовані Skills і `skills.load.extraDirs`, коли назви збігаються. + - Перекриває Skills агента проєкту, особисті Skills агента, керовані Skills, вбудовані Skills і `skills.load.extraDirs`, якщо імена збігаються. - `canvas/` (необов’язково) - - Файли UI canvas для відображень вузлів (наприклад `canvas/index.html`). + - Файли інтерфейсу Canvas для відображення вузлів (наприклад, `canvas/index.html`). -Якщо бракує будь-якого bootstrap-файлу, OpenClaw додає до -сесії маркер «відсутній файл» і продовжує роботу. Великі bootstrap-файли обрізаються під час додавання; -налаштуйте ліміти через `agents.defaults.bootstrapMaxChars` (типово: 12000) і -`agents.defaults.bootstrapTotalMaxChars` (типово: 60000). -`openclaw setup` може відновити відсутні типові файли без перезапису наявних -файлів. +Якщо будь-який bootstrap-файл відсутній, OpenClaw додає в сеанс маркер "відсутнього файла" +і продовжує роботу. Великі bootstrap-файли обрізаються під час додавання; +ліміти можна налаштувати через `agents.defaults.bootstrapMaxChars` (за замовчуванням: 12000) і +`agents.defaults.bootstrapTotalMaxChars` (за замовчуванням: 60000). +`openclaw setup` може відновити відсутні типові файли, не перезаписуючи наявні. -## ЩО НЕ знаходиться в робочому просторі +## Чого НЕМАЄ в робочому просторі -Ці дані містяться в `~/.openclaw/` і їх НЕ слід комітити до репозиторію робочого простору: +Ці дані зберігаються в `~/.openclaw/` і їх НЕ слід комітити до репозиторію робочого простору: - `~/.openclaw/openclaw.json` (конфігурація) - `~/.openclaw/agents//agent/auth-profiles.json` (профілі автентифікації моделей: OAuth + API-ключі) -- `~/.openclaw/credentials/` (стан каналу/провайдера плюс дані імпорту застарілого OAuth) -- `~/.openclaw/agents//sessions/` (транскрипти сесій + метадані) +- `~/.openclaw/credentials/` (стан каналів/провайдерів, а також застарілі дані імпорту OAuth) +- `~/.openclaw/agents//sessions/` (транскрипти сеансів і метадані) - `~/.openclaw/skills/` (керовані Skills) -Якщо вам потрібно перенести сесії або конфігурацію, копіюйте їх окремо й не зберігайте -під контролем версій. +Якщо вам потрібно перенести сеанси або конфігурацію, копіюйте їх окремо й не +додавайте до системи контролю версій. ## Резервне копіювання через Git (рекомендовано, приватно) -Ставтеся до робочого простору як до приватної пам’яті. Помістіть його в **приватний** git-репозиторій, щоб -він був захищений резервною копією та доступний для відновлення. +Ставтеся до робочого простору як до приватної пам’яті. Помістіть його в **приватний** +git-репозиторій, щоб мати резервну копію і можливість відновлення. -Виконуйте ці кроки на машині, де працює Gateway (саме там розташований +Виконайте ці кроки на машині, де працює Gateway (саме там розташований робочий простір). ### 1) Ініціалізуйте репозиторій -Якщо git установлено, абсолютно нові робочі простори ініціалізуються автоматично. Якщо цей +Якщо встановлено git, абсолютно нові робочі простори ініціалізуються автоматично. Якщо цей робочий простір ще не є репозиторієм, виконайте: ```bash @@ -212,10 +215,10 @@ git push - Усього, що знаходиться в `~/.openclaw/`. - Сирих дампів чатів або чутливих вкладень. -Якщо вам усе ж потрібно зберігати чутливі посилання, використовуйте заповнювачі та тримайте справжній -секрет в іншому місці (менеджер паролів, змінні середовища або `~/.openclaw/`). +Якщо вам все ж потрібно зберігати чутливі посилання, використовуйте заповнювачі й зберігайте +справжній секрет в іншому місці (менеджер паролів, змінні середовища або `~/.openclaw/`). -Рекомендований початковий варіант `.gitignore`: +Пропонований початковий варіант `.gitignore`: ```gitignore .DS_Store @@ -227,21 +230,22 @@ git push ## Перенесення робочого простору на нову машину -1. Клонуйте репозиторій у потрібний шлях (типово `~/.openclaw/workspace`). -2. Встановіть `agents.defaults.workspace` на цей шлях у `~/.openclaw/openclaw.json`. -3. Виконайте `openclaw setup --workspace `, щоб додати всі відсутні файли. -4. Якщо вам потрібні сесії, окремо скопіюйте `~/.openclaw/agents//sessions/` зі +1. Клонуйте репозиторій у потрібний шлях (за замовчуванням `~/.openclaw/workspace`). +2. Установіть `agents.defaults.workspace` на цей шлях у `~/.openclaw/openclaw.json`. +3. Виконайте `openclaw setup --workspace `, щоб додати відсутні файли. +4. Якщо вам потрібні сеанси, окремо скопіюйте `~/.openclaw/agents//sessions/` зі старої машини. ## Додаткові примітки -- Маршрутизація кількох агентів може використовувати різні робочі простори для різних агентів. Див. +- Маршрутизація з кількома агентами може використовувати різні робочі простори для різних агентів. Див. [Маршрутизація каналів](/uk/channels/channel-routing) для конфігурації маршрутизації. -- Якщо ввімкнено `agents.defaults.sandbox`, неосновні сесії можуть використовувати робочі простори пісочниці для кожної сесії в `agents.defaults.sandbox.workspaceRoot`. +- Якщо `agents.defaults.sandbox` увімкнено, неосновні сеанси можуть використовувати робочі простори + пісочниці для кожного сеансу в `agents.defaults.sandbox.workspaceRoot`. ## Пов’язане - [Standing Orders](/uk/automation/standing-orders) — постійні інструкції у файлах робочого простору - [Heartbeat](/uk/gateway/heartbeat) — файл робочого простору HEARTBEAT.md -- [Сесія](/uk/concepts/session) — шляхи зберігання сесій -- [Sandboxing](/uk/gateway/sandboxing) — доступ до робочого простору в середовищах із пісочницею +- [Session](/uk/concepts/session) — шляхи зберігання сеансів +- [Пісочниця](/uk/gateway/sandboxing) — доступ до робочого простору в середовищах із пісочницею diff --git a/docs/uk/concepts/agent.md b/docs/uk/concepts/agent.md index c21386ee8..f4ded547e 100644 --- a/docs/uk/concepts/agent.md +++ b/docs/uk/concepts/agent.md @@ -1,29 +1,29 @@ --- read_when: - - Зміна runtime агента, ініціалізації робочого простору або поведінки сесії -summary: Runtime агента, контракт робочого простору та початкова ініціалізація сесії -title: Runtime агента + - Зміна середовища виконання агента, ініціалізації робочого простору або поведінки сесії +summary: Середовище виконання агента, контракт робочого простору та ініціалізація сесії +title: Середовище виконання агента x-i18n: - generated_at: "2026-04-24T03:43:37Z" + generated_at: "2026-04-24T19:51:02Z" model: gpt-5.4 provider: openai - source_hash: 07fe0ca3c6bc306f95ac024b97b4e6e188c2d30786b936b8bd66a5f3ec012d4e + source_hash: 37483fdb62d41a8f888bd362db93078dc8ecb8bb3fd19270b0234689aa82f309 source_path: concepts/agent.md workflow: 15 --- -OpenClaw запускає **єдиний вбудований runtime агента** — один процес агента на Gateway, із власним робочим простором, bootstrap-файлами та сховищем сесій. Ця сторінка описує контракт цього runtime: що має містити робочий простір, які файли інжектуються та як відносно нього ініціалізуються сесії. +OpenClaw запускає **єдине вбудоване середовище виконання агента** — один процес агента на Gateway, із власним робочим простором, bootstrap-файлами та сховищем сесій. Ця сторінка описує контракт цього середовища виконання: що має містити робочий простір, які файли інжектуються та як відносно нього ініціалізуються сесії. ## Робочий простір (обов’язково) OpenClaw використовує єдиний каталог робочого простору агента (`agents.defaults.workspace`) як **єдиний** робочий каталог (`cwd`) агента для інструментів і контексту. -Рекомендовано: використайте `openclaw setup`, щоб створити `~/.openclaw/openclaw.json`, якщо його немає, і ініціалізувати файли робочого простору. +Рекомендовано: використовуйте `openclaw setup`, щоб створити `~/.openclaw/openclaw.json`, якщо його немає, та ініціалізувати файли робочого простору. -Повний макет робочого простору та посібник із резервного копіювання: [Agent workspace](/uk/concepts/agent-workspace) +Повна структура робочого простору + інструкція з резервного копіювання: [Робочий простір агента](/uk/concepts/agent-workspace) -Якщо ввімкнено `agents.defaults.sandbox`, сесії не з `main` можуть перевизначати це через робочі простори для кожної сесії в `agents.defaults.sandbox.workspaceRoot` (див. -[Gateway configuration](/uk/gateway/configuration)). +Якщо ввімкнено `agents.defaults.sandbox`, сесії не в `main` можуть перевизначати це за допомогою робочих просторів для кожної сесії в `agents.defaults.sandbox.workspaceRoot` (див. +[Конфігурація Gateway](/uk/gateway/configuration)). ## Bootstrap-файли (інжектуються) @@ -31,50 +31,50 @@ OpenClaw використовує єдиний каталог робочого - `AGENTS.md` — інструкції з роботи + «пам’ять» - `SOUL.md` — персона, межі, тон -- `TOOLS.md` — нотатки про інструменти, які підтримує користувач (наприклад, `imsg`, `sag`, домовленості) +- `TOOLS.md` — підтримувані користувачем примітки про інструменти (наприклад, `imsg`, `sag`, домовленості) - `BOOTSTRAP.md` — одноразовий ритуал першого запуску (видаляється після завершення) -- `IDENTITY.md` — ім’я/вайб/емодзі агента -- `USER.md` — профіль користувача + бажана форма звертання +- `IDENTITY.md` — ім’я агента/вайб/емодзі +- `USER.md` — профіль користувача + бажане звертання На першому ході нової сесії OpenClaw інжектує вміст цих файлів безпосередньо в контекст агента. -Порожні файли пропускаються. Великі файли обрізаються й усікаються з маркером, щоб prompts залишалися компактними (прочитайте файл, щоб отримати повний вміст). +Порожні файли пропускаються. Великі файли обрізаються й усікаються з маркером, щоб промпти залишалися компактними (прочитайте файл, щоб побачити повний вміст). -Якщо файл відсутній, OpenClaw інжектує один рядок-маркер «відсутній файл» (а `openclaw setup` створить безпечний шаблон за замовчуванням). +Якщо файл відсутній, OpenClaw інжектує один рядок-маркер «відсутній файл» (а `openclaw setup` створить безпечний типовий шаблон). -`BOOTSTRAP.md` створюється лише для **абсолютно нового робочого простору** (коли немає інших bootstrap-файлів). Якщо ви видалите його після завершення ритуалу, його не слід створювати знову під час наступних перезапусків. +`BOOTSTRAP.md` створюється лише для **абсолютно нового робочого простору** (коли немає інших bootstrap-файлів). Якщо ви видалите його після завершення ритуалу, він не повинен створюватися повторно під час наступних перезапусків. Щоб повністю вимкнути створення bootstrap-файлів (для попередньо підготовлених робочих просторів), установіть: ```json5 -{ agent: { skipBootstrap: true } } +{ agents: { defaults: { skipBootstrap: true } } } ``` ## Вбудовані інструменти -Основні інструменти (read/exec/edit/write і пов’язані системні інструменти) завжди доступні, -залежно від політики інструментів. `apply_patch` є необов’язковим і керується -`tools.exec.applyPatch`. `TOOLS.md` **не** керує тим, які інструменти існують; це +Основні інструменти (read/exec/edit/write та пов’язані системні інструменти) завжди доступні, +залежно від політики інструментів. `apply_patch` є необов’язковим і керується через +`tools.exec.applyPatch`. `TOOLS.md` **не** визначає, які інструменти існують; це настанови щодо того, як _ви_ хочете, щоб вони використовувалися. ## Skills -OpenClaw завантажує Skills із таких розташувань (найвищий пріоритет першим): +OpenClaw завантажує Skills із таких розташувань (від найвищого пріоритету до найнижчого): - Робочий простір: `/skills` -- Skills агента проєкту: `/.agents/skills` -- Особисті Skills агента: `~/.agents/skills` +- Skills агентів проєкту: `/.agents/skills` +- Особисті Skills агентів: `~/.agents/skills` - Керовані/локальні: `~/.openclaw/skills` - Вбудовані (постачаються разом з установленням) - Додаткові теки Skills: `skills.load.extraDirs` -Skills можуть обмежуватися через config/env (див. `skills` у [Gateway configuration](/uk/gateway/configuration)). +Skills можуть керуватися конфігурацією/env (див. `skills` у [Конфігурація Gateway](/uk/gateway/configuration)). -## Межі runtime +## Межі середовища виконання -Вбудований runtime агента побудовано на ядрі агента Pi (моделі, інструменти та -pipeline prompts). Керування сесіями, виявлення, підключення інструментів і доставка -через канали — це шари OpenClaw поверх цього ядра. +Вбудоване середовище виконання агента побудоване на ядрі агента Pi (моделі, інструменти та +конвеєр промптів). Керування сесіями, виявлення, підключення інструментів і доставка через канали +— це шари, якими поверх цього ядра володіє OpenClaw. ## Сесії @@ -82,58 +82,58 @@ pipeline prompts). Керування сесіями, виявлення, під - `~/.openclaw/agents//sessions/.jsonl` -Ідентифікатор сесії стабільний і вибирається OpenClaw. +ID сесії є стабільним і вибирається OpenClaw. Застарілі теки сесій з інших інструментів не читаються. -## Керування під час потокового передавання +## Керування під час потокової передачі Коли режим черги — `steer`, вхідні повідомлення інжектуються в поточний запуск. -Повідомлення керування в черзі доставляються **після того, як поточний хід асистента завершить +Поставлене в чергу керування доставляється **після завершення поточним ходом асистента виконання своїх викликів інструментів**, перед наступним викликом LLM. Керування більше не пропускає -решту викликів інструментів із поточного повідомлення асистента; натомість воно інжектує -повідомлення з черги на наступній межі моделі. +решту викликів інструментів із поточного повідомлення асистента; натомість воно інжектує поставлене в чергу +повідомлення на наступній межі моделі. -Коли режим черги — `followup` або `collect`, вхідні повідомлення утримуються до завершення -поточного ходу, після чого запускається новий хід агента з даними з черги. Див. -[Queue](/uk/concepts/queue) для деталей щодо режимів і поведінки debounce/cap. +Коли режим черги — `followup` або `collect`, вхідні повідомлення утримуються, доки +поточний хід не завершиться, після чого починається новий хід агента з поставленими в чергу корисними навантаженнями. Див. +[Черга](/uk/concepts/queue), щоб дізнатися про поведінку режимів + debounce/cap. -Block streaming надсилає завершені блоки асистента, щойно вони завершуються; він -**вимкнений за замовчуванням** (`agents.defaults.blockStreamingDefault: "off"`). -Налаштуйте межу через `agents.defaults.blockStreamingBreak` (`text_end` або `message_end`; типово `text_end`). -Керуйте м’яким розбиттям блоків через `agents.defaults.blockStreamingChunk` (типово -800–1200 символів; перевага надається межам абзаців, потім новим рядкам; речення — в останню чергу). +Потокова передача блоками надсилає завершені блоки асистента щойно вони завершуються; вона +**вимкнена за замовчуванням** (`agents.defaults.blockStreamingDefault: "off"`). +Налаштовуйте межу через `agents.defaults.blockStreamingBreak` (`text_end` чи `message_end`; типово — text_end). +Керуйте м’яким розбиттям блоків на фрагменти через `agents.defaults.blockStreamingChunk` (типово — +800–1200 символів; перевага надається розривам абзаців, потім новим рядкам; речення — в останню чергу). Об’єднуйте потокові фрагменти через `agents.defaults.blockStreamingCoalesce`, щоб зменшити -спам з одиночних рядків (злиття перед надсиланням на основі простою). Для каналів, відмінних від Telegram, потрібне -явне `*.blockStreaming: true`, щоб увімкнути відповіді блоками. -Докладні зведення інструментів виводяться на старті інструмента (без debounce); Control UI +спам з одного рядка (об’єднання перед надсиланням на основі простою). Канали, крім Telegram, вимагають +явного `*.blockStreaming: true`, щоб увімкнути відповіді блоками. +Розгорнуті підсумки інструментів надсилаються на початку роботи інструмента (без debounce); Control UI передає вивід інструментів потоком через події агента, коли це доступно. -Докладніше: [Streaming + chunking](/uk/concepts/streaming). +Докладніше: [Потокова передача + розбиття на фрагменти](/uk/concepts/streaming). ## Посилання на моделі -Посилання на моделі в конфігурації (наприклад, `agents.defaults.model` і `agents.defaults.models`) розбираються розділенням за **першим** `/`. +Посилання на моделі в конфігурації (наприклад, `agents.defaults.model` і `agents.defaults.models`) аналізуються розділенням за **першим** `/`. - Використовуйте `provider/model` під час налаштування моделей. -- Якщо сам ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`). -- Якщо ви не вкажете провайдера, OpenClaw спочатку спробує alias, потім — - унікальний збіг exact model id серед налаштованих провайдерів, і лише після цього повернеться - до налаштованого провайдера за замовчуванням. Якщо цей провайдер більше не надає +- Якщо сам ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`). +- Якщо ви не вкажете провайдера, OpenClaw спочатку спробує псевдонім, потім — унікальний + збіг налаштованого провайдера для цього точного id моделі, і лише після цього повернеться до + налаштованого провайдера за замовчуванням. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повернеться до першої налаштованої - пари provider/model замість того, щоб показувати застаріле значення за замовчуванням від видаленого провайдера. + пари provider/model замість того, щоб показувати застаріле значення типового провайдера, який уже видалено. ## Конфігурація (мінімальна) -Щонайменше встановіть: +Щонайменше налаштуйте: - `agents.defaults.workspace` - `channels.whatsapp.allowFrom` (наполегливо рекомендовано) --- -_Далі: [Group Chats](/uk/channels/group-messages)_ 🦞 +_Далі: [Групові чати](/uk/channels/group-messages)_ 🦞 ## Пов’язане -- [Agent workspace](/uk/concepts/agent-workspace) -- [Multi-agent routing](/uk/concepts/multi-agent) -- [Session management](/uk/concepts/session) +- [Робочий простір агента](/uk/concepts/agent-workspace) +- [Маршрутизація кількох агентів](/uk/concepts/multi-agent) +- [Керування сесіями](/uk/concepts/session) diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index 8f056da7e..8b447f151 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -1,32 +1,32 @@ --- read_when: - Розширення qa-lab або qa-channel - - Додавання QA-сценаріїв на основі репозиторію + - Додавання репозиторій-підтримуваних сценаріїв QA - Побудова більш реалістичної автоматизації QA навколо панелі Gateway -summary: Приватна форма автоматизації QA для qa-lab, qa-channel, початково заповнених сценаріїв і звітів протоколу +summary: Приватна структура автоматизації QA для qa-lab, qa-channel, початково заповнених сценаріїв і звітів протоколу title: Автоматизація QA E2E x-i18n: - generated_at: "2026-04-24T02:51:59Z" + generated_at: "2026-04-24T19:51:01Z" model: gpt-5.4 provider: openai - source_hash: bbde51169a1572dc6753ab550ca29ca98abb2394e8991a8482bd7b66ea80ce76 + source_hash: 9a49e0954845355667617c85340281b6dc1b043857a76d7b303cc0a8b2845a75 source_path: concepts/qa-e2e-automation.md workflow: 15 --- Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, -орієнтований на канали спосіб, ніж це може один unit-тест. +каналоподібний спосіб, ніж це може один unit-тест. Поточні складові: - `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, треду, реакцій, редагування та видалення. -- `extensions/qa-lab`: UI налагодження та шина QA для спостереження за транскриптом, - інʼєкції вхідних повідомлень та експорту Markdown-звіту. -- `qa/`: ресурси початкових даних на основі репозиторію для стартового завдання та базових QA- - сценаріїв. +- `extensions/qa-lab`: UI налагоджувача та шина QA для спостереження за транскриптом, + інʼєкції вхідних повідомлень і експорту звіту у Markdown. +- `qa/`: ресурси початкового наповнення, що зберігаються в репозиторії, для стартового завдання та базових + сценаріїв QA. -Поточний робочий процес QA-оператора — це двопанельний QA-сайт: +Поточний операторський потік QA — це двопанельний сайт QA: - Ліворуч: панель Gateway (Control UI) з агентом. - Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. @@ -37,12 +37,12 @@ x-i18n: pnpm qa:lab:up ``` -Це збирає QA-сайт, запускає lane Gateway на основі Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA- -місію, спостерігати реальну поведінку каналу та фіксувати, що спрацювало, -що не спрацювало або що залишилося заблокованим. +Це збирає сайт QA, запускає lane Gateway на базі Docker і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати агенту +QA-місію, спостерігати реальну поведінку каналу та зафіксувати, що спрацювало, +що зламалося або що залишилося заблокованим. -Для швидшої ітерації UI QA Lab без перебудови Docker-образу щоразу +Для швидших ітерацій UI QA Lab без повторного збирання Docker-образу щоразу, запустіть стек із bind-mounted збіркою QA Lab: ```bash @@ -52,10 +52,10 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` утримує Docker-сервіси на попередньо зібраному образі та bind-mount'ить -`extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перебудовує цей bundle при змінах, а браузер автоматично перезавантажується, -коли змінюється хеш ресурсу QA Lab. +`qa:lab:up:fast` залишає Docker-сервіси на попередньо зібраному образі та bind-mount +монтує `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` +перезбирає цей bundle при змінах, а браузер автоматично перезавантажується, коли +змінюється хеш ресурсів QA Lab. Для smoke lane Matrix із реальним транспортом виконайте: @@ -63,15 +63,17 @@ pnpm qa:lab:watch pnpm openclaw qa matrix ``` -Цей lane розгортає тимчасовий homeserver Tuwunel у Docker, реєструє -тимчасових користувачів driver, SUT і observer, створює одну приватну кімнату, -а потім запускає реальний Plugin Matrix усередині дочірнього QA gateway. Lane із -живим транспортом зберігає конфігурацію дочірнього процесу обмеженою -транспортом, що тестується, тому Matrix працює без `qa-channel` у дочірній -конфігурації. Він записує структуровані артефакти звіту та обʼєднаний лог -stdout/stderr у вибраний вихідний каталог Matrix QA. Щоб також захопити -зовнішній вивід збірки/запускача `scripts/run-node.mjs`, установіть -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` на локальний щодо репозиторію файл логу. +Цей lane розгортає одноразовий homeserver Tuwunel у Docker, реєструє +тимчасових користувачів driver, SUT і observer, створює одну приватну кімнату, а +потім запускає реальний Plugin Matrix у дочірньому Gateway QA. Live transport lane +утримує конфігурацію дочірнього процесу обмеженою транспортом, що тестується, тому Matrix +працює без `qa-channel` у дочірній конфігурації. Він записує структуровані +артефакти звіту та обʼєднаний лог stdout/stderr у вибраний вихідний каталог Matrix QA. +Щоб також захопити зовнішній вивід збирання/запускача `scripts/run-node.mjs`, +встановіть `OPENCLAW_RUN_NODE_OUTPUT_LOG=` у лог-файл у межах репозиторію. +Поступ Matrix виводиться типово. `OPENCLAW_QA_MATRIX_TIMEOUT_MS` обмежує +повний запуск, а `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` обмежує очищення, щоб +зависле згортання Docker повідомляло точну команду відновлення замість зависання. Для smoke lane Telegram із реальним транспортом виконайте: @@ -80,16 +82,26 @@ pnpm openclaw qa telegram ``` Цей lane націлюється на одну реальну приватну групу Telegram замість розгортання -тимчасового сервера. Для нього потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +одноразового сервера. Він потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також два різні боти в одній -приватній групі. Бот SUT повинен мати імʼя користувача Telegram, а -спостереження bot-to-bot працює найкраще, коли для обох ботів увімкнено -режим Bot-to-Bot Communication Mode в `@BotFather`. -Команда завершується ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також двох різних ботів в одній +приватній групі. Бот SUT повинен мати імʼя користувача Telegram, а спостереження +бот-до-бота працює найкраще, коли в обох ботів увімкнено Bot-to-Bot Communication Mode +у `@BotFather`. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. -Звіт і підсумок Telegram включають RTT для кожної відповіді — від запиту -надсилання повідомлення driver до спостережуваної відповіді SUT, починаючи з canary. +Звіт і підсумок Telegram містять RTT для кожної відповіді від запиту +надсилання повідомлення driver до зафіксованої відповіді SUT, починаючи з canary. + +Перед використанням пулу live credentials виконайте: + +```bash +pnpm openclaw qa credentials doctor +``` + +Doctor перевіряє env брокера Convex, валідовує налаштування endpoint і перевіряє +досяжність admin/list, коли присутній секрет супровідника. Він повідомляє лише +статус set/missing для секретів. Для smoke lane Discord із реальним транспортом виконайте: @@ -97,138 +109,136 @@ pnpm openclaw qa telegram pnpm openclaw qa discord ``` -Цей lane націлюється на один реальний приватний канал guild Discord із двома ботами: ботом -driver, яким керує harness, і ботом SUT, який запускається дочірнім -Gateway OpenClaw через вбудований Plugin Discord. Для нього потрібні +Цей lane націлюється на один реальний приватний канал guild у Discord із двома ботами: ботом +driver, яким керує harness, і ботом SUT, запущеним дочірнім +Gateway OpenClaw через вбудований Plugin Discord. Він потребує `OPENCLAW_QA_DISCORD_GUILD_ID`, `OPENCLAW_QA_DISCORD_CHANNEL_ID`, `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -і `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` у разі використання облікових даних env. -Lane перевіряє обробку згадок у каналі та перевіряє, що бот SUT +і `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` при використанні credentials через env. +Lane перевіряє обробку згадок каналу та перевіряє, що бот SUT зареєстрував нативну команду `/help` у Discord. -Команда завершується ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. -Тепер lane із живим транспортом використовують один менший контракт замість того, -щоб кожен вигадував власну форму списку сценаріїв: +Live transport lanes тепер поділяють один менший контракт замість того, щоб кожен вигадував +власну форму списку сценаріїв: -`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту і не входить +`qa-channel` залишається широким синтетичним набором перевірок продуктової поведінки й не входить до матриці покриття live transport. -| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальше повідомлення в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | Реєстрація нативної команди | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | ----------------------------- | --------------- | -------------------------- | ------------ | --------------------------- | -| Matrix | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | | | | | | | x | | -| Discord | x | x | | | | | | | | x | +| Lane | Canary | Обмеження за згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в треді | Ізоляція треду | Спостереження за реакціями | Команда help | Реєстрація нативної команду | +| -------- | ------ | --------------------- | -------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | -------------------------- | ------------ | --------------------------- | +| Matrix | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | | | | | | | x | | +| Discord | x | x | | | | | | | | x | -Це зберігає `qa-channel` як широкий набір перевірок поведінки продукту, тоді як Matrix, -Telegram і майбутні живі транспорти спільно використовують один явний контрольний список -транспортного контракту. +Це зберігає `qa-channel` як широкий набір перевірок продуктової поведінки, тоді як Matrix, +Telegram і майбутні live transports поділяють один явний контрольний список транспортного контракту. -Для lane з тимчасовою Linux VM без використання Docker у QA-шляху виконайте: +Для lane з одноразовою Linux VM без залучення Docker до шляху QA виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це завантажує нову гостьову машину Multipass, установлює залежності, збирає OpenClaw -усередині гостьової машини, запускає `qa suite`, а потім копіює звичайний QA-звіт і +Це запускає свіжий гість Multipass, встановлює залежності, збирає OpenClaw +всередині гостя, виконує `qa suite`, а потім копіює звичайний звіт QA та підсумок назад у `.artifacts/qa-e2e/...` на хості. Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. -Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних -сценаріїв паралельно з ізольованими worker Gateway. Для `qa-channel` -типове значення concurrency — 4, обмежене кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати -кількість worker, або `--concurrency 1` для послідовного виконання. -Команда завершується ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо +Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно +з ізольованими worker-ами Gateway. `qa-channel` типово використовує concurrency 4, +обмежену кількістю вибраних сценаріїв. Використовуйте `--concurrency ` для налаштування +кількості worker-ів або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. -Живі запуски передають підтримувані вхідні дані автентифікації QA, які практичні для -гостьової машини: ключі провайдерів на основі env, шлях до конфігурації live provider QA і +Live-запуски пересилають підтримувані вхідні дані автентифікації QA, практичні для +гостя: ключі провайдера через env, шлях до конфігурації live provider QA і `CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість -міг записувати назад через змонтований workspace. +міг записати результати назад через змонтований workspace. -## Початкові дані на основі репозиторію +## Початкове наповнення з репозиторію -Ресурси початкових даних знаходяться в `qa/`: +Ресурси початкового наповнення розміщені в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Вони навмисно зберігаються в git, щоб QA-план був видимий і людям, і +Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і агенту. -`qa-lab` має залишатися загальним runner для markdown. Кожен markdown-файл сценарію є -джерелом істини для одного тестового запуску й має визначати: +`qa-lab` має залишатися узагальненим виконавцем markdown. Кожен markdown-файл сценарію є +джерелом істини для одного тестового запуску й повинен визначати: - метадані сценарію -- необовʼязкові метадані category, capability, lane і risk -- посилання на docs і код +- необовʼязкові метадані категорії, можливостей, lane і ризику +- посилання на docs і code - необовʼязкові вимоги до Plugin -- необовʼязковий patch конфігурації gateway +- необовʼязковий patch конфігурації Gateway - виконуваний `qa-flow` -Поверхня повторно використовуваного runtime, що підтримує `qa-flow`, може залишатися загальною -і наскрізною. Наприклад, markdown-сценарії можуть поєднувати transport-side -допоміжні засоби з browser-side допоміжними засобами, які керують вбудованим Control UI через -seam Gateway `browser.request`, не додаючи спеціалізований runner. +Повторно використовувана поверхня runtime, що лежить в основі `qa-flow`, може залишатися узагальненою +і наскрізною. Наприклад, markdown-сценарії можуть поєднувати допоміжні засоби +на стороні транспорту з допоміжними засобами на стороні браузера, які керують вбудованим Control UI через +шов Gateway `browser.request`, не додаючи спеціалізованого runner-а. -Файли сценаріїв слід групувати за можливостями продукту, а не за папкою -вихідного дерева. Зберігайте стабільність ID сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` +Файли сценаріїв слід групувати за продуктовими можливостями, а не за папкою дерева +вихідного коду. Зберігайте стабільність ідентифікаторів сценаріїв при переміщенні файлів; використовуйте `docsRefs` і `codeRefs` для трасованості реалізації. -Базовий список має залишатися достатньо широким, щоб охоплювати: +Базовий список має залишатися достатньо широким, щоб покривати: - чат у DM і каналі - поведінку тредів - життєвий цикл дій із повідомленнями -- Cron callbacks -- виклик памʼяті +- зворотні виклики Cron +- згадування памʼяті - перемикання моделей -- передачу підзадачі субагенту -- читання репозиторію та документації -- одне невелике завдання на збірку, наприклад Lobster Invaders +- передавання субагенту +- читання репозиторію та читання docs +- одне невелике завдання зі збирання, наприклад Lobster Invaders -## Mock lanes провайдерів +## Mock lane-ы провайдерів -`qa suite` має два локальні mock lanes провайдерів: +`qa suite` має два локальні mock lane-ы провайдерів: -- `mock-openai` — це обізнаний про сценарії mock OpenClaw. Він залишається типовим - детермінованим mock lane для QA на основі репозиторію та перевірок паритету. -- `aimock` запускає сервер провайдера на основі AIMock для експериментального - покриття протоколу, фікстур, record/replay і chaos. Він є доповненням і не - замінює dispatcher сценаріїв `mock-openai`. +- `mock-openai` — це OpenClaw mock з урахуванням сценаріїв. Він залишається типовим + детермінованим mock lane для QA з репозиторій-підтримкою та перевірок паритету. +- `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття протоколу, + фікстур, record/replay і хаосу. Він є додатковим і не замінює диспетчер сценаріїв `mock-openai`. -Реалізація lane провайдерів знаходиться в `extensions/qa-lab/src/providers/`. -Кожен провайдер володіє своїми значеннями за замовчуванням, запуском локального сервера, -конфігурацією моделі gateway, потребами staging auth-profile і прапорцями live/mock capability. Спільний код suite і gateway -має маршрутизувати через registry провайдерів замість розгалуження за іменами провайдерів. +Реалізація provider lane розміщена в `extensions/qa-lab/src/providers/`. +Кожен провайдер володіє своїми типово встановленими значеннями, запуском локального сервера, +конфігурацією моделі Gateway, потребами staging auth-profile, а також прапорцями можливостей live/mock. Спільний код suite і Gateway має маршрутизувати +через реєстр провайдерів замість розгалуження за назвами провайдерів. ## Адаптери транспорту -`qa-lab` володіє загальним seam транспорту для markdown QA-сценаріїв. -`qa-channel` — перший адаптер на цьому seam, але ціль дизайну ширша: -майбутні реальні або синтетичні канали мають підключатися до того самого runner `suite` -замість додавання transport-specific QA runner. +`qa-lab` володіє узагальненим швом транспорту для markdown-сценаріїв QA. +`qa-channel` — перший адаптер на цьому шві, але ціль проєктування ширша: +майбутні реальні або синтетичні канали мають підключатися до того ж runner-а suite +замість додавання runner-а QA, специфічного для транспорту. -На рівні архітектури поділ такий: +На рівні архітектури розділення таке: -- `qa-lab` відповідає за загальне виконання сценаріїв, concurrency worker, запис артефактів і звітність. -- адаптер транспорту відповідає за конфігурацію gateway, готовність, спостереження за вхідними та вихідними даними, транспортні дії та нормалізований стан транспорту. -- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає повторно використовувану поверхню runtime, яка їх виконує. +- `qa-lab` володіє узагальненим виконанням сценаріїв, паралелізмом worker-ів, записом артефактів і звітністю. +- адаптер транспорту володіє конфігурацією Gateway, готовністю, спостереженням вхідного й вихідного трафіку, діями транспорту та нормалізованим станом транспорту. +- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає повторно використовувану поверхню runtime, яка його виконує. -Настанови з упровадження для нових адаптерів каналів, орієнтовані на мейнтейнерів, розміщені в -[Тестування](/uk/help/testing#adding-a-channel-to-qa). +Орієнтовані на супровідників вказівки з упровадження нових адаптерів каналів розміщені в +[Testing](/uk/help/testing#adding-a-channel-to-qa). ## Звітність -`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової шкали шини. -Звіт має відповідати на такі запитання: +`qa-lab` експортує звіт протоколу у Markdown на основі спостережуваної часової шкали шини. +Звіт має відповідати на запитання: - Що спрацювало -- Що не спрацювало +- Що зламалося - Що залишилося заблокованим -- Які подальші сценарії варто додати +- Які сценарії продовження варто додати -Для перевірок характеру та стилю запустіть той самий сценарій на кількох live model -refs і запишіть Markdown-звіт з оцінюванням: +Для перевірок характеру й стилю запустіть той самий сценарій для кількох live model +refs і запишіть оцінений звіт у Markdown: ```bash pnpm openclaw qa character-eval \ @@ -247,41 +257,42 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -Команда запускає локальні дочірні процеси QA gateway, а не Docker. Сценарії character eval -мають задавати persona через `SOUL.md`, а потім виконувати звичайні ходи користувача, +Команда запускає локальні дочірні процеси Gateway QA, а не Docker. Сценарії character eval +мають задавати персону через `SOUL.md`, а потім виконувати звичайні користувацькі ходи, такі як чат, допомога з workspace і невеликі файлові завдання. Моделі-кандидату не слід повідомляти, що її оцінюють. Команда зберігає кожен повний -транскрипт, записує базову статистику запуску, а потім просить моделі-судді в fast mode з -`xhigh` reasoning, де це підтримується, ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models` при порівнянні провайдерів: промпт судді все одно отримує -кожен транскрипт і статус запуску, але посилання кандидатів замінюються нейтральними -мітками на кшталт `candidate-01`; після парсингу звіт зіставляє ранжування назад із реальними ref. +транскрипт, записує базову статистику запуску, а потім просить моделі-судді у fast mode з +міркуванням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором. +Використовуйте `--blind-judge-models` при порівнянні провайдерів: підказка для судді все одно отримує +кожен транскрипт і статус запуску, але посилання кандидатів замінюються на нейтральні +мітки, такі як `candidate-01`; звіт зіставляє рейтинги назад із реальними посиланнями після +розбору. -Для запусків кандидатів за замовчуванням використовується thinking рівня `high`, із `medium` для GPT-5.4 та `xhigh` -для старіших OpenAI eval ref, які це підтримують. Перевизначте конкретного кандидата прямо в рядку через +Для запусків кандидатів типово використовується thinking `high`, `medium` для GPT-5.4 і `xhigh` +для старіших eval refs OpenAI, які це підтримують. Замініть значення для конкретного кандидата inline через `--model provider/model,thinking=`. `--thinking ` як і раніше задає -глобальне резервне значення, а старіша форма `--model-thinking ` збережена +глобальне резервне значення, а старіша форма `--model-thinking ` зберігається для сумісності. -OpenAI candidate ref за замовчуванням використовують fast mode, щоб застосовувалася пріоритетна обробка там, -де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` прямо в рядку, коли +Для посилань кандидатів OpenAI за замовчуванням використовується fast mode, щоб застосовувалася +пріоритетна обробка там, де провайдер це підтримує. Додайте `,fast`, `,no-fast` або `,fast=false` inline, коли одному кандидату або судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість роботи кандидатів і суддів -записується у звіт для аналізу бенчмарків, але в промптах для суддів явно сказано +примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів +записується у звіт для аналізу бенчмарків, але в підказках для суддів прямо сказано не ранжувати за швидкістю. -Для запусків моделей-кандидатів і моделей-суддів за замовчуванням використовується concurrency 16. Зменшуйте -`--concurrency` або `--judge-concurrency`, коли ліміти провайдера або навантаження на локальний gateway +І для запусків моделей-кандидатів, і для запусків моделей-суддів за замовчуванням використовується concurrency 16. Зменшуйте +`--concurrency` або `--judge-concurrency`, коли ліміти провайдера або навантаження на локальний Gateway роблять запуск надто шумним. -Якщо не передано жодного кандидата через `--model`, для character eval за замовчуванням використовуються +Коли не передано жодного кандидата через `--model`, для character eval за замовчуванням використовуються `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і -`google/gemini-3.1-pro-preview`, якщо не передано `--model`. -Якщо не передано `--judge-model`, за замовчуванням використовуються судді +`google/gemini-3.1-pro-preview`, якщо `--model` не передано. +Коли `--judge-model` не передано, судді за замовчуванням: `openai/gpt-5.4,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. -## Повʼязана документація +## Повʼязані docs -- [Тестування](/uk/help/testing) +- [Testing](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) -- [Панель](/uk/web/dashboard) +- [Dashboard](/uk/web/dashboard) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 6a52da841..ea9ae36c4 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -5,16 +5,16 @@ read_when: summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-24T03:16:45Z" + generated_at: "2026-04-24T19:51:02Z" model: gpt-5.4 provider: openai - source_hash: 0cc0ddb91af47a246c9a37528942b7d53c166255469169d6cb0268f83359c400 + source_hash: 2d51af7f3e4c084d2cf3ca9f9bcb6e54ee2c5fc3cd2aa6f844b6995f8f9e209c source_path: gateway/doctor.md workflow: 15 --- `openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу -конфігурацію/стан, перевіряє працездатність і надає практичні кроки відновлення. +конфігурацію/стан, перевіряє працездатність і надає практичні кроки для відновлення. ## Швидкий старт @@ -28,13 +28,13 @@ openclaw doctor openclaw doctor --yes ``` -Приймає типові варіанти без запитів (зокрема кроки відновлення перезапуску/служб/sandbox, коли це застосовно). +Приймає значення за замовчуванням без запитів (зокрема кроки відновлення перезапуску/сервісу/пісочниці, якщо застосовно). ```bash openclaw doctor --repair ``` -Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). +Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно). ```bash openclaw doctor --repair --force @@ -46,14 +46,14 @@ openclaw doctor --repair --force openclaw doctor --non-interactive ``` -Запускає без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + перенесення стану на диску). Пропускає дії перезапуску/служб/sandbox, які потребують підтвердження людиною. +Працює без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/пісочниці, які потребують підтвердження людиною. Міграції застарілого стану запускаються автоматично, якщо їх виявлено. ```bash openclaw doctor --deep ``` -Сканує системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks). +Сканує системні сервіси на наявність додаткових встановлень gateway (launchd/systemd/schtasks). Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації: @@ -64,80 +64,80 @@ cat ~/.openclaw/openclaw.json ## Що він робить (коротко) - Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі). -- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). +- Перевірка актуальності UI protocol (перебудовує Control UI, якщо схема protocol новіша). - Перевірка працездатності + запит на перезапуск. -- Підсумок стану Skills (доступні/відсутні/заблоковані) і стан Plugin. +- Підсумок стану Skills (доступні/відсутні/заблоковані) і стану плагінів. - Нормалізація конфігурації для застарілих значень. -- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. -- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. +- Міграція конфігурації Talk із застарілих плоских полів `talk.*` до `talk.provider` + `talk.providers.`. +- Перевірки міграції браузера для застарілих конфігурацій Chrome extension і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Попередження про затінення OAuth Codex (`models.providers.openai-codex`). -- Перевірка передумов OAuth TLS для профілів OAuth OpenAI Codex. -- Міграція застарілого стану на диску (sessions/agent dir/автентифікація WhatsApp). -- Міграція ключів контрактів маніфесту застарілого Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Міграція сховища застарілого Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні завдання Webhook із `notify: true`). +- Попередження про затінення Codex OAuth (`models.providers.openai-codex`). +- Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. +- Міграція застарілого стану на диску (сесії/каталог agent/автентифікація WhatsApp). +- Міграція ключів контрактів маніфестів застарілих плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Міграція сховища застарілих Cron (`jobId`, `schedule.cron`, верхньорівневі поля delivery/payload, `provider` у payload, прості резервні jobs для webhook з `notify: true`). - Перевірка файлів блокування сесій і очищення застарілих блокувань. -- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). -- Перевірки прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску. -- Стан автентифікації моделі: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких добігає кінця, і повідомляє про стани cooldown/disabled профілю автентифікації. +- Перевірки цілісності та дозволів стану (сесії, транскрипти, каталог стану). +- Перевірки дозволів файла конфігурації (chmod 600) під час локального запуску. +- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілів автентифікації. - Виявлення додаткового каталогу workspace (`~/openclaw`). -- Відновлення образу sandbox, коли sandboxing увімкнено. -- Міграція застарілих служб і виявлення додаткових gateway. +- Відновлення образу пісочниці, коли увімкнено sandboxing. +- Міграція застарілих сервісів і виявлення додаткових gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). -- Перевірки середовища виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd). -- Попередження про стан каналу (визначаються через запущений gateway). -- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. +- Перевірки середовища виконання Gateway (сервіс установлено, але він не запущений; кешована мітка launchd). +- Попередження про стан каналів (визначаються із запущеного gateway). +- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим виправленням. - Перевірки найкращих практик середовища виконання Gateway (Node проти Bun, шляхи менеджера версій). - Діагностика конфліктів порту Gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. -- Перевірки автентифікації Gateway для локального режиму токена (пропонує згенерувати токен, коли немає джерела токена; не перезаписує конфігурації token SecretRef). -- Виявлення проблем зі спарюванням пристроїв (очікувальні запити першого спарювання, очікувальні оновлення ролі/області дії, дрейф застарілого локального кешу токенів пристрою та дрейф автентифікації запису спарювання). -- Перевірка systemd linger на Linux. -- Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). -- Перевірка стану shell completion і автоматичне встановлення/оновлення. -- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD). -- Перевірки source-встановлення (невідповідність workspace pnpm, відсутні UI assets, відсутній двійковий файл tsx). +- Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації токенів SecretRef). +- Виявлення проблем зі сполученням пристроїв (очікувані перші запити на сполучення, очікувані оновлення ролей/областей дії, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації записів про сполучення). +- Перевірка systemd linger у Linux. +- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до ліміту для файлів контексту). +- Перевірка стану shell completion та автоматичне встановлення/оновлення. +- Перевірка готовності провайдера ембедингів для пошуку в пам’яті (локальна модель, віддалений API-ключ або бінарний файл QMD). +- Перевірки вихідного встановлення (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній бінарний файл tsx). - Записує оновлену конфігурацію + метадані wizard. -## Заповнення й скидання Dreams UI +## Backfill і скидання Dreams UI Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** -для workflow grounded dreaming. Ці дії використовують RPC-методи в стилі -doctor gateway, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`. +для процесу grounded dreaming. Ці дії використовують RPC-методи у стилі doctor для +gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. Що вони роблять: - **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному - workspace, запускає grounded REM diary pass і записує оборотні записи - backfill у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, які мають відповідні позначки. + workspace, запускає grounded REM diary pass і записує зворотні записи backfill + у `DREAMS.md`. +- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, які позначено. - **Clear Grounded** видаляє лише staged grounded-only short-term записи, які - з’явилися з історичного відтворення та ще не накопичили live recall або daily + походять з історичного відтворення і ще не накопичили live recall або daily support. -Чого вони самі по собі **не** роблять: +Що вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не переносять автоматично grounded candidate до сховища live short-term - promotion, якщо ви явно не запустите спочатку staged CLI-шлях +- вони не переміщують автоматично grounded candidates у live short-term + promotion store, якщо ви явно не запустили спочатку staged CLI path Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion -lane, використовуйте натомість CLI-потік: +lane, натомість використовуйте CLI-потік: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Це переносить grounded durable candidate до short-term dreaming store, водночас -залишаючи `DREAMS.md` як поверхню для перегляду. +Це розміщує grounded durable candidates у short-term dreaming store, водночас +залишаючи `DREAMS.md` поверхнею для перегляду. -## Докладна поведінка та обґрунтування +## Детальна поведінка та обґрунтування ### 0) Необов’язкове оновлення (git-встановлення) Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує -оновити (fetch/rebase/build) перед запуском doctor. +виконати оновлення (fetch/rebase/build) перед запуском doctor. ### 1) Нормалізація конфігурації @@ -145,25 +145,26 @@ openclaw memory rem-backfill --path ./memory --stage-short-term без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. -Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — -`talk.provider` + `talk.providers.`. Doctor переписує старі форми +Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — +це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` у мапу провайдера. +`talk.apiKey` у map провайдерів. ### 2) Міграції ключів застарілої конфігурації Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися -і просять вас запустити `openclaw doctor`. +і просять вас виконати `openclaw doctor`. -Doctor виконає таке: +Doctor: -- Пояснить, які застарілі ключі знайдено. -- Покажe міграцію, яку було застосовано. +- Пояснить, які застарілі ключі було знайдено. +- Покажe міграцію, яку він застосував. - Перезапише `~/.openclaw/openclaw.json` з оновленою схемою. -Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє -застарілий формат конфігурації, тому застарілі конфігурації відновлюються без -ручного втручання. Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`. +Gateway також автоматично запускає міграції doctor під час старту, коли виявляє +застарілий формат конфігурації, тому застарілі конфігурації виправляються без +ручного втручання. +Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`. Поточні міграції: @@ -174,7 +175,7 @@ Gateway також автоматично запускає міграції doct - `routing.queue` → `messages.queue` - `routing.bindings` → верхньорівневий `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` -- застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` +- застарілий `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` @@ -187,30 +188,31 @@ Gateway також автоматично запускає міграції doct - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Для каналів з іменованими `accounts`, але із залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістити ці значення в підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну ціль named/default) +- Для каналів з іменованими `accounts`, але зі збереженими верхньорівневими значеннями каналу для одного облікового запису, перемістити ці значення рівня облікового запису до promoted account, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну ціль named/default) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` -- видалити `browser.relayBindHost` (застаріле налаштування relay розширення) +- видалення `browser.relayBindHost` (застаріле налаштування relay для extension) -Попередження doctor також містять вказівки щодо типового облікового запису для багатoоблікових каналів: +Попередження doctor також містять рекомендації щодо account-default для мультиакаунтних каналів: -- Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. -- Якщо `channels..defaultAccount` вказує на невідомий id облікового запису, doctor попереджає й перелічує налаштовані id облікових записів. +- Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback routing може вибрати неочікуваний обліковий запис. +- Якщо `channels..defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає про це та перелічує налаштовані ID облікових записів. ### 2b) Перевизначення провайдера OpenCode Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. -Це може примусово направляти моделі до неправильного API або обнуляти вартість. Doctor попереджає, щоб ви могли видалити це перевизначення й відновити маршрутизацію API та вартість для кожної моделі. +Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає, щоб ви +могли видалити це перевизначення й відновити маршрутизацію API + вартість для кожної моделі. ### 2c) Міграція браузера та готовність Chrome MCP -Якщо конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor -нормалізує її до поточної моделі host-local attach для Chrome MCP: +Якщо ваша конфігурація браузера все ще вказує на вилучений шлях Chrome extension, doctor +нормалізує її до поточної моделі приєднання host-local Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється @@ -218,74 +220,73 @@ Gateway також автоматично запускає міграції doct Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: -- перевіряє, чи встановлено Google Chrome на тому самому хості для типових - профілів автопідключення -- перевіряє виявлену версію Chrome й попереджає, якщо вона нижча за Chrome 144 -- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад +- перевіряє, чи встановлено Google Chrome на тому самому хості для профілів авто-підключення за замовчуванням +- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 +- нагадує увімкнути remote debugging на сторінці inspect браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, або `edge://inspect/#remote-debugging`) -Doctor не може ввімкнути налаштування на боці Chrome за вас. Host-local Chrome MCP -як і раніше потребує: +Doctor не може увімкнути це налаштування з боку Chrome за вас. Host-local Chrome MCP +усе ще потребує: -- браузер на основі Chromium 144+ на хості gateway/node +- браузер на базі Chromium 144+ на хості gateway/node - локально запущений браузер - увімкнений remote debugging у цьому браузері -- підтвердження першого запиту на приєднання в браузері +- підтвердження першого запиту на дозвіл приєднання в браузері Готовність тут стосується лише локальних передумов приєднання. Existing-session зберігає -поточні обмеження маршруту Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, -перехоплення завантажень і пакетні дії, як і раніше потребують керованого -браузера або raw CDP-профілю. +поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, +перехоплення завантажень і пакетні дії, як і раніше, потребують керованого +браузера або профілю raw CDP. -Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших -headless-потоків. Вони й далі використовують raw CDP. +Ця перевірка **не** стосується Docker, sandbox, remote-browser або інших +headless-потоків. Вони й надалі використовують raw CDP. -### 2d) Передумови OAuth TLS +### 2d) TLS-передумови OAuth -Коли налаштовано профіль OAuth OpenAI Codex, doctor перевіряє кінцеву точку -авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може +Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, +щоб упевнитися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), -doctor виводить вказівки щодо виправлення для конкретної платформи. На macOS із Homebrew Node -виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується, -навіть якщо gateway справний. +doctor виводить рекомендації з виправлення для конкретної платформи. На macOS з Node, встановленим через Homebrew, +виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується +навіть якщо Gateway працює справно. -### 2c) Перевизначення провайдера OAuth Codex +### 2c) Перевизначення провайдера Codex OAuth -Якщо ви раніше додали застарілі налаштування транспорту OpenAI в +Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях -провайдера OAuth Codex, який новіші випуски використовують автоматично. Doctor -попереджає, коли бачить ці старі налаштування транспорту поруч із Codex OAuth, +провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor +попереджає, коли бачить ці старі налаштування транспорту разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й -повернути вбудовану поведінку маршрутизації/резервного переходу. Користувацькі -проксі та перевизначення лише заголовків, як і раніше, підтримуються й не -викликають цього попередження. +повернути вбудовану маршрутизацію/поведінку fallback. Користувацькі проксі та +перевизначення лише заголовків, як і раніше, підтримуються і не викликають +цього попередження. ### 3) Міграції застарілого стану (структура на диску) -Doctor може мігрувати старіші структури на диску в поточну структуру: +Doctor може мігрувати старіші структури на диску до поточної структури: -- Сховище sessions + transcripts: +- Сховище сесій + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог agent: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий id облікового запису: `default`) + - до `~/.openclaw/credentials/whatsapp//...` (ID облікового запису за замовчуванням: `default`) -Ці міграції виконуються в режимі best-effort та є ідемпотентними; doctor виведе попередження, якщо -він залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує -застарілі sessions + каталог agent під час запуску, тож history/auth/models потрапляють -до шляху для конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно +Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, коли +залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує +застарілі сесії + каталог agent під час запуску, тож історія/автентифікація/моделі +потрапляють у шлях для конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map Talk тепер -порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють -повторних порожніх змін `doctor --fix`. +порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють +повторних no-op змін у `doctor --fix`. -### 3a) Міграції застарілого маніфесту Plugin +### 3a) Міграції застарілих маніфестів плагінів -Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів -можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor сканує всі встановлені маніфести плагінів на наявність застарілих верхньорівневих ключів +можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` @@ -293,283 +294,289 @@ Doctor сканує всі встановлені маніфести Plugin на якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. -### 3b) Міграції застарілого сховища Cron +### 3b) Міграції сховища застарілих Cron -Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово, -або `cron.store`, якщо перевизначено) на наявність старих форм завдань, які scheduler усе ще +Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` за замовчуванням, +або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які scheduler усе ще приймає для сумісності. Поточні очищення Cron включають: - `jobId` → `id` - `schedule.cron` → `schedule.expr` -- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` -- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` -- псевдоніми доставки `provider` у payload → явний `delivery.channel` -- прості застарілі резервні завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` +- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` +- верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` +- псевдоніми delivery `provider` у payload → явний `delivery.channel` +- прості застарілі резервні jobs для webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` -Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це -без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним -режимом доставки не через webhook, doctor попереджає й залишає таке завдання для ручної перевірки. +Doctor автоматично мігрує jobs з `notify: true`, лише коли може зробити це без +зміни поведінки. Якщо job поєднує застарілий резервний notify з уже наявним +режимом delivery не для webhook, doctor попереджає й залишає цей job для ручної перевірки. ### 3c) Очищення блокувань сесій -Doctor сканує кожен каталог сесій agent на наявність застарілих файлів write-lock — файлів, що залишилися -після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: -шлях, PID, чи PID досі активний, вік блокування і чи -вважається воно застарілим (мертвий PID або старіше за 30 хвилин). У режимі `--fix` / `--repair` -він автоматично видаляє застарілі файли блокування; інакше лише друкує примітку й -радить перезапустити з `--fix`. +Doctor сканує каталог сесій кожного agent на наявність застарілих файлів write-lock — файлів, залишених +після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: +шлях, PID, чи PID ще живий, вік блокування та чи вважається воно +застарілим (PID не існує або вік перевищує 30 хвилин). У режимі `--fix` / `--repair` +він автоматично видаляє застарілі файли блокування; інакше друкує примітку та +пропонує повторити запуск із `--fix`. ### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека) Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите -sessions, credentials, logs і config (якщо у вас немає резервних копій в іншому місці). +сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій в іншому місці). Doctor перевіряє: -- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує заново створити - каталог і нагадує, що він не може відновити відсутні дані. -- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права - доступу (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). -- **Каталог стану macOS у хмарній синхронізації**: попереджає, коли стан розв’язується в iCloud Drive +- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує відтворити + каталог і нагадує, що не може відновити втрачені дані. +- **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи + (і виводить підказку `chown`, якщо виявлено невідповідність owner/group). +- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розв’язується в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або - `~/Library/CloudStorage/...`, оскільки шляхи з резервним sync можуть спричиняти повільніший I/O - і гонки блокувань/sync. -- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розв’язується на джерело монтування `mmcblk*`, - оскільки випадковий I/O на носіях SD або eMMC може бути повільнішим і швидше зношуватися - під час записів sessions і credentials. -- **Каталоги sessions відсутні**: `sessions/` і каталог сховища sessions - потрібні для збереження history та уникнення збоїв `ENOENT`. -- **Невідповідність transcript**: попереджає, коли в нещодавніх записах sessions відсутні - файли transcript. -- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний transcript має лише один - рядок (history не накопичується). -- **Кілька каталогів стану**: попереджає, коли існує кілька тек `~/.openclaw` у різних - домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може - розділятися між встановленнями). + `~/Library/CloudStorage/...`, оскільки шляхи з резервною синхронізацією можуть спричиняти повільніший I/O + і гонки блокування/синхронізації. +- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розв’язується до джерела монтування `mmcblk*`, + оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій + під час записів сесій і облікових даних. +- **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій + потрібні для збереження історії та уникнення збоїв `ENOENT`. +- **Невідповідність транскриптів**: попереджає, коли в недавніх записах сесій бракує + файлів транскриптів. +- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний транскрипт містить лише один + рядок (історія не накопичується). +- **Кілька каталогів стану**: попереджає, коли існує кілька папок `~/.openclaw` у різних + домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує кудись іще (історія може + розділитися між встановленнями). - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити - його на віддаленому хості (саме там зберігається стан). -- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є - доступним для читання групою/усіма, і пропонує посилити права до `600`. + його на віддаленому хості (стан зберігається там). +- **Дозволи файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний + для читання групі/усім, і пропонує посилити до `600`. -### 5) Стан автентифікації моделі (строк дії OAuth) +### 5) Стан автентифікації моделей (строк дії OAuth) -Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли строк дії токенів -наближається до завершення або вже завершився, і може оновити їх, коли це безпечно. Якщо профіль -OAuth/token Anthropic застарів, він пропонує ключ Anthropic API або +Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени +наближаються до завершення строку дії або вже прострочені, і може оновити їх, коли це безпечно. Якщо профіль +Anthropic OAuth/token застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. Коли оновлення OAuth остаточно завершується невдачею (наприклад `refresh_token_reused`, -`invalid_grant` або коли провайдер повідомляє, що потрібно знову увійти), doctor повідомляє, +`invalid_grant` або коли провайдер повідомляє, що потрібно увійти знову), doctor повідомляє, що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, яку слід виконати. Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні до використання через: -- короткі cooldown-и (обмеження швидкості/тайм-аути/збої автентифікації) -- довші вимкнення (збої білінгу/кредиту) +- короткі cooldown-и (rate limits/timeouts/auth failures) +- довші вимкнення (billing/credit failures) -### 6) Валідація моделі hooks +### 6) Перевірка моделі hooks -Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель у -каталозі та allowlist і попереджає, якщо воно не буде розв’язане або не дозволене. +Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за +каталогом і allowlist та попереджає, якщо воно не буде розв’язане або заборонене. ### 7) Відновлення образу sandbox -Коли sandboxing увімкнено, doctor перевіряє Docker-образи та пропонує зібрати їх або -перемкнутися на застарілі назви, якщо поточний образ відсутній. +Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або +переключитися на застарілі назви, якщо поточний образ відсутній. -### 7b) Залежності середовища виконання вбудованого Plugin +### 7b) Runtime-залежності вбудованих плагінів -Doctor перевіряє залежності середовища виконання лише для тих вбудованих Plugin, які активні в -поточній конфігурації або увімкнені типовим значенням у вбудованому маніфесті, наприклад +Doctor перевіряє runtime-залежності лише для вбудованих плагінів, які активні в +поточній конфігурації або ввімкнені типовим значенням їхнього вбудованого маніфесту, наприклад `plugins.entries.discord.enabled: true`, застаріле -`channels.discord.enabled: true` або типовий увімкнений вбудований провайдер. Якщо якихось -не вистачає, doctor повідомляє про пакети й встановлює їх у режимі -`openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugin, як і раніше, +`channels.discord.enabled: true` або вбудований провайдер, увімкнений за замовчуванням. Якщо якихось +залежностей бракує, doctor повідомляє пакунки й встановлює їх у режимі +`openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні плагіни, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не -встановлює залежності для довільних шляхів Plugin. +встановлює залежності для довільних шляхів плагінів. -### 8) Міграції служби Gateway і підказки з очищення +Gateway і локальний CLI також можуть за вимогою виправляти runtime-залежності активних вбудованих плагінів +перед імпортом вбудованого плагіна. Ці встановлення +обмежені коренем встановлення runtime плагіна, запускаються з вимкненими скриптами, не +записують package lock і захищені блокуванням кореня встановлення, щоб одночасні запуски CLI +або Gateway не змінювали те саме дерево `node_modules` одночасно. -Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і -пропонує видалити їх та встановити службу OpenClaw з використанням поточного -порту gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. -Іменовані за профілем служби gateway OpenClaw вважаються повноцінними і не -позначаються як "додаткові". +### 8) Міграції сервісів Gateway і підказки щодо очищення -### 8b) Стартова міграція Matrix +Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і +пропонує видалити їх та встановити сервіс OpenClaw з поточним портом gateway. +Він також може сканувати додаткові сервіси, схожі на gateway, і виводити підказки щодо очищення. +Сервіси gateway OpenClaw з назвами профілів вважаються повноцінними й не +позначаються як "extra." -Коли обліковий запис каналу Matrix має очікувальну або доступну до виконання міграцію застарілого стану, -doctor (у режимі `--fix` / `--repair`) створює знімок стану перед міграцією, а потім -запускає кроки міграції best-effort: міграцію застарілого стану Matrix і підготовку -застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а +### 8b) Міграція Matrix під час запуску + +Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, +doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім +виконує кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку +застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. -### 8c) Спарювання пристроїв і дрейф автентифікації +### 8c) Сполучення пристроїв і дрейф автентифікації -Doctor тепер перевіряє стан спарювання пристроїв як частину звичайної перевірки працездатності. +Doctor тепер перевіряє стан сполучення пристроїв як частину звичайної перевірки працездатності. Що він повідомляє: -- очікувальні запити на перше спарювання -- очікувальні оновлення ролі для вже спарених пристроїв -- очікувальні оновлення scope для вже спарених пристроїв -- виправлення невідповідності public key, коли id пристрою все ще збігається, але - ідентичність пристрою більше не відповідає схваленому запису -- спарені записи без активного токена для схваленої ролі -- спарені токени, чиї scope відхиляються від базового профілю схваленого спарювання +- очікувані перші запити на сполучення +- очікувані оновлення ролей для вже сполучених пристроїв +- очікувані оновлення scope для вже сполучених пристроїв +- виправлення невідповідностей public key, коли ID пристрою все ще збігається, але + ідентичність пристрою більше не збігається зі схваленим записом +- записи про сполучення, у яких немає активного токена для схваленої ролі +- токени сполучення, scope яких відхилилися від схваленого базового рівня сполучення - локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope -Doctor не схвалює запити на спарювання автоматично й не виконує автоматичну ротацію токенів пристрою. Натомість -він виводить точні наступні кроки: +Doctor не схвалює автоматично запити на сполучення і не виконує автоматичну ротацію токенів пристроїв. Натомість +він друкує точні наступні кроки: -- перегляньте очікувальні запити через `openclaw devices list` -- схваліть точний запит через `openclaw devices approve ` -- виконайте ротацію нового токена через `openclaw devices rotate --device --role ` -- видаліть і повторно схваліть застарілий запис через `openclaw devices remove ` +- переглянути очікувані запити за допомогою `openclaw devices list` +- схвалити точний запит за допомогою `openclaw devices approve ` +- ротувати новий токен за допомогою `openclaw devices rotate --device --role ` +- видалити та повторно схвалити застарілий запис за допомогою `openclaw devices remove ` -Це закриває типову прогалину "вже спарено, але все одно з’являється pairing required": -doctor тепер розрізняє перше спарювання, очікувальні оновлення ролі/scope -та дрейф застарілого токена/ідентичності пристрою. +Це закриває типову прогалину "вже сполучено, але все одно отримується pairing required": +doctor тепер розрізняє перше сполучення, очікувані оновлення ролі/scope +та дрейф застарілих токенів/ідентичності пристрою. ### 9) Попередження безпеки -Doctor виводить попередження, коли провайдер відкритий для DM без allowlist, або -коли політику налаштовано в небезпечний спосіб. +Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або +коли політику налаштовано небезпечним чином. ### 10) systemd linger (Linux) -Якщо запуск виконується як користувацька служба systemd, doctor забезпечує ввімкнення lingering, щоб +Якщо запуск відбувається як сервіс користувача systemd, doctor переконується, що linger увімкнено, щоб gateway залишався активним після виходу з системи. -### 11) Стан workspace (Skills, Plugins і застарілі каталоги) +### 11) Стан workspace (skills, плагіни та застарілі каталоги) -Doctor виводить зведення стану workspace для типового agent: +Doctor виводить підсумок стану workspace для agent за замовчуванням: - **Стан Skills**: кількість доступних, missing-requirements і allowlist-blocked skills. - **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace існують поруч із поточним workspace. -- **Стан Plugin**: кількість завантажених/вимкнених/з помилками plugins; перелічує id plugins для всіх - помилок; повідомляє про можливості bundle plugin. -- **Попередження про сумісність Plugin**: позначає plugins, які мають проблеми сумісності з - поточним середовищем виконання. -- **Діагностика Plugin**: показує всі попередження або помилки часу завантаження, які виводить - реєстр plugin. +- **Стан плагінів**: кількість loaded/disabled/errored плагінів; перелічує ID плагінів для будь-яких + помилок; повідомляє про можливості вбудованих плагінів. +- **Попередження про сумісність плагінів**: позначає плагіни, які мають проблеми сумісності з + поточним runtime. +- **Діагностика плагінів**: показує будь-які попередження або помилки часу завантаження, які виводить + реєстр плагінів. -### 11b) Розмір bootstrap-файлу +### 11b) Розмір bootstrap-файлів -Doctor перевіряє, чи не наближаються bootstrap-файли workspace (наприклад `AGENTS.md`, -`CLAUDE.md` або інші ін’єктовані контекстні файли) до налаштованого -ліміту символів або не перевищують його. Він повідомляє для кожного файла необроблену й ін’єктовану кількість символів, відсоток обрізання, -причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих -символів як частку від загального бюджету. Коли файли обрізаються або наближаються до ліміту, +Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`, +`CLAUDE.md` або інші впроваджені файли контексту) наближаються до налаштованого +ліміту символів або перевищують його. Він повідомляє для кожного файла сирі та впроваджені кількості символів, відсоток +обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість впроваджених +символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion -Doctor перевіряє, чи встановлено автодоповнення tab для поточної оболонки +Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell): - Якщо профіль оболонки використовує повільний динамічний шаблон completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого - варіанта з кешованим файлом. + варіанту з кешованим файлом. - Якщо completion налаштовано в профілі, але файл кешу відсутній, - doctor автоматично відновлює кеш. + doctor автоматично заново генерує кеш. - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). -Запустіть `openclaw completion --write-state`, щоб вручну перевідтворити кеш. +Запустіть `openclaw completion --write-state`, щоб згенерувати кеш вручну. ### 12) Перевірки автентифікації Gateway (локальний токен) -Doctor перевіряє готовність автентифікації локального токена gateway. +Doctor перевіряє готовність локальної токен-автентифікації gateway. -- Якщо режиму токена потрібен токен і немає його джерела, doctor пропонує згенерувати його. -- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. -- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. +- Якщо режим токена потребує токен і джерело токена відсутнє, doctor пропонує згенерувати його. +- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. +- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано токен SecretRef. -### 12b) Відновлення в режимі лише читання з урахуванням SecretRef +### 12b) Виправлення з урахуванням SecretRef у режимі лише читання -Деяким потокам відновлення потрібно перевіряти налаштовані credentials без послаблення поведінки fail-fast середовища виконання. +Деякі потоки виправлення мають перевіряти налаштовані облікові дані, не послаблюючи при цьому fail-fast поведінку під час виконання. -- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільового відновлення конфігурації. -- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. -- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення, ніби токен відсутній. +- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. +- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, якщо вони доступні. +- Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення про відсутність токена. ### 13) Перевірка працездатності Gateway + перезапуск -Doctor запускає перевірку працездатності й пропонує перезапустити gateway, якщо той +Doctor виконує перевірку працездатності й пропонує перезапустити gateway, якщо він виглядає несправним. -### 13b) Готовність пошуку в пам’яті +### 13b) Готовність memory search -Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті -для типового agent. Поведінка залежить від налаштованого backend і провайдера: +Doctor перевіряє, чи готовий налаштований провайдер ембедингів memory search +для agent за замовчуванням. Поведінка залежить від налаштованого backend і провайдера: - **QMD backend**: перевіряє, чи доступний і чи може запускатися бінарний файл `qmd`. - Якщо ні, виводить вказівки щодо виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла. + Якщо ні, виводить підказки для виправлення, зокрема npm-пакунок і варіант ручного шляху до бінарного файла. - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного - URL локальної/завантажуваної віддаленої моделі. Якщо їх немає, пропонує перейти на віддаленого провайдера. + URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого провайдера. - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ - у середовищі або в сховищі автентифікації. Якщо його немає, виводить практичні підказки щодо виправлення. -- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, потім пробує кожного віддаленого - провайдера в порядку автоматичного вибору. + у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. +- **Auto provider**: спочатку перевіряє доступність локальної моделі, потім пробує кожен віддалений + провайдер у порядку автовибору. -Коли результат перевірки gateway доступний (gateway був справним на момент -перевірки), doctor звіряє його результат із конфігурацією, видимою CLI, і зазначає +Коли результат перевірки gateway доступний (gateway був справний на момент +перевірки), doctor звіряє цей результат із конфігурацією, видимою CLI, і зазначає будь-які розбіжності. -Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. +Використовуйте `openclaw memory status --deep`, щоб перевірити готовність ембедингів під час виконання. -### 14) Попередження про стан каналу +### 14) Попередження про стан каналів -Якщо gateway справний, doctor запускає перевірку стану каналу й повідомляє -попередження з рекомендованими виправленнями. +Якщо gateway справний, doctor виконує перевірку стану каналів і повідомляє +попередження разом із запропонованими виправленнями. -### 15) Аудит конфігурації supervisor + відновлення +### 15) Аудит конфігурації supervisor + виправлення Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на -відсутні або застарілі типові значення (наприклад, залежності systemd від network-online та -затримку перезапуску). Коли він знаходить невідповідність, він рекомендує оновлення й може -переписати файл служби/завдання до поточних типових значень. +предмет відсутніх або застарілих значень за замовчуванням (наприклад, залежностей systemd network-online та +затримки перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення й може +перезаписати файл сервісу/завдання до поточних значень за замовчуванням. Примітки: -- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. -- `openclaw doctor --yes` приймає типові запити на відновлення. +- `openclaw doctor` запитує підтвердження перед перезаписом конфігурації supervisor. +- `openclaw doctor --yes` приймає типові запити на виправлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. -- Якщо автентифікація токеном потребує токена, а `gateway.auth.token` керується через SecretRef, doctor під час встановлення/відновлення служби перевіряє SecretRef, але не зберігає розв’язані відкриті значення токена в метаданих середовища служби supervisor. -- Якщо автентифікація токеном потребує токена, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення та надає практичні вказівки. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно встановлено. -- Для Linux user-systemd units перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. -- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. +- Якщо для автентифікації токеном потрібен токен і `gateway.auth.token` керується через SecretRef, doctor під час встановлення/виправлення сервісу перевіряє SecretRef, але не зберігає розв’язані значення токенів відкритим текстом у метадані середовища сервісу supervisor. +- Якщо для автентифікації токеном потрібен токен і налаштований токен SecretRef не розв’язується, doctor блокує шлях встановлення/виправлення та виводить практичні рекомендації. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/виправлення, доки режим не буде явно встановлено. +- Для Linux user-systemd units перевірки дрейфу токена в doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації сервісу. +- Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`. -### 16) Діагностика середовища виконання + порту Gateway +### 16) Діагностика runtime Gateway + порту -Doctor перевіряє середовище виконання служби (PID, останній статус завершення) і попереджає, коли -службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів -на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущено, -SSH-тунель). +Doctor перевіряє runtime сервісу (PID, останній статус завершення) і попереджає, коли +сервіс установлено, але він фактично не працює. Він також перевіряє конфлікти портів +на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже +працює, SSH-тунель). -### 17) Найкращі практики середовища виконання Gateway +### 17) Найкращі практики runtime Gateway -Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій +Doctor попереджає, коли сервіс gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, -а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не -завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, коли +а шляхи менеджерів версій можуть ламатися після оновлень, оскільки сервіс не +завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). ### 18) Запис конфігурації + метадані wizard -Doctor зберігає всі зміни конфігурації й проставляє метадані wizard, щоб зафіксувати +Doctor зберігає всі зміни конфігурації та ставить позначку в метаданих wizard, щоб зафіксувати запуск doctor. ### 19) Поради щодо workspace (резервне копіювання + система пам’яті) @@ -577,10 +584,10 @@ Doctor зберігає всі зміни конфігурації й прост Doctor пропонує систему пам’яті workspace, якщо її немає, і виводить пораду щодо резервного копіювання, якщо workspace ще не перебуває під git. -Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб ознайомитися з повним посібником щодо +Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). ## Пов’язане -- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) +- [Усунення проблем Gateway](/uk/gateway/troubleshooting) - [Runbook Gateway](/uk/gateway) diff --git a/docs/uk/help/testing-live.md b/docs/uk/help/testing-live.md index 2c85a7093..f53fa33d7 100644 --- a/docs/uk/help/testing-live.md +++ b/docs/uk/help/testing-live.md @@ -1,109 +1,109 @@ --- read_when: - - Запуск live smoke-тестів для матриці моделей / бекенда CLI / ACP / постачальника медіа - - Налагодження визначення облікових даних для live-тестів - - Додавання нового live-тесту, специфічного для постачальника + - Запуск живих smoke-тестів для матриці моделей / бекенду CLI / ACP / медіапровайдера + - Налагодження визначення облікових даних для живих тестів + - Додавання нового живого тесту, специфічного для провайдера sidebarTitle: Live tests -summary: 'Live (з доступом до мережі) тести: матриця моделей, бекенди CLI, ACP, постачальники медіа, облікові дані' -title: 'Тестування: live suites' +summary: 'Живі тести (із доступом до мережі): матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' +title: 'Тестування: живі набори тестів' x-i18n: - generated_at: "2026-04-24T15:33:58Z" + generated_at: "2026-04-24T19:51:02Z" model: gpt-5.4 provider: openai - source_hash: 3e9a76038dbfe50271225bd3b5405e5dea9a1a19d7591da2114709009f5de66e + source_hash: a221bb784b38b3dfd97c32f862f761cc9a655f904826afc181822f463bc4f753 source_path: help/testing-live.md workflow: 15 --- -Для швидкого старту, раннерів QA, unit/integration-наборів і Docker-потоків див. -[Тестування](/uk/help/testing). Ця сторінка охоплює **live** (з доступом до мережі) набори -тестів: матрицю моделей, бекенди CLI, ACP і live-тести постачальників медіа, а також -обробку облікових даних. +Для швидкого старту, QA runners, unit/integration наборів тестів і Docker-потоків див. +[Тестування](/uk/help/testing). Ця сторінка охоплює **живі** (із доступом до мережі) набори +тестів: матрицю моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також +роботу з обліковими даними. -## Live: перевірка можливостей Android node +## Живий режим: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка зараз оголошена** підключеним Android node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яка наразі оголошена** підключеним Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Налаштування перед запуском/вручну (набір тестів не встановлює/не запускає/не спаровує застосунок). - - Перевірка `node.invoke` Gateway для вибраного Android node по кожній команді окремо. + - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює/не запускає/не з’єднує застосунок у пару). + - Покомандна перевірка gateway `node.invoke` для вибраного Android Node. - Обов’язкове попереднє налаштування: - - Android-застосунок уже підключено й спаровано з Gateway. + - Android застосунок уже підключено та з’єднано в пару з Gateway. - Застосунок утримується на передньому плані. - - Для можливостей, які ви очікуєте як успішні, надано дозволи/підтвердження захоплення. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke-тест моделей (ключі профілів) +## Живий режим: smoke-тест моделі (ключі профілю) -Live-тести поділено на два рівні, щоб ми могли ізолювати збої: +Живі тести розділено на два рівні, щоб можна було ізолювати збої: -- «Пряма модель» показує, чи може постачальник/модель взагалі відповісти з наданим ключем. -- «Smoke-тест Gateway» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). +- «Безпосередня модель» показує, чи може провайдер/модель взагалі відповісти з указаним ключем. +- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сеанси, історія, інструменти, політика sandbox тощо). -### Рівень 1: Пряме завершення моделі (без gateway) +### Рівень 1: Безпосереднє завершення моделлю (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Запустити невелике completion для кожної моделі (і цільові регресійні перевірки там, де потрібно) + - Запустити невелике completion для кожної моделі (і цільові регресійні перевірки, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на smoke-тесті gateway +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір тестів; інакше його буде пропущено, щоб зберегти фокус `pnpm test:live` на gateway smoke - Як вибрати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all-прогонів за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого обмеження. - - Вичерпні прогони використовують `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут для всього прямого тесту моделей. За замовчуванням: 60 хвилин. - - Прямі перевірки моделей за замовчуванням виконуються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. -- Як вибрати постачальників: + - Для modern/all перевірок за замовчуванням використовується підібране обмеження високосигнальних моделей; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. + - Для вичерпних перевірок використовується `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього тесту безпосередньої моделі. За замовчуванням: 60 хвилин. + - За замовчуванням перевірки безпосередньої моделі виконуються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. +- Як вибрати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні значення env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб жорстко вимагати **лише сховище профілів** + - За замовчуванням: сховище профілів і резервні значення з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API постачальника зламане / ключ недійсний» від «зламаний конвеєр gateway agent» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки виклику інструментів) + - Відокремлює «API провайдера зламано / ключ недійсний» від «конвеєр gateway agent зламано» + - Містить невеликі ізольовані регресії (приклад: повторення міркувань OpenAI Responses/Codex Responses + потоки виклику інструментів) -### Рівень 2: Smoke-тест Gateway + dev agent (те, що насправді робить "@openclaw") +### Рівень 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти gateway in-process - - Створити/змінити сесію `agent:dev:*` (з перевизначенням моделі для кожного запуску) - - Ітерувати моделі з ключами й перевіряти: + - Підняти in-process Gateway + - Створити/пропатчити сеанс `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітеруватися по моделях із ключами та перевіряти: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (перевірка читання) + - що реальний виклик інструмента працює (перевірка read) - необов’язкові додаткові перевірки інструментів (перевірка exec+read) - - що регресійні шляхи OpenAI (лише виклик інструмента → подальший крок) і далі працюють -- Подробиці перевірок (щоб ви могли швидко пояснювати збої): - - перевірка `read`: тест записує nonce-файл у workspace й просить agent виконати `read` і повернути nonce назад. - - перевірка `exec+read`: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім через `read` прочитати його назад. - - перевірка зображення: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - що регресійні шляхи OpenAI (лише виклик інструмента → подальший крок) продовжують працювати +- Подробиці перевірок (щоб можна було швидко пояснювати збої): + - перевірка `read`: тест записує nonce-файл у workspace і просить agent виконати `read` цього файлу та повернути nonce. + - перевірка `exec+read`: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - перевірка зображення: тест додає згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибрати моделі: - - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для modern/all gateway-прогонів за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого обмеження. -- Як вибрати постачальників (уникнути «OpenRouter для всього»): + - Для modern/all gateway-перевірок за замовчуванням використовується підібране обмеження високосигнальних моделей; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. +- Як вибрати провайдерів (уникнути сценарію «OpenRouter everything»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки інструментів і зображень у цьому live-тесті завжди ввімкнені: - - перевірка `read` + перевірка `exec+read` (навантаження на інструменти) - - перевірка зображення виконується, коли модель заявляє підтримку вхідних зображень +- Перевірки інструментів і зображень у цьому живому тесті завжди ввімкнені: + - перевірка `read` + перевірка `exec+read` (стрес-тест інструментів) + - перевірка зображення виконується, коли модель оголошує підтримку введення зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Вбудований agent пересилає multimodal-повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) + - Вбудований agent передає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки дозволені) Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: @@ -112,26 +112,26 @@ openclaw models list openclaw models list --json ``` -## Live: smoke-тест бекенда CLI (Claude, Codex, Gemini або інші локальні CLI) +## Живий режим: smoke-тест бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent із використанням локального бекенда CLI, не торкаючись вашої типової конфігурації. -- Типові значення smoke-тесту для конкретного бекенда зберігаються у визначенні `cli-backend.ts` у розширенні-власнику. +- Мета: перевірити конвеєр Gateway + agent з використанням локального бекенду CLI, не торкаючись вашої типової конфігурації. +- Типові значення smoke-тестів для бекенду зберігаються разом із визначенням `cli-backend.ts` у відповідному розширенні. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Типові значення: - - Типовий постачальник/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих Plugin бекенда CLI-власника. +- Значення за замовчуванням: + - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` + - Поведінка команди/аргументів/зображень походить із метаданих Plugin бекенду CLI, якому він належить. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надсилати реальне вкладення-зображення (шляхи впроваджуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість впровадження в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи вбудовуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість вбудовування в prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображень, коли встановлено `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий крок і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності того самого сеансу Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -147,7 +147,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Docker-рецепти для окремих постачальників: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -158,28 +158,28 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-раннер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke-тест CLI-бекенда всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke-тесту CLI з розширення-власника, а потім встановлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований префікс із правом запису в `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносної OAuth-підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він підтверджує прямий виклик `claude -p` у Docker, а потім запускає два кроки Gateway CLI-бекенда без збереження env-змінних ключа Anthropic API. Ця гілка підписки за замовчуванням вимикає перевірки Claude MCP/tool і image, оскільки зараз Claude маршрутизує використання сторонніх застосунків через додаткове тарифікування usage замість звичайних лімітів плану підписки. -- Live smoke-тест CLI-бекенда тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий крок, крок класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. -- Типовий smoke-тест Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає живий smoke-тест CLI-бекенду всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke-тесту CLI з відповідного розширення, а потім установлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований префікс із правом запису в `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносного OAuth підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два кроки Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Цей маршрут підписки за замовчуванням вимикає перевірки Claude MCP/tool і зображень, оскільки наразі Claude маршрутизує використання сторонніх застосунків через тарифікацію за додаткове використання, а не через звичайні ліміти плану підписки. +- Живий smoke-тест CLI-бекенду тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий крок, крок класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke-тест Claude також патчить сеанс із Sonnet на Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку. -## Live: smoke-тест ACP bind (`/acp spawn ... --bind here`) +## Живий режим: smoke-тест прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP з live ACP agent: +- Мета: перевірити реальний потік conversation-bind ACP із живим ACP agent: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову каналу повідомлень на місці - надіслати звичайне подальше повідомлення в тій самій розмові - - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної сесії ACP + - перевірити, що подальше повідомлення потрапляє в transcript прив’язаного сеансу ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Типові значення: - - ACP-агенти в Docker: `claude,codex,gemini` - - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст розмови у стилі Slack DM +- Значення за замовчуванням: + - ACP agents у Docker: `claude,codex,gemini` + - ACP agent для прямого `pnpm test:live ...`: `claude` + - Синтетичний канал: контекст розмови в стилі особистих повідомлень Slack - Бекенд ACP: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -190,8 +190,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2` - Примітки: - - Ця гілка використовує поверхню gateway `chat.send` з адмінськими синтетичними полями originating-route, щоб тести могли додавати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів Plugin `acpx` для вибраного ACP harness agent. + - У цьому маршруті використовується поверхня gateway `chat.send` з адміністративними полями synthetic originating-route, щоб тести могли приєднувати контекст каналу повідомлень, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр agents Plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -207,7 +207,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Docker-рецепти для окремих агентів: +Рецепти Docker для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -217,36 +217,37 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-раннер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke-тест ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke-тест прив’язки ACP послідовно для всіх підтримуваних живих CLI agents: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підвантажує `~/.profile`, переносить відповідні матеріали автентифікації CLI в контейнер, встановлює `acpx` у npm-префікс із правом запису, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні постачальника з підвантаженого профілю доступними для дочірнього harness CLI. +- Він підвантажує `~/.profile`, розміщує відповідний матеріал автентифікації CLI в контейнері, установлює `acpx` у npm-префікс із правом запису, а потім установлює запитуваний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з підвантаженого profile доступними для дочірнього harness CLI. -## Live: smoke-тест harness app-server Codex +## Живий режим: smoke-тест harness app-server Codex -- Мета: перевірити harness Codex, яким володіє Plugin, через звичайний метод Gateway +- Мета: перевірити Codex harness, що належить Plugin, через звичайний метод gateway `agent`: - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший крок gateway agent до `openai/gpt-5.2` із примусово вибраним harness Codex - - надіслати другий крок до тієї самої сесії OpenClaw і перевірити, що потік - app-server може відновитися + - надіслати перший крок gateway agent до `openai/gpt-5.2` із примусово + ввімкненим Codex harness + - надіслати другий крок до того самого сеансу OpenClaw і перевірити, що потік + app-server можна відновити - виконати `/codex status` і `/codex models` через той самий шлях команди gateway - - необов’язково виконати дві Guardian-рецензовані ескаловані shell-перевірки: одну безпечну - команду, яку слід схвалити, і одне фальшиве вивантаження секрету, яке має бути - відхилене, щоб agent перепитав + - за потреби виконати дві ескальовані shell-перевірки, переглянуті Guardian: одну + безпечну команду, яку має бути схвалено, і одне фальшиве завантаження секрету, + яке має бути відхилено, щоб agent перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `openai/gpt-5.2` - Необов’язкова перевірка зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Необов’язкова перевірка MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke-тест установлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти, непомітно переключившись на PI. -- Автентифікація: автентифікація app-server Codex з локального входу в підписку Codex. Docker - smoke-тести також можуть надавати `OPENAI_API_KEY` для не-Codex перевірок, де це застосовно, +- Smoke-тест установлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти перевірку, непомітно переключившись на PI. +- Автентифікація: автентифікація Codex app-server із локального входу в підписку Codex. + Docker smoke-тести також можуть передавати `OPENAI_API_KEY` для не-Codex перевірок, де це застосовно, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -270,30 +271,30 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-раннер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. - Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у змонтований npm-префікс - із правом запису, підготовлює дерево вихідного коду, а потім запускає лише live-тест harness Codex. -- Docker за замовчуванням вмикає перевірки image, MCP/tool і Guardian. Установіть + автентифікації CLI Codex, якщо вони є, установлює `@openai/codex` у змонтований npm + префікс із правом запису, готує дерево вихідного коду, а потім запускає лише живий тест Codex-harness. +- У Docker перевірки зображення, MCP/tool і Guardian увімкнені за замовчуванням. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний - прогін. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфігурації live- + запуск. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфігурації живого тесту, щоб застарілі псевдоніми або fallback на PI не могли приховати регресію - harness Codex. + Codex harness. -### Рекомендовані live-рецепти +### Рекомендовані живі рецепти -Вузькі, явні allowlist працюють найшвидше й найменш схильні до збоїв: +Вузькі, явні allowlist — найшвидші та найменш схильні до збоїв: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, gateway smoke-тест: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів у кількох постачальників: +- Виклик інструментів для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (ключ API Gemini + Antigravity): @@ -302,36 +303,36 @@ pnpm test:docker:live-codex-harness Примітки: -- `google/...` використовує API Gemini (ключ API). -- `google-antigravity/...` використовує міст OAuth Antigravity (кінцева точка agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості інструментів). -- Gemini API порівняно з Gemini CLI: - - API: OpenClaw викликає розміщений Google API Gemini через HTTP (ключ API / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). +- `google/...` використовує Gemini API (ключ API). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint agent у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- Gemini API проти Gemini CLI: + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація ключем API / профілем); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). -## Live: матриця моделей (що ми покриваємо) +## Живий режим: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (live вмикається опційно), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Фіксованого «списку моделей CI» немає (живий режим — opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний набір smoke-тестів (виклик інструментів + image) +### Сучасний набір smoke-тестів (виклик інструментів + зображення) -Це прогін «типових моделей», який ми очікуємо зберігати працездатним: +Це запуск «поширених моделей», який ми очікуємо зберігати робочим: - OpenAI (не-Codex): `openai/gpt-5.2` - OpenAI Codex OAuth: `openai-codex/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) +- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - DeepSeek: `deepseek/deepseek-v4-flash` і `deepseek/deepseek-v4-pro` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустіть gateway smoke-тест із tools + image: +Запуск gateway smoke з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель з кожної родини постачальників: +Виберіть щонайменше одну модель на кожне сімейство провайдерів: - OpenAI: `openai/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -342,79 +343,77 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (бажано мати): -- xAI: `xai/grok-4` (або остання доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас ввімкнено) +- xAI: `xai/grok-4` (або найновіша доступна) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яка у вас увімкнена) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання зображень (вкладення → multimodal-повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити пробу зображення. -### Агрегатори / альтернативні gateway +### Aggregators / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші постачальники, яких можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Інші провайдери, яких можна включити до живої матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні кінцеві точки): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoints): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зашити в документацію «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + які ключі доступні. +Порада: не намагайтеся жорстко зафіксувати в документації «усі моделі». Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині + ті ключі, що доступні. ## Облікові дані (ніколи не комітьте) -Live-тести визначають облікові дані так само, як і CLI. Практичні наслідки: +Живі тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, живі тести мають знаходити ті самі ключі. +- Якщо живий тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у live-тестах означає «ключі профілів») +- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в живих тестах означає «ключі профілю») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але не є основним сховищем ключів профілю) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий домашній каталог тесту; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` вилучаються, щоб перевірки не торкалися вашого реального host workspace. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілю) +- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускає `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб проби не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live: Deepgram (транскрипція аудіо) +## Живий режим Deepgram (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Live: BytePlus coding plan +## Живий режим BytePlus coding plan - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: медіа ComfyUI workflow +## Живий режим ComfyUI workflow media - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Перевіряє вбудовані шляхи comfy для зображень, відео і `music_generate` + - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації Plugin -## Live: генерація зображень +## Живий режим генерації зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований Plugin постачальника генерації зображень - - Завантажує відсутні env-змінні постачальників із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env-ключі API раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає постачальників без придатної автентифікації/профілю/моделі - - Проганяє стандартні варіанти генерації зображень через спільну runtime-можливість: - - `google:flash-generate` - - `google:pro-generate` - - `google:pro-edit` - - `openai:default-generate` -- Поточні вбудовані постачальники в покритті: + - Перелічує кожен зареєстрований Plugin провайдера генерації зображень + - Завантажує відсутні змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Проганяє кожен налаштований провайдер через спільний runtime генерації зображень: + - `:generate` + - `:edit`, коли провайдер оголошує підтримку редагування +- Поточні вбудовані провайдери, що охоплюються: - `fal` - `google` - `minimax` @@ -429,73 +428,90 @@ Live-тести визначають облікові дані так само, - Необов’язкова поведінка автентифікації: - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Live: генерація музики +Для шляху постачаного CLI додайте smoke-тест `infer` після того, як живий +тест провайдера/runtime пройде успішно: + +```bash +OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts +openclaw infer image providers --json +openclaw infer image generate \ + --model google/gemini-3.1-flash-image-preview \ + --prompt "Мінімалістичне пласке тестове зображення: один синій квадрат на білому тлі, без тексту." \ + --output ./openclaw-infer-image-smoke.png \ + --json +``` + +Це охоплює розбір аргументів CLI, визначення конфігурації/типового agent, активацію вбудованого +Plugin, відновлення залежностей runtime вбудованого комплекту на вимогу, спільний +runtime генерації зображень і живий запит до провайдера. + +## Живий режим генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний вбудований шлях постачальника генерації музики + - Перевіряє спільний вбудований шлях провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні постачальників із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env-ключі API раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає постачальників без придатної автентифікації/профілю/моделі - - Запускає обидва оголошені runtime-режими, коли вони доступні: + - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені режими runtime, коли вони доступні: - `generate` з вхідними даними лише у вигляді prompt - - `edit`, коли постачальник оголошує `capabilities.edit.enabled` - - Поточне покриття спільної гілки: + - `edit`, коли провайдер оголошує `capabilities.edit.enabled` + - Поточне покриття спільного маршруту: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний прогін + - `comfy`: окремий живий файл Comfy, а не ця спільна перевірка - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Live: генерація відео +## Живий режим генерації відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний вбудований шлях постачальника генерації відео - - За замовчуванням використовує безпечний для релізу шлях smoke-тесту: постачальники без FAL, один запит text-to-video на постачальника, односекундний prompt із лобстером і обмеження операції на кожного постачальника з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - FAL за замовчуванням пропускається, оскільки затримка черги на боці постачальника може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env-змінні постачальників із вашого login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env-ключі API раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає постачальників без придатної автентифікації/профілю/моделі + - Перевіряє спільний вбудований шлях провайдера генерації відео + - За замовчуванням використовує безпечний для релізу маршрут smoke-тесту: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt із лобстером і обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може суттєво збільшити час релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно запустити його + - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдерів без придатної автентифікації/профілю/моделі - За замовчуванням запускає лише `generate` - - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення, коли вони доступні: - - `imageToVideo`, коли постачальник оголошує `capabilities.imageToVideo.enabled` і вибраний постачальник/модель приймає локальний вхід зображення на основі буфера у спільному прогоні - - `videoToVideo`, коли постачальник оголошує `capabilities.videoToVideo.enabled` і вибраний постачальник/модель приймає локальний вхід відео на основі буфера у спільному прогоні - - Поточні оголошені, але пропущені постачальники `imageToVideo` у спільному прогоні: - - `vydra`, оскільки вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений URL зображення - - Покриття Vydra, специфічне для постачальника: + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні зображення на основі buffer у спільній перевірці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні відео на основі buffer у спільній перевірці + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільній перевірці: + - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення + - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video, а також гілку `kling`, яка за замовчуванням використовує fixture з віддаленим URL зображення - - Поточне live-покриття `videoToVideo`: + - цей файл запускає маршрут `veo3` text-to-video, а також маршрут `kling`, який за замовчуванням використовує fixture із віддаленим URL зображення + - Поточне живе покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені постачальники `videoToVideo` у спільному прогоні: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені еталонні URL `http(s)` / MP4 - - `google`, оскільки поточна спільна гілка Gemini/Veo використовує локальний вхід на основі буфера, а цей шлях не приймається у спільному прогоні - - `openai`, оскільки в поточній спільній гілці немає гарантій доступу до video inpaint/remix, специфічного для org + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільній перевірці: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі потребують віддалених URL-посилань `http(s)` / MP4 + - `google`, оскільки поточний спільний маршрут Gemini/Veo використовує локальні вхідні дані на основі buffer, а цей шлях не приймається в спільній перевірці + - `openai`, оскільки поточному спільному маршруту бракує гарантій доступу до video inpaint/remix, специфічних для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити до типового прогону кожного постачальника, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного постачальника під час агресивного smoke-прогону + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, зокрема FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження часу операції для кожного провайдера під час агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Media live harness +## Harness для живих медіатестів - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики та відео через один вбудований у репозиторій entrypoint - - Автоматично завантажує відсутні env-змінні постачальників із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до постачальників, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet mode залишається узгодженою + - Запускає спільні живі набори тестів для зображень, музики та відео через один вбудований у репозиторій entrypoint + - Автоматично завантажує відсутні змінні середовища провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір тестів до провайдерів, які наразі мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -504,4 +520,4 @@ Live-тести визначають облікові дані так само, ## Пов’язане -- [Тестування](/uk/help/testing) — набори unit, integration, QA і Docker +- [Тестування](/uk/help/testing) — unit, integration, QA і Docker набори тестів diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 554d9897d..88690a3a6 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,193 +1,192 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделей/provider-ів + - Додавання регресійних тестів для помилок моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що покриває кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-24T18:11:18Z" + generated_at: "2026-04-24T19:51:30Z" model: gpt-5.4 provider: openai - source_hash: 49c663fb7be88707007b1bd58e15c14d2e48a99b3b64b32817372d8e171528bf + source_hash: 437a49f67b775f63670f00efec63e268e02e74e072d92a645d427b975028e8be source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір -Docker-ранерів. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — інструкція «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває). -- Які команди запускати для поширених сценаріїв (локально, перед push, налагодження). -- Як live-тести знаходять облікові дані та вибирають моделі/provider-и. -- Як додавати регресії для реальних проблем моделей/provider-ів. +- Що охоплює кожен набір (і що він навмисно _не_ охоплює). +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Як live-тести знаходять облікові дані й вибирають моделі/провайдерів. +- Як додавати регресії для реальних проблем моделей/провайдерів. ## Швидкий старт У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` - Прямий цикл watch для Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- Пряме націлення на файл тепер також маршрутизує шляхи 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-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більшої впевненості: +Коли ви змінюєте тести або хочете більше впевненості: -- Coverage gate: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних provider-ів/моделей (потрібні справжні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): -- Live-набір (моделі + probe-и gateway для tool/image): `pnpm test:live` -- Точково запустити один live-файл у тихому режимі: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live model sweep: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер проходить текстовий хід плюс невеликий probe у стилі читання файла. - Моделі, чиї метадані вказують підтримку вхідних `image`, також проходять маленький image-хід. - Вимкніть додаткові probe-и через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої provider-а. - - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Тихий запуск одного live-файла: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker-обхід live-моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку в стилі читання файла. + Моделі, у метаданих яких заявлено вхід `image`, також виконують невеликий хід із зображенням. + Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдерів. + - Покриття в CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, який включає окремі matrix-job-и Docker live model, - поділені за provider-ом. - - Для точкових повторних запусків у 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`. - - Додавайте нові високосигнальні секрети provider-ів до `scripts/ci-hydrate-live-auth.sh`, + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - планових/release-викликачів. -- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - - Запускає Docker live-доріжку проти шляху app-server Codex, прив’язує синтетичний + запланованих/release-викликів. +- Native Codex smoke для bind-chat: `pnpm test:docker:live-codex-bind` + - Запускає Docker live-lane проти шляху app-server Codex, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і image-вкладення - проходять через native plugin binding, а не через ACP. + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення + маршрутизуються через native binding Plugin, а не через ACP. - Smoke-перевірка вартості 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, а - транскрипт assistant зберігає нормалізований `usage.cost`. + проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6 і що + транскрипт асистента зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний кейс, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, звужуйте live-тести через allowlist env vars, описані нижче. ## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди стоять поруч із основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR -і з ручного dispatch із mock provider-ами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного dispatch із mock parity gate, live Matrix lane та -live Telegram lane під керуванням Convex як паралельні job-и. `OpenClaw Release Checks` -запускає ті самі доріжки перед схваленням релізу. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і +через manual dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через manual dispatch із mock parity gate, live Matrix lane і +live Telegram lane під керуванням Convex як паралельні jobs. `OpenClaw Release Checks` +запускає ті самі lanes перед затвердженням релізу. - `pnpm openclaw qa suite` - Запускає сценарії QA на базі репозиторію безпосередньо на хості. - - Типово запускає кілька вибраних сценаріїв паралельно з ізольованими - worker-ами gateway. `qa-channel` за замовчуванням використовує concurrency 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування - кількості worker-ів або `--concurrency 1` для старої послідовної доріжки. - - Завершується з ненульовим кодом, якщо падає будь-який сценарій. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без помилкового коду завершення. - - Підтримує режими provider-ів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер provider-а на базі AIMock для експериментального - покриття fixture і protocol-mock без заміни сценарійно-орієнтованої - доріжки `mock-openai`. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими + worker-процесами gateway. `qa-channel` типово використовує concurrency 4 (обмежене + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість + worker-ів, або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо хоч один сценарій зазнав збою. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без коду завершення з помилкою. + - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття фікстур і protocol-mock без заміни lane `mock-openai`, який знає про сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір у тимчасовій Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - - Повторно використовує ті самі прапорці вибору provider-а/моделі, що й `qa suite`. - - Live-запуски передають до guest підтримувані вхідні дані автентифікації QA, які практично використовувати: - ключі provider-ів через env, шлях до конфігурації QA live provider-а і `CODEX_HOME`, якщо він заданий. - - Каталоги виводу мають залишатися під коренем репозиторію, щоб guest міг записувати назад через - змонтований workspace. - - Записує звичайний QA-звіт + підсумок, а також журнали Multipass у + - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. + - Live-запуски передають підтримувані QA-входи автентифікації, які практично використовувати в гостьовій системі: + ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він є. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + змонтований робочий простір. + - Записує звичайний 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, виконує неінтерактивний onboarding з API-ключем OpenAI, типово налаштовує Telegram, - перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, запускає doctor - і виконує один локальний хід агента проти mock endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму доріжку - встановлення з пакета для Discord. + - Збирає npm tarball із поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивний onboarding з OpenAI API key, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, + запускає doctor і виконує один локальний хід агента проти замоканого OpenAI endpoint. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane + встановлення з пакета з Discord. - `pnpm test:docker:npm-telegram-live` - - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding встановленого пакета, - налаштовує Telegram через встановлений CLI, а потім повторно використовує - live Telegram QA lane з цим установленим пакетом як SUT Gateway. - - Типове значення: `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. + - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding + встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує + live Telegram QA lane із цим встановленим пакетом як SUT Gateway. + - Типово використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/release установіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс - `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і Convex role secret присутні в CI, + `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 використовує - середовище `qa-live-shared` і оренду облікових даних Convex для CI. + - `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` і lease-и облікових даних Convex для CI. - `pnpm test:docker:bundled-channel-deps` - - Пакує і встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає bundled channel/Plugin через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає runtime-залежності - неналаштованих Plugin відсутніми, що перший налаштований запуск Gateway або doctor - встановлює runtime-залежності кожного bundled Plugin на вимогу, і що другий restart не - перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу npm-базу, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що post-update doctor кандидата - відновлює runtime-залежності bundled channel без postinstall-відновлення на боці harness. + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає вбудовані channel/plugins через редагування конфігурації. + - Перевіряє, що виявлення під час setup залишає runtime-залежності + неналаштованих Plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює runtime-залежності кожного вбудованого + Plugin на вимогу, і що другий перезапуск не перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу npm baseline-версію, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor кандидата + після оновлення відновлює runtime-залежності вбудованих channel без виправлення postinstall + з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер provider-а AIMock для прямої smoke-перевірки протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver-а Tuwunel на базі Docker. - - Цей QA-хост сьогодні призначений лише для репозиторію/розробки. Встановлення OpenClaw з пакета не постачають - `qa-lab`, тому вони не відкривають `openclaw qa`. - - Checkout-и репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення Plugin не потрібен. - - Надає три тимчасових користувачі Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Matrix Plugin як транспортом SUT. + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані встановлення OpenClaw не постачають + `qa-lab`, тому не надають `openclaw qa`. + - Checkout-и репозиторію завантажують вбудований runner безпосередньо; окремий крок встановлення Plugin не потрібен. + - Підготовлює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway із реальним Plugin Matrix як транспортом SUT. - Типово використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки ця доріжка локально створює тимчасових користувачів. - - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки цей lane локально створює тимчасових користувачів. + - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований лог stdout/stderr у `.artifacts/qa-e2e/...`. + - Типово виводить прогрес і примусово застосовує жорсткий timeout виконання через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а у випадку збою включається команда відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - - Запускає live Telegram QA lane проти реальної приватної групи, використовуючи токени bot-а driver і SUT із env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Id групи має бути числовим id чату Telegram. - - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на pooled lease. - - Завершується з ненульовим кодом, якщо падає будь-який сценарій. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без помилкового коду завершення. - - Потребує двох різних bot-ів в одній приватній групі, причому bot SUT має мати username Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot-ів і переконайтеся, що bot driver може спостерігати трафік bot-ів у групі. - - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії відповідей включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. + - Запускає 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 chat id. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на спільні lease-и. + - Завершується з ненульовим кодом, якщо хоч один сценарій зазнав збою. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних bot в одній приватній групі, причому SUT bot має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що driver bot може спостерігати трафік bot у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. -Live transport-доріжки використовують один стандартний контракт, щоб нові транспорти не відхилялися: +Live transport lanes мають один спільний стандартний контракт, щоб нові транспорти не розходилися в поведінці: -`qa-channel` залишається широким синтетичним QA-набором і не є частиною matrix покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. -| Доріжка | Canary | Блокування за згадкою | Блокування allowlist | Відповідь верхнього рівня | Відновлення після restart | Thread follow-up | Ізоляція thread | Спостереження за реакціями | Команда help | -| -------- | ------ | --------------------- | -------------------- | ------------------------- | ------------------------- | ---------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Канарка | Керування згадками | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Follow-up у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------- | ------------------ | -------------- | ------------------------- | ----------------------------- | ----------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -для цієї оренди, поки доріжка працює, і звільняє оренду під час завершення роботи. +QA lab отримує ексклюзивний lease із пулу на базі Convex, підтримує Heartbeat +цього lease, поки lane виконується, і звільняє lease під час завершення роботи. Еталонний каркас проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env vars: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) -- Один секрет для вибраної role: +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` -- Вибір role облікових даних: +- Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення через env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env vars: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -195,29 +194,32 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `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 URL-и Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди мейнтейнера (додати/видалити/перелічити пул) потребують +Адміністративні команди мейнтейнера (pool add/remove/list) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI-хелпери для мейнтейнерів: ```bash +pnpm openclaw qa credentials doctor pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машинозчитуваного виводу в скриптах і утилітах CI. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker, +префікс 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 }` - Успіх: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Вичерпано/можна повторити: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Вичерпано/можна повторити спробу: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) @@ -230,7 +232,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -238,60 +240,60 @@ pnpm openclaw qa credentials remove --credential-id Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим id чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. -### Додавання каналу до QA +### Додавання channel до QA -Додавання каналу до markdown-системи QA вимагає рівно двох речей: +Додавання channel до markdown-системи QA потребує рівно двох речей: -1. Транспортного адаптера для каналу. -2. Пакета сценаріїв, який перевіряє контракт каналу. +1. Транспортного адаптера для channel. +2. Пакета сценаріїв, який перевіряє контракт channel. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -володіти цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` +може керувати цим процесом. `qa-lab` володіє спільною механікою хоста: - коренем команди `openclaw qa` - запуском і завершенням набору -- конкурентністю worker-ів +- паралелізмом worker-ів - записом артефактів - генерацією звітів - виконанням сценаріїв -- аліасами сумісності для старіших сценаріїв `qa-channel` +- alias сумісності для старіших сценаріїв `qa-channel` -Runner Plugin-и володіють транспортним контрактом: +Runner Plugins володіють транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` - як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як інжектяться вхідні події +- як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як відкриваються транскрипти й нормалізований транспортний стан -- як виконуються дії, що підтримуються транспортом -- як обробляється reset або cleanup, специфічний для транспорту +- як відкриваються транскрипти й нормалізований стан транспорту +- як виконуються дії на основі транспорту +- як обробляється специфічне для транспорту скидання або очищення -Мінімальна планка для впровадження нового каналу: +Мінімальний поріг прийняття для нового channel: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Залишайте механіку, специфічну для транспорту, всередині runner Plugin або harness каналу. +2. Реалізуйте transport runner на спільному шві хоста `qa-lab`. +3. Залишайте специфічну для транспорту механіку всередині runner Plugin або harness channel. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner Plugin-и мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; ліниве виконання CLI та runner має залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте generic helper-и для нових сценаріїв. -7. Зберігайте працездатність наявних аліасів сумісності, якщо тільки в репозиторії не відбувається навмисна міграція. + Runner Plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниві CLI і виконання runner мають залишатися за окремими entrypoint. +5. Пишіть або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Для нових сценаріїв використовуйте універсальні хелпери сценаріїв. +7. Залишайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. Правило прийняття рішення суворе: - Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспортного каналу, залишайте її в цьому runner Plugin або harness Plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту і явно зазначайте це в контракті сценарію. +- Якщо поведінка залежить від одного транспорту channel, залишайте її в тому runner Plugin або harness Plugin. +- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один channel, додавайте універсальний helper замість специфічної для channel гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. -Бажані назви generic helper-ів для нових сценаріїв: +Рекомендовані назви універсальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -306,7 +308,7 @@ Runner Plugin-и володіють транспортним контракто - `formatTransportTranscript` - `resetTransport` -Аліаси сумісності залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -314,9 +316,9 @@ Runner Plugin-и володіють транспортним контракто - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати generic helper-и. -Аліаси сумісності існують, щоб уникнути міграції типу flag day, а не як модель для -створення нових сценаріїв. +Нова робота над channel має використовувати універсальні назви helper. +Alias сумісності існують, щоб уникнути міграції в один день, а не як модель для +написання нових сценаріїв. ## Набори тестів (що де запускається) @@ -325,414 +327,414 @@ Runner Plugin-и володіють транспортним контракто ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: ненаправлені запуски використовують набір shard-конфігів `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в конфіги per-project для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які покриває `vitest.unit.config.ts` -- Охоплення: +- Конфігурація: ненацілені запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати багатопроєктні shard у конфігурації для кожного проєкту для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресії для відомих багів + - Внутрішньопроцесні integration-тести (автентифікація gateway, маршрутизація, інструментарій, парсинг, конфігурація) + - Детерміновані регресії для відомих помилок - Очікування: - - Запускається в CI + - Запускаються в CI - Реальні ключі не потрібні - - Має бути швидким і стабільним + - Мають бути швидкими й стабільними - + - - Ненаправлений `pnpm test` запускає дванадцять менших shard-конфігів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує нативний граф проєктів root `vitest.config.ts`, оскільки multi-shard watch-цикл непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише маршрутизованих source/test-файлів; редагування config/setup як і раніше переходять до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, метадані release і tooling, а потім запускає відповідні доріжки typecheck/lint/test. Зміни публічного Plugin SDK і контракту Plugin включають один прохід перевірки extension, оскільки extensions залежать від цих core-контрактів. Зміни лише метаданих release-версій запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни пакетів поза верхньорівневим полем версії. - - Легкі щодо import unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через доріжку `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних доріжках. - - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними sibling-тестами в цих легких доріжках, тож зміни helper-ів уникають повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` має три окремі кошики: helper-и верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти в дешеві тести status/chunk/token. + - Ненацілений `pnpm test` запускає дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу root project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує нативний граф проєктів root `vitest.config.ts`, оскільки цикл watch із багатьма shard непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scope-lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає витрат на повний запуск root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scope-lanes, коли diff зачіпає лише routable source/test-файли; редагування config/setup усе ще повертаються до широкого повторного запуску root project. + - `pnpm check:changed` — звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні typecheck/lint/test lanes. Зміни публічного Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих контрактів core. Зміни version bump лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни пакетів поза полем version верхнього рівня. + - Легкі unit-тести за імпортами з agents, commands, plugins, хелперів auto-reply, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через lane `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lanes, щоб редагування helper не змушували повторно запускати повний важкий набір для цього каталогу. + - `auto-reply` має три окремі бакети: top-level helper core, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій harness-роботі reply потрапляти в дешеві тести status/chunk/token. - + - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте точкові helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте здоровими integration-набори embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, + зберігайте обидва рівні покриття. + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації й нормалізації. + - Підтримуйте здоровий стан integration-наборів вбудованого 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-ів + - Ці набори перевіряють, що scope id і поведінка Compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. - + - - Базова конфігурація Vitest за замовчуванням використовує `threads`. + - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у root project, e2e і live config. - - Коренева доріжка UI зберігає своє налаштування `jsdom` і optimizer, але також працює на + неізольований runner у root projects, e2e і live config. + - Lane root UI зберігає своє налаштування `jsdom` й optimizer, але також працює на спільному неізольованому runner. - - Кожен shard у `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною - поведінкою V8. + Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні доріжки запускає diff. - - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до staging + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook відповідає лише за форматування. Він повторно додає до stage відформатовані файли і не запускає lint, typecheck або тести. - - Запускайте `pnpm check:changed` явно перед передачею роботи або push, коли - вам потрібен розумний локальний gate. Зміни публічного Plugin SDK і контракту - Plugin включають один прохід перевірки extension. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - однозначно зіставляються з меншим набором. + - Явно запускайте `pnpm check:changed` перед передачею чи push, коли + вам потрібен розумний локальний gate. Зміни публічного Plugin SDK і plugin-contract + включають один прохід валідації extension. + - `pnpm test:changed` маршрутизує через scope-lanes, коли змінені шляхи + можна чисто зіставити з меншим набором. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищою межею worker-ів. - - Автоматичне локальне масштабування worker-ів навмисно консервативне і зменшується, - коли середнє навантаження хоста вже високе, тож кілька одночасних + лише з вищим лімітом worker-ів. + - Автомасштабування локальних worker-ів навмисно консервативне й зменшується, + коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється тестова wiring. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо вам потрібне - одне явне розташування кешу для прямого профілювання. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import, а також - вивід структури import. - - `pnpm test:perf:imports:changed` обмежує той самий профільований перегляд + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпортів, а також + вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд файлами, зміненими від `origin/main`. - - Коли один гарячий тест усе ще витрачає більшу частину часу на стартові import, - тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - мокайте цей seam напряму замість deep-import runtime helper-ів - лише для того, щоб передати їх у `vi.mock(...)`. + - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, + тримайте важкі залежності за вузьким локальним швом `*.runtime.ts` і + напряму мокуйте цей шов замість глибоких імпортів runtime-helper-ів лише + для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з нативним шляхом root-project для цього зафіксованого - diff і виводить wall time плюс max RSS на macOS. - - `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне - брудне дерево, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root-конфіг Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для - старту Vitest/Vite і накладних витрат transform. + `test:changed` з нативним шляхом root project для цього зафіксованого + diff і виводить wall time плюс macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного + брудного дерева, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для + накладних витрат запуску й transform у Vitest/Vite. - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим файловим паралелізмом. -### Стабільність (gateway) +### Стабільність (Gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker -- Охоплення: - - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням +- Обсяг: + - Запускає реальний loopback Gateway з увімкненою за замовчуванням діагностикою - Пропускає синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - - Виконує запит до `diagnostics.stability` через WS RPC Gateway - - Покриває helper-и збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибини черг для кожної сесії зливаються назад до нуля + - Опитує `diagnostics.stability` через WS RPC Gateway + - Охоплює helper-и збереження набору діагностики стабільності + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються в межах бюджету тиску, а глибина черг для кожної сесії повертається до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька доріжка для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (gateway smoke) +### E2E (smoke Gateway) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled Plugin у `extensions/` -- Типові runtime-значення: +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin у `extensions/` +- Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - Використовує адаптивну кількість worker-ів (CI: до 2, локально: 1 за замовчуванням). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. + - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати консольного I/O. - Корисні перевизначення: - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість worker-ів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. -- Охоплення: - - Наскрізна поведінка gateway з кількома екземплярами - - WebSocket/HTTP-поверхні, pairing Node-ів і важче мережеве навантаження + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. +- Обсяг: + - End-to-end-поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing Node і важча мережева взаємодія - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може працювати повільніше) -### E2E: OpenShell backend smoke +### E2E: smoke backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` -- Охоплення: +- Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - - Створює sandbox з тимчасового локального Dockerfile - - Перевіряє backend OpenShell OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge + - Створює sandbox із тимчасового локального Dockerfile + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical-поведінку файлової системи через fs bridge sandbox - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - Потребує локального CLI `openshell` і працездатного Docker daemon - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест при ручному запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний CLI binary або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper-скрипт -### Live (реальні provider-и + реальні моделі) +### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled Plugin у `extensions/` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugin у `extensions/` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Охоплення: - - «Чи справді цей provider/ця модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату provider-а, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit +- Обсяг: + - «Чи справді цей провайдер/модель _сьогодні_ працює з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є CI-стабільним (реальні мережі, реальні політики provider-ів, квоти, збої) + - Навмисно нестабільно для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски завантажують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixture-и не могли змінити ваш реальний `~/.openclaw`. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API key. +- За замовчуванням 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-ключів (специфічно для provider-а): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюються у відповідь на rate limit. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і заглушує bootstrap-логи gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні логи запуску. +- Ротація API key (залежно від провайдера): встановіть `*_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, щоб було видно активність довгих викликів provider-а, навіть коли захоплення консолі Vitest працює в тихому режимі. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу provider-а/gateway потоково з’являються одразу під час live-запусків. - - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів було видно як активні, навіть коли перехоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway одразу передавалися потоком під час live-запусків. + - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який набір мені запускати? +## Який набір запускати? -Користуйтеся цією таблицею рішень: +Скористайтеся цією таблицею рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) -- Зміни в мережевій частині gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагодження «мій bot не працює» / збоїв, специфічних для provider-а / виклику інструментів: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь мережевої взаємодії gateway / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій bot не працює» / збої провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live-тести (із доступом до мережі) +## Live-тести (які торкаються мережі) -Для live matrix моделей, smoke-перевірок CLI backend, ACP smoke, harness -Codex app-server і всіх live-тестів media-provider-ів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також для обробки облікових даних у live-запусках — див. +Для матриці live-моделей, smoke backend CLI, smoke ACP, harness +app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також обробки облікових даних для live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). ## Docker-ранери (необов’язкові перевірки «працює в Linux») Ці Docker-ранери поділяються на дві групи: -- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл з profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і завантажують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери типово використовують меншу межу smoke, щоб повний Docker sweep залишався практичним: +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і робочий простір (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менший smoke-ліміт, щоб повний Docker-обхід залишався практичним: `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли - вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker live-доріжок. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke-ранерів E2E, які перевіряють зібраний застосунок. -- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або більше реальних контейнерів і перевіряють шляхи інтеграції вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли + вам навмисно потрібен більший вичерпний обхід. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для Docker live-lanes. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke-ранерів E2E, які перевіряють зібраний застосунок. Агрегатор використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а ліміти ресурсів не дають важким live-, npm-install- і multi-service-lanes запускатися одночасно. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більший запас ресурсів. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `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 model також bind-mount-ять лише потрібні CLI auth home (або всі підтримувані, коли запуск не звужений), а потім копіюють їх у container home перед запуском, щоб OAuth у зовнішньому CLI міг оновлювати token-и без змін у сховищі auth на хості: +Docker-ранери live-моделей також bind-mount лише потрібні home-каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище автентифікації на хості: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke для CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke для harness Codex app-server: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Wizard onboarding (TTY, повне scaffold-налаштування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke onboarding/channel/agent для npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding із посиланням на env плюс Telegram за замовчуванням, перевіряє, що doctor відновлює runtime-залежності активованих Plugin, і виконує один mock-хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke для глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image provider-и замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує один спільний npm cache для контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням бере npm `latest` як стабільну базу перед оновленням до tarball кандидата. Перевірки installer без root зберігають ізольований npm cache, щоб записи cache, створені root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm між локальними повторними запусками. -- Install Smoke у CI пропускає дубльоване пряме глобальне оновлення npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- Мережева частина Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Мінімальна reasoning-регресія для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mock-сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` із `minimal` до `low`, потім примусово викликає відхилення схеми provider-а і перевіряє, що сирі деталі з’являються в журналах Gateway. -- MCP channel bridge (попередньо ініціалізований Gateway + stdio bridge + smoke для сирого notification-frame 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`) -- Cron/subagent MCP cleanup (реальний Gateway + завершення дочірнього процесу stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugin-и (smoke встановлення + аліас `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke для незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke для metadata reload конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності bundled Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker runner image, один раз збирає і пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть повторну збірку на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker aggregate попередньо пакує цей tarball один раз, а потім ділить перевірки bundled channel на незалежні доріжки; використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити matrix каналів при прямому запуску bundled lane. Доріжка також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` приглушують відновлення runtime-залежностей doctor/runtime. -- Звужуйте перевірки runtime-залежностей bundled Plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: +- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke onboarding/channel/agent з npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з посиланням на env плюс Telegram за замовчуванням, перевіряє, що doctor відновлює runtime-залежності активованих Plugin, і виконує один замоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудовані image-провайдери замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` використовує спільний кеш npm для своїх контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільну базову версію перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований кеш npm, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- Install Smoke CI пропускає дубльоване глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Мінімальна reasoning-регресія для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає замоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово спричиняє відхилення схеми провайдера і перевіряє, що необроблена деталь з’являється в логах Gateway. +- Міст MCP channel (seeded Gateway + stdio-міст + smoke сирих notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти Pi bundle MCP (реальний stdio MCP-сервер + 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 встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності вбудованих 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_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегатор пакує цей tarball один раз, а потім розбиває перевірки вбудованих channel на незалежні lanes; використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю channel під час прямого запуску bundled-lane. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-залежностей. +- Звужуйте runtime-залежності вбудованих 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`. -Щоб вручну попередньо зібрати та повторно використовувати спільний built-app image: +Щоб вручну попередньо зібрати і повторно використати спільний образ зібраного застосунку: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для конкретного набору, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, як і раніше мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, оскільки перевіряють поведінку пакета/встановлення, а не спільний runtime built-app. +Перевизначення образів для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки перевіряють поведінку пакета/встановлення, а не спільний runtime зібраного застосунку. -Docker-ранери live-model також bind-mount-ять поточний checkout лише для читання та -розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно запускає Vitest точно на вашому локальному source/config. -Крок staging пропускає великі локальні cache та результати збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe-и gateway не запускали -справжні worker-и каналів Telegram/Discord тощо всередині контейнера. +Docker-ранери live-моделей також монтують bind-mount поточного checkout лише для читання та +розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime-образ +компактним, але водночас дозволяє запускати Vitest точно проти вашого локального source/config. +Крок staging пропускає великі локальні кеші й результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` застосунків або +вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +специфічних для машини артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +реальні worker-и channel Telegram/Discord/etc. усередині контейнера. `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, входить через -Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає -реальний chat-запит через proxy Open WebUI `/api/chat/completions`. +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття Gateway +з цього Docker lane. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, +запускає pinned-контейнер Open WebUI проти цього gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -image Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. -Ця доріжка очікує придатний ключ live model, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. +образ Open WebUI, а самому Open WebUI — завершити власне cold-start-налаштування. +Цей lane очікує придатний ключ live-моделі, і `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -справжнього облікового запису Telegram, Discord або iMessage. Він запускає -попередньо ініціалізований контейнер Gateway, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, metadata вкладень, -поведінку черги live event, маршрутизацію вихідного надсилання і сповіщення у стилі Claude про канал + -дозволи через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо інспектує сирі stdio MCP frame, тож smoke перевіряє те, що bridge -справді видає, а не лише те, що певний SDK клієнта випадково показує. +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded-контейнер Gateway, +запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, +поведінку live-черги подій, маршрутизацію надсилання outbound і сповіщення channel + +дозволів у стилі Claude через реальний stdio MCP-міст. Перевірка сповіщень +безпосередньо інспектує сирі stdio MCP-кадри, тож smoke перевіряє те, що міст +фактично випромінює, а не лише те, що випадково показує конкретний client SDK. `test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує -ключа live model. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей сервер через runtime bundle MCP -вбудованого Pi, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають -інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує -ключа live model. Він запускає попередньо ініціалізований Gateway з реальним stdio MCP probe server, виконує +ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe-сервер +усередині контейнера, матеріалізує цей сервер через runtime вбудованого Pi bundle +MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +Він запускає seeded Gateway з реальним stdio MCP probe-сервером, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручна smoke-перевірка ACP plain-language thread (не для CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для регресійних/налагоджувальних сценаріїв. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні змінні середовища: +Корисні env vars: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і завантажується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` щоб перевіряти лише env-змінні, завантажені з `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 vars, отримані з `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` - - Звужені запуски provider-ів монтують лише потрібні каталоги/файли, виведені з `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_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=...` щоб відфільтрувати provider-и всередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1` щоб повторно використовувати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб переконатися, що облікові дані надходять зі сховища profile (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати model, яку gateway відкриває для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...` щоб перевизначити закріплений тег image Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1` щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що облікові дані беруться зі сховища profile (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити промпт перевірки nonce, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...` щоб перевизначити pinned-тег образу Open WebUI -## Перевірка docs +## Перевірка документації -Запускайте перевірки docs після редагування документації: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку якірних посилань Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) -Це регресії «реального конвеєра» без реальних provider-ів: +Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл агента): `src/gateway/gateway.test.ts` (кейс: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Wizard Gateway (WS `wizard.start`/`wizard.next`, запис config + примусове auth): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config") +- Виклик інструментів 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 token): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: - Mock-виклик інструментів через реальний gateway + цикл агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- End-to-end-потоки майстра, які перевіряють прив’язку сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Decisioning:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/аргументів? -- **Workflow contracts:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Вибір рішень:** коли Skills перелічені в промпті, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval-и мають спочатку залишатися детермінованими: +Майбутні eval мають насамперед залишатися детермінованими: -- Runner сценаріїв, який використовує mock provider-и для перевірки викликів інструментів і їх порядку, читання Skill-файлів і wiring сесії. -- Невеликий набір сценаріїв, орієнтованих на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live eval-и (opt-in, із gate через env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, який використовує mock-провайдери для перевірки викликів інструментів і їхнього порядку, читання skill-файлів і прив’язки сесій. +- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-eval (opt-in, із керуванням через env) лише після того, як буде готовий безпечний для CI набір. -## Contract-тести (форма Plugin і каналу) +## Контрактні тести (форма Plugin і channel) -Contract-тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму -контракту інтерфейсу. Вони ітеруються по всіх виявлених Plugin і запускають набір -перевірок форми й поведінки. Типова unit-доріжка `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте contract-команди явно, -коли ви змінюєте спільні поверхні каналу або provider-а. +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму +контракту інтерфейсу. Вони проходять по всіх виявлених Plugins і запускають набір +перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, +коли торкаєтеся спільних поверхонь channel або провайдера. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти каналів: `pnpm test:contracts:channels` -- Лише контракти provider-ів: `pnpm test:contracts:plugins` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` -### Контракти каналів +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма Plugin (id, name, capabilities) -- **setup** - Контракт setup wizard +- **setup** - Контракт майстра setup - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу -- **threading** - Обробка id thread -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування групової політики +- **actions** - Обробники дій channel +- **threading** - Обробка ID thread +- **directory** - API directory/roster +- **group-policy** - Примусове застосування політики груп -### Контракти статусу provider-а +### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe-и статусу каналу +- **status** - Перевірки статусу channel - **registry** - Форма реєстру Plugin -### Контракти provider-ів +### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/selection auth +- **auth-choice** - Вибір/вибірка auth - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin -- **runtime** - Runtime provider-а +- **runtime** - Runtime провайдера - **shape** - Форма/інтерфейс Plugin -- **wizard** - Setup wizard +- **wizard** - Майстер setup ### Коли запускати -- Після зміни export-ів або subpath-ів plugin-sdk -- Після додавання або зміни каналу чи Plugin provider-а -- Після рефакторингу реєстрації або виявлення Plugin +- Після зміни exports або subpath у plugin-sdk +- Після додавання або зміни channel чи Plugin провайдера +- Після рефакторингу реєстрації Plugin або виявлення -Contract-тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API key. -## Додавання регресій (рекомендації) +## Додавання регресій (настанови) -Коли ви виправляєте проблему provider-а/моделі, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо це за своєю природою лише live-проблема (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні -- Намагайтеся націлюватися на найменший шар, який виявляє баг: - - баг конвертації/повторення запиту provider-а → тест direct models - - баг конвеєра gateway session/history/tool → live smoke gateway або безпечний для CI mock-тест gateway -- Захист для обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих id цілей, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або захоплення точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Віддавайте перевагу націлюванню на найменший шар, який ловить помилку: + - помилка перетворення/відтворення запиту провайдера → тест прямих моделей + - помилка gateway у pipeline сесії/історії/інструментів → live smoke Gateway або безпечний для CI mock-тест Gateway +- Захисне правило обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. ## Пов’язане -- [Тестування live](/uk/help/testing-live) +- [Live-тестування](/uk/help/testing-live) - [CI](/uk/ci) diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index 5f159ad92..42d454297 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -7,28 +7,29 @@ sidebarTitle: Getting Started summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини title: Створення Plugin-ів x-i18n: - generated_at: "2026-04-24T17:33:01Z" + generated_at: "2026-04-24T19:51:43Z" model: gpt-5.4 provider: openai - source_hash: 2989d85ebb7ef73a80de25bce5b156f9939c91fd0672c318aa2349bf079f6bc0 + source_hash: 5990f94cb404820f731070eb7454da26b160b3be56626476a062e4668cd9de6b source_path: plugins/building-plugins.md workflow: 15 --- -Plugin-и розширюють OpenClaw новими можливостями: канали, провайдери моделей, -мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, відеогенерація, отримання вебвмісту, вебпошук, інструменти агентів або будь-яка +Plugin-і розширюють OpenClaw новими можливостями: канали, провайдери моделей, +мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація +зображень, генерація відео, web fetch, web search, інструменти агента або будь-яка комбінація. Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в [ClawHub](/uk/tools/clawhub) або npm, і користувачі встановлять його за допомогою -`openclaw plugins install `. OpenClaw спочатку звертається до ClawHub, а -потім автоматично переходить до npm. +`openclaw plugins install `. OpenClaw спочатку намагається використати ClawHub і +автоматично переходить до npm, якщо це потрібно. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для Plugin-ів у репозиторії: клонований репозиторій і виконаний `pnpm install` +- Для Plugin-ів у репозиторії: репозиторій клоновано й виконано `pnpm install` ## Який тип Plugin-а? @@ -37,17 +38,17 @@ Plugin-и розширюють OpenClaw новими можливостями: Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - Додайте провайдера моделей (LLM, проксі або власну кінцеву точку) + Додайте провайдера моделей (LLM, проксі або кастомну кінцеву точку) - - Зареєструйте інструменти агента, хуки подій або сервіси — продовжуйте нижче + + Зареєструйте інструменти агента, hook-и подій або сервіси — продовження нижче -Для Plugin-а каналу, який не гарантовано буде встановлено під час запуску онбордингу/налаштування, -використовуйте `createOptionalChannelSetupSurface(...)` з -`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування й майстра, -яка повідомляє про вимогу встановлення та блокує реальні записи конфігурації, +Для Plugin-а каналу, який не гарантовано буде встановлено під час запуску +налаштування/onboarding, використовуйте `createOptionalChannelSetupSurface(...)` з +`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування + майстра, +яка повідомляє про вимогу встановлення і завершується в закритому режимі під час реальних записів конфігурації, доки Plugin не буде встановлено. ## Швидкий старт: Plugin інструмента @@ -90,9 +91,9 @@ Plugin-и розширюють OpenClaw новими можливостями: ``` - Кожному Plugin-у потрібен маніфест, навіть без конфігурації. Див. - [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти для публікації в ClawHub - містяться в `docs/snippets/plugin-publish/`. + Кожному Plugin-у потрібен маніфест, навіть без конфігурації. Повну схему див. у + [Маніфест](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub + розміщені в `docs/snippets/plugin-publish/`. @@ -121,14 +122,14 @@ Plugin-и розширюють OpenClaw новими можливостями: ``` `definePluginEntry` призначено для Plugin-ів, які не є каналами. Для каналів використовуйте - `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins). - Повний перелік параметрів точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints). + `defineChannelPluginEntry` — див. [Plugin-и каналів](/uk/plugins/sdk-channel-plugins). + Повний перелік параметрів точки входу див. у [Точки входу](/uk/plugins/sdk-entrypoints). - **Зовнішні Plugin-и:** перевірте та опублікуйте через ClawHub, потім встановіть: + **Зовнішні Plugin-и:** виконайте перевірку й опублікуйте через ClawHub, а потім встановіть: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -136,10 +137,10 @@ Plugin-и розширюють OpenClaw новими можливостями: openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, таких як + OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів на кшталт `@myorg/openclaw-my-plugin`. - **Plugin-и в репозиторії:** розмістіть їх у дереві робочого простору bundled Plugin-ів — їх буде знайдено автоматично. + **Plugin-и в репозиторії:** розмістіть їх у дереві робочого простору bundled Plugin-ів — вони виявляються автоматично. ```bash pnpm test -- /my-plugin/ @@ -152,68 +153,69 @@ Plugin-и розширюють OpenClaw новими можливостями: Один Plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`: -| Можливість | Метод реєстрації | Докладний посібник | -| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- | -| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | -| Бекенд inference для CLI | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) | -| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | -| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Відеогенерація | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Отримання вебвмісту | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Вебпошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Вбудоване розширення Pi | `api.registerEmbeddedExtensionFactory(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) | -| Інструменти агентів | `api.registerTool(...)` | Нижче | -| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| Хуки Plugin-а | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) | -| Внутрішні хуки подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) | -| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Можливість | Метод реєстрації | Детальний посібник | +| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ | +| Текстовий inference (LLM) | `api.registerProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins) | +| Бекенд inference CLI | `api.registerCliBackend(...)` | [Бекенди CLI](/uk/gateway/cli-backends) | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Plugin-и каналів](/uk/plugins/sdk-channel-plugins) | +| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web fetch | `api.registerWebFetchProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web search | `api.registerWebSearchProvider(...)` | [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) | +| Інструменти агента | `api.registerTool(...)` | Нижче | +| Кастомні команди | `api.registerCommand(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) | +| Hook-и Plugin-а | `api.on(...)` | [Hook-и Plugin-а](/uk/plugins/hooks) | +| Внутрішні hook-и подій | `api.registerHook(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) | +| HTTP-маршрути | `api.registerHttpRoute(...)` | [Внутрішня архітектура](/uk/plugins/architecture-internals#gateway-http-routes) | +| Підкоманди CLI | `api.registerCli(...)` | [Точки входу](/uk/plugins/sdk-entrypoints) | -Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api). +Повний API реєстрації див. у [Огляд SDK](/uk/plugins/sdk-overview#registration-api). -Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли Plugin-у потрібні -Pi-native хуки embedded-runner, наприклад асинхронне переписування `tool_result` -перед надсиланням фінального повідомлення з результатом інструмента. Віддавайте перевагу звичайним хукам Plugin-ів OpenClaw, якщо -робота не потребує таймінгу розширення Pi. +Використовуйте `api.registerAgentToolResultMiddleware(...)`, коли Plugin-у потрібне асинхронне +переписування результату інструмента до того, як модель побачить вивід. Оголошуйте цільові +harness-и в `contracts.agentToolResultMiddleware`, наприклад +`["pi", "codex-app-server"]`. Віддавайте перевагу звичайним hook-ам Plugin-ів OpenClaw, якщо +робота не потребує часу результату інструмента до моделі. -Якщо ваш Plugin реєструє власні RPC-методи Gateway, використовуйте для них -префікс, специфічний для Plugin-а. Простори імен адміністрування ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди відповідають -`operator.admin`, навіть якщо Plugin запитує вужчу область доступу. +Якщо ваш Plugin реєструє кастомні RPC-методи Gateway, зберігайте їх у +префіксі, специфічному для Plugin-а. Простори назв адміністратора ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди прив’язуються до +`operator.admin`, навіть якщо Plugin запитує вужчу область. -Семантика guard-хуків, про яку варто пам’ятати: +Семантика guard hook-ів, яку варто пам’ятати: - `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. - `before_tool_call`: `{ block: false }` вважається відсутністю рішення. -- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через накладку схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` в будь-якому каналі. +- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує в користувача схвалення через оверлей схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі. - `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. - `before_install`: `{ block: false }` вважається відсутністю рішення. - `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. - `message_sending`: `{ cancel: false }` вважається відсутністю рішення. -- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для додаткових даних, специфічних для каналу. +- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу. - `message_sending`: віддавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId` замість ключів metadata, специфічних для каналу. -Команда `/approve` обробляє як exec, так і схвалення Plugin-ів з обмеженим запасним варіантом: якщо ідентифікатор схвалення exec не знайдено, OpenClaw повторно перевіряє той самий ідентифікатор серед схвалень Plugin-ів. Переспрямування схвалень Plugin-ів можна окремо налаштувати через `approvals.plugin` у конфігурації. +Команда `/approve` обробляє як exec, так і схвалення Plugin-ів з обмеженим fallback: коли id схвалення exec не знайдено, OpenClaw повторно пробує той самий id через схвалення Plugin-ів. Переспрямування схвалення Plugin-ів можна налаштувати окремо через `approvals.plugin` у конфігурації. -Якщо власна логіка схвалення має визначати цей самий випадок обмеженого запасного варіанта, -використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` -замість ручного зіставлення рядків про завершення терміну дії схвалення. +Якщо кастомна логіка схвалення має виявляти той самий випадок обмеженого fallback, +віддавайте перевагу `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` +замість ручного зіставлення рядків завершення строку дії схвалення. -Приклади та довідник по хуках див. у [Plugin hooks](/uk/plugins/hooks). +Див. [Hook-и Plugin-а](/uk/plugins/hooks), щоб переглянути приклади та довідник hook-ів. -## Реєстрація інструментів агентів +## Реєстрація інструментів агента Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди -доступними) або необов’язковими (користувач вмикає їх самостійно): +доступними) або необов’язковими (користувач вмикає їх за бажанням): ```typescript register(api) { - // Required tool — always available + // Обов’язковий інструмент — завжди доступний api.registerTool({ name: "my_tool", description: "Do a thing", @@ -223,7 +225,7 @@ register(api) { }, }); - // Optional tool — user must add to allowlist + // Необов’язковий інструмент — користувач має додати його до allowlist api.registerTool( { name: "workflow_tool", @@ -246,11 +248,11 @@ register(api) { } ``` -- Назви інструментів не повинні конфліктувати з інструментами ядра (конфліктні буде пропущено) +- Назви інструментів не мають конфліктувати з інструментами ядра (конфлікти пропускаються) - Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів -- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши ідентифікатор Plugin-а до `tools.allow` +- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши id Plugin-а до `tools.allow` -## Угоди щодо імпортів +## Угоди щодо імпорту Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/`: @@ -258,76 +260,76 @@ register(api) { import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; -// Wrong: monolithic root (deprecated, will be removed) +// Неправильно: монолітний корінь (застаріло, буде видалено) import { ... } from "openclaw/plugin-sdk"; ``` -Повний довідник щодо підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview). +Повний довідник підшляхів див. у [Огляд SDK](/uk/plugins/sdk-overview). У межах вашого Plugin-а використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK. -Для Plugin-ів провайдерів зберігайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах -у корені пакета, якщо лише межа не є справді загальною. Поточні bundled-приклади: +Для Plugin-ів провайдерів зберігайте допоміжні засоби, специфічні для провайдера, у цих barrel-файлах +кореня пакета, якщо тільки межа справді не є загальною. Поточні bundled приклади: - Anthropic: обгортки потоків Claude і допоміжні засоби `service_tier` / beta -- OpenAI: конструктори провайдерів, допоміжні засоби для моделей за замовчуванням, провайдери realtime -- OpenRouter: конструктор провайдера плюс допоміжні засоби онбордингу/конфігурації +- OpenAI: конструктори провайдерів, допоміжні засоби моделей за замовчуванням, провайдери реального часу +- OpenRouter: конструктор провайдера плюс допоміжні засоби onboarding/конфігурації -Якщо допоміжна функція корисна лише в межах одного bundled-пакета провайдера, залишайте її на -межі кореня цього пакета, а не піднімайте до `openclaw/plugin-sdk/*`. +Якщо допоміжний засіб корисний лише всередині одного bundled пакета провайдера, залишайте його на цьому +package-root seam замість того, щоб переносити в `openclaw/plugin-sdk/*`. -Деякі згенеровані допоміжні межі `openclaw/plugin-sdk/` усе ще існують для +Деякі згенеровані helper seam-и `openclaw/plugin-sdk/` усе ще існують для підтримки bundled Plugin-ів і сумісності, наприклад -`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Розглядайте їх як зарезервовані -поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів. +`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Ставтеся до них як до зарезервованих +поверхонь, а не як до типової схеми для нових сторонніх Plugin-ів. ## Контрольний список перед поданням -**package.json** містить правильні метадані `openclaw` +**package.json** має правильні метадані `openclaw` Маніфест **openclaw.plugin.json** наявний і коректний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` Усі імпорти використовують цільові шляхи `plugin-sdk/` -Внутрішні імпорти використовують локальні модулі, а не самoімпорти SDK +Внутрішні імпорти використовують локальні модулі, а не self-import-и SDK Тести проходять (`pnpm test -- /my-plugin/`) `pnpm check` проходить (для Plugin-ів у репозиторії) ## Тестування бета-релізу -1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів. -2. Протестуйте свій Plugin на бета-тегу, щойно він з’явиться. Вікно до стабільного релізу зазвичай триває лише кілька годин. -3. Після тестування напишіть у треді вашого Plugin-а в каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає треду, створіть його. -4. Якщо щось зламалося, відкрийте або оновіть issue із заголовком `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свій тред. -5. Відкрийте PR до `main` із заголовком `fix(): beta blocker - ` і додайте посилання на issue як у PR, так і у вашому треді Discord. Учасники не можуть додавати мітки до PR, тому заголовок є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR будуть змерджені; блокери без нього можуть однаково потрапити в реліз. Мейнтейнери стежать за цими тредами під час бета-тестування. -6. Тиша означає, що все добре. Якщо ви пропустите вікно, ваш виправлений код, імовірно, потрапить до наступного циклу. +1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw), щоб отримувати анонси релізів. +2. Протестуйте свій Plugin із бета-тегом щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин. +3. Після тестування напишіть у гілці вашого Plugin-а в каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. +4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: - ` і додайте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у вашій гілці Discord. Учасники не можуть додавати мітки до PR, тому назва є сигналом на боці PR для супровідників і автоматизації. Блокери з PR будуть злиті; блокери без нього все одно можуть потрапити в реліз. Під час бета-тестування супровідники стежать за цими гілками. +6. Відсутність повідомлень означає, що все гаразд. Якщо ви пропустили це вікно, ваше виправлення, ймовірно, потрапить у наступний цикл. ## Наступні кроки - + Створіть Plugin каналу обміну повідомленнями - + Створіть Plugin провайдера моделей - - Карта імпортів і довідник з API реєстрації + + Карта імпортів і довідник API реєстрації - - TTS, пошук, subagent через api.runtime + + TTS, search, subagent через api.runtime - - Утиліти та шаблони тестування + + Утиліти й шаблони для тестування - - Повний довідник зі схеми маніфесту + + Повний довідник схеми маніфесту ## Пов’язане -- [Plugin Architecture](/uk/plugins/architecture) — поглиблений огляд внутрішньої архітектури -- [SDK Overview](/uk/plugins/sdk-overview) — довідник по Plugin SDK -- [Manifest](/uk/plugins/manifest) — формат маніфесту Plugin-а -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів +- [Архітектура Plugin-ів](/uk/plugins/architecture) — детальний огляд внутрішньої архітектури +- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin-ів +- [Маніфест](/uk/plugins/manifest) — формат маніфесту plugin-а +- [Plugin-и каналів](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів +- [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index cf50a3c2c..e05259fb4 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,26 +1,26 @@ --- read_when: - - Ви хочете використати комплектний app-server harness Codex + - Ви хочете використовувати вбудований harness app-server Codex - Вам потрібні приклади конфігурації harness Codex - - Ви хочете вимкнути резервний варіант Pi для розгортань лише з Codex -summary: Запустіть вбудовані ходи агента OpenClaw через комплектний app-server harness Codex + - Ви хочете вимкнути резервний перехід на Pi для розгортань лише з Codex +summary: Запускайте вбудовані ходи агента OpenClaw через вбудований harness app-server Codex title: harness Codex x-i18n: - generated_at: "2026-04-24T18:44:26Z" + generated_at: "2026-04-24T19:52:02Z" model: gpt-5.4 provider: openai - source_hash: 1942e571358674066a7a92139c0ab05273b8196ad68ae3ca2349e2be33cac403 + source_hash: 1bd8f23e8c807d0c97c99ca9c8a41e39f42a35a0bfed5c7f53793a15b6d24e18 source_path: plugins/codex-harness.md workflow: 15 --- -Комплектний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -app-server Codex замість вбудованого harness PI. +Вбудований Plugin `codex` дозволяє OpenClaw запускати вбудовані ходи агента через +app-server Codex замість вбудованого harness Pi. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням потоку, нативним Compaction і виконанням через app-server. -OpenClaw, як і раніше, керує каналами чату, файлами сесії, вибором моделі, інструментами, -підтвердженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневим сеансом агента: виявленням +моделей, нативним відновленням thread, нативним Compaction і виконанням через app-server. +OpenClaw, як і раніше, керує чат-каналами, файлами сеансів, вибором моделей, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом транскрипту. Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: @@ -32,88 +32,86 @@ OpenClaw, як і раніше, керує каналами чату, файла - `before_message_write` для дзеркальних записів транскрипту - `agent_end` -Комплектні plugins також можуть реєструвати фабрику розширення app-server Codex, щоб додати -асинхронне проміжне ПЗ `tool_result`. Це проміжне ПЗ виконується для динамічних інструментів OpenClaw -після того, як OpenClaw виконає інструмент, і до того, як результат буде повернено в Codex. Воно -відокремлене від публічного хука Plugin `tool_result_persist`, який перетворює записи результатів -інструментів у транскрипті, якими керує OpenClaw. +Plugins також можуть реєструвати нейтральне до harness middleware для результатів інструментів, щоб переписувати +динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, +як результат буде повернуто в Codex. Це окремо від публічного +хука Plugin `tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, +якими володіє OpenClaw. -За замовчуванням harness вимкнено. Нові конфігурації мають зберігати посилання на моделі OpenAI -канонічними як `openai/gpt-*` і явно примусово вказувати -`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли вони -хочуть нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і далі -автоматично вибирають harness для сумісності, але не показуються як звичайні варіанти -моделей/провайдерів. +harness вимкнений за замовчуванням. У нових конфігураціях слід зберігати посилання на моделі OpenAI +у канонічному вигляді `openai/gpt-*` і явно примусово вказувати +`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, якщо вони +хочуть нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають +harness для сумісності, але вони не показуються як звичайні варіанти моделі/провайдера. ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, якщо хочете -Codex OAuth через PI; використовуйте `openai/*`, якщо хочете прямий доступ до OpenAI API або -коли примусово використовуєте нативний harness app-server Codex: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, якщо вам потрібен +OAuth Codex через Pi; використовуйте `openai/*`, якщо вам потрібен прямий доступ до OpenAI API або +якщо ви примусово використовуєте нативний harness app-server Codex: | Посилання на модель | Шлях runtime | Використовуйте, коли | -| --------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Ви хочете поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Ви хочете автентифікацію за підпискою ChatGPT/Codex зі стандартним runner PI. | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harness app-server Codex | Ви хочете нативне виконання через app-server Codex для вбудованого ходу агента. | +| --------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через OpenClaw/Pi plumbing | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/Pi | Вам потрібна автентифікація підписки ChatGPT/Codex із типовим runner Pi. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. | -Наразі GPT-5.5 в OpenClaw доступна лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness -app-server Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` підтримуватиметься, +GPT-5.5 наразі в OpenClaw доступна лише через підписку/OAuth. Використовуйте +`openai-codex/gpt-5.5` для OAuth через Pi або `openai/gpt-5.5` з harness app-server +Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` буде підтримуватися, щойно OpenAI увімкне GPT-5.5 у публічному API. -Застарілі посилання `codex/gpt-*` і далі приймаються як сумісні псевдоніми. Міграція сумісності -doctor переписує застарілі основні посилання `codex/*` на `openai/*` -і окремо зберігає політику harness Codex. Нові конфігурації PI Codex OAuth -мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server -мають використовувати `openai/gpt-*` разом із `embeddedHarness.runtime: "codex"`. +Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми для сумісності. Doctor +міграції сумісності переписує застарілі основні посилання `codex/*` на `openai/*` +і окремо записує політику harness Codex. У нових конфігураціях PI OAuth Codex +слід використовувати `openai-codex/gpt-*`; у нових конфігураціях нативного harness app-server слід +використовувати `openai/gpt-*` разом із `embeddedHarness.runtime: "codex"`. -`agents.defaults.imageModel` дотримується того самого розділення за префіксами. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI -Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений хід app-server Codex. Модель app-server Codex має -оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою до початку -ходу з медіа. +`agents.defaults.imageModel` використовує той самий поділ за префіксами. Використовуйте +`openai-codex/gpt-*`, якщо розуміння зображень має виконуватися через шлях провайдера OAuth OpenAI +Codex. Використовуйте `codex/gpt-*`, якщо розуміння зображень має виконуватися +через обмежений хід app-server Codex. Модель app-server Codex повинна +підтримувати введення зображень; текстові моделі Codex завершуються з помилкою ще до початку +медіа-ходу. -Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо +Використовуйте `/status`, щоб підтвердити фактичний harness для поточного сеансу. Якщо вибір виглядає неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness` -та перевірте структурований запис gateway `agent harness selected`. Він -містить id вибраного harness, причину вибору, політику runtime/резервного варіанта, а -в режимі `auto` — результат підтримки для кожного кандидата Plugin. +і перегляньте структурований запис Gateway `agent harness selected`. Він +містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і, +у режимі `auto`, результат підтримки для кожного кандидата Plugin. -Вибір harness не є елементом керування живою сесією. Коли виконується вбудований хід, -OpenClaw записує id вибраного harness для цієї сесії та продовжує використовувати його для -наступних ходів у межах того самого id сесії. Змініть конфігурацію `embeddedHarness` або -`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; -використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI та Codex. Це дає змогу уникнути повторного відтворення одного транскрипту через -дві несумісні нативні системи сесій. +Вибір harness не є засобом керування активним сеансом. Коли вбудований хід виконується, +OpenClaw записує ідентифікатор вибраного harness у цей сеанс і продовжує використовувати його для +наступних ходів у тому самому ідентифікаторі сеансу. Змінюйте конфігурацію `embeddedHarness` або +`OPENCLAW_AGENT_RUNTIME`, якщо хочете, щоб майбутні сеанси використовували інший harness; +використовуйте `/new` або `/reset`, щоб почати новий сеанс перед перемиканням наявної +розмови між Pi і Codex. Це дозволяє уникнути відтворення одного транскрипту через +дві несумісні нативні системи сеансів. -Застарілі сесії, створені до появи фіксації harness, вважаються прив’язаними до PI, щойно вони +Застарілі сеанси, створені до закріплення harness, вважаються закріпленими за Pi, щойно вони мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на Codex після зміни конфігурації. -`/status` показує ефективний harness, відмінний від PI, поруч із `Fast`, наприклад -`Fast · codex`. Стандартний harness PI і далі показується як `Runner: pi (embedded)` і -не додає окремий бейдж harness. +`/status` показує фактичний не-Pi harness поруч із `Fast`, наприклад +`Fast · codex`. Типовий harness Pi і далі відображається як `Runner: pi (embedded)` і +не додає окремого бейджа harness. ## Вимоги -- OpenClaw із доступним комплектним Plugin `codex`. +- OpenClaw із доступним вбудованим Plugin `codex`. - app-server Codex версії `0.118.0` або новішої. -- Автентифікація Codex, доступна для процесу app-server. +- Автентифікація Codex, доступна процесу app-server. -Plugin блокує старіші або неверсіоновані рукостискання app-server. Це утримує -OpenClaw на поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані handshake app-server. Це дозволяє +OpenClaw залишатися на поверхні протоколу, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також +Для live- і Docker smoke-тестів автентифікація зазвичай надходить з `OPENAI_API_KEY`, а також необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний -app-server Codex. +`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний app-server Codex. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово використайте harness `codex`: ```json5 { @@ -136,7 +134,7 @@ app-server Codex. } ``` -Якщо ваша конфігурація використовує `plugins.allow`, також додайте туди `codex`: +Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -152,14 +150,14 @@ app-server Codex. ``` Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в -`codex/`, і далі автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають -надавати перевагу `openai/` разом із явним записом `embeddedHarness`, наведеним вище. +`codex/`, і далі автоматично вмикають вбудований Plugin `codex`. У нових конфігураціях +слід віддавати перевагу `openai/` разом із явним записом `embeddedHarness`, наведеним вище. -## Додайте Codex без заміни інших моделей +## Додайте Codex, не замінюючи інші моделі Зберігайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а -PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для -тих агентів, які мають використовувати harness. +Pi використовувався для всього іншого. Для нових конфігурацій краще явно вказувати `runtime: "codex"` +для агентів, які мають використовувати цей harness. ```json5 { @@ -189,15 +187,15 @@ PI — для всього іншого. Для нових конфігурац } ``` -Із такою конфігурацією: +За такої структури: - `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації. - `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано не модель Codex, PI залишається harness сумісності. +- Якщо вибрано не-Codex модель, Pi залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть резервний варіант PI, коли вам потрібно довести, що кожен вбудований хід агента використовує +Вимкніть fallback на Pi, якщо вам потрібно довести, що кожен вбудований хід агента використовує harness Codex: ```json5 @@ -214,7 +212,7 @@ harness Codex: } ``` -Перевизначення через змінні середовища: +Перевизначення через середовище: ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -222,12 +220,12 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо резервний варіант вимкнено, OpenClaw завершується з помилкою рано, якщо Plugin Codex вимкнено, +Коли fallback вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено, app-server надто старий або app-server не може запуститися. ## Codex для окремого агента -Ви можете зробити один агент лише-Codex, тоді як стандартний агент зберігатиме звичайний +Ви можете зробити одного агента лише-Codex, тоді як агент за замовчуванням зберігатиме звичайний автовибір: ```json5 @@ -259,15 +257,15 @@ app-server надто старий або app-server не може запуст } ``` -Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server -за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку -і дає змогу наступному ходу знову визначити harness на основі поточної конфігурації. +Використовуйте звичайні команди сеансу, щоб перемикати агентів і моделі. `/new` створює новий +сеанс OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server +за потреби. `/reset` очищає прив’язку сеансу OpenClaw для цього thread +і дозволяє наступному ходу знову визначити harness із поточної конфігурації. ## Виявлення моделей -За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або за тайм-аутом, він використовує комплектний резервний каталог для: +За замовчуванням Plugin Codex запитує в app-server доступні моделі. Якщо +виявлення не вдається або завершується за timeout, він використовує вбудований резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -315,19 +313,19 @@ app-server надто старий або app-server не може запуст ## Підключення app-server і політика -За замовчуванням Plugin запускає Codex локально командою: +За замовчуванням Plugin запускає Codex локально за допомогою: ```bash codex app-server --listen stdio:// ``` -За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: +За замовчуванням OpenClaw запускає локальні сеанси harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, що використовується -для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти без -зупинки на нативних запитах на підтвердження, на які нікому відповісти. +`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується +для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без +зупинки на нативних запитах погодження, на які нікому відповісти. -Щоб увімкнути підтвердження Codex із перевіркою guardian, задайте `appServer.mode: +Щоб увімкнути перегляд погоджень через guardian Codex, установіть `appServer.mode: "guardian"`: ```json5 @@ -348,9 +346,9 @@ codex app-server --listen stdio:// } ``` -Guardian — це нативний рецензент підтверджень Codex. Коли Codex просить вийти із sandbox, записати дані поза робочим простором або додати дозволи, як-от доступ до мережі, Codex спрямовує цей запит на підтвердження до субагента-рецензента замість запиту в людини. Рецензент застосовує рамку ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібні кращі запобіжники, ніж у режимі YOLO, але все ще потрібно, щоб агенти без нагляду могли просуватися далі. +Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти з пісочниці, записати за межі робочого простору або додати дозволи, наприклад доступ до мережі, Codex спрямовує цей запит на погодження до субагента-рецензента, а не до людини через підказку. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібно більше запобіжників, ніж у режимі YOLO, але водночас необхідно, щоб агенти без нагляду могли просуватися далі. -Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, перевизначають `mode`, тому розширені розгортання можуть поєднувати пресет із явними параметрами. +Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики все одно мають пріоритет над `mode`, тож у складніших розгортаннях можна поєднувати пресет із явними виборами. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -376,23 +374,23 @@ Guardian — це нативний рецензент підтверджень C Підтримувані поля `appServer`: -| Поле | За замовчуванням | Значення | -| ------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| Поле | Значення за замовчуванням | Значення | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | | `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL WebSocket app-server. | -| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. | -| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається під час запуску/відновлення потоку та ходу. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти запити. | -| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| `url` | не встановлено | URL WebSocket app-server. | +| `authToken` | не встановлено | Bearer-токен для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Timeout для викликів control-plane app-server. | +| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. | +| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що надсилається під час запуску/відновлення thread і під час ходу. | +| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається під час запуску/відновлення thread. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти запити. | +| `serviceTier` | не встановлено | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Старі змінні середовища й далі працюють як резервні варіанти для локального тестування, коли -відповідне поле конфігурації не задано: +Старіші змінні середовища все ще працюють як fallback для локального тестування, коли +відповідне поле конфігурації не встановлено: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -400,15 +398,15 @@ Guardian — це нативний рецензент підтверджень C - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Натомість використовуйте +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте `plugins.entries.codex.config.appServer.mode: "guardian"` або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурація -є бажаним варіантом для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у тому -самому перевіреному файлі, що й решта налаштування harness Codex. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація +є кращою для відтворюваних розгортань, оскільки зберігає поведінку Plugin в тому самому +перевіреному файлі, що й решта налаштувань harness Codex. ## Поширені рецепти -Локальний Codex зі стандартним транспортом stdio: +Локальний Codex із типовим транспортом stdio: ```json5 { @@ -422,7 +420,7 @@ Guardian — це нативний рецензент підтверджень C } ``` -Перевірка harness лише з Codex, із вимкненим резервним варіантом PI: +Перевірка harness лише-Codex із вимкненим fallback на Pi: ```json5 { @@ -439,7 +437,7 @@ Guardian — це нативний рецензент підтверджень C } ``` -Підтвердження Codex із перевіркою Guardian: +Погодження Codex із перевіркою Guardian: ```json5 { @@ -461,7 +459,7 @@ Guardian — це нативний рецензент підтверджень C } ``` -Віддалений app-server із явними заголовками: +Віддалений app-server з явними заголовками: ```json5 { @@ -484,65 +482,66 @@ Guardian — це нативний рецензент підтверджень C } ``` -Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw прив’язано -до наявного потоку Codex, наступний хід знову надсилає в -app-server поточно вибрану модель OpenAI, провайдера, політику підтверджень, sandbox і -рівень сервісу. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає -прив’язку до потоку, але просить Codex продовжити роботу з новою вибраною моделлю. +Перемикання моделей і далі контролюється OpenClaw. Коли сеанс OpenClaw приєднано +до наявного thread Codex, наступний хід знову надсилає до +app-server поточну вибрану модель OpenAI, провайдера, політику погоджень, пісочницю та рівень сервісу. +Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до +thread, але просить Codex продовжити роботу з новою вибраною моделлю. ## Команда Codex -Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -універсальною та працює на будь-якому каналі, що підтримує текстові команди OpenClaw. +Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона +загальна й працює в будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує активне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і skills. -- `/codex models` виводить список активних моделей app-server Codex. -- `/codex threads [filter]` виводить список нещодавніх потоків Codex. -- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить app-server Codex виконати Compaction для прив’язаного потоку. -- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку. +- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і Skills. +- `/codex models` показує поточні моделі app-server Codex. +- `/codex threads [filter]` показує нещодавні threads Codex. +- `/codex resume ` приєднує поточний сеанс OpenClaw до наявного thread Codex. +- `/codex compact` просить app-server Codex виконати Compaction для приєднаного thread. +- `/codex review` запускає нативну перевірку Codex для приєднаного thread. - `/codex account` показує стан облікового запису та лімітів швидкості. - `/codex mcp` показує стан серверів MCP app-server Codex. -- `/codex skills` показує skills app-server Codex. +- `/codex skills` показує Skills app-server Codex. `/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану модель OpenClaw в app-server і зберігає -увімкнену розширену історію. +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає +поточну вибрану модель OpenClaw до app-server і зберігає увімкненою +розширену історію. -Поверхня команд вимагає app-server Codex `0.118.0` або новішої версії. Для окремих -методів керування буде показано `unsupported by this Codex app-server`, якщо +Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Окремі +методи керування позначаються як `unsupported by this Codex app-server`, якщо майбутній або кастомний app-server не надає цей метод JSON-RPC. ## Межі хуків -Harness Codex має три шари хуків: +harness Codex має три шари хуків: -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | -------------------------------------------------------------------- | -| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. | -| Middleware розширення app-server Codex | Комплектні plugins OpenClaw | Поведінка адаптера на кожному ході навколо динамічних інструментів OpenClaw. | -| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. | +| Шар | Власник | Призначення | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | +| Middleware розширення app-server Codex | Вбудовані Plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. | +| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | -OpenClaw не використовує файли проєктного чи глобального Codex `hooks.json` для маршрутизації -поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, якими володіє Codex, -таких як політика shell, нативна перевірка результатів інструментів, обробка зупинки та +OpenClaw не використовує файли Codex `hooks.json` проєкту або глобального рівня для маршрутизації +поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, якими володіє +Codex, як-от політика shell, нативна перевірка результатів інструментів, обробка зупинки та нативний життєвий цикл Compaction/моделі, але вони не є API Plugin OpenClaw. -Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує -виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, в -адаптері harness. Для нативних інструментів Codex саме Codex володіє канонічним записом інструмента. -OpenClaw може віддзеркалювати окремі події, але не може переписати нативний -потік Codex, якщо тільки Codex не надає цю операцію через app-server або callbacks нативних хуків. +Для динамічних інструментів OpenClaw виконує інструмент після того, як Codex запитує +виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у +адаптері harness. Для нативних інструментів Codex канонічним записом інструмента володіє Codex. +OpenClaw може віддзеркалювати вибрані події, але не може переписати нативний thread Codex, +якщо тільки Codex не відкриває цю операцію через app-server або колбеки +нативних хуків. -Коли новіші збірки app-server Codex надаватимуть події нативних хуків життєвого циклу Compaction і моделі, -OpenClaw має обмежувати підтримку цього протоколу за версією та відображати ці +Коли новіші збірки app-server Codex відкривають нативні події хуків життєвого циклу Compaction і моделі, +OpenClaw має обмежувати підтримку цього протоколу за версією та відображати події в наявний контракт хуків OpenClaw там, де семантика є чесною. До того часу події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і `llm_output` є спостереженнями на рівні адаптера, а не побайтними копіями -внутрішнього запиту Codex або payload Compaction. +внутрішнього запиту або payload Compaction у Codex. Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. @@ -550,65 +549,65 @@ OpenClaw має обмежувати підтримку цього проток ## Інструменти, медіа та Compaction -Harness Codex змінює лише низькорівневий виконавець вбудованого агента. +harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw, як і раніше, формує список інструментів і отримує результати динамічних інструментів від -harness. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів обміну повідомленнями -й далі проходять через звичайний шлях доставки OpenClaw. +OpenClaw, як і раніше, будує список інструментів і отримує динамічні результати інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструмента повідомлень +і далі проходять через звичайний шлях доставки OpenClaw. -Запити на підтвердження для інструментів MCP Codex маршрутизуються через потік -підтверджень Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад у -початковий чат, а наступне повідомлення в черзі відповідає на цей нативний запит -сервера замість того, щоб бути спрямованим як додатковий контекст. Інші запити elicitation MCP, -як і раніше, завершуються із закритою відмовою. +Запити на погодження інструментів Codex MCP маршрутизуються через потік погоджень Plugin OpenClaw, коли +Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до +початкового чату, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний +запит сервера замість того, щоб додаватися як додатковий контекст. Інші запити MCP на +уточнення й далі завершуються з відмовою за замовчуванням. -Коли вибрана модель використовує harness Codex, нативний Compaction потоку делегується +Коли вибрана модель використовує harness Codex, нативний thread Compaction делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -містить запит користувача, фінальний текст помічника та полегшені записи міркувань або плану Codex, -коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали початку та завершення -нативного Compaction. Він іще не показує зручний для читання людиною підсумок Compaction -або придатний до аудиту список того, які записи Codex зберіг після Compaction. +включає запит користувача, фінальний текст асистента та спрощені записи міркувань або плану Codex, +коли app-server їх надсилає. Наразі OpenClaw лише записує сигнали початку й завершення +нативного Compaction. Він ще не показує зрозумілий для людини підсумок Compaction або +аудитований список того, які записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не +Оскільки канонічним нативним thread володіє Codex, `tool_result_persist` наразі не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли -OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. +OpenClaw записує результат інструмента в транскрипт сеансу, яким володіє OpenClaw. -Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS та розуміння медіа -й далі використовують відповідні параметри провайдера/моделі, такі як +Генерація медіа не потребує Pi. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення неполадок +## Усунення несправностей **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не бере виконання на себе, -OpenClaw може використовувати PI як бекенд сумісності. Установіть +**OpenClaw використовує Pi замість Codex:** якщо жоден harness Codex не бере на себе запуск, +OpenClaw може використовувати Pi як бекенд сумісності. Установіть `embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або -`embeddedHarness.fallback: "none"`, щоб отримувати помилку, коли жоден harness Plugin не підходить. Щойно +`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден harness Plugin не підходить. Щойно вибрано app-server Codex, його збої відображаються безпосередньо без додаткової -конфігурації резервного варіанта. +конфігурації fallback. -**app-server відхиляється:** оновіть Codex, щоб рукостискання app-server -повідомляло про версію `0.118.0` або новішу. +**app-server відхиляється:** оновіть Codex, щоб handshake app-server +повідомляв версію `0.118.0` або новішу. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket завершується з помилкою відразу:** перевірте `appServer.url`, `authToken` -і що віддалений app-server підтримує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` +і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Модель не Codex використовує PI:** це очікувана поведінка, якщо ви не примусово задали +**Не-Codex модель використовує Pi:** це очікувано, якщо ви не примусово встановили `embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні -посилання `openai/gpt-*` та інших провайдерів залишаються на своєму стандартному шляху провайдера. +`openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному шляху провайдера. ## Пов’язане -- [Plugins Agent Harness](/uk/plugins/sdk-agent-harness) +- [Agent Harness Plugins](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 34797ac73..ec799bf53 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,65 +1,52 @@ --- read_when: - - Ви створюєте Plugin OpenClaw - - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації) + - Ви створюєте Plugin для OpenClaw + - Вам потрібно постачати схему конфігурації plugin або налагоджувати помилки валідації plugin +summary: Вимоги до маніфесту Plugin і схеми JSON (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-24T18:19:00Z" + generated_at: "2026-04-24T19:51:54Z" model: gpt-5.4 provider: openai - source_hash: bbef814f015b285ada8e656050d85e3113c218017840a5d1002e04348587dd5d + source_hash: c4eb13f5b90656d164736e0fed964e6e2f0c8af2cfc7e9788c888bc65be8f0cf source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка призначена лише для **нативного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. -Для сумісних макетів bundle дивіться [Plugin bundles](/uk/plugins/bundles). +Для сумісних макетів bundle див. [Plugin bundles](/uk/plugins/bundles). Сумісні формати bundle використовують інші файли маніфесту: - Codex bundle: `.codex-plugin/plugin.json` -- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude - без маніфесту +- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонентів Claude без маніфесту - Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію -за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних bundle OpenClaw наразі зчитує метадані bundle, а також оголошені -корені skill, корені команд Claude, значення за замовчуванням `settings.json` для Claude bundle, -значення за замовчуванням LSP для Claude bundle та підтримувані набори hook, коли макет відповідає -очікуванням середовища виконання OpenClaw. +Для сумісних bundle OpenClaw наразі читає метадані bundle разом із оголошеними коренями skill, коренями команд Claude, значеннями за замовчуванням із Claude bundle `settings.json`, значеннями LSP за замовчуванням для Claude bundle та підтримуваними наборами hook, коли макет відповідає очікуванням runtime OpenClaw. -Кожен нативний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у -**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються -помилками Plugin і блокують валідацію конфігурації. +Кожен нативний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у **корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду plugin**. Відсутні або невалідні маніфести вважаються помилками plugin і блокують валідацію конфігурації. -Дивіться повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). -Щодо нативної моделі можливостей і поточних рекомендацій із зовнішньої сумісності: -[Модель можливостей](/uk/plugins/architecture#public-capability-model). +Див. повний посібник із системи plugin: [Plugins](/uk/tools/plugin). +Щодо нативної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності див.: [Capability model](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду -вашого Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску -середовища виконання Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску runtime plugin. **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок UI для конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища provider, варіанти автентифікації) -- підказок активації для поверхонь control plane -- скороченого володіння сімейством моделей +- ідентичності plugin, валідації конфігурації та підказок для UI конфігурації +- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь control-plane +- скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для channel, які об’єднуються в каталог і поверхні валідації +- метаданих QA runner, які спільний хост `openclaw qa` може перевіряти +- метаданих конфігурації, специфічних для channel, що зливаються в surfaces каталогу та валідації -**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення -точок входу коду або метаданих встановлення npm. Це належить до коду вашого Plugin -і `package.json`. +**Не використовуйте його для:** реєстрації поведінки runtime, оголошення entrypoint коду або метаданих встановлення npm. Це належить вашому коду plugin і `package.json`. ## Мінімальний приклад @@ -139,68 +126,66 @@ OpenClaw також автоматично визначає ці макети bu ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає bundle Plugin як увімкнений за замовчуванням. Пропустіть це поле або вкажіть будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | id provider, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на модель згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | id channel, що належать цьому Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | id provider, що належать цьому Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення provider, відносний до кореня Plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту та використовуються для автоматичного завантаження Plugin до запуску середовища виконання. | -| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl кінцевих точок, що належать маніфесту, для маршрутів provider, які ядро має класифікувати до завантаження середовища виконання provider. | -| `cliBackends` | Ні | `string[]` | id backend CLI, що належать цьому Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання provider або backend CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать bundle Plugin і представляють не секретний локальний стан, OAuth або ambient credential state. | -| `commandAliases` | Ні | `object[]` | Назви команд, що належать цьому Plugin і мають формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Легковагові env-метадані автентифікації provider, які OpenClaw може перевіряти без завантаження коду Plugin. | -| `providerAuthAliases` | Ні | `Record` | id provider, які мають повторно використовувати id іншого provider для пошуку автентифікації, наприклад provider для кодування, який спільно використовує API key базового provider і профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Легковагові env-метадані channel, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для setup channel на основі env або поверхонь автентифікації, які мають бачити узагальнені допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для picker під час онбордингу, визначення пріоритетного provider і простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження за provider, командою, channel, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання Plugin. | -| `setup` | Ні | `object` | Легковагові дескриптори setup/онбордингу, які поверхні виявлення та setup можуть перевіряти без завантаження середовища виконання Plugin. | -| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання Plugin. | -| `contracts` | Ні | `object` | Статичний знімок bundle capability для зовнішніх hook автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tool. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові значення за замовчуванням media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ----------------------------------- | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON Schema для конфігурації цього plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, що нормалізуються до цього канонічного ідентифікатора plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які повинні автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на моделі їх згадують. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори channel, якими володіє цей plugin. Використовуються для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносний до кореня plugin, для метаданих каталогу провайдерів на рівні маніфесту, які можна завантажити без активації повного runtime plugin. | +| `modelSupport` | Ні | `object` | Короткі метадані сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження plugin до runtime. | +| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдерів, які ядро має класифікувати до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить plugin, під час cold виявлення моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому plugin і представляють не секретний локальний, OAuth або ambient стан облікових даних. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin і які мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Дешеві метадані змінних середовища для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду plugin. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер для кодування, який використовує той самий API-ключ базового провайдера й auth profiles. | +| `channelEnvVars` | Ні | `Record` | Дешеві метадані змінних середовища channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel або поверхонь автентифікації, керованих змінними середовища, які мають бачити узагальнені допоміжні засоби запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Дешеві метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення бажаного провайдера та простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Дешеві метадані планувальника активації для завантаження, що запускається провайдером, командою, channel, маршрутом і можливістю. Лише метадані; фактична поведінка все одно належить runtime plugin. | +| `setup` | Ні | `object` | Дешеві дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime plugin. | +| `qaRunners` | Ні | `object[]` | Дешеві дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження runtime plugin. | +| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого bundle для зовнішніх hook автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, отримання вебданих, вебпошуку та володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві значення за замовчуванням для розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та зливаються в surfaces виявлення та валідації до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня plugin. | +| `name` | Ні | `string` | Зрозуміла для людини назва plugin. | +| `description` | Ні | `string` | Короткий підсумок, що показується на поверхнях plugin. | +| `version` | Ні | `string` | Інформаційна версія plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження середовища виконання provider. +OpenClaw читає це до завантаження runtime провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | id provider, до якого належить цей варіант. | -| `method` | Так | `string` | id методу автентифікації, до якого слід спрямувати. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується під час онбордингу та в потоках CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для picker. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних picker, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із picker асистента, але все одно дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, за замовчуванням це `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в потоках онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант від засобів вибору асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має відображатися цей варіант. Якщо пропущено, за замовчуванням використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть -помилково додати до `plugins.allow` або спробувати виконати як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. +Використовуйте `commandAliases`, коли plugin володіє назвою runtime-команди, яку користувачі можуть помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду runtime plugin. ```json { @@ -214,34 +199,21 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для CLI-операцій, якщо така існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як чат-команду зі слешем, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку можна рекомендувати для CLI-операцій, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane -мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли plugin може дешево оголосити, які події control-plane мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку під час виконання, не замінює `register(...)` і не гарантує, що -код Plugin уже був виконаний. Планувальник активації використовує ці поля для -звуження набору кандидатів Plugin, перш ніж повертатися до наявних -метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку runtime, не замінює `register(...)` і не обіцяє, що код plugin уже було виконано. Планувальник активації використовує ці поля, щоб звузити набір кандидатних plugin, перш ніж звертатися до наявних метаданих володіння в маніфесті, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. -Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, -які не можна представити через ці поля володіння. +Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають потрібний зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна подати через ці поля володіння. -Цей блок — лише метадані. Він не реєструє поведінку під час виконання та не -замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/Plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації зазвичай лише впливає на продуктивність; це не повинно -змінювати коректність, доки ще існують застарілі fallback-механізми володіння в маніфесті. +Цей блок містить лише метадані. Він не реєструє поведінку runtime і не замінює `register(...)`, `setupEntry` чи інші entrypoint runtime/plugin. Поточні споживачі використовують його як підказку для звуження набору кандидатів перед ширшим завантаженням plugin, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не повинна змінювати коректність, доки існують застарілі запасні механізми володіння через маніфест. ```json { @@ -255,37 +227,29 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | id provider, які мають включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | id команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | id channel, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control plane. За можливості надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей plugin до планів активації/завантаження. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають включати цей plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються в плануванні активації control-plane. За можливості віддавайте перевагу вужчим полям. | Поточні активні споживачі: -- планування CLI, ініційоване командою, повертається до застарілих +- планування CLI, що запускається командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/channel, ініційоване channel, повертається до застарілого володіння `channels[]`, - коли явні метадані активації channel відсутні -- планування setup/середовища виконання, ініційоване provider, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації provider - відсутні +- планування setup/channel, що запускається channel, повертається до застарілого + володіння `channels[]`, коли явні метадані активації channel відсутні +- планування setup/runtime, що запускається провайдером, повертається до застарілого + володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані + активації провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та fallback на -володіння з маніфесту. Наприклад, `activation-command-hint` означає, що -збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані, -які найкраще описують володіння. +Діагностика планувальника може розрізняти явні підказки активації та запасний механізм володіння через маніфест. Наприклад, `activation-command-hint` означає, що спрацювало `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння через `commandAliases`. Ці мітки причин призначені для діагностики хоста та тестів; авторам plugin слід і надалі оголошувати метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під -спільним коренем `openclaw qa`. Зберігайте ці метадані легковаговими та статичними; фактичною -реєстрацією CLI, як і раніше, керує середовище виконання Plugin через легковагову -поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли plugin додає один або кілька runner транспорту під спільним коренем `openclaw qa`. Зберігайте ці метадані дешевими й статичними; фактична реєстрація CLI як і раніше належить runtime plugin через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -298,15 +262,14 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | --------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням setup та онбордингу потрібні дешеві метадані, що належать Plugin, -до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, що належать plugin, до завантаження runtime. ```json { @@ -325,51 +288,36 @@ OpenClaw зчитує це до завантаження середовища в } ``` -Верхньорівневе `cliBackends` залишається валідним і надалі описує backend інференсу CLI. -`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для -потоків control plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається валідним і надалі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо присутні, `setup.providers` і `setup.cliBackends` є пріоритетною -поверхнею пошуку descriptor-first для виявлення setup. Якщо дескриптор лише -звужує candidate Plugin, а setup усе ще потребує багатших hook під час setup, встановіть `requiresRuntime: true` і залиште `setup-api` як -резервний шлях виконання. +Коли присутні, `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку на основі дескрипторів для виявлення setup. Якщо дескриптор лише звужує кандидатний plugin, а setup усе ще потребує багатших hook runtime під час налаштування, установіть `requiresRuntime: true` і збережіть `setup-api` як запасний шлях виконання. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори -і не виконуватиме `setup-api` для пошуку setup. Пропущений `requiresRuntime` -зберігає застарілу fallback-поведінку, щоб наявні Plugin, які додали дескриптори -без цього прапорця, не зламалися. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори й не виконуватиме `setup-api` для пошуку setup. Пропущений `requiresRuntime` зберігає застарілу поведінку запасного механізму, щоб наявні plugin, які додали дескриптори без цього прапорця, не зламалися. -Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані -значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними -серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою, а не вибором -переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися унікальними серед виявлених plugin. Неоднозначне володіння завершується в закритому режимі замість вибору переможця за порядком виявлення. -Коли середовище виконання setup усе ж виконується, діагностика реєстру setup повідомляє про -розбіжність дескрипторів, якщо `setup-api` реєструє provider або backend CLI, які -не оголошені дескрипторами маніфесту, або якщо дескриптор не має відповідної -реєстрації під час виконання. Ця діагностика є додатковою і не відхиляє застарілі Plugin. +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, якщо `setup-api` реєструє провайдера або backend CLI, які не оголошено в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. Ця діагностика є додатковою й не відхиляє застарілі plugin. ### Довідник `setup.providers` | Поле | Обов’язкове | Тип | Що воно означає | | ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- | -| `id` | Так | `string` | id provider, що надається під час setup або онбордингу. Зберігайте нормалізовані id глобально унікальними. | -| `authMethods` | Ні | `string[]` | id методів setup/автентифікації, які цей provider підтримує без завантаження повного середовища виконання. | -| `envVars` | Ні | `string[]` | Env vars, які узагальнені поверхні setup/status можуть перевіряти до завантаження середовища виконання Plugin. | +| `id` | Так | `string` | Ідентифікатор провайдера, доступний під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Змінні середовища, які узагальнені поверхні setup/status можуть перевіряти до завантаження runtime plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ | -| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | id backend для setup, що використовуються для descriptor-first пошуку setup. Зберігайте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | id міграцій конфігурації, що належать поверхні setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ----------------- | ----------- | ---------- | ----------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, доступні під час setup і онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для setup, що використовуються для пошуку setup за принципом descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations`| Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для рендерингу. +`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу. ```json { @@ -393,17 +341,16 @@ OpenClaw зчитує це до завантаження середовища в | `tags` | `string[]` | Необов’язкові теги UI. | | `advanced` | `boolean` | Позначає поле як розширене. | | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -зчитати без імпорту середовища виконання Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може прочитати без імпорту runtime plugin. ```json { "contracts": { - "embeddedExtensionFactories": ["pi"], + "agentToolResultMiddleware": ["pi", "codex-app-server"], "externalAuthProviders": ["acme-ai"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], @@ -421,38 +368,31 @@ OpenClaw зчитує це до завантаження середовища в Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | id вбудованого середовища виконання, для яких bundle Plugin може реєструвати factory. | -| `externalAuthProviders` | `string[]` | id provider, чий зовнішній hook профілю автентифікації належить цьому Plugin. | -| `speechProviders` | `string[]` | id provider мовлення, які належать цьому Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | id provider транскрипції в реальному часі, які належать цьому Plugin. | -| `realtimeVoiceProviders` | `string[]` | id provider голосу в реальному часі, які належать цьому Plugin. | -| `memoryEmbeddingProviders` | `string[]` | id provider embedding для пам’яті, які належать цьому Plugin. | -| `mediaUnderstandingProviders` | `string[]` | id provider media-understanding, які належать цьому Plugin. | -| `imageGenerationProviders` | `string[]` | id provider генерації зображень, які належать цьому Plugin. | -| `videoGenerationProviders` | `string[]` | id provider генерації відео, які належать цьому Plugin. | -| `webFetchProviders` | `string[]` | id provider web-fetch, які належать цьому Plugin. | -| `webSearchProviders` | `string[]` | id provider web search, які належать цьому Plugin. | -| `tools` | `string[]` | Назви tool агента, які належать цьому Plugin для bundle-перевірок контрактів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ----------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Застарілі ідентифікатори фабрик вбудованих extension. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори harness, для яких цей plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий hook профілю зовнішньої автентифікації належить цьому plugin. | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, що належать цьому plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрипції в реальному часі, що належать цьому plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, що належать цьому plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів ембедингів пам’яті, що належать цьому plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, що належать цьому plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, що належать цьому plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, що належать цьому plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів отримання вебданих, що належать цьому plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів вебпошуку, що належать цьому plugin. | +| `tools` | `string[]` | Назви інструментів агентів, що належать цьому plugin для перевірок контрактів вбудованого bundle. | -Plugin provider, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати -`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють -через застарілий fallback-механізм сумісності, але він повільніший і -буде вилучений після вікна міграції. +`contracts.embeddedExtensionFactories` збережено для коду сумісності вбудованих bundle, якому все ще потрібні прямі події Pi embedded-runner. Нові трансформації результатів інструментів повинні оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. -Bundle Plugin provider embedding для пам’яті повинні оголошувати -`contracts.memoryEmbeddingProviders` для кожного id adapter, який вони надають, включно з -вбудованими adapter, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, -щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway -зареєструє provider. +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий запасний механізм сумісності, але він повільніший і буде видалений після вікна міграції. + +Вбудовані провайдери ембедингів пам’яті повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише plugin-власник до того, як повний runtime Gateway зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має -моделі за замовчуванням, пріоритет fallback автоматичної автентифікації або нативну підтримку документів, -які потрібні узагальненим допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в -`contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має моделі за замовчуванням, пріоритет запасного автоматичного вибору автентифікації або нативну підтримку документів, які потрібні узагальненим допоміжним засобам ядра до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json { @@ -475,19 +415,18 @@ Bundle Plugin provider embedding для пам’яті повинні огол } ``` -Кожен запис provider може містити: +Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------ | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. | -| `defaultModels` | `Record` | Значення моделей за замовчуванням для можливостей, які використовуються, коли конфігурація не вказує модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує provider. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Значення моделей за замовчуванням для можливостей, що використовуються, коли конфігурація не вказує модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного запасного вибору провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin channel потребує дешевих метаданих конфігурації до -завантаження середовища виконання. +Використовуйте `channelConfigs`, коли plugin channel потребує дешевих метаданих конфігурації до завантаження runtime. ```json { @@ -516,18 +455,17 @@ Bundle Plugin provider embedding для пам’яті повинні огол Кожен запис channel може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації channel. | -| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації channel. | -| `label` | `string` | Мітка channel, що об’єднується з поверхнями picker та inspect, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис channel для поверхонь inspect і catalog. | -| `preferOver` | `string[]` | id застарілих або менш пріоритетних Plugin, які цей channel має випереджати на поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації channel. | +| `label` | `string` | Мітка channel, що зливається в surfaces вибору та перевірки, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис channel для surfaces перевірки та каталогу. | +| `preferOver` | `string[]` | Застарілі або нижчі за пріоритетом ідентифікатори plugin, які цей channel має випереджати в surfaces вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin provider із -скорочених id моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш plugin провайдера зі скорочених ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime plugin. ```json { @@ -540,105 +478,69 @@ Bundle Plugin provider embedding для пам’яті повинні огол OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику -- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes` -- якщо збігаються один небандлований Plugin і один bundle Plugin, перемагає небандлований - Plugin -- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть provider +- явні посилання `provider/model` використовують метадані володіння `providers` із маніфесту +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ----------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб -перемістити `speechProviders`, `realtimeTranscriptionProviders`, -`realtimeVoiceProviders`, `mediaUnderstandingProviders`, -`imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не трактує ці поля верхнього рівня як -володіння можливостями. +Застарілі ключі можливостей верхнього рівня застаріли. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не вважає ці поля верхнього рівня ознакою володіння можливостями. -## Маніфест і `package.json` +## Маніфест і package.json Ці два файли виконують різні завдання: -| Файл | Для чого використовувати | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмеження встановлення, setup або метаданих catalog | +| Файл | Використовуйте для | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмеження встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, де має належати певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів входу або поведінки встановлення npm, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, entry-файлів або поведінки встановлення npm, помістіть це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані Plugin до запуску середовища виконання навмисно зберігаються в `package.json` у блоці -`openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані plugin до runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує точки входу нативного Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel і виявлення статусу channel/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Легковагові метадані catalog channel, такі як мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Легковагові метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання channel. | -| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже є хтось увійшов у систему?» без завантаження повного середовища виконання channel. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundle Plugin і Plugin, опублікованих зовні. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок integrity npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundle Plugin, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного Plugin channel під час запуску. | +| Поле | Що воно означає | +| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує entrypoint нативного Plugin. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.runtimeExtensions` | Оголошує побудовані entrypoint runtime JavaScript для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.setupEntry` | Легковаговий entrypoint лише для setup, який використовується під час онбордингу, відкладеного запуску channel і виявлення read-only status/SecretRef для channel. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує побудований entrypoint setup JavaScript для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. | +| `openclaw.channel` | Дешеві метадані каталогу channel, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного runtime channel. | +| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід хоч десь?» без завантаження повного runtime channel. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugin. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення перевіряють отриманий артефакт відносно нього. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в -онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/channel/setup з’являються під час онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих варіантів. Не переміщуйте підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження -реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають -Plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають plugin на старіших хостах. -Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього catalog -повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися -безпечним відхиленням, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. -Інтерактивний онбординг, як і раніше, пропонує npm-специфікації довіреного реєстру, включно з -простими назвами пакетів і dist-tag, для сумісності. Діагностика catalog може -розрізняти точні, плаваючі, закріплені integrity, без integrity, із невідповідністю -назви пакета та з невалідним default-choice джерела. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає валідного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру -фіксується без закріплення integrity. +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися в закритому режимі, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг і надалі пропонує довірені npm-специфікації реєстру, включно з простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та з невалідним default-choice джерела. Вона також попереджає, коли `expectedIntegrity` присутній, але немає валідного джерела npm, яке можна ним закріпити. Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли він пропущений, визначення реєстру фіксується без закріплення цілісності. -Plugin channel мають надавати `openclaw.setupEntry`, коли статус, список channel -або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного -середовища виконання. Точка входу setup має надавати метадані channel разом із безпечними для setup adapter -конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і -транспортні середовища виконання залишайте в основній точці входу розширення. +Plugin channel повинні надавати `openclaw.setupEntry`, коли status, список channel або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного runtime. Entrypoint setup має надавати метадані channel разом із безпечними для setup адаптерами config, status і secrets; мережеві клієнти, слухачі Gateway і runtime транспорту слід тримати в основному entrypoint extension. -Поля точки входу runtime не скасовують перевірки меж пакета для полів -вихідної точки входу. Наприклад, `openclaw.runtimeExtensions` не може зробити -завантажуваним шлях `openclaw.extensions`, що виходить за межі. +Поля entrypoint runtime не перевизначають перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі дозволеного. -`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не -робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє -потокам встановлення відновлюватися після певних застарілих збоїв оновлення bundle Plugin, -таких як відсутній шлях bundle Plugin або застарілий запис `channels.` для того самого -bundle Plugin. Непов’язані помилки конфігурації, як і раніше, блокують встановлення та спрямовують операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого plugin, таких як відсутній шлях до вбудованого plugin або застарілий запис `channels.` для того самого вбудованого plugin. Непов’язані помилки конфігурації й надалі блокують встановлення та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля -перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: ```json { @@ -654,13 +556,9 @@ bundle Plugin. Непов’язані помилки конфігурації, } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка -автентифікації у форматі так/ні до завантаження повного Plugin channel. Цільовий export має бути невеликою -функцією, яка читає лише persisted state; не спрямовуйте її через повний barrel -середовища виконання channel. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка автентифікації типу yes/no до завантаження повного plugin channel. Цільовий експорт має бути невеликою функцією, що лише читає збережений стан; не пропускайте її через загальний barrel runtime channel. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок -configured-state лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: ```json { @@ -676,69 +574,62 @@ configured-state лише через env: } ``` -Використовуйте це, коли channel може визначити configured-state через env або інші невеликі -вхідні дані без середовища виконання. Якщо перевірка потребує повного розв’язання конфігурації або реального -середовища виконання channel, натомість залиште цю логіку в hook `config.hasConfiguredState` -Plugin. +Використовуйте це, коли channel може визначити налаштований стан із env або інших невеликих нерuntime-входів. Якщо перевірка потребує повного визначення конфігурації або справжнього runtime channel, залиште цю логіку в hook plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дубльовані id Plugin) +## Пріоритет виявлення (дублікати ідентифікаторів plugin) -OpenClaw виявляє Plugin із кількох коренів (bundle, global install, workspace, явні шляхи, вибрані конфігурацією). Якщо два знайдені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два знайдені plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч. -Пріоритет, від найвищого до найнижчого: +Пріоритет від найвищого до найнижчого: -1. **Config-selected** — шлях, явно закріплений у `plugins.entries.` -2. **Bundled** — Plugin, що постачаються разом з OpenClaw -3. **Global install** — Plugin, установлені в глобальний корінь Plugin OpenClaw -4. **Workspace** — Plugin, виявлені відносно поточного workspace +1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — plugin, що постачаються разом з OpenClaw +3. **Глобальне встановлення** — plugin, установлені в глобальний корінь plugin OpenClaw +4. **Workspace** — plugin, виявлені відносно поточного workspace Наслідки: -- Форкована або застаріла копія bundle Plugin у workspace не перекриє bundle-збірку. -- Щоб справді перевизначити bundle Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. -- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Розгалужена або застаріла копія вбудованого plugin у workspace не затьмарить вбудовану збірку. +- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в workspace. +- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен Plugin повинен містити JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми перевіряються під час читання/запису конфігурації, а не під час виконання. +- **Кожен plugin повинен постачатися зі схемою JSON Schema**, навіть якщо він не приймає жодної конфігурації. +- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми перевіряються під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` — це **помилки**, якщо тільки id channel не оголошено - в маніфесті Plugin. -- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **виявлювані** id Plugin. Невідомі id — це **помилки**. -- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, - валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, і - у Doctor + журналах показується **попередження**. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошено в маніфесті plugin. +- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` мають посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**. +- Якщо plugin встановлено, але його маніфест або схема пошкоджені чи відсутні, валідація завершується помилкою, а Doctor повідомляє про помилку plugin. +- Якщо конфігурація plugin існує, але plugin **вимкнений**, конфігурація зберігається й у Doctor + логах показується **попередження**. -Дивіться [Configuration reference](/uk/gateway/configuration) для повної схеми `plugins.*`. +Див. [Configuration reference](/uk/gateway/configuration) для повної схеми `plugins.*`. ## Примітки -- Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання, як і раніше, завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. -- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом. -- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широке середовище виконання; використовуйте його для статичних метаданих catalog provider або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Env-метадані (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставлення Cron та інші поверхні лише для читання, як і раніше, застосовують політику довіри до Plugin та ефективної активації, перш ніж вважати env var налаштованою. -- Для метаданих wizard під час виконання, які потребують коду provider, дивіться [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для нативних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime і надалі завантажує модуль plugin окремо; маніфест потрібен лише для виявлення + валідації. +- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, завершальні коми й ключі без лапок допускаються, якщо фінальне значення все одно є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код runtime; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). +- Метадані змінних середовища (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Status, audit, перевірка доставки Cron та інші read-only-поверхні й надалі застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Метадані runtime wizard, які потребують коду провайдера, див. у [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з Plugin. + + Початок роботи з plugin. - + Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin та імпорти підшляхів. + Довідник SDK plugin і імпорти підшляхів. diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index 58abe93d4..cd0fe05c0 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,56 +1,56 @@ --- read_when: - - Ви змінюєте вбудоване runtime-середовище агента або реєстр harness-ів + - Ви змінюєте вбудований runtime агента або реєстр harness-а - Ви реєструєте harness агента з вбудованого або довіреного Plugin-а - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із провайдерами моделей sidebarTitle: Agent Harness summary: Експериментальна поверхня SDK для Plugin-ів, які замінюють низькорівневий вбудований виконавець агента title: Plugin-и harness агента x-i18n: - generated_at: "2026-04-23T23:02:27Z" + generated_at: "2026-04-24T19:52:03Z" model: gpt-5.4 provider: openai - source_hash: af76c2a3ebe54c87920954b58126ee59538c0e6d3d1b4ba44890c1f5079fabc2 + source_hash: ffb57530e6259952c8dde473a69052f578b081f28659e22b72347fa64e497a38 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -**Harness агента** — це низькорівневий виконавець одного підготовленого циклу агента OpenClaw. -Це не провайдер моделі, не канал і не реєстр інструментів. +**harness агента** — це низькорівневий виконавець для одного підготовленого +ходу агента OpenClaw. Це не провайдер моделей, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для вбудованих або довірених native Plugin-ів. Контракт -усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний +Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin-ів. Контракт +досі експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований runner. ## Коли використовувати harness -Реєструйте harness агента, коли сімейство моделей має власне native session -runtime-середовище і звичайний транспорт провайдера OpenClaw є неправильною абстракцією. +Реєструйте harness агента, коли сімейство моделей має власний нативний runtime +сеансів, а звичайний транспорт провайдера OpenClaw є хибною абстракцією. Приклади: -- native server агента для кодування, який сам керує threads і Compaction -- локальний CLI або daemon, який має потоково передавати native-події плану/міркування/інструментів -- runtime-середовище моделі, якому потрібен власний resume id на додачу до транскрипту - сесії OpenClaw +- нативний сервер coding-agent, який володіє тредами й Compaction +- локальний CLI або демон, який має стримити нативні події plan/reasoning/tool +- runtime моделі, якому потрібен власний resume id на додачу до транскрипту + сеансу OpenClaw -**Не** реєструйте harness лише для додавання нового API LLM. Для звичайних HTTP- або -WebSocket-API моделей створюйте [provider plugin](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте harness лише для додавання нового API LLM. Для звичайних HTTP або +WebSocket API моделей створюйте [provider Plugin](/uk/plugins/sdk-provider-plugins). -## Чим і далі володіє core +## Чим усе ще володіє core -До вибору harness OpenClaw уже визначив: +До того, як буде вибрано harness, OpenClaw уже визначив: - провайдера і модель -- стан runtime-автентифікації +- стан автентифікації runtime - рівень thinking і бюджет контексту -- файл транскрипту/сесії OpenClaw -- робочий простір, sandbox і політику інструментів -- callback-и відповіді каналу і callback-и потокової передачі -- політику fallback моделі та живого перемикання моделі +- файл транскрипту/сеансу OpenClaw +- workspace, sandbox і політику інструментів +- callback-и відповіді каналу та стримінгу +- політику fallback моделі та live-перемикання моделей -Цей поділ є навмисним. Harness виконує підготовлену спробу; він не вибирає -провайдерів, не замінює доставку каналом і не перемикає моделі потайки. +Такий поділ навмисний. Harness виконує підготовлену спробу; він не вибирає +провайдерів, не замінює доставку каналу й не перемикає моделі непомітно. ## Реєстрація harness @@ -92,102 +92,109 @@ export default definePluginEntry({ OpenClaw вибирає harness після визначення провайдера/моделі: -1. Якщо в наявній сесії вже записано id harness, воно має пріоритет, тож зміни config/env - не перемикають цей транскрипт на інше runtime-середовище “на гарячу”. -2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстрований harness із цим id для - сесій, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований harness PI. +1. Ідентифікатор harness, записаний у наявному сеансі, має пріоритет, щоб зміни config/env не + перемикали цей транскрипт на інший runtime на льоту. +2. `OPENCLAW_AGENT_RUNTIME=` примусово вмикає зареєстрований harness з цим id для + сеансів, які ще не закріплені. +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вмикає вбудований harness PI. 4. `OPENCLAW_AGENT_RUNTIME=auto` просить зареєстровані harness-и перевірити, чи підтримують вони - визначені провайдера/модель. -5. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо fallback до PI + визначеного провайдера/модель. +5. Якщо відповідного зареєстрованого harness-а немає, OpenClaw використовує PI, якщо fallback на PI не вимкнено. -Збої Plugin harness відображаються як збої запуску. У режимі `auto` fallback до PI -використовується лише тоді, коли жоден зареєстрований Plugin harness не підтримує визначені -провайдера/модель. Щойно Plugin harness вже заявив про запуск, OpenClaw не -повторює цей самий цикл через PI, оскільки це може змінити семантику auth/runtime -або дублювати побічні ефекти. +Помилки harness-ів Plugin-ів відображаються як помилки виконання. У режимі `auto` fallback на PI +застосовується лише тоді, коли жоден зареєстрований harness Plugin-а не підтримує визначеного +провайдера/модель. Щойно harness Plugin-а заявив про запуск, OpenClaw не +програє той самий хід повторно через PI, оскільки це може змінити семантику +auth/runtime або спричинити дубльовані побічні ефекти. -Вибраний id harness зберігається разом з id сесії після вбудованого запуску. -Legacy-сесії, створені до закріплення harness, трактуються як закріплені за PI, щойно вони -мають історію транскрипту. Використовуйте нову/скинуту сесію при перемиканні між PI і -native Plugin harness. `/status` показує нетипові id harness, як-от `codex`, -поруч із `Fast`; PI приховується, бо це типовий шлях сумісності. -Якщо вибраний harness виглядає несподівано, увімкніть debug-логування `agents/harness` і +Вибраний id harness-а зберігається разом з id сеансу після вбудованого запуску. +Застарілі сеанси, створені до появи привʼязок harness-а, вважаються привʼязаними до PI, щойно в них +зʼявляється історія транскрипту. Використовуйте новий/скинутий сеанс, коли перемикаєтеся між PI і +нативним harness-ом Plugin-а. `/status` показує не типові id harness-ів, такі як `codex`, +поруч із `Fast`; PI прихований, оскільки це типовий шлях сумісності. +Якщо вибраний harness виглядає неочікуваним, увімкніть журналювання налагодження `agents/harness` і перегляньте структурований запис gateway `agent harness selected`. Він містить -id вибраного harness, причину вибору, політику runtime/fallback і, у режимі +id вибраного harness-а, причину вибору, політику runtime/fallback і, у режимі `auto`, результат підтримки для кожного кандидата Plugin-а. -Вбудований Plugin Codex реєструє `codex` як свій id harness. Core трактує це -як звичайний id Plugin harness; псевдоніми, специфічні для Codex, мають належати -Plugin-у або конфігурації оператора, а не спільному селектору runtime. +Вбудований Plugin Codex реєструє `codex` як свій id harness-а. Core розглядає це +як звичайний id harness-а Plugin-а; специфічні для Codex псевдоніми мають належати Plugin-у +або config оператора, а не спільному селектору runtime. -## Поєднання провайдера і harness +## Поєднання provider + harness -Більшість harness-ів також повинні реєструвати провайдера. Провайдер робить посилання на моделі, -стан auth, метадані моделі та вибір `/model` видимими для решти -OpenClaw. Потім harness заявляє про цей провайдер у `supports(...)`. +Більшість harness-ів також мають реєструвати provider. Provider робить refs моделей, +статус auth, метадані моделі та вибір `/model` видимими для решти +OpenClaw. Потім harness заявляє цей provider у `supports(...)`. Вбудований Plugin Codex дотримується цього шаблону: -- id провайдера: `codex` -- користувацькі посилання на модель: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; - legacy-посилання `codex/gpt-*` і далі приймаються для сумісності -- id harness: `codex` -- auth: синтетична доступність провайдера, оскільки harness Codex володіє - native login/session Codex -- запит app-server: OpenClaw надсилає Codex сирий id моделі й дозволяє - harness-у спілкуватися з native-протоколом app-server +- id provider: `codex` +- refs моделей для користувача: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; + застарілі refs `codex/gpt-*` досі приймаються для сумісності +- id harness-а: `codex` +- auth: синтетична доступність provider, оскільки harness Codex володіє + нативним входом/сеансом Codex +- запит app-server: OpenClaw надсилає до Codex чистий id моделі й дозволяє + harness-у працювати з нативним протоколом app-server -Plugin Codex є додатковим. Звичайні посилання `openai/gpt-*` і далі використовують -звичайний шлях провайдера OpenClaw, якщо ви не примусово задасте harness Codex через -`embeddedHarness.runtime: "codex"`. Старіші посилання `codex/gpt-*` і далі вибирають -провайдера і harness Codex для сумісності. +Plugin Codex є додатковим. Звичайні refs `openai/gpt-*` і далі використовують +нормальний шлях provider OpenClaw, якщо ви не примусите harness Codex через +`embeddedHarness.runtime: "codex"`. Старі refs `codex/gpt-*` і далі вибирають +provider і harness Codex для сумісності. -Налаштування оператора, приклади префіксів моделей і конфігурації лише для Codex див. у +Налаштування для операторів, приклади префіксів моделей і config-и лише для Codex дивіться в [Codex Harness](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server `0.118.0` або новіший. Plugin Codex перевіряє -initialize handshake app-server і блокує старіші або неверсійовані сервери, тож -OpenClaw працює лише з тією поверхнею протоколу, з якою його було протестовано. +OpenClaw вимагає Codex app-server `0.118.0` або новіше. Plugin Codex перевіряє +initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб +OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. -### Middleware результатів інструментів Codex app-server +### Middleware результатів інструментів -Вбудовані Plugin-и також можуть підключати middleware `tool_result`, специфічний для Codex app-server, -через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній -manifest оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`. -Це шов для довірених Plugin-ів для асинхронних перетворень `tool_result`, які мають -виконуватися всередині native harness Codex до того, як вивід інструмента буде спроєктовано -назад у транскрипт OpenClaw. +Plugin-и можуть підключати нейтральне щодо harness middleware для результатів інструментів через +`api.registerAgentToolResultMiddleware(...)`, коли їхній manifest оголошує +цільові id harness-ів у `contracts.agentToolResultMiddleware`. Це шов для +асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex +повернуть вивід інструмента назад у модель. -### Режим native harness Codex +Застарілі вбудовані Plugin-и все ще можуть використовувати +`api.registerCodexAppServerExtensionFactory(...)` для middleware лише app-server Codex, +але нові перетворення результатів мають використовувати API, нейтральний щодо harness-а. +Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` є застарілим для +перетворень результатів інструментів; зберігайте його лише для коду сумісності вбудованих компонентів, якому +досі потрібні прямі події embedded-runner-а Pi. -Вбудований harness `codex` — це native-режим Codex для вбудованих циклів -агента OpenClaw. Спочатку ввімкніть вбудований Plugin `codex` і додайте `codex` до -`plugins.allow`, якщо у вашій конфігурації використовується обмежувальний allowlist. Конфігурації native app-server +### Режим нативного harness-а Codex + +Вбудований harness `codex` — це нативний режим Codex для вбудованих +ходів агента OpenClaw. Спочатку ввімкніть вбудований Plugin `codex` і додайте `codex` до +`plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Конфігурації нативного app-server мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. -Використовуйте `openai-codex/*` для Codex OAuth через PI. Legacy-посилання на модель `codex/*` -залишаються псевдонімами сумісності для native harness. +Використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі refs моделей `codex/*` +і далі залишаються псевдонімами сумісності для нативного harness-а. -Коли цей режим працює, Codex володіє native thread id, поведінкою resume, -Compaction і виконанням app-server. OpenClaw і далі володіє каналом чату, -видимим дзеркалом транскрипту, політикою інструментів, approvals, доставкою медіа й -вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із -`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях -Codex app-server може заявити про цей запуск. Ця конфігурація є лише запобіжником вибору: -збої Codex app-server уже й так завершуються помилкою напряму, без повторної спроби через PI. +Коли цей режим працює, Codex володіє нативним id треду, поведінкою resume, +Compaction і виконанням app-server. OpenClaw, як і раніше, володіє чатом каналу, +видимим дзеркалом транскрипту, політикою інструментів, схваленнями, доставкою медіа та +вибором сеансу. Використовуйте `embeddedHarness.runtime: "codex"` разом із +`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що запуск може +заявити лише шлях app-server Codex. Цей config є лише захистом вибору: +помилки app-server Codex уже напряму завершуються помилкою замість повторної спроби через PI. -## Вимкнення fallback до PI +## Вимкнення fallback на PI -Типово OpenClaw запускає вбудованих агентів з `agents.defaults.embeddedHarness`, -установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані Plugin -harness-и можуть заявляти про пару провайдер/модель. Якщо жоден не підходить, OpenClaw повертається до PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, +встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані +harness-и Plugin-ів можуть заявити пару provider/model. Якщо жоден не підходить, OpenClaw +переходить до PI. -Установіть `fallback: "none"`, коли вам потрібно, щоб відсутність вибору Plugin harness завершувалася -помилкою замість використання PI. Збої вибраного Plugin harness і так уже завершуються жорсткою помилкою. Це -не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору harness-а Plugin-а +завершувалася помилкою замість використання PI. Помилки вже вибраних harness-ів Plugin-ів і так +завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. -Для вбудованих запусків лише з Codex: +Для вбудованих запусків лише Codex: ```json { @@ -203,8 +210,9 @@ harness-и можуть заявляти про пару провайдер/мо } ``` -Якщо ви хочете, щоб будь-який зареєстрований Plugin harness міг заявляти про відповідні моделі, але ніколи -не хочете, щоб OpenClaw непомітно повертався до PI, залиште `runtime: "auto"` і вимкніть fallback: +Якщо ви хочете, щоб будь-який зареєстрований harness Plugin-а міг заявити сумісні моделі, але ніколи +не хочете, щоб OpenClaw непомітно переходив до PI, залиште `runtime: "auto"` і вимкніть +fallback: ```json { @@ -219,7 +227,7 @@ harness-и можуть заявляти про пару провайдер/мо } ``` -Перевизначення для окремого агента використовують ту саму форму: +Перевизначення на рівні агента використовують ту саму форму: ```json { @@ -244,8 +252,8 @@ harness-и можуть заявляти про пару провайдер/мо } ``` -`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштоване runtime-середовище. Використовуйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback до PI через +`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI через середовище. ```bash @@ -254,53 +262,53 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли fallback вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний harness не -зареєстровано, він не підтримує визначені провайдера/модель або завершується помилкою до -створення побічних ефектів циклу. Це зроблено навмисно для розгортань лише з Codex і -для live-тестів, які мають довести, що фактично використовується саме шлях Codex app-server. +Коли fallback вимкнено, сеанс завершується рано з помилкою, якщо запитаний harness не +зареєстровано, він не підтримує визначеного provider/model або завершується +помилкою до появи побічних ефектів ходу. Це навмисно для розгортань лише Codex і +для live-тестів, які мають довести, що шлях app-server Codex справді використовується. -Це налаштування керує лише вбудованим harness агента. Воно не вимикає -маршрутизацію моделей, специфічну для провайдерів, для зображень, відео, музики, TTS, PDF чи інших. +Цей параметр керує лише вбудованим harness-ом агента. Він не вимикає +маршрутизацію моделей, специфічну для provider, для image, video, music, TTS, PDF або інших типів. -## Native-сесії та дзеркало транскрипту +## Нативні сеанси й дзеркало транскрипту -Harness може зберігати native session id, thread id або токен resume на боці daemon. -Явно пов’язуйте це прив’язування із сесією OpenClaw і продовжуйте -дзеркалити видимий користувачеві вивід помічника/інструментів у транскрипт OpenClaw. +Harness може зберігати нативний id сеансу, id треду або токен resume на боці демона. +Тримайте цю привʼязку явно повʼязаною із сеансом OpenClaw і продовжуйте +дзеркалити видимий користувачу вивід assistant/tool у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для: -- історії сесії, видимої в каналі -- пошуку та індексації транскрипту -- повернення до вбудованого harness PI на пізнішому циклі -- загальної поведінки `/new`, `/reset` і видалення сесії +- видимої в каналі історії сеансу +- пошуку та індексації транскриптів +- перемикання назад на вбудований harness PI на наступному ході +- узагальненої поведінки `/new`, `/reset` і видалення сеансу -Якщо ваш harness зберігає sidecar-прив’язування, реалізуйте `reset(...)`, щоб OpenClaw міг -очищати його під час скидання відповідної сесії OpenClaw. +Якщо ваш harness зберігає sidecar-привʼязку, реалізуйте `reset(...)`, щоб OpenClaw міг +очистити її під час скидання повʼязаного сеансу OpenClaw. ## Результати інструментів і медіа Core формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента через -форму результату harness замість того, щоб самостійно надсилати медіа каналом. +форму результату harness-а замість того, щоб самостійно надсилати медіа в канал. -Це дозволяє тексту, зображенням, відео, музиці, TTS, approvals і виводам -інструментів повідомлень проходити тим самим шляхом доставки, що й у запусках на базі PI. +Це зберігає text, image, video, music, TTS, approval і результати +інструментів для повідомлень на тому ж шляху доставки, що й запуски на базі PI. ## Поточні обмеження -- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроб/результатів усе ще +- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроб/результатів досі містять назви `Pi` для сумісності. -- Установлення сторонніх harness-ів є експериментальним. Надавайте перевагу provider plugin-ам, - доки вам не знадобиться native session runtime. -- Перемикання harness-ів між циклами підтримується. Не перемикайте harness-и посеред - циклу після того, як уже почалися native-інструменти, approvals, текст помічника або +- Установлення сторонніх harness-ів є експериментальним. Віддавайте перевагу provider Plugin-ам, + доки вам не знадобиться нативний runtime сеансів. +- Перемикання harness-ів між ходами підтримується. Не перемикайте harness-и посеред + ходу після того, як уже почалися нативні інструменти, схвалення, текст assistant-а або надсилання повідомлень. ## Пов’язане -- [Огляд SDK](/uk/plugins/sdk-overview) +- [SDK Overview](/uk/plugins/sdk-overview) - [Runtime Helpers](/uk/plugins/sdk-runtime) - [Provider Plugins](/uk/plugins/sdk-provider-plugins) - [Codex Harness](/uk/plugins/codex-harness) -- [Провайдери моделей](/uk/concepts/model-providers) +- [Model Providers](/uk/concepts/model-providers) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 3f2b322e8..094bf77e9 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -1,92 +1,166 @@ --- read_when: - - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - - Ви оновлюєте Plugin до сучасної архітектури плагінів - - Ви підтримуєте зовнішній Plugin OpenClaw + - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED. + - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED. + - Ви використовуєте `api.registerEmbeddedExtensionFactory`. + - Ви оновлюєте Plugin до сучасної архітектури plugin. + - Ви підтримуєте зовнішній Plugin OpenClaw. sidebarTitle: Migrate to SDK -summary: Перейдіть зі застарілого шару зворотної сумісності на сучасний Plugin SDK +summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK. title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-24T08:35:11Z" + generated_at: "2026-04-24T19:52:07Z" model: gpt-5.4 provider: openai - source_hash: d1461ae8a7de0a802c9deb59f843e7d93d9d73bea22c27d837ca2db8ae9d14b7 + source_hash: fa44b2e9f3748ce41c91b5e389dbe0acee03e2ec84b35086068f419a252208a0 source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури plugin +із точковими, задокументованими імпортами. Якщо ваш Plugin було створено до +нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система плагінів надавала дві широко відкриті поверхні, які дозволяли Plugin імпортувати все необхідне з однієї точки входу: +Стара система plugin надавала дві широко відкриті поверхні, які дозволяли plugin +імпортувати все необхідне з єдиної точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб старіші плагіни на основі хуків продовжували працювати, поки створювалася нова архітектура плагінів. -- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до допоміжних засобів на стороні хоста, таких як вбудований запускальник агентів. +- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував десятки + допоміжних засобів. Його було додано, щоб старіші hook-based plugin продовжували працювати, поки + будувалася нова архітектура plugin. +- **`openclaw/extension-api`** — міст, який давав plugin прямий доступ до + host-side helper, таких як вбудований runner агента. +- **`api.registerEmbeddedExtensionFactory(...)`** — hook bundled extension лише для Pi, + який міг спостерігати за подіями embedded-runner, такими як `tool_result`. -Обидві ці поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові плагіни не повинні їх використовувати, а наявні — мають перейти до наступного великого релізу, у якому їх буде видалено. +Тепер ці поверхні **застарілі**. Вони все ще працюють під час виконання, але нові +plugin не повинні їх використовувати, а наявним plugin слід мігрувати до того, як +наступний мажорний реліз їх видалить. -OpenClaw не видаляє і не переосмислює задокументовану поведінку Plugin у тій самій зміні, де з’являється заміна. Зміни контракту, що порушують сумісність, спочатку мають пройти через адаптер сумісності, діагностику, документацію та вікно застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки реєстрації під час виконання. +OpenClaw не видаляє й не переосмислює задокументовану поведінку plugin у тій самій +зміні, яка вводить заміну. Зміни контракту, що ламають сумісність, спочатку мають пройти +через адаптер сумісності, діагностику, документацію та вікно депрекації. +Це стосується імпортів SDK, полів маніфесту, API налаштування, hooks і поведінки +реєстрації під час виконання. - Шар зворотної сумісності буде видалено в одному з майбутніх великих релізів. - Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. + Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів. + Plugin, які досі імпортують із цих поверхонь, перестануть працювати, коли це станеться. ## Чому це змінилося Старий підхід спричиняв проблеми: -- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних модулів -- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту -- **Неочевидна поверхня API** — неможливо було зрозуміти, які експорти були стабільними, а які — внутрішніми +- **Повільний запуск** — імпорт одного helper завантажував десятки не пов’язаних модулів +- **Циклічні залежності** — широкі повторні експорти полегшували створення циклів імпорту +- **Неясна поверхня API** — не було способу зрозуміти, які експорти стабільні, а які внутрішні -Сучасний Plugin SDK виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) є невеликим самодостатнім модулем із чітким призначенням і задокументованим контрактом. +Сучасний Plugin SDK це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим самодостатнім модулем із чітким призначенням і задокументованим контрактом. -Застарілі зручні шви провайдерів для вбудованих каналів також прибрано. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, фірмові допоміжні шви каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями монорепозиторію, а не стабільними контрактами Plugin. Натомість використовуйте вузькі узагальнені підшляхи SDK. Усередині робочого простору вбудованого Plugin зберігайте допоміжні засоби, що належать провайдеру, у власному `api.ts` або `runtime-api.ts` цього Plugin. +Застарілі зручні seams постачальників для bundled channels також зникли. Імпорти +на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, +helper seams із брендингом channel і +`openclaw/plugin-sdk/telegram-core` були приватними скороченнями mono-repo, а не +стабільними контрактами plugin. Натомість використовуйте вузькі загальні subpath SDK. Усередині +робочого простору bundled plugin зберігайте helper, які належать постачальнику, у власному +`api.ts` або `runtime-api.ts` цього plugin. -Поточні приклади вбудованих провайдерів: +Поточні приклади bundled provider: -- Anthropic зберігає допоміжні засоби потокового передавання, специфічні для Claude, у власному шві `api.ts` / `contract-api.ts` -- OpenAI зберігає конструктори провайдерів, допоміжні засоби моделей за замовчуванням і конструктори провайдерів realtime у власному `api.ts` -- OpenRouter зберігає конструктор провайдера та допоміжні засоби онбордингу/конфігурації у власному `api.ts` +- Anthropic зберігає helper потоків, специфічні для Claude, у власному seam `api.ts` / + `contract-api.ts` +- OpenAI зберігає builder-и provider, helper-и моделей за замовчуванням і builder-и + realtime provider у власному `api.ts` +- OpenRouter зберігає helper-и builder provider і onboarding/config у власному + `api.ts` ## Політика сумісності -Для зовнішніх плагінів робота із сумісністю виконується в такому порядку: +Для зовнішніх plugin робота із сумісністю відбувається в такому порядку: 1. додати новий контракт -2. зберегти стару поведінку, підключивши її через адаптер сумісності -3. вивести діагностичне повідомлення або попередження, яке називає старий шлях і заміну +2. зберегти стару поведінку через адаптер сумісності +3. виводити діагностику або попередження, що вказує старий шлях і заміну 4. покрити обидва шляхи в тестах -5. задокументувати застарівання та шлях міграції -6. видаляти лише після оголошеного вікна міграції, зазвичай у великому релізі +5. задокументувати депрекацію та шлях міграції +6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному релізі -Якщо поле маніфесту все ще приймається, автори Plugin можуть і далі його використовувати, доки документація та діагностика не вкажуть інше. Новий код має надавати перевагу задокументованій заміні, але наявні плагіни не повинні ламатися в межах звичайних мінорних релізів. +Якщо поле маніфесту все ще приймається, автори plugin можуть і далі його використовувати, +доки документація та діагностика не скажуть інакше. Новий код має надавати перевагу +задокументованій заміні, але наявні plugin не повинні ламатися під час звичайних мінорних +релізів. ## Як виконати міграцію - - Плагіни каналів із підтримкою погодження тепер надають нативну поведінку погодження через `approvalCapability.nativeRuntime` разом зі спільним реєстром контексту виконання. + + Замініть handler-и `api.registerEmbeddedExtensionFactory(...)` для tool-result, що + працюють лише з Pi, на harness-neutral middleware. - Ключові зміни: + ```typescript + // Before: Pi-only compatibility hook + api.registerEmbeddedExtensionFactory((pi) => { + pi.on("tool_result", async (event) => { + return compactToolResult(event); + }); + }); - - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть специфічну для погодження автентифікацію/доставлення зі застарілого зв’язування `plugin.auth` / `plugin.approvals` на `approvalCapability` - - `ChannelPlugin.approvals` було видалено з публічного контракту channel-plugin; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу каналу; хуки автентифікації погодження там більше не читаються ядром - - Реєструйте об’єкти виконання, що належать каналу, наприклад клієнти, токени або застосунки Bolt, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте сповіщення про перенаправлення, що належать Plugin, із нативних обробників погодження; ядро тепер само керує сповіщеннями про доставлення в інше місце на основі фактичних результатів доставлення - - Передаючи `channelRuntime` у `createChannelManager(...)`, надавайте справжню поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. + // After: Pi and Codex app-server dynamic tools + api.registerAgentToolResultMiddleware(async (event) => { + return compactToolResult(event); + }, { + harnesses: ["pi", "codex-app-server"], + }); + ``` - Див. `/plugins/sdk-channel-plugins`, щоб ознайомитися з поточною структурою можливостей погодження. + Одночасно оновіть маніфест plugin: + + ```json + { + "contracts": { + "agentToolResultMiddleware": ["pi", "codex-app-server"] + } + } + ``` + + Залишайте `contracts.embeddedExtensionFactories` лише для bundled compatibility + коду, якому все ще потрібні прямі події Pi embedded-runner. - - Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані обгортки Windows `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. + + Plugin channel, які підтримують approval, тепер відкривають нативну поведінку approval через + `approvalCapability.nativeRuntime` плюс спільний реєстр runtime-context. + + Ключові зміни: + + - Замініть `approvalCapability.handler.loadRuntime(...)` на + `approvalCapability.nativeRuntime` + - Перенесіть auth/delivery, специфічні для approval, із застарілого зв’язування `plugin.auth` / + `plugin.approvals` на `approvalCapability` + - `ChannelPlugin.approvals` видалено з публічного контракту channel-plugin; + перенесіть поля delivery/native/render до `approvalCapability` + - `plugin.auth` залишається лише для потоків входу/виходу channel; approval auth + hooks там більше не читаються core + - Реєструйте runtime-об’єкти, що належать channel, такі як clients, tokens або Bolt + apps, через `openclaw/plugin-sdk/channel-runtime-context` + - Не надсилайте повідомлення reroute, що належать plugin, із native approval handler-ів; + тепер core відповідає за routed-elsewhere notices на основі фактичних результатів доставки + - Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте + справжню поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються. + + Див. `/plugins/sdk-channel-plugins` для актуального макета approval capability. + + + + + Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані обгортки Windows + `.cmd`/`.bat` тепер завершуються без fallback, якщо ви явно не передасте + `allowShellFallback: true`. ```typescript // Before @@ -95,18 +169,19 @@ OpenClaw не видаляє і не переосмислює задокумен // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Only set this for trusted compatibility callers that intentionally + // Set this only for trusted compatibility callers that intentionally // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Якщо ваш виклик навмисно не покладається на резервний перехід через оболонку, не встановлюйте `allowShellFallback`, а натомість обробіть згенеровану помилку. + Якщо ваш код навмисно не покладається на shell fallback, не встановлюйте + `allowShellFallback`, а натомість обробіть викинуту помилку. - Пошукайте у своєму Plugin імпорти з будь-якої із застарілих поверхонь: + Знайдіть у вашому plugin імпорти з будь-якої із застарілих поверхонь: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -115,7 +190,7 @@ OpenClaw не видаляє і не переосмислює задокумен - + Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту: ```typescript @@ -132,7 +207,8 @@ OpenClaw не видаляє і не переосмислює задокумен import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на стороні хоста використовуйте впроваджене середовище виконання Plugin замість прямого імпорту: + Для host-side helper використовуйте injected runtime plugin замість + прямого імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -143,7 +219,7 @@ OpenClaw не видаляє і не переосмислює задокумен const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується й до інших застарілих допоміжних засобів мосту: + Той самий шаблон застосовується до інших helper-ів застарілого bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -153,7 +229,7 @@ OpenClaw не видаляє і не переосмислює задокумен | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | + | helper-и session store | `api.runtime.agent.session.*` | @@ -168,185 +244,185 @@ OpenClaw не видаляє і не переосмислює задокумен ## Довідник шляхів імпорту - | Шлях імпорту | Призначення | Ключові експорти | + | Import path | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу Plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий парасольковий повторний експорт для визначень/конструкторів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цільові визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, конструктори статусу налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби середовища виконання під час налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | - | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Допоміжні засоби інструментарію налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/конфігурації/шлюзу дій облікових записів | - | `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікових записів | Допоміжні засоби пошуку облікових записів + резервного використання типового значення | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби списку облікових записів/дій облікового запису | + | `plugin-sdk/plugin-entry` | Канонічний helper точки входу Plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий umbrella re-export для визначень/builder-ів точки входу channel | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Експорт схеми конфігурації root | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Helper точки входу одного provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Точкові визначення й builder-и точки входу channel | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні helper-и майстра налаштування | Запити allowlist, builder-и статусу налаштування | + | `plugin-sdk/setup-runtime` | Helper-и runtime під час налаштування | Безпечні для імпорту адаптери patch налаштування, helper-и lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies | + | `plugin-sdk/setup-adapter-runtime` | Helper-и адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Helper-и інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Helper-и багатьох облікових записів | Helper-и списку/config/action-gate облікових записів | + | `plugin-sdk/account-id` | Helper-и account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | + | `plugin-sdk/account-resolution` | Helper-и пошуку облікового запису | Helper-и пошуку облікового запису + fallback за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі helper-и облікового запису | Helper-и списку облікових записів/account-action | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Примітиви спарювання DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + індикатора набору | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання опису, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `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-runtime` | Допоміжні засоби середовища виконання вихідних даних | Допоміжні засоби outbound identity/send delegate та планування payload | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу та адаптера прив’язки потоків | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор agent media payload для застарілих макетів полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти середовища виконання каналу | - | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | + | `plugin-sdk/channel-pairing` | Примітиви pairing для DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Підключення префікса reply + typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів config | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Builder-и схем config | Типи схем конфігурації channel | + | `plugin-sdk/telegram-command-config` | Helper-и config команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Визначення політики group/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Helper-и життєвого циклу статусу облікового запису та draft stream | `createAccountStatusSink`, helper-и фіналізації попереднього перегляду draft | + | `plugin-sdk/inbound-envelope` | Helper-и вхідного envelope | Спільні helper-и побудови route + envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helper-и вхідного reply | Спільні helper-и record-and-dispatch | + | `plugin-sdk/messaging-targets` | Парсинг цілей повідомлень | Helper-и парсингу/зіставлення цілей | + | `plugin-sdk/outbound-media` | Helper-и вихідного media | Спільне завантаження вихідного media | + | `plugin-sdk/outbound-runtime` | Helper-и вихідного runtime | Helper-и вихідної identity/send delegate і планування payload | + | `plugin-sdk/thread-bindings-runtime` | Helper-и thread-binding | Helper-и життєвого циклу та адаптера thread-binding | + | `plugin-sdk/agent-media-payload` | Застарілі helper-и media payload | Builder agent media payload для застарілих макетів полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime channel | + | `plugin-sdk/channel-send-result` | Типи результатів send | Типи результатів reply | | `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби середовища виконання | Допоміжні засоби runtime/logging/backup/встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, допоміжні засоби timeout, retry та backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби середовища виконання Plugin | Допоміжні засоби команд/хуків/http/інтерактивності Plugin | - | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра хуків | Спільні допоміжні засоби конвеєра Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого середовища виконання | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | - | `plugin-sdk/cli-runtime` | Допоміжні засоби середовища виконання CLI | Форматування команд, очікування, допоміжні засоби версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Допоміжні засоби клієнта Gateway та патчів статусу каналу | - | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів погодження | Допоміжні засоби payload погодження exec/Plugin, допоміжні засоби approval capability/profile, допоміжні засоби маршрутизації/середовища виконання нативного погодження | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби автентифікації погодження | Визначення approver, авторизація дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта погодження | Допоміжні засоби profile/filter нативного погодження exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставлення погодження | Адаптери нативної approval capability/delivery | - | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway погодження | Спільний допоміжний засіб визначення approval Gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера погодження | Полегшені допоміжні засоби завантаження адаптера нативного погодження для гарячих точок входу каналу | - | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника погодження | Ширші допоміжні засоби середовища виконання обробника погодження; надавайте перевагу вужчим швам adapter/gateway, якщо їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей погодження | Допоміжні засоби нативного погодження для прив’язки цілі/облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді погодження | Допоміжні засоби payload відповіді погодження exec/Plugin | - | `plugin-sdk/channel-runtime-context` | Допоміжні засоби контексту середовища виконання каналу | Узагальнені допоміжні засоби register/get/watch для контексту середовища виконання каналу | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби середовища виконання SSRF | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF | - | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби шлюзування діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні засоби повторних спроб | `RetryConfig`, `retryAsync`, виконавці політик | + | `plugin-sdk/runtime` | Широкі helper-и runtime | Helper-и runtime/logging/backup/plugin-install | + | `plugin-sdk/runtime-env` | Вузькі helper-и runtime env | Helper-и logger/runtime env, timeout, retry і backoff | + | `plugin-sdk/plugin-runtime` | Спільні helper-и runtime Plugin | Helper-и команд/hooks/http/interactive для Plugin | + | `plugin-sdk/hook-runtime` | Helper-и pipeline hook | Спільні helper-и pipeline webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Helper-и lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helper-и process | Спільні helper-и exec | + | `plugin-sdk/cli-runtime` | Helper-и CLI runtime | Форматування команд, очікування, helper-и версій | + | `plugin-sdk/gateway-runtime` | Helper-и Gateway | Helper-и клієнта Gateway і patch статусу channel | + | `plugin-sdk/config-runtime` | Helper-и config | Helper-и завантаження/запису config | + | `plugin-sdk/telegram-command-config` | Helper-и команд Telegram | Helper-и валідації команд Telegram зі стабільним fallback, коли поверхня контракту bundled Telegram недоступна | + | `plugin-sdk/approval-runtime` | Helper-и prompt approval | Payload exec/plugin approval, helper-и capability/profile approval, helper-и маршрутизації/runtime native approval | + | `plugin-sdk/approval-auth-runtime` | Helper-и auth approval | Визначення approver, auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Helper-и клієнта approval | Helper-и профілю/фільтра native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Helper-и доставки approval | Адаптери capability/delivery native approval | + | `plugin-sdk/approval-gateway-runtime` | Helper-и Gateway approval | Спільний helper визначення Gateway approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Helper-и адаптера approval | Легковагові helper-и завантаження адаптера native approval для гарячих точок входу channel | + | `plugin-sdk/approval-handler-runtime` | Helper-и handler approval | Ширші helper-и runtime handler approval; надавайте перевагу вужчим seams adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Helper-и цілей approval | Helper-и прив’язки цілі/облікового запису native approval | + | `plugin-sdk/approval-reply-runtime` | Helper-и reply approval | Helper-и payload reply exec/plugin approval | + | `plugin-sdk/channel-runtime-context` | Helper-и runtime-context channel | Загальні helper-и register/get/watch для runtime-context channel | + | `plugin-sdk/security-runtime` | Helper-и безпеки | Спільні helper-и trust, DM gating, external-content і збирання секретів | + | `plugin-sdk/ssrf-policy` | Helper-и політики SSRF | Helper-и allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Helper-и runtime SSRF | Helper-и pinned-dispatcher, guarded fetch, SSRF policy | + | `plugin-sdk/collection-runtime` | Helper-и обмеженого кешу | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Helper-и керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Helper-и форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, helper-и графа помилок | + | `plugin-sdk/fetch-runtime` | Helper-и wrapped fetch/proxy | `resolveFetch`, helper-и proxy | + | `plugin-sdk/host-runtime` | Helper-и нормалізації host | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Helper-и retry | `RetryConfig`, `retryAsync`, виконавці політик | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Шлюзування команд і допоміжні засоби поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/command-status` | Рендерери статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Розбір введення секретів | Допоміжні засоби введення секретів | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільне середовище виконання відповідей | Вхідна диспетчеризація, Heartbeat, планувальник відповідей, поділ на частини | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Допоміжні засоби finalize, provider dispatch і labels розмов | - | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань на відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби chunk для відповідей | Допоміжні засоби поділу тексту/markdown на частини | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key | - | `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори зведення статусу каналу/облікового запису, типові значення стану виконання, допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілей | Спільні допоміжні засоби target resolver | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягування рядкових URL із вхідних даних, подібних до запиту | - | `plugin-sdk/run-command` | Допоміжні засоби команд із таймером | Виконавець команд із таймером із нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Читачі параметрів | Поширені читачі параметрів інструментів/CLI | - | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload з об’єктів результатів інструментів | - | `plugin-sdk/tool-send` | Витягування send інструмента | Витягування канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів для тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби журналювання | Допоміжні засоби logger підсистем і редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режиму markdown-таблиць | - | `plugin-sdk/reply-payload` | Типи відповідей повідомлень | Типи payload відповідей | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | Допоміжні засоби виявлення/конфігурації self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted провайдерів | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби автентифікації провайдера під час виконання | Допоміжні засоби визначення API-ключа під час виконання | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результатів автентифікації провайдера | Стандартний конструктор результату автентифікації OAuth | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору провайдера | Вибір налаштованого або автоматичного провайдера та об’єднання необроблених конфігурацій провайдера | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars провайдера | Допоміжні засоби пошуку env vars для автентифікації провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделі/повторного відтворення провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики повторного відтворення, допоміжні засоби endpoint провайдера та нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні засоби конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Узагальнені допоміжні засоби HTTP/можливостей endpoint провайдера, зокрема допоміжні засоби multipart form для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search провайдера | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне зв’язування ввімкнення Plugin | - | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter для облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/середовища виконання провайдера web-search | - | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання провайдера | - | `plugin-sdk/provider-stream` | Допоміжні засоби обгортки потоку провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту провайдера | Нативні допоміжні засоби транспорту провайдера, як-от guarded fetch, перетворення транспортних повідомлень і доступні для запису потоки транспортних подій | - | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби отримання/перетворення/зберігання медіа, а також конструктори media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору кандидата та повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдерів media understanding, а також орієнтовані на провайдера експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для асистента тексту, допоміжні засоби рендерингу/поділу на частини/таблиць markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/журналювання | - | `plugin-sdk/text-chunking` | Допоміжні засоби поділу тексту на частини | Допоміжний засіб поділу вихідного тексту на частини | - | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи провайдерів мовлення, а також орієнтовані на провайдера допоміжні засоби директив, реєстру та валідації | - | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдерів мовлення, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції realtime | Типи провайдерів, допоміжні засоби реєстру та спільний допоміжний засіб WebSocket session | - | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу realtime | Типи провайдерів, допоміжні засоби реєстру/визначення та допоміжні засоби bridge session | - | `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/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/згортання payload інтерактивних відповідей | - | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви schema конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільний прелюд каналу | Експорти спільного прелюду channel Plugin | - | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби ухвалення рішень щодо доступу до груп | - | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби автентифікації/guard для direct-DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби розширення | Примітиви допоміжних засобів passive-channel/status та ambient proxy | - | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Допоміжні засоби реєстру цілей Webhook та встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляху Webhook | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби вебмедіа | Допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для користувачів Plugin SDK | - | `plugin-sdk/memory-core` | Вбудовані допоміжні засоби memory-core | Поверхня допоміжних засобів менеджера пам’яті/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання механізму пам’яті | Фасад середовища виконання індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий механізм хоста пам’яті | Експорти базового механізму хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Механізм embedding хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний провайдер і узагальнені пакетні/віддалені допоміжні засоби; конкретні віддалені провайдери розміщуються у Plugin, якому вони належать | - | `plugin-sdk/memory-core-host-engine-qmd` | Механізм QMD хоста пам’яті | Експорти механізму QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Механізм сховища хоста пам’яті | Експорти механізму сховища хоста пам’яті | - | `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` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Базове runtime хоста пам’яті | Допоміжні засоби базового runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Псевдонім базового runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів базового runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для Plugin, суміжних із пам’яттю | + | `plugin-sdk/command-auth` | Керування командами та helper-и поверхні команд | `resolveControlCommandGate`, helper-и авторизації відправника, helper-и реєстру команд | + | `plugin-sdk/command-status` | Рендерери статусу/help команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Парсинг secret input | Helper-и secret input | + | `plugin-sdk/webhook-ingress` | Helper-и запитів Webhook | Утиліти цілі Webhook | + | `plugin-sdk/webhook-request-guards` | Helper-и guards тіла запиту Webhook | Helper-и читання/ліміту тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний runtime reply | Inbound dispatch, Heartbeat, planner reply, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі helper-и dispatch reply | Helper-и finalize, provider dispatch і міток conversation | + | `plugin-sdk/reply-history` | Helper-и історії reply | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилань reply | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Helper-и chunk reply | Helper-и chunking text/markdown | + | `plugin-sdk/session-store-runtime` | Helper-и session store | Helper-и шляху сховища + updated-at | + | `plugin-sdk/state-paths` | Helper-и шляхів стану | Helper-и каталогів state і OAuth | + | `plugin-sdk/routing` | Helper-и routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper-и нормалізації session-key | + | `plugin-sdk/status-helpers` | Helper-и статусу channel | Builder-и зведення статусу channel/account, значення runtime-state за замовчуванням, helper-и метаданих issue | + | `plugin-sdk/target-resolver-runtime` | Helper-и визначення цілі | Спільні helper-и визначення цілі | + | `plugin-sdk/string-normalization-runtime` | Helper-и нормалізації рядків | Helper-и нормалізації slug/рядків | + | `plugin-sdk/request-url` | Helper-и URL запиту | Витяг рядкових URL з request-подібних вхідних даних | + | `plugin-sdk/run-command` | Helper-и timed command | Виконавець timed command із нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Зчитувачі параметрів | Загальні зчитувачі параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягнення payload tool | Витяг нормалізованих payload з об’єктів результатів tool | + | `plugin-sdk/tool-send` | Витягнення send tool | Витяг канонічних полів цілі send з аргументів tool | + | `plugin-sdk/temp-path` | Helper-и тимчасових шляхів | Спільні helper-и шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Helper-и logging | Helper-и logger підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Helper-и markdown-table | Helper-и режимів markdown table | + | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload reply | + | `plugin-sdk/provider-setup` | Кураторські helper-и налаштування локальних/self-hosted provider | Helper-и виявлення/конфігурації self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Точкові helper-и налаштування self-hosted provider, сумісного з OpenAI | Ті самі helper-и виявлення/конфігурації self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Helper-и runtime auth provider | Helper-и визначення API-key під час виконання | + | `plugin-sdk/provider-auth-api-key` | Helper-и налаштування API-key provider | Helper-и onboarding/profile-write для API-key | + | `plugin-sdk/provider-auth-result` | Helper-и auth-result provider | Стандартний builder auth-result OAuth | + | `plugin-sdk/provider-auth-login` | Helper-и інтерактивного входу provider | Спільні helper-и інтерактивного входу | + | `plugin-sdk/provider-selection-runtime` | Helper-и вибору provider | Вибір provider configured-or-auto і злиття raw config provider | + | `plugin-sdk/provider-env-vars` | Helper-и env var provider | Helper-и пошуку auth env var provider | + | `plugin-sdk/provider-model-shared` | Спільні helper-и моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, helper-и endpoint provider і helper-и нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні helper-и каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Патчі onboarding provider | Helper-и конфігурації onboarding | + | `plugin-sdk/provider-http` | Helper-и HTTP provider | Загальні helper-и HTTP/можливостей endpoint provider, зокрема helper-и multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch` | Helper-и web-fetch provider | Helper-и реєстрації/кешу provider web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helper-и конфігурації web-search provider | Вузькі helper-и config/облікових даних web-search для provider, яким не потрібне зв’язування enable Plugin | + | `plugin-sdk/provider-web-search-contract` | Helper-и контракту web-search provider | Вузькі helper-и контракту config/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter-и облікових даних з обмеженою областю | + | `plugin-sdk/provider-web-search` | Helper-и web-search provider | Helper-и реєстрації/кешу/runtime provider web-search | + | `plugin-sdk/provider-tools` | Helper-и сумісності tool/schema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також helper-и сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Helper-и використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші helper-и використання provider | + | `plugin-sdk/provider-stream` | Helper-и обгортки stream provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні helper-и обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Helper-и транспорту provider | Нативні helper-и транспорту provider, такі як guarded fetch, перетворення transport message і доступні для запису event stream транспорту | + | `plugin-sdk/keyed-async-queue` | Упорядкована async queue | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні helper-и media | Helper-и fetch/transform/store для media, а також builder-и media payload | + | `plugin-sdk/media-generation-runtime` | Спільні helper-и генерації media | Спільні helper-и failover, вибір кандидатів і повідомлення про відсутню модель для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Helper-и media-understanding | Типи provider media understanding, а також експортовані helper-и зображень/аудіо для provider | + | `plugin-sdk/text-runtime` | Спільні helper-и text | Видалення видимого асистенту тексту, helper-и рендерингу/chunking/table для markdown, helper-и редагування, helper-и тегів директив, утиліти safe-text і пов’язані helper-и text/logging | + | `plugin-sdk/text-chunking` | Helper-и chunking тексту | Helper chunking вихідного тексту | + | `plugin-sdk/speech` | Helper-и speech | Типи provider speech, а також helper-и директив, registry і валідації для provider | + | `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider speech, registry, директиви, нормалізація | + | `plugin-sdk/realtime-transcription` | Helper-и транскрибування в реальному часі | Типи provider, helper-и registry і спільний helper WebSocket session | + | `plugin-sdk/realtime-voice` | Helper-и голосу в реальному часі | Типи provider, helper-и registry/визначення та helper-и bridge session | + | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, helper-и failover, auth і registry | + | `plugin-sdk/music-generation` | Helper-и генерації музики | Типи provider/request/result для генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, helper-и failover, пошук provider і парсинг model-ref | + | `plugin-sdk/video-generation` | Helper-и генерації відео | Типи provider/request/result для генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, helper-и failover, пошук provider і парсинг model-ref | + | `plugin-sdk/interactive-runtime` | Helper-и інтерактивного reply | Нормалізація/зменшення payload інтерактивного reply | + | `plugin-sdk/channel-config-primitives` | Примітиви config channel | Вузькі примітиви config-schema channel | + | `plugin-sdk/channel-config-writes` | Helper-и запису config channel | Helper-и авторизації запису config channel | + | `plugin-sdk/channel-plugin-common` | Спільний prelude channel | Експорти спільного prelude plugin channel | + | `plugin-sdk/channel-status` | Helper-и статусу channel | Спільні helper-и snapshot/summary статусу channel | + | `plugin-sdk/allowlist-config-edit` | Helper-и config allowlist | Helper-и редагування/читання config allowlist | + | `plugin-sdk/group-access` | Helper-и доступу до group | Спільні helper-и прийняття рішень щодо доступу до group | + | `plugin-sdk/direct-dm` | Helper-и direct-DM | Спільні helper-и auth/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні helper-и extension | Примітиви helper-ів passive-channel/status і ambient proxy | + | `plugin-sdk/webhook-targets` | Helper-и цілей Webhook | Реєстр цілей Webhook і helper-и встановлення route | + | `plugin-sdk/webhook-path` | Helper-и шляху Webhook | Helper-и нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні helper-и web media | Helper-и завантаження віддалених/локальних media | + | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів Plugin SDK | + | `plugin-sdk/memory-core` | Helper-и bundled memory-core | Поверхня helper-ів memory manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексації/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій host пам’яті | Експорти базового рушія host пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding host пам’яті | Контракти embedding пам’яті, доступ до registry, local provider і загальні helper-и batch/remote; конкретні remote provider містяться у plugin, яким вони належать | + | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD host пам’яті | Експорти рушія QMD host пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища host пам’яті | Експорти рушія сховища host пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні helper-и host пам’яті | Мультимодальні helper-и host пам’яті | + | `plugin-sdk/memory-core-host-query` | Helper-и запитів host пам’яті | Helper-и запитів host пам’яті | + | `plugin-sdk/memory-core-host-secret` | Helper-и секретів host пам’яті | Helper-и секретів host пам’яті | + | `plugin-sdk/memory-core-host-events` | Helper-и журналу подій host пам’яті | Helper-и журналу подій host пам’яті | + | `plugin-sdk/memory-core-host-status` | Helper-и статусу host пам’яті | Helper-и статусу host пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime host пам’яті | Helper-и CLI runtime host пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Core runtime host пам’яті | Helper-и core runtime host пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Helper-и файлів/runtime host пам’яті | Helper-и файлів/runtime host пам’яті | + | `plugin-sdk/memory-host-core` | Псевдонім core runtime host пам’яті | Незалежний від постачальника псевдонім для helper-ів core runtime host пам’яті | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій host пам’яті | Незалежний від постачальника псевдонім для helper-ів журналу подій host пам’яті | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime host пам’яті | Незалежний від постачальника псевдонім для helper-ів файлів/runtime host пам’яті | + | `plugin-sdk/memory-host-markdown` | Helper-и керованого markdown | Спільні helper-и керованого markdown для plugin, суміжних із пам’яттю | | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active-memory | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Вбудовані допоміжні засоби memory-lancedb | Поверхня допоміжних засобів memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та макети | + | `plugin-sdk/memory-host-status` | Псевдонім статусу host пам’яті | Незалежний від постачальника псевдонім для helper-ів статусу host пам’яті | + | `plugin-sdk/memory-lancedb` | Helper-и bundled memory-lancedb | Поверхня helper-ів memory-lancedb | + | `plugin-sdk/testing` | Утиліти тестування | Helper-и тестування та mocks | -Ця таблиця навмисно містить поширену підмножину для міграції, а не всю -поверхню SDK. Повний список із понад 200 точок входу міститься в +Ця таблиця навмисно охоплює поширену підмножину для міграції, а не всю поверхню +SDK. Повний список із понад 200 точок входу міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще включає деякі шви допоміжних засобів вбудованих Plugin, як-от +Цей список усе ще включає деякі helper seams для bundled plugin, такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для -підтримки та сумісності вбудованих Plugin, але навмисно +`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони залишаються експортованими для +підтримки bundled plugin і сумісності, але навмисно не включені до поширеної таблиці міграції та не є рекомендованою ціллю для -нового коду Plugin. +нового коду plugin. -Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, таких як: +Те саме правило застосовується до інших сімейств bundled helper, таких як: -- допоміжні засоби підтримки браузера: `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` +- helper-и підтримки 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` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- поверхні вбудованих допоміжних засобів/Plugin, як-от `plugin-sdk/googlechat`, +- bundled helper/plugin surfaces, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -355,26 +431,26 @@ OpenClaw не видаляє і не переосмислює задокумен `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних засобів токенів +`plugin-sdk/github-copilot-token` наразі відкриває вузьку поверхню helper-ів токенів: `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти експорт, +Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти експорт, перевірте джерело в `src/plugin-sdk/` або запитайте в Discord. -## Хронологія видалення +## Часова шкала видалення | Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | | **Зараз** | Застарілі поверхні виводять попередження під час виконання | -| **Наступний великий реліз** | Застарілі поверхні буде видалено; плагіни, які все ще їх використовують, перестануть працювати | +| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; plugin, які все ще їх використовують, завершуватимуться з помилкою | -Усі основні плагіни вже було перенесено. Зовнішні плагіни мають виконати -міграцію до наступного великого релізу. +Усі core plugin уже мігровано. Зовнішнім plugin слід виконати міграцію +до наступного мажорного релізу. -## Тимчасове приглушення попереджень +## Тимчасове придушення попереджень -Установіть ці змінні середовища під час роботи над міграцією: +Установіть ці змінні середовища, поки працюєте над міграцією: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run @@ -386,8 +462,8 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ## Пов’язане - [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів -- [Внутрішня будова Plugin](/uk/plugins/architecture) — поглиблений розбір архітектури +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath +- [Plugins channel](/uk/plugins/sdk-channel-plugins) — створення plugin channel +- [Plugins provider](/uk/plugins/sdk-provider-plugins) — створення plugin provider +- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибше занурення в архітектуру - [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 0e51e42a3..57873a6f8 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - - Потрібно знати, з якого підшляху SDK імпортувати + - Вам потрібно знати, з якого підшляху SDK імпортувати - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Карта імпорту, довідник API реєстрації та архітектура SDK -title: Огляд Plugin SDK +summary: Карта імпортів, довідник API реєстрації та архітектура SDK +title: Огляд SDK Plugin-ів x-i18n: - generated_at: "2026-04-24T17:33:02Z" + generated_at: "2026-04-24T19:52:51Z" model: gpt-5.4 provider: openai - source_hash: 3a70b8241344da739b738d1cd6b4754f013212c752d6ca4d9f052d68f0ce8c30 + source_hash: 791b22f4753094ab1e0d26fb4d471cd400e9a34be699736fb96646d9e620d3cb source_path: plugins/sdk-overview.md workflow: 15 --- -Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є -довідником щодо **що імпортувати** і **що можна реєструвати**. +SDK Plugin-ів — це типізований контракт між Plugin-ами та ядром. Ця сторінка — +довідник про **що імпортувати** і **що можна реєструвати**. Шукаєте натомість практичний посібник? -- Перший plugin? Почніть із [Створення plugins](/uk/plugins/building-plugins). -- Channel plugin? Див. [Channel plugins](/uk/plugins/sdk-channel-plugins). -- Provider plugin? Див. [Provider plugins](/uk/plugins/sdk-provider-plugins). -- Tool або plugin із хуком життєвого циклу? Див. [Хуки plugin](/uk/plugins/hooks). +- Перший Plugin? Почніть із [Створення Plugin-ів](/uk/plugins/building-plugins). +- Plugin каналу? Див. [Plugin-и каналів](/uk/plugins/sdk-channel-plugins). +- Plugin провайдера? Див. [Plugin-и провайдерів](/uk/plugins/sdk-provider-plugins). +- Plugin інструмента або hook життєвого циклу? Див. [Hook-и Plugin-а](/uk/plugins/hooks). -## Правило імпорту +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -36,106 +36,113 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий самодостатній модуль. Це пришвидшує запуск і -запобігає проблемам із циклічними залежностями. Для специфічних для channel -допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` -залишайте для ширшої поверхні umbrella та спільних допоміжних засобів, як-от +Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і +запобігає проблемам із циклічними залежностями. Для специфічних для каналу допоміжних засобів точки входу/збирання +віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для +ширшої umbrella-поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. - Не імпортуйте branded convenience seams для provider або channel (наприклад + Не імпортуйте з брендованих зручних seam-ів провайдерів або каналів (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані plugins компонують загальні підшляхи SDK у власних barrel-файлах `api.ts` / - `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для plugin - barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді - є міжканальною. + Bundled Plugin-и поєднують загальні підшляхи SDK у власних barrel-файлах `api.ts` / + `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні barrel-файли Plugin-ів, + або додавати вузький загальний контракт SDK, коли потреба справді є + міжканальною. -Невеликий набір допоміжних seams для вбудованих plugins (`plugin-sdk/feishu`, -`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще присутній у -згенерованій карті export. Вони існують лише для супроводу вбудованих plugins і -не рекомендовані як шляхи імпорту для нових сторонніх plugins. +Невеликий набір helper seam-ів bundled Plugin-ів (`plugin-sdk/feishu`, +`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється в +згенерованій карті експортів. Вони існують лише для підтримки bundled Plugin-ів і +не рекомендовані як шляхи імпорту для нових сторонніх Plugin-ів. ## Довідник підшляхів -Plugin SDK надається як набір вузьких підшляхів, згрупованих за областями (entry -plugin, channel, provider, auth, runtime, capability, memory і зарезервовані -допоміжні засоби для вбудованих plugins). Повний каталог — згрупований і з -посиланнями — див. у [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). +SDK Plugin-ів надається як набір вузьких підшляхів, згрупованих за напрямами (Plugin +entry, channel, provider, auth, runtime, capability, memory і зарезервовані +helper-и bundled Plugin-ів). Повний каталог — зі групуванням і посиланнями — див. у +[Підшляхи SDK Plugin-ів](/uk/plugins/sdk-subpaths). -Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. +Згенерований список із понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Method | Що реєструє | +| Метод | Що він реєструє | | ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Виведення тексту (LLM) | +| `api.registerProvider(...)` | Текстовий inference (LLM) | | `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний backend виведення CLI | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerCliBackend(...)` | Локальний CLI-бекенд inference | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Двосторонні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | | `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Web search | -### Tools і команди +### Інструменти й команди -| Method | Що реєструє | -| ------------------------------- | -------------------------------------------- | +| Метод | Що він реєструє | +| ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Власна команда (оминає LLM) | +| `api.registerCommand(def)` | Кастомна команда (обходить LLM) | ### Інфраструктура -| Method | Що реєструє | -| ----------------------------------------------- | -------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway | +| Метод | Що він реєструє | +| ----------------------------------------------- | --------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook події | +| `api.registerHttpRoute(params)` | HTTP-кінцева точка Gateway | | `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerGatewayDiscoveryService(service)` | Рекламування локального виявлення Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerEmbeddedExtensionFactory(factory)` | Фабрика розширень вбудованого runner для Pi | -| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt, суміжний із memory | -| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання memory | +| `api.registerGatewayDiscoveryService(service)` | Рекламування виявлення локального Gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фонова служба | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструмента harness | +| `api.registerEmbeddedExtensionFactory(factory)` | Застаріла фабрика розширень Pi | +| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція prompt, суміжна з пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | - Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, - `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити - вужчу область для gateway method. Для методів, що належать plugin, віддавайте перевагу - префіксам, специфічним для plugin. + Зарезервовані простори назв адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити + вужчу область методу Gateway. Для методів, що належать Plugin-у, віддавайте перевагу + префіксам, специфічним для Plugin-а. - - Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли plugin потребує Pi-native - таймінгу подій під час вбудованих запусків OpenClaw — наприклад, для асинхронних - переписувань `tool_result`, які мають відбутися до того, як буде надіслано фінальне повідомлення - з результатом інструмента. + + Використовуйте `api.registerAgentToolResultMiddleware(...)`, коли Plugin-у потрібно + переписати результат інструмента після виконання і до того, як harness передасть цей + результат назад у модель. Це нейтральний до harness seam для асинхронних + редукторів виводу, таких як tokenjuice. -Наразі це seam для вбудованих plugins: лише вбудовані plugins можуть реєструвати його, -і вони мають оголосити `contracts.embeddedExtensionFactories: ["pi"]` у -`openclaw.plugin.json`. Для всього, що не потребує цього низькорівневого seam, -залишайте звичайні хуки plugin OpenClaw. +Plugin-и мають оголошувати `contracts.agentToolResultMiddleware` для кожного цільового +harness, наприклад `["pi", "codex-app-server"]`. Для роботи, якій не потрібен час результату інструмента до моделі, +залишайте звичайні hook-и Plugin-ів OpenClaw. + + + + `api.registerEmbeddedExtensionFactory(...)` є застарілим. Він залишається + сумісним seam для bundled Plugin-ів, яким усе ще потрібні прямі події + вбудованого виконання Pi. Нові трансформації результатів інструментів мають + натомість використовувати `api.registerAgentToolResultMiddleware(...)`. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дає змогу plugin рекламувати активний -Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає службу +`api.registerGatewayDiscoveryService(...)` дозволяє Plugin-у рекламувати активний +Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає поточні -порти Gateway і не секретні дані-підказки TXT, а також викликає повернутий -обробник `stop` під час зупинки Gateway. +порти Gateway і не секретні дані-підказки TXT, а також викликає повернений +обробник `stop` під час завершення роботи Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -151,21 +158,20 @@ api.registerGatewayDiscoveryService({ }); ``` -Plugins виявлення Gateway не повинні розглядати рекламовані значення TXT як секрети або -автентифікацію. Виявлення — це підказка для маршрутизації; довірою, як і раніше, керують -автентифікація Gateway і TLS pinning. +Plugin-и виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або +автентифікацію. Виявлення — це підказка для маршрутизації; довіра все ще належить автентифікації Gateway і pinning TLS. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє реєстратор -- `descriptors`: дескриптори команд на етапі парсингу, які використовуються для довідки root CLI, - маршрутизації та відкладеної реєстрації plugin CLI +- `commands`: явні корені команд, якими володіє registrar +- `descriptors`: дескриптори команд часу парсингу, які використовуються для довідки кореневого CLI, + маршрутизації та лінивої реєстрації CLI Plugin-а -Якщо ви хочете, щоб команда plugin залишалася з відкладеним завантаженням у звичайному root CLI path, -надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається -цим реєстратором. +Якщо ви хочете, щоб команда Plugin-а залишалася ліниво завантажуваною в звичайному шляху кореневого CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається цим +registrar. ```typescript api.registerCli( @@ -177,7 +183,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керуйте обліковими записами Matrix, верифікацією, пристроями та станом профілю", + description: "Manage Matrix accounts, verification, devices, and profile state", hasSubcommands: true, }, ], @@ -185,131 +191,130 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, тільки якщо вам не потрібна відкладена реєстрація root CLI. -Цей eager-сумісний шлях залишається підтримуваним, але він не встановлює -заповнювачі на основі descriptor для відкладеного завантаження на етапі парсингу. +Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореневого CLI. +Цей сумісний eager-шлях усе ще підтримується, але він не встановлює +placeholder-и на основі дескрипторів для лінивого завантаження під час парсингу. -### Реєстрація backend CLI +### Реєстрація CLI-бекенда -`api.registerCliBackend(...)` дає змогу plugin володіти конфігурацією за замовчуванням для локального -backend CLI AI, такого як `codex-cli`. +`api.registerCliBackend(...)` дозволяє Plugin-у володіти типовою конфігурацією для локального +AI CLI-бекенда, такого як `codex-cli`. -- `id` backend стає префіксом provider у посиланнях на моделі, таких як `codex-cli/gpt-5`. -- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - значення plugin за замовчуванням перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після об’єднання +- `id` бекенда стає префіксом провайдера в посиланнях на моделі на кшталт `codex-cli/gpt-5`. +- `config` бекенда використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має перевагу. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + типового значення Plugin-а перед запуском CLI. +- Використовуйте `normalizeConfig`, коли бекенду потрібні сумісні переписування після об’єднання (наприклад, нормалізація старих форм прапорців). ### Ексклюзивні слоти -| Method | Що реєструє | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг налаштувати доповнення до prompt. | -| `api.registerMemoryCapability(capability)` | Уніфіковану можливість memory | -| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt для memory | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush для memory | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory | +| Метод | Що він реєструє | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Механізм контексту (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб механізм міг адаптувати доповнення prompt. | +| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Генератор секції prompt для пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті | -### Адаптери embedding для memory +### Адаптери embedding-ів пам’яті -| Method | Що реєструє | -| ---------------------------------------------- | ------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin | +| Метод | Що він реєструє | +| ---------------------------------------------- | ---------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding-ів пам’яті для активного Plugin-а | -- `registerMemoryCapability` — рекомендований API ексклюзивного plugin для memory. +- `registerMemoryCapability` — це бажаний API ексклюзивного Plugin-а пам’яті. - `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, - щоб супутні plugins могли споживати експортовані артефакти memory через - `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної - структури конкретного plugin для memory. + щоб допоміжні Plugin-и могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватного макета + конкретного Plugin-а пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це сумісні з застарілими версіями API ексклюзивних plugins для memory. -- `registerMemoryEmbeddingProvider` дає змогу активному plugin для memory реєструвати один - або кілька ідентифікаторів adapter embedding (наприклад, `openai`, `gemini` або - власний ідентифікатор, визначений plugin). -- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими - ідентифікаторами adapter. + `registerMemoryRuntime` — це сумісні із застарілими версіями API ексклюзивного Plugin-а пам’яті. +- `registerMemoryEmbeddingProvider` дозволяє активному Plugin-у пам’яті реєструвати один + або кілька id адаптерів embedding-ів (наприклад, `openai`, `gemini` або кастомний id, визначений Plugin-ом). +- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих id + адаптерів. ### Події та життєвий цикл -| Method | Що робить | -| -------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | +| Метод | Що він робить | +| -------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | -Див. [Хуки plugin](/uk/plugins/hooks) для прикладів, поширених імен хуків і -семантики guard. +Див. [Hook-и Plugin-а](/uk/plugins/hooks), щоб переглянути приклади, поширені назви hook-ів і +семантику guard. -### Семантика рішень hook +### Семантика рішень hook-ів -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як і пропуск `cancel`), а не перевизначенням. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для extras, специфічних для channel. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для channel `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість того щоб покладатися на внутрішні хуки `gateway:startup`. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере на себе dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. +- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до `metadata`, специфічних для каналу. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні hook-и `gateway:startup`. ### Поля об’єкта API -| Field | Type | Опис | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія plugin (необов’язково) | -| `api.description` | `string?` | Опис plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела plugin | -| `api.rootDir` | `string?` | Коренева директорія plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок config (активний знімок runtime у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Специфічна для plugin config із `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Обчислити шлях відносно кореня plugin | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------- | +| `api.id` | `string` | id Plugin-а | +| `api.name` | `string` | Ім’я для відображення | +| `api.version` | `string?` | Версія Plugin-а (необов’язково) | +| `api.description` | `string?` | Опис Plugin-а (необов’язково) | +| `api.source` | `string` | Шлях до джерела Plugin-а | +| `api.rootDir` | `string?` | Кореневий каталог Plugin-а (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, якщо доступний) | +| `api.pluginConfig` | `Record` | Конфігурація Plugin-а з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного входу | +| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня Plugin-а | -## Правило внутрішніх модулів +## Угода щодо внутрішніх модулів -Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого Plugin-а використовуйте локальні barrel-файли для внутрішніх імпортів: -``` +```text my-plugin/ - api.ts # Публічні exports для зовнішніх споживачів - runtime-api.ts # Лише внутрішні exports runtime - index.ts # Точка входу plugin - setup-entry.ts # Полегшена точка входу лише для setup (необов’язково) + api.ts # Публічні експорти для зовнішніх споживачів + runtime-api.ts # Лише внутрішні експорти середовища виконання + index.ts # Точка входу Plugin-а + setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` - з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` + у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих plugins, що завантажуються через facade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), віддають перевагу -активному знімку config runtime, коли OpenClaw уже запущено. Якщо знімок runtime -ще не існує, вони повертаються до обчисленого файлу config на диску. +Публічні поверхні bundled Plugin-ів, завантажених через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні файли входу), віддають перевагу +активному знімку конфігурації середовища виконання, коли OpenClaw уже працює. Якщо знімок середовища виконання +ще не існує, вони повертаються до розв’язаного файлу конфігурації на диску. -Plugins provider можуть надавати вузький локальний barrel контракту plugin, коли -допоміжний засіб навмисно є специфічним для provider і ще не належить до загального підшляху SDK. -Приклади вбудованих: +Plugin-и провайдерів можуть надавати вузький barrel локального контракту Plugin-а, коли +допоміжний засіб навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK. +Bundled приклади: - **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude - beta-header і допоміжних засобів потоків `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и provider, - допоміжні засоби для моделей за замовчуванням і builder-и realtime provider. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder provider - разом із допоміжними засобами onboarding/config. + з beta-header і допоміжними засобами потоку `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує конструктори провайдерів, + допоміжні засоби моделей за замовчуванням і конструктори провайдерів реального часу. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує конструктор провайдера + плюс допоміжні засоби onboarding/конфігурації. - Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. + Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на capability, замість зв’язування двох plugins між собою. + наприклад `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + поверхні, орієнтованої на можливість, замість того щоб жорстко пов’язувати два Plugin-и. ## Пов’язане @@ -318,11 +323,11 @@ Plugins provider можуть надавати вузький локальний Параметри `definePluginEntry` і `defineChannelPluginEntry`. - - Повний довідник простору імен `api.runtime`. + + Повний довідник простору назв `api.runtime`. - - Пакування, маніфести та схеми config. + + Пакування, маніфести й схеми конфігурації. Утиліти тестування та правила lint. @@ -330,7 +335,7 @@ Plugins provider можуть надавати вузький локальний Міграція із застарілих поверхонь. - - Поглиблена архітектура та модель capability. + + Детальна архітектура та модель можливостей. diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index e9bf4abe3..494b9890c 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -4,48 +4,48 @@ read_when: summary: Як запускати тести локально (`vitest`) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-04-24T07:42:14Z" + generated_at: "2026-04-24T19:52:49Z" model: gpt-5.4 provider: openai - source_hash: 26cdb5fe005e738ddd00b183e91ccebe08c709bd64eed377d573a37b76e3a3bf + source_hash: 4393562f7ab8471d44ab1573bc14b041fb50058bfc61de628e02328793193ed7 source_path: reference/test.md workflow: 15 --- -- Повний набір для тестування (набори тестів, live, Docker): [Тестування](/uk/help/testing) +- Повний набір для тестування (набори, live, Docker): [Testing](/uk/help/testing) -- `pnpm test:force`: завершує будь-який завислий процес gateway, який утримує типовий порт керування, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб тести сервера не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. -- `pnpm test:coverage`: запускає набір unit-тестів із покриттям V8 (через `vitest.unit.config.ts`). Це поріг покриття unit-тестів для завантажених файлів, а не покриття всіх файлів у всьому репозиторії. Пороги становлять 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, поріг вимірює файли, завантажені набором unit coverage, замість того щоб вважати кожен файл вихідного коду з розділених lane непокритим. +- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує типовий control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб тести сервера не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. +- `pnpm test:coverage`: запускає unit-набір із V8 coverage (через `vitest.unit.config.ts`). Це перевірка unit coverage для завантажених файлів, а не coverage всіх файлів у всьому репозиторії. Пороги становлять 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit coverage, замість того щоб вважати непокритими всі файли вихідного коду з розділених lane-ів. - `pnpm test:coverage:changed`: запускає unit coverage лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: розгортає змінені git-шляхи в scoped Vitest lanes, коли diff торкається лише routable файлів вихідного коду/тестів. Зміни в config/setup усе одно повертаються до нативного запуску кореневих проєктів, щоб зміни в підключенні запускали ширший повторний прогін там, де це потрібно. -- `pnpm changed:lanes`: показує архітектурні lanes, активовані diff відносно `origin/main`. -- `pnpm check:changed`: запускає розумну перевірку changed для diff відносно `origin/main`. Вона запускає core-роботи разом із core test lanes, роботу розширень — разом із extension test lanes, зміни лише в тестах — лише з test typecheck/tests, розгортає зміни в публічному Plugin SDK або plugin-contract до одного проходу валідації розширень і залишає підвищення версій лише в release metadata націленими перевірками version/config/root-dependency. -- `pnpm test`: спрямовує явні цілі file/directory через scoped Vitest lanes. Запуски без цілі використовують фіксовані shard-групи та розгортаються до leaf config для локального паралельного виконання; група extension завжди розгортається до shard config окремих extension/plugin, а не до одного великого процесу root-project. -- Повні запуски та запуски extension shard оновлюють локальні дані таймінгу в `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги, щоб збалансувати повільні й швидкі shard. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгу. -- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через спеціальні легкі lanes, які зберігають лише `test/setup.ts`, залишаючи runtime-heavy випадки на їхніх наявних lanes. -- Вибрані допоміжні вихідні файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lanes, щоб малі зміни в helper не примушували повторно запускати важкі набори тестів із підтримкою runtime. -- `auto-reply` тепер також розбивається на три спеціальні config (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper. -- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в конфігураціях усього репозиторію. +- `pnpm test:changed`: розгортає змінені git-шляхи у scoped Vitest lane-и, коли diff зачіпає лише routable файли вихідного коду/тестів. Зміни config/setup, як і раніше, повертаються до нативного запуску root projects, щоб зміни в wiring за потреби повторно запускали ширший набір. +- `pnpm changed:lanes`: показує архітектурні lane-и, активовані diff-ом відносно `origin/main`. +- `pnpm check:changed`: запускає розумну перевірку changed gate для diff-а відносно `origin/main`. Вона запускає core-роботи з core test lane-ами, роботу extensions — з extension test lane-ами, зміни лише в тестах — тільки з test typecheck/tests, розширює зміни в публічному SDK Plugin-ів або plugin-contract до одного проходу валідації extensions і залишає version bumps лише в release metadata на цільових перевірках version/config/root-dependency. +- `pnpm test`: маршрутизує явні цілі file/directory через scoped Vitest lane-и. Запуски без цілі використовують фіксовані shard-групи та розгортаються до leaf config-ів для локального паралельного виконання; група extensions завжди розгортається до shard config-ів для кожного extension/plugin, а не до одного великого процесу root-project. +- Повні запуски та shard-запуски extensions оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard-ів. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. +- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lane-и, які зберігають лише `test/setup.ts`, залишаючи runtime-важкі випадки на їхніх наявних lane-ах. +- Вибрані файли вихідного коду helper-ів `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane-ах, тож невеликі правки helper-ів не спричиняють повторного запуску важких наборів із підтримкою runtime. +- `auto-reply` тепер також розділено на три окремі config-и (`core`, `top-level`, `reply`), тож harness reply не домінує над легшими тестами top-level status/token/helper. +- Базовий config Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний non-isolated runner увімкнено в config-ах репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. -- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane bundled plugin. -- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та деталізацію імпорту, водночас і далі використовуючи scoped lane routing для явних цілей file/directory. -- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює за бенчмарком routed changed-mode path із нативним запуском root-project для того самого закоміченого git diff. -- `pnpm test:perf:changed:bench -- --worktree` порівнює за бенчмарком поточний набір змін у worktree без попереднього коміту. -- `pnpm test:perf:profile:main`: записує CPU profile для основного потоку Vitest (`.artifacts/vitest-main-profile`). -- `pnpm test:perf:profile:runner`: записує CPU + heap profiles для unit runner (`.artifacts/vitest-runner-profile`). -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf config повного набору Vitest і записує згруповані дані тривалості плюс JSON/log артефакти для кожної config. Агент продуктивності тестів використовує це як baseline перед спробами виправити повільні тести. -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність. -- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: запускає smoke-тести end-to-end для gateway (парування кількох екземплярів WS/HTTP/node). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`. -- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потрібні API-ключі та `LIVE=1` (або специфічний для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск. -- `pnpm test:docker:all`: один раз збирає спільний образ live-test і образ Docker E2E, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1` з типовим рівнем паралелізму 8. Налаштовуйте основний пул через `OPENCLAW_DOCKER_ALL_PARALLELISM=` і чутливий до провайдера хвостовий пул через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=`; обидва типово дорівнюють 8. Запуски lanes типово зміщуються на 2 секунди, щоб уникнути локальних штормів створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner припиняє планувати нові pooled lanes після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, і кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Логи для кожного lane записуються в `.artifacts/docker-tests//`. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потрібен придатний ключ live model (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і стабільність у CI тут не очікується такою самою, як для звичайних unit/e2e наборів. -- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із підготовленими даними та другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення routed conversation, читання transcript, метадані вкладень, поведінку черги live events, маршрутизацію outbound send, а також сповіщення про channel і permissions у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, тож smoke відображає те, що міст фактично надсилає. +- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard-и extensions/Plugin-ів. Важкі channel Plugin-и, browser Plugin і OpenAI запускаються як окремі shard-и; інші групи Plugin-ів залишаються пакетованими. Використовуйте `pnpm test extensions/` для одного lane вбудованого Plugin-а. +- `pnpm test:perf:imports`: вмикає звітність Vitest про import-duration + import-breakdown, водночас зберігаючи scoped lane routing для явних цілей file/directory. +- `pnpm test:perf:imports:changed`: те саме профілювання import-ів, але лише для файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` виконує benchmark маршрутизованого шляху в режимі changed проти нативного запуску root-project для того самого закоміченого git diff-а. +- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін у worktree без попереднього коміту. +- `pnpm test:perf:profile:main`: записує CPU profile для головного потоку Vitest (`.artifacts/vitest-main-profile`). +- `pnpm test:perf:profile:runner`: записує CPU + heap profiles для unit runner-а (`.artifacts/vitest-runner-profile`). +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf config Vitest повного набору й записує згруповані дані тривалості разом з JSON/log артефактами для кожного config-а. Агент продуктивності тестів використовує це як базову лінію перед спробами виправити повільні тести. +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після зміни, зосередженої на продуктивності. +- Інтеграція Gateway: opt-in через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: запускає smoke-тести gateway end-to-end (multi-instance WS/HTTP/node pairing). Типово використовує `threads` + `isolate: false` з адаптивними worker-ами у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановлюйте `OPENCLAW_E2E_VERBOSE=1` для докладних логів. +- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потребує API-ключів і `LIVE=1` (або специфічного для провайдера `*_LIVE_TEST=1`) для зняття пропуску. +- `pnpm test:docker:all`: один раз збирає спільний image для live-тестів і Docker E2E image, а потім запускає Docker smoke lane-и з `OPENCLAW_SKIP_DOCKER_BUILD=1` через weighted scheduler. `OPENCLAW_DOCKER_ALL_PARALLELISM=` керує слотами процесів і типово дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` керує tail pool, чутливим до провайдерів, і також типово дорівнює 10. Обмеження важких lane-ів типово становлять `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`; для потужніших хостів використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`. Запуски lane-ів за замовчуванням зсуваються на 2 секунди, щоб уникнути локальних піків створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner припиняє планувати нові pooled lane-и після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Логи для кожного lane-а записуються в `.artifacts/docker-tests//`. +- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім виконує реальний проксійований чат через `/api/chat/completions`. Потребує придатного ключа live model (наприклад, OpenAI у `~/.profile`), завантажує зовнішній image Open WebUI і не очікується як CI-стабільний, на відміну від звичайних unit/e2e наборів. +- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із початковим наповненням і другий контейнер клієнта, який запускає `openclaw mcp serve`, а потім перевіряє виявлення маршрутованих розмов, читання транскриптів, метадані вкладень, поведінку черги live events, маршрутизацію вихідних надсилань і сповіщення про канал + дозволи в стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP-кадри напряму, щоб smoke-тест відображав те, що міст реально надсилає. -## Локальна PR-перевірка +## Локальний PR gate -Для локальних перевірок перед злиттям/проходженням PR виконайте: +Для локальних перевірок перед приземленням PR/gate запускайте: - `pnpm check:changed` - `pnpm check` @@ -54,12 +54,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` дає flaky-результат на завантаженій машині, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для машин з обмеженнями пам’яті використовуйте: +Якщо `pnpm test` дає flaky-результат на навантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## Бенчмарк затримки моделі (локальні ключі) +## Benchmark затримки моделей (локальні ключі) Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -67,14 +67,14 @@ x-i18n: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` - Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` -- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або додаткового тексту.” +- Типова підказка: “Reply with a single word: ok. No punctuation or extra text.” Останній запуск (2025-12-31, 20 запусків): - minimax median 1279ms (min 1114, max 2431) - opus median 2454ms (min 1224, max 3170) -## Бенчмарк запуску CLI +## Benchmark запуску CLI Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -95,21 +95,21 @@ x-i18n: - `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu` - `pnpm tsx scripts/bench-cli-startup.ts --json` -Набори preset: +Preset-и: - `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status` - `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port` -- `all`: обидва preset +- `all`: обидва preset-и -Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8 profiles для кожного запуску, тож вимірювання часу й збирання profiles використовують один і той самий harness. +Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8 profiles для кожного запуску, тому захоплення таймінгів і profiles використовує той самий harness. -Угоди щодо збережених результатів: +Угоди щодо збереженого виводу: -- `pnpm test:startup:bench:smoke` записує цільовий smoke artifact у `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` записує artifact повного набору в `.artifacts/cli-startup-bench-all.json` з `runs=5` і `warmup=1` -- `pnpm test:startup:bench:update` оновлює зафіксований у репозиторії baseline fixture у `test/fixtures/cli-startup-bench.json` з `runs=5` і `warmup=1` +- `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json` +- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з використанням `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює fixture baseline, що зберігається в репозиторії, у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` -Зафіксований у репозиторії fixture: +Fixture, що зберігається в репозиторії: - `test/fixtures/cli-startup-bench.json` - Оновлення через `pnpm test:startup:bench:update` @@ -117,19 +117,19 @@ x-i18n: ## Onboarding E2E (Docker) -Docker не є обов’язковим; це потрібно лише для контейнеризованих smoke-тестів onboarding. +Docker необов’язковий; це потрібно лише для containerized smoke-тестів onboarding. -Повний cold-start сценарій у чистому Linux-контейнері: +Повний cold-start flow у чистому Linux-контейнері: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт проходить інтерактивний майстер через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. +Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, а потім запускає gateway і виконує `openclaw health`. ## Smoke-тест імпорту QR (Docker) -Гарантує, що підтримуваний QR runtime helper завантажується в підтримуваних Node runtime у Docker (типово Node 24, сумісність із Node 22): +Гарантує, що підтримуваний runtime helper для QR завантажується в підтримуваних Docker Node runtime-ах (Node 24 за замовчуванням, Node 22 сумісний): ```bash pnpm test:docker:qr @@ -137,5 +137,5 @@ pnpm test:docker:qr ## Пов’язане -- [Тестування](/uk/help/testing) -- [Live-тестування](/uk/help/testing-live) +- [Testing](/uk/help/testing) +- [Testing live](/uk/help/testing-live) diff --git a/docs/uk/start/bootstrapping.md b/docs/uk/start/bootstrapping.md index a28db3e92..8571eac3d 100644 --- a/docs/uk/start/bootstrapping.md +++ b/docs/uk/start/bootstrapping.md @@ -1,46 +1,50 @@ --- read_when: - - Розуміння того, що відбувається під час першого запуску агента - - Пояснення, де знаходяться файли bootstrap-налаштування - - Налагодження налаштування identity під час onboarding + - Розуміння того, що відбувається під час першого запуску agent + - Пояснення, де розміщуються файли початкового налаштування + - Налагодження налаштування ідентичності під час онбордингу sidebarTitle: Bootstrapping -summary: Ритуал bootstrap агента, який ініціалізує workspace та файли identity -title: Bootstrap агента +summary: Ритуал початкового налаштування agent, що заповнює workspace і файли ідентичності +title: Початкове налаштування agent x-i18n: - generated_at: "2026-04-23T21:11:33Z" + generated_at: "2026-04-24T19:53:07Z" model: gpt-5.4 provider: openai - source_hash: 0c23a204a7afbf2ca0c0d19a227286cf0ae396181073403055db41dafa764d2a + source_hash: 435eb2a14707623903ab7873774cc8d4489b960719cf6a525d547983f8338027 source_path: start/bootstrapping.md workflow: 15 --- -Bootstrap-налаштування — це ритуал **першого запуску**, який готує workspace агента й -збирає деталі identity. Воно відбувається після onboarding, коли агент запускається -вперше. +Початкове налгодування — це ритуал **першого запуску**, який готує workspace agent і +збирає відомості про ідентичність. Він відбувається після онбордингу, коли agent +запускається вперше. -## Що робить bootstrap-налаштування +## Що робить початкове налаштування -Під час першого запуску агента OpenClaw виконує bootstrap-налаштування workspace (за замовчуванням +Під час першого запуску agent OpenClaw ініціалізує workspace (типово `~/.openclaw/workspace`): -- Ініціалізує `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`. +- Заповнює `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`. - Запускає короткий ритуал запитань і відповідей (по одному запитанню за раз). -- Записує identity + preferences у `IDENTITY.md`, `USER.md`, `SOUL.md`. -- Видаляє `BOOTSTRAP.md` після завершення, щоб це виконувалося лише один раз. +- Записує ідентичність і налаштування до `IDENTITY.md`, `USER.md`, `SOUL.md`. +- Видаляє `BOOTSTRAP.md` після завершення, щоб він виконувався лише один раз. + +## Пропуск початкового налаштування + +Щоб пропустити це для попередньо заповненого workspace, виконайте `openclaw onboard --skip-bootstrap`. ## Де це виконується -Bootstrap-налаштування завжди виконується на **host gateway**. Якщо застосунок macOS підключається до -віддаленого Gateway, workspace і файли bootstrap-налаштування живуть на тій віддаленій +Початкове налаштування завжди виконується на **хості gateway**. Якщо застосунок macOS підключається до +віддаленого Gateway, workspace і файли початкового налаштування зберігаються на тій віддаленій машині. -Коли Gateway працює на іншій машині, редагуйте файли workspace на host -gateway (наприклад, `user@gateway-host:~/.openclaw/workspace`). +Коли Gateway працює на іншій машині, редагуйте файли workspace на хості gateway +(наприклад, `user@gateway-host:~/.openclaw/workspace`). -## Пов’язані документи +## Пов’язана документація -- Onboarding застосунку macOS: [Onboarding](/uk/start/onboarding) -- Макет workspace: [Agent workspace](/uk/concepts/agent-workspace) +- Онбординг застосунку macOS: [Онбординг](/uk/start/onboarding) +- Структура workspace: [Workspace agent](/uk/concepts/agent-workspace) diff --git a/docs/uk/start/openclaw.md b/docs/uk/start/openclaw.md index ba32de0fc..3fccef552 100644 --- a/docs/uk/start/openclaw.md +++ b/docs/uk/start/openclaw.md @@ -1,44 +1,44 @@ --- read_when: - Початкове налаштування нового екземпляра асистента - - Огляд наслідків для безпеки/дозволів -summary: Повний посібник із запуску OpenClaw як персонального асистента із застереженнями щодо безпеки + - Оцінка наслідків для безпеки та дозволів +summary: Наскрізний посібник із запуску OpenClaw як персонального асистента із застереженнями щодо безпеки title: Налаштування персонального асистента x-i18n: - generated_at: "2026-04-24T04:19:42Z" + generated_at: "2026-04-24T19:53:07Z" model: gpt-5.4 provider: openai - source_hash: 3048f2faae826fc33d962f1fac92da3c0ce464d2de803fee381c897eb6c76436 + source_hash: 1647b78e8cf23a3a025969c52fbd8a73aed78df27698abf36bbf62045dc30e3b source_path: start/openclaw.md workflow: 15 --- # Створення персонального асистента з OpenClaw -OpenClaw — це self-hosted gateway, який підключає Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo та інші сервіси до AI-агентів. Цей посібник охоплює налаштування «персонального асистента»: окремий номер WhatsApp, який працює як ваш завжди доступний AI-асистент. +OpenClaw — це self-hosted gateway, який підключає Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo та інші сервіси до AI-агентів. У цьому посібнику розглядається сценарій "персонального асистента": окремий номер WhatsApp, який працює як ваш постійно активний AI-асистент. -## ⚠️ Спочатку про безпеку +## ⚠️ Безпека передусім Ви надаєте агенту можливість: -- запускати команди на вашій машині (залежно від вашої політики інструментів) -- читати/записувати файли у вашому робочому просторі +- виконувати команди на вашій машині (залежно від вашої політики інструментів) +- читати/записувати файли у вашому workspace - надсилати повідомлення назад через WhatsApp/Telegram/Discord/Mattermost та інші вбудовані канали -Починайте консервативно: +Починайте обережно: -- Завжди задавайте `channels.whatsapp.allowFrom` (ніколи не запускайте все відкритим для світу на своєму особистому Mac). +- Завжди встановлюйте `channels.whatsapp.allowFrom` (ніколи не запускайте це відкритим для всіх на вашому персональному Mac). - Використовуйте окремий номер WhatsApp для асистента. -- Heartbeat тепер типово запускається кожні 30 хвилин. Вимкніть його, доки не почнете довіряти цьому налаштуванню, встановивши `agents.defaults.heartbeat.every: "0m"`. +- Heartbeat тепер за замовчуванням виконується кожні 30 хвилин. Вимкніть його, доки не переконаєтеся, що налаштуванням можна довіряти, встановивши `agents.defaults.heartbeat.every: "0m"`. ## Передумови -- OpenClaw встановлено й початково налаштовано — див. [Початок роботи](/uk/start/getting-started), якщо ви ще цього не зробили -- Другий номер телефону (SIM/eSIM/передплачений тариф) для асистента +- OpenClaw установлено й пройдено початкове налаштування — див. [Getting Started](/uk/start/getting-started), якщо ви ще цього не зробили +- Другий номер телефону (SIM/eSIM/prepaid) для асистента ## Налаштування з двома телефонами (рекомендовано) -Вам потрібно ось так: +Вам потрібна така схема: ```mermaid flowchart TB @@ -46,11 +46,11 @@ flowchart TB B -- linked via QR --> C["Ваш Mac (openclaw)

AI-агент"] ``` -Якщо ви прив’яжете свій особистий WhatsApp до OpenClaw, кожне повідомлення вам стане «входом агента». Зазвичай це не те, що вам потрібно. +Якщо ви прив’яжете свій особистий WhatsApp до OpenClaw, кожне повідомлення вам стане “входом агента”. Зазвичай це не те, чого ви хочете. ## Швидкий старт за 5 хвилин -1. Сполучіть WhatsApp Web (буде показано QR; відскануйте його телефоном асистента): +1. Прив’яжіть WhatsApp Web (покаже QR; відскануйте його телефоном асистента): ```bash openclaw channels login @@ -62,7 +62,7 @@ openclaw channels login openclaw gateway --port 18789 ``` -3. Додайте мінімальну конфігурацію до `~/.openclaw/openclaw.json`: +3. Додайте мінімальну конфігурацію в `~/.openclaw/openclaw.json`: ```json5 { @@ -71,52 +71,56 @@ openclaw gateway --port 18789 } ``` -Тепер надішліть повідомлення на номер асистента зі свого телефону, який є в allowlist. +Тепер надішліть повідомлення на номер асистента зі свого телефону з allowlist. -Коли початкове налаштування завершиться, OpenClaw автоматично відкриє dashboard і виведе чисте посилання (без токена). Якщо dashboard просить автентифікацію, вставте налаштований shared secret у налаштуваннях Control UI. Під час onboarding типово використовується токен (`gateway.auth.token`), але автентифікація паролем теж працює, якщо ви перемкнули `gateway.auth.mode` на `password`. Щоб знову відкрити пізніше: `openclaw dashboard`. +Коли початкове налаштування завершиться, OpenClaw автоматично відкриє dashboard і виведе чисте посилання (без токена). Якщо dashboard попросить автентифікацію, вставте налаштований спільний секрет у налаштуваннях Control UI. Під час початкового налаштування за замовчуванням використовується токен (`gateway.auth.token`), але також працює автентифікація паролем, якщо ви змінили `gateway.auth.mode` на `password`. Щоб відкрити знову пізніше: `openclaw dashboard`. -## Надайте агенту робочий простір (AGENTS) +## Надайте агенту workspace (AGENTS) -OpenClaw читає робочі інструкції та «пам’ять» із каталогу робочого простору. +OpenClaw зчитує робочі інструкції та “пам’ять” із каталогу workspace. -Типово OpenClaw використовує `~/.openclaw/workspace` як робочий простір агента й автоматично створює його (разом із початковими `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`) під час налаштування/першого запуску агента. `BOOTSTRAP.md` створюється лише тоді, коли робочий простір абсолютно новий (він не має повертатися після того, як ви його видалите). `MEMORY.md` є необов’язковим (не створюється автоматично); якщо файл існує, його буде завантажено для звичайних сесій. Сесії субагентів інжектують лише `AGENTS.md` і `TOOLS.md`. +За замовчуванням OpenClaw використовує `~/.openclaw/workspace` як workspace агента і автоматично створює його (разом із початковими файлами `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`) під час налаштування/першого запуску агента. `BOOTSTRAP.md` створюється лише тоді, коли workspace зовсім новий (після видалення він не повинен з’являтися знову). `MEMORY.md` необов’язковий (автоматично не створюється); якщо він є, його завантажують для звичайних сесій. Сесії subagent інжектують лише `AGENTS.md` і `TOOLS.md`. -Порада: сприймайте цю папку як «пам’ять» OpenClaw і зробіть її git-репозиторієм (бажано приватним), щоб ваші `AGENTS.md` і файли пам’яті були збережені в резервній копії. Якщо git встановлено, абсолютно нові робочі простори ініціалізуються автоматично. +Порада: сприймайте цю папку як “пам’ять” OpenClaw і зробіть її git-репозиторієм (бажано приватним), щоб ваші `AGENTS.md` і файли пам’яті мали резервні копії. Якщо git установлено, нові workspace автоматично ініціалізуються. ```bash openclaw setup ``` -Повна структура робочого простору + посібник із резервного копіювання: [Робочий простір агента](/uk/concepts/agent-workspace) -Робочий процес пам’яті: [Пам’ять](/uk/concepts/memory) +Повна структура workspace + посібник із резервного копіювання: [Agent workspace](/uk/concepts/agent-workspace) +Робочий процес пам’яті: [Memory](/uk/concepts/memory) -Необов’язково: виберіть інший робочий простір через `agents.defaults.workspace` (підтримується `~`). +Необов’язково: виберіть інший workspace через `agents.defaults.workspace` (підтримує `~`). ```json5 { - agent: { - workspace: "~/.openclaw/workspace", + agents: { + defaults: { + workspace: "~/.openclaw/workspace", + }, }, } ``` -Якщо ви вже постачаєте власні файли робочого простору з репозиторію, можна повністю вимкнути створення bootstrap-файлів: +Якщо ви вже постачаєте власні файли workspace з репозиторію, можна повністю вимкнути створення bootstrap-файлів: ```json5 { - agent: { - skipBootstrap: true, + agents: { + defaults: { + skipBootstrap: true, + }, }, } ``` -## Конфігурація, яка перетворює це на «асистента» +## Конфігурація, яка перетворює це на "асистента" -OpenClaw типово має гарне налаштування для асистента, але зазвичай вам варто підлаштувати: +OpenClaw за замовчуванням має хороше налаштування для асистента, але зазвичай вам варто налаштувати: -- persona/інструкції в [`SOUL.md`](/uk/concepts/soul) +- persona/інструкції у [`SOUL.md`](/uk/concepts/soul) - типові параметри thinking (за потреби) -- Heartbeat (коли почнете довіряти системі) +- Heartbeat (коли вже почнете йому довіряти) Приклад: @@ -128,7 +132,7 @@ OpenClaw типово має гарне налаштування для асис workspace: "~/.openclaw/workspace", thinkingDefault: "high", timeoutSeconds: 1800, - // Починайте з 0; увімкніть пізніше. + // Почніть з 0; увімкнете пізніше. heartbeat: { every: "0m" }, }, channels: { @@ -159,21 +163,21 @@ OpenClaw типово має гарне налаштування для асис ## Сесії та пам’ять - Файли сесій: `~/.openclaw/agents//sessions/{{SessionId}}.jsonl` -- Метадані сесій (використання токенів, останній маршрут тощо): `~/.openclaw/agents//sessions/sessions.json` (застарілий шлях: `~/.openclaw/sessions/sessions.json`) -- `/new` або `/reset` починає нову сесію для цього чату (налаштовується через `resetTriggers`). Якщо команду надіслано окремо, агент відповідає коротким привітанням для підтвердження скидання. -- `/compact [instructions]` виконує Compaction контексту сесії та повідомляє про залишковий бюджет контексту. +- Метадані сесії (використання токенів, останній маршрут тощо): `~/.openclaw/agents//sessions/sessions.json` (застарілий шлях: `~/.openclaw/sessions/sessions.json`) +- `/new` або `/reset` запускає нову сесію для цього чату (налаштовується через `resetTriggers`). Якщо надіслати окремо, агент відповідає коротким привітанням для підтвердження скидання. +- `/compact [instructions]` стискає контекст сесії та повідомляє про залишок бюджету контексту. ## Heartbeat (проактивний режим) -Типово OpenClaw запускає Heartbeat кожні 30 хвилин із таким запитом: +За замовчуванням OpenClaw запускає Heartbeat кожні 30 хвилин із запитом: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -Щоб вимкнути, встановіть `agents.defaults.heartbeat.every: "0m"`. +Щоб вимкнути, установіть `agents.defaults.heartbeat.every: "0m"`. -- Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки на кшталт `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб зекономити виклики API. +- Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки, як-от `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб зекономити API-виклики. - Якщо файл відсутній, Heartbeat усе одно запускається, і модель сама вирішує, що робити. - Якщо агент відповідає `HEARTBEAT_OK` (необов’язково з коротким доповненням; див. `agents.defaults.heartbeat.ackMaxChars`), OpenClaw пригнічує вихідну доставку для цього Heartbeat. -- Типово доставка Heartbeat до цілей у стилі DM `user:` дозволена. Установіть `agents.defaults.heartbeat.directPolicy: "block"`, щоб заборонити доставку до прямих цілей, зберігши самі запуски Heartbeat активними. -- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. +- За замовчуванням доставка Heartbeat до цілей типу DM `user:` дозволена. Установіть `agents.defaults.heartbeat.directPolicy: "block"`, щоб заборонити доставку до прямих цілей, залишивши самі запуски Heartbeat активними. +- Heartbeat виконують повні ходи агента — коротші інтервали спалюють більше токенів. ```json5 { @@ -185,54 +189,54 @@ OpenClaw типово має гарне налаштування для асис ## Медіа на вхід і вихід -Вхідні вкладення (зображення/аудіо/документи) можуть передаватися у вашу команду через шаблони: +Вхідні вкладення (зображення/аудіо/документи) можуть передаватися вашій команді через шаблони: - `{{MediaPath}}` (шлях до локального тимчасового файла) - `{{MediaUrl}}` (псевдо-URL) -- `{{Transcript}}` (якщо увімкнено транскрибування аудіо) +- `{{Transcript}}` (якщо ввімкнено транскрибування аудіо) Вихідні вкладення від агента: додайте `MEDIA:` в окремому рядку (без пробілів). Приклад: ``` -Here’s the screenshot. +Ось знімок екрана. MEDIA:https://example.com/screenshot.png ``` -OpenClaw витягує їх і надсилає як медіа разом із текстом. +OpenClaw витягує це і надсилає як медіа разом із текстом. Поведінка локальних шляхів дотримується тієї самої моделі довіри до читання файлів, що й агент: -- Якщо `tools.fs.workspaceOnly` має значення `true`, локальні шляхи вихідних `MEDIA:` залишаються обмеженими тимчасовим коренем OpenClaw, кешем медіа, шляхами робочого простору агента та файлами, згенерованими в sandbox. -- Якщо `tools.fs.workspaceOnly` має значення `false`, вихідні `MEDIA:` можуть використовувати локальні файли хоста, які агенту вже дозволено читати. -- Надсилання локальних файлів хоста все одно дозволяє лише медіа та безпечні типи документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, не вважаються медіа, які можна надсилати. +- Якщо `tools.fs.workspaceOnly` має значення `true`, локальні шляхи вихідного `MEDIA:` залишаються обмеженими тимчасовим коренем OpenClaw, кешем медіа, шляхами workspace агента та файлами, створеними в sandbox. +- Якщо `tools.fs.workspaceOnly` має значення `false`, вихідний `MEDIA:` може використовувати локальні файли хоста, які агенту вже дозволено читати. +- Надсилання з локального хоста все одно дозволяє лише медіа та безпечні типи документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, не вважаються медіа, які можна надсилати. -Це означає, що згенеровані зображення/файли поза робочим простором тепер можна надсилати, якщо ваша політика fs уже дозволяє таке читання, без повторного відкриття довільної ексфільтрації текстових вкладень із хоста. +Це означає, що згенеровані зображення/файли поза workspace тепер можна надсилати, якщо ваша політика fs уже дозволяє таке читання, без повторного відкриття довільної ексфільтрації текстових вкладень з хоста. ## Контрольний список операцій ```bash openclaw status # локальний стан (облікові дані, сесії, події в черзі) openclaw status --all # повна діагностика (лише читання, можна вставляти) -openclaw status --deep # запитує gateway про живу перевірку стану з перевірками каналів, коли це підтримується -openclaw health --json # знімок стану gateway (WS; типово може повертати свіжий кешований знімок) +openclaw status --deep # запитує в gateway живу перевірку працездатності з перевірками каналів, де це підтримується +openclaw health --json # знімок стану gateway (WS; за замовчуванням може повертати свіжий кешований знімок) ``` -Журнали розміщуються в `/tmp/openclaw/` (типово: `openclaw-YYYY-MM-DD.log`). +Журнали зберігаються в `/tmp/openclaw/` (типово: `openclaw-YYYY-MM-DD.log`). ## Наступні кроки - WebChat: [WebChat](/uk/web/webchat) - Операції Gateway: [Runbook Gateway](/uk/gateway) - Cron + пробудження: [Cron jobs](/uk/automation/cron-jobs) -- Компаньйон у рядку меню macOS: [Застосунок OpenClaw для macOS](/uk/platforms/macos) -- Застосунок Node для iOS: [Застосунок iOS](/uk/platforms/ios) -- Застосунок Node для Android: [Застосунок Android](/uk/platforms/android) +- Помічник для рядка меню macOS: [Застосунок OpenClaw для macOS](/uk/platforms/macos) +- Node-застосунок iOS: [Застосунок iOS](/uk/platforms/ios) +- Node-застосунок Android: [Застосунок Android](/uk/platforms/android) - Стан Windows: [Windows (WSL2)](/uk/platforms/windows) - Стан Linux: [Застосунок Linux](/uk/platforms/linux) -- Безпека: [Безпека](/uk/gateway/security) +- Безпека: [Security](/uk/gateway/security) ## Пов’язане -- [Початок роботи](/uk/start/getting-started) -- [Налаштування](/uk/start/setup) +- [Getting started](/uk/start/getting-started) +- [Setup](/uk/start/setup) - [Огляд каналів](/uk/channels) diff --git a/docs/uk/start/wizard-cli-automation.md b/docs/uk/start/wizard-cli-automation.md index 27eabc15b..2d98e5393 100644 --- a/docs/uk/start/wizard-cli-automation.md +++ b/docs/uk/start/wizard-cli-automation.md @@ -1,20 +1,20 @@ --- read_when: - - Ви автоматизуєте onboarding у скриптах або CI + - Ви автоматизуєте онбординг у скриптах або CI - Вам потрібні неінтерактивні приклади для конкретних провайдерів sidebarTitle: CLI automation -summary: Скриптовий onboarding і налаштування агента для CLI OpenClaw +summary: Скриптовий онбординг і налаштування agent для CLI OpenClaw title: Автоматизація CLI x-i18n: - generated_at: "2026-04-23T23:06:46Z" + generated_at: "2026-04-24T19:53:17Z" model: gpt-5.4 provider: openai - source_hash: b114b6b4773af8f23be0e65485bdcb617848e35cfde1642776c75108d470cea3 + source_hash: 4d36801439b9243ea5cc0ab93757dde23d1ecd86c8f5b991541ee14f41bf05ac source_path: start/wizard-cli-automation.md workflow: 15 --- -Використовуйте `--non-interactive` для автоматизації `openclaw onboard`. +Використовуйте `--non-interactive`, щоб автоматизувати `openclaw onboard`. `--json` не означає неінтерактивний режим. Для скриптів використовуйте `--non-interactive` (і `--workspace`). @@ -32,16 +32,19 @@ openclaw onboard --non-interactive \ --gateway-bind loopback \ --install-daemon \ --daemon-runtime node \ + --skip-bootstrap \ --skip-skills ``` -Додайте `--json`, щоб отримати машинозчитуване зведення. +Додайте `--json` для зведення у форматі, придатному для машинної обробки. -Використовуйте `--secret-input-mode ref`, щоб зберігати в auth-профілях env-посилання замість значень у відкритому вигляді. -Інтерактивний вибір між env-посиланнями та налаштованими посиланнями провайдера (`file` або `exec`) доступний у потоці onboarding. +Використовуйте `--skip-bootstrap`, коли ваша автоматизація попередньо заповнює файли workspace і не хоче, щоб онбординг створював типові файли початкового налаштування. -У неінтерактивному режимі `ref` env-змінні провайдера мають бути задані в середовищі процесу. -Передавання вбудованих прапорців ключів без відповідної env-змінної тепер одразу завершується помилкою. +Використовуйте `--secret-input-mode ref`, щоб зберігати в профілях автентифікації посилання на env замість значень у відкритому вигляді. +Інтерактивний вибір між env-посиланнями та налаштованими посиланнями провайдера (`file` або `exec`) доступний у потоці онбордингу. + +У неінтерактивному режимі `ref` змінні середовища провайдера мають бути задані в середовищі процесу. +Передавання вбудованих прапорців ключів без відповідної змінної середовища тепер одразу завершується помилкою. Приклад: @@ -56,7 +59,7 @@ openclaw onboard --non-interactive \ ## Приклади для конкретних провайдерів - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -128,7 +131,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -174,7 +177,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - `--custom-api-key` не є обов’язковим. Якщо його не вказано, onboarding перевіряє `CUSTOM_API_KEY`. + `--custom-api-key` необов’язковий. Якщо його не вказано, онбординг перевіряє `CUSTOM_API_KEY`. Варіант режиму ref: @@ -192,18 +195,18 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - У цьому режимі onboarding зберігає `apiKey` як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. + У цьому режимі онбординг зберігає `apiKey` як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. -Anthropic setup-token і далі доступний як підтримуваний шлях токена для onboarding, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI, коли це можливо. -Для продакшну віддавайте перевагу API key Anthropic. +`setup-token` Anthropic залишається доступним як підтримуваний шлях токена онбордингу, але тепер OpenClaw надає перевагу повторному використанню Claude CLI, коли це можливо. +Для production віддавайте перевагу ключу API Anthropic. -## Додати ще одного агента +## Додати ще одного agent -Використовуйте `openclaw agents add `, щоб створити окремого агента з власними workspace, -сеансами й auth-профілями. Запуск без `--workspace` відкриває майстер. +Використовуйте `openclaw agents add `, щоб створити окремого agent із власним workspace, +сеансами та профілями автентифікації. Запуск без `--workspace` відкриває майстер. ```bash openclaw agents add work \ @@ -228,6 +231,6 @@ openclaw agents add work \ ## Пов’язана документація -- Центр onboarding: [Onboarding (CLI)](/uk/start/wizard) +- Центр онбордингу: [Онбординг (CLI)](/uk/start/wizard) - Повний довідник: [Довідник із налаштування CLI](/uk/start/wizard-cli-reference) - Довідник команд: [`openclaw onboard`](/uk/cli/onboard) diff --git a/docs/uk/start/wizard-cli-reference.md b/docs/uk/start/wizard-cli-reference.md index 14c7b7499..49100a190 100644 --- a/docs/uk/start/wizard-cli-reference.md +++ b/docs/uk/start/wizard-cli-reference.md @@ -1,165 +1,165 @@ --- read_when: - Вам потрібен детальний опис поведінки `openclaw onboard` - - Ви налагоджуєте результати початкового налаштування або інтегруєте клієнти початкового налаштування + - Ви налагоджуєте результати onboarding або інтегруєте клієнти onboarding sidebarTitle: CLI reference -summary: Повна довідка щодо потоку налаштування CLI, налаштування автентифікації/моделі, виводів і внутрішньої будови -title: Довідка з налаштування CLI +summary: Повний довідник щодо процесу налаштування CLI, налаштування автентифікації/моделей, виводів і внутрішньої реалізації +title: Довідник з налаштування CLI x-i18n: - generated_at: "2026-04-23T23:06:51Z" + generated_at: "2026-04-24T19:53:37Z" model: gpt-5.4 provider: openai - source_hash: e4b9377e84a6f8063f20a80fe08b5ea2eccdd5b329ec8dfd9d16cbf425d01f66 + source_hash: 951b8f0b0b6b70faaa6faafad998e74183f79aa8c4c50f622b24df786f1feea7 source_path: start/wizard-cli-reference.md workflow: 15 --- -Ця сторінка — повна довідка для `openclaw onboard`. +Ця сторінка — повний довідник для `openclaw onboard`. Короткий посібник див. у [Onboarding (CLI)](/uk/start/wizard). ## Що робить майстер -Локальний режим (типовий) проводить вас через: +Локальний режим (за замовчуванням) покроково проводить вас через: -- Налаштування моделі й автентифікації (OAuth підписки OpenAI Code, Anthropic Claude CLI або API-ключ, а також MiniMax, GLM, Ollama, Moonshot, StepFun і варіанти AI Gateway) +- Налаштування моделі та автентифікації (OAuth підписки OpenAI Code, Anthropic Claude CLI або API-ключ, а також варіанти для MiniMax, GLM, Ollama, Moonshot, StepFun і AI Gateway) - Розташування робочого простору та bootstrap-файли - Налаштування Gateway (порт, bind, auth, tailscale) -- Канали та provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles та інші комплектні channel-plugin) -- Установлення демона (LaunchAgent, user unit systemd або нативне завдання Windows Scheduled Task із резервним варіантом через папку Startup) -- Перевірку стану +- Канали та провайдери (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles та інші вбудовані Plugins каналів) +- Встановлення демона (LaunchAgent, systemd user unit або нативне Windows Scheduled Task із резервним варіантом через папку Startup) +- Перевірка стану - Налаштування Skills -Віддалений режим налаштовує цю машину для підключення до gateway в іншому місці. +Віддалений режим налаштовує цю машину для підключення до Gateway, який працює в іншому місці. Він не встановлює і не змінює нічого на віддаленому хості. -## Докладно про локальний потік +## Докладно про локальний процес - Якщо існує `~/.openclaw/openclaw.json`, виберіть Keep, Modify або Reset. - Повторний запуск майстра нічого не стирає, якщо ви явно не виберете Reset (або не передасте `--reset`). - - CLI `--reset` за замовчуванням означає `config+creds+sessions`; використовуйте `--reset-scope full`, щоб також видалити робочий простір. - - Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється й просить вас запустити `openclaw doctor`, перш ніж продовжити. - - Reset використовує `trash` і пропонує області дії: + - CLI `--reset` за замовчуванням використовує `config+creds+sessions`; використовуйте `--reset-scope full`, щоб також видалити робочий простір. + - Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється і просить вас запустити `openclaw doctor`, перш ніж продовжити. + - Reset використовує `trash` і пропонує такі варіанти: - Лише конфігурація - - Конфігурація + облікові дані + сесії + - Конфігурація + облікові дані + сеанси - Повне скидання (також видаляє робочий простір) - - Повна матриця варіантів наведена в [Параметри автентифікації та моделі](#auth-and-model-options). + - Повна матриця варіантів наведена в [Варіанти автентифікації та моделей](#auth-and-model-options). - - Типово `~/.openclaw/workspace` (можна налаштувати). - - Заповнює файли робочого простору, потрібні для bootstrap-ритуалу першого запуску. + - За замовчуванням `~/.openclaw/workspace` (можна налаштувати). + - Додає файли робочого простору, потрібні для bootstrap-ритуалу першого запуску. - Структура робочого простору: [Робочий простір агента](/uk/concepts/agent-workspace). - - Запитує порт, bind, режим auth і відкриття через tailscale. - - Рекомендовано: залишати token auth увімкненим навіть для loopback, щоб локальні WS-клієнти мали проходити автентифікацію. - - У режимі token інтерактивне налаштування пропонує: - - **Generate/store plaintext token** (типово) - - **Use SecretRef** (за бажанням) - - У режимі password інтерактивне налаштування також підтримує збереження plaintext або SecretRef. - - Неінтерактивний шлях SecretRef для token: `--gateway-token-ref-env `. - - Потребує непорожньої env-змінної в середовищі процесу initial setup. + - Запитує порт, bind, режим auth і експонування через tailscale. + - Рекомендовано: залишати auth за токеном увімкненим навіть для loopback, щоб локальні WS-клієнти мали автентифікуватися. + - У режимі токена інтерактивне налаштування пропонує: + - **Згенерувати/зберегти plaintext-токен** (за замовчуванням) + - **Використовувати SecretRef** (добровільно) + - У режимі пароля інтерактивне налаштування також підтримує збереження як plaintext, так і через SecretRef. + - Шлях SecretRef для токена в неінтерактивному режимі: `--gateway-token-ref-env `. + - Потрібна непорожня змінна середовища в середовищі процесу onboarding. - Не можна поєднувати з `--gateway-token`. - - Вимикайте auth лише якщо повністю довіряєте кожному локальному процесу. - - Bind, відмінний від loopback, усе одно потребує auth. + - Вимикайте auth лише якщо ви повністю довіряєте кожному локальному процесу. + - Для bind не лише на loopback auth усе одно обов’язковий. - [WhatsApp](/uk/channels/whatsapp): необов’язковий вхід через QR - - [Telegram](/uk/channels/telegram): token бота - - [Discord](/uk/channels/discord): token бота - - [Google Chat](/uk/channels/googlechat): JSON service account + аудиторія webhook - - [Mattermost](/uk/channels/mattermost): token бота + base URL + - [Telegram](/uk/channels/telegram): токен бота + - [Discord](/uk/channels/discord): токен бота + - [Google Chat](/uk/channels/googlechat): JSON service account + webhook audience + - [Mattermost](/uk/channels/mattermost): токен бота + базовий URL - [Signal](/uk/channels/signal): необов’язкове встановлення `signal-cli` + конфігурація облікового запису - - [BlueBubbles](/uk/channels/bluebubbles): рекомендовано для iMessage; URL сервера + password + webhook - - [iMessage](/uk/channels/imessage): застарілий шлях до CLI `imsg` + доступ до БД - - Безпека DM: типово використовується pairing. Перший DM надсилає код; підтвердіть через + - [BlueBubbles](/uk/channels/bluebubbles): рекомендовано для iMessage; URL сервера + пароль + Webhook + - [iMessage](/uk/channels/imessage): застарілий шлях до CLI `imsg` + доступ до DB + - Безпека DM: за замовчуванням використовується pairing. Перше DM надсилає код; підтвердьте через `openclaw pairing approve ` або використовуйте allowlist. - + - macOS: LaunchAgent - - Потребує активної сесії користувача; для headless використовуйте власний LaunchDaemon (не постачається). - - Linux і Windows через WSL2: user unit systemd - - Майстер намагається виконати `loginctl enable-linger `, щоб gateway продовжував працювати після виходу з системи. + - Потрібен сеанс користувача з входом у систему; для безголового режиму використовуйте власний LaunchDaemon (не постачається). + - Linux і Windows через WSL2: systemd user unit + - Майстер намагається виконати `loginctl enable-linger `, щоб Gateway залишався запущеним після виходу з системи. - Може попросити sudo (записує в `/var/lib/systemd/linger`); спочатку пробує без sudo. - - Нативна Windows: спочатку Scheduled Task - - Якщо створення завдання заборонено, OpenClaw повертається до login item у папці Startup для поточного користувача й одразу запускає gateway. - - Scheduled Tasks залишаються пріоритетними, оскільки дають кращий статус supervisor. - - Вибір runtime: Node (рекомендовано; обов’язково для WhatsApp і Telegram). Bun не рекомендується. + - Нативний Windows: спочатку Scheduled Task + - Якщо створення задачі заборонено, OpenClaw переходить до резервного варіанта — login item у папці Startup для поточного користувача — і негайно запускає Gateway. + - Scheduled Tasks залишаються бажаним варіантом, оскільки дають кращий статус супервізора. + - Вибір runtime: Node (рекомендовано; обов’язково для WhatsApp і Telegram). Bun не рекомендовано. - - Запускає gateway (за потреби) і виконує `openclaw health`. - - `openclaw status --deep` додає live-перевірку стану gateway до виводу status, зокрема channel-probes, коли вони підтримуються. + - Запускає Gateway (якщо потрібно) і виконує `openclaw health`. + - `openclaw status --deep` додає live-перевірку стану Gateway до виводу статусу, включно з перевірками каналів, якщо вони підтримуються. - Зчитує доступні Skills і перевіряє вимоги. - - Дозволяє вибрати менеджер node: npm, pnpm або bun. - - Установлює необов’язкові залежності (деякі використовують Homebrew на macOS). + - Дозволяє вибрати менеджер Node: npm, pnpm або bun. + - Встановлює необов’язкові залежності (деякі використовують Homebrew на macOS). - - Підсумок і наступні кроки, зокрема варіанти для застосунків iOS, Android і macOS. + - Підсумок і подальші кроки, включно з варіантами застосунків для iOS, Android і macOS. -Якщо GUI не виявлено, майстер виводить інструкції з перенаправлення SSH-порту для Control UI замість відкриття браузера. +Якщо GUI не виявлено, майстер виводить інструкції з SSH port-forward для Control UI замість відкриття браузера. Якщо ресурси Control UI відсутні, майстер намагається їх зібрати; резервний варіант — `pnpm ui:build` (автоматично встановлює UI-залежності). ## Докладно про віддалений режим -Віддалений режим налаштовує цю машину для підключення до gateway в іншому місці. +Віддалений режим налаштовує цю машину для підключення до Gateway, який працює в іншому місці. -Віддалений режим не встановлює й не змінює нічого на віддаленому хості. +Віддалений режим не встановлює і не змінює нічого на віддаленому хості. -Що ви задаєте: +Що ви налаштовуєте: -- URL віддаленого gateway (`ws://...`) -- Token, якщо для віддаленого gateway потрібна auth (рекомендовано) +- URL віддаленого Gateway (`ws://...`) +- Токен, якщо для віддаленого Gateway потрібна auth (рекомендовано) -- Якщо gateway доступний лише через loopback, використовуйте тунелювання SSH або tailnet. +- Якщо Gateway доступний лише через loopback, використовуйте SSH-тунелювання або tailnet. - Підказки для виявлення: - macOS: Bonjour (`dns-sd`) - Linux: Avahi (`avahi-browse`) -## Параметри автентифікації та моделі +## Варіанти автентифікації та моделей - Використовує `ANTHROPIC_API_KEY`, якщо він є, або запитує ключ, а потім зберігає його для використання демоном. + Використовує `ANTHROPIC_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його для використання демоном. Потік через браузер; вставте `code#state`. - Установлює `agents.defaults.model` в `openai-codex/gpt-5.5`, якщо модель не задано або вона вже належить до сімейства OpenAI. + Установлює `agents.defaults.model` на `openai-codex/gpt-5.5`, якщо модель не задана або вже належить до сімейства OpenAI. - + Потік pairing через браузер із короткоживучим кодом пристрою. - Установлює `agents.defaults.model` в `openai-codex/gpt-5.5`, якщо модель не задано або вона вже належить до сімейства OpenAI. + Установлює `agents.defaults.model` на `openai-codex/gpt-5.5`, якщо модель не задана або вже належить до сімейства OpenAI. - Використовує `OPENAI_API_KEY`, якщо він є, або запитує ключ, а потім зберігає облікові дані в auth profiles. + Використовує `OPENAI_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає облікові дані в auth-профілях. - Установлює `agents.defaults.model` в `openai/gpt-5.4`, якщо модель не задано, має вигляд `openai/*` або `openai-codex/*`. + Установлює `agents.defaults.model` на `openai/gpt-5.4`, якщо модель не задана, має вигляд `openai/*` або `openai-codex/*`. - Запитує `XAI_API_KEY` і налаштовує xAI як provider моделей. + Запитує `XAI_API_KEY` і налаштовує xAI як провайдера моделей. Запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) і дозволяє вибрати каталог Zen або Go. URL налаштування: [opencode.ai/auth](https://opencode.ai/auth). - + Зберігає ключ за вас. @@ -171,13 +171,13 @@ x-i18n: Докладніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway). - Конфігурація записується автоматично. Hosted-значення за замовчуванням — `MiniMax-M2.7`; налаштування через API-ключ використовує - `minimax/...`, а налаштування через OAuth — `minimax-portal/...`. + Конфігурація записується автоматично. Типове hosted-значення — `MiniMax-M2.7`; для налаштування через API-ключ використовується + `minimax/...`, а для налаштування через OAuth — `minimax-portal/...`. Докладніше: [MiniMax](/uk/providers/minimax). - Конфігурація автоматично записується для стандартного StepFun або Step Plan на ендпоїнтах China чи global. - Стандартний варіант наразі містить `step-3.5-flash`, а Step Plan також містить `step-3.5-flash-2603`. + Конфігурація записується автоматично для стандартного StepFun або Step Plan на китайських чи глобальних endpoint. + Стандартний варіант наразі включає `step-3.5-flash`, а Step Plan також включає `step-3.5-flash-2603`. Докладніше: [StepFun](/uk/providers/stepfun). @@ -185,94 +185,95 @@ x-i18n: Докладніше: [Synthetic](/uk/providers/synthetic). - Спочатку запитує `Cloud + Local`, `Cloud only` або `Local only`. + Спочатку пропонує `Cloud + Local`, `Cloud only` або `Local only`. `Cloud only` використовує `OLLAMA_API_KEY` з `https://ollama.com`. - Режими з прив’язкою до хоста запитують base URL (типово `http://127.0.0.1:11434`), виявляють доступні моделі та пропонують значення за замовчуванням. - `Cloud + Local` також перевіряє, чи цей хост Ollama виконав вхід для cloud-доступу. + У режимах із хостом запитується базовий URL (за замовчуванням `http://127.0.0.1:11434`), виявляються доступні моделі та пропонуються типові значення. + `Cloud + Local` також перевіряє, чи цей хост Ollama увійшов у систему для доступу до cloud. Докладніше: [Ollama](/uk/providers/ollama). Конфігурації Moonshot (Kimi K2) і Kimi Coding записуються автоматично. Докладніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot). - - Працює з ендпоїнтами, сумісними з OpenAI і Anthropic. + + Працює з endpoint, сумісними з OpenAI і Anthropic. - Інтерактивне initial setup підтримує ті самі варіанти зберігання API-ключа, що й інші потоки API-ключів provider: - - **Paste API key now** (plaintext) - - **Use secret reference** (env ref або налаштований provider ref, із preflight-перевіркою) + Інтерактивний onboarding підтримує ті самі варіанти збереження API-ключа, що й інші потоки API-ключів провайдерів: + - **Вставити API-ключ зараз** (plaintext) + - **Використовувати посилання на секрет** (env ref або налаштоване посилання провайдера з попередньою перевіркою) - Неінтерактивні прапорці: + Прапорці неінтерактивного режиму: - `--auth-choice custom-api-key` - `--custom-base-url` - `--custom-model-id` - - `--custom-api-key` (необов’язково; резервно використовує `CUSTOM_API_KEY`) + - `--custom-api-key` (необов’язково; інакше використовується `CUSTOM_API_KEY`) - `--custom-provider-id` (необов’язково) - - `--custom-compatibility ` (необов’язково; типово `openai`) + - `--custom-compatibility ` (необов’язково; за замовчуванням `openai`) - Залишає автентифікацію неналаштованою. + Залишає auth неналаштованою. Поведінка моделей: -- Виберіть типову модель із виявлених варіантів або вручну введіть provider і модель. -- Коли initial setup починається з вибору auth provider, засіб вибору моделі автоматично віддає - перевагу цьому provider. Для Volcengine і BytePlus така сама перевага - також охоплює їхні coding-plan варіанти (`volcengine-plan/*`, +- Виберіть модель за замовчуванням із виявлених варіантів або введіть провайдера і модель вручну. +- Коли onboarding починається з вибору автентифікації провайдера, засіб вибору моделі автоматично віддає + перевагу цьому провайдеру. Для Volcengine і BytePlus така сама перевага + також охоплює їхні варіанти coding-plan (`volcengine-plan/*`, `byteplus-plan/*`). -- Якщо такий фільтр preferred-provider дав би порожній результат, засіб вибору повертається до - повного каталогу замість того, щоб не показувати жодної моделі. -- Майстер виконує перевірку моделі та попереджає, якщо налаштована модель невідома або для неї бракує auth. +- Якщо такий фільтр бажаного провайдера дає порожній результат, засіб вибору повертається до + повного каталогу замість того, щоб показувати відсутність моделей. +- Майстер виконує перевірку моделі та попереджає, якщо налаштована модель невідома або для неї немає auth. -Шляхи облікових даних і профілів: +Шляхи до облікових даних і профілів: -- Auth profiles (API-ключі + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` -- Імпорт застарілого OAuth: `~/.openclaw/credentials/oauth.json` +- Auth-профілі (API-ключі + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` +- Застарілий імпорт OAuth: `~/.openclaw/credentials/oauth.json` Режим зберігання облікових даних: -- Типова поведінка initial setup зберігає API-ключі як plaintext-значення в auth profiles. -- `--secret-input-mode ref` вмикає режим посилань замість зберігання plaintext-ключів. - В інтерактивному налаштуванні можна вибрати: - - посилання на env-змінну (наприклад, `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`) - - посилання на налаштований provider (`file` або `exec`) з alias provider + id -- Інтерактивний режим посилань виконує швидку preflight-перевірку перед збереженням. - - Env refs: перевіряє ім’я змінної та непорожнє значення в поточному середовищі initial setup. - - Provider refs: перевіряє конфігурацію provider і розв’язує запитаний id. - - Якщо preflight-перевірка не проходить, initial setup показує помилку й дозволяє повторити спробу. -- У неінтерактивному режимі `--secret-input-mode ref` підтримує лише env-backed варіант. - - Задайте env-змінну provider у середовищі процесу initial setup. - - Inline-прапорці ключів (наприклад, `--openai-api-key`) вимагають, щоб цю env-змінну було задано; інакше initial setup одразу завершується помилкою. - - Для користувацьких provider неінтерактивний режим `ref` зберігає `models.providers..apiKey` як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. - - У такому випадку для custom-provider `--custom-api-key` вимагає, щоб було задано `CUSTOM_API_KEY`; інакше initial setup одразу завершується помилкою. -- Облікові дані auth Gateway підтримують вибір plaintext і SecretRef в інтерактивному налаштуванні: - - Режим token: **Generate/store plaintext token** (типово) або **Use SecretRef**. - - Режим password: plaintext або SecretRef. -- Неінтерактивний шлях SecretRef для token: `--gateway-token-ref-env `. -- Наявні plaintext-конфігурації продовжують працювати без змін. +- Типова поведінка onboarding зберігає API-ключі як plaintext-значення в auth-профілях. +- `--secret-input-mode ref` вмикає режим посилань замість зберігання ключів як plaintext. + В інтерактивному налаштуванні можна вибрати один із двох варіантів: + - посилання на змінну середовища (наприклад, `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`) + - посилання на налаштованого провайдера (`file` або `exec`) з alias провайдера + id +- Інтерактивний режим посилань виконує швидку попередню перевірку перед збереженням. + - Env ref: перевіряє ім’я змінної та непорожнє значення в поточному середовищі onboarding. + - Посилання провайдера: перевіряє конфігурацію провайдера та визначає запитаний id. + - Якщо попередня перевірка не проходить, onboarding показує помилку й дозволяє повторити спробу. +- У неінтерактивному режимі `--secret-input-mode ref` підтримує лише env. + - Установіть змінну середовища провайдера в середовищі процесу onboarding. + - Inline-прапорці ключів (наприклад, `--openai-api-key`) вимагають, щоб ця змінна середовища була встановлена; інакше onboarding одразу завершується з помилкою. + - Для кастомних провайдерів неінтерактивний режим `ref` зберігає `models.providers..apiKey` як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. + - У цьому випадку для кастомного провайдера `--custom-api-key` вимагає, щоб `CUSTOM_API_KEY` було встановлено; інакше onboarding одразу завершується з помилкою. +- Облікові дані auth Gateway в інтерактивному налаштуванні підтримують як plaintext, так і SecretRef: + - Режим токена: **Згенерувати/зберегти plaintext-токен** (за замовчуванням) або **Використовувати SecretRef**. + - Режим пароля: plaintext або SecretRef. +- Шлях SecretRef для токена в неінтерактивному режимі: `--gateway-token-ref-env `. +- Наявні plaintext-налаштування і далі працюють без змін. -Порада для headless і серверів: завершіть OAuth на машині з браузером, а потім скопіюйте +Порада для headless- і серверного режиму: виконайте OAuth на машині з браузером, а потім скопіюйте `auth-profiles.json` цього агента (наприклад, `~/.openclaw/agents//agent/auth-profiles.json` або відповідний -шлях `$OPENCLAW_STATE_DIR/...`) на хост gateway. `credentials/oauth.json` +шлях `$OPENCLAW_STATE_DIR/...`) на хост Gateway. `credentials/oauth.json` є лише застарілим джерелом імпорту. -## Виводи й внутрішня будова +## Виводи та внутрішня реалізація Типові поля в `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` +- `agents.defaults.skipBootstrap`, якщо передано `--skip-bootstrap` - `agents.defaults.model` / `models.providers` (якщо вибрано Minimax) -- `tools.profile` (локальне initial setup за замовчуванням встановлює `"coding"`, якщо значення не задано; наявні явні значення зберігаються) +- `tools.profile` (локальний onboarding за замовчуванням встановлює `"coding"`, якщо значення не задано; наявні явно встановлені значення зберігаються) - `gateway.*` (mode, bind, auth, tailscale) -- `session.dmScope` (локальне initial setup за замовчуванням встановлює `per-channel-peer`, якщо значення не задано; наявні явні значення зберігаються) +- `session.dmScope` (локальний onboarding за замовчуванням встановлює `per-channel-peer`, якщо значення не задано; наявні явно встановлені значення зберігаються) - `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*` -- Channel allowlist (Slack, Discord, Matrix, Microsoft Teams), якщо ви ввімкнете це під час prompt (імена за можливості розв’язуються в ID) +- Allowlist каналів (Slack, Discord, Matrix, Microsoft Teams), якщо ви добровільно вмикаєте їх під час запитів (імена за можливості перетворюються на ID) - `skills.install.nodeManager` - Прапорець `setup --node-manager` приймає `npm`, `pnpm` або `bun`. - У ручній конфігурації пізніше все ще можна встановити `skills.install.nodeManager: "yarn"`. @@ -285,33 +286,33 @@ x-i18n: `openclaw agents add` записує `agents.list[]` і необов’язкові `bindings`. Облікові дані WhatsApp зберігаються в `~/.openclaw/credentials/whatsapp//`. -Сесії зберігаються в `~/.openclaw/agents//sessions/`. +Сеанси зберігаються в `~/.openclaw/agents//sessions/`. -Деякі канали постачаються як plugin. Якщо їх вибрано під час налаштування, майстер -запропонує встановити plugin (npm або локальний шлях) перед конфігурацією каналу. +Деякі канали постачаються як Plugins. Якщо їх вибрано під час налаштування, майстер +пропонує встановити Plugin (npm або локальний шлях) перед налаштуванням каналу. -Wizard RPC Gateway: +RPC майстра Gateway: - `wizard.start` - `wizard.next` - `wizard.cancel` - `wizard.status` -Клієнти (застосунок macOS і Control UI) можуть відображати кроки, не перевпроваджуючи логіку initial setup. +Клієнти (застосунок macOS і Control UI) можуть відображати кроки, не перевпроваджуючи логіку onboarding. Поведінка налаштування Signal: -- Завантажує відповідний release-артефакт +- Завантажує відповідний release asset - Зберігає його в `~/.openclaw/tools/signal-cli//` - Записує `channels.signal.cliPath` у конфігурацію -- JVM-збірки потребують Java 21 -- За наявності використовуються нативні збірки -- Windows використовує WSL2 і дотримується потоку Linux signal-cli всередині WSL +- Для збірок JVM потрібна Java 21 +- Коли доступні нативні збірки, використовуються вони +- Windows використовує WSL2 і дотримується Linux-процесу signal-cli всередині WSL ## Пов’язані документи -- Центр initial setup: [Onboarding (CLI)](/uk/start/wizard) -- Автоматизація та скрипти: [CLI Automation](/uk/start/wizard-cli-automation) -- Довідка по команді: [`openclaw onboard`](/uk/cli/onboard) +- Центр onboarding: [Onboarding (CLI)](/uk/start/wizard) +- Автоматизація і скрипти: [Автоматизація CLI](/uk/start/wizard-cli-automation) +- Довідник команд: [`openclaw onboard`](/uk/cli/onboard) diff --git a/docs/uk/tools/tokenjuice.md b/docs/uk/tools/tokenjuice.md index 01288a2b9..e34dd2a7c 100644 --- a/docs/uk/tools/tokenjuice.md +++ b/docs/uk/tools/tokenjuice.md @@ -1,29 +1,29 @@ --- read_when: - Ви хочете коротші результати інструментів `exec` або `bash` в OpenClaw - - Ви хочете ввімкнути bundled Plugin tokenjuice - - Вам потрібно зрозуміти, що змінює tokenjuice, а що він залишає сирим -summary: Стискання шумних результатів інструментів exec і bash за допомогою необов’язкового bundled Plugin + - Ви хочете ввімкнути вбудований Plugin tokenjuice + - Вам потрібно зрозуміти, що змінює tokenjuice і що він залишає в сирому вигляді +summary: Компактування шумних результатів інструментів exec і bash за допомогою необов’язкового вбудованого Plugin-а title: Tokenjuice x-i18n: - generated_at: "2026-04-23T23:08:55Z" + generated_at: "2026-04-24T19:53:59Z" model: gpt-5.4 provider: openai - source_hash: 0ff542095eb730f06eadec213289b93e31f1afa179160b7d4e915329f09ad5f1 + source_hash: 04328cc7a13ccd64f8309ddff867ae893387f93c26641dfa1a4013a4c3063962 source_path: tools/tokenjuice.md workflow: 15 --- -`tokenjuice` — це необов’язковий bundled Plugin, який стискає шумні результати інструментів `exec` і `bash` -після того, як команда вже виконалася. +`tokenjuice` — це необов’язковий вбудований Plugin, який виконує Compaction шумних результатів інструментів `exec` і `bash` +після того, як команда вже була виконана. Він змінює повернений `tool_result`, а не саму команду. Tokenjuice не переписує shell-ввід, не перезапускає команди й не змінює коди виходу. -Сьогодні це застосовується до вбудованих запусків Pi, де tokenjuice перехоплює вбудований -шлях `tool_result` і обрізає вивід, який повертається в сесію. +Наразі це застосовується до вбудованих запусків PI та динамічних інструментів OpenClaw у harness app-server Codex. Tokenjuice підключається до middleware результатів інструментів OpenClaw і +обрізає вивід перед тим, як він повертається в активний сеанс harness-а. -## Увімкнення Plugin +## Увімкнення Plugin-а Швидкий шлях: @@ -37,10 +37,10 @@ openclaw config set plugins.entries.tokenjuice.enabled true openclaw plugins enable tokenjuice ``` -OpenClaw уже постачає цей Plugin. Окремого кроку `plugins install` +OpenClaw уже постачається з цим Plugin-ом. Окремого кроку `plugins install` або `tokenjuice install openclaw` немає. -Якщо ви віддаєте перевагу прямому редагуванню конфігурації: +Якщо вам зручніше редагувати config напряму: ```json5 { @@ -56,19 +56,19 @@ OpenClaw уже постачає цей Plugin. Окремого кроку `plu ## Що змінює tokenjuice -- Стискає шумні результати `exec` і `bash` перед тим, як вони повертаються в сесію. -- Не змінює оригінальне виконання команди. +- Виконує Compaction шумних результатів `exec` і `bash` перед тим, як вони повертаються в сеанс. +- Залишає оригінальне виконання команди без змін. - Зберігає точне читання вмісту файлів та інші команди, які tokenjuice має залишати сирими. -- Залишається опціональним: вимкніть Plugin, якщо хочете буквальний вивід всюди. +- Залишається opt-in: вимкніть Plugin, якщо хочете дослівний вивід усюди. -## Як перевірити, що це працює +## Як перевірити, що він працює 1. Увімкніть Plugin. -2. Запустіть сесію, яка може викликати `exec`. +2. Запустіть сеанс, який може викликати `exec`. 3. Виконайте шумну команду, наприклад `git status`. -4. Переконайтеся, що повернений результат інструмента коротший і структурованіший, ніж сирий shell-вивід. +4. Переконайтеся, що повернений результат інструмента коротший і більш структурований, ніж сирий shell-вивід. -## Вимкнення Plugin +## Вимкнення Plugin-а ```bash openclaw config set plugins.entries.tokenjuice.enabled false @@ -82,6 +82,6 @@ openclaw plugins disable tokenjuice ## Пов’язане -- [Інструмент Exec](/uk/tools/exec) -- [Рівні мислення](/uk/tools/thinking) -- [Рушій контексту](/uk/concepts/context-engine) +- [Exec tool](/uk/tools/exec) +- [Thinking levels](/uk/tools/thinking) +- [Context engine](/uk/concepts/context-engine)