From 3e741b1d4d0e55c74ddd7cdaebcba3a7d19f8f58 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 7 Apr 2026 08:10:48 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 655 ++++++++++++++++++++-------------------- 1 file changed, 332 insertions(+), 323 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 0f5e4b3fc..6489baabb 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - - Запуск тестів локально або в CI + - Локальний запуск тестів або запуск у CI - Додавання регресій для багів моделей/провайдерів - - Налагодження поведінки gateway та агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що покриває кожен тест' + - Налагодження поведінки шлюзу та агента +summary: 'Набір тестування: набори unit/e2e/live, Docker-ранери та що покриває кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-07T07:08:10Z" + generated_at: "2026-04-07T08:10:48Z" model: gpt-5.4 provider: openai - source_hash: 9bd5fbc91435d7acd94758fa4a00af5a80363ddebc715b8731bb508b9e5d6d28 + source_hash: f7ae891b3ad878e4295f94a385e95dbcfdb26c23c2c257984148708894c9546b source_path: help/testing.md workflow: 15 --- @@ -20,10 +20,10 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Цей документ — посібник «як ми тестуємо»: -- Що покриває кожен набір тестів (і що він навмисно _не_ покриває) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) +- Що покриває кожен набір (і що він навмисно _не_ покриває) +- Які команди запускати для типових сценаріїв (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Як додавати регресії для реальних проблем із моделями/провайдерами ## Швидкий старт @@ -35,110 +35,110 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - QA-сайт на базі Docker: `pnpm qa:lab:up` -Коли ви змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете більше впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + gateway-перевірки tools/images): `pnpm test:live` +- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` - Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один збійний сценарій, краще звужувати live-тести через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): +Думайте про набори як про «зростаючу реалістичність» (і зростаючу нестабільність/вартість): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` -- Охоплення: +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped-проєктах Vitest +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Обсяг: - Чисті unit-тести - - In-process integration-тести (gateway auth, routing, tooling, parsing, config) + - Внутрішньопроцесні integration-тести (gateway auth, routing, tooling, parsing, config) - Детерміновані регресії для відомих багів - Очікування: - - Запускаються в CI + - Запускається в CI - Реальні ключі не потрібні - - Мають бути швидкими й стабільними -- Примітка про проєкти: - - Ненаправлений `pnpm test` тепер запускає десять менших shard-конфігів (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` як і раніше використовує граф native root `vitest.config.ts`, тому що multi-shard цикл watch непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/каталог через scoped-lane, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не платить повну ціну запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-lane, коли diff торкається лише routable source/test-файлів; зміни config/setup як і раніше повертаються до широкого повторного запуску root-project. - - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lane, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли лишаються на наявних lane. - - Вибрані helper-source файли `plugin-sdk` і `commands` у режимі changed також мапляться на явні sibling-тести в цих легких lane, тому зміни 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-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі `auto-reply`/extension виснажувати не пов’язані набори. + - `pnpm test --watch` і далі використовує граф проєктів native root `vitest.config.ts`, бо цикл watch із багатьма shard не є практичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped-lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-lanes, коли diff торкається лише routable source/test-файлів; зміни config/setup усе ще повертаються до широкого повторного запуску root-project. + - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними sibling-тестами в цих легких lanes, щоб зміни helper не запускали повторно весь важкий набір для цього каталогу. + - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply впливати на дешеві тести status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, + - Коли ви змінюєте вхідні дані discovery message-tool або runtime context compaction, зберігайте обидва рівні покриття. - - Додавайте цільові helper-регресії для чистих меж routing/normalization. - - Також підтримуйте здоровий стан integration-наборів embedded runner: + - Додавайте фокусні helper-регресії для чистих меж routing/normalization. + - Також підтримуйте в доброму стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, and `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка compaction як і раніше проходять + - Ці набори перевіряють, що scoped id та поведінка compaction і далі проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. -- Примітка про pool: +- Примітка про пул: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e та live-конфігах. - - Root UI lane зберігає свій `jsdom` setup та optimizer, але тепер також працює на спільному non-isolated runner. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e та live configs. + - Root UI lane зберігає свої `jsdom` setup і optimizer, але тепер також працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для child Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. + - Спільний launcher `scripts/run-vitest.mjs` тепер також додає `--no-maglev` для дочірніх Node-процесів Vitest типово, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти поведінку зі стандартним V8. - Примітка про швидку локальну ітерацію: - - `pnpm test:changed` маршрутизує через scoped-lane, коли змінені шляхи однозначно відповідають меншому набору. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Локальне автоскейлінг workers тепер навмисно консервативніше й також зменшується, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в режимі changed лишалися коректними, коли змінюється wiring тестів. - - Конфігурація зберігає ввімкненим `OPENCLAW_VITEST_FS_MODULE_CACHE` на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. + - `pnpm test:changed` маршрутизується через scoped-lanes, коли змінені шляхи однозначно зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею worker. + - Автомасштабування локальних worker тепер навмисно більш консервативне й також відступає, коли середнє навантаження хоста вже високе, тож кілька паралельних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/конфіг-файли як `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється 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, а також вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання файлами, зміненими від `origin/main`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього зафіксованого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфіг Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU головного потоку для накладних витрат запуску й трансформацій Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner-а для unit-набору з вимкненим паралелізмом файлів. +- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для накладних витрат запуску та transform Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим паралелізмом файлів. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові параметри runtime: - - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. - - Використовує adaptive workers (CI: до 2, локально: 1 за замовчуванням). - - Типово запускається в silent-режимі, щоб зменшити накладні витрати консолі I/O. -- Корисні override: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). +- Типові параметри виконання: + - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. + - Використовує адаптивну кількість worker-ів (CI: до 2, локально: 1 типово). + - Типово запускається в тихому режимі, щоб зменшити накладні витрати на console I/O. +- Корисні перевизначення: + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість worker-ів (обмежено 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. -- Охоплення: - - Наскрізна поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing вузлів і більш важкі мережеві сценарії +- Обсяг: + - Наскрізна поведінка multi-instance gateway + - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження - Очікування: - - Запускаються в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Мають більше рухомих частин, ніж unit-тести (можуть бути повільнішими) + - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: smoke backend-а OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Охоплення: - - Запускає ізольований OpenShell gateway на хості через Docker - - Створює sandbox з тимчасового локального Dockerfile +- Обсяг: + - Запускає ізольований gateway OpenShell на хості через Docker + - Створює sandbox із тимчасового локального Dockerfile - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку файлової системи з remote-canonical через sandbox fs bridge + - Перевіряє canonical-поведінку віддаленої файлової системи через fs bridge sandbox-а - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і працездатний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox -- Корисні override: + - Лише opt-in; не є частиною типового запуску `pnpm test:e2e` + - Потрібні локальний `openshell` CLI і робочий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox +- Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний CLI binary або wrapper-script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний двійковий файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) @@ -146,139 +146,139 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Охоплення: +- Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін форматів провайдера, особливостей tool-calling, проблем auth і поведінки rate limit + - Виявлення змін формату провайдера, особливостей tool-calling, проблем автентифікації та поведінки rate limit - Очікування: - - Навмисно нестабільні для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштують грошей / використовують rate limit + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски source-ять `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth матеріали у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний home-каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: він залишає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і приглушує bootstrap-логи gateway/Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежить від провайдера): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях про rate limit. +- Live-запуски джерелять `~/.profile`, щоб підхопити відсутні API-ключі. +- Типово live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали в тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.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`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера залишалися помітно активними, навіть коли перехоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. + - Налаштуйте heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо багато змінювали) -- Торкаєтесь мережі gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / tool calling: запустіть звужений `pnpm test:live` +- Редагування логіки/тестів: запустіть `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінювали) +- Зміни в gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагодження «мій бот не працює» / збоїв, характерних для провайдера / tool calling: запустіть звужений `pnpm test:live` -## Live: перевірка можливостей Android node +## Live: огляд можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` - Мета: викликати **кожну команду, яку зараз рекламує** підключений Android node, і перевірити поведінку контракту команди. -- Охоплення: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не pair-ить застосунок). - - Перевірка `node.invoke` gateway команда за командою для вибраного Android node. +- Обсяг: + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing застосунку). + - Покомандна валідація gateway `node.invoke` для вибраного Android node. - Обов’язкова попередня підготовка: - - Android-застосунок уже підключено й pair-ено до gateway. + - Android-застосунок уже підключений і paired із gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/погодження на захоплення для можливостей, які ви очікуєте як успішні. -- Необов’язкові override цілі: + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішними. +- Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke моделей (profile keys) +## Live: smoke моделі (ключі профілів) -Live-тести розділені на два шари, щоб можна було ізолювати збої: +Live-тести розділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи провайдер/модель узагалі може відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). +- «Пряма модель» показує, чи може провайдер/модель взагалі відповісти з даним ключем. +- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (сесії, історія, tools, політика sandbox тощо). ### Шар 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перелічити знайдені моделі + - Перелічити виявлені моделі - Використати `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` щоб запускати сучасний 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=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="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: profile store і резервні env-значення - - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - Типово: сховище профілів і резервні env-значення + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «зламаний pipeline агента gateway» - - Містить невеликі, ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + tool-call flows) + - Відокремлює «API провайдера зламане / ключ невалідний» від «зламаний pipeline gateway agent» + - Містить малі ізольовані регресії (приклад: replay reasoning OpenAI Responses/Codex Responses + tool-call flows) -### Шар 2: Gateway + smoke dev agent-а (що насправді робить "@openclaw") +### Шар 2: smoke gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/змінити session `agent:dev:*` (override моделі для кожного запуску) + - Створити/патчити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) - Ітеруватися по моделях-із-ключами й перевіряти: - «змістовну» відповідь (без tools) - - що працює справжній виклик tool-а (read probe) - - необов’язкові додаткові перевірки tools (exec+read probe) - - що шляхи регресії OpenAI (лише tool-call → наступний крок) продовжують працювати -- Деталі probe-ів (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його через `read`. - - image probe: тест додає згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - що працює реальний виклик tool (read probe) + - необов’язкові додаткові tool probes (exec+read probe) + - що шляхи регресій OpenAI (лише tool-call → follow-up) залишаються працездатними +- Деталі probe (щоб ви могли швидко пояснити збої): + - probe `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - probe `exec+read`: тест просить агента `exec`-ом записати nonce у тимчасовий файл, а потім `read`-нути його назад. + - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - Типово: сучасний 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"` (або список через кому), щоб звузити вибір -- Як вибирати провайдерів (уникати «усе OpenRouter»): + - Типово: 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"` (або список через кому), щоб звузити набір +- Як вибирати провайдерів (уникнути «усе OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки tool + image завжди ввімкнені в цьому live-тесті: - - `read` probe + `exec+read` probe (навантаження на tools) - - image probe запускається, коли модель повідомляє про підтримку image input +- Tool + image probes у цьому live-тесті завжди увімкнені: + - probe `read` + probe `exec+read` (навантаження на tools) + - image probe запускається, коли модель заявляє про підтримку image input - Потік (на високому рівні): - - Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - Embedded agent пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (толерантність OCR: незначні помилки дозволені) + - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме можна протестувати на вашій машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke для CLI backend (Codex CLI або інші локальні CLI) +## Live: smoke backend-а CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + agent за допомогою локального CLI backend, не торкаючись вашої типової config. +- Мета: перевірити pipeline 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` - Типові значення: - - Модель: `codex-cli/gpt-5.4` - - Команда: `codex` - - Args: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]` -- Override-и (необов’язково): + - Типовий provider/model: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image походить із метаданих plugin-а-власника CLI backend-а. +- Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `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` щоб надіслати справжній image attachment (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи image-файлів як CLI args замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати способом передавання image args, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий крок і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне image-attachment (шляхи впроваджуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до image-файлів як CLI args замість вбудовування в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати передаванням image args, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити flow відновлення. Приклад: @@ -294,37 +294,45 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` +Рецепти Docker для одного провайдера: + +```bash +pnpm test:docker:live-cli-backend:claude +pnpm test:docker:live-cli-backend:codex +pnpm test:docker:live-cli-backend:gemini +``` + Примітки: - Docker-ранер розташовано в `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend всередині Docker-образу репозиторію від імені non-root користувача `node`. -- Для `codex-cli` він встановлює Linux-пакет `@openai/codex` у кешований записуваний prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- Він запускає 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`). ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний flow прив’язки ACP conversation із live ACP agent: +- Мета: перевірити реальний flow conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну conversation message-channel на місці - - надіслати звичайний follow-up у цій самій conversation - - переконатися, що follow-up потрапляє до transcript прив’язаної ACP session + - прив’язати синтетичну message-channel conversation на місці + - надіслати звичайний follow-up у тій самій conversation + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agent-и в Docker: `claude,codex,gemini` + - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - Синтетичний channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` -- Override-и: +- Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Цей lane використовує поверхню gateway `chat.send` з полями synthetic originating-route лише для admin, щоб тести могли прикріплювати контекст message-channel, не вдаючи зовнішню доставку. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent-ів plugin `acpx` для вибраного ACP harness agent. + - Ця lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли приєднати контекст message-channel без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів plugin-а `acpx` для вибраного ACP harness agent. Приклад: @@ -340,7 +348,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent-а: +Рецепти Docker для одного агента: ```bash pnpm test:docker:live-acp-bind:claude @@ -353,12 +361,12 @@ pnpm test:docker:live-acp-bind:gemini - Docker-ранер розташовано в `scripts/test-live-acp-bind-docker.sh`. - Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agent-ів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він source-ить `~/.profile`, переносить відповідні auth-матеріали CLI у контейнер, встановлює `acpx` у записуваний npm prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав доступність provider env vars із source-нутого profile для дочірнього harness CLI. +- Він джерелить `~/.profile`, готує відповідні auth-матеріали CLI всередині контейнера, встановлює `acpx` у записуваний npm-префікс, а потім встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. +- Усередині Docker ранер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із джереленого профілю доступними для дочірнього harness CLI. ### Рекомендовані live-рецепти -Найшвидші й найменш нестабільні — вузькі, явні allowlist-и: +Вузькі явні allowlist-и — найшвидші та найменш нестабільні: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -366,31 +374,31 @@ pnpm test:docker:live-acp-bind:gemini - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling у кількох провайдерів: +- Tool calling через кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,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 (Gemini API key + Antigravity): - - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API-ключ Gemini + Antigravity): + - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: -- `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent-а в стилі Cloud Code Assist). +- `google/...` використовує Gemini API (API-ключ). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента у стилі Cloud Code Assist). - `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає хостований Gemini API від Google через HTTP (API key / profile auth); це те, що більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний binary `gemini`; у нього власна auth і він може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / auth профілю); це те, що більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (live — opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» не існує (live — це opt-in), але ось **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. ### Сучасний набір smoke (tool calling + image) Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: -- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - 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) @@ -403,7 +411,7 @@ pnpm test:docker:live-acp-bind:gemini ### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть принаймні одну модель на кожне сімейство провайдерів: +Вибирайте щонайменше одну на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -413,79 +421,79 @@ pnpm test:docker:live-acp-bind:gemini Необов’язкове додаткове покриття (було б добре мати): -- xAI: `xai/grok-4` (або найновішу доступну) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас ввімкнено) +- xAI: `xai/grok-4` (або найновіша доступна) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання image (attachment → мультимодальне повідомлення) +### Vision: надсилання зображень (attachment → multimodal message) -Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб виконати image probe. -### Aggregators / альтернативні gateway +### Агрегатори / альтернативні gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти підходящих кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити в live-матрицю (якщо у вас є облікові дані/config): +Більше провайдерів, які можна включити в live-матрицю (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoint-и): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (кастомні endpoints): `minimax` (хмара/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко зафіксувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс наявні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як CLI. Практичні наслідки: +Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест повідомляє «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. -- Auth-профілі для кожного agent-а: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) -- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Legacy state dir: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище profile-key) -- Локальні live-запуски типово копіюють активну config, файли `auth-profiles.json` для кожного agent-а, legacy `credentials/` і підтримувані auth-каталоги зовнішніх CLI у тимчасовий test home; override-и шляхів `agents.*.workspace` / `agentDir` прибираються в цій staged config, щоб probe-и не працювали у вашому реальному workspace хоста. +- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог legacy-стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо наявний, але не є основним сховищем ключів профілів) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні CLI auth-каталоги в тимчасовий test home; перевизначення шляхів `agents.*.workspace` / `agentDir` вилучаються з цієї staged-конфігурації, щоб probes не торкалися вашого реального workspace хоста. Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live Deepgram (аудіотранскрипція) +## Deepgram live (транскрипція аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live BytePlus coding plan +## BytePlus coding plan live - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Необов’язковий override моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live для ComfyUI workflow media +## ComfyUI workflow media live - Тест: `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` - - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні comfy workflow, polling, downloads або реєстрації plugin +- Обсяг: + - Перевіряє вбудовані шляхи comfy image, video і `music_generate` + - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Корисно після змін у поданні workflow comfy, polling, завантаженнях або реєстрації plugin-а -## Live генерація зображень +## Image generation live - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` -- Охоплення: - - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env vars провайдера з вашої login shell (`~/.profile`) перед probe +- Обсяг: + - Перелічує кожен зареєстрований provider plugin для генерації зображень + - Завантажує відсутні env-змінні провайдерів із вашої shell-взаємодії входу (`~/.profile`) перед перевіркою - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатного auth/profile/model - - Проганяє стандартні варіанти генерації зображень через спільну runtime-capability: + - Пропускає провайдерів без придатної auth/profile/model + - Запускає стандартні варіанти генерації зображень через спільну runtime-capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, що покриваються: +- Поточні вбудовані провайдери в покритті: - `openai` - `google` - Необов’язкове звуження: @@ -493,71 +501,71 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати override-и лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Live генерація музики +## Music 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` -- Охоплення: - - Перевіряє спільний вбудований шлях провайдера генерації музики - - Наразі охоплює Google і MiniMax - - Завантажує env vars провайдера з вашої login shell (`~/.profile`) перед probe +- Обсяг: + - Перевіряє спільний шлях вбудованих провайдерів генерації музики + - Наразі покриває Google і MiniMax + - Завантажує env-змінні провайдерів із вашої shell-взаємодії входу (`~/.profile`) перед перевіркою - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатного auth/profile/model - - Запускає обидва оголошені режими runtime, коли вони доступні: - - `generate` з input лише у вигляді prompt + - Пропускає провайдерів без придатної auth/profile/model + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` із лише prompt-входом - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного lane: + - Поточне покриття shared-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+"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати override-и лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Live генерація відео +## Video 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` -- Охоплення: - - Перевіряє спільний вбудований шлях провайдера генерації відео - - Завантажує env vars провайдера з вашої login shell (`~/.profile`) перед probe +- Обсяг: + - Перевіряє спільний шлях вбудованих провайдерів генерації відео + - Завантажує env-змінні провайдерів із вашої shell-взаємодії входу (`~/.profile`) перед перевіркою - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатного auth/profile/model - - Запускає обидва оголошені режими runtime, коли вони доступні: - - `generate` з input лише у вигляді prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільному sweep - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: - - `vydra`, тому що вбудований `veo3` працює лише з текстом, а вбудований `kling` вимагає віддалений image URL - - Покриття Vydra для конкретного провайдера: + - Пропускає провайдерів без придатної auth/profile/model + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` із лише prompt-входом + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає локальний image input на основі buffer у спільному огляді + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає локальний video input на основі buffer у спільному огляді + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному огляді: + - `vydra`, бо вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений image 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 з віддаленим image URL + - цей файл запускає `veo3` text-to-video плюс lane `kling`, яка типово використовує fixture віддаленого image URL - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз вимагають віддалені reference URL `http(s)` / MP4 - - `google`, тому що поточний спільний lane Gemini/Veo використовує локальний input на основі buffer, а цей шлях у спільному sweep не приймається - - `openai`, тому що поточний спільний lane не гарантує org-specific доступ до video inpaint/remix + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному огляді: + - `alibaba`, `qwen`, `xai`, бо ці шляхи зараз вимагають віддалені reference URL `http(s)` / MP4 + - `google`, бо поточна спільна lane Gemini/Veo використовує локальний input на основі buffer, і цей шлях не приймається в межах спільного огляду + - `openai`, бо поточна спільна lane не гарантує наявність доступу до video inpaint/remix, специфічного для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати override-и лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Harness для live media +## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один native entrypoint репозиторію - - Автоматично завантажує відсутні env vars провайдерів із `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатний auth - - Повторно використовує `scripts/test-live.mjs`, щоб поведінка heartbeat і quiet-mode залишалася сталою + - Запускає спільні image, music і video live-набори через один repo-native 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` @@ -568,122 +576,123 @@ Live-тести знаходять облікові дані так само, я Ці Docker-ранери поділяються на дві групи: -- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм profile-key live-файл всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний config dir і workspace (і source-ючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери типово мають менший smoke-ліміт, щоб повний 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`, а потім повторно використовує його для двох live Docker-lane. -- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` підіймають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + вам явно потрібне більше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane live. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють integration-шляхи вищого рівня. -Live-model Docker-ранери також bind-mount-ять лише потрібні home-каталоги auth CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени, не змінюючи host auth store: +Ранери Docker для live-моделей також bind-mount лише потрібні CLI auth-home-и (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змінення auth-store хоста: - Прямі моделі: `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 backend-а CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-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`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст MCP channel (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (install smoke + псевдонім `/plugin` + семантика restart набору Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережева взаємодія gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke install + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Live-model Docker-ранери також bind-mount-ять поточний checkout лише для читання і -переносять його в тимчасовий workdir усередині контейнера. Це дає змогу тримати runtime-образ -компактним, але все одно запускати Vitest точно на вашому локальному source/config. -Крок staging пропускає великі локальні кеші та артефакти збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні каталоги `.build` застосунків або -каталоги виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинозалежних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, тож gateway live-probe-и не запускають -реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе одно запускає `pnpm test:live`, тож також передавайте +Ранери Docker для live-моделей також bind-mount-ять поточний checkout лише для читання й +stage-ять його в тимчасовий workdir усередині контейнера. Це робить runtime +image компактним, водночас усе ще дозволяючи запускати Vitest точно на ваших +локальних source/config. +Під час stage-прокладання пропускаються великі локальні кеші та результати збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги +`.build` або результати Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live-probes не запускали +реальні channel-worker-и Telegram/Discord/etc. усередині контейнера. +`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, входить через +live-покриття з цієї Docker-lane. +`test:docker:openwebui` — це smoke перевірки сумісності вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, +запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження -образу Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. -Цей lane очікує наявний придатний live-ключ моделі, і `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Docker-ізольованих запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний chat-запит через proxy `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, бо Docker може потребувати завантаження +image Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. +Ця lane очікує наявності придатного live-ключа моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` типово) — це основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON-payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він підіймає seeded Gateway -контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих conversation, читання transcript, метадані attachment, -поведінку черги live events, маршрутизацію вихідного надсилання, а також channel + -сповіщення про permissions у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -напряму інспектує raw stdio MCP frames, тож smoke перевіряє те, що -міст реально випромінює, а не лише те, що випадково показує конкретний client SDK. +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord або iMessage. Він піднімає seeded Gateway +container, запускає другий container, який виконує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих conversation, читання transcript-ів, metadata attachment-ів, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення у стилі Claude про channel + +permissions через реальний stdio MCP bridge. Перевірка notification +безпосередньо аналізує сирі stdio MCP frames, тож цей smoke перевіряє саме те, що +bridge реально випромінює, а не лише те, що випадково показує конкретний client SDK. -Ручна smoke-перевірка plain-language thread ACP (не CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв і сценаріїв налагодження. Він може знову знадобитися для валідації маршрутизації thread ACP, тому не видаляйте його. -Корисні env vars: +Корисні env-змінні: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і source-иться перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI всередині Docker -- Зовнішні auth-каталоги/файли CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і джерелиться перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли auth CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ручний override: `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_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) + - Перевизначення вручну: `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_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 +- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити nonce-check prompt, використаний smoke Open WebUI +- `OPENWEBUI_IMAGE=...` щоб перевизначити pinned tag image Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли потрібна також перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки документації: `pnpm check:docs`. +Запускайте повну валідацію прив’язок Mintlify, коли вам також потрібні перевірки внутрішньосторінкових заголовків: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Tool calling gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (сценарій: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (сценарій: "runs wizard over ws and writes auth token config") +- Gateway tool calling (mock OpenAI, реальний gateway + цикл agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway wizard (WS `wizard.start`/`wizard.next`, записує config + примусову auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Evals надійності agent-а (Skills) +## Оцінювання надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «evals надійності agent-а»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні flow майстра, які перевіряють wiring session і ефекти config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний gateway + цикл agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють прив’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для skills (див. [Skills](/uk/tools/skills)): -- **Decisioning:** коли Skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Compliance:** чи читає agent `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/args? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tools, перенесення history сесії та межі sandbox. +- **Прийняття рішень:** коли skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. -Майбутні eval-и мають передусім залишатися детермінованими: +Майбутні eval-и мають насамперед залишатися детермінованими: -- Scenario runner із mock-провайдерами для перевірки викликів tools + їхнього порядку, читання skill-файлів і wiring session. -- Невеликий набір сценаріїв, сфокусованих на Skills (використати чи уникнути, gate-инг, injection у prompt). -- Необов’язкові live eval-и (opt-in, під захистом env) лише після того, як буде готовий набір, безпечний для CI. +- Runner сценаріїв, який використовує mock-провайдерів для перевірки tool calls + їх порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, сфокусованих на skills (використати чи уникнути, gate, prompt injection). +- Необов’язкові live-eval-и (opt-in, керовані env) лише після того, як буде готовий безпечний для CI набір. -## Contract-тести (форма plugin і channel) +## Contract tests (форма plugin-ів і channel-ів) -Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму interface-контракту. Вони проходять по всіх виявлених plugins і запускають набір -перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте команди contract явно, -коли торкаєтесь спільних поверхонь channel або provider. +Contract tests перевіряють, що кожен зареєстрований plugin і channel відповідає +контракту свого інтерфейсу. Вони ітеруються по всіх виявлених plugin-ах і запускають набір +перевірок форми та поведінки. Типова unit-lane `pnpm test` навмисно +пропускає ці спільні файли seam і smoke; запускайте contract-команди явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -695,53 +704,53 @@ Contract-тести перевіряють, що кожен зареєстров Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) +- **plugin** - Базова форма plugin-а (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки session +- **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка thread ID -- **directory** - API directory/roster -- **group-policy** - Забезпечення group policy +- **threading** - Обробка Thread ID +- **directory** - API каталогу/реєстру +- **group-policy** - Забезпечення групової політики -### Контракти status provider-а +### Контракти status провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. - **status** - Перевірки status channel -- **registry** - Форма registry plugin-ів +- **registry** - Форма реєстру plugin-ів -### Контракти provider-а +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт flow auth -- **auth-choice** - Вибір/селекція auth +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/selection auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin-ів - **loader** - Завантаження plugin-ів -- **runtime** - Runtime provider-а +- **runtime** - Runtime провайдера - **shape** - Форма/інтерфейс plugin-а - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export-ів або subpath-ів `plugin-sdk` -- Після додавання або зміни channel або provider plugin-а -- Після рефакторингу реєстрації plugin-ів або discovery +- Після зміни export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel чи provider plugin-а +- Після рефакторингу реєстрації або discovery plugin-ів -Contract-тести запускаються в CI і не потребують реальних API-ключів. +Contract tests запускаються в CI й не потребують реальних API-ключів. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо можливо (mock/stub провайдер або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Надавайте перевагу найменшому шару, який ловить баг: - - баг перетворення/відтворення запиту провайдера → direct models test +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або зафіксуйте точну трансформацію форми запиту) +- Якщо це за своєю природою можливо лише в live (rate limits, політики auth), зберігайте live-тест вузьким і opt-in через env-змінні +- Краще націлюватися на найменший шар, який виявляє баг: + - баг перетворення/відтворення запиту провайдера → тест прямих моделей - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Guardrail обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибірковій цілі на кожен клас SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на не класифікованих target id, щоб нові класи не можна було мовчки пропустити. +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити.