From 48ee209ddfcd97a6efa374fb7b620ea067db515f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 09:57:41 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 659 ++++++++++++++++++++-------------------- 1 file changed, 330 insertions(+), 329 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 2c7c73cec..96a1ebbdb 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,27 +1,27 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделі/провайдера + - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки шлюзу й агента -summary: 'Набір для тестування: модульні/e2e/live набори, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, виконавці Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-09T22:54:33Z" + generated_at: "2026-04-10T09:54:19Z" model: gpt-5.4 provider: openai - source_hash: 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4 + source_hash: 8ab72e60eb2eea352a117b914a4da24f4dac6233d7fcfd394b7e19c3ccefd97b source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір виконавців Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) +- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів - Як додавати регресійні тести для реальних проблем із моделями/провайдерами @@ -30,99 +30,99 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією помилкою спочатку надавайте перевагу цільовим запускам. -- QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-ланка на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Під час ітерацій над однією помилкою спершу віддавайте перевагу таргетованим запускам. +- QA-сайт на основі Docker: `pnpm qa:lab:up` +- QA-lane на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете мати додаткову впевненість: +Коли ви змінюєте тести або хочете більше впевненості: -- Gate покриття: `pnpm test:coverage` +- Coverage gate: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Набір live (моделі + перевірки інструментів/зображень шлюзу): `pnpm test:live` +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: якщо вам потрібен лише один проблемний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. -## Спеціалізовані QA-ранери +## Виконавці, специфічні для QA -Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди використовуються поряд з основними наборами тестів, коли вам потрібна реалістичність QA-lab: - `pnpm openclaw qa suite` - - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - Запускає сценарії QA на основі репозиторію безпосередньо на хості. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір у disposable Linux VM Multipass. + - Запускає той самий набір QA у тимчасовій Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані QA-входи автентифікації, які практичні для guest: + - Live-запуски передають до гостьової системи підтримувані вхідні дані автентифікації QA, які там практично використовувати: ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, - якщо вони присутні. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у + якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. + - Записує звичайний звіт і підсумок QA, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на основі Docker для QA-роботи в операторському стилі. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про ці набори як про «зростання реалістичності» (і зростання нестабільності/вартості): -### Unit / integration (типовий) +### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest-проєктах -- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted `ui` node-тести, які охоплює `vitest.unit.config.ts` -- Обсяг: - - Чисті модульні тести - - In-process інтеграційні тести (gateway auth, routing, tooling, parsing, config) - - Детерміновані регресії для відомих багів +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) через наявні scoped Vitest projects +- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted `ui` node-тести, охоплені `vitest.unit.config.ts` +- Охоплення: + - Чисті unit-тести + - In-process integration-тести (автентифікація шлюзу, маршрутизація, інструменти, парсинг, конфігурація) + - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка щодо проєктів: - - Ненаправлений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує граф проєктів native root `vitest.config.ts`, оскільки цикл спостереження з кількома 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-mode на явні sibling-тести в цих легких lanes, тож редагування helper-ів не спричиняє повторний запуск повного важкого набору для цього каталогу. - - `auto-reply` тепер має три спеціальні кошики: core helper-і верхнього рівня, інтеграційні тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply осторонь дешевих тестів status/chunk/token. -- Примітка щодо embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime context compaction, +- Примітка про projects: + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що цикл спостереження з кількома 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 зачіпає лише source/test-файли, які можна маршрутизувати; зміни config/setup усе ще повертаються до широкого повторного запуску root-project. + - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі полегшені lanes, які пропускають `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime лишаються на наявних lanes. + - Вибрані допоміжні source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними 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 context ущільнення, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте в належному стані інтеграційні набори embedded runner: + - Додавайте сфокусовані регресії helper для чистих меж маршрутизації/нормалізації. + - Також підтримуйте справність integration-наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка compaction усе ще проходять + - Ці набори перевіряють, що scoped id і поведінка ущільнення все ще проходять через реальні шляхи `run.ts` / `compact.ts`; самих лише helper-тестів - недостатньо як заміни для цих інтеграційних шляхів. -- Примітка щодо pool: + недостатньо як заміни цих integration-шляхів. +- Примітка про пул: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e та live configs. - - Root UI lane зберігає своє налаштування `jsdom` та optimizer, але тепер теж працює на спільному non-isolated runner. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. + - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер також працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка щодо швидкої локальної ітерації: +- Примітка про швидкі локальні ітерації: - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи однозначно відповідають меншому набору. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості воркерів. - - Автомасштабування локальних воркерів тепер навмисно консервативне й також зменшує активність, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків 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:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею на кількість worker. + - Автомасштабування локальних worker тепер навмисно консервативне і також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в changed-mode лишалися коректними, коли змінюється wiring тестів. + - Конфігурація зберігає увімкненим `OPENCLAW_VITEST_FS_MODULE_CACHE` на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. +- Примітка про налагодження продуктивності: + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту та вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд файлами, зміненими відносно `origin/main`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project path для цього зафіксованого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU main-thread для накладних витрат запуску й transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим file parallelism. +- `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root Vitest config. + - `pnpm test:perf:profile:main` записує CPU profile головного потоку для накладних витрат запуску та трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для unit-набору з вимкненим файловим паралелізмом. ### E2E (gateway smoke) @@ -130,36 +130,36 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Типові параметри runtime: - - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: типово 1). - - Типово запускається в тихому режимі, щоб зменшити витрати на I/O консолі. + - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість worker (CI: до 2, локально: 1 типово). + - Типово запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` — примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` — знову ввімкнути докладний консольний вивід. -- Обсяг: - - End-to-end поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість worker (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. +- Охоплення: + - End-to-end-поведінка шлюзу з кількома екземплярами + - Поверхні WebSocket/HTTP, сполучення вузлів і важчий мережевий стек - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у модульних тестах (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестів (може бути повільніше) -### E2E: smoke OpenShell backend +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker +- Охоплення: + - Запускає ізольований шлюз OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє OpenShell backend в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Верифікує remote-canonical поведінку файлової системи через bridge fs sandbox + - Перевіряє backend OpenShell OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє канонічну поведінку віддаленої файлової системи через міст fs sandbox - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і робочий Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, потім знищує тестовий gateway і sandbox + - Лише за явного ввімкнення; не входить до типового запуску `pnpm test:e2e` + - Потрібні локальний CLI `openshell` і робочий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий шлюз і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1` — увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` — вказати нестандартний CLI-бінарник або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) @@ -167,55 +167,55 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Обсяг: - - «Чи працює цей провайдер/модель _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику tools, проблем auth і поведінки rate limit +- Охоплення: + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем автентифікації та поведінки за rate limit - Очікування: - - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits + - Навмисно нестабільні для CI (реальні мережі, реальні політики провайдерів, квоти, відмови) + - Коштують грошей / споживають rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють конфігурацію/матеріали auth у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує журнали запуску 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. +- Live-запуски завантажують `~/.profile`, щоб підхопити відсутні API-ключі. +- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth до тимчасової домашньої теки тесту, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували вашу реальну домашню теку. +- `pnpm test:live` тепер типово використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap шлюзу/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 прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу до stderr, тому під час тривалих викликів провайдерів видно, що виконання активне, навіть коли Vitest тихо перехоплює консоль. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/шлюзу транслювалися одразу під час live-запусків. + - Налаштувати heartbeat для прямих моделей можна через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштувати heartbeat для шлюзу/перевірок можна через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Скористайтеся цією таблицею рішень: +Використовуйте таку таблицю рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтеся мережевої взаємодії gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / виклик tools: запускайте звужений `pnpm test:live` +- Торкаєтеся мережевого стеку шлюзу / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live: Android node capability sweep +## Live: перевірка можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка наразі оголошується** підключеним Android-вузлом, і перевірити поведінку контракту команди. -- Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не спаровує застосунок). - - Перевірка `node.invoke` у gateway для вибраного Android-вузла по команді за командою. -- Необхідне попереднє налаштування: - - Android-застосунок уже підключений і спарений із gateway. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android node, і перевірити поведінку контракту команд. +- Охоплення: + - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не сполучає застосунок). + - Покомандна валідація gateway `node.invoke` для вибраного Android node. +- Потрібне попереднє налаштування: + - Android-застосунок уже підключений і сполучений зі шлюзом. - Застосунок утримується на передньому плані. - - Для можливостей, які ви очікуєте, що пройдуть перевірку, надано дозволи/згоду на захоплення. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: - `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-тести поділено на два шари, щоб можна було ізолювати збої: - «Пряма модель» показує, чи може провайдер/модель узагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сеанси, історія, tools, sandbox policy тощо). +- «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). ### Шар 1: Пряме завершення моделі (без gateway) @@ -223,86 +223,86 @@ Live-тести поділено на два шари, щоб можна бул - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і цільові регресії, де це потрібно) + - Запустити невелике завершення для кожної моделі (і таргетовані регресії там, де потрібно) - Як увімкнути: - - `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 через кому) - - Modern/all sweeps типово використовують відібрану верхню межу високосигнальних моделей; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншої межі. + - Modern/all sweeps типово мають підібрану межу з високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншої межі. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: сховище профілів і резервні значення з env + - Типово: сховище профілів і резервні варіанти через env - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ невалідний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки виклику інструментів) -### Шар 2: smoke gateway + dev agent (що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process gateway - - Створити/оновити сеанс `agent:dev:*` (перевизначення моделі для кожного запуску) - - Перебрати моделі з ключами та перевірити: - - «змістовну» відповідь (без tools) - - що працює реальний виклик tool (read probe) - - необов’язкові додаткові probes tool (exec+read probe) - - що шляхи регресій OpenAI (лише tool-call → follow-up) продовжують працювати -- Відомості про probe-и (щоб ви могли швидко пояснити збої): - - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його через `read`. - - image probe: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - Запустити in-process gateway + - Створити/змінити сесію `agent:dev:*` (з перевизначенням моделі для кожного запуску) + - Перебрати моделі-з-ключами й перевірити: + - «змістовну» відповідь (без інструментів) + - що працює реальний виклик інструмента (перевірка `read`) + - необов’язкові додаткові перевірки інструментів (перевірка `exec+read`) + - що шляхи регресій OpenAI (лише виклик інструмента → подальший крок) і далі працюють +- Подробиці перевірок (щоб ви могли швидко пояснити збої): + - перевірка `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - перевірка `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім прочитати його назад через `read`. + - перевірка зображення: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) + - `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 + - Типово: 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"` (або список через кому), щоб звузити вибір - - Modern/all gateway sweeps типово використовують відібрану верхню межу високосигнальних моделей; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншої межі. -- Як вибирати провайдерів (уникати «все OpenRouter»): + - Modern/all gateway sweeps типово мають підібрану межу з високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншої межі. +- Як вибирати провайдерів (уникати «усе через OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Tool та image probes у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (stress для tool) - - image probe запускається, коли модель оголошує підтримку image input +- Перевірки інструментів і зображень у цьому live-тесті завжди ввімкнені: + - перевірка `read` + перевірка `exec+read` (навантаження на інструменти) + - перевірка зображення запускається, коли модель оголошує підтримку вхідних зображень - Потік (на високому рівні): - Тест генерує крихітний 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 пересилає моделі мультимодальне повідомлення користувача + - Embedded agent пересилає мультимодальне повідомлення користувача моделі - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме можна протестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke для CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent із локальним CLI backend, не торкаючись вашої типової конфігурації. -- Типові значення smoke для конкретного backend зберігаються у визначенні `cli-backend.ts` розширення-власника. +- Мета: перевірити конвеєр Gateway + agent за допомогою локального CLI backend, не торкаючись вашої типової конфігурації. +- Типові параметри 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` - Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin-а CLI backend, якому це належить. -- Перевизначення (необов’язково): + - Поведінка 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-вкладення (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до image-файлів як аргументи CLI замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання image-аргументів, коли задано `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності того самого сеансу Claude Sonnet -> Opus (установіть `1`, щоб примусово його ввімкнути, коли вибрана модель підтримує ціль перемикання). + - `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`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль переключення). Приклад: @@ -312,43 +312,45 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash pnpm test:docker:live-cli-backend ``` -Docker-рецепти для одного провайдера: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude +pnpm test:docker:live-cli-backend:claude-subscription 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-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke CLI з розширення-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований придатний для запису префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- Live smoke CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації image, а потім виклик MCP tool `cron`, перевірений через CLI gateway. -- Типовий smoke Claude також оновлює сеанс із Sonnet на Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку. +- Виконавець Docker розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. +- Він визначає метадані CLI smoke з 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. Ця subscription-lane типово вимикає перевірки Claude MCP/tool і image, оскільки зараз Claude маршрутизує використання сторонніх застосунків через додаткове білінг-споживання, а не через звичайні ліміти тарифного плану підписки. +- Live smoke CLI-backend тепер перевіряє однаковий end-to-end-потік для Claude, Codex і Gemini: текстовий хід, хід із класифікацією зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія досі пам’ятає попередню нотатку. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke для ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язування розмови ACP із live ACP-агентом: +- Мета: перевірити реальний потік ACP conversation-bind із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати synthetic розмову message-channel на місці - - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє до transcript прив’язаного ACP-сеансу + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайний подальший хід у тій самій розмові + - перевірити, що подальший хід потрапляє в transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP-агенти в Docker: `claude,codex,gemini` - - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Synthetic channel: контекст розмови у стилі Slack DM + - ACP agents у Docker: `claude,codex,gemini` + - ACP agent для прямого `pnpm test:live ...`: `claude` + - Синтетичний канал: контекст розмови в стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -357,8 +359,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця ланка використовує поверхню gateway `chat.send` з synthetic originating-route fields лише для адміністраторів, щоб тести могли прикріплювати контекст 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 agent. Приклад: @@ -368,13 +370,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash pnpm test:docker:live-acp-bind ``` -Docker-рецепти для одного агента: +Рецепти Docker для окремих агентів: ```bash pnpm test:docker:live-acp-bind:claude @@ -384,11 +386,11 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Виконавець Docker розташований у `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`, підготовлює відповідні матеріали 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` зберігав доступність змінних середовища провайдера з підключеного профілю для дочірнього harness CLI. +- Він завантажує `~/.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-змінні провайдера із завантаженого профілю доступними для дочірнього CLI harness. ### Рекомендовані live-рецепти @@ -400,7 +402,7 @@ 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` -- Виклик tools у кількох провайдерів: +- Виклик інструментів через кількох провайдерів: - `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 (API-ключ Gemini + Antigravity): @@ -410,21 +412,21 @@ pnpm test:docker:live-acp-bind:gemini Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (кінцева точка агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tools). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує оболонковий виклик локального бінарника `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка tools/розсинхронізація версій). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / автентифікація профілю); це те, що більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). ## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (live — opt-in), але це **рекомендовані** моделі, які варто регулярно охоплювати на dev-машині з ключами. +Фіксованого «списку моделей CI» немає (live — за явного ввімкнення), але ось **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний smoke-набір (виклик tools + image) +### Сучасний набір smoke (виклик інструментів + зображення) -Це запуск «поширених моделей», працездатність якого ми очікуємо зберігати: +Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: -- 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) @@ -432,12 +434,12 @@ pnpm test:docker:live-acp-bind:gemini - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з tools + image: +Запуск gateway smoke з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,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` -### Базовий рівень: виклик tools (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель для кожного сімейства провайдерів: +Виберіть щонайменше одну модель для кожної родини провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -445,46 +447,46 @@ pnpm test:docker:live-acp-bind:gemini - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано мати): +Необов’язкове додаткове покриття (корисно мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою «tools», яку у вас ввімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик tools залежить від режиму API) +- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання image (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб задіяти перевірку зображень. -### Агрегатори / альтернативні gateway +### Агрегатори / альтернативні шлюзи -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою інструментів і зображень) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, яких можна включити в live-матрицю (якщо у вас є облікові дані/конфігурація): +Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (кастомні кінцеві точки): `minimax` (хмара/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (хмара/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зафіксувати в документації «всі моделі». Авторитетним списком є все, що `discoverModels(...)` повертає на вашій машині + усі доступні ключі. +Порада: не намагайтеся жорстко кодувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як це робить CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо live-тест повідомляє «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «ключі профілю») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог legacy state: `~/.openclaw/credentials/` (копіюється в підготовлений live home, якщо присутній, але не є основним сховищем ключів профілів) -- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для окремих агентів, legacy `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; підготовлені live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не працювали у вашому реальному workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілів) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасової домашньої теки тесту; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб перевірки не торкалися вашого реального хостового workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть змонтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-виконавці нижче (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрибування аудіо) +## 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` @@ -499,22 +501,22 @@ 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` +- Охоплення: + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у поданні workflow comfy, polling, завантаженнях або реєстрації plugin-а + - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації plugin -## Live генерації image +## 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 провайдера генерації image - - Завантажує відсутні env-змінні провайдера з вашої оболонки входу (`~/.profile`) перед probing - - Типово використовує live/env API-ключі раніше, ніж збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки +- Охоплення: + - Перелічує кожен зареєстрований provider plugin генерації зображень + - Завантажує відсутні env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає стандартні варіанти генерації image через спільну runtime-можливість: + - Запускає стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -527,69 +529,69 @@ 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"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через 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-змінні провайдера з вашої оболонки входу (`~/.profile`) перед probing - - Типово використовує live/env API-ключі раніше, ніж збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Завантажує env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` із введенням лише prompt + - `generate` з вхідними даними лише через prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної лінії: + - Поточне покриття спільної lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не цей спільний sweep + - `comfy`: окремий live-файл Comfy, не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через 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-змінні провайдера з вашої оболонки входу (`~/.profile`) перед probing - - Типово використовує live/env API-ключі раніше, ніж збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки +- Охоплення: + - Перевіряє спільний шлях вбудованих провайдерів генерації відео + - Завантажує env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` із введенням лише prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід image на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід video на основі buffer у спільному sweep + - `generate` з вхідними даними лише через prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні дані зображень на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальні вхідні дані відео на основі buffer у спільному sweep - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: - - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL image - - Покриття Vydra, специфічне для провайдера: + - `vydra`, тому що вбудований `veo3` — лише текстовий, а вбудований `kling` вимагає віддалений URL зображення + - Специфічне для провайдера покриття Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка типово використовує fixture із віддаленим URL image + - цей файл запускає `veo3` text-to-video, а також lane `kling`, яка типово використовує fixture віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені URL-посилання `http(s)` / reference MP4 - - `google`, оскільки поточна спільна лінія Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається у спільному sweep - - `openai`, оскільки поточна спільна лінія не гарантує доступу до org-specific video inpaint/remix + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалених reference URL `http(s)` / MP4 + - `google`, тому що поточна спільна lane Gemini/Veo використовує локальні вхідні дані на основі buffer, а цей шлях не приймається у спільному sweep + - `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"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один стандартний entrypoint репозиторію - - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - Запускає спільні live-набори для зображень, музики та відео через один native entrypoint репозиторію + - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - Повторно використовує `scripts/test-live.mjs`, тому поведінка heartbeat і quiet-mode залишається узгодженою - Приклади: @@ -598,124 +600,123 @@ Live-тести знаходять облікові дані так само, я - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-ранери (необов’язкові перевірки «працює в Linux») +## Виконавці Docker (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці виконавці Docker поділяються на дві категорії: -- Docker-ранери live-моделей: `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`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери live типово використовують меншу межу smoke, щоб повний Docker sweep залишався практичним: +- Виконавці live-model: `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`), монтуючи ваш локальний каталог конфігурації та workspace (і завантажуючи `~/.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`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - ви явно хочете більший вичерпний scan. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. -- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам явно потрібне ширше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `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-шляхи вищого рівня. -Docker-ранери live-моделей також bind-mount лише потрібні homes автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста: +Виконавці Docker для live-model також bind-mount лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашню теку контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище автентифікації на хості: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-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`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Wizard онбордингу (TTY, повне scaffold): `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 (ініціалізований Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (install smoke + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Міст каналу MCP (ініціалізований Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-ранери live-моделей також bind-mount поточний checkout лише для читання й -підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ -компактним, але водночас запускає Vitest точно на ваших локальних source/config. -Крок підготовки пропускає великі лише локальні кеші та результати збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або -вивід Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +Виконавці Docker для live-model також bind-mount поточний checkout лише для читання і +розгортають його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ +компактним і водночас дозволяє запускати Vitest точно проти вашого локального source/config. +Етап розгортання пропускає великі локальні кеші та результати збирання застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги +`.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали -реальні воркери каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе одно запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цієї Docker-лінії. -`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, -запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути -образ Open WebUI, а Open WebUI може знадобитися завершити власне cold-start налаштування. -Ця лінія очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Docker-запусках. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-перевірки gateway не запускали +реальні worker каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття gateway у цій Docker-lane. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає контейнер +gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, запускає прив’язаний контейнер Open WebUI проти +цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний chat-запит через проксі Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися витягнути +образ Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. +Ця 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`, а потім +реального облікового запису Telegram, Discord або iMessage. Він запускає ініціалізований контейнер Gateway, +запускає другий контейнер, який стартує `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення каналу + -дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -напряму перевіряє raw stdio MCP frames, тож smoke-тест перевіряє те, що bridge +поведінку черги live-подій, маршрутизацію вихідного надсилання, а також сповіщення каналів + дозволів у стилі Claude +через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі stdio MCP-кадри, тож smoke перевіряє те, що міст справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. -Ручний smoke plain-language thread для ACP (не CI): +Ручний smoke звичайномовного thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації thread ACP, тож не видаляйте його. Корисні 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_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і завантажується перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI у Docker +- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ручне перевизначення: `OPENCLAW_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_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) +- `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=...`, щоб перевизначити pinned тег образу Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити прив’язаний тег образу Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки документації: `pnpm check:docs`. -Коли вам також потрібна повна перевірка anchor у Mintlify для заголовків на сторінці, запускайте: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку якірних посилань Mintlify, коли також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайнова регресія (безпечна для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Виклик tools у gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, із примусовим записом config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів gateway (мок OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard gateway (WS `wizard.start`/`wizard.next`, запис config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock виклику tools через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, що перевіряють wiring сеансу та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Мокований виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють прив’язку сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): - **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти робочого процесу:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сеансу й межі sandbox. +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Контракти робочого процесу:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесій і межі sandbox. -Майбутні оцінювання мають насамперед залишатися детермінованими: +Майбутні оцінювання насамперед мають залишатися детермінованими: -- Runner сценаріїв із mock-провайдерами для перевірки викликів tools + їх порядку, читання skill-файлів і wiring сеансу. -- Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-evals (opt-in, із керуванням через env) лише після того, як буде готовий безпечний для CI набір. +- Виконавець сценаріїв із mock-провайдерами для перевірки викликів інструментів + їхнього порядку, читання skill-файлів і прив’язки сесій. +- Невеликий набір сценаріїв, зосереджених на skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live-оцінювання (за явного ввімкнення, із захистом через env) лише після того, як буде готовий набір, безпечний для CI. ## Контрактні тести (форма plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -інтерфейсному контракту. Вони перебирають усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно +контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір перевірок +форми та поведінки. Типова unit-lane `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider. @@ -729,53 +730,53 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin-а (id, name, capabilities) -- **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язування сеансу -- **outbound-payload** - Структура payload вихідного повідомлення +- **plugin** - Базова форма plugin (id, name, capabilities) +- **setup** - Контракт wizard налаштування +- **session-binding** - Поведінка прив’язки сесії +- **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу +- **actions** - Обробники дій channel - **threading** - Обробка ID thread - **directory** - API каталогу/списку учасників -- **group-policy** - Застосування групової політики +- **group-policy** - Застосування політики груп -### Контракти статусу provider +### Контракти стану provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel -- **registry** - Форма реєстру plugin-ів +- **status** - Перевірки стану channel +- **registry** - Форма реєстру plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/підбір автентифікації +- **auth-choice** - Вибір/добір автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin-ів -- **loader** - Завантаження plugin-ів -- **runtime** - Runtime provider-а -- **shape** - Форма/інтерфейс plugin-а -- **wizard** - Майстер налаштування +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin +- **runtime** - Runtime provider +- **shape** - Форма/інтерфейс plugin +- **wizard** - Wizard налаштування ### Коли запускати -- Після змін у `plugin-sdk` exports або subpaths -- Після додавання чи зміни channel або provider plugin-а -- Після рефакторингу реєстрації plugin-ів або їх виявлення +- Після зміни export або subpath у plugin-sdk +- Після додавання або зміни plugin channel чи provider +- Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI й не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- За можливості додайте безпечну для CI регресію (mock/stub provider-а або захоплення точної форми трансформації запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env-змінні -- Намагайтеся націлюватися на найменший шар, який виявляє баг: - - баг перетворення/повторного програвання запиту provider-а → тест прямих моделей - - баг конвеєра сеансу/історії/tool gateway → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне обмеження обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) +- Якщо проблема за своєю природою лише для live (rate limits, політики автентифікації), залишайте live-тест вузьким і за явного ввімкнення через env-змінні +- Намагайтеся націлюватися на найменший шар, який ловить помилку: + - помилка перетворення/повторення запиту provider → тест direct models + - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Запобіжник обходу 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, щоб нові класи не можна було тихо пропустити.