diff --git a/docs/uk/ci.md b/docs/uk/ci.md index ad3449552..f7deec2cc 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,47 +1,25 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося + - Вам потрібно зрозуміти, чому завдання CI було або не було запущене - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, перевірки за областю змін і локальні еквіваленти команд -title: CI pipeline +summary: Граф завдань CI, шлюзи області змін і локальні еквіваленти команд +title: Конвеєр CI x-i18n: - generated_at: "2026-04-23T20:45:42Z" + generated_at: "2026-04-23T21:58:43Z" model: gpt-5.4 provider: openai - source_hash: f06d3bec8a44402afb3aeec252105d3e3c985307deb3fcc0859c2d1df50f2612 + source_hash: d2aa581f173b7171373a9292cef3da20621b845d81a8550bd8b4c8e743d27a4b source_path: ci.md workflow: 15 --- -CI запускається при кожному push до `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише непов’язані частини. +CI запускається для кожного push до `main` і кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. -QA Lab має окремі lane-и CI поза основним smart-scoped workflow. Workflow -`Parity gate` запускається для відповідних змін у PR і через manual dispatch; він -збирає приватне runtime QA і порівнює agentic pack-и mock GPT-5.4 та Opus 4.6. -Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через -manual dispatch; він розпаралелює mock parity gate, live lane Matrix і live -lane Telegram як паралельні завдання. Live-завдання використовують environment -`qa-live-shared`, а lane Telegram використовує lease-и Convex. `OpenClaw Release -Checks` також запускає ті самі lane-и QA Lab перед схваленням релізу. +QA Lab має окремі CI-лінії поза основним workflow з розумним визначенням області. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний dispatch; він збирає приватне QA runtime і порівнює agentic pack-и mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний dispatch; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram lane використовує lease-и Convex. `OpenClaw Release Checks` також запускає ті самі лінії QA Lab перед затвердженням релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow супровідника для -очищення дублікатів після приземлення змін. За замовчуванням він працює в режимі dry-run і -закриває лише явно вказані PR, коли `apply=true`. Перш ніж змінювати GitHub, -він перевіряє, що приземлений PR уже merged, і що кожен дублікат має або спільну -issue, на яку є посилання, або перекривані змінені hunks. +Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідників для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді об’єднано, і що кожен дублікат має або спільну пов’язану issue, або перетин змінених hunks. -Workflow `Test Performance Agent` — це event-driven lane супроводу Codex -для повільних тестів. Він не має суто планового запуску: його може запустити -успішний небоговий запуск push CI на `main`, але він пропускається, якщо того UTC-дня -інше workflow-run викликання вже виконалося або ще виконується. -Manual dispatch обходить це денне обмеження активності. Цей lane будує grouped report -продуктивності Vitest для повного набору тестів, дозволяє Codex вносити лише -невеликі виправлення продуктивності тестів без втрати покриття, потім повторно запускає -повний report і відхиляє зміни, які зменшують базову кількість тестів, що проходять. -Якщо в базовому стані є тести, що не проходять, Codex може виправляти лише очевидні -помилки, а підсумковий повний report після агента має пройти повністю, перш ніж -щось буде закомічено. Він використовує GitHub-hosted Ubuntu, щоб дія Codex могла -зберігати ту саму безпечну політику drop-sudo, що й агент документації. +Workflow `Test Performance Agent` — це event-driven лінія обслуговування Codex для повільних тестів. Вона не має окремого розкладу: її може запустити успішний неблокований push CI на `main`, але вона пропускається, якщо того ж дня за UTC вже був або виконується інший виклик workflow-run. Ручний dispatch обходить це денне обмеження активності. Лінія збирає grouped Vitest performance report для повного набору тестів, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору тестів і відхиляє зміни, які зменшують базову кількість тестів, що проходять. Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а after-agent звіт для повного набору тестів має пройти, перш ніж щось буде закомічено. Коли `main` просувається вперед до того, як bot push буде застосовано, лінія перебазовує перевірений patch, повторно запускає `pnpm check:changed` і повторює push; застарілі patch-і з конфліктами пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну політику drop-sudo, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -52,84 +30,87 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Виявляє зміни лише в docs, змінені області, змінені extensions і будує CI manifest | Завжди для non-draft push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для non-draft push і PR | -| `security-fast` | Обов’язковий aggregate для швидких завдань безпеки | Завжди для non-draft push і PR | -| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні Node | -| `checks-fast-core` | Швидкі lane-и коректності Linux, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні Node | -| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним aggregate результатом перевірки | Зміни, релевантні Node | -| `checks-node-extensions` | Повні шардовані тести bundled-plugin для всього набору extension | Зміни, релевантні Node | -| `checks-node-core-test` | Шарди core Node tests, за винятком lane-ів channel, bundled, contract і extension | Зміни, релевантні Node | -| `extension-fast` | Фокусні тести лише для змінених bundled plugin | Pull request-и зі змінами в extension | -| `check` | Шардований еквівалент основного локального gate: production types, lint, guards, test types і strict smoke | Зміни, релевантні Node | -| `check-additional` | Architecture, boundary, guards поверхні extension, package-boundary і шарди gateway-watch | Зміни, релевантні Node | -| `build-smoke` | Smoke-тести built-CLI і smoke перевірка пам’яті під час запуску | Зміни, релевантні Node | -| `checks` | Верифікатор для channel tests built-artifact плюс compat з Node 22 лише для push | Зміни, релевантні Node | -| `check-docs` | Форматування docs, lint і перевірки битих посилань | Змінено docs | -| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні Python Skills | -| `checks-windows` | Специфічні для Windows test lane-и | Зміни, релевантні Windows | -| `macos-node` | Lane тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні macOS | -| `macos-swift` | Swift lint, build і tests для застосунку macOS | Зміни, релевантні macOS | -| `android` | Android unit tests для обох flavor-ів плюс одна debug APK build | Зміни, релевантні Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх main CI або manual dispatch | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | +| `preflight` | Визначає зміни лише в docs, змінені області, змінені extensions і будує CI manifest | Завжди для недрафтових push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для недрафтових push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для недрафтових push і PR | +| `security-fast` | Обов’язковий агрегатор для швидких security-завдань | Завжди для недрафтових push і PR | +| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі Linux-лінії коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extensions | Зміни, релевантні для Node | +| `checks-node-core-test` | Шарди основних Node-тестів, без channel, bundled, contract і extension-ліній | Зміни, релевантні для Node | +| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request-и зі змінами extensions | +| `check` | Шардований еквівалент основного локального шлюзу: production types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Шарди для архітектури, меж, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести built-CLI і smoke стартової пам’яті | Зміни, релевантні для Node | +| `checks` | Верифікатор для built-artifact тестів каналів плюс сумісність 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 з використанням спільних built artifacts | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Android unit-тести для обох flavor-ів плюс одна debug APK збірка | Зміни, релевантні для Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний CI на main або ручний dispatch | ## Порядок Fail-Fast -Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запускаються дорогі: +Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запустяться дорогі: -1. `preflight` вирішує, які lane-и взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих matrix-завдань для artifacts і platform. -3. `build-artifacts` виконується паралельно зі швидкими Linux lane-ами, щоб downstream-споживачі могли стартувати, щойно спільна збірка буде готова. -4. Після цього розгалужуються важчі lane-и platform і runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, PR-only `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`, `extension-fast` лише для PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка області змін живе в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. -Редагування workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують запускати native build-и Windows, Android або macOS; ці platform lane-и залишаються прив’язаними до змін у платформному коді. -Перевірки Windows Node обмежені специфічними для Windows wrapper-ами process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цей lane; непов’язані зміни вихідного коду, plugin, install-smoke і test-only зміни залишаються в Linux Node lane-ах, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними test shard-ами. -Окремий workflow `install-smoke` повторно використовує той самий скрипт області змін через власне завдання `preflight`. Він обчислює `run_install_smoke` з вужчого сигналу changed-smoke, тож Docker/install smoke запускається для змін, пов’язаних із встановленням, пакуванням, контейнерами, production-змін bundled extension, а також для основних поверхонь plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише в tests і docs не резервують Docker workers. Його QR package smoke примушує шар Docker `pnpm install` перезапускатися, зберігаючи кеш BuildKit pnpm store, тож він усе одно перевіряє встановлення без повторного завантаження залежностей у кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах того самого завдання, тож додає реальне покриття WebSocket між контейнерами без ще однієї Docker build. Локальний `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім паралельно запускає live/E2E smoke lane-и з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартний рівень паралелізму 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний aggregate за замовчуванням припиняє планувати нові pooled lane-и після першого збою, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane-и, чутливі до запуску або provider-а, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний workflow live/E2E віддзеркалює шаблон shared-image: він збирає та пушить один GHCR Docker E2E image з тегом SHA перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Плановий workflow live/E2E щодня запускає повний набір Docker suite для шляху релізу. Docker-тести QR та installer зберігають власні Dockerfile, сфокусовані на встановленні. Окреме завдання `docker-e2e-fast` запускає обмежений Docker profile bundled-plugin під тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс ізоляцію synthetic bundled-loader failure. Повна matrix для bundled update/channel залишається ручною/повного набору, оскільки виконує повторні реальні проходи npm update і doctor repair. +Логіка області змін міститься в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни workflow CI перевіряють Node CI graph плюс lint workflow, але самі по собі не примушують запускати нативні збірки для Windows, Android або macOS; ці platform-лінії залишаються прив’язаними до змін у коді відповідної платформи. +Перевірки Windows Node прив’язані до специфічних для Windows process/path wrappers, npm/pnpm/UI runner helpers, конфігурації package manager і поверхонь CI workflow, які виконують цю лінію; не пов’язані зміни вихідного коду, plugins, install-smoke і зміни лише тестів залишаються на Linux Node-лініях, щоб не резервувати Windows worker на 16 vCPU для покриття, яке вже перевіряється звичайними test shard-ами. +Окремий workflow `install-smoke` повторно використовує той самий скрипт визначення області через власне завдання `preflight`. Він обчислює `run_install_smoke` із вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, пов’язаних з установленням, пакуванням, контейнерами, production-змін bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише тестів і лише docs не резервують Docker workers. Його QR package smoke примушує Docker-шар `pnpm install` виконатися повторно, водночас зберігаючи кеш BuildKit pnpm store, тож установка все одно перевіряється без повторного завантаження залежностей у кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в цьому завданні, тож додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локально `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image з `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke-лінії паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартний рівень паралелізму 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled lanes після першого збою, а кожна лінія має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Лінії, чутливі до запуску або provider-ів, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний live/E2E workflow відтворює шаблон спільного image, збираючи й публікуючи один SHA-tagged GHCR Docker E2E image перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний релізний Docker-набір. QR і installer Docker-тести зберігають власні Dockerfile, орієнтовані на встановлення. Окреме завдання `docker-e2e-fast` запускає обмежений профіль bundled-plugin у Docker з тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс synthetic bundled-loader failure isolation. Повна matrix для оновлення bundled і channel залишається ручною/для повного набору, оскільки виконує повторні реальні проходи `npm update` і `doctor repair`. -Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо architecture boundary, ніж широка CI-область платформ: production-зміни core запускають typecheck core prod плюс core tests, зміни лише в core tests запускають лише typecheck/tests для core test, production-зміни extension запускають typecheck extension prod плюс extension tests, а зміни лише в extension tests запускають лише typecheck/tests для extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extension, оскільки extension залежать від цих core contract. Version bump-и лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно розширюються до всіх lane-ів. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний шлюз суворіший щодо архітектурних меж, ніж широка platform-область у CI: production-зміни core запускають production typecheck core плюс тести core, зміни лише test-коду core запускають лише typecheck/tests для тестів core, production-зміни extensions запускають production typecheck extensions плюс тести extensions, а зміни лише test-коду extensions запускають лише typecheck/tests для тестів extensions. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extensions, тому що extensions залежать від цих core-контрактів. Версійні зміни лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно переводять у всі лінії. -Для push matrix `checks` додає lane `compat-node22`, який запускається лише для push. Для pull request цей lane пропускається, і matrix зосереджується на звичайних test/channel lane-ах. +Для push matrix `checks` додає лінію `compat-node22`, що запускається лише для push. Для pull request-ів ця лінія пропускається, і matrix залишається зосередженою на звичайних test/channel-лініях. -Найповільніші сімейства Node tests поділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contract-и запускаються у трьох зважених shard-ах, bundled plugin tests балансуються між шістьма worker-ами extension, невеликі core unit lane-и об’єднуються в пари, auto-reply запускається у трьох збалансованих worker-ах замість шести крихітних worker-ів, а agentic gateway/plugin config-и розподіляються між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media та різні plugin tests використовують свої окремі конфігурації Vitest замість спільного універсального plugin catch-all. Завдання shard-ів extension запускають групи конфігурацій plugin послідовно з одним worker-ом Vitest і більшим heap Node, щоб import-heavy пакети plugin-ів не перевантажували малі CI runner-и. Широкий lane agents використовує спільний file-parallel scheduler Vitest, оскільки в ньому домінують import/scheduling, а не один повільний test file. `runtime-config` запускається разом із shard-ом infra core-runtime, щоб спільний runtime shard не залишався найдовшим. `check-additional` тримає compile/canary-роботи package-boundary разом і відокремлює архітектуру topology runtime від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guard-и паралельно всередині одного завдання. Gateway watch, channel tests і shard support-boundary core запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі імена перевірок як легкі завдання-верифікатори й водночас уникаючи двох додаткових worker-ів Blacksmith і другої черги споживачів artifact-ів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-test усе одно компілює цей flavor із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK при кожному Android-релевантному push. -`extension-fast` виконується лише для PR, оскільки push-запуски вже виконують повні shard-и bundled plugin. Це зберігає зворотний зв’язок для reviews щодо змінених plugin-ів, не резервуючи додатковий worker Blacksmith на `main` для покриття, яке вже є в `checks-node-extensions`. +Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів виконуються як три зважені шарди, тести bundled plugin розподіляються між шістьма worker-ами extension, малі core unit-лінії об’єднуються в пари, auto-reply працює на трьох збалансованих worker-ах замість шести дрібних, а конфігурації agentic gateway/plugin розподіляються по наявних source-only agentic Node-завданнях замість очікування built artifacts. Широкі browser-, QA-, media- та miscellaneous plugin-тести використовують свої виділені конфігурації Vitest замість спільного універсального plugin-набору. Завдання shard-ів extensions запускають групи конфігурацій plugin послідовно з одним Vitest worker-ом і більшим Node heap, щоб import-інтенсивні пакети plugin-ів не перевантажували малі CI runner-и. Широка лінія agents використовує спільний file-parallel scheduler Vitest, оскільки в ній домінують import-и/планування, а не один повільний тестовий файл. `runtime-config` виконується разом із shard-ом infra core-runtime, щоб спільний runtime-shard не утримував tail. `check-additional` тримає package-boundary compile/canary-перевірки разом і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guard-и паралельно в межах одного завдання. Gateway watch, channel-тести та shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи свої старі назви перевірок як легкі verifier-завдання та водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги artifact-consumer. -GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тож вони все ще повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений. -Ключ concurrency CI має версію (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запускі `main`. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює цей flavor із прапорцями SMS/call-log BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK при кожному Android-релевантному push. + +`extension-fast` доступний лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це зберігає зворотний зв’язок для змінених plugin-ів під час review без резервування додаткового Blacksmith worker-а на `main` для покриття, яке вже є в `checks-node-extensions`. + +GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані shard-перевірки використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений. + +Ключ concurrency CI має версіонування (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій queue group не міг безстроково блокувати новіші запуски `main`. ## Runner-и -| Runner | Завдання | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та aggregate-и (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, shard-и `check`, крім lint, shard-и й aggregate-и `check-additional`, aggregate-верифікатори Node tests, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб matrix 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 build-и install-smoke, де час очікування в черзі на 32 vCPU коштував дорожче, ніж давав вигоду | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; fork-и повертаються до `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; fork-и повертаються до `macos-latest` | +| Runner | Завдання | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі security-завдання й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, aggregate verifier-и Node-тестів, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла ставати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди Linux Node-тестів, шарди тестів bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який і надалі достатньо чутливий до CPU, так що 8 vCPU коштували дорожче, ніж заощаджували; Docker-збірки install-smoke, де вартість часу очікування 32-vCPU перевищувала виграш | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для fork-ів відбувається fallback до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork-ів відбувається fallback до `macos-latest` | ## Локальні еквіваленти ```bash -pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумний локальний gate: changed typecheck/lint/tests за boundary lane -pnpm check # швидкий локальний gate: production tsgo + sharded lint + parallel fast guards +pnpm changed:lanes # перевірити локальний класифікатор changed-lane для origin/main...HEAD +pnpm check:changed # розумний локальний шлюз: changed typecheck/lint/tests за boundary lane +pnpm check # швидкий локальний шлюз: production tsgo + шардований lint + паралельні швидкі guard-и pnpm check:test-types -pnpm check:timed # той самий gate з вимірюванням часу по етапах +pnpm check:timed # той самий шлюз із таймінгами для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # формат docs + lint + биті посилання -pnpm build # зібрати dist, коли важливі lane-и CI artifact/build-smoke -node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші завдання -node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запускі main CI +pnpm check:docs # форматування docs + lint + биті посилання +pnpm build # зібрати dist, коли важливі CI artifact/build-smoke лінії +node scripts/ci-run-timings.mjs # підсумувати загальний час, час у черзі та найповільніші завдання +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md index 1a66c0a70..47321ca6b 100644 --- a/docs/uk/gateway/cli-backends.md +++ b/docs/uk/gateway/cli-backends.md @@ -1,48 +1,41 @@ --- read_when: - - Ви хочете надійний fallback, коли API-провайдери виходять з ладу + - Вам потрібен надійний резервний варіант, коли API-провайдери не працюють - Ви запускаєте Codex CLI або інші локальні AI CLI і хочете використовувати їх повторно - - Ви хочете зрозуміти міст MCP loopback для доступу інструментів backend CLI -summary: 'CLI backends: локальний fallback AI CLI з необов’язковим мостом інструментів MCP' -title: CLI backends + - Ви хочете зрозуміти міст local loopback MCP для доступу CLI-бекенда до інструментів +summary: 'CLI-бекенди: локальний резервний варіант AI CLI з необов’язковим мостом інструментів MCP' +title: CLI-бекенди x-i18n: - generated_at: "2026-04-23T20:52:25Z" + generated_at: "2026-04-23T21:58:47Z" model: gpt-5.4 provider: openai - source_hash: 86594b886c259df68591223e106c7507ab802321aaedebc9b243793c4f453388 + source_hash: d4f3f2f0a02539455de1a9f3982590e507e5ccd1e4cc354658118eadf522150a source_path: gateway/cli-backends.md workflow: 15 --- -# CLI backends (fallback runtime) +# CLI-бекенди (резервне середовище виконання) -OpenClaw може запускати **локальні AI CLI** як **text-only fallback**, коли API-провайдери недоступні, -обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний режим: +OpenClaw може запускати **локальні AI CLI** як **лише текстовий резервний варіант**, коли API-провайдери недоступні, обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід: -- **Інструменти OpenClaw не впроваджуються напряму**, але backends із `bundleMcp: true` - можуть отримувати інструменти gateway через loopback MCP bridge. -- **JSONL Streaming** для CLI, які це підтримують. -- **Підтримуються сесії** (щоб подальші ходи залишалися узгодженими). +- **Інструменти OpenClaw не інжектуються безпосередньо**, але бекенди з `bundleMcp: true` можуть отримувати інструменти шлюзу через міст loopback MCP. +- **JSONL-стримінг** для CLI, які його підтримують. +- **Сесії підтримуються** (тому наступні ходи залишаються узгодженими). - **Зображення можна передавати наскрізно**, якщо CLI приймає шляхи до зображень. -Це задумано як **страхувальна сітка**, а не основний шлях. Використовуйте це, коли вам -потрібні відповіді у форматі «працює завжди» без залежності від зовнішніх API. +Це розроблено як **страхувальну опцію**, а не як основний шлях. Використовуйте це, коли вам потрібні текстові відповіді, які «завжди працюють», без залежності від зовнішніх API. -Якщо вам потрібен повноцінний runtime harness із керуванням сесіями ACP, фоновими завданнями, -прив’язкою до thread/conversation і постійними зовнішніми coding sessions, використовуйте -[ACP Agents](/uk/tools/acp-agents). CLI backends — це не ACP. +Якщо вам потрібне повноцінне середовище виконання з керуванням сесіями ACP, фоновими завданнями, прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, натомість використовуйте [ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP. ## Швидкий старт для початківців -Ви можете використовувати Codex CLI **без жодної конфігурації** (bundled OpenAI Plugin -реєструє типовий backend): +Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований Plugin OpenAI реєструє типовий бекенд): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.5 ``` -Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише -шлях до команди: +Якщо ваш Gateway працює під launchd/systemd і `PATH` мінімальний, додайте лише шлях до команди: ```json5 { @@ -58,16 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 } ``` -І все. Не потрібні ні ключі, ні додаткова конфігурація auth, окрім тієї, що вже є в самому CLI. +І це все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. -Якщо ви використовуєте bundled CLI backend як **основного провайдера повідомлень** на -хості gateway, OpenClaw тепер автоматично завантажує Plugin-власник, коли ваша конфігурація -явно посилається на цей backend у model ref або в -`agents.defaults.cliBackends`. +Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на хості Gateway, OpenClaw тепер автоматично завантажує відповідний вбудований Plugin, коли ваша конфігурація явно посилається на цей бекенд у посиланні моделі або в `agents.defaults.cliBackends`. -## Використання як fallback +## Використання як резервного варіанта -Додайте CLI backend до списку fallback, щоб він запускався лише тоді, коли основні моделі дають збій: +Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не спрацьовують: ```json5 { @@ -88,20 +78,19 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 Примітки: -- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого CLI backend. -- Якщо основний провайдер виходить з ладу (auth, rate limits, timeouts), OpenClaw - спробує наступним саме CLI backend. +- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого CLI-бекенда. +- Якщо основний провайдер не спрацьовує (автентифікація, обмеження швидкості, тайм-аути), OpenClaw далі спробує CLI-бекенд. ## Огляд конфігурації -Усі CLI backends розміщуються в: +Усі CLI-бекенди розміщуються в: ``` agents.defaults.cliBackends ``` -Кожен запис має ключ у вигляді **provider id** (наприклад, `codex-cli`, `my-cli`). -provider id стає лівою частиною вашого model ref: +Кожен запис має ключ у вигляді **id провайдера** (наприклад, `codex-cli`, `my-cli`). +Id провайдера стає лівою частиною посилання моделі: ``` / @@ -131,7 +120,7 @@ provider id стає лівою частиною вашого model ref: sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // CLI у стилі Codex можуть замість цього вказувати на файл prompt: + // CLI у стилі Codex можуть натомість вказувати на файл промпта: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -147,33 +136,34 @@ provider id стає лівою частиною вашого model ref: ## Як це працює -1. **Вибирає backend** на основі префікса провайдера (`codex-cli/...`). -2. **Будує системний prompt** з використанням того самого prompt OpenClaw + контексту робочого простору. -3. **Виконує CLI** з ID сесії (якщо це підтримується), щоб історія залишалася узгодженою. - Bundled backend `claude-cli` підтримує процес Claude stdio активним для кожної - сесії OpenClaw і надсилає подальші ходи через stdin stream-json. +1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`). +2. **Будує системний промпт** із використанням того самого промпта OpenClaw і контексту робочого простору. +3. **Виконує CLI** з id сесії (якщо підтримується), щоб історія залишалася узгодженою. + Вбудований бекенд `claude-cli` підтримує процес Claude stdio живим для кожної + сесії OpenClaw і надсилає наступні ходи через stream-json stdin. 4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст. -5. **Зберігає ID сесій** для кожного backend, тож подальші ходи повторно використовують ту саму CLI-сесію. +5. **Зберігає id сесій** для кожного бекенда, щоб наступні звернення повторно використовували ту саму CLI-сесію. -Bundled backend Anthropic `claude-cli` знову підтримується. Співробітники Anthropic -повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw розглядає +Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic +повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику. -Bundled backend OpenAI `codex-cli` передає системний prompt OpenClaw через -перевизначення конфігурації Codex `model_instructions_file` (`-c -model_instructions_file="..."`). Codex не надає прапорця -`--append-system-prompt` у стилі Claude, тому OpenClaw записує зібраний prompt у +Вбудований бекенд OpenAI `codex-cli` передає системний промпт OpenClaw через +перевизначення конфігурації `model_instructions_file` у Codex (`-c +model_instructions_file="..."`). Codex не надає прапорця у стилі Claude +`--append-system-prompt`, тому OpenClaw записує зібраний промпт у тимчасовий файл для кожної нової сесії Codex CLI. -Bundled backend Anthropic `claude-cli` отримує snapshot Skills OpenClaw -двома способами: компактний каталог Skills OpenClaw у доданому системному prompt і +Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw +двома способами: компактний каталог Skills OpenClaw у доданому системному промпті та тимчасовий Plugin Claude Code, переданий через `--plugin-dir`. Plugin містить -лише придатні Skills для цього агента/сесії, тож вбудований засіб визначення Skills у Claude Code бачить той самий відфільтрований набір, який OpenClaw інакше показав би в prompt. Перевизначення env/API key для Skills усе одно застосовуються OpenClaw до середовища дочірнього процесу для цього запуску. +лише ті Skills, які дозволені для цього агента/сесії, тож власний резолвер Skills у Claude Code +бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в промпті. Перевизначення env/API-ключів для Skills усе ще застосовуються OpenClaw до середовища дочірнього процесу під час запуску. -Перш ніж OpenClaw зможе використовувати bundled backend `claude-cli`, сам Claude Code +Перш ніж OpenClaw зможе використовувати вбудований бекенд `claude-cli`, сам Claude Code має вже бути авторизований на тому самому хості: ```bash @@ -188,67 +178,66 @@ openclaw models auth login --provider anthropic --method cli --set-default ## Сесії - Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або - `sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити + `sessionArgs` (placeholder `{sessionId}`), коли id потрібно вставляти в кілька прапорців. -- Якщо CLI використовує **resume subcommand** з іншими прапорцями, задайте +- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, задайте `resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput` (для відновлень не у форматі JSON). - `sessionMode`: - - `always`: завжди надсилати ID сесії (новий UUID, якщо нічого не збережено). - - `existing`: надсилати ID сесії лише якщо його було збережено раніше. - - `none`: ніколи не надсилати ID сесії. -- `claude-cli` типово використовує `liveSession: "claude-stdio"`, `output: "jsonl"` - і `input: "stdin"`, щоб подальші ходи повторно використовували активний процес Claude, поки - він працює. Тепле stdio тепер є типовим, включно з користувацькими конфігураціями, - які не вказують полів транспорту. Якщо Gateway перезапускається або процес у стані idle - завершується, OpenClaw відновлюється зі збереженого ID сесії Claude. Збережені ID сесій - перевіряються на наявність доступного для читання transcript проєкту перед - відновленням, тож фантомні прив’язки очищуються з `reason=transcript-missing` - замість тихого запуску нової сесії Claude CLI через `--resume`. + - `always`: завжди надсилати id сесії (новий UUID, якщо нічого не збережено). + - `existing`: надсилати id сесії лише якщо його вже було збережено. + - `none`: ніколи не надсилати id сесії. +- `claude-cli` типово використовує `liveSession: "claude-stdio"`, `output: "jsonl"`, + і `input: "stdin"`, тому наступні ходи повторно використовують живий процес Claude, поки + він активний. Тепле stdio тепер використовується за замовчуванням, зокрема для користувацьких конфігурацій, + які не вказують поля транспорту. Якщо Gateway перезапуститься або процес простою + завершиться, OpenClaw відновить роботу зі збереженого id сесії Claude. Збережені id сесій + перевіряються на наявність доступного для читання наявного транскрипту проєкту перед + відновленням, тож фантомні прив’язки очищаються з `reason=transcript-missing`, + а не непомітно запускають нову сесію Claude CLI під `--resume`. - Збережені CLI-сесії — це безперервність, якою володіє провайдер. Неявне щоденне - скидання сесії не розриває їх; `/reset` і явні політики `session.reset` усе ж розривають. + скидання їх не обриває; `/reset` і явні політики `session.reset` — обривають. Примітки щодо серіалізації: -- `serialize: true` зберігає порядок запусків у тій самій доріжці. -- Більшість CLI серіалізуються в межах однієї доріжки провайдера. -- OpenClaw відмовляється від повторного використання збереженої CLI-сесії, коли змінюється вибрана auth-ідентичність, - зокрема при зміні ID auth profile, статичного API key, статичного token або OAuth-ідентичності - облікового запису, якщо CLI її надає. Ротація OAuth access і refresh token - не розриває збережену CLI-сесію. Якщо CLI не надає стабільного ID облікового запису OAuth, - OpenClaw дозволяє цьому CLI самому застосовувати дозволи на відновлення. +- `serialize: true` зберігає порядок виконання в одній lane. +- Більшість CLI серіалізуються в одній lane провайдера. +- OpenClaw відкидає повторне використання збереженої CLI-сесії, коли змінюється вибрана identity автентифікації, + зокрема у разі зміни id профілю автентифікації, статичного API-ключа, статичного токена або OAuth- + identity облікового запису, якщо CLI її надає. Ротація OAuth access і refresh token не + обриває збережену CLI-сесію. Якщо CLI не надає стабільний OAuth account id, OpenClaw дозволяє цій CLI самій контролювати дозволи на відновлення. ## Зображення (наскрізна передача) -Якщо ваш CLI приймає шляхи до зображень, задайте `imageArg`: +Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw записуватиме base64-зображення в тимчасові файли. Якщо задано `imageArg`, ці -шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає -шляхи до файлів у prompt (впровадження шляху), чого достатньо для CLI, які автоматично -завантажують локальні файли за звичайними шляхами. +OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці +шляхи передаватимуться як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає +шляхи до файлів у промпт (інжекція шляху), чого достатньо для CLI, які автоматично +завантажують локальні файли зі звичайних шляхів. ## Входи / виходи -- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ID сесії. +- `output: "json"` (типово) намагається розібрати JSON і витягти текст + id сесії. - Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а - usage — зі `stats`, коли `usage` відсутній або порожній. -- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента плюс ідентифікатори сесії, коли вони присутні. -- `output: "text"` трактує stdout як фінальну відповідь. + usage — з `stats`, коли `usage` відсутній або порожній. +- `output: "jsonl"` розбирає JSONL-потоки (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента та ідентифікатори сесії, коли вони присутні. +- `output: "text"` розглядає stdout як фінальну відповідь. -Режими входу: +Режими введення: -- `input: "arg"` (типово) передає prompt як останній аргумент CLI. -- `input: "stdin"` надсилає prompt через stdin. -- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin. +- `input: "arg"` (типово) передає промпт як останній аргумент CLI. +- `input: "stdin"` надсилає промпт через stdin. +- Якщо промпт дуже довгий і задано `maxPromptArgChars`, використовується stdin. -## Типові значення (належать Plugin) +## Значення за замовчуванням (керуються Plugin) -Bundled OpenAI Plugin також реєструє типове значення для `codex-cli`: +Вбудований Plugin OpenAI також реєструє типові значення для `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -259,7 +248,7 @@ Bundled OpenAI Plugin також реєструє типове значення - `imageArg: "--image"` - `sessionMode: "existing"` -Bundled Google Plugin також реєструє типове значення для `google-gemini-cli`: +Вбудований Plugin Google також реєструє типові значення для `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -277,25 +266,25 @@ Bundled Google Plugin також реєструє типове значення Примітки щодо JSON Gemini CLI: - Текст відповіді читається з поля JSON `response`. -- Usage повертається до `stats`, коли `usage` відсутній або порожній. -- `stats.cached` нормалізується в `cacheRead` OpenClaw. -- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з +- Usage резервно береться з `stats`, коли `usage` відсутній або порожній. +- `stats.cached` нормалізується в OpenClaw `cacheRead`. +- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів з `stats.input_tokens - stats.cached`. -Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`). +Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`). -## Типові значення, що належать Plugin +## Значення за замовчуванням, що належать Plugin -Типові значення CLI backend тепер є частиною поверхні Plugin: +Типові значення CLI-бекендів тепер є частиною поверхні Plugin: - Plugins реєструють їх через `api.registerCliBackend(...)`. -- `id` backend стає префіксом провайдера в model refs. -- Конфігурація користувача в `agents.defaults.cliBackends.` усе ще перевизначає типове значення Plugin. -- Очищення конфігурації, специфічної для backend, і далі належить Plugin через необов’язковий +- `id` бекенда стає префіксом провайдера в посиланнях моделей. +- Користувацька конфігурація в `agents.defaults.cliBackends.` усе ще перевизначає типове значення Plugin. +- Очищення конфігурації, специфічне для бекенда, залишається у власності Plugin через необов’язковий hook `normalizeConfig`. -Plugins, яким потрібні невеликі сумісні shim-перетворення prompt/повідомлень, можуть оголошувати -двобічні текстові перетворення без заміни провайдера чи CLI backend: +Plugins, яким потрібні невеликі шими сумісності промптів/повідомлень, можуть оголошувати +двоспрямовані текстові трансформації без заміни провайдера або CLI-бекенда: ```typescript api.registerTextTransforms({ @@ -312,52 +301,54 @@ api.registerTextTransforms({ }); ``` -`input` переписує системний prompt і prompt користувача, що передаються до CLI. `output` -переписує потокові assistant deltas і розібраний фінальний текст до того, як OpenClaw обробить -власні control markers і доставку в канали. +`input` переписує системний промпт і користувацький промпт, що передаються до CLI. `output` +переписує стримінгові дельти асистента та розібраний фінальний текст до того, як OpenClaw обробить +власні керівні маркери та доставку в канал. -Для CLI, які надсилають JSONL, сумісний зі stream-json Claude Code, встановіть -`jsonlDialect: "claude-stream-json"` у конфігурації цього backend. +Для CLI, які виводять JSONL, сумісний із Claude Code stream-json, задайте +`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенда. -## Bundle MCP overlays +## Накладки bundle MCP -CLI backends **не** отримують виклики інструментів OpenClaw напряму, але backend може -добровільно ввімкнути згенерований накладний MCP-конфіг через `bundleMcp: true`. +CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може +увімкнути згенеровану накладку конфігурації MCP через `bundleMcp: true`. -Поточна bundled-поведінка: +Поточна вбудована поведінка: -- `claude-cli`: згенерований строгий MCP config file -- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers` +- `claude-cli`: згенерований строгий конфігураційний файл MCP +- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`; згенерований + loopback-сервер OpenClaw позначається режимом схвалення інструментів Codex для кожного сервера, + щоб виклики MCP не зависали через локальні запити на схвалення - `google-gemini-cli`: згенерований файл системних налаштувань Gemini Коли bundle MCP увімкнено, OpenClaw: -- запускає loopback HTTP MCP server, який надає gateway tools процесу CLI -- автентифікує bridge токеном для конкретної сесії (`OPENCLAW_MCP_TOKEN`) +- запускає loopback HTTP MCP-сервер, який надає інструменти шлюзу процесу CLI +- автентифікує міст за допомогою токена для кожної сесії (`OPENCLAW_MCP_TOKEN`) - обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу -- завантажує увімкнені bundle-MCP server для поточного робочого простору -- об’єднує їх з будь-якою наявною MCP config/settings-структурою backend -- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить backend, із розширення-власника +- завантажує увімкнені bundle-MCP сервери для поточного робочого простору +- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенда +- переписує конфігурацію запуску з використанням режиму інтеграції, що належить бекенду, з відповідного extension -Якщо жоден MCP server не ввімкнено, OpenClaw усе одно впроваджує сувору конфігурацію, коли -backend добровільно використовує bundle MCP, щоб фонові запуски залишалися ізольованими. +Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно інжектує строгий конфіг, коли +бекенд використовує bundle MCP, щоб фонові запуски залишалися ізольованими. ## Обмеження -- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у - протокол CLI backend. Backends бачать інструменти gateway лише тоді, коли добровільно ввімкнули +- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у + протокол CLI-бекенда. Бекенди бачать інструменти шлюзу лише тоді, коли використовують `bundleMcp: true`. -- **Streaming залежить від backend.** Деякі backends передають JSONL потоком; інші буферизують - усе до завершення. -- **Структуровані виходи** залежать від формату JSON конкретного CLI. -- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш - структуровано, ніж початковий запуск із `--json`. Сесії OpenClaw при цьому все одно працюють +- **Стримінг залежить від бекенда.** Деякі бекенди стримлять JSONL; інші буферизують + дані до завершення. +- **Структуровані виходи** залежать від JSON-формату CLI. +- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що є менш + структурованим, ніж початковий запуск `--json`. Сесії OpenClaw при цьому все одно працюють нормально. ## Усунення несправностей - **CLI не знайдено**: задайте `command` як повний шлях. -- **Неправильна назва моделі**: використовуйте `modelAliases` для зіставлення `provider/model` → моделі CLI. -- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не має значення +- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI. +- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює `none` (Codex CLI наразі не може відновлюватися з JSON-виводом). -- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів). +- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів). diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 746e8a8ab..0f81e7ed1 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,184 +1,189 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделей/провайдерів - - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live-набори, Docker runners і що покриває кожен тест' + - Додавання регресійних тестів для помилок моделей/провайдерів + - Налагодження поведінки Gateway + агентів +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T20:56:04Z" + generated_at: "2026-04-23T21:58:42Z" model: gpt-5.4 provider: openai - source_hash: 0e0486e188407275915672b0f3955fcd52652cad6b11dbe3195644c539f9179e + source_hash: 3cbd2be379692062162981a8709218dc62f37bb1517d03d561b6da1f7af1f923 source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір -Docker runners. Цей документ — посібник "як ми тестуємо": +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: -- Що покриває кожен набір (і чого він навмисно _не_ покриває). +- Що охоплює кожен набір (і що він навмисно _не_ охоплює). - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресії для реальних проблем із моделями/провайдерами. +- Як додавати регресійні тести для реальних проблем моделей/провайдерів. ## Швидкий старт У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл watch у Vitest: `pnpm test:watch` -- Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Спочатку віддавайте перевагу цільовим запускам, коли ітеруєте над одним збоєм. -- QA-сайт на основі Docker: `pnpm qa:lab:up` +- Швидший локальний запуск усіх наборів на потужній машині: `pnpm test:max` +- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерацій над окремим збоєм спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на базі Docker: `pnpm qa:lab:up` - QA-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете більшої впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Коли налагоджуєте реальних провайдерів/моделі (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + probes для інструментів/image Gateway): `pnpm test:live` -- Тихий запуск одного live-файла: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker-свіп live-моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невеликий probe у стилі читання файла. - Моделі, у чиїх метаданих зазначено підтримку вхідних `image`, також виконують маленький хід із зображенням. - Вимкніть додаткові probes через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Live-набір (моделі + gateway-перевірки tool/image): `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` і ручні + - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, який включає окремі матричні завдання Docker для live-моделей, - розбиті по провайдерах. - - Для цільових повторних запусків CI викликайте `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, що включає окремі matrix-job Docker live-моделей, + розшардовані за провайдером. + - Для цільових повторних запусків у CI викличте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` - плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - виклики для schedule/release. -- Smoke-тест вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім запустіть ізольований + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + scheduled/release-джерел виклику. +- Перевірка вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, а потім ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - для `moonshot/kimi-k2.6`. Переконайтеся, що JSON показує Moonshot/K2.6, а - транскрипт асистента зберігає нормалізоване `usage.cost`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що + transcript помічника зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, краще звужуйте live-тести через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## Runners, специфічні для QA +## Спеціалізовані QA-ранери -Ці команди працюють поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч із основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і -через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щонічно на -`main` і через ручний dispatch із mock parity gate, live Matrix lane і -Convex-керованим live Telegram lane як паралельними завданнями. `OpenClaw Release Checks` -запускає ті самі lanes перед схваленням релізу. +CI запускає QA Lab в окремих workflows. `Parity gate` запускається на відповідних PR і +з ручного виклику з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного виклику з mock parity gate, live Matrix lane та керованим Convex +live Telegram lane як паралельними jobs. `OpenClaw Release Checks` +запускає ті самі lanes перед погодженням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. - - Типово запускає кілька вибраних сценаріїв паралельно з ізольованими - worker-ами Gateway. `qa-channel` типово має concurrency 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість worker-ів, або `--concurrency 1` для старішого послідовного lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без збійного коду завершення. + - Запускає QA-сценарії на базі репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими + gateway-worker'ами. Для `qa-channel` за замовчуванням використовується concurrency 4 + (обмежено кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб + налаштувати кількість worker'ів, або `--concurrency 1` для старого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера AIMock для експериментального - покриття фікстур і mock-протоколів без заміни сценарно-орієнтованого + `aimock` запускає локальний AIMock-сервер провайдера для експериментального + покриття fixture і protocol-mock без заміни сценарійно-орієнтованого lane `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині одноразової Linux VM Multipass. - - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають у гостьову систему підтримувані входи автентифікації QA, які практично пересилати: - ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він є. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через + - Запускає той самий QA-набір усередині одноразової Multipass Linux VM. + - Зберігає ту саму поведінку вибору сценаріїв, що і `qa suite` на хості. + - Повторно використовує ті самі прапорці вибору провайдера/моделі, що і `qa suite`. + - Для live-запусків пересилає підтримувані вхідні дані автентифікації QA, які практично використовувати в гостьовій системі: + ключі провайдерів на основі env, шлях до конфігурації QA live provider та `CODEX_HOME`, + якщо він присутній. + - Каталоги виводу мають залишатися під коренем репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує звичайний QA-звіт + summary, а також логи Multipass у + - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської QA-роботи. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, запускає неінтерактивний onboarding OpenAI з API-ключем, типово налаштовує Telegram, - перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, запускає doctor - і виконує один локальний хід агента проти змоканого endpoint OpenAI. + Docker, виконує неінтерактивний onboarding OpenAI API-key, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, + запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий - lane пакетованого встановлення з Discord. + lane packaged-install з Discord. - `pnpm test:docker:bundled-channel-deps` - - Пакує й встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає bundled channel/plugin через редагування конфігурації. - - Перевіряє, що виявлення під час setup залишає не налаштовані runtime-залежності Plugin відсутніми, перший налаштований запуск Gateway або doctor встановлює runtime-залежності кожного bundled Plugin на вимогу, а другий restart не перевстановлює залежності, які вже було активовано. + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає bundled channel/plugins через + редагування конфігурації. + - Перевіряє, що виявлення налаштування залишає відсутніми runtime-залежності + не налаштованих plugins, що перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного bundled plugin за потреби, і що другий перезапуск не + перевстановлює залежності, які вже були активовані. - Також встановлює відомий старіший npm-baseline, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що - post-update doctor кандидата виправляє runtime-залежності bundled channel без післявстановлювального repair з боку harness. + `openclaw update --tag `, і перевіряє, що doctor кандидата + після оновлення відновлює runtime-залежності bundled channel без + postinstall-відновлення з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. + - Запускає лише локальний AIMock-сервер провайдера для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA-lane Matrix проти одноразового Tuwunel homeserver на базі Docker. - - Цей QA-host наразі лише для repo/dev. Пакетовані встановлення 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 не відкриває спільні прапорці джерел облікових даних, тому що lane локально створює одноразових користувачів. - - Записує QA-звіт Matrix, summary, артефакт observed-events і об’єднаний лог stdout/stderr у `.artifacts/qa-e2e/...`. + - Запускає Matrix live QA lane проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі лише для репозиторію/розробки. Паковані встановлення OpenClaw не постачають + `qa-lab`, тому вони не надають `openclaw qa`. + - Checkout'и репозиторію завантажують bundled runner напряму; окремий крок встановлення plugin не потрібен. + - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній процес QA gateway з реальним Matrix plugin як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює одноразових користувачів. + - Записує Matrix QA-звіт, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA-lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT із env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим chat id Telegram. - - Підтримує `--credential-source convex` для спільних pooled credentials. Типово використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без збійного коду завершення. - - Потребує двох різних ботів в одній приватній групі, при цьому бот SUT має відкривати username Telegram. - - Для стабільного спостереження бот-до-бота увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати бот-трафік у групі. - - Записує QA-звіт Telegram, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту відправлення driver до спостереженої відповіді SUT. + - Запускає Telegram live QA lane проти реальної приватної групи з токенами bot driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. Типово використовуйте режим env, або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані облікові дані з пулу. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо + вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження взаємодії бот-до-бота ввімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати бот-трафік у групі. + - Записує Telegram QA-звіт, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання від driver до спостережуваної відповіді SUT. -Live transport lanes мають один спільний стандартний контракт, щоб нові транспорти не дрейфували: +Live transport-lanes використовують один стандартний контракт, щоб нові transport'и не відхилялися: -`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | -| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія у треді | Ізоляція тредів | Спостереження реакцій | Команда 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 отримує ексклюзивний lease із пулу на базі Convex, підтримує heartbeat -цього lease, поки lane працює, і звільняє lease під час завершення. +QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +для цієї оренди, поки lane працює, і звільняє оренду під час завершення роботи. -Опорний scaffold проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env-змінні: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення з env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback-URL Convex через `http://` лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі має використовувати `https://`. +У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (додати/видалити/перелічити пул) потребують +Адміністративні команди maintainer'а (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні CLI-команди для maintainers: +CLI-хелпери для maintainer'ів: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -188,12 +193,12 @@ pnpm openclaw qa credentials remove --credential-id Використовуйте `--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`) @@ -206,68 +211,68 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для типу Telegram: +Форма payload для виду Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим chat id Telegram. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. +- `groupId` має бути рядком із числовим Telegram chat id. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. ### Додавання каналу до QA -Додавання каналу до markdown-системи QA потребує рівно двох речей: +Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Transport adapter для каналу. +1. Адаптер транспорту для каналу. 2. Набір сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий top-level-командний простір QA, якщо спільний хост `qa-lab` може +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може керувати цим потоком. `qa-lab` володіє спільною механікою хоста: -- коренем команди `openclaw qa` +- кореневим командним простором `openclaw qa` - запуском і завершенням набору -- паралелізмом worker-ів +- паралелізмом worker'ів - записом артефактів - генерацією звітів - виконанням сценаріїв -- alias-ами сумісності для старіших сценаріїв `qa-channel` +- сумісними псевдонімами для старіших сценаріїв `qa-channel` -Runner Plugins володіють транспортним контрактом: +Runner-плагіни володіють транспортним контрактом: -- тим, як `openclaw qa ` монтується під спільним коренем `qa` -- тим, як Gateway налаштовується для цього транспорту -- тим, як перевіряється готовність -- тим, як інжектуються вхідні події -- тим, як спостерігаються вихідні повідомлення -- тим, як відкриваються транскрипти й нормалізований стан транспорту -- тим, як виконуються дії на основі транспорту -- тим, як обробляються скидання або очищення, специфічні для транспорту +- як `openclaw qa ` монтується під спільним коренем `qa` +- як Gateway налаштовується для цього транспорту +- як перевіряється готовність +- як ін’єктуються вхідні події +- як спостерігаються вихідні повідомлення +- як надаються transcript'и та нормалізований стан транспорту +- як виконуються дії на основі транспорту +- як обробляється специфічне для транспорту скидання або очищення -Мінімальний поріг прийняття для нового каналу такий: +Мінімальний поріг прийняття для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Тримайте механіку, специфічну для транспорту, всередині runner Plugin або channel harness. +2. Реалізуйте transport-runner на спільному шві хоста `qa-lab`. +3. Зберігайте специфічну для транспорту механіку всередині runner-plugin або harness каналу. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner Plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; ліниве виконання CLI й runner має залишатися за окремими entrypoint. + Runner-плагіни мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Зберігайте `runtime-api.ts` легким; відкладений CLI і виконання runner мають залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Для нових сценаріїв використовуйте універсальні helper-и сценаріїв. -7. Зберігайте наявні alias-и сумісності робочими, якщо тільки репозиторій не виконує навмисну міграцію. +6. Використовуйте загальні helper для сценаріїв у нових сценаріях. +7. Зберігайте робочими наявні псевдоніми сумісності, якщо в репозиторії не виконується навмисна міграція. -Правило ухвалення рішення суворе: +Правило прийняття рішення суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспортного каналу, залишайте її в runner Plugin або plugin harness цього каналу. -- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один канал, додайте універсальний helper замість channel-specific branch у `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від транспорту одного каналу, зберігайте її в цьому runner-plugin або harness plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальний helper замість специфічної для каналу гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, зберігайте сценарій специфічним для цього транспорту й явно вказуйте це в контракті сценарію. -Бажані назви універсальних helper-ів для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -282,7 +287,7 @@ Runner Plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Alias-и сумісності й далі доступні для наявних сценаріїв, зокрема: +Для наявних сценаріїв залишаються доступними псевдоніми сумісності, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -290,97 +295,100 @@ Alias-и сумісності й далі доступні для наявних - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати універсальні назви helper-ів. -Alias-и сумісності існують, щоб уникнути міграції за один день, а не як модель для +Для нової роботи з каналами слід використовувати загальні назви helper. +Псевдоніми сумісності існують, щоб уникнути міграції одним днем, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Думайте про набори як про “зростання реалізму” (і зростання крихкості/вартості): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: запуски без явного таргетингу використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в конфігурації для окремих проєктів для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті node-тести `ui`, охоплені `vitest.unit.config.ts` +- Конфігурація: ненаправлені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` та дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресії для відомих багів + - In-process integration-тести (gateway auth, routing, tooling, parsing, config) + - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - - Untargeted `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-loop непрактичний. - `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 торкається лише routable source/test-файлів; зміни config/setup і далі використовують fallback до широкого перезапуску root project. - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні typecheck/lint/test lanes. Зміни в публічному SDK Plugin і plugin-contract включають валідацію extensions, тому що extensions залежать від цих core-контрактів. Version bump-и, які зачіпають лише release metadata, запускають цільові перевірки version/config/root-dependency замість повного набору, із guard-ом, що відхиляє зміни package поза top-level-полем version. - Легкі за імпортами unit-тести з agents, commands, plugins, auto-reply helper-ів, `plugin-sdk` та подібних чистих утиліт маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - Вибрані helper-source-файли `plugin-sdk` і `commands` також маплять changed-mode-запуски на явні sibling-тести в цих легких lanes, щоб зміни helper-ів не змушували перезапускати весь важкий набір для цього каталогу. - `auto-reply` має три окремі bucket-и: top-level core helper-и, top-level 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 process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує нативний граф проєктів кореневого `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 торкається лише routable source/test файлів; редагування config/setup все ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це звичайний smart local gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають валідацію extension, оскільки extensions залежать від цих core-контрактів. Зміни версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із guard, який відхиляє зміни package поза полем version верхнього рівня. - Unit-тести з легким import з agents, commands, plugins, helper'ів auto-reply, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - Вибрані helper-файли вихідного коду `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними сусідніми тестами в цих легких lanes, тож редагування helper'ів уникають повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три окремі bucket'и: helper'и верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply осторонь від дешевих тестів status/chunk/token. - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, + - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для меж чистої маршрутизації та нормалізації. - - Підтримуйте вбудовані integration-набори runner-а в здоровому стані: + - Додавайте сфокусовані helper-регресії для чистих меж routing і normalization. + - Підтримуйте інтеграційні набори embedded runner у здоровому стані: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести - не є достатньою заміною для цих integration-шляхів. + - Ці набори перевіряють, що scoped id і поведінка Compaction як і раніше проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише для helper + не є достатньою заміною цих integration-шляхів. - + - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у root-проєктах, e2e і live-конфігураціях. - - Root UI-lane зберігає своє `jsdom`-налаштування й optimizer, але також працює на - спільному неізольованому runner-і. + неізольований runner у root projects, а також у конфігураціях e2e і live. + - Кореневий lane UI зберігає свої `jsdom` setup та optimizer, але теж працює на + спільному неізольованому runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Задайте `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, + щоб зменшити churn компіляції V8 під час великих локальних запусків. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - Pre-commit hook запускає `pnpm check:changed --staged` після staged - formatting/linting, тож core-only коміти не оплачують вартість extension tests, - якщо тільки вони не торкаються публічних контрактів, орієнтованих на extensions. Коміти лише з release - metadata залишаються на цільовому lane - version/config/root-dependency. - - Якщо точний staged-набір змін уже було перевірено - рівними або сильнішими gate-ами, використовуйте - `scripts/committer --fast "" `, щоб пропустити лише повторний запуск changed-scope hook-а. Staged format/lint усе одно запускаються. Згадайте - виконані gate-и у своєму handoff. Це також прийнятно після - повторного запуску ізольованого flaky hook failure, який проходить із вузьким доказом. + formatting/linting, тож коміти лише core не сплачують вартість extension tests, + якщо вони не торкаються публічних контрактів, орієнтованих на extension. Коміти лише + з release metadata залишаються на цільовому + lane version/config/root-dependency. + - Якщо точний staged change set уже було перевірено + gate'ами того ж або вищого рівня, використовуйте + `scripts/committer --fast "" `, щоб пропустити лише повторний запуск + changed-scope hook. Staged format/lint усе ще запускаються. Згадайте + завершені gate'и у своєму handoff. Це також прийнятно після + повторного запуску ізольованого flaky hook failure, який проходить із scoped proof. - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чисто мапляться на менший набір. + чисто відповідають меншому набору. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищою межею worker-ів. - - Локальне автоскейлення worker-ів навмисно консервативне і відступає, - коли load average хоста вже високий, тож кілька паралельних запусків - Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає проєкти/файли конфігурації як - `forceRerunTriggers`, щоб rerun-и в changed-mode залишалися коректними, коли змінюється - wiring тестів. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; задайте `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + лише з вищим лімітом worker'ів. + - Автомасштабування локальних worker'ів навмисно консервативне і відступає, + коли середнє навантаження хоста вже високе, тож кілька одночасних + запусків Vitest типово завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/конфіг-файли як + `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними + при зміні wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітність Vitest щодо тривалості імпорту плюс - вивід розподілу імпортів. - - `pnpm test:perf:imports:changed` звужує той самий вигляд профілювання до - файлів, змінених відносно `origin/main`. + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість import плюс + вивід breakdown import. + - `pnpm test:perf:imports:changed` обмежує той самий вид профілювання + файлами, зміненими від `origin/main`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з нативним шляхом root-project для цього закоміченого diff і друкує wall time плюс max RSS на macOS. + `test:changed` з нативним шляхом root-project для цього зафіксованого diff + і виводить wall time плюс macOS max RSS. - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-profile головного потоку для - старту Vitest/Vite і витрат на transform. - - `pnpm test:perf:profile:runner` записує CPU+heap profile runner-а для + `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для + накладних витрат запуску та transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner для unit-набору з вимкненим файловим паралелізмом. @@ -391,193 +399,193 @@ Alias-и сумісності існують, щоб уникнути мігра - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Проганяє синтетичний churn повідомлень Gateway, пам’яті й великих payload через шлях діагностичних подій - - Запитує `diagnostics.stability` через WS RPC Gateway - - Покриває helper-и збереження пакетів стабільності діагностики - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються нижче бюджету тиску, а глибини черг для кожної сесії повертаються до нуля + - Пропускає синтетичне churn повідомлень gateway, пам’яті та великих payload через діагностичний шлях подій + - Виконує запити до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper'и збереження пакета stability diagnostics + - Підтверджує, що recorder залишається обмеженим, синтетичні RSS-вибірки залишаються в межах бюджету тиску, а глибини черг для кожної сесії повертаються до нуля - Очікування: - Безпечно для CI і без ключів - - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузький lane для подальшої роботи над регресіями stability, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled Plugin у `extensions/` +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` - Типові значення runtime: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість worker-ів (CI: до 2, локально: типово 1). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. + - Використовує Vitest `threads` з `isolate: false`, як і в решті репозиторію. + - Використовує адаптивну кількість worker'ів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості worker-ів (обмежено 16). + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість worker'ів (обмежено 16). - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка Gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing Node і важче мережеве навантаження + - End-to-end-поведінка Gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing вузлів і складніша мережева взаємодія - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### 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-поведінку файлової системи через fs bridge sandbox + - Створює sandbox з тимчасового локального Dockerfile + - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Перевіряє remote-canonical-поведінку файлової системи через fs-bridge sandbox - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працюючого Docker daemon + - Лише за явного ввімкнення; не входить до типового запуску `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=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний двійковий файл CLI або wrapper-script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled Plugin у `extensions/` -- Типово: **увімкнено** через `pnpm test:live` (задає `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - “Чи працює цей провайдер/модель _сьогодні_ з реальними обліковими даними?” - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін форматів провайдерів, особливостей виклику tool, проблем автентифікації та поведінки rate limit - Очікування: - - Не є CI-стабільним за своєю природою (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає ліміти rate limit - - Краще запускати звужені підмножини, а не “все” -- Live-запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали в тимчасовий test-home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Задавайте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: він залишає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap Gateway / шум Bonjour. Задайте `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежно від провайдера): задавайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для конкретного live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби у відповідь на rate limit. -- Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно, що довгі виклики провайдера активні, навіть коли захоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/Gateway передаються одразу під час live-запусків. - - Налаштовуйте heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limit + - Краще запускати звужені підмножини, а не «все» +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixture не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує журнали bootstrap Gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. +- Ротація API-ключів (специфічна для провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях з rate limit. +- Вивід прогресу/Heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, тож тривалі виклики провайдерів помітно активні навіть тоді, коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі у Vitest, щоб рядки прогресу провайдера/Gateway одразу передавалися під час live-запусків. + - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею вибору: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато чого змінили) -- Торкаєтеся мережевої частини Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` -- Налагоджуєте “мій бот не працює” / збої, специфічні для провайдера / виклики інструментів: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) +- Торкаєтеся мережевої взаємодії Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик tool: запускайте звужений `pnpm test:live` -## Live: sweep можливостей Android Node +## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` - Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Ручний/попередньо підготовлений setup (набір не встановлює/не запускає/не pair-ить застосунок). - - Перевірка gateway `node.invoke` команда за командою для вибраного Android Node. + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing застосунку). + - Перевірка `node.invoke` Gateway для вибраного Android Node по кожній команді. - Обов’язкове попереднє налаштування: - - Android-застосунок уже підключено + виконано pairing із Gateway. - - Застосунок тримається на передньому плані. - - Дозволи/згода на capture надані для можливостей, які ви очікуєте побачити як успішні. + - Android-застосунок уже підключений і пройшов pairing з Gateway. + - Застосунок залишається на передньому плані. + - Дозволи/згода на capture надані для можливостей, які мають пройти перевірку. - Необов’язкові перевизначення цілі: - `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) +- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) ## Live: smoke моделей (ключі профілів) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділені на два шари, щоб ми могли ізолювати збої: -- “Direct model” показує, чи провайдер/модель взагалі можуть відповісти з наданим ключем. -- “Gateway smoke” показує, чи працює повний pipeline gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» повідомляє нам, чи може провайдер/модель узагалі відповісти з наданим ключем. +- «Gateway smoke» повідомляє нам, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, політика sandbox тощо). ### Шар 1: Direct model completion (без Gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії там, де це потрібно) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії, де це потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) -- Задайте `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався сфокусованим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір; інакше його буде пропущено, щоб зберегти фокус `pnpm test:live` на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запускати modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, 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.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Sweeps modern/all типово мають curated high-signal cap; задайте `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. + - Прогони modern/all за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: profile store і env fallback-и - - Задайте `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: сховище профілів і резервні значення з env + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює “API провайдера зламане / ключ невалідний” від “pipeline gateway agent зламаний” - - Містить невеликі ізольовані регресії (приклад: reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) + - Відокремлює «API провайдера зламане / ключ недійсний» від «зламаний конвеєр gateway agent» + - Містить малі ізольовані регресії (приклад: reasoning replay OpenAI Responses/Codex Responses + потоки tool-call) -### Шар 2: Gateway + smoke dev-агента (що насправді робить "@openclaw") +### Шар 2: smoke Gateway + dev agent (те, що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process Gateway - - Створити/оновити сесію `agent:dev:*` (override моделі для кожного запуску) - - Ітеруватися по моделях-із-ключами й перевіряти: - - “змістовну” відповідь (без інструментів) - - що реальний виклик інструмента працює (read probe) - - необов’язкові додаткові probes інструментів (exec+read probe) - - що regression-шляхи OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probes (щоб можна було швидко пояснювати збої): - - `read` probe: тест записує файл з nonce у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента `exec`-ом записати nonce у тимчасовий файл, а потім `read`-нути його назад. - - image probe: тест прикріплює згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat `. - - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. + - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітерувати моделі-з-ключами та перевіряти: + - «змістовну» відповідь (без tools) + - що реальний виклик tool працює (read probe) + - необов’язкові додаткові перевірки tool (exec+read probe) + - що шляхи регресій OpenAI (лише tool-call → подальша дія) продовжують працювати +- Подробиці probe (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента виконати `read` для нього та повернути nonce. + - `exec+read` probe: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` прочитати його назад. + - image probe: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - Еталон реалізації: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — псевдонім для modern allowlist - - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити - - Sweeps modern/all для gateway типово мають curated high-signal cap; задайте `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. -- Як вибирати провайдерів (щоб уникати “OpenRouter everything”): + - Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Прогони modern/all для gateway за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникати «усе OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Проби інструментів + зображень у цьому live-тесті завжди увімкнені: - - `read` probe + `exec+read` probe (стрес для інструментів) - - image probe запускається, коли модель оголошує підтримку image input - - Потік (на високому рівні): - - Тест генерує маленький PNG з “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) +- Перевірки tool + image завжди ввімкнені в цьому live-тесті: + - `read` probe + `exec+read` probe (навантаження на tool) + - image probe запускається, коли модель заявляє підтримку вхідних `image` + - Потік (загальний рівень): + - Тест генерує крихітний 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`) - - Embedded agent передає моделі мультимодальне повідомлення користувача - - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки допустимі) + - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Вбудований агент пересилає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете протестувати на своїй машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke backend CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + agent через локальний CLI backend, не торкаючись вашої типової конфігурації. -- Типові значення smoke для конкретного backend-а містяться в `cli-backend.ts` того extension, який ним володіє. +- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний backend CLI, не торкаючись вашої типової конфігурації. +- Типові значення smoke для конкретного backend розташовані у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типовий provider/model: `claude-cli/claude-sonnet-4-6` - - Команда/аргументи/поведінка зображень беруться з метаданих plugin-а CLI backend, якому це належить. + - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image походить із метаданих plugin CLI backend-власника. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"` - `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_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображення, коли задано `IMAGE_ARG`. + - `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`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності в тій самій сесії Claude Sonnet -> Opus (задайте `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -593,7 +601,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для окремих провайдерів: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -604,29 +612,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розміщений у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live-smoke CLI backend усередині Docker-образу репозиторію від імені не-root-користувача `node`. -- Він розв’язує метадані smoke CLI з extension, якому це належить, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований writable prefix у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI backend без збереження Anthropic API-key env vars. Цей lane підписки типово вимикає probes Claude MCP/tool та image, тому що Claude наразі маршрутизує використання сторонніх застосунків через додаткове білінгове використання, а не через звичайні ліміти плану підписки. -- Smoke для live CLI backend тепер перевіряє той самий end-to-end-потік для Claude, Codex і Gemini: текстовий хід, хід із класифікацією зображення, а потім виклик інструмента MCP `cron`, перевірений через CLI Gateway. -- Типовий smoke Claude також patch-ить сесію з Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke для CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний 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-backend без збереження env-змінних Anthropic API-key. Цей lane підписки за замовчуванням вимикає перевірки Claude MCP/tool і image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг додаткового використання, а не через звичайні ліміти плану підписки. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end-потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик tool `cron` MCP, перевірений через CLI Gateway. +- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік ACP conversation-bind із live ACP agent: +- Мета: перевірити реальний потік conversation-bind ACP з live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну conversation message-channel на місці - - надіслати звичайне follow-up у тій самій conversation - - перевірити, що follow-up потрапляє в транскрипт прив’язаної ACP-сесії + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайну подальшу дію в тій самій розмові + - перевірити, що подальша дія потрапляє до transcript прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agents у Docker: `claude,codex,gemini` - - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст conversation у стилі Slack DM - - ACP backend: `acpx` + - ACP-агенти в Docker: `claude,codex,gemini` + - ACP-агент для прямого `pnpm test:live ...`: `claude` + - Синтетичний канал: контекст розмови у стилі Slack DM + - ACP-backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -636,8 +644,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.4` - Примітки: - - Цей lane використовує поверхню Gateway `chat.send` з admin-only полями synthetic originating-route, щоб тести могли додавати контекст message-channel без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів Plugin `acpx` для вибраного ACP harness agent. + - Цей lane використовує поверхню Gateway `chat.send` з синтетичними полями originating-route, доступними лише адміністратору, щоб тести могли приєднати контекст message-channel без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного агента ACP harness. Приклад: @@ -663,35 +671,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker runner розміщений у `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає smoke ACP bind для всіх підтримуваних live 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` у writable npm prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. -- Усередині Docker runner задає `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав env vars провайдера з підвантаженого профілю доступними для дочірнього CLI harness. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити matrix. +- Він використовує `~/.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-змінні провайдера з підвантаженого profile доступними для дочірнього CLI harness. -## Live: smoke harness app-server Codex +## Live: smoke Codex app-server harness -- Мета: перевірити harness Codex, яким володіє Plugin, через звичайний метод Gateway +- Мета: перевірити Codex harness, яким володіє plugin, через звичайний метод Gateway `agent`: - - завантажити вбудований Plugin `codex` + - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `openai/gpt-5.5` з примусовим Codex harness - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що thread app-server - може відновитися - - запустити `/codex status` і `/codex models` через той самий командний - шлях Gateway - - за бажанням запустити два shell-probe з escalated-правами, перевірені Guardian: одну безпечну - команду, яку слід схвалити, і одне фальшиве завантаження секрету, яке має бути - відхилено, щоб агент перепитав + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що app-server + thread може відновитися + - виконати `/codex status` і `/codex models` через той самий командний + шлях gateway + - за бажанням виконати дві перевірки escalated shell, схвалені Guardian: одну нешкідливу + команду, яку має бути схвалено, і одну фальшиву відправку секрету, + яку має бути відхилено, щоб агент поставив уточнювальне запитання - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `openai/gpt-5.5` -- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язковий Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Цей smoke задає `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти, тихо використавши fallback до PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile плюс необов’язкові скопійовані +- Необов’язкова image-перевірка: `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`, щоб зламаний Codex + harness не міг пройти, тихо переключившись назад на PI. +- Автентифікація: `OPENAI_API_KEY` з shell/profile, плюс за бажанням скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -715,22 +723,22 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розміщений у `scripts/test-live-codex-harness-docker.sh`. -- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у writable mounted npm - prefix, переносить дерево сирців, а потім запускає лише live-тест Codex-harness. -- Docker типово вмикає probes image, MCP/tool і Guardian. Задайте +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- + префікс, готує дерево вихідних файлів, а потім запускає лише live-тест Codex-harness. +- Docker за замовчуванням вмикає перевірки image, 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`, як і жива - конфігурація тесту, щоб застарілі alias-и або fallback до PI не могли приховати + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий запуск + для налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live- + тесту, щоб застарілі псевдоніми або fallback на PI не могли приховати регресію Codex harness. ### Рекомендовані live-рецепти -Найшвидші й найменш flaky — вузькі, явні allowlist-и: +Вузькі, явні allowlist — найшвидші та найменш нестабільні: - Одна модель, direct (без Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -738,7 +746,7 @@ pnpm test:docker:live-codex-harness - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів через кілька провайдерів: +- Виклик tool через кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): @@ -748,34 +756,34 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує OAuth-bridge Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає hosted Gemini API від Google через HTTP (автентифікація через API-ключ / profile); це саме те, що більшість користувачів мають на увазі під “Gemini”. - - CLI: OpenClaw викликає локальний binary `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація API-ключем / профілем); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка tools/розбіжність версій). -## Live: матриця моделей (що ми покриваємо) +## Live: matrix моделей (що ми охоплюємо) -Фіксованого “списку моделей CI” немає (live є opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. +Фіксованого «списку моделей CI» немає (live запускається за явним бажанням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний набір smoke (tool calling + image) +### Сучасний набір smoke (виклик tool + image) -Це запуск “поширених моделей”, який ми очікуємо підтримувати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: - OpenAI (не Codex): `openai/gpt-5.5` (необов’язково: `openai/gpt-5.4-mini`) -- OpenAI Codex OAuth: `openai/gpt-5.5` (`openai-codex/gpt-*` лишається застарілим alias-ом) +- OpenAI Codex OAuth: `openai/gpt-5.5` (`openai-codex/gpt-*` залишається застарілим псевдонімом) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `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` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запускати gateway smoke з інструментами + image: +Запуск gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,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,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Базовий рівень: виклик tool (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на кожну сім’ю провайдерів: +Виберіть щонайменше одну модель для кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.5` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -783,46 +791,46 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (приємно мати): +Необов’язкове додаткове покриття (добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яка у вас увімкнена) -- Cerebras: `cerebras/`… (якщо маєте доступ) -- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) +- Cerebras: `cerebras/`… (якщо у вас є доступ) +- LM Studio: `lmstudio/`… (локально; виклик tool залежить від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні gateway +### Агрегатори / альтернативні Gateway -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Інші провайдери, які ви можете включити в live matrix (якщо у вас є облікові дані/конфігурація): - Вбудовані: `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` (кастомні endpoint-и): `minimax` (cloud/API), а також будь-який сумісний з OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (хмара/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати “всі моделі” в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + які ключі доступні. +Порада: не намагайтеся жорстко закодувати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + які ключі доступні. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже “no creds”, налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо live-тест повідомляє «немає облікових даних», налагоджуйте це так само, як ви б налагоджували `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у live-тестах мається на увазі під “profile keys”) +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у live-тестах означає «ключі профілів») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в staged live-home, якщо присутній, але це не основне сховище profile-key) -- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI в тимчасовий test-home; staged live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probes не працювали проти вашого реального workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staging live home, якщо присутній, але це не головне сховище ключів профілю) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий каталог `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staging live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` вилучаються, щоб перевірки не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker runners нижче (вони можуть змонтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live Deepgram (транскрипція аудіо) +## Live Deepgram (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` @@ -833,31 +841,31 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live media workflow ComfyUI +## Live медіапотоку ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у поданні workflow comfy, polling, downloads або реєстрації Plugin + - Корисно після змін у відправленні медіапотоку comfy, polling, завантаженнях або реєстрації plugin -## Live generation зображень +## 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 vars провайдера з вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/profile/model - - Проганяє типові варіанти генерації зображень через спільну runtime-можливість: + - Перелічує кожен зареєстрований plugin провайдера генерації зображень + - Завантажує відсутні env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної auth/profile/model + - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, які покриваються: +- Поточні вбудовані провайдери, які охоплюються: - `fal` - `google` - `minimax` @@ -868,289 +876,293 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth із profile-store і ігнорувати override лише з env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Live generation музики +## Live генерація музики - Тест: `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` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів music-generation - - Наразі покриває Google і MiniMax - - Завантажує env vars провайдера з вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/profile/model + - Перевіряє спільний шлях вбудованого провайдера генерації музики + - Наразі охоплює Google і MiniMax + - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з input лише у вигляді prompt + - `generate` із вхідними даними лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний sweep + - `comfy`: окремий live-файл 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`, щоб примусово використовувати auth із profile-store і ігнорувати override лише з env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Live generation відео +## 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` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів video-generation - - Типово використовує безпечний для релізу smoke-шлях: провайдери без FAL, один text-to-video-запит на провайдера, prompt про омара на одну секунду та ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) - - Типово пропускає FAL, тому що затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити - - Завантажує env vars провайдера з вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/profile/model - - Типово запускає лише `generate` - - Задайте `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені transform-режими, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled`, а вибраний провайдер/модель приймає локальний image input на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled`, а вибраний провайдер/модель приймає локальний video input на основі buffer у спільному sweep - - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільному sweep: - - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` потребує віддаленого URL зображення - - Покриття Vydra, специфічне для провайдера: + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - За замовчуванням використовує безпечний для релізу шлях 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-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної auth/profile/model + - За замовчуванням запускає лише `generate` + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: + - `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 плюс lane `kling`, який типово використовує fixture з віддаленим URL зображення + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує fixture віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільному sweep: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі потребують віддалених reference URL `http(s)` / MP4 - - `google`, тому що поточний спільний lane Gemini/Veo використовує локальний buffer-backed input, а цей шлях не приймається в спільному sweep - - `openai`, тому що поточний спільний lane не гарантує організаційний доступ до video inpaint/remix + - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному прогоні: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені URL-посилання `http(s)` / MP4 + - `google`, тому що поточний спільний lane Gemini/Veo використовує локальний вхід на основі buffer, і цей шлях не приймається у спільному прогоні + - `openai`, тому що поточний спільний lane не гарантує організаційно-специфічний доступ до inpaint/remix відео - Необов’язкове звуження: - `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=""`, щоб включити кожного провайдера в типовий sweep, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції на кожного провайдера для агресивного smoke-запуску -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth із profile-store і ігнорувати override лише з env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового прогону, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера для агресивного smoke-прогону +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Harness для live media +## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env vars провайдерів із `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка heartbeat і quiet-mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики та відео через один нативний entrypoint репозиторію + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які зараз мають придатну auth + - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet-mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker runners (необов’язкові перевірки “працює в Linux”) +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker runners діляться на дві групи: +Ці Docker-ранери поділяються на дві групи: -- Runners для live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл з profile keys усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (і підвантажуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners типово використовують менший smoke cap, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` типово встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово встановлює `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із ключами профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог конфігурації та workspace (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менший smoke-ліміт, щоб повний Docker-прогін залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - явно хочете більший вичерпний скан. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane для live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E container smoke runners, які перевіряють зібраний застосунок. -- Container smoke runners: `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-змінні, коли + вам явно потрібне більше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для smoke-ранерів E2E у контейнерах, які перевіряють зібраний застосунок. +- 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 runners для live-моделей також bind-mount-ять лише потрібні auth-home для CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без зміни auth-store хоста: +Docker-ранери live-моделей також bind-монтують лише потрібні каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх до домашнього каталогу контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище auth на хості: -- Direct models: `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`) -- CLI backend smoke: `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`) +- Direct model: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke CLI-backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke Codex app-server harness: `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`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Wizard 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-ref плюс Telegram за замовчуванням, перевіряє, що ввімкнення Plugin встановлює його runtime-залежності на вимогу, запускає doctor і виконує один змоканий хід агента 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` повертає вбудованих 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 cache між root-, update- і direct-npm-контейнерами. Не-root-перевірки інсталятора зберігають ізольований npm cache, щоб cache-елементи, які належать root, не маскували поведінку користувацького локального встановлення. Задайте `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm під час локальних повторних запусків. -- Мережева частина 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 bridge (попередньо підготовлений Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти Pi bundle MCP (реальний stdio MCP server + smoke allow/deny для вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення Cron/subagent MCP (реальний Gateway + завершення дочірнього stdio MCP після ізольованого запуску cron та одноразових запусків subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення + alias `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-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-ref і типово Telegram, перевіряє, що ввімкнення Plugin встановлює його runtime-залежності за потреби, запускає doctor і виконує один змоканий хід агента 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` повертає вбудованих провайдерів зображень, а не зависає. Щоб повторно використати попередньо зібраний 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`. +- Smoke Docker для інсталятора: `bash scripts/test-install-sh-docker.sh` використовує один кеш npm для своїх контейнерів root, update і direct-npm. Smoke оновлення типово використовує npm `latest` як стабільний baseline перед оновленням до tarball кандидата. Перевірки інсталятора без root зберігають ізольований кеш npm, щоб записи кешу, якими володіє root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- CI Install Smoke пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Мережева взаємодія 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 bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Pi bundle MCP tools (реальний stdio MCP-сервер + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення Cron/subagent MCP (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke встановлення + псевдонім `/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 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. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Звужуйте перевірку runtime-залежностей bundled Plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: +- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності bundled plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker-образ раннера, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вкажіть на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте перевірки runtime-залежностей bundled plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати та повторно використовувати спільний образ built-app: +Щоб вручну попередньо зібрати і повторно використовувати спільний 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 ``` -Перевагу й далі мають suite-specific overrides образів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, якщо вони задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо локально його ще немає. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку package/install, а не shared built-app runtime. +Специфічні для набору перевизначення образів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх встановлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо він ще не локальний. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку пакування/встановлення, а не спільний runtime зібраного застосунку. -Docker runners для live-моделей також bind-mount-ять поточний checkout лише для читання та -переносять його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ компактним, але водночас дозволяє запускати Vitest точно на вашому локальному source/config. -Крок staging пропускає великі локальні кеші та артефакти збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` застосунків або -виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live-проби Gateway не запускали -реальних worker-ів каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе одно запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цього Docker lane. -`test:docker:openwebui` — це smoke вищого рівня для сумісності: він запускає -контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint-ами, -запускає pinned-контейнер Open WebUI проти цього Gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає -реальний chat-запит через proxy Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -образу Open WebUI, а сам Open WebUI — завершення власного cold-start setup. -Цей lane очікує наявність придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — це основний спосіб надати його в Dockerized-запусках. +Docker-ранери live-моделей також bind-монтують поточний checkout лише для читання і +готують його в тимчасовий workdir усередині контейнера. Це зберігає runtime- +образ компактним, водночас дозволяючи запускати Vitest точно на вашому локальному source/config. +Підготовчий крок пропускає великі локальні кеші та результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, і локальні для застосунків каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +машинно-специфічних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +реальні worker'и каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття gateway +live з цього Docker-lane. +`test:docker:openwebui` — це smoke вищого рівня для перевірки сумісності: він запускає +контейнер Gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього Gateway, входить у систему через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний запит чату через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження +образу Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — основний спосіб надати його у Docker-запусках. Успішні запуски виводять невеликий JSON-payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він піднімає підготовлений контейнер -Gateway, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення conversation з маршрутизацією, читання транскриптів, metadata вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і сповіщення у стилі Claude про channel + -permissions через реальний stdio MCP bridge. Перевірка notification безпосередньо -аналізує сирі stdio MCP frames, тож smoke перевіряє те, що bridge реально -надсилає, а не лише те, що випадково показує певний client SDK. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує live-ключа -моделі. Він збирає Docker-образ репозиторію, запускає всередині контейнера реальний stdio MCP probe server, -матеріалізує цей сервер через вбудований runtime Pi bundle MCP, -виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають -інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує live-ключа -моделі. Він запускає підготовлений Gateway з реальним stdio MCP probe server, виконує +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded +контейнер Gateway, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію надсилання назовні та сповіщення у стилі Claude про канал + +дозволи через реальний stdio MCP bridge. Перевірка сповіщень +переглядає сирі stdio MCP-frame безпосередньо, тож smoke перевіряє те, що міст +справді видає, а не лише те, що конкретний client SDK випадково показує. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує live- +ключа моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +всередині контейнера, матеріалізує цей сервер через вбудований runtime Pi bundle +MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. +`test:docker:cron-mcp-cleanup` детермінований і не потребує live-ключа моделі. +Він запускає seeded Gateway з реальним stdio MCP probe server, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. Ручний smoke plain-language thread ACP (не для CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв і налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. -Корисні змінні середовища: +Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`), монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`), монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`), монтується в `/home/node/.profile` і підвантажується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env vars, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові config/workspace-каталоги та без монтування зовнішньої автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_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/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Перевизначення вручну: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться з profile store (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway відкриватиме для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt із перевіркою nonce, який використовується у smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag образу Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, використаний у smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег образу Open WebUI -## Базова перевірка документації +## Перевірка коректності документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor-ів Mintlify, коли вам також потрібна перевірка заголовків усередині сторінок: `pnpm docs:check-links:anchors`. +Запускайте перевірки docs після редагування документації: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. ## Офлайнова регресія (безпечно для CI) -Це регресії “реального pipeline” без реальних провайдерів: +Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `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") +- Виклик tool через Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Evals надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як “evals надійності агента”: +У нас уже є кілька безпечних для CI тестів, які поводяться як «evals надійності агента»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, які перевіряють wiring сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик tool через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end-потоки майстра, які перевіряють wiring сесії та вплив на config (`src/gateway/gateway.test.ts`). -Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Decisioning:** коли Skills перелічені в prompt, чи обирає агент правильний Skill (або уникає нерелевантних)? -- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічені в prompt, чи вибирає агент правильний Skills (або уникає нерелевантних)? +- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Workflow contracts:** багатокрокові сценарії, які перевіряють порядок tool, перенесення історії сесії та межі sandbox. -Майбутні evals спочатку мають залишатися детермінованими: +Майбутні evals насамперед мають залишатися детермінованими: -- Scenario runner з mock-провайдерами для перевірки викликів інструментів + порядку, читання Skill-файлів і wiring сесій. -- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати vs уникати, gating, prompt injection). -- Необов’язкові live-evals (opt-in, захищені env) лише після того, як буде готовий безпечний для CI набір. +- Ранер сценаріїв, що використовує mock-провайдерів для перевірки викликів tool + їхнього порядку, читання файлів skill і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, гейтінг, prompt injection). +- Необов’язкові live evals (лише за явного ввімкнення, керовані env) — тільки після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма Plugin і channel) +## Contract-тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає -своєму інтерфейсному контракту. Вони ітеруються по всіх виявлених Plugin і запускають набір -перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider. +Contract-тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму +контракту інтерфейсу. Вони ітерують усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте contract-команди явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише channel-контракти: `pnpm test:contracts:channels` -- Лише provider-контракти: `pnpm test:contracts:plugins` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` ### Контракти channel -Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма Plugin (id, name, capabilities) -- **setup** - Контракт setup wizard -- **session-binding** - Поведінка прив’язки сесії +- **setup** - Контракт майстра налаштування +- **session-binding** - Поведінка прив’язування сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій каналу -- **threading** - Обробка thread ID -- **directory** - API directory/roster -- **group-policy** - Примусове застосування group policy +- **threading** - Обробка ID thread +- **directory** - API каталогу/списку учасників +- **group-policy** - Забезпечення групової політики -### Контракти status провайдера +### Контракти status provider -Розміщені в `src/plugins/contracts/*.contract.test.ts`. +Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probes status каналу +- **status** - Перевірки status каналу - **registry** - Форма реєстру Plugin ### Контракти provider -Розміщені в `src/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селекція auth +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір/підбір автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin -- **runtime** - Runtime провайдера +- **runtime** - Runtime provider - **shape** - Форма/інтерфейс Plugin -- **wizard** - Setup wizard +- **wizard** - Майстер налаштування ### Коли запускати -- Після змін у export-ах або subpath-ах plugin-sdk -- Після додавання або змін у Plugin channel або provider +- Після зміни export або subpath у plugin-sdk +- Після додавання або зміни channel чи provider Plugin - Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Contract-тести запускаються в CI й не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або захопіть точну трансформацію форми запиту) -- Якщо вона за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Віддавайте перевагу найменшому шару, який ловить баг: - - баг конверсії/повтору запиту провайдера → direct models test - - баг pipeline Gateway для сесій/історії/інструментів → gateway live smoke або безпечний для CI gateway mock test -- Захисна межа для обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не могли бути тихо пропущені. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або зафіксуйте точне перетворення форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики автентифікації), залишайте live-тест вузьким і таким, що вмикається через env-змінні +- Намагайтеся націлюватися на найменший шар, який виявляє помилку: + - помилка перетворення/повторення запиту provider → direct models test + - помилка конвеєра сесії/історії/tool у gateway → gateway live smoke або безпечний для CI gateway mock test +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index b2e04d469..71de6931a 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,30 +1,28 @@ --- read_when: - - Ви хочете використовувати вбудований harness app-server Codex - - Вам потрібні model refs Codex і приклади конфігурації - - Ви хочете вимкнути fallback PI для розгортань лише з Codex -summary: Запуск вбудованих ходів агента OpenClaw через вбудований harness app-server Codex -title: Harness Codex + - Ви хочете використовувати комплектний harness app-server Codex. + - Вам потрібні посилання на модель Codex і приклади конфігурації. + - Ви хочете вимкнути резервне перемикання на PI для розгортань лише з Codex. +summary: Запускайте вбудовані ходи агента OpenClaw через комплектний harness app-server Codex. +title: harness Codex x-i18n: - generated_at: "2026-04-23T21:02:22Z" + generated_at: "2026-04-23T21:58:44Z" model: gpt-5.4 provider: openai - source_hash: 65e96ac709a7996878037da3ffb8903cdd3ad83bb5de75c47ab2f0a08882098c + source_hash: 27b7b662c5eb2002fed8d2c752c4227a46a89d767ac838138327e64df84e4919 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 володів низькорівневою сесією агента: виявленням -моделей, native thread resume, native compaction і виконанням app-server. -OpenClaw усе ще володіє chat channels, файлами сесій, вибором моделі, tools, -approvals, доставкою медіа та видимим дзеркалом transcript. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативним Compaction і виконанням через app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Native-ходи Codex також поважають спільні plugin hooks, тож prompt shim-и, -автоматизація з урахуванням compaction, middleware tools і lifecycle observers -залишаються узгодженими з harness PI: +Нативні ходи Codex також поважають спільні хуки Plugin, тож shim-и промптів, +автоматизація з урахуванням Compaction, middleware інструментів і спостерігачі життєвого циклу залишаються +узгодженими з harness PI: - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -33,59 +31,65 @@ Native-ходи Codex також поважають спільні plugin hooks, - `before_message_write` - `agent_end` -Вбудовані plugins також можуть реєструвати factory розширення app-server Codex для додавання -асинхронного middleware `tool_result`. +Комплектні plugins також можуть реєструвати factory розширення app-server Codex, щоб додавати +асинхронний middleware `tool_result`. -Harness типово вимкнений. Нові конфігурації мають залишати refs моделей OpenAI -канонічними як `openai/gpt-*` і явно примусово задавати -`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли -потрібне native-виконання через app-server. Legacy refs моделей `codex/*` усе ще автоматично вибирають +harness вимкнено за замовчуванням. Нові конфігурації мають зберігати посилання на моделі OpenAI +канонічними як `openai/gpt-*` і явно примусово встановлювати +`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм +потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*` усе ще автоматично вибирають harness для сумісності. ## Виберіть правильний префікс моделі -Тепер OpenClaw зберігає refs моделей OpenAI GPT канонічними як `openai/*`: +Тепер OpenClaw зберігає посилання на моделі OpenAI GPT канонічними як `openai/*`: -| Ref моделі | Шлях runtime | Використовуйте, коли | -| ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ | -| `openai/gpt-5.5` | provider OpenAI через OpenClaw/PI plumbing | Вам потрібен прямий доступ до OpenAI Platform API через `OPENAI_API_KEY`. | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне native-виконання через app-server Codex для вбудованого ходу агента. | +| Посилання на модель | Шлях runtime | Використовуйте, коли | +| --------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.5` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Ви хочете прямий доступ до OpenAI Platform API за допомогою `OPENAI_API_KEY`. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Ви хочете нативне виконання через app-server Codex для вбудованого ходу агента. | -Legacy refs `openai-codex/gpt-*` і `codex/gpt-*` усе ще приймаються як -compatibility alias-и, але нові приклади документації/конфігурації мають використовувати `openai/gpt-*`. +Застарілі посилання `openai-codex/gpt-*` і `codex/gpt-*` як і раніше приймаються як +аліаси сумісності, але нові приклади в документації/конфігурації мають використовувати `openai/gpt-*`. -Вибір harness — це не механізм керування live session. Коли виконується вбудований хід, -OpenClaw записує id вибраного harness у цій сесії й продовжує використовувати його для -наступних ходів у тому самому id сесії. Змінюйте конфігурацію `embeddedHarness` або +Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо +вибір виглядає неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness` +і перегляньте структурований запис gateway `agent harness selected`. Він +містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і, +у режимі `auto`, результат підтримки кожного кандидата Plugin. + +Вибір harness не є елементом керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його для +наступних ходів у тому самому ідентифікаторі сесії. Змінюйте конфігурацію `embeddedHarness` або `OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; -використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням уже наявної -розмови між PI і Codex. Це запобігає повторному програванню одного transcript через -дві несумісні native session systems. +використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної +розмови між PI і Codex. Це дозволяє уникнути відтворення одного транскрипту через +дві несумісні нативні системи сесій. -Legacy sessions, створені до появи pins harness, вважаються прив’язаними до PI, щойно -мають історію transcript. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на +Застарілі сесії, створені до закріплення harness, вважаються закріпленими за PI, щойно в них +з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на Codex після зміни конфігурації. -`/status` показує ефективний non-PI harness поруч із `Fast`, наприклад -`Fast · codex`. Типовий harness PI лишається `Runner: pi (embedded)` і -не додає окремий badge harness. +`/status` показує ефективний не-PI harness поруч із `Fast`, наприклад +`Fast · codex`. harness PI за замовчуванням і далі відображається як `Runner: pi (embedded)` і +не додає окремого бейджа harness. ## Вимоги -- OpenClaw із доступним вбудованим Plugin `codex`. -- Codex app-server `0.118.0` або новіший. -- Auth Codex, доступна для процесу app-server. +- OpenClaw із доступним комплектним Plugin `codex`. +- app-server Codex `0.118.0` або новіший. +- Автентифікація Codex, доступна процесу app-server. -Plugin блокує старіші або безверсійні handshakes app-server. Це тримає -OpenClaw у межах тієї поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або безверсійні handshake app-server. Це гарантує, що +OpenClaw працює з поверхнею протоколу, на якій його було протестовано. -Для live- і Docker smoke tests auth зазвичай надходить із `OPENAI_API_KEY`, плюс -необов’язкові файли Codex CLI, такі як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте той самий auth material, який використовує ваш локальний Codex app-server. +Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також +необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, що й ваш локальний app-server Codex. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово задайте harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово встановіть harness `codex`: ```json5 { @@ -108,7 +112,7 @@ OpenClaw у межах тієї поверхні протоколу, з якою } ``` -Якщо ваша конфігурація використовує `plugins.allow`, включіть туди й `codex`: +Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -123,15 +127,15 @@ OpenClaw у межах тієї поверхні протоколу, з якою } ``` -Legacy-конфігурації, які задають `agents.defaults.model` або модель агента як -`codex/`, усе ще автоматично вмикають вбудований Plugin `codex`. Нові конфігурації мають -надавати перевагу `openai/` плюс явному запису `embeddedHarness` вище. +Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента як +`codex/`, як і раніше автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають +надавати перевагу `openai/` разом із явним записом `embeddedHarness`, наведеним вище. -## Додати Codex без заміни інших моделей +## Додайте Codex, не замінюючи інші моделі -Залишайте `runtime: "auto"`, коли хочете, щоб legacy refs `codex/*` вибирали Codex, а -PI — усе інше. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для -агентів, які мають використовувати harness. +Зберігайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а +PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для +агентів, які мають використовувати цей harness. ```json5 { @@ -161,15 +165,15 @@ PI — усе інше. Для нових конфігурацій надава } ``` -За такої форми: +За такої структури: - `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації. -- `/model opus` використовує шлях provider-а Anthropic. -- Якщо вибрано non-Codex model, PI лишається harness сумісності. +- `/model opus` використовує шлях провайдера Anthropic. +- Якщо вибрано не-Codex модель, PI залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть fallback PI, коли потрібно довести, що кожен вбудований хід агента використовує +Вимкніть fallback на PI, коли вам потрібно гарантувати, що кожен вбудований хід агента використовує harness Codex: ```json5 @@ -186,7 +190,7 @@ harness Codex: } ``` -Перевизначення через середовище: +Перевизначення через змінні середовища: ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -194,13 +198,13 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли fallback вимкнено, OpenClaw одразу завершується з помилкою, якщо Plugin Codex вимкнено, -app-server занадто старий або app-server не вдається запустити. +Якщо fallback вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено, +app-server занадто старий або app-server не може запуститися. ## Codex для окремого агента -Ви можете зробити одного агента Codex-only, тоді як типовий агент зберігатиме звичайне -автовибрання: +Ви можете зробити один агент лише для Codex, тоді як агент за замовчуванням зберігатиме звичайний +автовибір: ```json5 { @@ -231,15 +235,15 @@ app-server занадто старий або app-server не вдається } ``` -Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює свіжу +Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову сесію OpenClaw, а harness Codex створює або відновлює свій sidecar app-server -thread за потреби. `/reset` очищає прив’язку сесії OpenClaw до цього thread -і дозволяє наступному ходу знову розв’язати harness з поточної конфігурації. +потік за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку +і дозволяє наступному ходу знову визначити harness із поточної конфігурації. ## Виявлення моделей -Типово Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення не вдається або спливає timeout, він використовує вбудований fallback catalog для: +За замовчуванням Plugin Codex запитує в app-server доступні моделі. Якщо +виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -265,8 +269,8 @@ thread за потреби. `/reset` очищає прив’язку сесії } ``` -Вимкніть виявлення, якщо хочете, щоб startup не виконував probe Codex і лишався на -fallback catalog: +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався +резервний каталог: ```json5 { @@ -287,19 +291,19 @@ fallback catalog: ## Підключення 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 і network tools без -зупинки на native approval prompts, на які нікому відповідати. +`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується +для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без +зупинки на нативних запитах на погодження, на які нікому відповідати. -Щоб увімкнути перевірювані Guardian approvals у Codex, задайте `appServer.mode: +Щоб увімкнути погодження Codex, які перевіряє Guardian, встановіть `appServer.mode: "guardian"`: ```json5 @@ -320,9 +324,9 @@ codex app-server --listen stdio:// } ``` -Guardian — це native reviewer approvals у Codex. Коли Codex просить вийти із sandbox, писати поза workspace або додати дозволи на кшталт доступу до мережі, Codex спрямовує цей approval request до reviewer subagent-а, а не до prompt людини. Reviewer застосовує risk framework Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але все ще потрібно, щоб unattended agents могли просуватися далі. +Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти з sandbox, записати за межі workspace або додати дозволи, як-от доступ до мережі, Codex надсилає цей запит на погодження рецензенту-підагенту замість запиту людині. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібні суворіші запобіжники, ніж у режимі YOLO, але ви все одно хочете, щоб агенти без нагляду могли просуватися далі. -Preset `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики все одно перевизначають `mode`, тому в розширених розгортаннях можна змішувати preset з явними виборами. +Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, перевизначають `mode`, тож у розширених розгортаннях можна поєднувати цей пресет із явними параметрами. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -348,22 +352,22 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`, Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` породжує Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Executable для транспорту stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL WebSocket app-server. | -| `authToken` | не задано | Bearer token для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Timeout для викликів control-plane app-server. | -| `mode` | `"yolo"` | Preset для YOLO або виконання з approvals, перевірюваними Guardian. | -| `approvalPolicy` | `"never"` | Native approval policy Codex, що надсилається під час start/resume/turn thread. | -| `sandbox` | `"danger-full-access"` | Native sandbox mode Codex, що надсилається під час start/resume. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб Codex Guardian перевіряв prompts. | -| `serviceTier` | не задано | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Невалідні legacy values ігноруються. | +| Поле | За замовчуванням | Значення | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не задано | URL app-server WebSocket. | +| `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"`, щоб Guardian Codex перевіряв запити. | +| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Старіші змінні середовища все ще працюють як fallback для локального тестування, коли +Старіші змінні середовища, як і раніше, працюють як fallback для локального тестування, коли відповідне поле конфігурації не задано: - `OPENCLAW_CODEX_APP_SERVER_BIN` @@ -372,15 +376,15 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`, - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Використовуйте -`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` натомість, або `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація -є кращою для повторюваних розгортань, оскільки зберігає поведінку plugin у тому самому -перевіреному файлі, що й решта налаштування harness Codex. +є кращим варіантом для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у +тому самому перевіреному файлі, що й решта налаштування harness Codex. ## Поширені рецепти -Локальний Codex з типовим транспортом stdio: +Локальний Codex із транспортом stdio за замовчуванням: ```json5 { @@ -394,7 +398,7 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`, } ``` -Перевірка harness лише з Codex, з вимкненим fallback PI: +Перевірка harness лише для Codex із вимкненим fallback на PI: ```json5 { @@ -411,7 +415,7 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`, } ``` -Approvals Codex, перевірювані Guardian: +Погодження Codex, перевірені Guardian: ```json5 { @@ -433,7 +437,7 @@ Approvals Codex, перевірювані Guardian: } ``` -Віддалений app-server з явними headers: +Віддалений app-server із явними заголовками: ```json5 { @@ -457,86 +461,91 @@ Approvals Codex, перевірювані Guardian: ``` Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw прив’язано -до наявного thread Codex, наступний хід знову надсилає до -app-server поточні вибрані OpenClaw модель OpenAI, provider, approval policy, sandbox і service tier. -Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до thread, але просить Codex продовжити з новою вибраною моделлю. +до наявного потоку Codex, наступний хід знову надсилає до +app-server поточну вибрану модель OpenAI, провайдера, політику погодження, sandbox і service tier. +Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку +до потоку, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex -Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона -загальна й працює на будь-якому каналі, який підтримує текстові команди OpenClaw. +Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є +універсальною та працює в будь-якому каналі, який підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує live-підключення до app-server, моделі, обліковий запис, rate limits, MCP servers і skills. -- `/codex models` показує live-моделі app-server Codex. -- `/codex threads [filter]` показує список недавніх thread-ів Codex. -- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного thread Codex. -- `/codex compact` просить app-server Codex виконати compaction для прив’язаного thread. -- `/codex review` запускає native review Codex для прив’язаного thread. -- `/codex account` показує стан облікового запису й rate-limit. -- `/codex mcp` показує стан MCP server app-server Codex. +- `/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 account` показує стан облікового запису та лімітів швидкості. +- `/codex mcp` показує стан MCP-сервера app-server Codex. - `/codex skills` показує skills app-server Codex. -`/codex resume` записує той самий файл прив’язки sidecar, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновить цей thread Codex, передасть -поточну вибрану в OpenClaw модель `codex/*` в app-server і збереже -розширену історію ввімкненою. +`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw до app-server і зберігає +увімкнену розширену історію. -Поверхня команд вимагає Codex app-server `0.118.0` або новішого. Окремі -control-методи показуються як `unsupported by this Codex app-server`, якщо -майбутній або custom app-server не відкриває цей JSON-RPC method. +Поверхня команд вимагає app-server Codex `0.118.0` або новішої версії. Окремі +методи керування повідомляються як `unsupported by this Codex app-server`, якщо +майбутній або кастомний app-server не надає цей метод JSON-RPC. -## Tools, media і Compaction +## Інструменти, медіа та Compaction -Harness Codex змінює лише низькорівневий виконавець вбудованого агента. +harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw і далі будує список tools і отримує динамічні результати tools від -harness. Текст, зображення, відео, музика, TTS, approvals і вивід messaging-tool -продовжують проходити звичайним шляхом доставки OpenClaw. +OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями +і далі проходять через звичайний шлях доставки OpenClaw. -Elicitation approval для інструментів MCP Codex маршрутизується через потік -approval plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`; інші elicitation- і free-form input-запити все ще завершуються в закритий спосіб. +Запити на погодження інструментів MCP Codex маршрутизуються через потік +погодження Plugin в OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`; інші запити на підтвердження та запити на довільне введення, як і раніше, завершуються +безпечною відмовою. -Коли вибрана модель використовує harness Codex, native compaction thread -делегується app-server Codex. OpenClaw зберігає transcript mirror для історії каналів, -пошуку, `/new`, `/reset` і майбутнього перемикання моделей або harness. Mirror -містить prompt користувача, фінальний текст асистента та полегшені записи reasoning або plan від Codex, коли app-server їх генерує. Наразі OpenClaw записує лише сигнали початку й завершення native compaction. Він ще не показує -людинозрозуміле зведення compaction або придатний до аудиту список того, які записи Codex -залишив після compaction. +Коли вибрана модель використовує harness Codex, нативний Compaction потоку +делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, +пошуку, `/new`, `/reset` і майбутнього перемикання моделей або harness. Дзеркало +включає промпт користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли їх генерує app-server. Наразі OpenClaw записує лише сигнали початку та завершення нативного Compaction. Він поки що не показує +людинозрозумілий підсумок Compaction або перевірний список того, які записи Codex +зберіг після Compaction. -Генерація медіа не потребує PI. Зображення, відео, музика, PDF, TTS і розуміння медіа -і далі використовують відповідні налаштування provider/model, як-от +Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа, як і раніше, використовує відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, -задайте ref моделі `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`. +виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або +застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не взяв на себе цей запуск, -OpenClaw може використати PI як backend сумісності. Задайте -`embeddedHarness.runtime: "codex"`, щоб примусово вибирати Codex під час тестування, або -`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден harness plugin не підходить. Щойно вибрано app-server Codex, його збої показуються напряму без додаткової -конфігурації fallback. +**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не заявляє про запуск, +OpenClaw може використовувати PI як backend сумісності. Установіть +`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або +`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли не підходить жоден harness Plugin. Щойно +буде вибрано app-server Codex, його помилки відображатимуться безпосередньо без додаткового +налаштування fallback. -**App-server відхиляється:** оновіть Codex так, щоб handshake app-server +**app-server відхиляється:** оновіть Codex, щоб handshake app-server повідомляв версію `0.118.0` або новішу. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. **Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і що віддалений app-server говорить тією самою версією протоколу app-server Codex. +і те, що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Non-Codex model використовує PI:** це очікувано. Harness Codex бере на себе -лише refs моделей `codex/*`. +**Не-Codex модель використовує PI:** це очікувана поведінка, якщо ви не примусово встановили +`embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні +`openai/gpt-*` та посилання інших провайдерів залишаються на своєму стандартному шляху провайдера. ## Пов’язане -- [Agent Harness Plugins](/uk/plugins/sdk-agent-harness) -- [Model Providers](/uk/concepts/model-providers) -- [Configuration Reference](/uk/gateway/configuration-reference) -- [Testing](/uk/help/testing#live-codex-app-server-harness-smoke) +- [Plugins harness агента](/uk/plugins/sdk-agent-harness) +- [Провайдери моделей](/uk/concepts/model-providers) +- [Довідник із конфігурації](/uk/gateway/configuration-reference) +- [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index b2dced893..a892a8354 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,56 +1,51 @@ --- read_when: - - Ви змінюєте вбудований runtime агента або реєстр harness - - Ви реєструєте agent harness із вбудованого або довіреного Plugin - - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із provider моделей + - Ви змінюєте вбудоване середовище виконання агента або реєстр каркаса агента + - Ви реєструєте каркас агента з комплектного або довіреного плагіна + - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневий вбудований виконавець агента -title: Plugins для agent harness +summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента +title: Плагіни каркаса агента x-i18n: - generated_at: "2026-04-23T21:02:42Z" + generated_at: "2026-04-23T21:58:46Z" model: gpt-5.4 provider: openai - source_hash: 69d0c4febbc0f0397d4fc8a212039a2d78764798b82f48e600daf68626826904 + source_hash: 966d685627b11651fbd0c7fe00a7e3e412c14b39511845ecfcdc4366fa9f8767 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -Agent harness — це низькорівневий виконавець одного підготовленого ходу агента OpenClaw. Це не provider моделі, не канал і не реєстр tools. +**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт -усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний -вбудований runner. +Використовуйте цю поверхню лише для комплектних або довірених native-плагінів. Контракт усе ще є експериментальним, тому що типи параметрів навмисно віддзеркалюють поточний вбудований раннер. -## Коли використовувати harness +## Коли використовувати каркас -Реєструйте agent harness, коли сімейство моделей має власний нативний runtime -сесії, а звичайний транспорт provider OpenClaw є неправильною абстракцією. +Реєструйте каркас агента, коли сімейство моделей має власне native-середовище виконання сесії, а звичайний транспорт постачальника OpenClaw є неправильною абстракцією. Приклади: -- нативний сервер coding-agent, який володіє threads і Compaction -- локальний CLI або daemon, який має передавати нативні події plan/reasoning/tool через streaming -- runtime моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw +- native-сервер агента для кодування, який керує потоками та Compaction +- локальний CLI або демон, який має транслювати native-події плану/міркування/інструментів +- середовище виконання моделі, якому потрібен власний resume id на додачу до стенограми сесії OpenClaw -**Не** реєструйте harness лише для додавання нового LLM API. Для звичайних HTTP- або -WebSocket-API моделей створюйте [provider plugin](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP- або WebSocket-API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). -## Чим і далі володіє core +## Чим усе ще керує ядро -До вибору harness OpenClaw уже розв’язав: +Перш ніж буде вибрано каркас, OpenClaw уже визначив: -- provider і model -- стан auth runtime -- рівень thinking і бюджет контексту -- транскрипт/файл сесії OpenClaw -- робочий простір, sandbox і політику tools -- callback для відповідей каналу й callback для streaming -- fallback моделі та політику перемикання live-моделі +- постачальника та модель +- стан автентифікації середовища виконання +- рівень міркування та бюджет контексту +- файл стенограми/сесії OpenClaw +- робочий простір, sandbox і політику інструментів +- зворотні виклики відповіді каналу та зворотні виклики потокової передачі +- політику резервного переходу моделі та перемикання live-моделей -Такий розподіл є навмисним. Harness виконує підготовлену спробу; він не вибирає -providers, не замінює доставку каналом і не перемикає моделі мовчки. +Цей розподіл навмисний. Каркас виконує підготовлену спробу; він не вибирає постачальників, не замінює доставку каналу і не перемикає моделі непомітно. -## Реєстрація harness +## Зареєструвати каркас **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -88,96 +83,54 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає harness після розв’язання provider/model: +OpenClaw вибирає каркас після визначення постачальника/моделі: -1. Зафіксований id harness у наявній сесії має пріоритет, щоб зміни config/env - не перемикали цей транскрипт гарячим способом на інший runtime. -2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстрований harness з цим id для - сесій, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований harness PI. -4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness, чи підтримують вони - розв’язаний provider/model. -5. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо fallback PI - не вимкнено. +1. Записаний id каркаса наявної сесії має пріоритет, щоб зміни config/env не перемикали цю стенограму на інше середовище виконання «на гарячу». +2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстрований каркас із цим id для сесій, які ще не закріплені. +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований каркас PI. +4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані каркаси, чи підтримують вони визначеного постачальника/модель. +5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено. -Збої harness Plugin проявляються як збої запуску. У режимі `auto` fallback PI -використовується лише тоді, коли жоден зареєстрований Plugin harness не підтримує розв’язаний -provider/model. Щойно Plugin harness узяв run, OpenClaw не -програє той самий хід через PI, оскільки це може змінити семантику auth/runtime -або дублювати побічні ефекти. +Збої каркаса плагіна відображаються як збої виконання. У режимі `auto` резервний перехід на PI використовується лише тоді, коли жоден зареєстрований каркас плагіна не підтримує визначеного постачальника/модель. Щойно каркас плагіна взяв на себе виконання, OpenClaw не відтворює той самий хід через PI, тому що це може змінити семантику автентифікації/середовища виконання або спричинити дублювання побічних ефектів. -Вибраний id harness зберігається разом з id сесії після вбудованого запуску. -Застарілі сесії, створені до закріплення harness, трактуються як закріплені за PI, щойно -в них з’являється історія транскрипту. Використовуйте нову/скинуту сесію під час перемикання між PI і -нативним Plugin harness. `/status` показує нетипові id harness, такі як `codex`, -поруч із `Fast`; PI не показується, бо це типовий сумісний шлях. +Вибраний id каркаса зберігається разом з id сесії після вбудованого виконання. Застарілі сесії, створені до закріплення каркасів, вважаються закріпленими за PI, щойно в них з’являється історія стенограми. Використовуйте нову/скинуту сесію під час перемикання між PI та native-каркасом плагіна. `/status` показує нестандартні id каркасів, такі як `codex`, поруч із `Fast`; PI приховано, тому що це стандартний шлях сумісності. Якщо вибраний каркас виглядає неочікуваним, увімкніть журналювання налагодження `agents/harness` і перевірте структурований запис шлюзу `agent harness selected`. Він містить id вибраного каркаса, причину вибору, політику runtime/fallback і, у режимі `auto`, результат підтримки для кожного кандидата-плагіна. -Вбудований Plugin Codex реєструє `codex` як свій id harness. Core трактує це -як звичайний id harness Plugin; псевдоніми, специфічні для Codex, мають належати в Plugin -або в конфігурацію оператора, а не в спільний selector runtime. +Комплектний плагін Codex реєструє `codex` як свій id каркаса. Ядро розглядає його як звичайний id каркаса плагіна; специфічні для Codex псевдоніми мають належати плагіну або config оператора, а не спільному селектору середовища виконання. -## Поєднання provider і harness +## Поєднання постачальника й каркаса -Більшість harness також мають реєструвати provider. Provider робить refs моделей, -стан auth, метадані моделі та вибір `/model` видимими для решти -OpenClaw. Потім harness заявляє цей provider у `supports(...)`. +Більшість каркасів також мають реєструвати постачальника. Постачальник робить посилання на моделі, статус автентифікації, метадані моделі та вибір `/model` видимими для решти OpenClaw. Потім каркас заявляє підтримку цього постачальника в `supports(...)`. -Вбудований Plugin Codex дотримується цього шаблону: +Комплектний плагін Codex дотримується цього шаблону: -- 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 +- id постачальника: `codex` +- користувацькі посилання на моделі: канонічне `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; застарілі посилання `codex/gpt-*` усе ще приймаються для сумісності +- id каркаса: `codex` +- автентифікація: синтетична доступність постачальника, оскільки каркас Codex керує native-входом/сесією Codex +- запит до app-server: OpenClaw надсилає в Codex лише bare id моделі та дозволяє каркасу працювати з native-протоколом app-server -Plugin Codex є додатковим. Звичайні refs `openai/gpt-*` і далі використовують -нормальний шлях provider OpenClaw, якщо ви примусово не задасте harness Codex через -`embeddedHarness.runtime: "codex"`. Старіші refs `codex/gpt-*` і далі вибирають -provider і harness Codex для сумісності. +Плагін Codex є адитивним. Звичайні посилання `openai/gpt-*` і далі використовують стандартний шлях постачальника OpenClaw, якщо ви не примусите використання каркаса Codex через `embeddedHarness.runtime: "codex"`. Старіші посилання `codex/gpt-*` усе ще вибирають постачальника і каркас Codex для сумісності. -Налаштування для оператора, приклади префіксів моделей і конфігурації лише для Codex див. -у [Codex Harness](/uk/plugins/codex-harness). +Щоб дізнатися про налаштування для операторів, приклади префіксів моделей і config лише для Codex, див. [Каркас Codex](/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` або новішої версії. Плагін Codex перевіряє initialize-handshake app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. -### Middleware результатів tools для Codex app-server +### Middleware результатів інструментів Codex app-server -Вбудовані Plugin також можуть підключати middleware `tool_result`, специфічне для Codex app-server, через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній -маніфест оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`. -Це seam довіреного Plugin для асинхронних перетворень результатів tools, які потрібно -виконувати всередині нативного harness Codex до того, як вивід tool буде спроєктовано назад -у транскрипт OpenClaw. +Комплектні плагіни також можуть приєднувати middleware `tool_result`, специфічне для Codex app-server, через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній маніфест оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`. +Це seam довіреного плагіна для асинхронних перетворень результатів інструментів, які мають виконуватися всередині native-каркаса Codex, перш ніж вивід інструмента буде спроєктовано назад у стенограму OpenClaw. -### Режим нативного harness Codex +### Режим native-каркаса Codex -Вбудований harness `codex` — це нативний режим Codex для вбудованих ходів -агента OpenClaw. Спочатку ввімкніть вбудований Plugin `codex`, а також включіть `codex` у -`plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Нові конфігурації мають -використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Застарілі -refs моделей `openai-codex/*` і `codex/*` і далі залишаються псевдонімами сумісності. +Комплектний каркас `codex` — це native-режим Codex для вбудованих ходів агента OpenClaw. Спочатку ввімкніть комплектний плагін `codex` і додайте `codex` до `plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Нові config мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Застарілі посилання на моделі `openai-codex/*` і `codex/*` залишаються псевдонімами сумісності. -Коли цей режим працює, Codex володіє нативним thread id, поведінкою resume, -Compaction і виконанням app-server. OpenClaw і далі володіє каналом чату, -видимим дзеркалом транскрипту, політикою tools, approvals, доставкою медіа та -вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із -`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях -Codex app-server може взяти run. Ця конфігурація є лише запобіжником вибору: -збої Codex app-server вже напряму завершуються помилкою без повторної спроби через PI. +Коли цей режим працює, Codex керує native-id потоку, поведінкою відновлення, Compaction і виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом стенограми, політикою інструментів, підтвердженнями, доставкою медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що виконання може взяти на себе лише шлях Codex app-server. Цей config є лише запобіжником вибору: збої Codex app-server уже напряму спричиняють збій замість повторної спроби через PI. -## Вимкнення fallback PI +## Вимкнути резервний перехід на PI -Типово OpenClaw запускає вбудованих агентів з `agents.defaults.embeddedHarness`, -установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані Plugin -harness можуть узяти пару provider/model. Якщо жоден не підходить, OpenClaw повертається до PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси плагінів можуть заявляти підтримку пари постачальник/модель. Якщо жоден не підходить, OpenClaw виконує резервний перехід на PI. -Установіть `fallback: "none"`, якщо вам потрібно, щоб відсутність вибору Plugin harness -призводила до помилки замість використання PI. Збої вже вибраного Plugin harness і так завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору каркаса плагіна спричиняла збій замість використання PI. Збої вибраного каркаса плагіна вже спричиняють жорсткий збій. Це не блокує явне `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. Для вбудованих запусків лише з Codex: @@ -195,7 +148,7 @@ harness можуть узяти пару provider/model. Якщо жоден н } ``` -Якщо ви хочете, щоб будь-який зареєстрований Plugin harness міг брати відповідні моделі, але не хочете, щоб OpenClaw мовчки повертався до PI, залиште `runtime: "auto"` і вимкніть fallback: +Якщо ви хочете, щоб будь-який зареєстрований каркас плагіна міг заявити підтримку відповідних моделей, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть fallback: ```json { @@ -210,7 +163,7 @@ harness можуть узяти пару provider/model. Якщо жоден н } ``` -Перевизначення для конкретного агента використовують ту саму форму: +Перевизначення для окремих агентів використовують ту саму форму: ```json { @@ -235,9 +188,7 @@ harness можуть узяти пару provider/model. Якщо жоден н } ``` -`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback PI із -середовища. +`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI із середовища. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -245,53 +196,40 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли fallback вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний harness не -зареєстрований, не підтримує розв’язаний provider/model або завершується помилкою до -створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і -для live-тестів, які мають довести, що шлях Codex app-server справді використовується. +Коли fallback вимкнено, сесія завершується збоєм рано, якщо запитаний каркас не зареєстровано, не підтримує визначеного постачальника/модель або завершується збоєм до створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що фактично використовується шлях Codex app-server. -Цей параметр керує лише вбудованим agent harness. Він не вимикає -маршрутизацію моделей, специфічну для image, video, music, TTS, PDF або інших provider. +Це налаштування керує лише каркасом вбудованого агента. Воно не вимикає маршрутизацію моделей, специфічну для постачальника, для зображень, відео, музики, TTS, PDF або інших типів. -## Нативні сесії та дзеркало транскрипту +## Native-сесії та дзеркало стенограми -Harness може зберігати нативний session id, thread id або токен resume на стороні daemon. -Тримайте це прив’язування явно пов’язаним із сесією OpenClaw і продовжуйте -дзеркалити видимий для користувача вивід assistant/tool у транскрипт OpenClaw. +Каркас може зберігати native-id сесії, id потоку або токен відновлення на боці демона. Явно пов’язуйте цей зв’язок із сесією OpenClaw і продовжуйте дзеркалити видимий для користувача вивід асистента/інструментів у стенограму OpenClaw. -Транскрипт OpenClaw залишається шаром сумісності для: +Стенограма OpenClaw залишається шаром сумісності для: -- видимої в каналі історії сесій -- пошуку й індексації транскриптів -- повернення до вбудованого harness PI на пізнішому ході +- видимої в каналі історії сесії +- пошуку та індексації стенограми +- перемикання назад на вбудований каркас PI у пізнішому ході - загальної поведінки `/new`, `/reset` і видалення сесії -Якщо ваш harness зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг -очистити її, коли пов’язану сесію OpenClaw буде скинуто. +Якщо ваш каркас зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли відповідну сесію OpenClaw буде скинуто. -## Результати tools і медіа +## Результати інструментів і медіа -Core будує список tools OpenClaw і передає його в підготовлену спробу. -Коли harness виконує динамічний виклик tool, повертайте результат tool назад через -форму результату harness, а не надсилайте медіа каналу самостійно. +Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. +Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату каркаса замість того, щоб самостійно надсилати медіа в канал. -Це зберігає text, image, video, music, TTS, approval і виводи tools обміну повідомленнями -в тому самому шляху доставки, що й запуски, підкріплені PI. +Це зберігає текст, зображення, відео, музику, TTS, підтвердження та виводи інструментів обміну повідомленнями на тому самому шляху доставки, що й у запусків на базі PI. ## Поточні обмеження -- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів і далі - містять назви `Pi` для сумісності. -- Встановлення сторонніх harness усе ще експериментальне. Надавайте перевагу provider plugins, - доки вам не знадобиться нативний runtime сесії. -- Перемикання harness між ходами підтримується. Не перемикайте harness - посеред ходу після того, як уже почалися нативні tools, approvals, текст assistant або - надсилання повідомлень. +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів і далі містять назви `Pi` для сумісності. +- Установлення сторонніх каркасів є експериментальним. Віддавайте перевагу плагінам постачальників, доки вам не знадобиться native-середовище виконання сесії. +- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред ходу після того, як уже почалися native-інструменти, підтвердження, текст асистента або надсилання повідомлень. ## Пов’язане -- [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) -- [Model Providers](/uk/concepts/model-providers) +- [Огляд SDK](/uk/plugins/sdk-overview) +- [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) +- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) +- [Каркас Codex](/uk/plugins/codex-harness) +- [Постачальники моделей](/uk/concepts/model-providers) diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 1193cfa4e..583869735 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,54 +1,54 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Вам потрібна автентифікація підписки Codex замість API keys - - Вам потрібна суворіша агентна поведінка виконання GPT-5 -summary: Використання OpenAI через API keys або підписку Codex в OpenClaw + - Ви хочете автентифікацію за підпискою Codex замість API-ключів + - Вам потрібні суворіші правила виконання агента GPT-5 +summary: Використовуйте OpenAI через API-ключі або підписку Codex у OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-23T21:07:15Z" + generated_at: "2026-04-23T21:58:43Z" model: gpt-5.4 provider: openai - source_hash: 39f5259ef82bb95bb7a94cf36a33c4a3ea2b9ba06f5355dc7abf256167d7a4b9 + source_hash: 7cbe3f548cc53ca50c5e76dea0a940c4e0a807dce7f777cd1692280a820c1f29 source_path: providers/openai.md workflow: 15 --- -OpenAI надає developer API для моделей GPT. OpenClaw підтримує два шляхи автентифікації за одними й тими самими канонічними посиланнями на моделі OpenAI: +OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два способи автентифікації за одними й тими самими канонічними посиланнями на моделі OpenAI: -- **API key** — прямий доступ до OpenAI Platform з білінгом за використанням (моделі `openai/*`) -- **Підписка Codex** — вхід через ChatGPT/Codex із доступом за підпискою. Внутрішній id auth/provider-а — `openai-codex`, але нові посилання на моделі все одно мають використовувати `openai/*`. +- **API-ключ** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) +- **Підписка Codex** — вхід через ChatGPT/Codex із доступом за підпискою. Внутрішній ідентифікатор автентифікації/провайдера — `openai-codex`, але для нових посилань на моделі все одно слід використовувати `openai/*`. -OpenAI явно підтримує використання OAuth-підписки у зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI явно підтримує використання OAuth за підпискою у зовнішніх інструментах і робочих процесах, таких як OpenClaw. -## Покриття можливостей OpenAI в OpenClaw +## Покриття можливостей OpenClaw -| Можливість OpenAI | Поверхня OpenClaw | Статус | -| ----------------------- | --------------------------------------- | --------------------------------------------------------- | -| Chat / Responses | provider моделей `openai/` | Так | -| Моделі підписки Codex | `openai/` з auth `openai-codex` | Так | -| Server-side web search | Нативний інструмент OpenAI Responses | Так, коли web search увімкнено і provider не зафіксовано | -| Зображення | `image_generate` | Так | -| Відео | `video_generate` | Так | -| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так | -| Batch speech-to-text | `tools.media.audio` / media understanding | Так | -| Streaming speech-to-text| Voice Call `streaming.provider: "openai"` | Так | -| Realtime voice | Voice Call `realtime.provider: "openai"` | Так | -| Embeddings | provider embeddings для memory | Так | +| Можливість OpenAI | Поверхня OpenClaw | Статус | +| ----------------------- | ---------------------------------------- | ------------------------------------------------------ | +| Chat / Responses | провайдер моделі `openai/` | Так | +| Моделі підписки Codex | `openai/` з автентифікацією `openai-codex` | Так | +| Пошук у вебі на боці сервера | Нативний інструмент OpenAI Responses | Так, якщо вебпошук увімкнено і провайдера не зафіксовано | +| Зображення | `image_generate` | Так | +| Відео | `video_generate` | Так | +| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | +| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | +| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | +| Голос у реальному часі | Voice Call `realtime.provider: "openai"` | Так | +| Embeddings | провайдер embedding для пам’яті | Так | ## Початок роботи -Виберіть бажаний метод автентифікації та виконайте кроки налаштування. +Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - - **Найкраще для:** прямого доступу до API та білінгу за використанням. + + **Найкраще для:** прямого доступу до API та оплати за використання. - - Створіть або скопіюйте API key з [dashboard OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API-ключ на [панелі керування OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -59,25 +59,25 @@ OpenAI явно підтримує використання OAuth-підписк openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### Підсумок маршрутизації + ### Підсумок маршрутів - | Посилання на модель | Маршрут | Auth | - |-----------|-------|------| + | Model ref | Маршрут | Автентифікація | + |-----------|---------|----------------| | `openai/gpt-5.5` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.5-pro` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - `openai-codex/*` усе ще приймається як застарілий псевдонім сумісності, але нові конфігурації мають використовувати `openai/*`. + `openai-codex/*` і далі приймається як застарілий сумісний псевдонім, але в нових конфігураціях слід використовувати `openai/*`. - ### Приклад config + ### Приклад конфігурації ```json5 { @@ -87,13 +87,13 @@ OpenAI явно підтримує використання OAuth-підписк ``` - OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не показує. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає. - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Хмарний Codex вимагає входу через ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT. @@ -107,35 +107,35 @@ OpenAI явно підтримує використання OAuth-підписк openclaw models auth login --provider openai-codex ``` - Для безголових конфігурацій або конфігурацій, де callback браузера не підходить, додайте `--device-code`, щоб увійти через потік ChatGPT device-code замість localhost browser callback: + Для headless-середовищ або налаштувань, де callback працює ненадійно, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback браузера localhost: ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash openclaw config set agents.defaults.model.primary openai/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` - ### Підсумок маршрутизації + ### Підсумок маршрутів - | Посилання на модель | Маршрут | Auth | - |-----------|-------|------| - | `openai/gpt-5.5` | ChatGPT/Codex OAuth | Вхід Codex | + | Model ref | Маршрут | Автентифікація | + |-----------|---------|----------------| + | `openai/gpt-5.5` | ChatGPT/Codex OAuth | вхід Codex | - Посилання на моделі `openai-codex/*` і `codex/*` — це застарілі псевдоніми сумісності. Для команд auth/profile і далі використовуйте id provider-а `openai-codex`. + Посилання на моделі `openai-codex/*` і `codex/*` — це застарілі сумісні псевдоніми. Для команд автентифікації/профілю продовжуйте використовувати ідентифікатор провайдера `openai-codex`. - ### Приклад config + ### Приклад конфігурації ```json5 { @@ -144,27 +144,27 @@ OpenAI явно підтримує використання OAuth-підписк ``` - Onboarding більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через браузерний OAuth (типово) або через device-code flow вище — OpenClaw керує отриманими обліковими даними у власному сховищі auth агента. + Онбординг більше не імпортує матеріали OAuth із `~/.codex`. Увійдіть через OAuth у браузері (типово) або через наведений вище потік коду пристрою — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів. ### Індикатор стану - Чат-команда `/status` показує, який вбудований harness активний для поточної - session. Типовий harness PI відображається як `Runner: pi (embedded)` і не - додає окремого badge. Коли вибрано bundled harness app-server Codex, - `/status` додає id не-PI harness поруч із `Fast`, наприклад - `Fast · codex`. Наявні sessions зберігають свій записаний id harness, тож використовуйте + Chat `/status` показує, яка вбудована обв’язка активна для поточної + сесії. Обв’язка PI за замовчуванням відображається як `Runner: pi (embedded)` і + не додає окремого значка. Якщо вибрано вбудовану обв’язку app-server Codex, + `/status` додає ідентифікатор не-PI обв’язки поруч із `Fast`, наприклад + `Fast · codex`. Наявні сесії зберігають записаний ідентифікатор обв’язки, тому використовуйте `/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. ### Обмеження вікна контексту - OpenClaw розглядає метадані моделі та обмеження контексту runtime як окремі значення. + OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення. Для `openai/gpt-5.5` через Codex OAuth: - Нативний `contextWindow`: `1000000` - - Типове обмеження runtime `contextTokens`: `272000` + - Типове обмеження `contextTokens` під час виконання: `272000` Менше типове обмеження на практиці дає кращі характеристики затримки та якості. Перевизначте його через `contextTokens`: @@ -181,7 +181,7 @@ OpenAI явно підтримує використання OAuth-підписк ``` - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime. + Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. @@ -190,14 +190,18 @@ OpenAI явно підтримує використання OAuth-підписк ## Генерація зображень Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. +Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію +зображень через Codex OAuth за тим самим посиланням на модель `openai/gpt-image-2`. -| Можливість | Значення | -| ------------------------- | ------------------------------------ | -| Типова модель | `openai/gpt-image-2` | -| Макс. зображень на запит | 4 | -| Режим редагування | Увімкнено (до 5 reference image) | -| Перевизначення size | Підтримуються, включно з розмірами 2K/4K | -| Aspect ratio / resolution | Не пересилаються до OpenAI Images API | +| Можливість | API-ключ OpenAI | Codex OAuth | +| ----------------------- | ---------------------------------- | ------------------------------------ | +| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` | +| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth | +| Транспорт | OpenAI Images API | бекенд Codex Responses | +| Макс. зображень на запит | 4 | 4 | +| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | +| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K | +| Співвідношення сторін / роздільність | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно | ```json5 { @@ -210,15 +214,19 @@ OpenAI явно підтримує використання OAuth-підписк ``` -Спільні параметри інструмента, вибір provider-а та поведінку failover див. в [Генерація зображень](/uk/tools/image-generation). +Див. [Image Generation](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки резервного перемикання. -`gpt-image-2` є типовим значенням і для текст-у-зображення OpenAI, і для -редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. +`gpt-image-2` — це модель за замовчуванням як для генерації зображень із тексту OpenAI, так і для +редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але для нових +робочих процесів OpenAI із зображеннями слід використовувати `openai/gpt-image-2`. -Provider `openai-codex` також надає `gpt-image-2` для генерації зображень і -редагування reference-image через OpenAI Codex OAuth. Використовуйте -`openai-codex/gpt-image-2`, коли агент увійшов через Codex OAuth, але не має `OPENAI_API_KEY`. +Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Якщо +налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає цей збережений токен +доступу OAuth і надсилає запити на зображення через бекенд Codex Responses. Він +не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихий перехід до API-ключа для цього +запиту. Явно налаштуйте `models.providers.openai` за допомогою API-ключа, +власного base URL або кінцевої точки Azure, якщо вам потрібен прямий маршрут через OpenAI Images API. Генерація: @@ -226,12 +234,6 @@ Provider `openai-codex` також надає `gpt-image-2` для генера /tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 ``` -Генерація з Codex OAuth: - -``` -/tool image_generate model=openai-codex/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 -``` - Редагування: ``` @@ -242,13 +244,13 @@ Provider `openai-codex` також надає `gpt-image-2` для генера Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. -| Можливість | Значення | -| ---------------- | ----------------------------------------------------------------------------------- | -| Типова модель | `openai/sora-2` | -| Режими | Текст-у-відео, зображення-у-відео, редагування одного відео | -| Reference inputs | 1 зображення або 1 відео | -| Перевизначення size | Підтримуються | -| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з warning від інструмента | +| Можливість | Значення | +| --------------- | --------------------------------------------------------------------------------- | +| Типова модель | `openai/sora-2` | +| Режими | Текст у відео, зображення у відео, редагування одного відео | +| Еталонні входи | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримується | +| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 { @@ -261,22 +263,22 @@ Provider `openai-codex` також надає `gpt-image-2` для генера ``` -Спільні параметри інструмента, вибір provider-а та поведінку failover див. в [Генерація відео](/uk/tools/video-generation). +Див. [Video Generation](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки резервного перемикання. -## Внесок у prompt для GPT-5 +## Внесок у промпт GPT-5 -OpenClaw додає спільний внесок у prompt для GPT-5 для запусків сімейства GPT-5 у різних provider-ів. Він застосовується за model id, тож `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання на GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x — ні. -Вбудований нативний harness Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через developer instructions app-server Codex, тож sessions `openai/gpt-5.x`, примусово проведені через `embeddedHarness.runtime: "codex"`, зберігають ті самі настанови щодо доведення справи до кінця та проактивного Heartbeat, навіть якщо рештою prompt harness володіє Codex. +Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладання Heartbeat через інструкції для розробника Codex app-server, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення справ до кінця й проактивного Heartbeat, навіть якщо Codex керує рештою промпта обв’язки. -Внесок GPT-5 додає tagged-контракт поведінки для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналів поведінка reply і silent-message залишається в спільному системному prompt OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Дружній interaction-style layer є окремим і налаштовуваним. +Внесок GPT-5 додає тегований поведінковий контракт для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей і тихих повідомлень, специфічна для каналу, залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Рівень дружнього стилю взаємодії відокремлений і налаштовується. -| Значення | Ефект | -| ---------------------- | ------------------------------------------ | -| `"friendly"` (типово) | Увімкнути дружній interaction-style layer | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише friendly style layer | +| Значення | Ефект | +| --------------------- | -------------------------------------------- | +| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише рівень дружнього стилю | @@ -300,11 +302,11 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для -Під час runtime значення нечутливі до регістру, тож і `"Off"`, і `"off"` вимикають friendly style layer. +Під час виконання значення не чутливі до регістру, тож і `"Off"`, і `"off"` вимикають рівень дружнього стилю. -Застарілий `plugins.entries.openai.config.personality` усе ще читається як compatibility fallback, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застарілий параметр `plugins.entries.openai.config.personality` усе ще зчитується як сумісний запасний варіант, якщо спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не встановлено. ## Голос і мовлення @@ -313,17 +315,17 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. - | Налаштування | Шлях config | Типове значення | - |-------------|-------------|-----------------| + | Параметр | Шлях конфігурації | Типове значення | + |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | Voice | `messages.tts.providers.openai.voice` | `coral` | - | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | - | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | - | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для voice note, `mp3` для файлів | - | API key | `messages.tts.providers.openai.apiKey` | Fallback на `OPENAI_API_KEY` | + | Голос | `messages.tts.providers.openai.voice` | `coral` | + | Швидкість | `messages.tts.providers.openai.speed` | (не встановлено) | + | Інструкції | `messages.tts.providers.openai.instructions` | (не встановлено, лише `gpt-4o-mini-tts`) | + | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | + | API-ключ | `messages.tts.providers.openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні voice: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. + Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. ```json5 { @@ -338,23 +340,23 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для ``` - Задайте `OPENAI_TTS_BASE_URL`, щоб перевизначити base URL для TTS, не впливаючи на endpoint chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити base URL для TTS без впливу на кінцеву точку chat API. - - Вбудований Plugin `openai` реєструє пакетний speech-to-text через - поверхню транскрибування для media-understanding в OpenClaw. + + Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через + поверхню транскрибування розуміння медіа OpenClaw. - Типова модель: `gpt-4o-transcribe` - - Endpoint: OpenAI REST `/v1/audio/transcriptions` - - Шлях входу: multipart-завантаження audio-файла - - Підтримується в OpenClaw всюди, де транскрибування вхідного audio використовує - `tools.media.audio`, включно з сегментами voice-channel у Discord і - audio-вкладеннями каналів + - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` + - Шлях входу: multipart-завантаження аудіофайлу + - Підтримується в OpenClaw всюди, де транскрибування вхідного аудіо використовує + `tools.media.audio`, зокрема для сегментів голосових каналів Discord і + аудіовкладень каналів - Щоб примусово використовувати OpenAI для транскрибування вхідного audio: + Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: ```json5 { @@ -374,71 +376,72 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для } ``` - Підказки щодо мови й prompt пересилаються до OpenAI, коли вони надані - спільною конфігурацією audio media або запитом транскрибування для конкретного виклику. + Підказки щодо мови та промпта передаються до OpenAI, коли вони задані у + спільній конфігурації аудіомедіа або в запиті на транскрибування для окремого виклику. - Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin-а Voice Call. + Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. - | Налаштування | Шлях config | Типове значення | - |-------------|-------------|-----------------| + | Параметр | Шлях конфігурації | Типове значення | + |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | - | Мова | `...openai.language` | (не задано) | - | Prompt | `...openai.prompt` | (не задано) | + | Мова | `...openai.language` | (не встановлено) | + | Промпт | `...openai.prompt` | (не встановлено) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API key | `...openai.apiKey` | Fallback на `OPENAI_API_KEY` | + | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | - Використовує WebSocket-з’єднання до `wss://api.openai.com/v1/realtime` з audio у форматі G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей streaming provider призначений для шляху транскрибування в реальному часі в Voice Call; Discord voice наразі записує короткі сегменти й використовує пакетний шлях транскрибування `tools.media.audio`. + Використовує WebSocket-з’єднання до `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі у Voice Call; голос у Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрибування `tools.media.audio`. - Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin-а Voice Call. + Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. - | Налаштування | Шлях config | Типове значення | - |-------------|-------------|-----------------| + | Параметр | Шлях конфігурації | Типове значення | + |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | Voice | `...openai.voice` | `alloy` | + | Голос | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API key | `...openai.apiKey` | Fallback на `OPENAI_API_KEY` | + | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант | - Підтримує Azure OpenAI через ключі config `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує audio-формат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує формат аудіо G.711 u-law. -## Endpoint-и Azure OpenAI +## Кінцеві точки Azure OpenAI -Вбудований provider `openai` може націлюватися на ресурс Azure OpenAI для генерації -зображень через перевизначення base URL. На шляху генерації зображень OpenClaw -визначає Azure-hostname-и в `models.providers.openai.baseUrl` і автоматично перемикається на -форму запиту Azure. +Вбудований провайдер `openai` може працювати з ресурсом Azure OpenAI для +генерації зображень через перевизначення base URL. На шляху генерації зображень OpenClaw +визначає імена хостів Azure у `models.providers.openai.baseUrl` і автоматично перемикається на +формат запиту Azure. -Для голосу в реальному часі використовується окремий шлях конфігурації -(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`), -на який `models.providers.openai.baseUrl` не впливає. Налаштування Azure для нього див. в accordion **Голос і мовлення** під [Голос і мовлення](#voice-and-speech). +Голос у реальному часі використовує окремий шлях конфігурації +(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) +і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному +часі** в розділі [Голос і мовлення](#voice-and-speech) для його параметрів Azure. -Використовуйте Azure OpenAI, коли: +Використовуйте Azure OpenAI, якщо: -- у вас уже є підписка Azure OpenAI, quota або enterprise agreement -- вам потрібні регіональна резидентність даних або механізми compliance, які надає Azure -- ви хочете, щоб трафік залишався в межах наявного tenancy Azure +- У вас уже є підписка Azure OpenAI, квота або корпоративна угода +- Вам потрібна регіональна локалізація даних або засоби відповідності вимогам, які надає Azure +- Ви хочете зберігати трафік у межах наявного середовища Azure ### Конфігурація -Для генерації зображень Azure через вбудований provider `openai` спрямуйте -`models.providers.openai.baseUrl` на свій ресурс Azure і задайте `apiKey` як +Для генерації зображень через Azure за допомогою вбудованого провайдера `openai`, укажіть +`models.providers.openai.baseUrl` для вашого ресурсу Azure і встановіть `apiKey` як ключ Azure OpenAI (а не ключ OpenAI Platform): ```json5 @@ -454,100 +457,99 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для } ``` -OpenClaw розпізнає такі Azure host suffix для -шляху генерації зображень Azure: +OpenClaw розпізнає такі суфікси хостів Azure для маршруту генерації зображень Azure: - `*.openai.azure.com` - `*.services.ai.azure.com` - `*.cognitiveservices.azure.com` -Для запитів генерації зображень на розпізнаному Azure host OpenClaw: +Для запитів на генерацію зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує deployment-scoped-шляхи (`/openai/deployments/{deployment}/...`) +- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -Інші base URL (публічний OpenAI, OpenAI-сумісні proxy) зберігають стандартну -форму запиту до OpenAI для зображень. +Інші base URL (публічний OpenAI, сумісні з OpenAI проксі) зберігають стандартний +формат запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень provider-а `openai` потребує -OpenClaw 2026.4.22 або новішої версії. Раніші версії трактують будь-який кастомний -`openai.baseUrl` як публічний endpoint OpenAI і завершуються помилкою при роботі з Azure -image deployment-ами. +Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує +OpenClaw 2026.4.22 або новішої версії. Попередні версії обробляють будь-який власний +`openai.baseUrl` як публічну кінцеву точку OpenAI і не працюватимуть із deployment генерації +зображень Azure. -### Версія API + ### Версія API -Задайте `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview або GA-версію Azure -для шляху генерації зображень Azure: + Установіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure + для шляху генерації зображень Azure: -```bash -export AZURE_OPENAI_API_VERSION="2024-12-01-preview" -``` + ```bash + export AZURE_OPENAI_API_VERSION="2024-12-01-preview" + ``` - Типове значення — `2024-12-01-preview`, якщо змінну не задано. + Типове значення — `2024-12-01-preview`, якщо змінну не встановлено. ### Назви моделей — це назви deployment - Azure OpenAI прив’язує моделі до deployment-ів. Для запитів генерації зображень Azure, - маршрутизованих через вбудований provider `openai`, поле `model` в OpenClaw - має бути **назвою deployment Azure**, яку ви налаштували в Azure portal, а не - публічним model id OpenAI. + Azure OpenAI прив’язує моделі до deployment. Для запитів на генерацію зображень Azure, + маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw + має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не + публічним ідентифікатором моделі OpenAI. - Якщо ви створили deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: + Якщо ви створили deployment під назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` Те саме правило назви deployment застосовується до викликів генерації зображень, - маршрутизованих через вбудований provider `openai`. + маршрутизованих через вбудований провайдер `openai`. ### Регіональна доступність - Генерація зображень Azure наразі доступна лише в підмножині регіонів + Генерація зображень Azure наразі доступна лише в обмеженій кількості регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, - `uaenorth`). Перевірте поточний список регіонів Microsoft перед створенням - deployment і підтвердьте, що конкретна модель пропонується у вашому регіоні. + `uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням + deployment і підтвердьте, що конкретна модель доступна у вашому регіоні. ### Відмінності параметрів Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні - значення `background` для `gpt-image-2`) або надавати їх лише для конкретних - версій моделі. Ці відмінності походять від Azure і базової моделі, а не від + значення `background` для `gpt-image-2`) або надавати їх лише для певних версій + моделі. Ці відмінності походять від Azure та базової моделі, а не від OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте - набір параметрів, який підтримується вашим конкретним deployment і версією API в - Azure portal. + набір параметрів, які підтримує ваш конкретний deployment і версія API, у + порталі Azure. - Azure OpenAI використовує нативний transport і compat-поведінку, але не отримує - приховані заголовки attribution OpenClaw — див. accordion **Нативні vs OpenAI-compatible - маршрути** у розділі [Розширена конфігурація](#advanced-configuration). + Azure OpenAI використовує нативний транспорт і сумісну поведінку, але не отримує + приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні маршрути та маршрути, сумісні з OpenAI** + в розділі [Розширена конфігурація](#advanced-configuration). Для трафіку chat або Responses на Azure (поза генерацією зображень) використовуйте - потік onboarding або окрему конфігурацію provider-а Azure — одного лише - `openai.baseUrl` недостатньо, щоб підхопити форму API/auth Azure. Існує окремий - provider `azure-openai-responses/*`; див. - accordion про Server-side Compaction нижче. + потік онбордингу або окрему конфігурацію провайдера Azure — самого лише + `openai.baseUrl` недостатньо, щоб застосувати форму API/автентифікації Azure. Існує окремий + провайдер `azure-openai-responses/*`; див. + акордеон Server-side Compaction нижче. ## Розширена конфігурація - - OpenClaw використовує підхід WebSocket-first із fallback на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. + + OpenClaw використовує спочатку WebSocket із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - - Повторює одну ранню помилку WebSocket перед переходом на fallback через SSE - - Після збою позначає WebSocket як degraded приблизно на 60 секунд і використовує SSE під час cool-down - - Додає стабільні заголовки identity для session і ходу для retry та reconnect - - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами transport + - Повторює одну ранню помилку WebSocket перед переходом на SSE + - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження + - Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і перепідключень + - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | - |----------|-----------| - | `"auto"` (типово) | Спочатку WebSocket, fallback на SSE | + |-------|----------| + | `"auto"` (типово) | Спочатку WebSocket, резервний перехід на SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -591,13 +593,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" - - OpenClaw надає спільний перемикач fast mode для `openai/*`: + + OpenClaw надає спільний перемикач швидкого режиму для `openai/*`: - **Chat/UI:** `/fast status|on|off` - - **Config:** `agents.defaults.models["/"].params.fastMode` + - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли його ввімкнено, OpenClaw відображає fast mode на priority processing OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, і fast mode не переписує `reasoning` або `text.verbosity`. + Коли ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` чи `text.verbosity`. ```json5 { @@ -612,13 +614,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` - Перевизначення на рівні session мають пріоритет над config. Очищення перевизначення session в UI Sessions повертає session до налаштованого типового значення. + Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення. - - API OpenAI надає priority processing через `service_tier`. Задавайте його для кожної моделі в OpenClaw: + + API OpenAI надає пріоритетну обробку через `service_tier`. Установіть її для кожної моделі в OpenClaw: ```json5 { @@ -635,7 +637,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` пересилається лише до нативних endpoint-ів OpenAI (`api.openai.com`) і нативних endpoint-ів Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих provider-ів через proxy, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. @@ -643,13 +645,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) OpenClaw автоматично вмикає Server-side Compaction: - - Примусово задає `store: true` (якщо тільки compat моделі не задає `supportsStore: false`) + - Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`) - Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли воно недоступне) + - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо недоступно) - - Корисно для сумісних endpoint-ів, таких як Azure OpenAI Responses: + + Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses: ```json5 { @@ -665,7 +667,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" } ``` - + ```json5 { agents: { @@ -701,12 +703,12 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses усе одно примусово задають `store: true`, якщо тільки compat не задає `supportsStore: false`. + `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses однаково примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`. - + Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання: ```json5 @@ -719,33 +721,33 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" } ``` - Із `strict-agentic` OpenClaw: - - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія з інструментом - - Повторює хід зі steer «дій зараз» + З `strict-agentic` OpenClaw: + - Більше не вважає хід лише з планом успішним поступом, якщо доступна дія інструмента + - Повторює хід із вказівкою діяти зараз - Автоматично вмикає `update_plan` для суттєвої роботи - - Показує явний blocked state, якщо модель продовжує планувати без дії + - Показує явний заблокований стан, якщо модель продовжує планувати без дії - Обмежено лише запусками OpenAI і Codex сімейства GPT-5. Інші provider-и та старіші сімейства моделей зберігають типову поведінку. + Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. - - OpenClaw по-різному трактує прямі endpoint-и OpenAI, Codex і Azure OpenAI та загальні OpenAI-compatible `/v1` proxy: + + OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні проксі `/v1`, сумісні з OpenAI: **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort - - Пропускають вимкнений reasoning для моделей або proxy, які відхиляють `reasoning.effort: "none"` - - Типово задають strict mode для tool schema - - Додають приховані attribution headers лише на перевірених нативних host-ах - - Зберігають request shaping лише для OpenAI (`service_tier`, `store`, reasoning-compat, підказки prompt-cache) + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI effort `none` + - Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` + - Типово встановлюють суворий режим для схем інструментів + - Додають приховані заголовки атрибуції лише на перевірених нативних хостах + - Зберігають формування запитів лише для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів) - **Маршрути proxy/compatible:** - - Використовують м’якшу compat-поведінку - - Не примушують strict tool schema або заголовки лише для native + **Проксі/сумісні маршрути:** + - Використовують м’якшу сумісну поведінку + - Не примушують суворі схеми інструментів або заголовки лише для нативних маршрутів - Azure OpenAI використовує нативний transport і compat-поведінку, але не отримує прихованих attribution headers. + Azure OpenAI використовує нативний транспорт і сумісну поведінку, але не отримує прихованих заголовків атрибуції. @@ -754,15 +756,15 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" - Вибір provider-ів, посилань на моделі та поведінки failover. + Вибір провайдерів, посилань на моделі та поведінки резервного перемикання. - Спільні параметри image-інструмента та вибір provider-а. + Спільні параметри інструмента зображень і вибір провайдера. - Спільні параметри video-інструмента та вибір provider-а. + Спільні параметри інструмента відео та вибір провайдера. - - Деталі auth і правила повторного використання облікових даних. + + Відомості про автентифікацію та правила повторного використання облікових даних. diff --git a/docs/uk/reference/memory-config.md b/docs/uk/reference/memory-config.md index c2d4c3d55..d85bd588d 100644 --- a/docs/uk/reference/memory-config.md +++ b/docs/uk/reference/memory-config.md @@ -1,95 +1,96 @@ --- read_when: - - Ви хочете налаштувати провайдерів memory search або embedding-моделі - - Ви хочете налаштувати backend QMD - - Ви хочете налаштувати hybrid search, MMR або temporal decay - - Ви хочете ввімкнути multimodal indexing для memory -summary: Усі параметри конфігурації для memory search, embedding providers, QMD, hybrid search і multimodal indexing -title: Довідник конфігурації Memory + - Ви хочете налаштувати постачальників пошуку в пам’яті або моделі ембедингів + - Ви хочете налаштувати бекенд QMD + - Ви хочете налаштувати гібридний пошук, MMR або часовий спад + - Ви хочете ввімкнути мультимодальне індексування пам’яті +summary: Усі параметри конфігурації для пошуку в пам’яті, постачальників ембедингів, QMD, гібридного пошуку та мультимодального індексування +title: Довідник із конфігурації пам’яті x-i18n: - generated_at: "2026-04-23T21:09:47Z" + generated_at: "2026-04-23T21:58:49Z" model: gpt-5.4 provider: openai - source_hash: 2e179b955ee0532805ee254d79217b66c093def534c2ef3952d955b3b05de8ca + source_hash: e8f91c15c149feb1a351585d246f3155ce56164cbda3e773dd63ebfa6c1b63b7 source_path: reference/memory-config.md workflow: 15 --- -Ця сторінка перелічує всі параметри конфігурації для memory search в OpenClaw. Для -концептуальних оглядів див.: +На цій сторінці наведено всі параметри конфігурації для пошуку в пам’яті OpenClaw. Для концептуальних оглядів дивіться: -- [Memory Overview](/uk/concepts/memory) -- як працює memory -- [Builtin Engine](/uk/concepts/memory-builtin) -- типовий backend SQLite -- [QMD Engine](/uk/concepts/memory-qmd) -- локально-орієнтований sidecar -- [Memory Search](/uk/concepts/memory-search) -- конвеєр пошуку та налаштування -- [Active Memory](/uk/concepts/active-memory) -- увімкнення субагента memory для інтерактивних сесій +- [Огляд пам’яті](/uk/concepts/memory) -- як працює пам’ять +- [Вбудований рушій](/uk/concepts/memory-builtin) -- типовий бекенд SQLite +- [Рушій QMD](/uk/concepts/memory-qmd) -- локальний sidecar із local-first підходом +- [Пошук у пам’яті](/uk/concepts/memory-search) -- конвеєр пошуку та налаштування +- [Active Memory](/uk/concepts/active-memory) -- увімкнення субагента пам’яті для інтерактивних сесій -Усі параметри memory search розміщуються в `agents.defaults.memorySearch` у +Усі налаштування пошуку в пам’яті розміщені в `agents.defaults.memorySearch` у `openclaw.json`, якщо не зазначено інше. Якщо ви шукаєте перемикач функції **active memory** і конфігурацію субагента, -вона розміщена в `plugins.entries.active-memory`, а не в `memorySearch`. +вона розташована в `plugins.entries.active-memory`, а не в `memorySearch`. -Active memory використовує модель із двома шлюзами: +Active Memory використовує двоетапну модель перевірки: -1. Plugin має бути увімкнений і націлений на поточний id агента -2. Запит має бути придатною інтерактивною постійною чат-сесією +1. plugin має бути ввімкнений і націлений на поточний id агента +2. запит має бути відповідною інтерактивною постійною сесією чату -Модель активації, конфігурацію, якою володіє Plugin, збереження транскриптів і безпечний шаблон упровадження див. у [Active Memory](/uk/concepts/active-memory). +Дивіться [Active Memory](/uk/concepts/active-memory) щодо моделі активації, +конфігурації, якою володіє plugin, збереження транскриптів і безпечної схеми розгортання. --- -## Вибір provider +## Вибір постачальника -| Ключ | Тип | Типове значення | Опис | -| --------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------ | -| `provider` | `string` | auto-detected | id адаптера embedding: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | -| `model` | `string` | provider default | Назва embedding-моделі | -| `fallback` | `string` | `"none"` | id резервного адаптера, якщо основний завершується помилкою | -| `enabled` | `boolean` | `true` | Увімкнути або вимкнути memory search | +| Ключ | Тип | Типове значення | Опис | +| ---------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | автоматично визначається | ID адаптера ембедингів: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | +| `model` | `string` | типове значення постачальника | Назва моделі ембедингів | +| `fallback` | `string` | `"none"` | ID резервного адаптера, якщо основний завершується невдачею | +| `enabled` | `boolean` | `true` | Увімкнути або вимкнути пошук у пам’яті | -### Порядок автовизначення +### Порядок автоматичного визначення -Коли `provider` не задано, OpenClaw вибирає перший доступний варіант: +Коли `provider` не задано, OpenClaw вибирає перший доступний: 1. `local` -- якщо налаштовано `memorySearch.local.modelPath` і файл існує. -2. `github-copilot` -- якщо можна розв’язати токен GitHub Copilot (env var або auth profile). -3. `openai` -- якщо можна розв’язати ключ OpenAI. -4. `gemini` -- якщо можна розв’язати ключ Gemini. -5. `voyage` -- якщо можна розв’язати ключ Voyage. -6. `mistral` -- якщо можна розв’язати ключ Mistral. -7. `bedrock` -- якщо ланцюг облікових даних AWS SDK розв’язується (роль екземпляра, ключі доступу, profile, SSO, web identity або спільна конфігурація). +2. `github-copilot` -- якщо вдається визначити токен GitHub Copilot (змінна середовища або профіль автентифікації). +3. `openai` -- якщо вдається визначити ключ OpenAI. +4. `gemini` -- якщо вдається визначити ключ Gemini. +5. `voyage` -- якщо вдається визначити ключ Voyage. +6. `mistral` -- якщо вдається визначити ключ Mistral. +7. `bedrock` -- якщо вдається визначити облікові дані через стандартний ланцюжок AWS SDK (роль екземпляра, ключі доступу, профіль, SSO, web identity або спільна конфігурація). -`ollama` підтримується, але не визначається автоматично (задайте його явно). +`ollama` підтримується, але не визначається автоматично (вкажіть його явно). -### Розв’язання API-ключа +### Визначення API-ключа -Віддалені embeddings потребують API-ключа. Натомість Bedrock використовує типовий -ланцюг облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу). +Для віддалених ембедингів потрібен API-ключ. Натомість Bedrock використовує +стандартний ланцюжок облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу). -| Provider | Env var | Ключ конфігурації | -| -------------- | -------------------------------------------------- | --------------------------------- | -| Bedrock | ланцюг облікових даних AWS | API-ключ не потрібен | -| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Auth profile через device login | -| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Ollama | `OLLAMA_API_KEY` (placeholder) | -- | -| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | -| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | +| Постачальник | Змінна середовища | Ключ конфігурації | +| ------------ | ------------------------------------------------- | --------------------------------- | +| Bedrock | ланцюжок облікових даних AWS | API-ключ не потрібен | +| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Профіль автентифікації через вхід із пристрою | +| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | +| Ollama | `OLLAMA_API_KEY` (заповнювач) | -- | +| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | +| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -Codex OAuth покриває лише chat/completions і не задовольняє embedding-запити. +Codex OAuth охоплює лише chat/completions і не задовольняє запити на +ембединги. --- -## Конфігурація віддаленого endpoint +## Конфігурація віддаленої кінцевої точки -Для власних OpenAI-сумісних endpoint або перевизначення типових значень provider: +Для користувацьких OpenAI-сумісних кінцевих точок або перевизначення типових значень постачальника: -| Ключ | Тип | Опис | -| ---------------- | -------- | -------------------------------------------- | -| `remote.baseUrl` | `string` | Власний API base URL | -| `remote.apiKey` | `string` | Перевизначення API-ключа | -| `remote.headers` | `object` | Додаткові HTTP headers (зливаються з типовими значеннями provider) | +| Ключ | Тип | Опис | +| ---------------- | -------- | ------------------------------------------------- | +| `remote.baseUrl` | `string` | Користувацька базова URL-адреса API | +| `remote.apiKey` | `string` | Перевизначити API-ключ | +| `remote.headers` | `object` | Додаткові HTTP-заголовки (об’єднуються з типовими значеннями постачальника) | ```json5 { @@ -110,24 +111,24 @@ Codex OAuth покриває лише chat/completions і не задоволь --- -## Конфігурація, специфічна для Gemini +## Конфігурація Gemini -| Ключ | Тип | Типове значення | Опис | -| ---------------------- | -------- | ----------------------- | ------------------------------------------ | -| `model` | `string` | `gemini-embedding-001` | Також підтримує `gemini-embedding-2-preview` | -| `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 | +| Ключ | Тип | Типове значення | Опис | +| ---------------------- | -------- | --------------------- | ------------------------------------------ | +| `model` | `string` | `gemini-embedding-001` | Також підтримується `gemini-embedding-2-preview` | +| `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 | -Зміна моделі або `outputDimensionality` запускає автоматичне повне повторне індексування. +Зміна моделі або `outputDimensionality` запускає автоматичне повне переіндексування. --- -## Конфігурація embedding для Bedrock +## Конфігурація ембедингів Bedrock -Bedrock використовує типовий ланцюг облікових даних AWS SDK -- API-ключі не потрібні. -Якщо OpenClaw працює на EC2 з роллю екземпляра, у якої ввімкнено Bedrock, просто задайте -provider і модель: +Bedrock використовує стандартний ланцюжок облікових даних AWS SDK -- API-ключі не потрібні. +Якщо OpenClaw працює на EC2 з роллю екземпляра, у якій увімкнено Bedrock, просто задайте +постачальника та модель: ```json5 { @@ -142,47 +143,48 @@ provider і модель: } ``` -| Ключ | Тип | Типове значення | Опис | -| ---------------------- | -------- | ----------------------------- | --------------------------------- | -| `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який id embedding-моделі Bedrock | -| `outputDimensionality` | `number` | model default | Для Titan V2: 256, 512 або 1024 | +| Ключ | Тип | Типове значення | Опис | +| ---------------------- | -------- | ----------------------------- | ---------------------------------- | +| `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який ID моделі ембедингів Bedrock | +| `outputDimensionality` | `number` | типове значення моделі | Для Titan V2: 256, 512 або 1024 | ### Підтримувані моделі -Підтримуються такі моделі (з визначенням сімейства та типовими значеннями розмірностей): +Підтримуються такі моделі (з визначенням сімейства та типовими +значеннями розмірності): -| Model ID | Provider | Типові розмірності | Налаштовувані розмірності | -| ------------------------------------------ | ---------- | ------------------ | ------------------------- | -| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | -| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | -| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | -| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | -| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | -| `cohere.embed-english-v3` | Cohere | 1024 | -- | -| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | -| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | -| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | -| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | +| ID моделі | Постачальник | Типова розмірність | Налаштовувана розмірність | +| ------------------------------------------ | ------------ | ------------------ | ------------------------- | +| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | +| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | +| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | +| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | +| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | +| `cohere.embed-english-v3` | Cohere | 1024 | -- | +| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | +| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | +| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | +| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | -Варіанти з суфіксами пропускної здатності (наприклад, `amazon.titan-embed-text-v1:2:8k`) успадковують +Варіанти із суфіксом пропускної здатності (наприклад, `amazon.titan-embed-text-v1:2:8k`) успадковують конфігурацію базової моделі. ### Автентифікація -Auth Bedrock використовує стандартний порядок розв’язання облікових даних AWS SDK: +Автентифікація Bedrock використовує стандартний порядок визначення облікових даних AWS SDK: 1. Змінні середовища (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. Кеш токенів SSO -3. Облікові дані web identity token +3. Облікові дані токена web identity 4. Спільні файли облікових даних і конфігурації -5. Облікові дані ECS або EC2 metadata +5. Облікові дані метаданих ECS або EC2 -Регіон розв’язується з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` provider -`amazon-bedrock` або типово задається як `us-east-1`. +Регіон визначається з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` +постачальника `amazon-bedrock` або за замовчуванням використовується `us-east-1`. -### IAM permissions +### Дозволи IAM -Роль або користувач IAM потребують: +Ролі або користувачу IAM потрібно: ```json { @@ -192,7 +194,7 @@ Auth Bedrock використовує стандартний порядок ро } ``` -Для принципу найменших привілеїв обмежте `InvokeModel` конкретною моделлю: +Для мінімально необхідних привілеїв обмежте `InvokeModel` конкретною моделлю: ``` arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 @@ -200,44 +202,45 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 --- -## Конфігурація локальних embeddings +## Конфігурація локальних ембедингів -| Ключ | Тип | Типове значення | Опис | -| --------------------- | -------- | ---------------------- | -------------------------------- | -| `local.modelPath` | `string` | auto-downloaded | Шлях до файла моделі GGUF | -| `local.modelCacheDir` | `string` | типове значення node-llama-cpp | Каталог кешу для завантажених моделей | +| Ключ | Тип | Типове значення | Опис | +| --------------------- | ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `local.modelPath` | `string` | автоматично завантажується | Шлях до файлу моделі GGUF | +| `local.modelCacheDir` | `string` | типове значення node-llama-cpp | Каталог кешу для завантажених моделей | +| `local.contextSize` | `number \| "auto"` | `4096` | Розмір контекстного вікна для контексту ембедингів. 4096 покриває типові чанки (128–512 токенів), водночас обмежуючи VRAM, що не припадає на ваги моделі. На обмежених хостах зменшуйте до 1024–2048. `"auto"` використовує максимальне значення, на якому навчалася модель, — не рекомендовано для моделей 8B+ (Qwen3-Embedding-8B: 40 960 токенів → ~32 ГБ VRAM проти ~8.8 ГБ при 4096). | -Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, auto-downloaded). -Потребує нативного build: `pnpm approve-builds`, потім `pnpm rebuild node-llama-cpp`. +Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 ГБ, автоматично завантажується). +Потрібна нативна збірка: `pnpm approve-builds`, потім `pnpm rebuild node-llama-cpp`. --- -## Конфігурація hybrid search +## Конфігурація гібридного пошуку -Усе розміщується в `memorySearch.query.hybrid`: +Усе в `memorySearch.query.hybrid`: | Ключ | Тип | Типове значення | Опис | | --------------------- | --------- | --------------- | ------------------------------------- | -| `enabled` | `boolean` | `true` | Увімкнути hybrid BM25 + vector search | +| `enabled` | `boolean` | `true` | Увімкнути гібридний пошук BM25 + vector | | `vectorWeight` | `number` | `0.7` | Вага для vector-оцінок (0-1) | | `textWeight` | `number` | `0.3` | Вага для BM25-оцінок (0-1) | | `candidateMultiplier` | `number` | `4` | Множник розміру пулу кандидатів | -### MMR (різноманіття) +### MMR (різноманітність) -| Ключ | Тип | Типове значення | Опис | -| ------------ | --------- | --------------- | ------------------------------------------ | -| `mmr.enabled` | `boolean` | `false` | Увімкнути MMR re-ranking | -| `mmr.lambda` | `number` | `0.7` | 0 = максимальне різноманіття, 1 = максимальна релевантність | +| Ключ | Тип | Типове значення | Опис | +| ------------- | --------- | --------------- | ------------------------------------ | +| `mmr.enabled` | `boolean` | `false` | Увімкнути повторне ранжування MMR | +| `mmr.lambda` | `number` | `0.7` | 0 = максимальна різноманітність, 1 = максимальна релевантність | -### Temporal decay (давність) +### Часовий спад (свіжість) -| Ключ | Тип | Типове значення | Опис | -| ---------------------------- | --------- | --------------- | ------------------------------------- | -| `temporalDecay.enabled` | `boolean` | `false` | Увімкнути підсилення за давністю | +| Ключ | Тип | Типове значення | Опис | +| ---------------------------- | --------- | --------------- | --------------------------------- | +| `temporalDecay.enabled` | `boolean` | `false` | Увімкнути підсилення свіжості | | `temporalDecay.halfLifeDays` | `number` | `30` | Оцінка зменшується вдвічі кожні N днів | -Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ніколи не піддаються згасанню. +Для evergreen-файлів (`MEMORY.md`, файли без дат у `memory/`) часовий спад ніколи не застосовується. ### Повний приклад @@ -262,11 +265,11 @@ Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ні --- -## Додаткові шляхи memory +## Додаткові шляхи пам’яті | Ключ | Тип | Опис | | ----------- | ---------- | ----------------------------------------- | -| `extraPaths` | `string[]` | Додаткові каталоги або файли для індексації | +| `extraPaths` | `string[]` | Додаткові каталоги або файли для індексування | ```json5 { @@ -280,153 +283,152 @@ Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ні } ``` -Шляхи можуть бути абсолютними або відносними до workspace. Каталоги скануються -рекурсивно на наявність файлів `.md`. Обробка symlink залежить від активного backend: -вбудований engine ігнорує symlink, тоді як QMD дотримується поведінки -базового scanner QMD. +Шляхи можуть бути абсолютними або відносними до робочого простору. Каталоги +скануються рекурсивно на наявність файлів `.md`. Обробка симлінків залежить від активного бекенда: +вбудований рушій ігнорує симлінки, тоді як QMD наслідує поведінку базового +сканера QMD. -Для agent-scoped пошуку транскриптів між агентами використовуйте +Для пошуку транскриптів між агентами в межах агента використовуйте `agents.list[].memorySearch.qmd.extraCollections` замість `memory.qmd.paths`. -Ці додаткові collections дотримуються тієї самої форми `{ path, name, pattern? }`, але -зливаються для кожного агента окремо й можуть зберігати явні спільні назви, коли шлях -вказує поза поточний workspace. -Якщо той самий розв’язаний шлях з’являється і в `memory.qmd.paths`, і в -`memorySearch.qmd.extraCollections`, QMD залишає перший запис і пропускає +Ці додаткові колекції мають ту саму форму `{ path, name, pattern? }`, але +об’єднуються для кожного агента і можуть зберігати явно задані спільні назви, коли шлях +вказує за межі поточного робочого простору. +Якщо той самий визначений шлях з’являється і в `memory.qmd.paths`, і в +`memorySearch.qmd.extraCollections`, QMD зберігає перший запис і пропускає дублікат. --- -## Multimodal memory (Gemini) +## Мультимодальна пам’ять (Gemini) Індексуйте зображення й аудіо разом із Markdown за допомогою Gemini Embedding 2: | Ключ | Тип | Типове значення | Опис | | ------------------------- | ---------- | --------------- | -------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | Увімкнути multimodal indexing | +| `multimodal.enabled` | `boolean` | `false` | Увімкнути мультимодальне індексування | | `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` або `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файла для індексації | +| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файлу для індексування | -Застосовується лише до файлів у `extraPaths`. Типові корені memory і далі підтримують лише Markdown. -Потребує `gemini-embedding-2-preview`. `fallback` має бути `"none"`. +Застосовується лише до файлів у `extraPaths`. Типові корені пам’яті залишаються лише для Markdown. +Потрібен `gemini-embedding-2-preview`. `fallback` має бути `"none"`. Підтримувані формати: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` (зображення); `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac` (аудіо). --- -## Кеш embeddings +## Кеш ембедингів | Ключ | Тип | Типове значення | Опис | | ------------------ | --------- | --------------- | ---------------------------------- | -| `cache.enabled` | `boolean` | `false` | Кешувати embeddings чанків у SQLite | -| `cache.maxEntries` | `number` | `50000` | Максимум кешованих embeddings | +| `cache.enabled` | `boolean` | `false` | Кешувати ембединги чанків у SQLite | +| `cache.maxEntries` | `number` | `50000` | Максимум кешованих ембедингів | -Запобігає повторному embedding незміненого тексту під час reindex або оновлень транскриптів. +Запобігає повторному створенню ембедингів для незміненого тексту під час переіндексації або оновлень транскриптів. --- -## Пакетна індексація +## Пакетне індексування -| Ключ | Тип | Типове значення | Опис | -| ----------------------------- | --------- | --------------- | ---------------------------- | -| `remote.batch.enabled` | `boolean` | `false` | Увімкнути пакетний API embedding | -| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання | -| `remote.batch.wait` | `boolean` | `true` | Чекати завершення пакета | -| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування | -| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета | +| Ключ | Тип | Типове значення | Опис | +| ----------------------------- | --------- | --------------- | ------------------------------ | +| `remote.batch.enabled` | `boolean` | `false` | Увімкнути API пакетних ембедингів | +| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання | +| `remote.batch.wait` | `boolean` | `true` | Чекати завершення пакета | +| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування | +| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета | Доступно для `openai`, `gemini` і `voyage`. Пакетний режим OpenAI зазвичай -найшвидший і найдешевший для великих зворотних індексацій. +найшвидший і найдешевший для великих зворотних заповнень. --- -## Memory search сесій (експериментально) +## Пошук у пам’яті сесій (експериментально) Індексуйте транскрипти сесій і відображайте їх через `memory_search`: -| Ключ | Тип | Типове значення | Опис | -| ---------------------------- | ---------- | --------------- | ------------------------------------------ | -| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексацію сесій | -| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти | -| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для reindex | -| `sync.sessions.deltaMessages`| `number` | `50` | Поріг повідомлень для reindex | +| Ключ | Тип | Типове значення | Опис | +| ----------------------------- | ---------- | --------------- | ------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексування сесій | +| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти | +| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для переіндексації | +| `sync.sessions.deltaMessages` | `number` | `50` | Поріг повідомлень для переіндексації | -Індексація сесій є opt-in і виконується асинхронно. Результати можуть бути трохи -застарілими. Логи сесій живуть на диску, тому вважайте доступ до файлової системи +Індексування сесій виконується за явною згодою і працює асинхронно. Результати можуть бути +дещо застарілими. Журнали сесій зберігаються на диску, тож вважайте доступ до файлової системи межею довіри. --- ## Прискорення векторів SQLite (sqlite-vec) -| Ключ | Тип | Типове значення | Опис | -| ---------------------------- | --------- | --------------- | ------------------------------------ | -| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для vector queries | -| `store.vector.extensionPath` | `string` | bundled | Перевизначити шлях до sqlite-vec | +| Ключ | Тип | Типове значення | Опис | +| ---------------------------- | --------- | --------------- | --------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для векторних запитів | +| `store.vector.extensionPath` | `string` | bundled | Перевизначити шлях до sqlite-vec | -Коли sqlite-vec недоступний, OpenClaw автоматично повертається до cosine -similarity у процесі. +Коли sqlite-vec недоступний, OpenClaw автоматично повертається до косинусної +схожості в межах процесу. --- ## Зберігання індексу -| Ключ | Тип | Типове значення | Опис | -| ------------------- | -------- | -------------------------------------- | ------------------------------------------------ | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Розташування індексу (підтримує токен `{agentId}`) | -| `store.fts.tokenizer` | `string` | `unicode61` | Токенізатор FTS5 (`unicode61` або `trigram`) | +| Ключ | Тип | Типове значення | Опис | +| ------------------- | -------- | ------------------------------------ | ------------------------------------------- | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Розташування індексу (підтримує токен `{agentId}`) | +| `store.fts.tokenizer` | `string` | `unicode61` | Токенізатор FTS5 (`unicode61` або `trigram`) | --- -## Конфігурація backend QMD +## Конфігурація бекенда QMD -Установіть `memory.backend = "qmd"`, щоб увімкнути його. Усі параметри QMD розміщуються в +Щоб увімкнути, задайте `memory.backend = "qmd"`. Усі налаштування QMD розміщені в `memory.qmd`: -| Ключ | Тип | Типове значення | Опис | -| ------------------------ | --------- | --------------- | -------------------------------------------- | -| `command` | `string` | `qmd` | Шлях до виконуваного файла QMD | +| Ключ | Тип | Типове значення | Опис | +| ------------------------ | --------- | --------------- | ------------------------------------------- | +| `command` | `string` | `qmd` | Шлях до виконуваного файлу QMD | | `searchMode` | `string` | `search` | Команда пошуку: `search`, `vsearch`, `query` | -| `includeDefaultMemory` | `boolean` | `true` | Автоіндексація `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | Індексувати транскрипти сесій | -| `sessions.retentionDays` | `number` | -- | Утримання транскриптів | -| `sessions.exportDir` | `string` | -- | Каталог експорту | +| `includeDefaultMemory` | `boolean` | `true` | Автоматично індексувати `MEMORY.md` + `memory/**/*.md` | +| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | Індексувати транскрипти сесій | +| `sessions.retentionDays` | `number` | -- | Термін зберігання транскриптів | +| `sessions.exportDir` | `string` | -- | Каталог експорту | -OpenClaw надає перевагу поточним формам collection і MCP query у QMD, але -зберігає працездатність старіших випусків QMD, повертаючись до застарілих прапорців collection `--mask` -та старіших назв MCP tools за потреби. +OpenClaw віддає перевагу поточним формам колекцій QMD і запитів MCP, але +підтримує старіші випуски QMD, за потреби повертаючись до застарілих прапорців колекцій `--mask` +і старіших назв інструментів MCP. -Перевизначення моделей QMD залишаються на стороні QMD, а не в конфігурації OpenClaw. Якщо вам потрібно +Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо вам потрібно глобально перевизначити моделі QMD, задайте змінні середовища, такі як -`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у -runtime-середовищі gateway. +`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у середовищі виконання Gateway. -### Розклад оновлення +### Розклад оновлень | Ключ | Тип | Типове значення | Опис | | ------------------------- | --------- | --------------- | ------------------------------------- | | `update.interval` | `string` | `5m` | Інтервал оновлення | -| `update.debounceMs` | `number` | `15000` | Debounce змін файлів | +| `update.debounceMs` | `number` | `15000` | Debounce для змін файлів | | `update.onBoot` | `boolean` | `true` | Оновлювати під час запуску | | `update.waitForBootSync` | `boolean` | `false` | Блокувати запуск до завершення оновлення | -| `update.embedInterval` | `string` | -- | Окремий ритм embed | +| `update.embedInterval` | `string` | -- | Окрема частота ембедингів | | `update.commandTimeoutMs` | `number` | -- | Тайм-аут для команд QMD | | `update.updateTimeoutMs` | `number` | -- | Тайм-аут для операцій оновлення QMD | -| `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій embed QMD | +| `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій ембедингів QMD | ### Обмеження | Ключ | Тип | Типове значення | Опис | | ------------------------- | -------- | --------------- | ------------------------------ | | `limits.maxResults` | `number` | `6` | Максимум результатів пошуку | -| `limits.maxSnippetChars` | `number` | -- | Обмежити довжину снипета | +| `limits.maxSnippetChars` | `number` | -- | Обмежити довжину сніпета | | `limits.maxInjectedChars` | `number` | -- | Обмежити загальну кількість вставлених символів | | `limits.timeoutMs` | `number` | `4000` | Тайм-аут пошуку | -### Scope +### Область дії -Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й +Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й для [`session.sendPolicy`](/uk/gateway/configuration-reference#session): ```json5 @@ -442,21 +444,21 @@ runtime-середовищі gateway. } ``` -Постачуване типове значення дозволяє direct і channel sessions, водночас і далі забороняючи -groups. +Типова конфігурація в постачанні дозволяє прямі сесії та сесії каналів, водночас забороняючи +групи. Типове значення — лише DM. `match.keyPrefix` зіставляється з нормалізованим ключем сесії; `match.rawKeyPrefix` зіставляється з сирим ключем, включно з `agent::`. -### Citations +### Цитування -`memory.citations` застосовується до всіх backend: +`memory.citations` застосовується до всіх бекендів: | Значення | Поведінка | | ---------------- | --------------------------------------------------- | -| `auto` (типово) | Включати footer `Source: ` у снипети | -| `on` | Завжди включати footer | -| `off` | Не включати footer (шлях усе одно передається агенту внутрішньо) | +| `auto` (типово) | Додає нижній колонтитул `Source: ` у сніпети | +| `on` | Завжди додає нижній колонтитул | +| `off` | Не додає нижній колонтитул (шлях усе одно передається агенту внутрішньо) | ### Повний приклад QMD @@ -486,17 +488,17 @@ groups. Dreaming налаштовується в `plugins.entries.memory-core.config.dreaming`, а не в `agents.defaults.memorySearch`. -Dreaming виконується як один запланований прохід і використовує внутрішні фази light/deep/REM як +Dreaming працює як один запланований прохід і використовує внутрішні фази light/deep/REM як деталь реалізації. -Концептуальну поведінку та slash-команди див. у [Dreaming](/uk/concepts/dreaming). +Щодо концептуальної поведінки та slash-команд дивіться [Dreaming](/uk/concepts/dreaming). ### Налаштування користувача -| Ключ | Тип | Типове значення | Опис | -| ----------- | --------- | --------------- | ----------------------------------------------------- | -| `enabled` | `boolean` | `false` | Повністю ввімкнути або вимкнути Dreaming | -| `frequency` | `string` | `0 3 * * *` | Необов’язковий Cron-ритм для повного проходу Dreaming | +| Ключ | Тип | Типове значення | Опис | +| ---------- | --------- | --------------- | ------------------------------------------------- | +| `enabled` | `boolean` | `false` | Увімкнути або повністю вимкнути Dreaming | +| `frequency` | `string` | `0 3 * * *` | Необов’язкова Cron-частота для повного проходу Dreaming | ### Приклад @@ -519,6 +521,6 @@ Dreaming виконується як один запланований прох Примітки: -- Dreaming записує стан машини в `memory/.dreams/`. -- Dreaming записує людиночитний наративний вивід у `DREAMS.md` (або наявний `dreams.md`). -- Політика та пороги фаз light/deep/REM є внутрішньою поведінкою, а не користувацькою конфігурацією. +- Dreaming записує машинний стан у `memory/.dreams/`. +- Dreaming записує зрозумілий людині наративний вивід у `DREAMS.md` (або наявний `dreams.md`). +- Політика фаз light/deep/REM і порогові значення є внутрішньою поведінкою, а не користувацькою конфігурацією. diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index 86d1a861a..3d5333851 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-23T21:11:07Z" + generated_at: "2026-04-23T21:58:41Z" model: gpt-5.4 provider: openai - source_hash: f6b9c765c8a6a3ad668626e0787a9a94bcb250d2627594ef960ab024f229e8ca + source_hash: 3753fd6f29598318f15a34e623a06fac80430cae34d6b42ad06657a46c72fc54 source_path: reference/test.md workflow: 15 --- - Повний набір для тестування (сьюти, live, Docker): [Тестування](/uk/help/testing) -- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує типовий control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували з уже запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив порт 18789 зайнятим. -- `pnpm test:coverage`: запускає unit-сьют з покриттям V8 (через `vitest.unit.config.ts`). Це поріг покриття завантажених unit-файлів, а не покриття всіх файлів у всьому репозиторії. Пороги: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, поріг вимірює файли, завантажені unit-сьютом покриття, замість того щоб вважати всі файли split-lane source непокритими. -- `pnpm test:coverage:changed`: запускає unit coverage лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: розгортає змінені git-шляхи в scoped Vitest lanes, коли diff торкається лише routable source/test-файлів. Зміни config/setup, як і раніше, використовують запасний варіант — native root projects run — щоб зміни wiring, де потрібно, повторно запускалися ширше. -- `pnpm changed:lanes`: показує архітектурні lanes, які запускає diff відносно `origin/main`. -- `pnpm check:changed`: запускає smart changed gate для diff відносно `origin/main`. Він запускає core-роботу з core test lanes, extension-роботу з extension test lanes, роботу лише з тестами — лише з test typecheck/tests, розширює зміни в public Plugin SDK або plugin-contract до перевірки extension і залишає зміни лише в release metadata та version bump на цільових перевірках version/config/root-dependency. -- `pnpm test`: маршрутизує явні цілі file/directory через scoped Vitest lanes. Запуски без конкретної цілі використовують фіксовані shard groups і розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до shard-конфігурацій для кожного extension окремо, а не до одного гігантського root-project процесу. -- Повні та shard-запуски extension оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; подальші запуски використовують ці таймінги, щоб балансувати повільні та швидкі shards. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. -- Вибрані test-файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lanes, які залишають лише `test/setup.ts`, тоді як важкі runtime-кейси залишаються на своїх наявних lanes. -- Вибрані source helper-файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними sibling-тестами в цих легких lanes, тож малі зміни helper не змушують повторно запускати важкі runtime-backed сьюти. -- `auto-reply` тепер також розділено на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper. -- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний runner без ізоляції увімкнено по всіх конфігураціях репозиторію. +- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує порт керування за замовчуванням, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. +- `pnpm test:coverage`: запускає набір unit-тестів з покриттям V8 (через `vitest.unit.config.ts`). Це перевірка покриття unit-тестів для завантажених файлів, а не покриття всього репозиторію для всіх файлів. Порогові значення: 70% для рядків/функцій/інструкцій і 55% для гілок. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit-тестів з покриттям, замість того щоб вважати всі файли вихідного коду з розбитих lane непокритими. +- `pnpm test:coverage:changed`: запускає покриття unit-тестів лише для файлів, змінених відносно `origin/main`. +- `pnpm test:changed`: розгортає змінені шляхи git у scoped lane Vitest, коли diff торкається лише routable файлів джерела/тестів. Зміни конфігурації/налаштування, як і раніше, повертаються до нативного запуску root projects, щоб за потреби правки wiring запускали ширший прогін. +- `pnpm changed:lanes`: показує архітектурні lane, які запускаються diff відносно `origin/main`. +- `pnpm check:changed`: запускає розумну перевірку changed gate для diff відносно `origin/main`. Вона запускає core-роботи разом із core test lane, роботу над розширеннями — з extension test lane, роботу лише над тестами — лише з typecheck/tests для тестів, розгортає зміни публічного Plugin SDK або plugin-contract до перевірки розширень і залишає version bump лише в release metadata на цільових перевірках version/config/root-dependency. +- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped lane Vitest. Запуски без цілі використовують фіксовані shard-групи та розгортаються в leaf configs для локального паралельного виконання; група розширень завжди розгортається в shard-конфіги для кожного extension/plugin, а не в один великий процес root-project. +- Повні запуски та запуски shard розширень оновлюють локальні дані таймінгів у `.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` тепер також поділяється на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими top-level тестами status/token/helper. +- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний non-isolated runner увімкнено в усіх конфігураціях репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. -- `pnpm test:extensions` і `pnpm test extensions` запускають усі shards extension/plugin. Важкі channel extensions і OpenAI працюють як окремі shards; інші групи extension залишаються об’єднаними. Використовуйте `pnpm test extensions/` для одного lane вбудованого Plugin. -- `pnpm test:perf:imports`: вмикає звітування Vitest про тривалість імпорту та import-breakdown, при цьому зберігаючи scoped lane routing для явних цілей file/directory. -- `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює routed changed-mode path з native root-project run для того самого committed git diff. -- `pnpm test:perf:changed:bench -- --worktree` порівнює поточний набір змін у worktree без попереднього commit. +- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugin, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin лишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane bundled plugin. +- `pnpm test:perf:imports`: вмикає звітність Vitest щодо тривалості імпорту та деталізації імпорту, при цьому все ще використовує маршрутизацію scoped lane для явних цілей файлів/каталогів. +- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `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-профіль для головного потоку Vitest (`.artifacts/vitest-main-profile`). -- `pnpm test:perf:profile:runner`: записує CPU + heap-профілі для unit runner (`.artifacts/vitest-runner-profile`). -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf-конфігурацію Vitest для повного набору і записує згруповані дані тривалості плюс JSON/log-артефакти для кожної конфігурації. Агент продуктивності тестів використовує це як базову лінію перед спробами виправлення повільних тестів. +- `pnpm test:perf:profile:runner`: записує профілі CPU + heap для unit runner (`.artifacts/vitest-runner-profile`). +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf-конфігурацію Vitest повного набору та записує дані про тривалість за групами, а також JSON/лог-артефакти для кожної конфігурації. Агент Test Performance використовує це як базову лінію перед спробою виправити повільні тести. - `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`: запускає end-to-end smoke-тести gateway (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 keys і `LIVE=1` (або специфічних для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск. -- `pnpm test:docker:all`: один раз збирає спільний образ live-test і образ Docker E2E, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`, типово з паралелізмом 4. Налаштовуйте через `OPENCLAW_DOCKER_ALL_PARALLELISM=`. Runner припиняє планувати нові pooled lanes після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lanes, чутливі до старту або провайдера, запускаються ексклюзивно після паралельного пулу. Логи для кожного lane записуються в `.artifacts/docker-tests//`. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потребує придатного live model key (наприклад OpenAI у `~/.profile`), витягує зовнішній образ Open WebUI і не очікується, що буде настільки ж стабільним для CI, як звичайні unit/e2e сьюти. -- `pnpm test:docker:mcp-channels`: запускає seeded Gateway container і другий client container, який стартує `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, метадані вкладень, поведінку live event queue, outbound send routing і сповіщення у стилі Claude про channel + permission через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, тож smoke відображає те, що bridge фактично передає. +- Інтеграція Gateway: увімкнення за бажанням через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (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-тести provider (minimax/zai). Потрібні API-ключі та `LIVE=1` (або provider-специфічний `*_LIVE_TEST=1`) для зняття `skip`. +- `pnpm test:docker:all`: один раз збирає спільний образ для live-тестів і Docker E2E image, а потім запускає Docker smoke lane з `OPENCLAW_SKIP_DOCKER_BUILD=1` і типовим паралелізмом 4. Налаштовується через `OPENCLAW_DOCKER_ALL_PARALLELISM=`. Runner припиняє планувати нові pooled lane після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а для кожного lane діє тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane, чутливі до старту або provider, запускаються ексклюзивно після паралельного пулу. Логи для кожного lane записуються в `.artifacts/docker-tests//`. +- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксований чат через `/api/chat/completions`. Потрібен робочий live model key (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і цей сценарій не очікується стабільним у CI так, як звичайні unit/e2e сьюти. +- `pnpm test:docker:mcp-channels`: запускає seeded-контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, метадані вкладень, поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + permissions у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP-фрейми напряму, щоб smoke-тест відображав те, що міст фактично надсилає. -## Локальний PR gate +## Локальна PR-перевірка -Для локальних перевірок land/gate PR запускайте: +Для локальних перевірок перед злиттям PR запускайте: - `pnpm check:changed` - `pnpm check` @@ -54,12 +54,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` дає flaky-збої на завантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` нестабільно працює на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте проблему через `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: “Reply with a single word: ok. No punctuation or extra text.” +- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або додаткового тексту.” -Останній запуск (2025-12-31, 20 запусків): +Останній запуск (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,41 +95,41 @@ 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: - `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`: обидва пресети +- `all`: обидва preset -Вивід включає `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і підсумки max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного запуску, тож захоплення таймінгів і профілів використовує той самий harness. +Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного прогону, тож вимірювання часу та захоплення профілю використовують той самий harness. -Домовленості щодо збереженого виводу: +Умовні позначення для збереженого виводу: - `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` оновлює закомічений baseline-fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` Закомічений fixture: - `test/fixtures/cli-startup-bench.json` -- Оновити: `pnpm test:startup:bench:update` -- Порівняти поточні результати з fixture: `pnpm test:startup:bench:check` +- Оновлення: `pnpm test:startup:bench:update` +- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check` ## Onboarding E2E (Docker) -Docker необов’язковий; це потрібно лише для containerized onboarding smoke-тестів. +Docker необов’язковий; це потрібно лише для контейнеризованих onboarding smoke-тестів. -Повний cold-start flow у чистому Linux container: +Повний cold-start сценарій у чистому Linux-контейнері: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, а потім запускає gateway і виконує `openclaw health`. +Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. -## QR import smoke (Docker) +## Smoke-тест імпорту QR (Docker) -Переконується, що підтримуваний helper QR runtime завантажується в підтримуваних Docker Node runtime (типово Node 24, сумісність із Node 22): +Переконується, що підтримуваний QR runtime helper завантажується в підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22): ```bash pnpm test:docker:qr diff --git a/docs/uk/tools/image-generation.md b/docs/uk/tools/image-generation.md index 29895b19f..6cae57504 100644 --- a/docs/uk/tools/image-generation.md +++ b/docs/uk/tools/image-generation.md @@ -1,28 +1,28 @@ --- read_when: - - Генерація зображень через агента - - Налаштування providers і моделей для генерації зображень - - Розуміння параметрів інструмента image_generate -summary: Генерувати та редагувати зображення за допомогою налаштованих providers (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI) + - Генерування зображень через агента + - Налаштування provider і моделей для генерації зображень + - Розуміння параметрів інструмента `image_generate` +summary: Генеруйте та редагуйте зображення за допомогою налаштованих provider (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI) title: Генерація зображень x-i18n: - generated_at: "2026-04-23T21:15:30Z" + generated_at: "2026-04-23T21:59:24Z" model: gpt-5.4 provider: openai - source_hash: 2ca23553fa80fbc286046baa2bdb639aab76a24f2d55dc1764085f57b24be29e + source_hash: 77b104fb5e7d1a512d77493218276b9000c03a05b7579719ac9d182603d6b03e source_path: tools/image-generation.md workflow: 15 --- -Інструмент `image_generate` дає агенту змогу створювати й редагувати зображення за допомогою ваших налаштованих providers. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента. +Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою налаштованих provider. Згенеровані зображення автоматично додаються як медіавкладення у відповідь агента. -Інструмент з’являється лише тоді, коли доступний принаймні один provider генерації зображень. Якщо ви не бачите `image_generate` серед інструментів агента, налаштуйте `agents.defaults.imageGenerationModel` або задайте API-ключ provider. +Інструмент з’являється лише тоді, коли доступний принаймні один provider для генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ provider або увійдіть через OpenAI Codex OAuth. ## Швидкий старт -1. Задайте API-ключ принаймні для одного provider (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`). +1. Задайте API-ключ принаймні для одного provider (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth. 2. За бажанням задайте бажану модель: ```json5 @@ -37,24 +37,25 @@ x-i18n: } ``` -3. Попросіть агента: _"Generate an image of a friendly lobster mascot."_ +Codex OAuth використовує той самий ref моделі `openai/gpt-image-2`. Коли налаштовано профіль OAuth `openai-codex`, OpenClaw маршрутизує запити на зображення через цей самий профіль OAuth замість того, щоб спочатку пробувати `OPENAI_API_KEY`. Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API-ключ або custom/Azure base URL, знову вмикає прямий маршрут через OpenAI Images API. -Агент автоматично викличе `image_generate`. Додавання в allow-list інструментів не потрібне — він типово ввімкнений, коли доступний provider. +3. Попросіть агента: _«Згенеруй зображення дружнього робота-маскота.»_ -## Підтримувані providers +Агент автоматично викликає `image_generate`. Додавати інструмент до allow-list не потрібно — він увімкнений за замовчуванням, коли provider доступний. -| Provider | Типова модель | Підтримка редагування | API-ключ | -| ------------ | ------------------------------- | -------------------------------- | ----------------------------------------------------- | -| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` | -| OpenAI Codex | `gpt-image-2` | Так (до 4 зображень) | OpenAI Codex OAuth | -| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | -| MiniMax | `image-01` | Так (посилання на subject) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | -| ComfyUI | `workflow` | Так (1 зображення, залежить від workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud | -| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | +## Підтримувані provider -Використовуйте `action: "list"`, щоб переглянути доступні providers і моделі під час виконання: +| Provider | Модель за замовчуванням | Підтримка редагування | Автентифікація | +| -------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------ | +| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | +| MiniMax | `image-01` | Так (референс суб’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | +| ComfyUI | `workflow` | Так (1 зображення, задається workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud | +| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | +| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | + +Використовуйте `action: "list"`, щоб переглянути доступні provider і моделі під час виконання: ``` /tool image_generate action=list @@ -62,22 +63,22 @@ x-i18n: ## Параметри інструмента -| Параметр | Тип | Опис | -| ------------- | --------- | ------------------------------------------------------------------------------------- | -| `prompt` | string | Prompt для генерації зображення (обов’язковий для `action: "generate"`) | -| `action` | string | `"generate"` (типово) або `"list"` для перегляду providers | -| `model` | string | Перевизначення provider/model, наприклад `openai/gpt-image-2` | -| `image` | string | Шлях або URL одного опорного зображення для режиму редагування | -| `images` | string[] | Кілька опорних зображень для режиму редагування (до 5) | -| `size` | string | Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` | -| `aspectRatio` | string | Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | Підказка роздільної здатності: `1K`, `2K` або `4K` | -| `count` | number | Кількість зображень для генерації (1–4) | -| `filename` | string | Підказка для імені вихідного файла | +| Параметр | Тип | Опис | +| ------------ | -------- | ------------------------------------------------------------------------------------- | +| `prompt` | string | Prompt для генерації зображення (обов’язковий для `action: "generate"`) | +| `action` | string | `"generate"` (за замовчуванням) або `"list"` для перегляду provider | +| `model` | string | Перевизначення provider/моделі, наприклад `openai/gpt-image-2` | +| `image` | string | Шлях або URL одного референсного зображення для режиму редагування | +| `images` | string[] | Кілька референсних зображень для режиму редагування (до 5) | +| `size` | string | Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` | +| `aspectRatio`| string | Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | +| `resolution` | string | Підказка роздільної здатності: `1K`, `2K` або `4K` | +| `count` | number | Кількість зображень для генерації (1–4) | +| `filename` | string | Підказка для імені вихідного файлу | -Не всі providers підтримують усі параметри. Коли fallback-provider підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням переналаштовує на найближчий підтримуваний `size`, `aspectRatio` або `resolution`. Справді непідтримувані перевизначення все одно повідомляються в результаті інструмента. +Не всі provider підтримують усі параметри. Коли fallback provider підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням зіставляє запит із найближчим підтримуваним розміром, співвідношенням сторін або роздільною здатністю. Справді непідтримувані перевизначення все одно зазначаються в результаті інструмента. -Результати інструмента повідомляють застосовані налаштування. Коли OpenClaw переналаштовує геометрію під час fallback provider, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. +Результати інструмента показують застосовані налаштування. Коли OpenClaw змінює геометрію під час fallback provider, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. ## Конфігурація @@ -98,114 +99,102 @@ x-i18n: ### Порядок вибору provider -Під час генерації зображення OpenClaw пробує providers у такому порядку: +Під час генерації зображення OpenClaw пробує provider у такому порядку: -1. **Параметр `model`** з виклику інструмента (якщо агент його вказує) -2. **`imageGenerationModel.primary`** з config -3. **`imageGenerationModel.fallbacks`** у вказаному порядку -4. **Автовизначення** — використовує лише типові значення providers, підкріплені auth: - - спочатку поточний типовий provider - - далі решта зареєстрованих providers генерації зображень у порядку provider-id +1. **Параметр `model`** із виклику інструмента (якщо агент його задає) +2. **`imageGenerationModel.primary`** із конфігурації +3. **`imageGenerationModel.fallbacks`** у заданому порядку +4. **Автовизначення** — використовує лише типові значення provider, підкріплені автентифікацією: + - спочатку поточний provider за замовчуванням + - далі решта зареєстрованих provider генерації зображень у порядку provider-id -Якщо provider не спрацьовує (помилка auth, rate limit тощо), автоматично пробується наступний кандидат. Якщо не спрацювали всі, помилка містить подробиці кожної спроби. +Якщо provider завершується помилкою (помилка автентифікації, rate limit тощо), автоматично пробується наступний кандидат. Якщо не спрацьовують усі, помилка містить подробиці про кожну спробу. Примітки: -- Автовизначення враховує auth. Типове значення provider потрапляє до списку кандидатів - лише тоді, коли OpenClaw справді може автентифікувати цей provider. -- Автовизначення типово ввімкнено. Установіть - `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`. -- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих providers, - їхні типові моделі та підказки щодо auth env-var. +- Автовизначення враховує автентифікацію. Типовий provider потрапляє до списку кандидатів лише тоді, коли OpenClaw справді може автентифікувати цей provider. +- Автовизначення ввімкнене за замовчуванням. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`. +- Використовуйте `action: "list"`, щоб переглянути поточні зареєстровані provider, їхні моделі за замовчуванням і підказки щодо env var для автентифікації. ### Редагування зображень -OpenAI, Google, fal, MiniMax, ComfyUI та xAI підтримують редагування опорних зображень. Передайте шлях або URL опорного зображення: +OpenAI, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування референсних зображень. Передайте шлях або URL референсного зображення: ``` -"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" +"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg" ``` -OpenAI, Google та xAI підтримують до 5 опорних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1. +OpenAI, Google і xAI підтримують до 5 референсних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1. ### OpenAI `gpt-image-2` -Генерація зображень OpenAI типово використовує `openai/gpt-image-2`. Старішу -модель `openai/gpt-image-1` усе ще можна вибрати явно, але для нових запитів на генерацію зображень і редагування зображень через OpenAI слід використовувати `gpt-image-2`. +Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо налаштовано профіль OAuth `openai-codex`, OpenClaw повторно використовує той самий профіль OAuth, що й для моделей чату за підпискою Codex, і надсилає запит на зображення через бекенд Codex Responses; він не виконує непомітний fallback на `OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут через OpenAI Images API, явно налаштуйте `models.providers.openai` за допомогою API-ключа, custom base URL або Azure endpoint. Старішу модель `openai/gpt-image-1` усе ще можна явно вибрати, але нові запити OpenAI на генерацію та редагування зображень мають використовувати `gpt-image-2`. -`gpt-image-2` підтримує як генерацію text-to-image, так і редагування опорних зображень через той самий інструмент `image_generate`. OpenClaw передає в OpenAI `prompt`, -`count`, `size` і опорні зображення. OpenAI не отримує -`aspectRatio` або `resolution` напряму; коли можливо, OpenClaw відображає їх у -підтримуваний `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення. +`gpt-image-2` підтримує як генерацію зображень за текстом, так і редагування за референсним зображенням через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`, `count`, `size` і референсні зображення. OpenAI не отримує `aspectRatio` або `resolution` напряму; коли можливо, OpenClaw зіставляє їх із підтримуваним `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення. -Згенерувати одне landscape-зображення 4K: +Згенерувати одне панорамне 4K-зображення: ``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 ``` -Згенерувати два квадратні зображення: +Згенерувати два квадратних зображення: ``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2 ``` -Відредагувати одне локальне опорне зображення: +Відредагувати одне локальне референсне зображення: ``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 ``` -Редагування з кількома опорними зображеннями: +Редагування з кількома референсами: ``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість -`api.openai.com`, див. [Azure OpenAI endpoints](/uk/providers/openai#azure-openai-endpoints) -у документації провайдера OpenAI. +Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість `api.openai.com`, див. [Azure OpenAI endpoints](/uk/providers/openai#azure-openai-endpoints) у документації provider OpenAI. -Генерація зображень MiniMax доступна через обидва вбудовані шляхи auth MiniMax: +Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax: -- `minimax/image-01` для налаштувань через API-ключ -- `minimax-portal/image-01` для налаштувань через OAuth +- `minimax/image-01` для налаштувань з API-ключем +- `minimax-portal/image-01` для налаштувань з OAuth -## Можливості providers +## Можливості provider -| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | -| -------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ------------------------------------ | ------- | -------------------- | -| Generate | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (визначені workflow outputs) | Так (1) | Так (до 4) | -| Edit/reference | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, subject ref) | Так (1 зображення, залежить від workflow) | Ні | Так (до 5 зображень) | -| Керування size | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні | -| Aspect ratio | Ні | Так | Так (лише generate) | Так | Ні | Ні | Так | -| Resolution (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) | +| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | +| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | +| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (визначається виходами workflow) | Так (1) | Так (до 4) | +| Редагування/референс | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, референс суб’єкта) | Так (1 зображення, задається workflow) | Ні | Так (до 5 зображень) | +| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні | +| Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так | +| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) | ### xAI `grok-imagine-image` -Вбудований provider xAI використовує `/v1/images/generations` для запитів лише з prompt -і `/v1/images/edits`, коли присутній `image` або `images`. +Вбудований provider xAI використовує `/v1/images/generations` для запитів лише з prompt і `/v1/images/edits`, коли присутній `image` або `images`. - Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro` -- Count: до 4 -- Опорні зображення: один `image` або до п’яти `images` -- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` -- Resolutions: `1K`, `2K` -- Outputs: повертаються як керовані OpenClaw вкладення зображень +- Кількість: до 4 +- Референси: один `image` або до п’яти `images` +- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` +- Роздільна здатність: `1K`, `2K` +- Результати: повертаються як керовані OpenClaw вкладення зображень -OpenClaw навмисно не надає xAI-нативні `quality`, `mask`, `user` або -додаткові native-only aspect ratios, доки ці елементи керування не з’являться в спільному -крос-провайдерному контракті `image_generate`. +OpenClaw навмисно не відкриває для xAI рідні параметри `quality`, `mask`, `user` або додаткові співвідношення сторін, доступні лише нативно, доки ці елементи керування не з’являться в спільному міжprovider-ному контракті `image_generate`. ## Пов’язане -- [Огляд Tools](/uk/tools) — усі доступні інструменти агента +- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента - [fal](/uk/providers/fal) — налаштування provider зображень і відео fal -- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та Comfy Cloud workflow +- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та workflow Comfy Cloud - [Google (Gemini)](/uk/providers/google) — налаштування provider зображень Gemini - [MiniMax](/uk/providers/minimax) — налаштування provider зображень MiniMax - [OpenAI](/uk/providers/openai) — налаштування provider OpenAI Images -- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та speech у Vydra -- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, search, виконання коду та TTS -- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — config `imageGenerationModel` -- [Models](/uk/concepts/models) — конфігурація моделей і failover +- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra +- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS +- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `imageGenerationModel` +- [Моделі](/uk/concepts/models) — конфігурація моделей і failover