From 74ff95e6a3cebf43b761789faa259426ed948d74 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 01:55:32 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/qa-e2e-automation.md | 270 +++---- docs/uk/help/testing.md | 1045 ++++++++++++------------- 2 files changed, 657 insertions(+), 658 deletions(-) diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md index 9e9fc3a61..53b93badb 100644 --- a/docs/uk/concepts/qa-e2e-automation.md +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -2,47 +2,48 @@ read_when: - Розширення qa-lab або qa-channel - Додавання QA-сценаріїв, що підтримуються репозиторієм - - Побудова реалістичнішої QA-автоматизації навколо панелі Gateway -summary: Форма приватної QA-автоматизації для qa-lab, qa-channel, початково підготовлених сценаріїв і звітів протоколу -title: QA E2E-автоматизація + - Створення автоматизації QA з вищим рівнем реалізму навколо панелі керування Gateway +summary: Приватна форма автоматизації QA для qa-lab, qa-channel, початково заповнених сценаріїв і звітів протоколу +title: Автоматизація QA E2E x-i18n: - generated_at: "2026-04-23T22:58:57Z" + generated_at: "2026-04-24T01:50:42Z" model: gpt-5.4 provider: openai - source_hash: 8cf607af9e85c1f6908049da2b31a1c6c9eaa1fc95bc3af2136babb1a3b9b48f + source_hash: f6924a05faebdd22ac5222db6b9579b57d9c7f3dfac71df6c5f2ee7d2bf0a5f8 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -Приватний стек QA призначений для того, щоб перевіряти OpenClaw у більш реалістичний, -схожий на справжні канали спосіб, ніж це може зробити один unit-тест. +Приватний стек QA призначений для перевірки OpenClaw у більш реалістичний, +орієнтований на канали спосіб, ніж це може зробити один unit-тест. Поточні складові: -- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями для DM, каналу, треду, +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями DM, каналу, гілки, реакцій, редагування та видалення. -- `extensions/qa-lab`: UI для налагодження та QA-шина для спостереження за транскриптом, - ін’єкції вхідних повідомлень і експорту Markdown-звіту. -- `qa/`: початкові ресурси, що підтримуються репозиторієм, для стартового завдання та базових QA-сценаріїв. +- `extensions/qa-lab`: UI налагодження та QA-шина для спостереження за транскриптом, + інʼєкції вхідних повідомлень і експорту звіту у Markdown. +- `qa/`: ресурси початкових даних, що підтримуються репозиторієм, для стартового завдання та базових QA- + сценаріїв. -Поточний робочий процес QA-оператора — це двопанельний QA-сайт: +Поточний робочий процес QA-оператора — це двопанельний сайт QA: -- Ліворуч: панель Gateway (Control UI) з агентом. +- Ліворуч: панель керування Gateway (Control UI) з агентом. - Праворуч: QA Lab, де показано схожий на Slack транскрипт і план сценарію. -Запустіть його так: +Запустіть так: ```bash pnpm qa:lab:up ``` -Це збирає QA-сайт, запускає lane Gateway на базі Docker і відкриває -сторінку QA Lab, де оператор або цикл автоматизації можуть дати агенту QA-місію, -спостерігати реальну поведінку каналу та фіксувати, що спрацювало, що зламалося або -що залишилося заблокованим. +Це збирає QA-сайт, запускає доріжку gateway на базі Docker і відкриває +сторінку QA Lab, де оператор або цикл автоматизації може дати агенту QA- +місію, спостерігати реальну поведінку каналу й фіксувати, що спрацювало, +що не спрацювало або що залишилося заблокованим. -Щоб швидше ітерувати UI QA Lab без перебудови Docker-образу щоразу, -запустіть стек із bind-mounted bundle QA Lab: +Для швидшої ітерації UI QA Lab без повторного збирання Docker-образу щоразу, +запустіть стек із bind-mounted збіркою QA Lab: ```bash pnpm openclaw qa docker-build-image @@ -51,165 +52,167 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` тримає сервіси Docker на попередньо зібраному образі та bind-mount-ить +`qa:lab:up:fast` тримає Docker-сервіси на попередньо зібраному образі та bind-mount `extensions/qa-lab/web/dist` у контейнер `qa-lab`. `qa:lab:watch` -перебудовує цей bundle при змінах, а браузер автоматично перезавантажується, коли хеш ресурсів QA Lab змінюється. +перезбирає цю збірку при змінах, а браузер автоматично перезавантажується, коли +змінюється хеш ресурсу QA Lab. -Для smoke-lane Matrix із реальним транспортом виконайте: +Для smoke-доріжки Matrix з реальним транспортом виконайте: ```bash pnpm openclaw qa matrix ``` -Цей lane створює тимчасовий homeserver Tuwunel у Docker, реєструє -тимчасових користувачів driver, SUT та observer, створює одну приватну кімнату, а потім запускає -справжній Plugin Matrix усередині дочірнього QA gateway. Lane із живим транспортом тримає -конфігурацію дочірнього процесу обмеженою транспортом, який тестується, тому Matrix працює без -`qa-channel` у конфігурації дочірнього процесу. Він записує артефакти структурованого звіту та -об’єднаний журнал stdout/stderr у вибраний вихідний каталог Matrix QA. Щоб -також захопити зовнішній вивід збірки/запуску `scripts/run-node.mjs`, установіть -`OPENCLAW_RUN_NODE_OUTPUT_LOG=` на локальний для репозиторію файл журналу. +Ця доріжка розгортає одноразовий homeserver Tuwunel у Docker, реєструє +тимчасових користувачів driver, SUT та observer, створює одну приватну кімнату, +а потім запускає реальний Plugin Matrix всередині дочірнього процесу QA gateway. Доріжка живого транспорту тримає +конфігурацію дочірнього процесу обмеженою транспортом, що тестується, тому Matrix запускається без +`qa-channel` у конфігурації дочірнього процесу. Вона записує структуровані артефакти звіту та +обʼєднаний лог stdout/stderr у вибраний вихідний каталог Matrix QA. Щоб +також захопити зовнішній вивід збирання/запуску `scripts/run-node.mjs`, +встановіть `OPENCLAW_RUN_NODE_OUTPUT_LOG=` у лог-файл усередині репозиторію. -Для smoke-lane Telegram із реальним транспортом виконайте: +Для smoke-доріжки Telegram з реальним транспортом виконайте: ```bash pnpm openclaw qa telegram ``` -Цей lane націлений на одну реальну приватну групу Telegram замість створення -тимчасового сервера. Для нього потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +Ця доріжка націлюється на одну реальну приватну групу Telegram замість розгортання +одноразового сервера. Вона вимагає `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також два різні боти в одній -приватній групі. Бот SUT повинен мати ім’я користувача Telegram, а спостереження бот-до-бота -працює найкраще, коли в обох ботів увімкнено режим Bot-to-Bot Communication Mode -в `@BotFather`. -Команда завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, а також двох різних ботів в одній +приватній групі. Бот SUT повинен мати імʼя користувача Telegram, а +спостереження бот-до-бота працює найкраще, коли в обох ботів увімкнено режим Bot-to-Bot Communication Mode +у `@BotFather`. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. -Звіт і підсумок Telegram включають RTT для кожної відповіді — від запиту на -надсилання повідомлення driver до спостереженої відповіді SUT, починаючи з canary. +Звіт Telegram і підсумок містять RTT для кожної відповіді від запиту +надсилання повідомлення driver до спостережуваної відповіді SUT, починаючи з canary. -Тепер lane живого транспорту використовують один менший спільний контракт замість того, щоб кожен вигадував -власну форму списку сценаріїв: +Тепер доріжки живого транспорту використовують один менший спільний контракт, замість того щоб +кожна вигадувала власну форму списку сценаріїв: -`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту і не входить +`qa-channel` залишається широким синтетичним набором перевірок поведінки продукту й не входить до матриці покриття живого транспорту. -| Lane | Canary | Обмеження за згадкою | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальші дії в треді | Ізоляція треду | Спостереження за реакціями | Команда help | -| -------- | ------ | -------------------- | -------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Доріжка | Canary | Фільтрація згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в гілці | Ізоляція гілки | Спостереження реакцій | Команда help | +| --------- | ------ | ----------------- | -------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Це залишає `qa-channel` широким набором перевірок поведінки продукту, тоді як Matrix, -Telegram і майбутні живі транспорти мають спільний явний чеклист транспортного контракту. +Це зберігає `qa-channel` як широкий набір перевірок поведінки продукту, тоді як Matrix, +Telegram і майбутні живі транспорти спільно використовують один явний контрольний список транспортного контракту. -Для lane з тимчасовою Linux VM без використання Docker у QA-шляху виконайте: +Для доріжки з одноразовою Linux VM без залучення Docker до QA-шляху виконайте: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Це запускає нову гостьову машину Multipass, встановлює залежності, збирає OpenClaw -усередині гостьової машини, запускає `qa suite`, а потім копіює звичайний QA-звіт і +Це запускає нову гостьову машину Multipass, установлює залежності, збирає OpenClaw +усередині гостя, виконує `qa suite`, а потім копіює звичайний QA-звіт і підсумок назад у `.artifacts/qa-e2e/...` на хості. -Він повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. +Вона повторно використовує ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. Запуски suite на хості та в Multipass за замовчуванням виконують кілька вибраних сценаріїв паралельно -з ізольованими працівниками gateway. `qa-channel` за замовчуванням має concurrency 4, +з ізольованими worker-процесами gateway. `qa-channel` за замовчуванням використовує concurrency 4, обмежений кількістю вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати -кількість працівників, або `--concurrency 1` для послідовного виконання. -Команда завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо +кількість worker-процесів, або `--concurrency 1` для послідовного виконання. +Команда завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. -Живі запуски передають підтримувані QA-входи автентифікації, які практичні для -гостьової машини: ключі провайдера через env, шлях до конфігурації QA live provider і +Живі запуски передають підтримувані вхідні дані QA-автентифікації, які практичні для +гостя: ключі провайдера через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. Тримайте `--output-dir` у межах кореня репозиторію, щоб гість міг записувати назад через змонтований робочий простір. ## Початкові дані, що підтримуються репозиторієм -Початкові ресурси живуть у `qa/`: +Ресурси початкових даних знаходяться в `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Вони навмисно зберігаються в git, щоб план QA був видимий і людям, і -агенту. +Вони навмисно зберігаються в git, щоб план QA був видимий і для людей, і для +агента. -`qa-lab` має залишатися універсальним виконавцем Markdown. Кожен Markdown-файл сценарію є +`qa-lab` має залишатися загальним виконавцем markdown. Кожен markdown-файл сценарію є джерелом істини для одного тестового запуску й має визначати: - метадані сценарію -- необов’язкові метадані категорії, можливості, lane і ризику +- необовʼязкові метадані категорії, можливостей, доріжки та ризику - посилання на документацію та код -- необов’язкові вимоги до Plugin -- необов’язковий patch конфігурації gateway +- необовʼязкові вимоги до Plugin +- необовʼязковий патч конфігурації gateway - виконуваний `qa-flow` -Повторно використовувана поверхня runtime, що лежить в основі `qa-flow`, може залишатися універсальною -і наскрізною. Наприклад, Markdown-сценарії можуть поєднувати транспортні -допоміжні засоби з браузерними допоміжними засобами, які керують вбудованим Control UI через -seam `browser.request` у Gateway, не додаючи спеціалізований виконавець. +Повторно використовувана поверхня runtime, яка лежить в основі `qa-flow`, може залишатися загальною +і наскрізною. Наприклад, markdown-сценарії можуть поєднувати +допоміжні засоби на стороні транспорту з допоміжними засобами на стороні браузера, які керують вбудованим Control UI через +інтерфейс Gateway `browser.request`, не додаючи спеціалізованого виконавця. -Файли сценаріїв слід групувати за можливостями продукту, а не за папкою дерева вихідного коду. -Зберігайте стабільність ID сценаріїв під час переміщення файлів; використовуйте `docsRefs` і `codeRefs` -для простежуваності реалізації. +Файли сценаріїв слід групувати за можливістю продукту, а не за папкою +дерева вихідного коду. Зберігайте ідентифікатори сценаріїв стабільними при переміщенні файлів; використовуйте `docsRefs` і `codeRefs` +для відстежуваності реалізації. Базовий список має залишатися достатньо широким, щоб охоплювати: -- чат у DM і каналі -- поведінку тредів +- чати в DM і каналах +- поведінку гілок - життєвий цикл дій із повідомленнями -- зворотні виклики Cron -- відтворення пам’яті +- зворотні виклики cron +- відтворення з памʼяті - перемикання моделей - передачу підлеглому агенту - читання репозиторію та документації -- одне невелике завдання зі збірки, наприклад Lobster Invaders +- одне невелике завдання зі збирання, наприклад Lobster Invaders -## Mock-lane провайдерів +## Доріжки mock-провайдерів -`qa suite` має два локальні mock-lane провайдерів: +`qa suite` має дві локальні доріжки mock-провайдерів: -- `mock-openai` — це залежний від сценарію mock OpenClaw. Він залишається типовим - детермінованим mock-lane для QA, що підтримується репозиторієм, і перевірок паритету. +- `mock-openai` — це обізнаний про сценарії mock OpenClaw. Він залишається + типовою детермінованою mock-доріжкою для QA, що підтримується репозиторієм, і перевірок паритету. - `aimock` запускає сервер провайдера на базі AIMock для експериментального покриття - протоколу, фікстур, record/replay і chaos. Він є додатковим і не замінює - диспетчер сценаріїв `mock-openai`. + протоколу, фікстур, запису/відтворення та хаосу. Це доповнення і воно не + замінює диспетчер сценаріїв `mock-openai`. -Реалізація provider-lane знаходиться в `extensions/qa-lab/src/providers/`. -Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, -конфігурацією моделей gateway, потребами staging для профілів автентифікації та прапорцями live/mock можливостей. Спільний код suite і gateway має маршрутизувати через реєстр провайдерів, а не розгалужуватися за назвами провайдерів. +Реалізація доріжок провайдерів розміщена в `extensions/qa-lab/src/providers/`. +Кожен провайдер володіє своїми типовими значеннями, запуском локального сервера, конфігурацією моделей gateway, +потребами підготовки auth-profile і прапорцями можливостей live/mock. Спільний код suite та +gateway має проходити через реєстр провайдерів замість розгалуження за назвами провайдерів. -## Транспортні адаптери +## Адаптери транспорту -`qa-lab` володіє універсальним seam транспорту для Markdown QA-сценаріїв. -`qa-channel` — перший адаптер на цьому seam, але ціль дизайну ширша: -майбутні реальні або синтетичні канали мають підключатися до того самого виконавця suite, -а не додавати специфічний для транспорту QA-виконавець. +`qa-lab` володіє загальним інтерфейсом транспорту для markdown-сценаріїв QA. +`qa-channel` — перший адаптер на цьому інтерфейсі, але ціль проєктування ширша: +майбутні реальні або синтетичні канали мають підключатися до того самого виконавця suite +замість додавання спеціалізованого QA-виконавця для транспорту. На рівні архітектури поділ такий: -- `qa-lab` відповідає за універсальне виконання сценаріїв, concurrency працівників, запис артефактів і звітність. -- транспортний адаптер відповідає за конфігурацію gateway, готовність, спостереження за вхідними та вихідними подіями, транспортні дії й нормалізований стан транспорту. -- Markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає повторно використовувану поверхню runtime, яка їх виконує. +- `qa-lab` володіє загальним виконанням сценаріїв, паралельністю worker-процесів, записом артефактів і звітністю. +- адаптер транспорту володіє конфігурацією gateway, готовністю, спостереженням за вхідними та вихідними подіями, транспортними діями та нормалізованим станом транспорту. +- markdown-файли сценаріїв у `qa/scenarios/` визначають тестовий запуск; `qa-lab` надає повторно використовувану поверхню runtime, яка їх виконує. -Орієнтовані на мейнтейнерів рекомендації щодо впровадження нових адаптерів каналів наведено в -[Testing](/uk/help/testing#adding-a-channel-to-qa). +Настанови з упровадження для супровідників нових адаптерів каналів містяться в +[Тестування](/uk/help/testing#adding-a-channel-to-qa). ## Звітність -`qa-lab` експортує Markdown-звіт протоколу зі спостережуваної часової шкали шини. -Звіт має відповідати на такі питання: +`qa-lab` експортує протокольний звіт у Markdown зі спостережуваної часової шкали шини. +Звіт має відповідати на запитання: - Що спрацювало -- Що зламалося +- Що не спрацювало - Що залишилося заблокованим -- Які наступні сценарії варто додати +- Які додаткові сценарії варто додати -Для перевірок характеру та стилю запустіть той самий сценарій на кількох живих model -refs і створіть оцінений Markdown-звіт: +Для перевірок характеру та стилю виконайте той самий сценарій для кількох живих ref моделей +і запишіть оцінений звіт у Markdown: ```bash pnpm openclaw qa character-eval \ - --model openai-codex/gpt-5.5,thinking=xhigh \ + --model openai/gpt-5.4,thinking=medium,fast \ --model openai/gpt-5.2,thinking=xhigh \ --model openai/gpt-5,thinking=xhigh \ --model anthropic/claude-opus-4-6,thinking=high \ @@ -217,7 +220,7 @@ pnpm openclaw qa character-eval \ --model zai/glm-5.1,thinking=high \ --model moonshot/kimi-k2.5,thinking=high \ --model google/gemini-3.1-pro-preview,thinking=high \ - --judge-model openai-codex/gpt-5.5,thinking=xhigh,fast \ + --judge-model openai/gpt-5.4,thinking=xhigh,fast \ --judge-model anthropic/claude-opus-4-6,thinking=high \ --blind-judge-models \ --concurrency 16 \ @@ -225,40 +228,39 @@ pnpm openclaw qa character-eval \ ``` Команда запускає локальні дочірні процеси QA gateway, а не Docker. Сценарії character eval -мають задавати персонажа через `SOUL.md`, а потім виконувати звичайні ходи користувача, -такі як чат, допомога з робочим простором і невеликі файлові завдання. Модель-кандидат -не повинна знати, що її оцінюють. Команда зберігає кожен повний -транскрипт, фіксує базову статистику запуску, а потім просить моделі-судді в швидкому режимі з -міркуванням `xhigh` ранжувати запуски за природністю, вайбом і гумором. -Використовуйте `--blind-judge-models`, коли порівнюєте провайдерів: промпт для судді все одно отримує -кожен транскрипт і статус запуску, але refs кандидатів замінюються нейтральними -мітками на кшталт `candidate-01`; звіт зіставляє рейтинги з реальними refs після -розбору. -Для запусків кандидатів за замовчуванням використовується рівень thinking `high`, а для моделей OpenAI, -які це підтримують, — `xhigh`. Перевизначте конкретного кандидата inline через -`--model provider/model,thinking=`. `--thinking ` як і раніше задає -глобальне запасне значення, а старіша форма `--model-thinking ` збережена -для сумісності. -Для refs кандидатів OpenAI за замовчуванням використовується fast mode, щоб застосовувалася -пріоритетна обробка там, де провайдер це підтримує. Додайте inline `,fast`, `,no-fast` або `,fast=false`, коли -одному кандидату або судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете -примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалості кандидатів і суддів -записуються у звіт для аналізу бенчмарків, але в промптах для суддів явно сказано +мають задавати persona через `SOUL.md`, а потім виконувати звичайні користувацькі ходи, +такі як чат, допомога з робочим простором і невеликі файлові завдання. Моделі-кандидату +не слід повідомляти, що її оцінюють. Команда зберігає кожен повний +транскрипт, записує базову статистику запуску, а потім просить моделі-судді в швидкому режимі з +міркуванням `xhigh`, де це підтримується, ранжувати запуски за природністю, вайбом і гумором. +Використовуйте `--blind-judge-models`, коли порівнюєте провайдерів: запит для судді все одно отримує +кожен транскрипт і статус запуску, але ref кандидатів замінюються нейтральними +мітками на кшталт `candidate-01`; звіт зіставляє ранжування назад із реальними ref після парсингу. +Запуски кандидатів за замовчуванням використовують `high` thinking, з `medium` для GPT-5.4 і `xhigh` +для старіших eval-ref OpenAI, які це підтримують. Перевизначте конкретного кандидата безпосередньо через +`--model provider/model,thinking=`. `--thinking ` і далі задає +глобальне резервне значення, а старіша форма `--model-thinking ` +зберігається для сумісності. +Ref кандидатів OpenAI за замовчуванням використовують fast mode, щоб застосовувалася пріоритетна обробка там, +де це підтримує провайдер. Додайте `,fast`, `,no-fast` або `,fast=false` безпосередньо, коли +окремому кандидату або судді потрібне перевизначення. Передавайте `--fast` лише тоді, коли хочете +примусово ввімкнути fast mode для кожної моделі-кандидата. Тривалість запусків кандидатів і суддів +записується у звіт для аналізу продуктивності, але в запитах до суддів прямо вказано не ранжувати за швидкістю. -І для кандидатів, і для суддів за замовчуванням використовується concurrency 16. Зменште -`--concurrency` або `--judge-concurrency`, коли обмеження провайдера чи навантаження на локальний gateway -роблять запуск надто шумним. -Коли не передано жодного кандидата `--model`, для character eval за замовчуванням використовуються -`openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openai/gpt-5.2`, `anthropic/claude-opus-4-6`, +І запуски моделей-кандидатів, і запуски моделей-суддів за замовчуванням використовують concurrency 16. Зменшуйте +`--concurrency` або `--judge-concurrency`, коли обмеження провайдера чи локальне навантаження на gateway +роблять запуск занадто шумним. +Якщо не передано жодного `--model` кандидата, character eval за замовчуванням використовує +`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` і -`google/gemini-3.1-pro-preview`, якщо `--model` не передано. -Коли не передано жодного `--judge-model`, за замовчуванням суддями є -`openai-codex/gpt-5.5,thinking=xhigh,fast` і +`google/gemini-3.1-pro-preview`, якщо не передано `--model`. +Якщо не передано жодного `--judge-model`, суддями за замовчуванням є +`openai/gpt-5.4,thinking=xhigh,fast` і `anthropic/claude-opus-4-6,thinking=high`. -## Пов’язані документи +## Повʼязана документація -- [Testing](/uk/help/testing) +- [Тестування](/uk/help/testing) - [QA Channel](/uk/channels/qa-channel) - [Панель керування](/uk/web/dashboard) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 39a045d32..f17f507d6 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделей/провайдерів + - Додавання регресійних тестів для багів моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-24T00:42:37Z" + generated_at: "2026-04-24T01:50:40Z" model: gpt-5.4 provider: openai - source_hash: bf98cc453740fefbd85fd453ec0fc2f08b3546f99aa62a4fd50c01f303314c94 + source_hash: 2598e4f03b2133dcbe6dac0a51f1d75e075e8961b00f6519003d41311936fd1d source_path: help/testing.md workflow: 15 --- @@ -19,154 +19,153 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Що охоплює кожен набір (і що він навмисно _не_ охоплює). - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем моделей/провайдерів. +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. ## Швидкий старт У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && 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 lane на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Якщо ви ітеруєтеся над однією помилкою, спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на базі Docker: `pnpm qa:lab:up` +- QA-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете більше впевненості: -- Coverage gate: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live-перебір моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку в стилі читання файлу. - Моделі, у чиїх метаданих заявлено вхід `image`, також виконують маленький хід із зображенням. - Вимкніть додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Тихий запуск одного live-файла: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker sweep live-моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку у стилі читання файла. + Моделі, чиї метадані оголошують вхід `image`, також виконують маленький хід із зображенням. + Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - - Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, який містить окремі Docker live model - matrix jobs, розшардені за провайдером. - - Для цільових повторних запусків CI викликайте `OpenClaw Live And E2E Checks (Reusable)` + - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні + `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `include_live_suites: true`, який включає окремі матричні Docker-job для live-моделей, + розшардовані за провайдером. + - Для точкових повторних запусків у CI dispatch `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові high-signal секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` - плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - scheduled/release викликачів. -- Перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + викликів для schedule/release. +- Перевірка вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте `openclaw models list --provider moonshot --json`, потім виконайте ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що - transcript помічника зберігає нормалізоване `usage.cost`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON показує Moonshot/K2.6, а + транскрипт помічника зберігає нормалізоване `usage.cost`. -Порада: якщо вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний кейс, краще звужувати live-тести через змінні середовища allowlist, описані нижче. ## QA-специфічні ранери -Ці команди розміщені поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поряд з основними тестовими наборами, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` виконується для відповідних PR і -при ручному виклику з mock-провайдерами. `QA-Lab - All Lanes` виконується щоночі на -`main` і при ручному виклику з mock parity gate, live Matrix lane і -Convex-керованою live lane Telegram як паралельними job. `OpenClaw Release Checks` +CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR і +через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний dispatch із mock parity gate, live Matrix lane та +live Telegram lane під керуванням Convex як паралельні job. `OpenClaw Release Checks` запускає ті самі lane перед затвердженням релізу. - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - workers Gateway. Для `qa-channel` типовим є concurrency 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування - кількості workers або `--concurrency 1` для старішої послідовної lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо ви + воркерами Gateway. `qa-channel` за замовчуванням використовує concurrency 4 (обмежену + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати + кількість воркерів, або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли хочете отримати артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на основі AIMock для експериментального - покриття фікстурами та імітацією протоколу, не замінюючи - lane `mock-openai`, орієнтовану на сценарії. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття фікстур і моків протоколу без заміни lane `mock-openai`, що знає про сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір у тимчасовій Linux VM Multipass. + - Запускає той самий QA-набір усередині одноразової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані QA-входи автентифікації, які практично передати в гостьову систему: - ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через - змонтований робочий простір. - - Записує звичайні QA report + summary, а також логи Multipass до + - Live-запуски перенаправляють підтримувані QA-входи автентифікації, практичні для гостя: + ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо наявний. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через + змонтовану робочу область. + - Записує звичайний QA-звіт і підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на основі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на базі Docker для операторської роботи з QA. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивний онбординг із ключем API OpenAI, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, - запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму - lane встановлення з пакета з Discord. + Docker, виконує неінтерактивний onboarding з OpenAI API key, за замовчуванням налаштовує Telegram, + перевіряє, що увімкнення Plugin встановлює runtime-залежності за потреби, + запускає doctor і виконує один локальний хід агента проти замоканого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane + пакетного встановлення з Discord. - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані channel/plugin через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає runtime-залежності - неналаштованих Plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює - runtime-залежності кожного вбудованого Plugin на вимогу, і що другий перезапуск не перевстановлює - залежності, які вже були активовані. - - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що - post-update doctor кандидата відновлює runtime-залежності вбудованого channel без - postinstall-відновлення з боку harness. + - Пакує і встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає вбудовані channel/Plugin через редагування config. + - Перевіряє, що виявлення setup залишає не налаштовані runtime-залежності Plugin відсутніми, + що перший налаштований запуск Gateway або doctor встановлює runtime-залежності + кожного вбудованого Plugin за потреби, і що другий перезапуск не перевстановлює залежності, + які вже були активовані. + - Також встановлює відому старішу npm-базу, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor після оновлення у кандидата + відновлює runtime-залежності вбудованих channel без відновлення postinstall з боку harness. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на основі Docker. - - Цей QA-хост наразі призначений лише для repo/dev. Пакетні встановлення OpenClaw не постачають + - Запускає live QA lane Matrix проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA-хост сьогодні лише для repo/dev. Пакетні встановлення OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout репозиторію напряму завантажують вбудований runner; окремий крок встановлення Plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, потім запускає дочірній QA gateway з реальним Plugin Matrix як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки ця lane локально створює тимчасових користувачів. - - Записує report Matrix QA, summary, артефакт observed-events і поєднаний лог виводу stdout/stderr до `.artifacts/qa-e2e/...`. + - Checkout із репозиторію завантажують вбудований раннер безпосередньо; окремий крок + встановлення Plugin не потрібен. + - Налаштовує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, потім запускає дочірній QA Gateway із реальним Plugin Matrix як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільні прапорці джерела облікових даних, оскільки lane локально налаштовує одноразових користувачів. + - Записує Matrix QA-звіт, підсумок, артефакт observed-events і комбінований лог stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо ви + - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулінгові lease. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли хочете отримати артефакти без коду завершення з помилкою. - - Потребує двох різних bot в одній приватній групі, причому bot SUT має мати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що bot driver може спостерігати трафік bot у групі. - - Записує report Telegram QA, summary і артефакт observed-messages до `.artifacts/qa-e2e/...`. Сценарії reply містять RTT від запиту на надсилання driver до спостереженої відповіді SUT. + - Потребує двох різних ботів у тій самій приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує Telegram QA-звіт, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостережуваної відповіді SUT. -Live transport lane поділяють один стандартний контракт, щоб нові транспорти не розходилися: +Live transport lane використовують один стандартний контракт, щоб нові транспорти не розходилися: `qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Lane | Canary | Гейтинг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у потоці | Ізоляція потоку | Спостереження реакцій | Команда help | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | --------------------------- | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Канарка | Гейтінг згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальше повідомлення в треді | Ізоляція тредів | Спостереження реакцій | Команда help | +| -------- | ------- | -------------- | --------------- | ------------------------- | ----------------------------- | ----------------------------- | --------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) -Коли для -`openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -цієї оренди, поки lane виконується, і звільняє оренду під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), +QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat +для цього lease, поки lane виконується, і звільняє lease під час завершення роботи. -Еталонний scaffold проєкту Convex: +Шаблон еталонного проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env-змінні: +Обов’язкові змінні середовища: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, інакше `maintainer`) -Необов’язкові env-змінні: +Необов’язкові змінні середовища: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -176,9 +175,9 @@ Live transport lane поділяють один стандартний конт - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. +У звичайній роботі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (додавання/видалення/список пулу) потребують +Адміністраторські команди maintainer (додавання/видалення/перелік пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Допоміжні CLI-команди для maintainer: @@ -191,7 +190,7 @@ pnpm openclaw qa credentials remove --credential-id Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. -Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -203,18 +202,18 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише для секрету maintainer) +- `POST /admin/add` (лише секрет maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише для секрету maintainer) +- `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише для секрету maintainer) + - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для Telegram kind: +Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` має бути рядком із числовим Telegram chat id. @@ -222,55 +221,55 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання channel до QA -Додавання channel до markdown-системи QA потребує рівно двох речей: +Додавання channel до markdown-системи QA вимагає рівно двох речей: -1. Transport adapter для channel. -2. Scenario pack, який перевіряє контракт channel. +1. Транспортного адаптера для channel. +2. Набору сценаріїв, який перевіряє контракт channel. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, коли спільний хост `qa-lab` може +взяти на себе цей потік. -`qa-lab` відповідає за спільну хостову механіку: +`qa-lab` володіє спільною механікою хоста: -- кореневий простір команд `openclaw qa` -- запуск і завершення suite -- concurrency workers -- запис артефактів -- генерацію report -- виконання сценаріїв -- compatibility aliases для старіших сценаріїв `qa-channel` +- кореневою командою `openclaw qa` +- запуском і завершенням suite +- concurrency воркерів +- записом артефактів +- генерацією звітів +- виконанням сценаріїв +- alias сумісності для старіших сценаріїв `qa-channel` -Runner plugins відповідають за транспортний контракт: +Runner Plugin володіють транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` - як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як інжектяться вхідні події +- як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються transcript і нормалізований стан транспорту -- як виконуються дії, підкріплені транспортом -- як обробляється transport-specific reset або cleanup +- як надаються транскрипти та нормалізований стан транспорту +- як виконуються дії, підтримувані транспортом +- як обробляються скидання або очищення, специфічні для транспорту -Мінімальний поріг впровадження для нового channel: +Мінімальний поріг прийняття для нового channel: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному хостовому seam `qa-lab`. -3. Зберігайте transport-specific механіку всередині runner plugin або channel harness. -4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; відкладене виконання CLI та runner має залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте generic scenario helpers для нових сценаріїв. -7. Зберігайте наявні compatibility aliases робочими, якщо тільки репозиторій не виконує навмисну міграцію. +2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. +3. Залишайте механіку, специфічну для транспорту, всередині runner Plugin або harness channel. +4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. + Runner Plugin мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниві CLI та виконання runner мають залишатися за окремими entrypoint. +5. Пишіть або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовуйте загальні допоміжні функції сценаріїв для нових сценаріїв. +7. Зберігайте працездатність наявних alias сумісності, якщо лише репозиторій не виконує навмисну міграцію. -Правило ухвалення рішень суворе: +Правило ухвалення рішення суворе: -- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного channel transport, залишайте її в цьому runner plugin або plugin harness. -- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один channel, додавайте generic helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно вказуйте це в контракті сценарію. +- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного channel transport, залишайте її в тому runner Plugin або harness Plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додайте загальний helper замість channel-специфічної гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-специфічним і явно зазначайте це в контракті сценарію. -Бажані назви generic helper для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -285,7 +284,7 @@ Runner plugins відповідають за транспортний контр - `formatTransportTranscript` - `resetTransport` -Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -293,151 +292,149 @@ Compatibility aliases залишаються доступними для ная - `formatConversationTranscript` - `resetBus` -Нова робота з channel має використовувати generic helper names. -Compatibility aliases існують, щоб уникнути міграції в стилі flag day, а не як модель для -створення нових сценаріїв. +Нова робота над channel має використовувати загальні назви helper. +Alias сумісності існують, щоб уникнути міграції в стилі flag day, а не як модель для +написання нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання flaky/cost): ### Unit / integration (типово) - Команда: `pnpm test` -- Config: нецільові запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shards у per-project config для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-тести `ui` для node, охоплені `vitest.unit.config.ts` -- Обсяг: +- Config: нетаргетовані запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shard у per-project config для паралельного планування +- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Scope: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресії для відомих помилок + - In-process integration-тести (автентифікація gateway, маршрутизація, інструментарій, парсинг, config) + - Детерміновані регресійні тести для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - - Нецільовий `pnpm test` запускає дванадцять менших shard config (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це знижує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що multi-shard watch loop непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory targets через 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 files; зміни config/setup усе ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це звичайний smart local gate для вузьких змін. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один додатковий прохід перевірки extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза верхньорівневим полем version. - Unit-тести з малими імпортами з agents, commands, plugins, допоміжних засобів auto-reply, `plugin-sdk` і подібних чистих утилітних ділянок маршрутизуються через lane `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски в changed-mode з явними sibling tests у цих легких lanes, тож зміни helper не змушують повторно запускати весь важкий набір для цього каталогу. - `auto-reply` має три виділені bucket: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. + - Нетаргетовані запуски `pnpm test` використовують дванадцять менших shard-конфігів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує нативний граф проєктів кореневого `vitest.config.ts`, оскільки multi-shard цикл watch непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні target на файли/каталоги через scoped lane, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної ціни запуску кореневого проєкту. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lane, коли diff зачіпає лише routable source/test файли; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, metadata релізу та tooling, а потім запускає відповідні lane typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій, що зачіпають лише metadata релізу, запускають цільові перевірки version/config/root-dependency замість повного набору, із guard, що відхиляє зміни package поза полем версії верхнього рівня. - Легкі щодо імпортів unit-тести з agents, commands, plugins, helper auto-reply, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lane. - Вибрані helper-файли джерела `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними sibling-тестами в цих легких lane, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три виділені bucket: helper верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст compaction, - зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте справність integration-наборів embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. + - Додавайте точкові регресійні тести helper для чистих меж маршрутизації та нормалізації. + - Підтримуйте в належному стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - Ці набори перевіряють, що scoped id і поведінка compaction і далі проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих integration-шляхів. + через реальні шляхи `run.ts` / `compact.ts`; тести лише для helper + не є достатньою заміною для цих integration-шляхів. - - - Базова config Vitest типово використовує `threads`. - - Спільна config Vitest фіксує `isolate: false` і використовує - non-isolated runner у root projects, e2e і live config. - - Коренева lane UI зберігає свій `jsdom` setup і optimizer, але теж працює на + + - Базовий config Vitest типово використовує `threads`. + - Спільний config Vitest фіксує `isolate: false` і використовує + non-isolated runner у root projects, config e2e і live. + - Кореневий lane UI зберігає свій setup `jsdom` і optimizer, але теж виконується на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` - зі спільної config Vitest. + - Кожен shard `pnpm test` успадковує ті самі типові значення + `threads` + `isolate: false` зі спільного config Vitest. - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook лише форматує. Він повторно індексує відформатовані файли і + - `pnpm changed:lanes` показує, які архітектурні lane запускає diff. + - Хук pre-commit виконує лише форматування. Він повторно додає до staging відформатовані файли і не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли вам - потрібен smart local gate. Зміни публічного Plugin SDK і plugin-contract - включають один прохід перевірки extension. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чітко відповідають меншому набору. + - Перед передачею роботи або push явно запускайте `pnpm check:changed`, коли + вам потрібен розумний локальний gate. Зміни публічного Plugin SDK і plugin-contract + включають один прохід валідації extension. + - `pnpm test:changed` маршрутизує через scoped lane, коли змінені шляхи + чітко зіставляються з меншим набором. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищою межею кількості workers. - - Автомасштабування локальних workers навмисно консервативне і зменшує навантаження, + лише з вищою межею кількості воркерів. + - Автомасштабування локальних воркерів навмисно консервативне і зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базова config Vitest позначає проєкти/config files як - `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, - коли змінюється wiring тестів. - - Config зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - одну явну локацію кешу для прямого профілювання. + - Базовий config Vitest позначає проєкти/config-файли як + `forceRerunTriggers`, щоб повторні запуски у changed-mode залишалися коректними, коли змінюється wiring тестів. + - Config залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одне явне розташування кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту, а також - вивід breakdown імпорту. - - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту плюс + вивід деталізації імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий профільний перегляд файлами, зміненими відносно `origin/main`. - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, - тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - напряму змокайте цей seam замість deep-import runtime helpers - лише для того, щоб передати їх через `vi.mock(...)`. + тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і мокайте цей seam + напряму замість deep-import runtime helper лише для того, + щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із native root-project шляхом для цього зафіксованого - diff і виводить wall time та macOS max RSS. + `test:changed` з нативним шляхом root-project для цього commit diff і виводить wall time плюс macOS max RSS. - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і кореневу config Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для - накладних витрат запуску й трансформації Vitest/Vite. + `scripts/test-projects.mjs` і кореневий config Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для + старту Vitest/Vite і накладних витрат transform. - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для unit-набору з вимкненим паралелізмом файлів. -### Stability (Gateway) +### Стабільність (gateway) - Команда: `pnpm test:stability:gateway` -- Config: `vitest.gateway.config.ts`, примусово один worker -- Обсяг: +- Config: `vitest.gateway.config.ts`, примусово один воркер +- Scope: - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - - Запитує `diagnostics.stability` через Gateway WS RPC - - Охоплює helper persistence для diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються в межах бюджету тиску, а глибина черг на рівні сесії знову зменшується до нуля + - Проганяє синтетичне churn повідомлень gateway, memory і великих payload через шлях діагностичних подій + - Виконує запити до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper збереження пакета діагностики стабільності + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються в межах бюджету тиску, а глибини черг на рівні сесій знову зменшуються до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька lane для подальшого відстеження stability-регресій, а не заміна повного набору Gateway + - Вузький lane для подальшого опрацювання регресій стабільності, а не заміна повного набору Gateway -### E2E (Gateway smoke) +### E2E (smoke для gateway) - Команда: `pnpm test:e2e` - Config: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin у `extensions/` -- Типові параметри runtime: +- Типові значення runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: типово 1). + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено до 16). + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. -- Обсяг: - - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, спарювання Node і важча мережева взаємодія +- Scope: + - Наскрізна поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing вузлів і важчий networking - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: smoke-тест бекенда OpenShell +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` -- Обсяг: +- Scope: - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через міст fs sandbox + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє канонічну для віддаленого середовища поведінку файлової системи через fs bridge sandbox - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і справного демона Docker + - Потрібен локальний CLI `openshell` і робочий Docker daemon - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний CLI-бінарник або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний двійковий файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) @@ -445,142 +442,142 @@ Compatibility aliases існують, щоб уникнути міграції - Config: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugin у `extensions/` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Обсяг: - - «Чи працює цей провайдер/модель _сьогодні_ з реальними обліковими даними?» +- Scope: + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає ліміти rate limit - - Краще запускати звужені піднабори, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб unit-фікстури не могли змінювати ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap gateway / шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (специфічна для провайдера): установіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або окреме live-перевизначення через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / витрачає rate limit + - Краще запускати звужені підмножини, а не «все» +- Live-запуски підвантажують `~/.profile`, щоб отримати відсутні API key. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали до тимчасового тестового home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і заглушує логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API key (залежить від провайдера): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно, що довгі виклики провайдера активні, навіть коли захоплення консолі 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, щоб рядки прогресу провайдера/gateway одразу передавалися під час live-запусків. + - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Зачіпаєте мережеву взаємодію gateway / протокол WS / pairing: додайте `pnpm test:e2e` +- Зачіпаєте networking gateway / протокол WS / pairing: додайте `pnpm test:e2e` - Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live: перевірка можливостей Android Node +## Live: sweep можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка зараз рекламується** підключеним Android Node, і перевірити поведінку контракту команди. -- Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не спаровує застосунок). - - Перевірка `node.invoke` gateway команда за командою для вибраного Android Node. -- Обов’язкове попереднє налаштування: - - Android-застосунок уже підключений і спарений із gateway. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команд. +- Scope: + - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не виконує pairing застосунку). + - Валідація `node.invoke` gateway команда за командою для вибраного Android Node. +- Потрібне попереднє налаштування: + - Android-застосунок уже підключено та спарено з gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. + - Надано дозволи/згоди на захоплення для можливостей, які ви очікуєте як успішні. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) +- Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke-тест моделі (ключі профілів) +## Live: smoke моделей (ключі профілів) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб ми могли ізолювати збої: -- «Direct model» показує, чи може провайдер/модель узагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» повідомляє нам, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Gateway smoke» повідомляє нам, чи працює для цієї моделі повний pipeline gateway+agent (сесії, історія, інструменти, політика sandbox тощо). ### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Перерахувати виявлені моделі + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб цей набір справді запустився; інакше він буде пропущений, щоб `pnpm test:live` залишався сфокусованим на smoke-тесті gateway + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб цей набір справді запускався; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це alias для modern 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` — alias для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Modern/all sweep типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. + - Modern/all sweep за замовчуванням використовують curated high-signal cap; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: profile store і env fallback - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: сховище профілів і резервні значення з env + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відділяє «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» - - Містить малі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + tool-call flows) + - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: відтворення reasoning replay + flow tool-call у OpenAI Responses/Codex Responses) -### Шар 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:*` (перевизначення моделі на кожен запуск) - - Перебрати моделі-з-ключами і перевірити: + - Створити/оновити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) + - Ітерувати за моделями-з-ключами і перевіряти: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (read probe) - - необов’язкові додаткові перевірки інструментів (exec+read probe) - - що шляхи регресій OpenAI (лише виклик інструмента → подальший крок) і далі працюють + - що працює реальний виклик інструмента (перевірка read) + - додаткові необов’язкові перевірки інструментів (перевірка exec+read) + - що шляхи регресій OpenAI (лише tool-call → follow-up) залишаються працездатними - Деталі probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у робочий простір і просить агента `read` його та повернути nonce назад. - - `exec+read` probe: тест просить агента `exec`-ом записати nonce у тимчасовий файл, а потім `read`-ом прочитати його назад. - - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - probe `read`: тест записує nonce-файл у робочу область і просить агента `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 напряму) - Як вибирати моделі: - - Типово: 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` — це alias для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити - - Modern/all gateway sweep типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. -- Як вибирати провайдерів (уникайте «усе з 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` — alias для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Modern/all gateway sweep за замовчуванням використовують curated high-signal cap; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. +- Як вибирати провайдерів (уникнути «все з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки tool + image у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (стрес для інструментів) - - image probe запускається, коли модель заявляє підтримку вхідного `image` - - Потік (на високому рівні): +- Перевірки tool + image у цьому live-тесті завжди увімкнені: + - probe `read` + probe `exec+read` (навантаження на інструменти) + - image probe запускається, коли модель оголошує підтримку вводу зображень + - Flow (високорівнево): - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) + - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent передає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (толерантність OCR: незначні помилки допустимі) -Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke-тест CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke для backend CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + agent з використанням локального CLI backend, не зачіпаючи вашу типову config. -- Типові smoke-параметри, специфічні для backend, знаходяться у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити pipeline Gateway + agent, використовуючи локальний backend CLI, не торкаючись вашого типового config. +- Типові значення smoke для конкретного backend розміщено у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий provider/model: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin CLI backend-власника. -- Перевизначення (необов’язкові): + - Поведінка command/args/image береться з метаданих Plugin відповідного backend CLI. +- Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення 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` щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності тієї самої сесії 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` щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -605,31 +602,31 @@ 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`. -- Він визначає метадані 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-змінних API-ключа Anthropic. Ця lane підписки типово вимикає перевірки Claude MCP/tool та image, тому що Claude зараз маршрутизує використання сторонніх застосунків через тарифікацію extra-usage замість звичайних лімітів плану підписки. -- Live smoke-тест CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через CLI gateway. -- Типовий smoke-тест Claude також патчить сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Він запускає live smoke для CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані CLI smoke з відповідного extension, потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносимий OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, потім виконує два ходи Gateway CLI-backend без збереження змінних середовища Anthropic API key. Цей lane підписки типово вимикає probe Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через додаткове тарифікування usage замість звичайних лімітів плану підписки. +- Live smoke CLI-backend тепер перевіряє той самий наскрізний flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через CLI gateway. +- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: ACP bind smoke (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP з live ACP-агентом: +- Мета: перевірити реальний flow conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову каналу повідомлень на місці - - надіслати звичайне подальше повідомлення в цій самій розмові - - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної сесії ACP + - прив’язати синтетичну conversation message-channel на місці + - надіслати звичайне follow-up у тій самій conversation + - перевірити, що follow-up потрапляє в транскрипт прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP-агенти в Docker: `claude,codex,gemini` - - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Синтетичний channel: контекст розмови у стилі Slack DM - - ACP-бекенд: `acpx` + - ACP agent у Docker: `claude,codex,gemini` + - ACP agent для прямого `pnpm test:live ...`: `claude` + - Синтетичний channel: контекст conversation у стилі Slack DM + - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -638,9 +635,9 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.4` -- Примітки: - - Ця lane використовує поверхню gateway `chat.send` з полями synthetic originating-route лише для адміністраторів, щоб тести могли приєднувати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness-агента. +- Нотатки: + - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли додавати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent Plugin `acpx` для вибраного agent harness ACP. Приклад: @@ -656,7 +653,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Docker-рецепти для окремих агентів: +Рецепти Docker для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -664,39 +661,39 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Примітки щодо Docker: +Нотатки щодо Docker: - Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає ACP bind smoke-тест для всіх підтримуваних live CLI-агентів послідовно: `claude`, `codex`, потім `gemini`. +- За замовчуванням він запускає ACP bind smoke послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, готує відповідний матеріал автентифікації CLI у контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з використаного profile доступними для дочірнього harness CLI. +- Він підвантажує `~/.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 зберігав змінні середовища провайдера з підвантаженого profile доступними для дочірнього CLI harness. -## Live: smoke-тест harness app-server Codex +## Live: smoke harness app-server Codex -- Мета: перевірити plugin-owned harness Codex через звичайний метод gateway +- Мета: перевірити harness Codex, яким володіє plugin, через звичайний метод gateway `agent`: - - завантажити вбудований plugin `codex` + - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `openai/gpt-5.5` з примусовим використанням harness Codex - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік - app-server може відновитися + - надіслати перший хід gateway agent до `openai/gpt-5.4` із примусовим використанням harness Codex + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що + thread app-server може відновитися - виконати `/codex status` і `/codex models` через той самий шлях команди gateway - - необов’язково виконати дві escalated shell probes, переглянуті Guardian: одну нешкідливу - команду, яку слід схвалити, і одне фальшиве вивантаження секрету, яке має бути - відхилене, щоб агент перепитав + - за потреби виконати дві probe escalated shell, перевірені Guardian: одну безпечну + команду, яку слід схвалити, і одне фальшиве завантаження секрету, яке має бути + відхилене, щоб agent перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Типова модель: `openai/gpt-5.5` +- Типова модель: `openai/gpt-5.4` - Необов’язкова image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Необов’язкова Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke-тест установлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти непомітно, тихо переключившись на PI. -- Автентифікація: auth app-server Codex з локального логіну підписки Codex. Docker - smoke-тести також можуть передавати `OPENAI_API_KEY` для probe, не пов’язаних із Codex, коли це доречно, - а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти, тихо переключившись на PI. +- Auth: автентифікація app-server Codex із локального логіну підписки Codex. Docker + smoke також можуть передавати `OPENAI_API_KEY` для probe, не пов’язаних із Codex, коли це доречно, + плюс необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -706,7 +703,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \ - OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.5 \ + OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.4 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` @@ -717,69 +714,69 @@ source ~/.profile pnpm test:docker:live-codex-harness ``` -Примітки щодо Docker: +Нотатки щодо Docker: - Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - auth CLI Codex, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- - префікс, готує вихідне дерево, а потім запускає лише live-тест Codex-harness. -- Docker типово вмикає image-, MCP/tool- і Guardian-probe. Установіть +- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, коли вони присутні, встановлює `@openai/codex` у записуваний змонтований npm + prefix, готує дерево вихідних кодів, а потім запускає лише live-тест Codex-harness. +- Docker типово вмикає image, MCP/tool і Guardian probe. Встановіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли вам потрібен вужчий + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live - config тесту, щоб застарілі alias або fallback на PI не могли приховати - регресію harness Codex. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і config live-тесту, + щоб застарілі alias або fallback на PI не могли приховати регресію + harness Codex. -### Рекомендовані live-рецепти +### Рекомендовані рецепти live -Вузькі, явні allowlist — найшвидші й найменш нестабільні: +Вузькі, явні allowlist — найшвидші й найменш flaky: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, smoke-тест gateway: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів через кількох провайдерів: +- Виклик інструментів для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API-ключ Gemini + Antigravity): - - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" 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` - 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/...` використовує API Gemini (API-ключ). -- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google/...` використовує Gemini API (API key). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). - `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості tooling). -- API Gemini проти CLI Gemini: - - API: OpenClaw викликає розміщений Google API Gemini через HTTP (auth через API-ключ / profile); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний бінарник `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжності версій). +- Gemini API проти Gemini CLI: + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація через API key / profile); саме це більшість користувачів мають на увазі під “Gemini”. + - CLI: OpenClaw виконує shell-виклик локального двійкового файла `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «списку моделей CI» (live є opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. +Немає фіксованого «списку моделей CI» (live — це opt-in), але це **рекомендовані** моделі, які слід регулярно охоплювати на dev-машині з ключами. -### Сучасний набір smoke-тестів (виклик інструментів + image) +### Сучасний набір smoke (виклик інструментів + 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 OAuth: `openai-codex/gpt-5.5` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) +- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск smoke-тесту gateway з інструментами + image: +Запустіть gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть принаймні одну модель для кожного сімейства провайдерів: +Виберіть щонайменше одну модель для кожної родини провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -787,81 +784,81 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (бажано мати): -- xAI: `xai/grok-4` (або найновішу доступну) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- xAI: `xai/grok-4` (або найновіша доступна) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання image (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні gateway +### Aggregator і альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідні кандидати з підтримкою tool+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, яких можна включити до live matrix (якщо у вас є облікові дані/config): +Більше провайдерів, які можна додати до live-матриці (якщо у вас є облікові дані/config): - Вбудовані: `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` (власні endpoint): `minimax` (cloud/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 для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає “profile keys” у live-тестах) +- Профілі auth для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у live-тестах означає «ключі профілів») - Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в підготовлений live home за наявності, але це не основне сховище profile keys) -- Локальні live-запуски типово копіюють активну config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового тестового home; підготовлені live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` і `agentDir` видаляються, щоб probe не працювали у вашому реальному робочому просторі хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілів) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового тестового home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probe не торкалися вашого реального робочого простору хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрипція аудіо) +## Live Deepgram (транскрипція аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live для плану кодування BytePlus - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live для workflow медіа ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Обсяг: - - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` - - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у поданні workflow comfy, polling, завантаженнях або реєстрації plugin +- Scope: + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` + - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin -## Image generation live +## Live для генерації зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` -- Обсяг: - - Перелічує кожен зареєстрований plugin провайдера генерації image - - Завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатного auth/profile/model - - Проганяє стандартні варіанти генерації image через спільну runtime-можливість: +- Scope: + - Перераховує кожен зареєстрований Plugin провайдера генерації зображень + - Перед перевіркою завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API key раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної auth/profile/model + - Запускає стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери в покритті: +- Поточні вбудовані провайдери, що охоплюються: - `fal` - `google` - `minimax` @@ -874,23 +871,23 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env -## Music generation live +## 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` -- Обсяг: +- Scope: - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатного auth/profile/model + - Перед перевіркою завантажує env-змінні провайдера з вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API key раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt + - `generate` із вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної lane: + - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: окремий live-файл Comfy, а не цей спільний sweep @@ -898,51 +895,51 @@ Live-тести знаходять облікові дані так само, я - `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 зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env -## Video generation live +## Live для генерації відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` -- Обсяг: - - Перевіряє спільний шлях вбудованого провайдера генерації video - - Типово використовує безпечний для релізу шлях smoke-тесту: провайдери не-FAL, один запит text-to-video на провайдера, односекундний prompt із лобстером і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) - - Типово пропускає FAL, тому що затримка черги з боку провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно запустити його - - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатного auth/profile/model - - Типово запускає лише `generate` - - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід image на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід video на основі buffer у спільному sweep +- Scope: + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster prompt і обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити + - Перед перевіркою завантажує env-змінні провайдера з вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API key раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної auth/profile/model + - За замовчуванням запускає лише `generate` + - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled`, а вибраний провайдер/модель приймає локальні вхідні дані зображення на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled`, а вибраний провайдер/модель приймає локальні вхідні дані відео на основі buffer у спільному sweep - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: - - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` потребує віддаленого URL image + - `vydra`, бо вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, яка типово використовує фікстуру віддаленого URL image + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує фікстуру віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз потребують віддалених reference URL `http(s)` / MP4 - - `google`, тому що поточна спільна lane Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається у спільному sweep - - `openai`, тому що поточна спільна lane не гарантує доступ до video inpaint/remix, специфічний для org + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені 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_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового sweep, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера під час агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції кожного провайдера для агресивного smoke-запуску - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env -## Media live harness +## Harness для media live - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один природний для репозиторію entrypoint + - Запускає спільні live-набори для зображень, музики й відео через один нативний entrypoint репозиторію - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатний auth - - Повторно використовує `scripts/test-live.mjs`, щоб поведінка Heartbeat і тихого режиму залишалася узгодженою + - За замовчуванням автоматично звужує кожен набір до провайдерів, які зараз мають придатну auth + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet-mode лишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -953,18 +950,18 @@ Live-тести знаходять облікові дані так само, я Ці Docker-ранери поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile keys всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і робочий простір (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери типово використовують менший smoke-cap, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний файл live із ключами профілів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і робочий простір (і підвантажуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менший smoke cap, щоб повний 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-змінні, коли - ви явно хочете більший вичерпний прогін. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker lane live. Він також збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E smoke-ранерів у контейнері, які перевіряють зібраний застосунок. -- Smoke-ранери контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам явно потрібен більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для контейнерних smoke-ранерів E2E, які перевіряють зібраний застосунок. +- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-моделей також bind-mount лише потрібні home-каталоги auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі auth на хості: +Docker-ранери live-моделей також bind-mount лише потрібні home-каталоги auth CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі auth хоста: - Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) @@ -972,142 +969,142 @@ Docker-ранери live-моделей також bind-mount лише потр - Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер онбордингу (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke-тест онбордингу/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і типово Telegram, перевіряє, що ввімкнення plugin встановлює його runtime-залежності на вимогу, запускає doctor і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих провайдерів image, а не зависає. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Docker smoke-тест інсталятора: `bash scripts/test-install-sh-docker.sh` використовує один спільний npm-кеш для своїх контейнерів root, update і direct-npm. Smoke-тест оновлення типово використовує npm `latest` як стабільну baseline перед оновленням до tarball кандидата. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб записи кешу, що належать root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. -- Install Smoke CI пропускає дубльоване пряме глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення provider schema і перевіряє, що сирі деталі з’являються в логах Gateway. -- Міст channel MCP (seeded Gateway + stdio bridge + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP у Pi bundle (реальний stdio MCP server + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke-тест встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke-тест незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke-тест метаданих reload config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності вбудованих Plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker-образ раннера, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожний Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Звужуйте перевірки runtime-залежностей вбудованих Plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke onboarding/channel/agent з npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з посиланням на env і за замовчуванням Telegram, перевіряє, що ввімкнення Plugin встановлює його runtime-залежності за потреби, запускає doctor і виконує один замоканий хід агента OpenAI. Щоб повторно використати попередньо зібраний tarball, використовуйте `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, щоб пропустити перебудову на хості — `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, або щоб переключити channel — `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих провайдерів зображень замість зависання. Щоб повторно використати попередньо зібраний tarball, використовуйте `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, щоб пропустити збірку на хості — `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, або щоб скопіювати `dist/` із зібраного Docker-образу — `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm-кеш між своїми контейнерами root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільну базу перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- CI для Install Smoke пропускає дубльоване пряме глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібно покриття прямого `npm install -g`. +- Networking Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає замоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення схеми провайдера і перевіряє, що сирі деталі з’являються в логах Gateway. +- Міст channel MCP (ініціалізований Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP пакета Pi (реальний stdio MCP server + smoke allow/deny для вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків Cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugin (smoke встановлення + alias `/plugin` + семантика перезапуску пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності вбудованих Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ раннера, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вказуйте на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Під час ітерації звужуйте перевірку runtime-залежностей вбудованих Plugin, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використовувати спільний image built-app: +Щоб вручну попередньо зібрати й повторно використовувати спільний built-app image: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку пакета/встановлення, а не спільний runtime built-app. +Коли встановлено suite-специфічні перевизначення image, наприклад `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, вони все одно мають пріоритет. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Тести Docker для QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. Docker-ранери live-моделей також монтують поточний checkout лише для читання і -підготовлюють його у тимчасовий workdir всередині контейнера. Це зберігає runtime- -image компактним, але все одно дозволяє запускати Vitest проти ваших точних локальних source/config. -Крок підготовки пропускає великі локальні кеші та результати збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні каталоги `.build` застосунків або -вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +переносять його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, водночас запускаючи Vitest точно на ваших локальних source/config. +Крок staging пропускає великі локальні кеші й результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги +`.build` або результати Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали +реальні воркери channel Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття -gateway live із цієї Docker lane. -`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway +live із цього Docker-lane. +`test:docker:openwebui` — це smoke вищого рівня для сумісності: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження -image Open WebUI, а сам Open WebUI може завершувати власне налаштування холодного старту. -Ця lane очікує наявності придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — це основний спосіб надати його в Dockerized-запусках. +реальний chat-запит через proxy `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, бо Docker може знадобитися завантажити +image Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Docker-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway- -контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live events, маршрутизацію outbound send і сповіщення каналу + -дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що -міст реально виводить, а не лише те, що випадково показує конкретний client SDK. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live- -моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -всередині контейнера, матеріалізує цей сервер через runtime вбудованого Pi bundle -MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +реального акаунта Telegram, Discord або iMessage. Він запускає контейнер +ініціалізованого Gateway, запускає другий контейнер, який піднімає `openclaw mcp serve`, потім +перевіряє виявлення маршрутизованих conversation, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення у стилі Claude для channel + +дозволів через реальний stdio MCP bridge. Перевірка сповіщень безпосередньо +аналізує сирі stdio MCP frame, тому smoke перевіряє те, що міст справді +випромінює, а не лише те, що випадково показує конкретний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує +реального ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей server через runtime вбудованого пакета MCP Pi, +виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує -ізольований хід cron і one-shot дочірній хід `/subagents spawn`, а потім перевіряє, +`test:docker:cron-mcp-cleanup` детермінований і не потребує +реального ключа live-моделі. Він запускає ініціалізований Gateway із реальним stdio MCP probe server, +виконує ізольований хід Cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний ACP smoke-тест thread природною мовою (не для CI): +Ручний smoke plain-language 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_PROFILE_ENV_ONLY=1` щоб перевіряти лише env-змінні, використані з `OPENCLAW_PROFILE_FILE`, з тимчасовими каталогами config/workspace і без зовнішніх монтувань auth CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підвантажується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої auth CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker - Зовнішні каталоги/файли auth CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1` щоб повторно використовувати наявний image `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=...` щоб перевизначити закріплений тег image Open WebUI + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний image `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Після змін у документації запускайте перевірки docs: `pnpm check:docs`. Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресії (безпечні для CI) +## Офлайнова регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів 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 (mock OpenAI, реальний loop gateway + agent): `src/gateway/gateway.test.ts` (кейс: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності agent (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: -- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний loop gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні flow майстра, які перевіряють wiring сесій і ефекти config (`src/gateway/gateway.test.ts`). -Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Вибір рішень:** коли Skills перелічено в prompt, чи вибирає agent правильний Skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає agent `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають передусім залишатися детермінованими: +Майбутні eval мають передусім залишатися детермінованими: -- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесій. -- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-evals (opt-in, із gating через env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів і їхнього порядку, читання файлів Skill та wiring сесій. +- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, гейтінг, ін’єкція prompt). +- Необов’язкові live eval (opt-in, керовані env) лише після того, як буде готовий безпечний для CI набір. -## Contract-тести (форма plugin і channel) +## Контрактні тести (форма plugin і channel) -Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітеруються по всіх виявлених plugin і запускають набір -перевірок форми та поведінки. Типова unit lane `pnpm test` навмисно -пропускає ці файли спільних seam і smoke; запускайте contract-команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму інтерфейсному контракту. Вони ітеруються по всіх виявлених plugin і запускають +набір перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, +коли зачіпаєте спільні поверхні channel або провайдерів. ### Команди - Усі контракти: `pnpm test:contracts` - Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` ### Контракти channel @@ -1120,46 +1117,46 @@ Contract-тести перевіряють, що кожен зареєстров - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API каталогу/ростеру -- **group-policy** - Застосування групової політики +- **directory** - API каталогу/складу +- **group-policy** - Дотримання групової політики -### Контракти статусу provider +### Контракти статусу провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel -- **registry** - Форма реєстру Plugin +- **status** - Probe статусу channel +- **registry** - Форма реєстру plugin -### Контракти provider +### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/добір auth +- **auth** - Контракт flow автентифікації +- **auth-choice** - Вибір/selection автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення Plugin -- **loader** - Завантаження Plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс Plugin +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни експортів або subpath у plugin-sdk -- Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації чи виявлення plugin +- Після зміни експортів або subpath plugin-sdk +- Після додавання чи зміни channel або provider plugin +- Після рефакторингу реєстрації або виявлення plugin -Contract-тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API key. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні -- Намагайтеся націлюватися на найменший шар, який виявляє помилку: - - помилка конвертації/повтору запиту provider → тест direct models - - помилка pipeline сесії/історії/інструментів gateway → live smoke-тест gateway або безпечний для CI mock-тест gateway -- Захисний механізм обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або зафіксуйте точне перетворення форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому шару, який виявляє баг: + - баг перетворення/повторення запиту провайдера → direct models test + - баг pipeline сесії/історії/інструментів 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` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих id цілей, щоб нові класи не могли бути тихо пропущені.